[Analysis] Subagent cancellation & session persistence: root-cause analysis with source references, and a proposed fix path (marked-dispose + persistence tolerance)

[yamingmou]

Related bug report

This analysis is the technical companion to: [Bug] Cancelling a task that spawned subagents permanently corrupts session persistence — #3662

---

EN / English

Purpose

This is a technical analysis companion to the bug report "Cancelling a task that spawned subagents permanently corrupts session persistence" ([#3662](#3662)). We studied the engine source (rc.6/rc.7, cross-checked against the latest 0.1.1-rc.2) to locate the root cause precisely and to propose a fix path that respects the existing architecture. We are sharing it openly in case it helps the maintainers.

Version note / 版本说明

This analysis cites symbols rather than line numbers; all of them were re-verified on 0.1.1-rc.2 and remain present with the same semantics: notifySettlement / child-first disposal / ctx.on("agent/disposed") in dsh-subagent, foldSurface() in the persistence layer, and SessionLogScanner.

Root-cause analysis (with source references)

1. "Background agent keeps running" is an explicit design, not a gap.

The subagent-control tool description states cancellation semantics verbatim:

"Request cancellation of a background agent's current turn by its agent id... Only the current turn stops: messages already queued for the agent stay parked until a later send_message, agents it started keep running, and the agent itself stays available for follow-ups."

So when a parent session is cancelled, the engine intentionally leaves child agents running. That is the background-agent model.

2. The engine already owns a clean child-close path — it is just not invoked on parent cancel.

In @deepseek-ai/dsh-subagent (lib/index.js), the continuable-subagent manager documents "child-first disposal, and settlement delivery to the parent", and states that ending child residency is the manager's job alone (notifySettlement). There is a full vocabulary for closing a child (subagent/descriptor, settlement summary, subagent/end), and a ctx.on("agent/disposed") hook exists to clean up closing scopes.

3. Where the corruption actually comes from.

When the parent is cancelled, the parent log gains turn/end reason=aborted + session/end-seed, but:

• child sessions are not closed (no turn/end / settlement written), leaving unclosed turn/start / step/start and tool/call with no tool/result;
• if the child later tries to write back to the parent (or the parent session is re-opened and re-written), the parent log's seq counter has moved on while the file was truncated/repaired — the two no longer agree, and the persistence layer rejects the log.

The failure is a missing link between "parent cancelled" and "children disposed" — the architecture has the pieces, but no trigger wires them together on the cancel path.

Proposed fix path (respecting the background-agent design)

We propose a combination of "marked dispose" (not force-kill) + persistence tolerance:

A′. Marked dispose on parent cancel (behavior-preserving)

• When a parent is cancelled, do not kill child agents (preserve the background-agent contract).
• Instead, mark the child as disposed in its durable descriptor and write closure events (turn/end reason=disposed, synthetic tool/result reason=aborted for unmatched calls) — i.e. invoke the existing child-first disposal + settlement machinery that already exists.
• The child finishes its current turn naturally; anything after the marker is refused at admission, so the child log never accumulates unclosed state.

B. Persistence-layer tolerance (recovery of already-corrupted logs)

• Beyond foldSurface(), add an inbox/subagent consistency pass: on load, detect unclosed turn/start / step/start and orphaned removedCount, and synthesize the missing closure events instead of rejecting the whole log.
• This mirrors how rc.7 handled max-tokens truncation: one decision point that decides "which chunks to drop" and "which closure events to synthesize" together.

This combination: A′ fixes the live path (cancellation no longer creates corruption), B fixes the historical path (logs already damaged become loadable again).

Our recovery tooling (offered)

We have built and battle-tested frame-accurate recovery tooling over several real incidents (multi-frame zstd session logs):

• frame-level first-header validation,
• strict seq contiguity scan (mirroring SessionLogScanner),
• content audit (spliced pairing / turn-step pairing / tool pairing / time monotonicity),
• surgical truncation at the last completed turn/end,
• orphan removedCount repair.

We are happy to contribute this as a dsh doctor / recovery utility if the maintainers are interested.

Environment

• Engine: @deepseek-ai/dsh 0.1.0-rc.7 / 0.1.1-rc.2 (verified on both)

Questions for maintainers

1. Is the "background child keeps running on parent cancel" behavior intentional and to be preserved?
2. Would the marked-dispose (A′) approach fit the existing notifySettlement / child-first-disposal design?
3. Is persistence-level closure synthesis (B) on the roadmap, similar to the max-tokens truncation handling in rc.7?

---

中文版 / ZH

关联的 bug 报告

本分析是下述 bug 报告的技术配套帖：[Bug] 取消启动过子 agent 的任务会永久损坏会话持久化 —— #3662

目的

这是对 bug 报告《取消启动过子 agent 的任务会永久损坏会话持久化》（[#3662](https://github.com/deepseek-ai/deepseek-harness/discussions/3662)）的**技术分析配套帖**。我们研读了引擎源码（rc.6/rc.7，并对照了最新的 0.1.1-rc.2）以精确定位根因，并提出尊重现有架构的修复路径，公开分享以供维护者参考。

版本说明

本分析引用的是符号而非行号；全部在 0.1.1-rc.2 上重新验证，仍然存在且语义一致：dsh-subagent 中的 notifySettlement / child-first disposal / ctx.on("agent/disposed")，持久化层的 foldSurface()，以及 SessionLogScanner。

根因分析（附源码引用）

1. "子 agent 后台继续运行"是明确设计，不是缺口。

subagent-control 工具对取消语义的原文：

"请求按 agent id 取消后台 agent 的当前 turn…… 只有当前 turn 停止：已排队消息保留到后续 send_message，它启动的 agent 继续运行，agent 本身保持可后续使用。"

因此，父会话被取消时，引擎有意让子 agent 继续运行——这就是"后台 agent"模型。

2. 引擎已拥有干净的子关闭链路——只是父取消时没有调用它。

在 @deepseek-ai/dsh-subagent（lib/index.js）中，continuable-subagent 管理器明确写着 "child-first disposal（子先关闭），以及结算送达父会话"，并声明结束子会话驻留是该管理器独有的职责（notifySettlement）。关闭子会话的完整词汇已存在（subagent/descriptor、结算摘要、subagent/end），且有 ctx.on("agent/disposed") 钩子用于清理 closing scopes。

3. 损坏的真正来源。

父会话被取消时，父日志获得 turn/end reason=aborted + session/end-seed，但：

• 子会话没有被关闭（没有 turn/end/结算写入），留下未闭合的 turn/start / step/start 和无对应 tool/result 的 tool/call；
• 如果子会话稍后尝试写回父会话（或父会话被重新打开并重写），父日志的 seq 计数器已前移、而文件曾被截断/修复——两者不再一致，持久化层拒绝该日志。

失败点在于 "父取消"与"子 disposed"之间缺少链接——架构里零件齐全，但取消路径上没有把它们串起来的触发器。

建议修复路径（尊重后台 agent 设计）

我们建议 "标记式 dispose（非强杀）+ 持久化容错" 的组合：

A′. 父取消时标记式 dispose（保持行为不变）

• 父被取消时不杀掉子 agent（保留后台 agent 契约）。
• 而是在子会话的持久化 descriptor 中将其标记为 disposed，并写入闭合事件（turn/end reason=disposed、为未匹配调用补写合成 tool/result reason=aborted）——即调用已存在的 child-first disposal + settlement 机制。
• 子会话自然完成当前 turn；之后任何写入在准入阶段被拒绝，子日志永不积累未闭合状态。

B. 持久化层容错（恢复已损坏日志）

• 在 foldSurface() 之外增加 inbox/subagent 一致性检查：加载时检测未闭合的 turn/start / step/start 与孤儿 removedCount，合成缺失的闭合事件，而不是拒绝整份日志。
• 这与 rc.7 处理 max-tokens 截断的思路一致：在一个决策点同时决定"丢弃哪些块"与"补写哪些闭合事件"。

此组合：A′ 修复实时路径（取消不再产生损坏），B 修复历史路径（已损坏日志重新可加载）。

我们的恢复工具（愿意贡献）

我们已构建并在多次真实事故中实战验证了帧级恢复工具（多帧 zstd 会话日志）：

• 首帧 header 校验；
• 严格 seq 连续性扫描（复刻 SessionLogScanner）；
• 内容审计（spliced 配对 / turn-step 配对 / tool 配对 / 时间单调）；
• 在最后一个 completed 的 turn/end 处手术式截断；
• 孤儿 removedCount 修复。

如果维护者感兴趣，我们愿意将其贡献为 dsh doctor / 恢复工具。

环境

• 引擎：@deepseek-ai/dsh 0.1.0-rc.7 / 0.1.1-rc.2（均在两者上验证）

向维护者提出的问题

1. "父取消时后台子 agent 继续运行"是否有意为之、需要保留？
2. 标记式 dispose（A′）是否符合现有 notifySettlement / child-first-disposal 设计？
3. 持久化层闭合事件合成（B）是否在路线图上，类似 rc.7 的 max-tokens 截断处理？

---

署名 / About this report

EN: Reported by the OfferKuai (Offer快) Team — an AI startup building full-lifecycle job-application services, guided by the belief that "users need results, not repeated conversations." Founder: Zhaofeng (Yaming). We use DeepSeek Harness as part of our daily development workflow; this report is our way of contributing back to the ecosystem. Website: https://www.offerkuai.com/ | Contact: <contact@offerkuai.com>

ZH: 本报告由 OfferKuai（Offer快）团队提交 —— 一家专注 AI 全流程求职托管的创业团队，核心理念是「用户要的是结果，不是重复对话」。创始人：Zhaofeng（Yaming）。我们将 DeepSeek Harness 用于日常开发工作流，这份报告是我们对社区的回馈。官网：https://www.offerkuai.com/ | 联系：<contact@offerkuai.com>

[yamingmou]

在 rc.2 重验存在且语义一致