Skip to content

[PR] Stop pinning the claude MCP face to a stale lane port (#5128) - #5129

Open
ranxianglei wants to merge 9 commits into
masterfrom
2026-10-29_claude-mcp-face-pin-drift
Open

ranxianglei wants to merge 9 commits into
masterfrom
2026-10-29_claude-mcp-face-pin-drift

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #5128

What & why

bili plugin install claude baked BILI_MCP_PROXY=<base port> into the registered MCP server. When the claude lane proxy drifts +1 on a port collision (#1660), the SessionStart hook repins ANTHROPIC_BASE_URL to the live origin but the MCP entry kept the stale pin; resolveProxyOrigin() honours the env pin before live discovery, so ACP tools/list failed with -32003 while model traffic kept compressing through the repinned URL. Same class as #926 (fixed for opencode in #936), still present in the claude installer.

The mismatch is one layer deeper than the symptom: the mid-session watchdog probes the managed block's live origin (correct), but the stdio tool calls resolve through the env pin (stale) — so the watchdog sees a healthy proxy while every tool call dials a dead port.

Changes

  • claudeInstall() — no origin pin by default; a pin lands only when BILI_MCP_PROXY is set explicitly at install time (user intent). Mirrors fix(plugin): stop freezing a stale MCP origin into opencode installs (Fixes #926) #936.
  • claudeMcpFaceAction() — a no-pin entry is now the canonical current form; a stale baked pin is healed away on reinstall (mcp remove + mcp add without the pin). A matching explicit pin stays current.
  • claude-mcp-entry.js main() — new pure resolveClaudeMcpOrigin(managed, env): managed-block last-repinned URL > explicit pin > live discovery. When the repin won, it bridges that origin into BILI_MCP_PROXY so stdio tool calls dial the same live proxy the watchdog probes. Old installs self-heal without a reinstall or waiting out the ~90 s watchdog window.

Behavior change (flagged)

  • Old: bili plugin install claude always wrote mcpServers.bili.env.BILI_MCP_PROXY = http://127.0.0.1:<install-time base port>.
  • New: it writes NO pin unless BILI_MCP_PROXY is exported during the install; reinstalling over a legacy pinned entry removes the pin.
  • Why: the pinned value was wrong every time the lane drifted ([Design] 定死端口 lane(claude 48787 / zcode 48789)端口被占时的 0 配置解法 #1660) — exactly the reporter's repro. The entry now resolves the live lane proxy per session, matching what model traffic already dials.

Tests

Targeted suites green locally (full-suite verdict is remote CI):

  • tests/claude-mcp-entry.test.ts: 23/23 — fresh install bakes no pin, no-pin entry stays current, stale pin healed, explicit-env pin honored (positive+negative gate), resolveClaudeMcpOrigin precedence (managed beats stale pin — the exact repro), foreign/unreadable paths.
  • tests/claude-native.test.ts: installer round-trip unaffected (65 tests, live-E2E ones skip by default).

npm run typecheck clean (exit 0).

Related: #1660 (port drift), #926/#936 (opencode twin), #5001 (MCP shim cold proxy, different symptom).

The claude installer baked BILI_MCP_PROXY=<base port> into the registered MCP
server. When the claude lane proxy drifts +1 on a port collision (#1660), the
SessionStart hook repins ANTHROPIC_BASE_URL to the live origin but the MCP
entry kept the stale pin; resolveProxyOrigin() honours the env pin before live
discovery, so ACP tools/list failed (-32003) while model traffic kept
compressing through the repinned URL. Same class as #926 (fixed for opencode in
#936), still present in the claude installer.

- claudeInstall(): no origin pin by default; a pin lands only when BILI_MCP_PROXY
  is set explicitly at install time (user intent).
- claudeMcpFaceAction(): a no-pin entry is now the canonical/current form; a
  stale baked pin is healed away on reinstall (remove + add without the pin).
- claude-mcp-entry.js main(): resolveClaudeMcpOrigin() prefers the managed
  block's last-repinned URL over a stale baked pin and bridges it into
  BILI_MCP_PROXY so stdio tool calls dial the same live origin as the watchdog —
  old installs self-heal without a reinstall.
@ranxianglei ranxianglei changed the title Stop pinning the claude MCP face to a stale lane port (#5128) [PR] Stop pinning the claude MCP face to a stale lane port (#5128) Oct 29, 2026
@github-actions

github-actions Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-29_claude-mcp-face-pin-drift (ce3426a)

Latest build — install this exact version

npm install -g billion-context@0.0.7392-pr.5129.db150c9

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
ce3426a billion-context@0.0.7392-pr.5129.db150c9 build
60b8266 billion-context@0.0.7287-pr.5129.b16e368 build
5077739 billion-context@0.0.7264-pr.5129.c2e2c22 build
4c63364 billion-context@0.0.7012-pr.5129.039343e build
2b1bb24 billion-context@0.0.6761-pr.5129.904441c build
b6484be billion-context@0.0.6757-pr.5129.13bd2f1 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr5129.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重:不重复。与 #926/#936(opencode 的 MCP origin 冻结)同族——都是「安装时烘焙的 origin 在 lane 漂移后变死端口」这一机制,但客户端不同(本 PR 是 claude 安装器 bili plugin install claude),而 #936 只改了 opencode、没碰 claude。属同一问题在 claude 车道的独立修复面,不是重复劳动。

审核方式:带 ework-agent-pr 标记的 [PR]——按「已完成的活」对待,不重做;拉分支核代码 + 查 CI + 给结构化结论。GitHub PR = #5129(head b6484be7,base master,open)。

结构化八问:

  1. 是什么问题:bili plugin install claude 把 BILI_MCP_PROXY=<安装时基础端口> 焊死进注册的 MCP server。claude lane 撞端口漂移 +1([Design] 定死端口 lane(claude 48787 / zcode 48789)端口被占时的 0 配置解法 #1660)后,SessionStart hook 把模型通道的 ANTHROPIC_BASE_URL 重钉到活 origin,但 MCP 条目里那个旧 pin 还在;而 resolveProxyOrigin()(src/mcp.ts:66)读 env pin 在读活实例登记之前——于是 ACP tools/list 拨死端口报 -32003,模型流量却照常走重钉后的 URL 压缩。看门狗探的是活 origin(健康),stdio 工具调用拨的却是旧 pin(死)——两层不同源,所以「看门狗看着好好的、每个工具调用却全挂」。

  2. 什么原因导致的:根因在生产者——安装器烘焙了一个会过期的值(env pin),且 entry 启动时从不把「本会话实际骑的活 origin」reconcile 进 BILI_MCP_PROXY;resolveProxyOrigin() 的 env-priority 让过期 pin 短路了活发现。修法是去掉默认烘焙 + 启动时对齐活 origin,不是症状层打补丁。

  3. 影响范围与严重程度:仅 claude 原生姿势(bili plugin install claude)且发生端口漂移的场景。程度:该场景下 ACP 工具面整体不可用(tools/list -32003),但模型压缩仍工作——「特定条件下核心能力局部失灵」,有绕行(重装 / 先起 bili),非全局崩溃。新装(不再烘焙 pin)从此不受此窗口影响。

  4. 怎么修复的(策略层,三处协同):①claudeInstall() 默认不写 origin pin,只有安装时显式 export BILI_MCP_PROXY 才落 pin(用户意图);②claudeMcpFaceAction() 把「无 pin」定为规范形态,重装时把遗留旧 pin 治愈掉(remove+add 不带 pin),匹配的显式 pin 保持 current;③claude-mcp-entry.js main() 新增纯函数 resolveClaudeMcpOrigin(managed, env):managed 块最后重钉的 URL > 显式 pin > 活发现,并在 managed 胜出时把它桥接进 BILI_MCP_PROXY,让 stdio 工具调用拨到和看门狗同一个活 origin——老装无需重装、无需等 ~90s 看门狗窗口即自愈。

  5. 是否有回归问题:审过的既有行为逐项——(a) 行为变更已在 PR 明确披露(旧=恒烘焙基础端口 → 新=默认不烘焙、显式 env 仍 honor),方向正确;(b) 删掉的 nativePort/stableOrigin 局部量无残留引用,resolveClaudeNativePort/lanePreferredPort 两个 import 仍在 plugin-install.ts:530 别处使用,不会 unused-import;(c) claudeMcpFaceAction 是模块私有、唯一调用点(plugin-install.ts:912)已在 diff 内同步改签名;(d) 桥接只在 plan.action==="start" 早退之后执行,attach/passthrough 用户不受影响,且不触碰模型通道(模型读 settings.json 的 ANTHROPIC_BASE_URL,不读 BILI_MCP_PROXY),env 变更仅限该会话 stdio 子进程,无跨进程/跨会话泄漏;(e) 没有其它测试硬断言旧的恒烘焙行为——tests/claude-native.test.ts:871 断言的是 ANTHROPIC_BASE_URL(managed 块)而非 MCP pin,tests/plugin-agent.test.ts:2195 断言的是「managed 块先写、MCP exec 失败」的错误契约(diff 未触碰);opencode 侧 pin 断言属另一代码路径(fix(plugin): stop freezing a stale MCP origin into opencode installs (Fixes #926) #936)。(f) 文档面核对:没有任何 .md 声称 claude MCP face「钉在稳定端口」,无文档失步。高危模式逐项:无语义漂移、无 fail-fast 变吞错、无阈值/时序/输出格式变化。未发现回归。

  6. 是否破坏缓存:不涉及。改的是安装器写什么 env + entry 启动解析顺序,不碰前缀缓存/摘要/ref/账本。

  7. 是否改了设计方向:不涉及架构转向。是沿用 fix(plugin): stop freezing a stale MCP origin into opencode installs (Fixes #926) #936 在 opencode 已确立的「不烘焙、按会话解析活 origin」范式补齐到 claude 车道——收敛而非分叉。

  8. 是否引入新配置:无新配置项。BILI_MCP_PROXY 语义不变(本就是可选覆盖),只是安装器不再默认替用户填它。

测试有效性:断言有牙,正负双向门禁齐备——新装不烘焙且命令不含 BILI_MCP_PROXY=;无 pin 条目保持 current、零 CLI churn;遗留旧 pin 被治愈且重加不带 pin;显式 env pin 正例落地 + 重装匹配条目保持 current;不可读 json 回退也不烘焙。resolveClaudeMcpOrigin 优先级用例直接编码报告者原样(:18791 活值压过 :18787 旧 pin)、空 pin 落活发现。每个安装器用例 try/finally 保存还原 BILI_MCP_PROXY,隔离干净。能兜住回归,非恒真/mock。

CI 状态:PR #5129 head b6484be7 远端 CI 进行中——已完成 7 success / 11 skipped,12 项仍在跑,目前 0 failure。本地 node_modules 缺失未跑本地套件(全量裁决以远端 CI 为准);静态核对确认无孤儿引用/import,typecheck 层面安全。master 自 merge-base 起对这三个文件 0 提交,故 mergeable_state: behind 良性、rebase 零冲突。

判定:独立代码/回归分析全部通过——修法打到根因、与既有范式一致、测试有牙、无回归、diff 干净。建议 CI 转绿后合并;我会盯 CI,转绿/转红第一时间补一条确认。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

CI 红判定:继承性失败,已按 CI 协调政策处理——merge origin/ci-fixes 进 PR 分支并推送(新 head 2b1bb24ae),等 CI 重跑。

证据链:四个红分片的失败签名逐条拉日志核对,全部落在本 PR diff 之外的子系统:

红分片 失败用例 归属
ubuntu 22,2 / 24,2 resolveNativeAttachExternal/LanePriority/Policy/Url ×4 + #3436 native lane attaches ×2 claude-native 测试的 fixture 配置被遮蔽 + #3436 attach 域(src/launcher.ts、src/config.ts)
windows 22,1 resolveNativeAttach* ×4 同上
windows 22,2 #3436 ×2 + snapshotSessionsTree / #5107 sessions-dir leak-guard CLI ×4 windows 路径分隔符 relpath 归一(ci-fixes cf99d93 点名修复面)

本 PR 只改三文件(src/claude-mcp-entry.ts、src/plugin-install.ts、tests/claude-mcp-entry.test.ts),与上述失败路径零交集;且 master 自身在 10:03Z 的 run 上正是这批分片红(#4599 floor 458,哨兵已接管、修复收敛到常驻分支 ci-fixes)。ci-fixes head cf99d93 自述本地定向验证「claude-native + #3436 + test-suite-lock 96/96 pass」,签名对得上。

八问:

  1. 是什么问题:PR head b6484be7 上 4 个 test 分片红——不是本 PR 代码的问题,是 master 侧既有红随分片调度落到了这个 head 上。
  2. 什么原因导致的:master 自身的 native-attach fixture 遮蔽 / native lanes suspected of not reusing instances: one proxy per process, instances only grow (v0.1.197 / opencode v2) | [Bug?] native 车道疑似不复用实例:一进程一代理,实例只增不减(v0.1.197 / opencode v2) #3436 attach / windows leak-guard relpath 三条既有缺陷(CI Control Center: Centralized CI Failure Handling & Status Sync (Comment all CI issues here; do not open new issues) | CI 总控: CI 失败集中处理与状态同步(所有 CI 问题在此评论, 勿开新 issue) #4599 总控域),与 claude MCP face 修复无任何共享代码路径。
  3. 影响范围与严重程度:仅检查矩阵信号层(该 PR 无法转绿),无用户侧功能影响;master 面上同批分片同样红。
  4. 怎么修复的:不动本 PR 代码,git merge origin/ci-fixes(哨兵常驻维护的 master 修复收敛分支)进 PR 分支后推送——merge 无冲突,带入的 23 个文件全是 tests/scripts 测试基建,不触碰本 PR 的三个源文件。
  5. 是否有回归问题:不涉及——本 PR 代码零改动;ci-fixes 带入的是已在 CI Control Center: Centralized CI Failure Handling & Status Sync (Comment all CI issues here; do not open new issues) | CI 总控: CI 失败集中处理与状态同步(所有 CI 问题在此评论, 勿开新 issue) #4599 车道的测试基建修复,其自身回归风险由哨兵车道负责。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及。
  8. 是否引入新配置:不涉及。

已在 #4599 留一行结论(PR #5130 红,已 merge ci-fixes,sha=2b1bb24ae)。CI 重跑结果出来前本条即最终处置;若重跑仍有非继承红,再开下一轮定向排查。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

CI 结论更新(接上一条 review):PR 现已转绿,之前那条「CI 进行中」作废,以此为准。

  • 我最初审的 head b6484be75 有 4 个 test 分片红(ubuntu 22s2 / ubuntu 24s2 / windows 22s1+s2),每片 # fail 6——全部落在 tests/claude-native.test.ts 的 resolveNativeAttachExternal/LanePriority/Policy/Url(src/config.ts:2656-2708)+ #3436 …mitm.domains,断言模式一致:config 文件层的 native.* 值没进到 resolver、全落回默认(false / [] / 'own-lane')。
  • 这是继承性 born-red,不是本 PR 引入,三点证据:① 本 PR 只改 claude-mcp-entry.ts / plugin-install.ts / claude-mcp-entry.test.ts,与失败文件、被调函数零交集;② master 自 merge-base 5594c1315 起对 src/config.ts 和 tests/claude-native.test.ts 0 提交——被测代码与测试从 base 到两侧都逐字未变,本 PR 无从影响;③ 失败是纯输出断言、ubuntu/windows 跨平台复现 = 系统性,非 flaky。
  • 该红已由车队按 CI 协调政策收敛:ci-fixes tip cf99d935f(fix(test): un-shadow fixture configs …)正是命中「fixture config 被环境泄漏 shadow」这一症状的修复,已并入本分支 → 新 head 2b1bb24ae(ci-check 于 18:31 合入,parents = 本 PR commit + ci-fixes)。我动手前先核对了 ci-fixes 三个独有 commit 只碰 test-harness 文件(tests/preload-test-env.mjs 等)、与本 PR 三文件零交集;实际合并到我这边是 no-op(已在),未产生任何新提交/推送。
  • 当前 head 2b1bb24ae CI:36 success / 13 skipped / 0 failure,全绿。

最终判定:独立代码/回归分析通过(修法打到根因、与 #936 opencode 范式一致、测试有牙正负双向、无回归、diff 干净)+ 当前 head CI 全绿。可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Merge guard 结果(第五轮):master 本轮推进很快(约 19 commits,30ec63b55→e19386182),与 PR 三文件零交集。已合入并推送——首次推送遇 origin 代理瞬时 502,重试成功;因 master 在同步期间又前进,补做了第二次同步落到当前 tip。最终新 head ce3426a35(已含 master tip e19386182),全程零冲突。推送后 PR 状态:open,mergeable_state behind → blocked(新 head CI 运行中),无冲突、无需设计决策。注:master 当前处于高频合并期,若再前进仍可能触发新一轮同步。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant