Skip to content

[PR] fix(claude): stop force-exiting the SessionStart hook (Windows libuv abort) - #7094

Open
Sentryea wants to merge 2 commits into
ranxianglei:masterfrom
Sentryea:2026-11-18_fix-claude-hook-graceful-exit
Open

Sentryea wants to merge 2 commits into
ranxianglei:masterfrom
Sentryea:2026-11-18_fix-claude-hook-graceful-exit

Conversation

@Sentryea

@Sentryea Sentryea commented Nov 17, 2026 •

Copy link
Copy Markdown

Fixes #7093

What & why

On Windows + Node v24.15.0, Claude Code's SessionStart hook aborts after the proxy attaches:

[bili-claude-bootstrap] proxy attached at http://127.0.0.1:18787
Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 76

Exit code is -1073740791 (0xC0000409). The proxy attach succeeds, but the hook process aborts during teardown, so Claude marks the whole SessionStart hook as failed.

Root cause: hookMainWithDeps destroyed stdin and then called the default process.exit(0) in the same finally. On Windows + early Node 24.x, that races libuv's win async-handle close path and trips the assertion. This is the same mechanism fixed for zcode/kimi in #2943 / #2946; the Claude hook had been left untouched as lower risk, but Node v24.15.0 reproduces it.

Fix

Route the Claude SessionStart hook through the existing runSessionStartHook():

  • tear down stdin, set process.exitCode = 0, and let the event loop drain to a natural exit;
  • keep the unref'd 5-second backstop only for an unexpected leaked handle;
  • never call process.exit() on the normal path;
  • add Claude-specific regression coverage for the normal and backstop paths, and update the existing hook-entry assertions.

Scope / non-changes

  • src/claude-native-bootstrap.ts, src/agent/shared.ts comments, and two test files only.
  • No config, wire, persistence, or dependency changes.

Verification

  • npm run typecheck clean.
  • node --import tsx --test tests/hook-graceful-exit.test.ts: 6/6 pass.
  • Manual hook run: proxy attached at http://127.0.0.1:18787, exit code 0, no libuv assertion.
  • Real claude -p "reply OK" --max-turns 1: output OK, exit code 0, no SessionStart hook error.

Full CI runs on the PR head.

The claude-native-bootstrap hook destroyed stdin and then called process.exit(0) in the same tick, which triggers a libuv win async-handle close assertion on Node 24.15.0. Route it through runSessionStartHook so the event loop drains naturally, with the unref'd backstop only as a leak guard.

Refs ranxianglei#7093
@ranxianglei ranxianglei changed the title fix(claude): stop force-exiting the SessionStart hook (Windows libuv abort) [PR] fix(claude): stop force-exiting the SessionStart hook (Windows libuv abort) Nov 17, 2026
ranxianglei#2943)

Review addition for the Claude hook graceful-exit fix: the zcode lane already
carries a spawn-level 'real entry exits 0 promptly and does not hang' test in
this file; the claude lane had only the injectable-deps coverage plus manual
verification. Add the claude counterpart — spawn the real
src/claude-native-bootstrap.ts entry with BILLION_CONTEXT_PROXY set (plan
action "exit": earliest safe return, no proxy/config side effects) and assert
a prompt clean exit 0. Bounded by an 8s SIGKILL so the suite can never hang.
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复 — 与 #2943 (issue) / #2946 (PR) 同一机制:那两条已修复 zcode/kimi 车道的同型 process.exit 与 libuv win async-handle 关闭竞态(均已关闭);本 PR 是该机制在 Claude 车道的未修复实例。无其他 open issue/PR 覆盖 Claude hook 此问题。

标签: bug, claude-code, scope/wiring, p2 — Windows + 早期 Node 24.x 上 hook 可见失败,但 proxy 已附着、压缩功能不受影响,故 p2。

