[Architecture] Lifecycle handoff contract is missing — parent agent disposes, child agents are orphaned (production-constant, not an edge case)

[yamingmou]

---

Context — community convergence + upstream status (read this first)

Several of us have independently been converging on the same pattern from different angles: a weak cross-module lifecycle contract. On #4793, Jstn-1g reproduced it against 0.1.2-alpha.1 and shipped a reference fix (cleanup bound to the parent Agent's own scope; 146 tests green). argszero confirmed the dispose half is real and framed it as the dispose-side of that weak-contract family. weijiafu14 / liyangbing / nokkies surfaced the same shape from the MCP-runtime and preset-mount angles.

Upstream status that matters: the option half of #4666 was natively fixed in 0.1.2-alpha.1, but the dispose half is still NOT merged into the main branch — only the community reference implementation exists. So this is not re-reporting a bug; it lifts the pattern to the architecture layer and gives the convergence view, then points at the minimum-cost fix anchor.

TL;DR (30s to judge priority)

• Defect class: runtime lifecycle / ownership management.
• Severity: High — systemic resource leak + violates user mental model + silently swallows failures.
• One line: dsh-agent-loop and dsh-subagent both use factory/fiber-level ownership; neither binds a child agent's lifecycle to its parent's dispose. Result: parent exits → child stays; orphan never released; handoff info lost; crash silently dies. The design assumes the ideal exit path; production-normal exits (crash / abort / parent-exits-first / child-hung) have no handoff contract.
• Impact:
  • Business: long delegation chains lose downstream settlement notifications permanently → user goes deaf, thinks the task is still running.
  • Technical: long-running service + high concurrency → activations grows monotonically (OOM risk); drain / drainDescendants degrade to O(n); scheduler fault → dangling tool_calls → model 400 hard-hang.
• Reproducible: hard fact — scope binding / drain call sites / watchSettlement logic all have direct source evidence (@deepseek-ai/dsh@0.1.1-rc.2).

The contract is 4 links, each broken

Link	Should	Actual	Gap
① ownership	child owned by parent scope; parent dispose → cascade	child bound to agents service fiber scope	parent exit ≠ child exit
② cascade	parent dispose auto drainChildren	drainChildren/drainDescendants are explicit APIs, no auto hook	never triggered on normal exit
③ hung cleanup	hung child times out / force-reclaimed	watchSettlement waits on whenIdle(); hung never settles	orphan lives forever
④ settlement delivery	child settlement reliably reaches parent	parent gone → notifySettlement silently returns	handoff info lost

Root cause is not a single line — it is ownership层级选错 + 清理靠显式调用 + 挂起靠自管 + 交付靠乐观存在 stacked together. Notably, dsh-jobs-local / dsh-schedule in the same repo bind cleanup correctly to agent.ctx.effect — so the authors do know how; dsh-subagent's continuation manager just architecturally skipped the cascade.

Evidence chain (per source line, versioned) → in follow-up 1. Fix direction (minimum-cost anchor = align dsh-subagent to the jobs/schedule agent.ctx.effect cascade) → in follow-up 2.

---

中文版 / ZH

背景 —— 社区印证 + 上游状态（先看这段）

我们几个人从不同角度独立收敛到了同一个模式：跨模块生命周期契约薄弱。在 #4793，Jstn-1g 用 0.1.2-alpha.1 复现并给出参考实现（cleanup 装到父 Agent 自身作用域，146 测试全绿）；argszero 确认 dispose 这一半是真实的，并把它定为那个弱契约家族的 dispose 侧；weijiafu14 / liyangbing / nokkies 从 MCP 运行时和 preset 挂载角度也点出了同一形态。

关键的上游状态：#4666 的 option 半已在 0.1.2-alpha.1 原生修复，但 dispose 半仍未合入主分支——目前只有社区参考实现。所以这不是重复报 bug，而是把模式升到架构层、给收敛视角，再指最小代价修复锚点。

TL;DR（30 秒判断优先级）

• 缺陷类别：运行时生命周期 / 所有权管理。
• 严重度：High —— 系统性资源泄漏 + 违背用户心智模型 + 故障静默化。
• 一句话：dsh-agent-loop 与 dsh-subagent 两层都用 factory/fiber 级所有权；没有任何一层把子 agent 生命周期绑定到父 dispose。结果：父退 → 子留；孤儿不释放；交接信息丢失；崩溃静默死。设计按理想退出路径；生产常态（崩溃 / abort / 父先退 / 子挂起）没有交接契约。
• 影响：
  • 业务层：长委托链下游结算通知永久丢失 → 用户失聪、以为任务还在跑。
  • 技术层：常驻服务 + 高并发 → activations 单调增长（OOM 风险）；drain/drainDescendants 退化为 O(n)；调度异常 → 悬挂 tool_calls → 模型 400 永久卡死。
