Repository navigation
fix: hermes native lane attach gate — Python discovery now refuses lifecycle-less proxies (#1338) - #1342
fix: hermes native lane attach gate — Python discovery now refuses lifecycle-less proxies (#1338)#1342ranxianglei wants to merge 4 commits into
Conversation
A manually started daemon squatting the claude-native stable port has no BILI_PARENT_PID, so its parent-gone watchdog never arms and every session's POST /__bili/watcher gets a 409 that registerWatcherDefault swallowed silently. The README's 'the proxy lives and dies with the session' contract was void with zero signal anywhere. - /__bili/health now reports watchdog state (armed / parentPid / watchers) so attachers and operators can see whether a proxy dies with its sessions or outlives them all - registerWatcherDefault returns ok|refused|failed instead of void; 409 stays silent at this layer but ensureProxyRunning flags handle.refusedWatcher - the claude-native SessionStart hook logs a loud WARNING when it attaches to such a proxy (non-destructive: the daemon keeps serving, its fate is the operator's) Closes #1322
- watcher-registration: 200->ok / 409->refused / 500->failed / connect-refused->failed via stub HTTP servers - watchdog-health + watchdog-health-daemon (separate files: BILI_PARENT_PID is captured at module load): armed proxy health shows armed/parentPid/watchers and accepts registrations; daemon proxy health shows armed:false and still refuses with 409 - launcher: refused registration flags handle.refusedWatcher, ok does not - claude-native live e2e (gated ACP_TEST_CLAUDE_NATIVE): pre-squatted daemon + fake claude SessionStart -> hook warns on stderr, stays non-destructive, health explains the warning; existing watcher-route test extended with the new health fields
…lt (#1335) A native hook attaches to whatever answers on the port. A manually started 'bili start' daemon has no lifecycle owner (refuses watcher registration, never dies with its sessions, often runs an older bili build) — attaching to it is how #1322 happened. Gate at the shared primitive (ensureProxyRunning / pickAttachable), so every auto-discovery lane inherits it once: claude-native, kimi, dsh, omp, opencode (V1+native), pi, zcode, and the MCP entries. A candidate is attached only when its health endpoint reports an armed session-lifecycle watchdog (watchdog.armed == true, exposed by #1330); a missing watchdog field (pre-#1330 builds) is unverifiable and refused by default. Refused candidates are logged loudly once per origin per bring-up, and the hook spawns its own session-owned proxy instead (ephemeral port, armed from birth, dies with the last session per #1186). This also fixes version skew: sessions now run the currently installed bili. Escape hatch: native.attachExternal (config file) or BILI_NATIVE_ATTACH_EXTERNAL (1/true) restores attaching to any compatible listener regardless of watchdog state. Explicit user-directed attaches (kimi/dsh BILLION_CONTEXT_ATTACH / preset BILLION_CONTEXT_PROXY) bypass discovery entirely and stay exempt. strictPort launches fail fast with a precise error when their pinned port is held by a refused proxy, instead of burning the wait window into a confusing EADDRINUSE; the claude-native bootstrap catch message now says what is actually true about a non-session-managed listener. Preserved: armed instances stay shared (never duplicated, #394/#417), lane compatibility rules (#1225/#1232), code-fingerprint reuse, starter-wait coordination (#707/#964). Docs: README (+zh-CN) lifecycle-contract section rewritten around the gate; CONFIGURATION.md (+zh-CN) documents the new key/env var. Tests: 10 existing attach-path fakes updated to report an armed watchdog (or run under the escape hatch where they model a daemon); new tests pin unarmed -> self-managed spawn, missing-field -> refused, escape-hatch -> attached, and the strictPort squatter error; resolveNativeAttachExternal precedence pinned (env > file, exact-true file value, junk falls through, malformed file degrades closed).
…fecycle-less proxies (#1338) #1335's attach gate lives in the shared TS primitive (ensureProxyRunning / pickAttachable), which every TS auto-discovery lane inherits. The hermes plugin is a separate Python implementation whose own discovery path (discover_instance -> _attach) bypassed that primitive entirely: a hermes session could still attach to a manually started `bili start` daemon — no death-with-session guarantee, swallowed 409 watcher refusals, version skew (the exact one-way dependency #1322 demonstrated). Mirror the gate on the Python side, behavior-identical to the TS gate: - discover_instance now reads /__bili/health's watchdog.armed (#1330); missing field / non-bool / unreachable health = unverifiable -> refuse (default-deny), same as attachGateAllows. - Same escape hatch: env BILI_NATIVE_ATTACH_EXTERNAL (1/true opens, 0/false closes) > config file native.attachExternal (exactly true) > default false — mirrors resolveNativeAttachExternal. - On refusal: log loudly once per origin per bring-up, then fall through to the existing spawn path (session-owned proxy, armed from birth). - Explicit BILLION_CONTEXT_ATTACH stays exempt (handled before discovery). - Armed instances stay shareable (#394/#417): only unarmed or unverifiable candidates are refused. Pin the health contract (endpoint, field, default-deny rule, escape-hatch names/precedence, exempt paths, refusal behavior) in TECHNICAL-NOTES.md so the two implementations cannot drift. Tests: 6 new subprocess scenarios drive the shipped plugin against a stub proxy — unarmed refused+inert+logged, missing-field refused (default-deny), env escape attaches, config-file escape attaches, armed stays attachable, explicit attach exempt even against an unarmed health report. Fixes #1338
1b428a5 to
cb7290a
Compare
[bot] 🏷 Reviewed PR #1342 against the live branch. Verdict: do not merge as-is — it is now redundant with #1337 and in a conflicting state. Details below; I verified each point with git + the GitHub API rather than trusting the description. What changed while this PR was open#1342 branched off #1337 at So #1342 is no longer "stacked on #1337's head" — it is a sibling that diverged at
Code comparison (I read both implementations)Functionally equivalent at the core — both read
I confirmed the CI on #1342's headGreen — 3/3 checks (codex e2e vs fake upstream, hermetic registry e2e, pi package-native lane). Pre-flight per the description also green. So this is not a "CI red" situation; it's a duplication/conflict situation. What #1342 uniquely has that #1337 does NOT
Recommendation (your call — it's your parallel work, so I will not touch #1337 unilaterally)
Behavior-change note: choosing one implementation over the other introduces no new behavior delta — both implement the identical documented old→new default-deny change; whichever lands, hermes attaches only when 一句话中文摘要:核对发现本 PR(#1342)与你在 #1337 里独立提交的同款 hermes 修复(commit |
|
Superseded: the hermes attach-gate fix landed via #1337 (commit cb7290a — same gate semantics, watchdog_armed/resolve_attach_external/discover_instance refusal + 4 stub-health scenarios), which auto-closed #1338 at merge. This PR's diff is now redundant against master; closing to avoid double-landing. Thanks for the parallel implementation — the escape-hatch naming matched. |
Fixes #1338
Stacking note: this PR is based on PR #1337's branch (
2026-09-25_native-attach-gate), not master — it reuses #1337's gate semantics and escape-hatch names directly, so the diff here is a clean 3-file change. It becomes mergeable once #1337 lands (rebase onto master then, or merge in order).What & why
#1335's attach gate lives in the shared TS primitive (
ensureProxyRunning→pickAttachable,src/launcher.ts), which every TS auto-discovery lane inherits. The hermes plugin is a separate Python implementation with its own discovery path that bypassed that primitive entirely:discover_instance()only checked pid liveness + a manifest probe, so a hermes session could still attach to a manually startedbili startdaemon — inheriting exactly the one-way dependency #1322 demonstrated: no death-with-session guarantee, swallowed 409 watcher refusals, version skew.This mirrors the gate on the Python side, behavior-identical to the TS gate:
discover_instance()now reads/__bili/health'swatchdog.armed(fix: surface claude-native attach-to-daemon watcher refusal (#1322) #1330). Missing field / non-boolean / unreachable or malformed health = unverifiable → refuse (default-deny, same asattachGateAllows).BILI_NATIVE_ATTACH_EXTERNAL(1/trueopens,0/falsecloses, anything else falls through) > config filenative.attachExternal(must be exactlytrue) > defaultfalse. MirrorsresolveNativeAttachExternal(src/config.ts) including theBILI_CONFIG_FILEoverride and XDG config path resolution.BILLION_CONTEXT_ATTACHstays exempt (handled before discovery, per claude-native hooks must not attach to a lifecycle-less proxy — attach gate + self-managed fallback #1335's semantics).bili startdaemons (no watchdog) and pre-fix: surface claude-native attach-to-daemon watcher refusal (#1322) #1330 proxies (no watchdog field)./__bili/healthreportswatchdog.armed === true; anything else logs one refusal line per origin and spawns its own session-owned proxy instead. Settingnative.attachExternal: trueorBILI_NATIVE_ATTACH_EXTERNAL=1restores the old behavior (identical names to the TS lanes from claude-native hooks must not attach to a lifecycle-less proxy — attach gate + self-managed fallback #1335). ExplicitBILLION_CONTEXT_ATTACHbehavior is unchanged.This is the same class of default change #1335 made for the TS lanes; hermes was simply the missed lane.
Tests
6 new subprocess scenarios drive the shipped plugin against a stub proxy (same harness as the existing suite):
discover-unarmed:armed:false→ inert, no marker left, stderr contains the "NO session-lifecycle watchdog" refusal;discover-missing-field: health withoutwatchdog→ refused (default-deny);discover-escape-env: unarmed +BILI_NATIVE_ATTACH_EXTERNAL=1→ attaches fully;discover-escape-config: unarmed + config filenative.attachExternal:true→ attaches fully;discover-armed:armed:true→ attaches (sharing regression guard, 无单实例守卫:多个 bili 代理进程并存共写 sessions 目录,伴随孤儿 ref、有注册表无 transcript、计数自相矛盾的污染簇 #394/实例治理伞形:身份/验活/attach-or-spawn/优雅退出/状态卫生 —— 合并修复 #394 #403 #407 #414 #410 #406 #417);attach-unarmed: explicitBILLION_CONTEXT_ATTACHagainst an unarmed health report + 409 watcher → still attaches (pins the exemption).Pre-flight on this branch:
npm run typecheckclean ·npm test2614 pass / 0 fail / 11 skipped ·npm run buildOK (dist-import-annotations: OK).No README/CONFIGURATION.md changes needed: #1337 already rewrote the generic Option-1 lifecycle paragraph ("attaches … only when it passes the attach gate below") which covers hermes, and no new config keys are introduced.