Skip to content

fix: hermes native lane attach gate — Python discovery now refuses lifecycle-less proxies (#1338) - #1342

Closed
ranxianglei wants to merge 4 commits into
2026-09-25_native-attach-gatefrom
2026-09-25_hermes-attach-gate
Closed

ranxianglei wants to merge 4 commits into
2026-09-25_native-attach-gatefrom
2026-09-25_hermes-attach-gate

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

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 started bili start daemon — 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:

  1. discover_instance() now reads /__bili/health's watchdog.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 as attachGateAllows).
  2. Same escape hatch as the TS lanes: env BILI_NATIVE_ATTACH_EXTERNAL (1/true opens, 0/false closes, anything else falls through) > config file native.attachExternal (must be exactly true) > default false. Mirrors resolveNativeAttachExternal (src/config.ts) including the BILI_CONFIG_FILE override and XDG config path resolution.
  3. On refusal: log loudly once per origin per bring-up, then fall through to the existing spawn path — a session-owned proxy on an ephemeral port, armed from birth, dying with the last session (fix: shared stable-port proxy outlives its first owner (watcher set + grace window + gated route) #1186).
  4. Explicit BILLION_CONTEXT_ATTACH stays exempt (handled before discovery, per claude-native hooks must not attach to a lifecycle-less proxy — attach gate + self-managed fallback #1335's semantics).
  5. Armed instances stay shareable (无单实例守卫:多个 bili 代理进程并存共写 sessions 目录,伴随孤儿 ref、有注册表无 transcript、计数自相矛盾的污染簇 #394/实例治理伞形:身份/验活/attach-or-spawn/优雅退出/状态卫生 —— 合并修复 #394 #403 #407 #414 #410 #406 #417): only unarmed or unverifiable candidates are refused.
  6. The health contract (endpoint, field, default-deny rule, escape-hatch names/precedence, exempt paths, refusal behavior) is pinned in TECHNICAL-NOTES.md so the TS and Python copies cannot drift.

⚠️ Behavior change (intended — old → new)

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):

Pre-flight on this branch: npm run typecheck clean · npm test 2614 pass / 0 fail / 11 skipped · npm run build OK (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.

ework-agent added 4 commits September 25, 2026 21:49
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
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[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 36d32d1f (the #1335 attach gate). After that, #1337 (2026-09-25_native-attach-gate) advanced past the fork point and picked up two more commits — 5ba30d34 (e2e test pin) and, critically, 1b428a51 "carry the #1335 attach gate into the hermes Python discovery path (#1338)" — i.e. an independent implementation of the very same hermes fix, touching the same files (hermes-plugin/__init__.py, tests/hermes-native.test.ts).

So #1342 is no longer "stacked on #1337's head" — it is a sibling that diverged at 36d32d1f. Two consequences:

Code comparison (I read both implementations)

Functionally equivalent at the core — both read /__bili/health's watchdog.armed, default-deny on missing / non-bool / unreachable health, same escape-hatch precedence (BILI_NATIVE_ATTACH_EXTERNAL env 1/true vs 0/false > config native.attachExternal === true > false, incl. BILI_CONFIG_FILE), explicit BILLION_CONTEXT_ATTACH exempt, armed stays shareable (#394/#417), log-once-per-origin, fall through to a session-owned spawn. Minor differences (neither is wrong):

I confirmed the ok field is real: the live handler on the branch returns { ok: true, …, watchdog: { armed: initialWatcherPid !== null, … } } (src/server.ts:888), so neither version silently no-ops — sharing still works for armed proxies.

CI on #1342's head

Green — 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

  1. The TECHNICAL-NOTES.md "Native attach gate — health contract" section (endpoint, watchdog.armed field, default-deny rule, escape-hatch names + precedence, exempt paths, refusal behavior, and the TS↔Python cross-reference). Issue hermes native lane can still attach to lifecycle-less proxies — #1335's attach gate does not cover the Python-side discovery path #1338 explicitly asked for this drift-prevention contract, and I verified fix: native-hook attach gate — refuse lifecycle-less proxies by default (#1335) #1337 makes no TECHNICAL-NOTES change — so closing fix: hermes native lane attach gate — Python discovery now refuses lifecycle-less proxies (#1338) #1342 without salvaging this would drop the requested contract.
  2. Two extra test pins: config-file escape hatch, and the explicit-attach-exemption case.

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 watchdog.armed === true.

一句话中文摘要:核对发现本 PR(#1342)与你在 #1337 里独立提交的同款 hermes 修复(commit 1b428a51)重复,且因 #1337 已前进,#1342 现处于冲突态(mergeable:false/dirty)、两版代码功能等价——建议先合 #1337、再关掉 #1342,只把 #1342 独有的 TECHNICAL-NOTES「健康契约」一节(及可选的 2 个测试钉)并入 #1337 或单独小 PR,避免两份实现漂移;是否照此处理由你定。

@ranxianglei

Copy link
Copy Markdown
Owner Author

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.

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