Review in progress — initial findings:

  • Direction: correct. Root cause matches the shipped [zcode] Windows + Node 24.14 上 bootstrap-hook.js 必崩(libuv 断言 async.c:76),zcode 集成静默失效 #2943/fix(zcode,kimi): SessionStart hooks stop force-calling process.exit (Windows libuv abort) #2946 fix: the hook destroyed stdin and called process.exit(0) on the normal path in the same finally, racing libuv's Windows async-handle close. Routing through the existing runSessionStartHook() (stdin teardown + exitCode = 0 + natural drain + unref'd 5s backstop) is the right shape. The src/agent/shared.ts comment updates are accurate — "24.21+ is clean" is grounded in the [zcode] Windows + Node 24.14 上 bootstrap-hook.js 必崩(libuv 断言 async.c:76),zcode 集成静默失效 #2943 control experiment (24.14.0/24.14.1 crash, 24.21.0 clean).
  • Regression check (so far): clean. Fail-open behavior, the 2s stdin-drain contract, and all non-"start" plan paths are untouched. I verified the natural-drain claim empirically: undici keep-alive does not hold the event loop, the spawned proxy child is detached + unref'd (src/launcher.ts:5862/5900), and no live interval timers exist on the hook's run path — so exit is immediate in practice and the 5s backstop is a pure leak guard (bounded worst case ≪ Claude's 60s hook timeout).
  • Local verification: tests/hook-graceful-exit.test.ts 5/5 pass on the PR head; tests/claude-fork-lineage.test.ts hook-entry tests pass (3 unrelated growParent failures reproduce identically on master — pre-existing sandbox difference, not this PR).
  • One gap, fixed in place (additive commit 50a705b on the PR branch): the zcode lane carries a spawn-level "real entry exits 0 promptly and does not hang" test in this file, but the claude lane had only injectable-deps coverage. I added the claude counterpart — spawn the real src/claude-native-bootstrap.ts entry with BILLION_CONTEXT_PROXY set (plan action "exit": earliest safe return, no side effects), assert prompt clean exit 0, 8s SIGKILL bound. File now 6/6 pass; typecheck clean.

CI: the original head (128d8bf) is fully green — all 11 test shards + both static-gates + all 14 guard jobs pass. The run for the new head (50a705b) is still being scheduled; I'll post the full verdict (8问) once it completes.

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

Review complete — verdict: mergeable (可合).

The fix routes the Claude SessionStart hook through the same runSessionStartHook() helper that #2943/#2946 already shipped for zcode/kimi: stdin teardown + exitCode = 0 + natural drain, with an unref'd 5s backstop only for unexpected leaked handles. I verified the natural-drain claim empirically (undici keep-alive does not hold the loop; the spawned proxy child is detached + unref'd at src/launcher.ts:5862/5900; no live interval timers on the hook's run path) — exit is immediate in practice, so the 5s backstop is a pure leak guard, far below Claude's 60s hook timeout. The shared helper itself is byte-unchanged, so the zcode/kimi lanes are untouched.

8问:

  1. 是什么问题:Windows + 早期 Node 24.x(24.14.x/24.15.x 已确认)上,Claude Code 的 SessionStart hook 在 proxy 附着成功后被 libuv 断言中止(assert(!(handle->flags & UV_HANDLE_CLOSING)),src/win/async.c:76,exit 0xC0000409),Claude 把整个 hook 标记为失败。
  2. 什么原因导致的:hook 的 finally 在同一 tick 里销毁 stdin 并调用 process.exit(0),在 Windows 上与 libuv 的 async-handle 关闭路径竞态。与 [zcode] Windows + Node 24.14 上 bootstrap-hook.js 必崩(libuv 断言 async.c:76),zcode 集成静默失效 #2943/fix(zcode,kimi): SessionStart hooks stop force-calling process.exit (Windows libuv abort) #2946 修复的 zcode/kimi 同机制——Claude 车道当时被判定低风险而未改,Node 24.15.0 证明它同样会触发。
  3. 影响范围与严重程度:仅 Windows + Claude Code + 早期 Node 24.x。每次会话启动 hook 可见失败,但 proxy 在 abort 前已附着、压缩功能不受影响 → p2(可用但有明显问题;升级 Node 到 24.21+ 可绕行,[zcode] Windows + Node 24.14 上 bootstrap-hook.js 必崩(libuv 断言 async.c:76),zcode 集成静默失效 #2943 对照实验确认 24.21+ 干净)。
  4. 怎么修复的:复用既有共享 helper runSessionStartHook()——拆 stdin、置 process.exitCode = 0、让事件循环自然排空退出;unref 的 5s backstop 仅在意外泄漏 handle 时强退(此时所有 handle 早已 settle,不会再触发竞态)。正常路径永不 process.exit()。
  5. 是否有回归问题:无。逐项审过的既有行为:① zcode/kimi 车道共用该 helper——helper 本身零改动,不受影响;② fail-open 保持——main() reject 时仍走同一 finally 到 exit 0;③ 2s stdin-drain 契约未动;④ 退出时序——实测自然排空即时(33ms 模拟 / ~500ms 真实 spawn 含 tsx 启动),最坏有界 5s ≪ 60s hook 超时。有意的行为变更(已披露):退出从同 tick 强退变为自然排空 + 5s 泄漏兜底,有界且仅影响该 hook 进程生命周期;⑤ 无 wire/persistence/config/kernel 改动;⑥ 本地定向验证:tests/hook-graceful-exit.test.ts 6/6 过,tests/claude-fork-lineage.test.ts hook-entry 测试过(3 个 growParent 失败在 master 上同样复现,系既有沙箱环境差异,非本 PR)。
  6. 是否破坏缓存:不涉及——短命 hook 进程生命周期,未触碰任何缓存/重试/游标/去重面。
  7. 是否改了设计方向:否——复用 [zcode] Windows + Node 24.14 上 bootstrap-hook.js 必崩(libuv 断言 async.c:76),zcode 集成静默失效 #2943/fix(zcode,kimi): SessionStart hooks stop force-calling process.exit (Windows libuv abort) #2946 建立的共享 helper,Claude 车道与 zcode/kimi 对齐同一模式,无新架构/边界/数据流。
  8. 是否引入了新的配置:不涉及——无新 env/config/默认值。

CI:最终 head 50a705b 上全部 52 个 check run 绿(11 个 CORE test shard + 2 个 static-gates + 全部 guard job;e2e 车道按 CORE scope 设计跳过)。PR 显示 "blocked" 仅因仓库 CORE 矩阵按设计(ci.yml #3295)不产出三个 legacy test (windows-latest, 24, *) required context——这是本仓库所有 PR 的常态,enforce_admins 关闭,可直接合并。Windows + Node 24 的 libuv 竞态本身在 CI 任何可用 Node 版本上不可复现(CI 的 node-24 镜像解析为最新 24.x,按 #2943 对照实验已干净);直接证据是作者的 Windows + Node 24.15.0 手动复现 + 本 PR 的生命周期测试。

Review 顺带补强(已推至 PR 分支):commit 50a705b 补上 claude 车道的 spawn 级真实入口测试(与同文件 zcode "real entry exits 0 promptly and does not hang" 对齐)——此前 claude 只有可注入依赖的覆盖。

判定:可合——方向正确(修根因非症状)、回归干净、测试双向钉住、CI 绿。

This branch has not been deployed

No deployments
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] Windows + Node 24.15: SessionStart hook aborts with libuv assertion async.c:76 (process.exit race)

2 participants