Skip to content

fix: native-hook attach gate — refuse lifecycle-less proxies by default (#1335) - #1337

Merged
ranxianglei merged 3 commits into
masterfrom
2026-09-25_native-attach-gate
Sep 25, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-09-25_native-attach-gate

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #1335

Depends on PR #1330 (this branch contains its two commits — the gate consumes #1330's watchdog health 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:

Listener Lifecycle owner Attach?
Its own session-spawned proxy armed from birth ✅
Another session's armed proxy (watcher set, #1186) watcher set ✅ — sharing stays the design
Manually started bili start daemon none — refuses watchers, never dies with sessions, often an older build ❌ never by default

Attaching 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 → pickAttachable in src/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/health reports watchdog.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) or BILI_NATIVE_ATTACH_EXTERNAL=1 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 by construction.

Bonus fixes:

  • Version skew: each session now runs the currently installed bili instead of whatever a stale resident daemon carries.
  • strictPort fail-fast: a strictPort launch whose pinned port is held by a refused proxy throws a precise error (with the squatter's pid and the opt-in hint) instead of burning the wait window into a confusing EADDRINUSE.
  • claude-native bootstrap catch message now states what is actually true about a non-session-managed listener (previously implied lifecycle guarantees that don't hold).

Behavior changes (old → new)

  1. Default attach decision: old = any code/lane-compatible healthy listener is attached (a manual bili start daemon 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.
  2. Cost accepted (per issue): ~1 extra short-lived proxy process per session when no armed proxy exists; the multi-instance warning (无单实例守卫:多个 bili 代理进程并存共写 sessions 目录,伴随孤儿 ref、有注册表无 transcript、计数自相矛盾的污染簇 #394) becomes more common. Session state is shared on disk, so compression continuity is unaffected.
  3. StrictPort + refused listener on the pinned port: old = spawn attempt → EADDRINUSE retry churn → confusing timeout; new = immediate precise error naming the offending pid and the escape hatch.
  4. Users who deliberately ran a resident daemon for native hooks must set 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 — clean
  • npm test — 2608 pass / 0 fail / 11 skipped (gated live e2e)
  • npm run build — clean
  • New tests: unarmed → self-managed spawn (no watcher registration attempted), missing watchdog field → refused, escape hatch → attached, strictPort squatter error text; resolveNativeAttachExternal precedence 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.

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-25_native-attach-gate (cb7290a)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1337

Each push to this PR publishes a new version under the pr-1337 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1337.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

[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
The #1322-era assertions expected warn-but-attach; PR #1337's gate
refuses unarmed listeners outright (strictPort launch then fails fast).
Pin the refusal + escape-hatch + kill-hint surface.
ework-agent and others added 3 commits September 25, 2026 23:09
…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).
The #1322-era assertions expected warn-but-attach; PR #1337's gate
refuses unarmed listeners outright (strictPort launch then fails fast).
Pin the refusal + escape-hatch + kill-hint surface.
#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
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.

claude-native hooks must not attach to a lifecycle-less proxy — attach gate + self-managed fallback

1 participant