From 4ea8612fde770f416ad66d6fc4ddd408c574b941 Mon Sep 17 00:00:00 2001 From: Number531 <120485065+Number531@users.noreply.github.com> Date: Fri, 24 Apr 2026 19:13:28 -0400 Subject: [PATCH] docs(changelog): document 0.2.119 staging rollback + root cause MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v6.3.0 bump merged cleanly to main (PR #79 + #80) but the subsequent staging deploy failed on first query() invocation with: Claude Code native binary not found at /app/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl/claude Root cause is an SDK runtime-lookup bug (upstream anthropics/claude-agent-sdk-typescript#296, filed independently by another user 2026-04-24): the SDK tries the -musl variant path first and fails to fall through to glibc when musl isn't installed. Our node:22-slim base correctly installs only the glibc variant via npm's libc filter, so the musl path is absent. Staging MIG rolled back to previous instance template (0.2.97 image); code remains at 0.2.119 on main pending the Dockerfile symlink fix (tracked at Legal-API #81, targeted for v6.3.1). This CHANGELOG update adds a prominent callout at the top of the v6.3.0 entry documenting deployment status, what the pre-merge probe missed, and the fix path. Future SDK bumps should include a container-level smoke test before production — static package inspection alone was insufficient. No code changes. Docs-only. Co-Authored-By: Claude Opus 4.7 (1M context) --- super-legal-mcp-refactored/CHANGELOG.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/super-legal-mcp-refactored/CHANGELOG.md b/super-legal-mcp-refactored/CHANGELOG.md index a9ffd03f4..8e11788b7 100644 --- a/super-legal-mcp-refactored/CHANGELOG.md +++ b/super-legal-mcp-refactored/CHANGELOG.md @@ -6,7 +6,13 @@ All notable changes to the Super Legal MCP Server are documented in this file. ### Upgraded — `@anthropic-ai/claude-agent-sdk` 0.2.97 → 0.2.119 -Absorbs 22 point releases covering security, correctness, and observability improvements. Probe (2026-04-24) confirmed the new per-platform native binary packaging (0.2.113+) is safe with our existing `npm ci --omit=dev --ignore-scripts --legacy-peer-deps` Dockerfile command — no build changes required. +> **⚠️ Deployment status (2026-04-24 post-merge):** Code at 0.2.119 merged to `main` (PR [#79](https://github.com/Number531/Legal-API/pull/79) + doc consistency follow-up [#80](https://github.com/Number531/Legal-API/pull/80)). Staging deploy via `/deploy` **failed on first `query()` invocation** with `Claude Code native binary not found at .../claude-agent-sdk-linux-x64-musl/claude`. Root cause is an SDK runtime-lookup bug that tries the musl binary path first and fails to fall through to the glibc path when musl isn't installed — which it correctly isn't on our `node:22-slim` (Debian glibc) base. **Rolled back the staging GCE MIG to the previous instance template (0.2.97 image) — health green.** Code remains at 0.2.119 on `main` pending the Dockerfile symlink fix. Tracking: [Legal-API #81](https://github.com/Number531/Legal-API/issues/81) (internal), [anthropics/claude-agent-sdk-typescript#296](https://github.com/anthropics/claude-agent-sdk-typescript/issues/296) (upstream). +> +> **What the pre-merge probe missed.** Static analysis on 2026-04-24 correctly verified (1) platform-package tarball structure (binary pre-chmodded 0755), (2) zero postinstall scripts — `--ignore-scripts` is not blocking anything, (3) npm's `libc` filter installs the glibc variant only. What it did not verify was the SDK's runtime lookup order inside a spawned container, which probes the musl path regardless of what's actually installed. Lesson for future SDK bumps: add a minimal container-level smoke test (`docker run node -e 'import(...).then(s => s.startup())'`) to the pre-merge checklist. The static/package-level analysis was correct but insufficient on its own. +> +> **Fix path.** Preferred: 5-line Dockerfile symlink addition after `npm ci` that points `claude-agent-sdk-linux-x64-musl/claude` at the glibc binary's real path. The binary is a native glibc ELF — correct for our OS; the `-musl` suffix in the lookup path is just a naming key the SDK's buggy resolution expects. Alternative: explicit `pathToClaudeCodeExecutable` option at each `agentQuery()` call site (Anthropic's own workaround pattern, per [claude-code-action#1235](https://github.com/anthropics/claude-code-action/pull/1235)) — cleaner architecturally, wider code footprint. A follow-up PR (targeted for v6.3.1) will land the symlink fix. + +Absorbs 22 point releases covering security, correctness, and observability improvements. Probe (2026-04-24) confirmed the new per-platform native binary packaging (0.2.113+) is safe at the **package-install** layer with our existing `npm ci --omit=dev --ignore-scripts --legacy-peer-deps` Dockerfile command — no npm-level changes required. Runtime-level SDK lookup bug requires the Dockerfile symlink workaround noted above to make the deployed container functional. **Key changes captured by the bump:**