• 可复现：硬事实 —— scope 绑定 / drain 调用点 / watchSettlement 逻辑均有源码直接证据（@deepseek-ai/dsh@0.1.1-rc.2）。

契约是 4 个环节，每一环都断

环节	应有	实际	缺口
① 所有权	子归父 scope，父 dispose 级联	子绑到 agents 服务 fiber scope	父退 ≠ 子退
② 级联	父 dispose 自动 drainChildren	drainChildren/drainDescendants 是显式 API，无自动 hook	日常退出不触发
③ 挂起清理	挂起子超时/强制回收	watchSettlement 等 whenIdle()，挂起永不 settle	孤儿永久常驻
④ 结算交付	子结算可靠送达父	父不在 notifySettlement 静默 return	交接信息丢失

根因不是某一行——是「ownership 层级选错 + 清理靠显式调用 + 挂起靠自管 + 交付靠乐观存在」四者叠加。值得指出的是：同仓库的 dsh-jobs-local / dsh-schedule 都把清理正确绑定到 agent.ctx.effect——说明作者会做清理，dsh-subagent 的 continuation manager 只是在架构上漏做了级联。

证据链（按源码行号、带版本）→ 跟帖1。修复方向（最小代价锚点 = 把 dsh-subagent 对齐到 jobs/schedule 的 agent.ctx.effect 级联）→ 跟帖2。

[denial123789]

This lifecycle-handoff proposal is a useful operator-level boundary to document alongside the implementation discussion. The handbook has a source-backed subagent strategy guide covering ownership, continuations, cancellation, and settlement handoff, plus the agent runtime map for tracing where those contracts cross model, tool, Session, and safety layers. It is community-maintained and tracks the upstream project; current release: v0.5.265.

[denial123789]

Follow-up: the Agent lifecycle guide now captures the parent-dispose / child-handoff contract from this report, including bounded hung-child reclamation and durable settlement disposition. It is published in v0.5.289: https://github.com/sandbaseai/deepseek-harness-handbook/releases/tag/v0.5.289

[yamingmou]

Operator-level boundary — I agree with the framing. We'd still rather treat it as a missing contract than as docs that need writing.

The two things you pulled into the lifecycle guide are the two that actually carry the weight: bounded hung-child reclamation, and durable settlement disposition. They're also what follow-up 1's evidence chain is built around — watchSettlement never advances while a continuable child sits hung (rc.2 dsh-subagent/lib/index.js:1383-1407), and notifySettlement drops the settlement silently once the parent is already gone (:1488-1523). So the guide picked up the right ends of it.

One status note, since the guide now references this report: the option / inheritance half is a separate story and it's already fixed natively in 0.1.2-alpha.1 (argszero verified it against the current tree in #4666). The dispose half is still not merged upstream — only Jstn-1g's reference implementation exists (146 tests passing), nothing in main. That unmerged half is what #4909 is actually about, so it's worth keeping the two halves visibly distinct on the handbook side; otherwise the entry reads as more settled than it is.

Follow-up 1 will carry the rc.2 line numbers, follow-up 2 the fix direction. They should be usable when you re-baseline.

---

Operator 级边界——这个定位我认同。不过我们更想把它当一个缺失的契约，而不只是要补的文档。

你收进 lifecycle guide 的那两点，正是最有分量的两点：有界的挂起子回收、持久化的结算处置。这也正是跟帖1 证据链围绕的东西——watchSettlement 在可续传子 agent 挂起时永不推进（rc.2 dsh-subagent/lib/index.js:1383-1407），notifySettlement 在父已经没了时静默丢掉结算（:1488-1523）。所以你抓的是对的那一头。

既然 guide 现在引了这篇，标个现状：option / inheritance 这一半是另一回事，已经在 0.1.2-alpha.1 原生修好了（argszero 在 #4666 对当前树核过）。dispose 这一半还没合入上游——目前只有 Jstn-1g 的参考实现（146 测试全过），没进主线。这半边才是 #4909 真正的题面，所以 handbook 那边值得把两半的区别标出来；不标的话，条目读起来会比实际情况更「已解决」。

