[建议] 任务卡在下载/安装时无法停止：不可中断的工具使 cancel 无法生效（协作式契约无强制力） [Suggestion] Non-interruptible tools make cancel ineffective: the cooperative execute contract has no teeth

[ningmengxr]

摘要 / Summary

当 agent 卡在一个长时间运行的前台工具调用上（例如 pip install torch 或 curl -o 在网络不稳定时下载 2.5GB 大文件），
原生的「停止」按钮和 session.cancel 都无法及时终止任务。需要修正此前的表述：session.cancel 本身不是被排队——
宿主调用 agent.cancel({ kind: "user" }, { keepInbox: true }) 会立即返回 { accepted: true }；但该确认只证明 agent 信号被中止，
不证明已启动的工具/子进程树/管道/插件 promise 已收敛（quiescence）。不可中断的工具拒绝 settle，会话因此冻结到工具结束或超时。

When the agent is stuck waiting on a long-running foreground tool call (e.g. pip install torch or a curl -o download over a slow/unstable network), neither the native Stop button nor session.cancel can stop the task in time. Note: session.cancel is not queued — the host calls agent.cancel({ kind: "user" }, { keepInbox: true }) and immediately gets { accepted: true }, which only proves the agent signal was aborted, not that the started tool/child tree/pipe/plugin promise reached quiescence. A non-interruptible tool refuses to settle, so the session stays frozen until the tool finishes or times out.

复现步骤 / Repro

1. 让 agent 执行一个长时间下载（如 curl -o big.zip <url> 或 pip install）。
2. 下载仍在进行时点击「停止」/ 调用 session.cancel。
3. 轮次不会结束，agent 继续等待该工具调用数分钟甚至更久。

影响 / Impact

在国内网络环境下非常常见：pip / GitHub 下载频繁卡顿或超时。用户会陷入"停不掉、也进行不下去"的局面，
只能重启 DSH。这对国内用户是很高频的痛点。

Very common in CN networks where pip/GitHub downloads frequently hang or time out. Users are left with a task they can neither finish nor stop, forcing a DSH restart.

衍生问题（跨启动）/ Follow-up: triggerable second lock across restarts

通过杀进程解决第一层锁死之后，还存在更隐蔽的第二层问题：
DSH 重启并重新连接后，不会主动恢复上一个等待；但当用户输入「继续」「继续上一个任务」「恢复刚才的任务」
等恢复类提示词时，会触发 agent 对一个【已经不存在于新进程中的任务】发起恢复/重试，于是再次陷入对
该空壳任务的返回值等待，暂停键/停止键再次全部失效，只能再次重启。

After killing the stuck process, a subtler second layer remains:
DSH does NOT automatically resume the old wait after restart and reconnect. But when the user sends
resume-style prompts like "continue", "continue the previous task", or "resume the last task",
the agent is triggered to resume/retry a task that no longer exists in the new process, and falls back
into waiting on its phantom return value — Stop/cancel become unresponsive again, forcing another restart.

家族汇总 / Family summary

这是「工具工作不可被宿主抢占」家族的第 3 个报告，与两个既有报告共享同一根因：

报告	现象	严重度
#1607 / #2544（unbounded-wait）	promise 永不 settle（监听器缺失时查询挂起）	可收到 cancel，但不响应
#3477（spawnSync checkpoint 死锁）	工具同步阻塞在 microtask checkpoint → 嵌套 uv_run 重入 → 事件循环永久冻结	cancel 无法送达
#3400（本帖）	工具异步但不可中断（前台长下载/安装，不观察 exec.signal 或子进程不受控）	cancel 被等待在工具返回值之后

共同根因：packages/core/tools/src/index.ts:222-233 的 execute 契约是协作式——registry "cannot hard-kill same-process code"，工具必须自行观察 exec.signal 并让工作达到 quiescence。契约对不合作的工具没有任何强制力，一个不观察 signal 的插件就能让会话无限期冻结。

