Repository navigation
[PR] feat: claude lane mid-session proxy self-heal via MCP watchdog - #1874
Conversation
📦 Built Package ArtifactBranch: Option A — Install this exact build (recommended)npm install -g billion-context@0.0.4456-pr.1874.212f95cThis exact version is immutable and reproducible. The rolling Option B — Download artifact
tar xzf billion-context-pr1874.tgz
npm install -g packageInstall instructions are refreshed on each push. |
…up (zcode parity) Review fix for #1874: the counter was reset BEFORE ensureProxyRunning, so a throwing bring-up cooled it down and cost another full failure cycle (~90 s) before retrying. zcode resets only after a completed bring-up and retries on the very next tick. Move the reset after the log line and pin the semantics with a regression test.
…de-mcp-entry.js (#1821) Review fix for #1874: both CONFIGURATION docs still said every no-plugin-API host installs the MCP bridge at dist/mcp.js; after this PR claude registers dist/claude-mcp-entry.js instead (codex keeps plain dist/mcp.js). The zh line also listed opencode among hosts WITHOUT a plugin API while the en line and the code (opencode-native) say otherwise — aligned to the en wording.
[bot] 🏷 Review 完成:可合并(等 CI 绿 + 你合并)。审查过程与结论如下。 ① 原 issue 方向核对(方向关):#1821 的 triage 判断经我逐条代码核实成立——zcode 已有同款自愈( ② 回归审计(既有行为清点)——diff 触碰路径逐项过:
③ 代码审查:实现是对 zcode 模式的忠实镜像。origin 跟踪优先级正确(settings.json managed block = 运行中 claude 实际拨的地址 > ④ 测试有效性:21 个测试全是真断言——spawn 参数(port 0 vs strict pin、scriptPath basename= ⑤ diff 整洁度:6 文件 +625−10,每行与本 PR 目的相关;README en/zh 同步更新;tsup +1 entry;单一线性提交;无空白噪音。干净。 review 中发现的两个小问题,均已直接修掉并推到 PR 分支(两个独立标注 commit):
结构化七问:
验证状态:typecheck 干净;定向套件(claude-mcp-entry 21 + claude-native + plugin-agent)133 tests / 125 pass / 0 fail / 8 skipped(live-e2e 门控);build 交给 CI(tsup entry 列表 +1,无 import 环)。CI 已在最新 head(41e1461,含我的两个 review commit)上重触发,11 checks queued;PR mergeable=True(无冲突),当前 blocked 仅等 checks。 收工判定:review 通过,两个小问题已直接修复推上分支(分支现共 3 个提交);CI 全绿后即可由你合并——按规范合并按钮在你手里。 |
…s CI red) CI review of #1874: both windows-latest jobs failed in the 4 installer-matrix tests. On Windows runClaudeCli routes .cmd shims through the shell with per-token quoting (src/plugin-install.ts), so the fake claude's %* log lines come back as '"mcp" "add" ...' with CRLF endings instead of plain LF tokens. cliLog() asserted the Linux shape verbatim. Normalize quotes + line endings before asserting; production invocation is untouched (the real claude CLI gets identical argv after CommandLineToArgvW unquoting).
[bot] 🏷 CI 结果跟进 + 又直接修了一处(分支现共 4 个提交,最新 c4039d6)。 我前两个 commit 后 CI 跑完:10/12 绿(ubuntu 22+24、全部 lane e2e(codex/pi/dsh/opencode)、hermetic registry e2e、build、version-guard、codex overlay),两个 windows job 红。逐项查了日志: ① win22 红 = 本 PR 引入的测试可移植性缺陷(已直接修掉)——4 个失败全在新测试的 installer-matrix 里。根因: ② win24 红 = 同样这 4 个 + 一个 pre-existing 失败:master(95a30be)自己的 win24 也是红的—— 修复后预期:两个 windows job 各自只剩已修的 4 个用例 → 应全绿。已推送到分支,CI 自动重跑中,我继续盯,再有异常立即报。 |
[bot] 🏷 CI 全绿,review 收工。 最新 head c4039d6:12/12 checks success(ubuntu 22+24、windows 22+24、codex/pi/dsh/opencode 四个 lane e2e、hermetic registry e2e、build-artifact、version-guard、codex overlay)。之前 win24 的 pre-existing esbuild 瞬态崩溃这次也未复现。 分支最终状态(4 个提交):
合并判定:可合并,mergeable=True 无冲突,checks 全绿——按规范合并按钮在你手里:#1874 |
…up (zcode parity) Review fix for #1874: the counter was reset BEFORE ensureProxyRunning, so a throwing bring-up cooled it down and cost another full failure cycle (~90 s) before retrying. zcode resets only after a completed bring-up and retries on the very next tick. Move the reset after the log line and pin the semantics with a regression test.
c4039d6 to
03dda82
Compare
…de-mcp-entry.js (#1821) Review fix for #1874: both CONFIGURATION docs still said every no-plugin-API host installs the MCP bridge at dist/mcp.js; after this PR claude registers dist/claude-mcp-entry.js instead (codex keeps plain dist/mcp.js). The zh line also listed opencode among hosts WITHOUT a plugin API while the en line and the code (opencode-native) say otherwise — aligned to the en wording.
…s CI red) CI review of #1874: both windows-latest jobs failed in the 4 installer-matrix tests. On Windows runClaudeCli routes .cmd shims through the shell with per-token quoting (src/plugin-install.ts), so the fake claude's %* log lines come back as '"mcp" "add" ...' with CRLF endings instead of plain LF tokens. cliLog() asserted the Linux shape verbatim. Normalize quotes + line endings before asserting; production invocation is untouched (the real claude CLI gets identical argv after CommandLineToArgvW unquoting).
|
ci失败 |
[bot] 🏷 CI 失败已定位并修好(分支现最新 4e623aa)。 先交代背景:我上轮 review(10-01,当时 CI 12/12 绿)之后,分支又追加了两个提交(10-13:把 watchdog 机制扩展到 zcode lane + 一个 typecheck 修复),rebase 到新 master 后 CI 重跑。这次红的是 根因是清单漂移,不是死代码: 修法:在门禁的 |
…up (zcode parity) Review fix for #1874: the counter was reset BEFORE ensureProxyRunning, so a throwing bring-up cooled it down and cost another full failure cycle (~90 s) before retrying. zcode resets only after a completed bring-up and retries on the very next tick. Move the reset after the log line and pin the semantics with a regression test.
…de-mcp-entry.js (#1821) Review fix for #1874: both CONFIGURATION docs still said every no-plugin-API host installs the MCP bridge at dist/mcp.js; after this PR claude registers dist/claude-mcp-entry.js instead (codex keeps plain dist/mcp.js). The zh line also listed opencode among hosts WITHOUT a plugin API while the en line and the code (opencode-native) say otherwise — aligned to the en wording.
4e623aa to
ca4ca20
Compare
…s CI red) CI review of #1874: both windows-latest jobs failed in the 4 installer-matrix tests. On Windows runClaudeCli routes .cmd shims through the shell with per-token quoting (src/plugin-install.ts), so the fake claude's %* log lines come back as '"mcp" "add" ...' with CRLF endings instead of plain LF tokens. cliLog() asserted the Linux shape verbatim. Normalize quotes + line endings before asserting; production invocation is untouched (the real claude CLI gets identical argv after CommandLineToArgvW unquoting).
[bot] 🏷 第二个 CI 红也修了,顺带把分支 rebase 到了最新 master(最新 head ca4ca20)。 上一笔修复(unused-exports)推上去后重跑:unused-exports 转绿,但冒出一个新的失败 根因和上一个完全同型:这个门禁(scripts/check-test-import-graph.mjs)同样维护一份硬编码的 entry 清单(注释原话 "Same list as scripts/check-unused-exports.mjs"),同样漏了本 PR 新增的 tsup entry 另外发现分支基线已经落后 master 5 天(两个新门禁都是这期间落地的),按 §7.2 纪律rebase 到了当前 master(ce4d60b,干净无冲突,8 个提交全部重放成功)。本地验证:两个 import 门禁 clean、typecheck clean、claude/zcode watchdog + claude-native + plugin-agent 五个套件 191 tests / 0 fail / 8 skipped(live-e2e 门控)。已 force-push(PR 分支更新基线的标准操作,master 未动)。这轮 CI 会把之前被 skip 的全量 test + e2e 真正跑一遍,结果出来我再报。 |
The zcode lane already respawns a dead proxy from its session-lived MCP child (30s tick x 3 failures); the claude lane's MCP shell had no watchdog, so a proxy death left every model request ECONNREFUSED until the next session's SessionStart hook re-ran. - new src/claude-mcp-entry.ts: mirrors zcode/mcp-entry.ts — session-lived stdio entry that probes healthUrl every 30s and, after 3 consecutive failures, re-runs ensureProxyRunning(lane:"claude") with zone port semantics and chooseWatchdogParentPid() so the respawned proxy still watches the claude host pid; on origin drift it repins the managed settings base URL (next session heals) and follows BILI_MCP_PROXY for its own tool calls. Attach posture (BILLION_CONTEXT_PROXY) and passthrough (BILI_NATIVE_CLAUDE=0) never respawn — user-owned proxies stay user-owned. No exit handoff needed: the proxy watches the host pid and the next hook drops dead pins. - plugin-install.ts: claudeInstall now registers dist/claude-mcp-entry.js instead of dist/mcp.js and migrates an existing legacy registration in place (remove+add); fresh/current/foreign registrations handled without clobbering. - tsup.config.ts: build the new entry. - tests: 20 new tests (watchdog semantics, posture gates, installer migration matrix). - docs: README en/zh note the mid-session self-heal.
…up (zcode parity) Review fix for #1874: the counter was reset BEFORE ensureProxyRunning, so a throwing bring-up cooled it down and cost another full failure cycle (~90 s) before retrying. zcode resets only after a completed bring-up and retries on the very next tick. Move the reset after the log line and pin the semantics with a regression test.
…de-mcp-entry.js (#1821) Review fix for #1874: both CONFIGURATION docs still said every no-plugin-API host installs the MCP bridge at dist/mcp.js; after this PR claude registers dist/claude-mcp-entry.js instead (codex keeps plain dist/mcp.js). The zh line also listed opencode among hosts WITHOUT a plugin API while the en line and the code (opencode-native) say otherwise — aligned to the en wording.
…s CI red) CI review of #1874: both windows-latest jobs failed in the 4 installer-matrix tests. On Windows runClaudeCli routes .cmd shims through the shell with per-token quoting (src/plugin-install.ts), so the fake claude's %* log lines come back as '"mcp" "add" ...' with CRLF endings instead of plain LF tokens. cliLog() asserted the Linux shape verbatim. Normalize quotes + line endings before asserting; production invocation is untouched (the real claude CLI gets identical argv after CommandLineToArgvW unquoting).
master history rewrite landed a launcher API drift: ProxyHandle/LaunchOptions are no longer exported and LaunchOptions.parentPid is optional. The test now derives its types from ensureProxyRunning (Parameters/Awaited) and builds explicit handle literals.
… on user pins (#1821) The zcode watchdog treated every 'attached at bootstrap' proxy as externally owned and only logged 'waiting for it to recover' — but attached=true also fires when ensureProxyRunning finds a LANE-owned instance alive at bootstrap time, including one spawned by a concurrent session. A death of that proxy then stranded the session until the next SessionStart boot (external repro on v0.1.184/Windows). - native.ts: BootstrapMode gains externallyOwned — true ONLY for an explicit user pin (plan.mode === attach); exported ZcodeRouteApplied. - mcp-entry.ts: watchdog tick now recovers (ensureProxyRunning + re-route on origin drift) for lane-owned proxies and keeps the wait-only behavior for user pins; same-origin recovery logs 'recovered without a re-route'. Exported zcodeWatchdogTick/ZcodeWatchdogDeps/state types for tests. - Behavior change (old→new): zcode lane, proxy found alive at session start then dies mid-session: stranded until next session → auto-recovery within ~90s (30s x 3 failures), same semantics as the spawn case and as the claude lane in this PR. User-pin attach posture is unchanged. - Tests: new tests/zcode-mcp-entry.test.ts (8) + bootstrap externallyOwned assertions in tests/zcode-native.test.ts.
CI on the rebased head failed in unused-exports (gate #1440 P6, landed on master after this PR was written): 'INTERNAL_ONLY src/claude-mcp-entry.ts: WatchdogState'. Root cause is drift, not a dead symbol — this PR added src/claude-mcp-entry.ts as a tsup entry, and the gate's ENTRY_FILES list is contractually kept in sync with tsup.config.ts entry ('a missing entry here gets over-gated'); its zcode twin src/zcode/mcp-entry.ts is already listed. Add the missing entry; WatchdogState/MutableWatchdogState stay exported so the test import of MutableWatchdogSource keeps working.
) Second instance of the same drift: scripts/check-test-import-graph.mjs (#2989, landed on master after this PR's new tsup entry) keeps its own ENTRY_FILES list ('same list as scripts/check-unused-exports.mjs') that was missing src/claude-mcp-entry.ts, so the gate saw the module as unreachable from production and flagged tests/claude-mcp-entry.test.ts's import as an unlabeled retired-module pin. It is a live production entry (tsup.config.ts), not retired code — add it to the list. Branch also rebased onto current master (was based on Oct-11 master; two new CI gates landed since).
ca4ca20 to
17fad2e
Compare
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) 「ci失败」已定位并处理完。这次的红全部与 PR 代码无关,是两个独立原因,都已消除或归类: 失败面(上一轮 head
|
| 分片 | 失败 | 定性 |
|---|---|---|
| ubuntu 22-3 / ubuntu 24-1 / windows 22-2 | storage-render golden ×4(chat/anthropic/responses/google) |
本分支 base 过期,继承 master 当时的已知红 |
| windows 22-1 | AC12: a multi-hop grandchild stays eligible… |
既有 flake,master 自己也在挂 |
原因 1:golden 漂移 = base 太旧(已修)
- 本分支此前 rebase 到的 base
ce4d60b60早于 master 上 test: rebaseline storage-render goldens after #3295 dropped dead image-stats fields from state.stats #3314/修 CI 无故变红:#1086 T5 用例的 'x'×360 填充触发 #3289 输出护栏,含 #3289 的每棵树必挂 #3317 的金标重生成与 PTC模式下 模型直接调用了 compress工具, 没有走run_code, 这块能不能在 billion-context 的几个工具中明确一下PTC要走run_code调用? #3252 fold-seam 修复(dc47d2af9/4bf28c5e6「regen storage-render goldens on the merged tree」)。base 树里金标与渲染代码失同步 ⇒ 凡跑到该文件的分片必挂——这正是 CI 测试 lane 出现与代码改动无关的失败:存储渲染快照漂移 + 两个偶发用例 #3315 子缺陷 1 的同一机制,只是 master 已修、本分支还没吃到修复。 - 证据链:①在 base
ce4d60b60上本地单跑tests/golden-storage-render.test.ts→ 4/5 失败(与 CI 签名逐字一致);②rebase 到当前 master 后同命令 → 5/5 通过;③本 PR 9 个提交对 golden/render/storage 路径零 diff(git diff --name-only核实)。 - 处置:rebase 到当前 master(干净,9 个提交零冲突),force-push
ca4ca20c0 → 17fad2ed9。PR 内容零变化,纯换 base。
原因 2:AC12 = 既有 Windows flake(不归本 PR)
- 断言
derivedBlocksAdopted !== true(adoption gate 时序敏感,tests/lineage-reconcile-boot.test.ts:468)。 - 证据:同签名在 master 自己的 run(
a046d4ecd7,今天 01:48)windows 22-1 也挂;ubuntu 全绿、本机 Linux 单跑 4/4 通过。本 PR 对 lineage/adoption 代码零 diff。 - 这正是已关闭的 CI 测试 lane 出现与代码改动无关的失败:存储渲染快照漂移 + 两个偶发用例 #3315 子缺陷 3(当时结论:跨平台偶发、时序竞态,先攒样本再定修法)。我已在 CI 测试 lane 出现与代码改动无关的失败:存储渲染快照漂移 + 两个偶发用例 #3315 补了一条复发证据(master run + 本 PR run 各一次,均 windows 22-1),建议 reopen 继续跟踪;是否按真回归 bisect 由你定。
新 head 17fad2ed9 验证状态
- 本地(rebased 树):golden-storage-render 5/5;unused-exports / test-import-graph 两门禁 exit 0;typecheck 干净;定向套件(claude-mcp-entry + zcode-mcp-entry + zcode-native + claude-native + plugin-agent)183 pass / 0 fail / 8 skipped(live-e2e 门控)。
- CI:全部 gate 已绿(unused-exports、test-import-graph、kernel-guard、version-guard…),test 分片运行中。全量结果出来我再报一次;若只剩 AC12 偶发,属 CI 测试 lane 出现与代码改动无关的失败:存储渲染快照漂移 + 两个偶发用例 #3315 观察项,不阻塞本 PR。
合并判定不变:可合并,等这轮 test lane 全绿后你点合并即可(Agent 无合并权限)。
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) CI 全量结果出来了(head 结果:38/40 绿,剩余 2 红全是已知 AC12 flake
处置已对 run 38839924684 发起 rerun-failed-jobs(HTTP 201,沿用 #3237 的降噪先例)。结果出来我再报最终状态;若这 2 个 job 重跑转绿,本 PR CI 即全绿可合并。 另注:触发后 master 又合入一个与本 PR 文件零交集的 PR(#3318 opencode-native 超窗拒发),不影响本轮结论;合并前 GitHub 会提示是否需要 base 同步,到时你点一下即可。 |
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b) CI 全绿了:rerun 的两个 AC12 job(ubuntu 22-2 / windows 22-1)都转绿,head 合并判定可合并,等你的手。分支最终 9 个 commit:原 feat(claude MCP watchdog)+ zcode 同机制修复 + 我的三个 review 修复(watchdog 计数器热态、CONFIGURATION 文档、Windows CLI 日志归一化)+ 两个门禁清单同步(unused-exports / test-import-graph,各一行)。 两个小提醒:
|
📦 Merged Build PublishedThis merge to master was published as npm install -g billion-context@0.0.592-master.9631d63 # this exact build
npm install -g billion-context@master # always the newest merged build
|
Fixes #1821
Scope correction from triage (updated after an external repro in the thread)
The issue title says "hook-model clients (claude/zcode)". Initial triage found zcode already self-heals mid-session: its session-lived MCP child (
src/zcode/mcp-entry.ts) runs a watchdog — 30 s health tick × 3 consecutive failures →ensureProxyRunning(lane:"zcode")respawn + re-route (#1660/#1623). A fresh external repro in this thread (zcode lane, v0.1.184, Windows 11) then exposed that coverage was incomplete: the watchdog treated any proxy that was alive at bootstrap as externally owned and only loggedwaiting for it to recover— including a LANE-owned instance spawned by a concurrent session. So the real gap was two facets: claude (no watchdog at all) + zcode attached-to-a-lane-instance (wait-only). Both are fixed here.Root cause
Claude Code has no in-process extension point: the SessionStart hook and the MCP shell are both out-of-process children, and neither watches the proxy. The hook only re-runs at session start (which is why recovery currently works at session granularity); the MCP shell resolves its proxy origin at call time but has no respawn logic. So a dead proxy =
ECONNREFUSEDon every model request until a new session. The zcode facet had the same root cause one layer down:attached(a live instance existed at bootstrap) conflated user-pinned proxies with lane-owned ones.What this PR does
New
src/claude-mcp-entry.ts— the claude lane's dedicated stdio entry, mirroring zcode's proven design:dist/claude-mcp-entry.jsas thebiliMCP server instead ofdist/mcp.js.runMcpStdio) plus a watchdog: probehealthUrlevery 30 s; after 3 consecutive failures, runensureProxyRunning({lane:"claude", port:resolveClaudeNativePort()??0, strictPort:<explicit pin>, parentPid:chooseWatchdogParentPid()})with zone port semantics — the same ensure path the SessionStart hook uses, so sticky-pin drop / instance-file / EADDRINUSE-ladder behavior is identical.parentPidcomes from the same host-pid walk the hook uses, so the respawned proxy still exits when the claude session dies (no orphans).BILI_MCP_PROXYfor the shell's own tool calls (immediate).BILLION_CONTEXT_PROXYset (attach posture) orBILI_NATIVE_CLAUDE=0(passthrough) → no watchdog; user-owned proxies stay user-owned. No exit handoff needed for claude (the proxy watches the host pid; the next hook drops dead pins).src/plugin-install.ts: an existing legacydist/mcp.jsregistration is swapped in place (remove + add) on reinstall/update; fresh installs register the new entry; a foreign (non-bili)biliserver is left untouched; a matching current registration is left alone (idempotent, zero CLI calls).And the zcode facet (triggered by the external repro):
src/zcode/native.ts:BootstrapModegainsexternallyOwned— true ONLY for an explicit user pin (plan.mode === "attach");attachedalone may mean "a lane-owned instance was alive at bootstrap".ZcodeRouteAppliedexported.src/zcode/mcp-entry.ts: the watchdog tick now recovers lane-owned proxies through the same ensure + re-route path (re-route on origin drift, env follow, state update); user-pin attach posture keeps the wait-only behavior; same-origin recovery logsrecovered without a re-route.zcodeWatchdogTick/ deps / state types exported for tests. No kill semantics anywhere — ensure probes first, drops dead pins, then spawns, so cross-session recovery is safe and concurrent double-recovery converges via the bug: cross-process startup-window race — two concurrent launches each spawn a proxy (double writers over one sessions dir) #707 marker.Rejected alternatives (from the issue thread discussion): extra event hooks (per-call node startup tax on every prompt/tool call + race window), a separate supervisor process (duplicates the resident child, adds orphan scenarios), docs-only (concedes an avoidable failure).
Related but orthogonal: a spawn-side mechanism uncovered while analyzing the external repro (Windows same-port double-bind via default SO_REUSEADDR semantics + residual spawn fall-throughs + last-writer pointer divergence) is tracked separately in #2941 — merging this PR does not fix that root cause.
Behavior changes (old → new)
ECONNREFUSEDuntil next sessionBILLION_CONTEXT_PROXY)waiting for it to recoverforever)recovered without a re-routewhen it lands back on the same originbili startmanual daemon killeddist/mcp.jsdist/claude-mcp-entry.js(auto-migrated remove+add)No new config fields / env vars / CLI flags. Detection latency ~90 s worst case (same cadence as before for zcode's self-spawned case).
Verification
npm run typecheckclean;npm run buildOK (dist/claude-mcp-entry.jsbuilt, acp-kernel inlined as usual).tests/claude-mcp-entry.test.ts(20 tests): watchdog semantics (zone vs strict-pin spawn args, drift repin + env follow, attached no-op, refusedWatcher [bug] claude native proxy outlives all sessions despite README lifecycle contract — watcher-based shutdown did not fire #1322 warning, non-fatal repin), posture gates,readClaudeManagedBaseUrl, installer migration matrix (fresh / legacy-swap / current-idempotent / stale-repin / foreign-untouched / malformed-json-fallback).tests/zcode-mcp-entry.test.ts(8 tests): healthy-reset, below-limit no-op, third-failure respawn args, strict pin, drift re-route + env follow, failed-rewrite throw, externally-owned never-respawns across two full cycles, NODE_TEST_CONTEXT short-circuit; plusexternallyOwnedassertions intests/zcode-native.test.ts(user pin = true, lane-owned-alive-at-bootstrap = false).claude-mcp-entry+claude-native+plugin-agent→ 124 pass / 0 fail / 8 skipped (live-e2e gated);zcode-mcp-entry+zcode-native→ 43 pass / 0 fail.proxy respawned at http://127.0.0.1:<port>andtools/listserves 5 tools through the respawned proxy. Lifecycle verified both ways: proxy survives MCP-child crash (watch target = session root, not the child) and exits when the session root dies (parent-gone).src/server.ts,src/loop/**, adapters, persist) untouched — CI e2e path unaffected.