[bug] async 工具 execute() 内 spawnSync → 事件循环死锁（microtask checkpoint 内嵌套 uv_run 重入）

[Jakey1395]

环境：macOS / node v22.23.1 / dsh 0.1.0-rc.7

摘要：工具插件在 async execute() 内同步调用 spawnSync，当该回调被工具调度在 microtask checkpoint 中执行时（由会话写盘 fs close 完成回调触发 checkpoint），spawnSync 内部嵌套运行事件循环（uv_run），与未完成的 checkpoint 重入 → 事件循环永久冻结（HTTP 000，仅 kill -9 恢复）。生产实例一周内挂死 3 次。

挂死栈（macOS sample，5s 采样 4233 次全同）：

uv_run → uv__io_poll → uv__async_io → uv__work_done
→ MakeLibuvRequestCallback<uv_fs_s> → FileHandle::ClosePromise → CloseReq::Resolve()
→ InternalCallbackScope::~InternalCallbackScope → Close()
→ MicrotaskQueue::PerformCheckpoint → RunMicrotasks
→ PromiseFulfillReactionJob → AsyncFunctionAwaitResolveClosure → JIT JS
→ Builtins_CallApiCallbackGeneric
→ node::SyncProcessRunner::Spawn()      ← 同步子进程（JS 内 spawnSync）
→ SyncProcessRunner::Run → TryInitializeAndRunLoop
→ uv_run（嵌套事件循环重入）→ uv__io_poll → kevent（永久阻塞）

触发链：活跃会话周期写盘（writeAtomic → FileHandle close，dsh-session-projection-cache write-behind 每 5s）→ 完成回调触发 microtask checkpoint → checkpoint 中排队的工具调度 await 续体执行 → spawnSync → 嵌套 uv_run 死锁。libuv 4 工作线程全空闲（非线程池饥饿）。

对照实验（逐一否定候选假说）：

实验	条件	结果
活跃会话	活跃 + 写盘，无 spawnSync 工具调用	1 小时+ 不挂
空闲实例	无请求	10 分钟不挂
遍历扫描 / ws-sim / 组合	单独或并发	均不挂
fs+zstd 并发脚本	writeAtomic 5s + 多帧 zstd 解压（含/不含 ALS）	9 分钟不挂

必要条件 = spawnSync 在 checkpoint 中执行；大会话读取等只是概率放大器。

影响面：任何第三方插件作者都可能写出 async execute() { spawnSync(...) }（最自然的写法）——defineTool 契约未禁止/警告此用法，属框架文档/契约缺口。

建议：

1. @deepseek-ai/dsh-tools 文档明示 execute 内禁止同步阻塞（spawnSync/execSync/execFileSync 等）
2. 可选：工具契约层检测/警告同步子进程调用
3. 插件侧修复模式（已用此修复 6 个插件并验证）：spawnSync → promisify(execFile)，超时/非 0 退出在 catch 提取 stdout/stderr，status 语义保持

[denial123789]

This report matches the current tool-lifecycle contract and is broader than a performance concern. In rc.8, ToolDefinition.execute(args, exec) explicitly requires async work to observe or forward exec.signal and settle only after owned work reaches quiescence; the registry does not abandon the promise and cannot hard-kill same-process code. A spawnSync / execSync / execFileSync path cannot satisfy that contract while it owns the Host thread.

The migration should preserve more than stdout:

• use execFile(binary, argv) for bounded output, or async spawn(binary, argv) for streams;
• forward exec.signal;
• keep executable and argv separate instead of replacing execSync(commandString) with shell-based async exec(commandString);
• preserve the old nonzero-exit semantics and bounded stdout/stderr;
• on cancel/timeout/disposal, terminate the owned process tree, drain pipes, wait for quiescence, then settle the same tool promise;
• verify another Session and a Web health probe remain responsive during the call.

For helpers that spawn descendants, the DSH subprocess seam is the stronger owner because its termination and wait contracts are tree-scoped.

I published a complete migration example and acceptance matrix here:
https://sandbaseai.github.io/deepseek-harness-handbook/async-subprocess-tools.html

The source contract is packages/core/tools/src/index.ts lines 222–255; adding the same prohibition and migration pattern to the public tool-authoring guide would make this invariant much harder for ecosystem plugins to miss.

[argszero]

Excellent report — the checkpoint-context detail is the crux, and it's worth making the mechanism explicit because it's why this failure is a hard freeze rather than a mere slowdown.

Why checkpoint-context spawnSync is uniquely deadly. The freeze stack you captured is the exact signature: fs-close completion (FileHandle::ClosePromise) → MicrotaskQueue::PerformCheckpoint → the tool's async continuation → SyncProcessRunner::Spawn → nested uv_run. The event loop is mid-checkpoint when spawnSync's synchronous wait starts; the nested loop waits on I/O (kevent) that the outer loop would normally service, but the outer loop is suspended inside the sync call. That is a libuv re-entrancy deadlock — your control experiments prove it's not thread-pool starvation (4 workers idle). A spawnSync outside a checkpoint is a blocking pause (bad); a spawnSync inside a checkpoint can never return (fatal).

This is the extreme end of a "tool work is not preemptable by the harness" family. The contract at packages/core/tools/src/index.ts:222-233 explicitly says the registry "cannot hard-kill same-process code" — and it genuinely cannot: no signal, abort, or timeout can interrupt a synchronous call that owns the loop. Same family as #3400 (session.cancel can't interrupt a stuck tool call) and the unbounded-wait reports (#1607/#2544: promises that never settle when a listener is absent). The difference here is severity: a hung-but-alive loop can still receive the cancel; a spawnSync-deadlocked loop is frozen before it can even observe the signal. So documentation (denial123789's migration contract) is necessary but not sufficient — the contract needs to make the violation loud, because the harness cannot self-protect.

Two concrete zero-code additions that complement the doc fix:

1. NODE_OPTIONS=--trace-sync-io — Node's built-in flag prints a warning + stack at the moment any sync fs/child_process API is used. This catches spawnSync/execSync/execFileSync at the point of occurrence with the offending plugin's stack, no harness instrumentation needed. Making it the documented "develop your tool with this flag" step turns the silent freeze into an immediate, attributable error.

2. The freeze itself is already diagnosable — codify your sampling procedure. Your macOS sample (5s, 4233 identical) is the canonical diagnostic. The runbook should prescribe: on suspected freeze, sample the process stack (macOS sample <pid>, Windows procdump, or a SIGUSR2/--stack-trace-limit handler), and the SyncProcessRunner::Spawn frame in the nested uv_run is the fingerprint. This is also the exact shape a host health-probe watchdog can detect (loop unresponsive for N seconds → dump + annotate), which is the only detect path available since prevention is impossible from inside the frozen loop.

The 6-plugin migration pattern you validated (spawnSync → promisify(execFile) + timeout + exit-status preservation) is the right plugin-side answer; the framework-side ask is: (a) add the explicit "no synchronous blocking in execute" prohibition to the tool-authoring guide with the checkpoint mechanism explained, (b) document --trace-sync-io as the dev-time tripwire, (c) keep the sampling procedure as the ops-time diagnostic. That closes the loop from "silent weekly freeze" to "caught at write-time, attributed at dev-time, diagnosed at ops-time."