跟帖1 会带 rc.2 行号，跟帖2 给修复方向。你 re-baseline 时应该能直接用上。

[yamingmou]

Follow-up 1 — Evidence chain (per source line, @deepseek-ai/dsh@0.1.1-rc.2)

Note: SandBase handbook's lifecycle guide (v0.5.289) already captures this pattern from this thread (#4909). The evidence chain below is rc.2 line-number-level, meant for re-baselining — not a restatement of the handbook entry.

2.1 Root cause: ownership level mismatch (parent exits, child stays)

• dsh-agent-loop/lib/index.js:1022-1023 — prepare() registers teardown to factory ownership (module scope), not the caller (parent agent) scope. Parent exit does not trigger it.
• dsh-subagent/lib/index.js:2395-2405 — SubagentContinuationManager binds to the agents service fiber scope via ctx.inject(["agents"], ...); the constructor :743-755 ctx.effect(... yield () => this.drain()) only fires drain() on the agents fiber dispose.
• :1014-1044 / :1055-1066 — drainDescendants / drainChildren are public explicit methods, no auto hook on parent dispose; :997-1004 drain() (full) also only via effect on fiber unload.
• Conclusion: single agent exit ≠ agents fiber exit → drain() not triggered → the parent's child Activation is never reclaimed.

2.2 Most stubborn orphan form: hung, never released

• :1304-1309 acquireOwnership(parent, childId): if (this.activations.get(parent.id) === void 0) return; — a top-level (non-continuable) agent's children are not registered to ownedChildren → normal exit doesn't trigger, and:
• :1383-1407 watchSettlement: while (disposal === void 0) { await Promise.race([agent.whenIdle(), poke]); if (stateOf(activation) !== "settled") continue; }. stateOf (:1132-1136) returns waiting while accepted.size>0 or ownedChildren.size>0. A continuable child in "waiting for parent message / external report" makes whenIdle() never resolve → infinite loop → never dispose.
• Conclusion: it is not that dispose is unt triggered — watchSettlement's self-managed logic never advances in the hung state. After the parent crashes, the child keeps waiting for a parent message that will never come.

2.3 Handoff info lost: parent exits first → child settlement silently dropped

• :1488-1523 notifySettlement: if (!activation.announced) return; ... const parent = this.ctx.agents.get(activation.parentSession); if (parent === void 0) return; — parent already disposed → parent undefined → silent return (no error, no retry, no durable record).
• Comment :1482-1484 assumes the child Session is a durable record, but there is no replay / no backlog to re-send lost notifications on parent recovery.
• Conclusion: any layer of a long delegation chain exiting first → all downstream child settlements are lost; the upper layer goes completely deaf.

2.4 Fault silentization (makes the defect harder to spot)

• dsh-agent-loop/lib/index.js:252-256 — runGroup's scheduler-failure catch path does not call appendSkippedToolCall to fill the skipped tool result (the abort path :257-263 does) → dispatched-but-uncommitted tool_calls hang → model receives non-contiguous tool_calls → API 400 hard-hang (root cause of 工具调用失败留下悬挂 tool_calls,会话被 400 INVALID_REQUEST 永久卡死 #4017).
• :480 kick's catch (_error) {} silently swallows all errors → agent dies silently, monitoring goes blind.

2.5 Unbounded container (scale amplifier)

• :728 activations = new Map() — module-level, shared across all sessions, only grows (:1464 delete only at the success tail of finishDisposal); :700 tails, :740 closingScopes same.
• :699-715 ChildLock.tails grows with childId count, no eviction.
• Conclusion: orphans accumulate → activations monotonic growth (OOM risk); drain() (:1001) / drainDescendants (:1019) iterate the full activations map → O(n) degradation.

---

跟帖1 — 证据链（按源码行号，@deepseek-ai/dsh@0.1.1-rc.2）

注：SandBase handbook 的 lifecycle guide（v0.5.289）已从本帖 #4909 收录此模式。下面的证据链是 rc.2 行号级，用于 re-baseline——不是复述 handbook 条目。

2.1 根因：ownership 层级错配（父退子留）