This is the 3rd report of the "tool work cannot be preempted by the host" family (#1607/#2544 unbounded-wait, #3477 spawnSync deadlock, #3400 non-interruptible tools), sharing one root cause: the cooperative execute contract at core/tools/src/index.ts:222-233 has no enforcement against uncooperative tools.

两条 API 诉求 / API requests

① 工具层进程树终止能力

• 现状：dsh-subprocess 已存在树作用域终止契约，但未暴露到 tools/execute 工具层；
• 诉求：暴露为工具执行的可终止接口（配合 exec.signal 转发 + 管道清理 + 有界收尾），使宿主/插件无需"猜命令行指纹"强杀；
• 源码 seam：packages/core/tools/README.md#cancellation、packages/host/apiproxy/src/api-proxy.ts:2617-2633

② 中断恢复的强制决策点

• 现状：冷恢复用 interruptedTurnClosers（core/session/src/repair.ts:27）合成 closers，TOOL_OUTCOME_UNKNOWN（repair.ts:13-16）的恢复提示文本（repair.ts:104）引导模型"只在只读/幂等时重试"，但这是提示而非强制；
• 诉求：升级为结构化决策点——模型对 TOOL_OUTCOME_UNKNOWN 的调用重试前必须显式选择（验证外部状态 / 询问用户 / 放弃），使恢复契约从"建议"变为"硬门"。

建议修复方案 / Suggested fix

• 在工具层落地可终止的执行接口（进程树终止 + signal 转发 + 管道清理 + 有界收尾）；
• 将 TOOL_OUTCOME_UNKNOWN 恢复语义升级为结构化决策点；
• 向宿主插件开放工具级 kill/terminate 能力（官方 API 落地前的插件侧应急）。

参考实现 / Reference implementation

我开发了一个插件解决了第一层问题（运行中的锁死）：宿主按卡住工具的命令行特征匹配并强制杀掉子进程，
使工具调用立即返回——用户因此获得一键「急停」（带防误触确认，外加下载进度检测），并正在落地：
急停后的真实 stopping 状态展示（accepted / stopping / idle 三态）与 TOOL_OUTCOME_UNKNOWN 的结构化恢复决策。
注意：该插件【无法解决】上述跨启动的触发式二次锁死，它需要 DSH 官方在会话恢复/重试机制层面修复。

I built a plugin that solves the first layer (in-session lockup): the host matches the stuck tool's command-line
fingerprint and force-kills the child process — one-click "emergency stop" with a confirmation dialog and live
download-progress detection. It is an emergency workaround; the real fix belongs in the tool execution layer.

🔗 https://github.com/ningmengxr/dsh-task-control （npm: dsh-task-control）

---

Analysis credits / 分析来源

• denial123789（SandBase AI）：源码级修复方向（信号转发 + 进程树终止 + 管道清理 + 有界收尾）、12 修复门、跨重启语义 — 本帖评论
• argszero：家族归类（cordis_inspect_query client-platform queries hang forever when no page responds, freezing the agent #1607/userQuestions: single global provider without timeout hangs non-web channels (WeChat/Telegram gateways) forever #2544/[bug] async 工具 execute() 内 spawnSync → 事件循环死锁（microtask checkpoint 内嵌套 uv_run 重入） #3477）、恢复契约机制确认（repair.ts 根因与源码位置）— 本帖评论

谢谢！Thanks!

[denial123789]

The current rc.8 source suggests a useful distinction for this report: session.cancel itself is not queued behind the tool result. The Web Host calls agent.cancel({ kind: "user" }, { keepInbox: true }) and immediately returns { accepted: true }. That acknowledgement only proves the Agent signal was aborted; it does not prove an already-started tool, child tree, pipe, or plugin promise has reached quiescence.

The tools contract is deliberately cooperative: every tool gets exec.signal, and the registry does not race away from a started same-process promise. This keeps DSH from recording a final result while a side effect continues invisibly, but an uncooperative download/install implementation can prevent idle indefinitely. The repair therefore needs signal forwarding plus process-tree termination, pipe cleanup, and bounded settlement—not only another UI cancel request.

There is a second distinction after restart. The old OS process/promise cannot resume. Cold Session recovery closes interrupted calls with TOOL_NOT_STARTED or TOOL_OUTCOME_UNKNOWN. A later “continue” is a new model turn; it may choose to retry because the durable outcome says the side effect is unknown. That retry should be automatic only for read-only or proven-idempotent work; writes and installs need external-state verification first.

I wrote up the full evidence timeline, live containment sequence, UI states (accepted vs stopping vs idle), inbox behavior, restart semantics, and twelve repair gates here:
https://sandbaseai.github.io/deepseek-harness-handbook/stuck-tool-cancellation.html

The key source seams are packages/host/apiproxy/src/api-proxy.ts lines 2617–2633, packages/core/tools/README.md#cancellation, and the interrupted-turn recovery contract in packages/session/session-persistence/README.md.

[ningmengxr]

Thanks for the deep dive — this is exactly the kind of analysis the report needed. The correction on session.cancel semantics is important: { accepted: true } only means the agent signal was aborted, not that the tool/process tree reached quiescence. That reframes the problem precisely as a tool-layer cooperation issue rather than a queued cancel.

Agreed on the repair shape — signal forwarding, process-tree termination, pipe cleanup, and bounded settlement are the right gates. On my side, the plugin implements one slice of that: matching the stuck tool's command-line fingerprint and force-killing its child tree, which makes the tool call return immediately. It works, but it's clearly an external patch — the real fix belongs in the tool execution layer, as you outlined.

The cross-restart semantics you described (TOOL_NOT_STARTED / TOOL_OUTCOME_UNKNOWN, and only auto-retrying read-only or proven-idempotent work) also matches what we observed: after restart, a "continue" prompt can re-trigger waiting on a task that no longer exists in the new process. The "verify external state before retrying writes/installs" rule would have saved us exactly that second lockup.

Your handbook link is a great reference — I'll link it from the plugin README so others can trace the full discussion. Thanks again for taking the time.

🔗 Plugin: https://github.com/ningmengxr/dsh-task-control

[argszero]

denial123789 已经把这帖的两个层面（运行中锁死 + 跨重启二次锁死）讲得很透，我补充一个家族视角和一个恢复契约的精确机制确认。

1. 这是"工具工作不可被宿主抢占"家族的第 3 个报告。

• cordis_inspect_query client-platform queries hang forever when no page responds, freezing the agent #1607 / userQuestions: single global provider without timeout hangs non-web channels (WeChat/Telegram gateways) forever #2544（unbounded-wait 家族）：promise 永不 settle（监听器缺失时查询挂起）
• [bug] async 工具 execute() 内 spawnSync → 事件循环死锁（microtask checkpoint 内嵌套 uv_run 重入） #3477（spawnSync checkpoint 死锁）：工具同步阻塞在 microtask checkpoint → 嵌套 uv_run 重入 → 事件循环永久冻结（连 cancel 都收不到，比本贴更极端）
• [建议] 任务卡在下载/安装时无法停止：不可中断的工具使 cancel 无法生效（协作式契约无强制力） [Suggestion] Non-interruptible tools make cancel ineffective: the cooperative execute contract has no teeth #3400（本贴）：工具异步但不可中断（前台长下载/安装，不观察 exec.signal 或观察了但子进程不受控）→ cancel 被"排队在工具返回值后面"，会话冻结到工具结束

共同根因：packages/core/tools/src/index.ts:222-233 的 execute 契约是协作式——registry "cannot hard-kill same-process code"，工具必须自行观察 exec.signal 并让自有工作达到 quiescence。契约对不合作工具没有任何强制力：不观察 signal 的插件可以让会话无限期冻结。三层严重度递增：unbounded-wait（可收到 cancel，只是不响应）→ 不可中断工具（cancel 排队，等到超时）→ spawnSync 死锁（loop 冻结，cancel 无法送达）。

2. 第二层锁死（跨重启）的恢复契约机制——你的插件确实无法解决，且根因在 repair.ts 而非 resume。
rc.8 源码确认：冷恢复用 interruptedTurnClosers（core/session/src/repair.ts:27）合成 closers，工具调用被标为 TOOL_NOT_STARTED 或 TOOL_OUTCOME_UNKNOWN（repair.ts:13-16）。关键在 TOOL_OUTCOME_UNKNOWN 的恢复提示文本（repair.ts:104）——它明确告诉模型"结果未知，只在只读/幂等时重试，可能有副作用则先验证外部状态或询问用户"。也就是说：恢复契约已经在引导模型不要盲目重试，但它是提示文本而非强制——模型仍可能（如你观察到的）对空壳任务发起"恢复/继续"，然后陷入等待一个新进程里不存在的 promise。

3. 修复方向补充（在 denial123789 的 12 门之上）：

• 第二层的强制面：TOOL_OUTCOME_UNKNOWN 的恢复语义应从"提示文本"升级为结构化决策点——模型重试前必须显式选择（验证外部状态 / 询问用户 / 放弃），而不是默认重试。这与 [bug] async 工具 execute() 内 spawnSync → 事件循环死锁（microtask checkpoint 内嵌套 uv_run 重入） #3477 的"契约须让违规响亮"同理：提示文本靠不住时，把决策变成硬门。
• 第一层的工具层 kill 能力：你的插件（命令行指纹匹配强杀）是实用的应急方案，但官方应有 tools/execute 层的进程树终止 API（denial123789 提到 dsh-subprocess 树作用域终止契约已有——把它的能力暴露给工具层即可，而非宿主猜指纹）。
• cancel 状态可视化：denial123789 的 UI 状态区分（accepted vs stopping vs idle）是对的——用户看到 accepted 但工具仍在跑时，应显示"正在等待工具协作退出"而不是假死感。

家族闭环：#1607/#2544（unbounded-wait）+ #3477（spawnSync 死锁）+ #3400（不可中断工具）= 同一"协作式契约无强制力"根因的三个严重度档位。修复 = 契约禁止同步阻塞 + 工具层进程树终止 API + 恢复决策硬门 + 取消状态可视化。

[ningmengxr]

非常专业的分析，家族视角让我们对这个问题的理解上了一个台阶——"协作式工具契约无强制力"这个根因概括，比我们原帖的表述准确得多。我们决定采纳你的建议，并开始落地两处修改：

1. 提议侧（帖子）：把本帖升级为"工具不可抢占家族"的汇总请求——

• 引用 cordis_inspect_query client-platform queries hang forever when no page responds, freezing the agent #1607 / userQuestions: single global provider without timeout hangs non-web channels (WeChat/Telegram gateways) forever #2544（unbounded-wait）、[bug] async 工具 execute() 内 spawnSync → 事件循环死锁（microtask checkpoint 内嵌套 uv_run 重入） #3477（spawnSync 死锁）与本帖组成完整家族谱系；
• 明确向官方提出两条 API 诉求：① tools/execute 层暴露进程树终止能力（dsh-subprocess 树作用域终止契约已存在，暴露到工具层即可）；② TOOL_OUTCOME_UNKNOWN 的恢复语义从提示文本升级为结构化决策点（验证外部状态 / 询问用户 / 放弃）；
• 附上你指出的精确源码位置（core/tools/src/index.ts:222-233、repair.ts:27/104）与严重度分层。

2. 插件侧：把你在第三点里建议的"决策点"和"状态可视化"落到插件实现上——

• 急停后展示真实的 stopping 状态（accepted / stopping / idle 三态），而不是假称"已立即停止"；
• 恢复被中断的工具时，先查会话日志确认结果，若为 TOOL_OUTCOME_UNKNOWN 则弹出结构化选择（验证外部状态 / 重跑 / 跳过）——正是你说的"把决策变成硬门"在插件层的实现。

希望这两处落地后，能让官方看到这个家族问题值得一次系统性的修复。再次感谢你的分析。

---

🌟 不情之请：如果觉得这个插件还算有点用，欢迎顺手点个 star 嘿嘿（不想点也完全没问题！）

[ningmengxr]

@argszero 关于「TOOL_OUTCOME_UNKNOWN 结构化决策点」想在插件侧落地时请教三个技术问题：

1. 决策状态写回哪一层：用户做出 verify/rerun/skip 选择后，这个决策结果应该写回哪里？作为会话事件的话会碰到你说的 Route A 问题（自定义事件导致会话无法加载）；放插件独立状态文件的话，官方将来若采纳此建议，两边状态会分叉。插件侧现阶段的最佳落点是什么？

2. 插件层"硬门"能做到什么程度：在无法改 repair.ts 的前提下，我们现在的实现是——急停中断的工具结果未知时，强制弹窗让用户三选一（验证外部状态/重跑/跳过），选完注入定向指令（如"只重跑工具 X"）。这算不算"决策硬门"的插件等价物？还是说缺少某个关键环节（比如决策结果应该反馈给模型做二次确认）？

3. 与官方未来修复的兼容性：如果 DSH 采纳建议把 TOOL_OUTCOME_UNKNOWN 升级为结构化决策点，插件侧的这套实现应该设计成"直接退役"（交给官方），还是保留为"自定义策略层"（用户可配置默认行为）？从你的视角哪个更合理？

另外顺带确认：你提到的"验证外部状态"在插件层可以怎么给用户可操作的入口？我们现在只是注入一条"请先检查文件/进程/日志"的指令让 agent 去查，是否够，还是应该有更结构化的验证流程？

谢谢！