Skip to content

fix(launcher): handle async spawn 'error' in ensureProxyRunning (#835) - #838

Closed
ranxianglei wants to merge 1 commit into
masterfrom
2026-09-16_835-proxy-spawn-error-handler
Closed

ranxianglei wants to merge 1 commit into
masterfrom
2026-09-16_835-proxy-spawn-error-handler

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What & why

ensureProxyRunning (src/launcher.ts) registered only child.on("exit"), never child.on("error"). An async spawn failure — EACCES/ENOENT on a mis-resolved runtime (e.g. a bad BILLION_CONTEXT_NODE or an exotic runtime path) — emits 'error', not 'exit'. With no listener, Node turns that unhandled 'error' into an uncaughtException that kills the hosting process, while the poll loop keeps burning the full SPAWN_WAIT_MS and then misreports "proxy did not become healthy".

runClient already handled 'error' correctly; only the proxy-spawn path was missing it. This is shared code — it affects every launcher that spawns the proxy (pi/omp/opencode/codex/…), not just one client. A narrow trigger (bad runtime resolution) escalates into killing the launching client.

Change

  • Register a child.on("error") handler in ensureProxyRunning.
  • Break the health-poll loop as soon as either childExit or childError is set — fail fast instead of burning the window.
  • After the loop, reject with the spawn cause: bili: proxy spawn failed (<detail>) (log: <path>).
  • Regression test in tests/launcher.test.ts: asserts an 'error' handler is registered on the spawned child and that ensureProxyRunning rejects with spawn failed when the child emits an async spawn error.

Pre-flight

  • npm run typecheck — clean
  • npm test — 1650 tests, 1648 pass, 0 fail, 2 skipped (pre-existing skips)
  • npm run build — success

Provenance / overlap

Found as finding D of #809 while hands-on testing the OpenCode npm-plugin deployment. The identical fix already exists in open PR #824 (commit 54f8fb2), but #824 targets the feat/pi-native-plugin branch (base ≠ master), so the defect is still live on master and in every published release. This PR brings the D-fix forward to master independently so the bug is closed on the mainline. The N4 mcp-guard half of that commit is a separate finding (#809 N4) and is intentionally out of scope here.

Fixes #835.

ensureProxyRunning registered only child.on('exit'), never 'error'. An async spawn failure (EACCES/ENOENT on a mis-resolved runtime) emits 'error', which with no listener becomes an uncaughtException that kills the host process, while the poll loop burns the full SPAWN_WAIT_MS and misreports 'proxy did not become healthy'. runClient already handled 'error' correctly; the proxy-spawn path did not.

Register an 'error' handler, break the poll on it, and reject with the spawn cause ('bili: proxy spawn failed (<detail>)'). Regression test added to tests/launcher.test.ts (asserts an 'error' handler is registered + rejects 'spawn failed').

Found as finding D of #809 while hands-on testing #824; the identical change already lives in open PR #824 (which targets feat/pi-native-plugin, not master). This brings it forward to master independently so the defect is closed on the mainline. Fixes #835.
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-16_835-proxy-spawn-error-handler (32dc9f4)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-838

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

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr838.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] 🏷 Review in progress. Pulled branch 2026-09-16_835-proxy-spawn-error-handler (single commit 32dc9f4, base master):

  • Diff is clean: 2 files, +42/−1 — src/launcher.ts (+13) and tests/launcher.test.ts (+30). Every line is on-topic, no stray changes.
  • CI: all 7 check runs green on the head commit (test ubuntu 22/24, windows 22/24, codex e2e zero-token preflight, build-artifact, version-guard). mergeable: true; state is blocked = awaiting review/merge permission, not a conflict.

Currently running independent local verification (typecheck / test / build) on the branch before giving the final verdict.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review complete — approved, ready for human merge.

Bug verification (triage before review)

  • Confirmed live on master: ensureProxyRunning (src/launcher.ts) registered only child.on?.("exit"). An async spawn failure emits 'error'; with no listener Node escalates it to uncaughtException and kills the hosting client. Meanwhile the loop burns the full SPAWN_WAIT_MS and misreports "did not become healthy" — that misreport is the symptom, the missing handler is the root cause, and this PR fixes the root cause.
  • Confirmed the asymmetry claim: runClient already handles 'error' (src/launcher.ts:2167, rejects with it); only the proxy-spawn path was missing it.

Fix quality

  • Handler follows the existing child.on?.(...) convention; fail-fast break on childExit || childError !== undefined is correct (an errored child can never become healthy); the new throw reuses the sibling errors' style incl. (log: <path>). If both exit+error land, the more specific spawn-failure message wins — sensible.
  • Regression test asserts both required things: an 'error' listener is actually subscribed on the spawned child, and ensureProxyRunning rejects with /spawn failed/ on an async spawn error. Mock style matches neighboring tests.

Diff cleanliness: single commit 32dc9f4, 2 files, +42/−1 — every line on-topic, based directly on master tip (d54070f), no version bump, no lockfile drift.

Provenance check: verified via API — #824 is open with base feat/pi-native-plugin (≠ master), and its commit 54f8fb2 bundles the D-fix with the N4 mcp-guards; this PR carries only the D half to master. Legitimate forward-port, not a duplicate merge; N4 correctly left out of scope.

CI: 7/7 green on the head commit (ubuntu 22/24, windows 22/24, codex e2e zero-token preflight, build-artifact, version-guard). mergeable: true; state blocked = awaiting approval, not a conflict.

Independent local verification (checked out the branch): npm run typecheck clean · tests/launcher.test.ts 168/168 · full suite 1650 tests / 1648 pass / 0 fail / 2 skipped (matches the PR's stated pre-flight exactly) · npm run build success.

No issues found that needed fixing on the branch. Merge is human-only per repo rules: #838

中文摘要:修复了 ensureProxyRunning 只监听 'exit' 不监听 'error'、异步 spawn 失败(EACCES/ENOENT)会把宿主进程打崩的缺陷(根因而非误报症状),diff 干净、CI 全绿、本地独立复验通过,可以合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

继续

@ranxianglei

Copy link
Copy Markdown
Owner Author

Closing as superseded — the fix landed on master via the #809/#824 spawn-failure work:

  • the async error capture is live in src/launcher.ts (the #809/D block: childError capture + bili: proxy spawn failed (…) (log: …)),
  • the regression test is live too: tests/launcher.test.ts — "ensureProxyRunning: registers a child 'error' handler so an async spawn failure rejects cleanly (#809/D)".

Nothing in this PR's diff remains un-merged. (Queue triage per #1020.)

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.

[bug] ensureProxyRunning: missing child error handler kills host on async spawn failure

1 participant