• dsh-agent-loop/lib/index.js:1022-1023 —— prepare() 把 teardown 注册到 factory ownership（模块级 scope），而非调用方（父 agent）scope。父 agent 退出不会触发该 effect。
• dsh-subagent/lib/index.js:2395-2405 —— SubagentContinuationManager 通过 ctx.inject(["agents"], ...) 绑定到 agents 服务 fiber scope；:743-755 构造函数里 ctx.effect(... yield () => this.drain()) 的 drain() 只在 agents 服务 fiber dispose 时触发。
• :1014-1044 / :1055-1066 —— drainDescendants / drainChildren 是 public 显式方法，父 agent dispose 时无自动 hook 调用；:997-1004 drain()（全量）也只在 fiber 卸载时由 effect 调。
• 结论：单个 agent 退出 ≠ agents 服务 fiber 退出 → drain() 不触发 → 该父的子 Activation 永不回收。

2.2 孤儿最顽固形态：挂起永不释放

• :1304-1309 acquireOwnership(parent, childId)：if (this.activations.get(parent.id) === void 0) return; —— 顶层 agent（非 continuable）创建的子不登记到 ownedChildren → 日常退出不触发。
• :1383-1407 watchSettlement：while (disposal === void 0) { await Promise.race([agent.whenIdle(), poke]); if (stateOf(activation) !== "settled") continue; }。stateOf（:1132-1136）在 accepted.size>0 或 ownedChildren.size>0 时判为 waiting。continuable 子进入"等父消息/外部 report"态时 whenIdle() 不 resolve → 无限循环 → 永不 dispose。
• 结论：不是 dispose 没被触发，而是 watchSettlement 自管逻辑在挂起态下永不前进。父崩溃后子还在等"永远不会来的父消息"。

2.3 交接信息丢失：父先退 → 子结算静默丢

• :1488-1523 notifySettlement：if (!activation.announced) return; ... const parent = this.ctx.agents.get(activation.parentSession); if (parent === void 0) return; —— 父已 dispose → parent undefined → 直接 return（不报错、不重试、不记 durable）。
• 注释 :1482-1484 明示设计依赖"子的 Session 是 durable record"，但无重放 / 无 backlog 在父恢复时补发丢失通知。
• 结论：长委托链任一层先退 → 下游所有子的结算都丢，上层完全失聪。

2.4 故障静默化（让缺陷更难发现）

• dsh-agent-loop/lib/index.js:252-256 —— runGroup 的 scheduler-failure catch 路径不调 appendSkippedToolCall 补 skipped tool result（abort 路径 :257-263 却补）→ 已派发未提交的 tool_calls 悬挂 → 模型收到非连续 tool_calls → API 400 永久卡死（工具调用失败留下悬挂 tool_calls,会话被 400 INVALID_REQUEST 永久卡死 #4017 根因）。
• :480 kick 的 catch (_error) {} 静默吞掉所有错误 → agent 静默死，监控失明。

2.5 容器无上限（规模放大）

• :728 activations = new Map() 模块级、跨所有 session 共享、只增不删（:1464 delete 仅在 finishDisposal 成功末段）；:700 tails、:740 closingScopes 同理。
• :699-715 ChildLock.tails 随 childId 数增长，无驱逐。
• 结论：孤儿累积 → activations 单调增长（OOM 风险）；drain()（:1001）/ drainDescendants（:1019）全量遍历 → O(n) 退化。

[yamingmou]

---

Follow-up 2 — Fix direction (minimum-cost anchor)

The correct pattern already exists in-repo (the authors know how):

• dsh-jobs-local/lib/index.js:394-405 ensureOwnerCleanup → owner.ctx.effect(...) → disposeOwned (cancel + await + delete). Sharp contrast with subagent.
• dsh-schedule/lib/index.js:1359 agent.ctx.effect(...) correctly cascades runtime.dispose() + runtimes.delete(agent); :747 clearTimeout closes the timer.
• dsh-mcp-client/lib/index.js:678 dispose closes connection + clears timer + releases serverName, and the timer unref() doesn't keep alive.

→ The fix is not "rewrite lifecycle management." It is to align dsh-subagent's continuation manager to the agent.ctx.effect cascade that jobs/schedule already prove works — minimum cost, highest confidence.

Fix direction (direction only, no implementation):

Gap	Direction	Difficulty
E1 ownership level	manager follows parent agent scope (or parent dispose explicitly triggers child cascade)	Medium
E2 no auto drain	parent agent scope dispose → auto drainChildren	Low (align jobs pattern)
E3/E4 hung not released	watchSettlement add timeout / force-reclaim; hung state must not block dispose	Medium
E5 settlement lost	settlement notification durable / backlog replay on parent recovery	Medium
L1 hung tool_calls	failure path add appendSkippedToolCall (align abort path)	Low (one-liner, can be a standalone issue)
L2 silent swallow	kick catch at least log + report	Low
E7/E8 unbounded container	activations / tails capacity cap + eviction + per-session isolation	Medium

