Repository navigation
fix: native-hook attach gate — refuse lifecycle-less proxies by default (#1335) - #1337
Merged
Merged
Conversation
Contributor
📦 Built Package ArtifactBranch: Option A — Install from npm PR tag (recommended)npm install -g billion-context@pr-1337Each push to this PR publishes a new version under the Option B — Download artifact
tar xzf billion-context-pr1337.tgz
npm install -g packageInstall instructions are refreshed on each push. |
Owner
Author
[bot] 🏷 Reviewing PR #1337 now (stacked on #1330, which is still open — I'll treat the 3-commit stack as the unit under review). Plan: pull the branch, walk the diff file-by-file against the original issue's acceptance criteria (#1335), regression-check every existing attach/sharing flow the touched paths carry, run typecheck/test/build locally, then report with a merge verdict. Will reply here with the full conclusion shortly. |
ranxianglei
added a commit
that referenced
this pull request
Sep 25, 2026
…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).
#1338) hermes-plugin/__init__.py discover_instance() probed only pid liveness + manifest health, so a manually started 'bili start' daemon (unarmed watchdog, refuses 409, never dies with sessions) was silently ridden — the exact disease #1335 fixed for the TS lanes. - watchdog_armed(): read #1330's /__bili/health watchdog field; absent (pre-#1330 build) counts as unverifiable => unarmed, mirroring pickAttachable. - resolve_attach_external(): BILI_NATIVE_ATTACH_EXTERNAL > bili config native.attachExternal > false — mirrors resolveNativeAttachExternal (src/config.ts); BILI_CONFIG_FILE override honored. - discover_instance() refuses unarmed listeners (log dedup per origin), falling through to the session-owned spawn; explicit BILLION_CONTEXT_ATTACH stays exempt (user-directed). - tests/hermes-native.test.ts: stub health endpoint (BC_HEALTH_WATCHDOG armed/false/absent) + 4 scenarios — armed attaches, unarmed refused to inert spawn fallback, absent-field refused, escape hatch attaches. Fixes #1338
ranxianglei
force-pushed
the
2026-09-25_native-attach-gate
branch
from
September 25, 2026 15:10
1b428a5 to
cb7290a
Compare
This was referenced Sep 25, 2026
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #1335
Depends on PR #1330 (this branch contains its two commits — the gate consumes #1330's
watchdoghealth field; merge #1330 first or squash this on top of it).Problem
A native hook attaches to whatever answers on the port. Three listener kinds exist:
bili startdaemonAttaching to the third kind is how #1322 happened: sessions depend one-way on a process with no lifecycle contract.
Fix
Gate at the shared primitive (
ensureProxyRunning→pickAttachableinsrc/launcher.ts), so every auto-discovery lane inherits it once — claude-native, kimi, dsh, omp, opencode (V1 + native), pi, zcode, MCP entries (per the scope generalization in the issue thread). A candidate is attached only when its/__bili/healthreportswatchdog.armed == true; a missing field (pre-#1330 builds) is unverifiable and refused by default. Refusals log 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 watcher semantics).Escape hatch:
native.attachExternal: true(config file) orBILI_NATIVE_ATTACH_EXTERNAL=1restores attaching to any compatible listener regardless of watchdog state. Explicit user-directed attaches (kimi/dshBILLION_CONTEXT_ATTACH/ presetBILLION_CONTEXT_PROXY) bypass discovery entirely and stay exempt by construction.Bonus fixes:
Behavior changes (old → new)
bili startdaemon was shareable by every client); new = only listeners reporting an armed watchdog are attached — unarmed/unverifiable listeners are refused and each session spawns its own ephemeral proxy. Reason: [bug] claude native proxy outlives all sessions despite README lifecycle contract — watcher-based shutdown did not fire #1322 — one-way dependency on a process that cannot die with its users.native.attachExternal: true/BILI_NATIVE_ATTACH_EXTERNAL=1(documented in README + CONFIGURATION.md, zh/en).Preserved (no regression of existing flows): armed instances stay shared and are never duplicated (#394/#417), lane compatibility (#1225/#1232), code-fingerprint reuse, starter-wait coordination (#707/#964), explicit-attach exemption.
Verification
npm run typecheck— cleannpm test— 2608 pass / 0 fail / 11 skipped (gated live e2e)npm run build— cleanresolveNativeAttachExternalprecedence pinned (env > file, exact-true file value, junk falls through, malformed file degrades closed). 10 existing attach-path fakes updated to report an armed watchdog (or run under the escape hatch where they model a daemon, incl. the [bug] claude native proxy outlives all sessions despite README lifecycle contract — watcher-based shutdown did not fire #1322 refused-watcher path which is now reachable through the opt-in).Note for reviewers: the hermes Python plugin has its own out-of-band attach path (
hermes-plugin/__init__.py) that does not go through this primitive — filed as a follow-up issue.