Priority suggestion: L1 (#4017, one-liner, direct availability hit) > E2 (align jobs pattern, eliminates the default orphan) > E1 (root cause) > E5 / E3 / E4 (settlement & hung) > E7 (scale cap).

Note: the dispose half of this family is still not merged upstream — only Jstn-1g's community reference implementation exists (146 tests green against 0.1.2-alpha.1). The cheapest first move is L1 + E2, both low-difficulty and independently shippable.

---

跟帖2 — 修复方向（最小代价锚点）

正确模式同仓库已存在（作者会做）：

• dsh-jobs-local/lib/index.js:394-405 ensureOwnerCleanup → owner.ctx.effect(...) → disposeOwned（cancel + await + delete）。与 subagent 形成尖锐反差。
• dsh-schedule/lib/index.js:1359 agent.ctx.effect(...) 正确级联 runtime.dispose() + runtimes.delete(agent)；:747 clearTimeout 关 timer。
• dsh-mcp-client/lib/index.js:678 dispose 关连接 + 清 timer + 释放 serverName，且 timer unref() 不保活。

→ 修复方向不是"重写全生命周期管理"，而是把 dsh-subagent 的 continuation manager 对齐到 jobs/schedule 已验证的 agent.ctx.effect 级联模式——最小代价、最高置信。

修复方向（仅方向，不写具体实现）：

缺口	方向	难度
E1 ownership 层级	manager 改为跟随父 agent scope（或父 dispose 显式触发子级联）	中
E2 无自动 drain	父 agent scope dispose → 自动 drainChildren	低（对齐 jobs 模式）
E3/E4 挂起不释放	watchSettlement 增加超时 / 强制回收；挂起态不阻塞 dispose	中
E5 结算丢失	结算通知 durable 化 / 父恢复时 backlog 重放	中
L1 悬挂 tool_calls	failure 路径补 appendSkippedToolCall（对齐 abort 路径）	低（一行级，可单独提 issue）
L2 静默吞错	kick catch 至少 log + 上报	低
E7/E8 容器无上限	activations / tails 加容量上限 + 驱逐 + per-session 隔离	中

优先级建议：L1（#4017，一行级、直接可用性硬伤）> E2（对齐 jobs 模式，消除默认孤儿）> E1（根因）> E5 / E3 / E4（结算与挂起）> E7（规模封顶）。

补充：该弱契约家族的 dispose 半仍未合入上游——目前只有 Jstn-1g 的社区参考实现（0.1.2-alpha.1 下 146 测试全绿）。最便宜的第一步是 L1 + E2，两者都是低难度、可独立交付。

[yamingmou]

EN / English

Worth pulling in #4989 here — it's the same "unbounded container" pattern hitting a different module in production.

HiSeax reports that session_projcache.json (global single-document rewrite, no eviction) grew to 64.6 MB on rc.2, blocking the event loop for 30–120s on every turn/end checkpoint write. The watchdog killed the server 8 times in one night, each kill losing in-flight tool calls. The per-record layout fix in alpha.1 addresses the giant-file rewrite, but the cache itself is still unbounded — records accumulate forever.

That's the same structural gap as the activations / tails growth documented in #4909's evidence chain (section 2.5), just in dsh-session-projection-cache instead of dsh-subagent. Two modules, same missing eviction contract, both hitting production.

---

中文版 / ZH

值得把 #4989 拉进来——是同一个「无界容器」模式，打在不同模块上，已经进了生产环境。

HiSeax 报告 session_projcache.json（全局单文档重写、无驱逐）在 rc.2 上膨胀到 64.6 MB，每次 turn/end 写入阻塞事件循环 30-120s。watchdog 一晚上杀了 8 次服务器，每次丢失 in-flight tool calls。alpha.1 的 per-record layout 修了 giant-file rewrite，但缓存本身仍然无界——记录永远累积。

这就是 #4909 证据链 2.5 节文档化的 activations / tails 增长的同一结构缺口，只是打在 dsh-session-projection-cache 而非 dsh-subagent 上。两个模块，同一个缺失的驱逐契约，都进了生产。