Merge retargeted parent into Claude Code subagent provider

2026-08-06 21:38:47 +08:00
parent f09986a02b 0748ebee39
commit 4b1528bcec
2613 changed files with 56218 additions and 27543 deletions
--- a/packages/subagent/subagent/README.i18n.yaml
+++ b/packages/subagent/subagent/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/subagent/subagent/README.md
-README.md: a388f5a57fd32768dc9b66e3637ff53bf6479149
-README.zh.md: 48e5694e82ee0269661fbb5ede75cf995cbc00aa
+README.md: 08b6175e018db072b99490a25b8df887bb89eb47
+README.zh.md: 435be7660b3f004a1f0bcb59a8d9a74ac8e8aae3
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -4,24 +4,7 @@ English | [中文](README.zh.md)

 The subagent seam lets one agent delegate work to a child through a named provider. Callers use one service API (`ctx.subagents`); providers decide whether the child runs in this process, in another process, or through a future transport.

-## Package roles
-
-The family separates the stable interface from implementations and model-facing tools:
-
-| Package | Role |
-|---|---|
-| `@deepseek-ai/dsh-subagent` | Provider registry, request/result/descriptor types, lifecycle events, and continuable-child orchestration. |
-| `@deepseek-ai/dsh-subagent-spawn` | Fresh in-process child; supports continuable children. |
-| `@deepseek-ai/dsh-subagent-fork` | In-process child seeded with completed parent turns; supports continuable children. |
-| `@deepseek-ai/dsh-subagent-acp` | Fresh out-of-process ACP child (one-shot). |
-| `@deepseek-ai/dsh-subagent-codex` | Fresh real Codex app-server child with one ephemeral thread and turn (one-shot). |
-| `@deepseek-ai/dsh-subagent-claude-code` | Fresh official Claude Agent SDK query with a real managed Claude Code CLI child (one-shot). |
-| `@deepseek-ai/dsh-subagent-dsh-sdk` | Fresh out-of-process harness child driven through the TypeScript SDK client (one-shot). |
-| `@deepseek-ai/dsh-tool-subagent` | Model-facing delegation tool over one configured provider. |
-| `@deepseek-ai/dsh-tool-subagent-control` | The globally named `send_message` follow-up tool. |
-| `@deepseek-ai/dsh-tool-subagent-report` | Child-scoped return channel to the direct parent. |
-
-Multiple providers may coexist under different names. This lets a deployment expose, for example, a cheap in-process child and an isolated ACP child without changing the service contract.
+The [subagent family overview](../README.md) maps implementations and model-facing consumers. This package owns the provider registry, shared request and result contracts, durable descriptors, and continuable-child orchestration. Multiple named providers may coexist behind that contract.

 ## Service API

--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -4,24 +4,7 @@

 subagent seam 允许一个 agent（智能体）通过具名提供方把工作委派给子 agent。调用方使用统一的服务 API（`ctx.subagents`）；提供方决定子 agent 在当前进程、另一进程还是未来的传输之上运行。

-## 包角色
-
-该能力族把稳定接口与实现、面向模型的工具分开：
-
-| 包 | 角色 |
-|---|---|
-| `@deepseek-ai/dsh-subagent` | 提供方注册表、请求／结果／描述符类型、生命周期事件和可继续子 agent 编排。 |
-| `@deepseek-ai/dsh-subagent-spawn` | 全新的进程内子 agent；支持可继续子 agent。 |
-| `@deepseek-ai/dsh-subagent-fork` | 以父 agent 已完成轮次作为初始内容的进程内子 agent；支持可继续子 agent。 |
-| `@deepseek-ai/dsh-subagent-acp` | 全新的进程外 ACP（Agent Client Protocol）子 agent（一次性）。 |
-| `@deepseek-ai/dsh-subagent-codex` | 全新的真实 Codex app-server 子 agent，包含一个临时 thread 和一个轮次（一次性）。 |
-| `@deepseek-ai/dsh-subagent-claude-code` | 通过官方 Claude Agent SDK 启动的全新 query，带有一个真实且受管的 Claude Code CLI 子进程（一次性）。 |
-| `@deepseek-ai/dsh-subagent-dsh-sdk` | 通过 TypeScript SDK 客户端驱动的全新进程外 harness 子 agent（一次性）。 |
-| `@deepseek-ai/dsh-tool-subagent` | 基于一个已配置提供方、面向模型的委派工具。 |
-| `@deepseek-ai/dsh-tool-subagent-control` | 全局具名 `send_message` 后续操作工具。 |
-| `@deepseek-ai/dsh-tool-subagent-report` | 子级作用域的返回通道，指向直接父级。 |
-
-多个提供方可以使用不同名称共存。因此，部署可以同时公开低成本的进程内子 agent 和隔离的 ACP 子 agent，而无需改变服务契约。
+[subagent 家族概述](../README.md)列出了实现和面向模型的消费方。本包负责提供方注册表、共享请求和结果契约、持久描述符以及可继续子级编排。多个具名提供方可以在该契约背后共存。

 ## 服务 API

@@ -29,7 +12,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委

 | 成员 | 含义 |
 |---|---|
-| `registerProvider(provider)` | 按名称注册一个可信的同进程实现。注册受 effect 作用域约束；移除注册会阻止新的启动，但不会撤销已返回给调用方的运行。重复名称会立即失败。 |
+| `registerProvider(provider)` | 按名称注册一个可信的同进程实现。注册受 effect 作用域约束；移除注册会阻止新的启动，但不会撤销已返回给调用方的运行。重复名称会明确报错。 |
 | `getProvider(name)` | 返回提供方；不存在时返回 `undefined`。 |
 | `list()` | 按插入顺序返回提供方名称。 |
 | `start(name, request)` | 校验普通调用方请求，解析其分离的 `one-shot` 描述符，然后等待提供方，直到真实的一次性子 agent 发布。兑现时返回由持有方拥有的 `SubagentRun`；拒绝表示提供方已清理所有未发布的启动资源，而发布后的轮次或基础设施故障会通过该 run 结算。可继续子 agent 绝不通过此操作进入。 |
@@ -40,7 +23,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
 | `listChildren(parentSessionId, signal?)` | 按稳定的追踪顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。要求会话查询；不要求 `ctx.agents` 或继续执行管理器。 |

-`SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose 子 agent。
+`SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。

 后续操作的权限来自子 agent 持久化 header 中记录的确切在线直接父级。冷恢复会在重建前检查该权限，并在最终无 await 的 inbox 准入区间再次检查，因此在物化期间被注销或替换的 parent 无法授权投递。后续操作上的 `source` 是保留在所投递消息上的持久化来源，不授予任何权限。

@@ -59,7 +42,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委

 ## 持久化描述符

-该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果契约）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。
+该 seam 拥有版本化的 `subagent/descriptor` 会话事件词汇（`src/descriptor.ts`）：`snapshotSubagentDescriptor()` 会在提供方工作之前校验并分离记录，`foldSubagentDescriptor()` 则会在从已加载子 agent 日志中恢复描述符之前，校验当前版本的完整 payload。每次由本地会话支撑的启动都会追加一个带有提供方名称与生命周期 `mode` 的描述符。`one-shot` 描述符可以携带调用方拥有的可选持久化显示 `label`；`continuable` 描述符要求其持久化创建标签，并另外记录已解析的子 agent `agentOptions.provider`／`model`，以及用于从持久化存储恢复的可选 `persona`／`toolFilter`。这些是显式字段，绝不是可通过合并扩展的 `AgentOptions` 对象，因此无关的扩展值不会破坏继续执行。描述符省略 `subagentDepth`（持久化 header 的 `delegationDepth` 是单调下界）和 `outputSchema`（单次 Activation 的结果契约）。该事件只进入日志：不含 `surfaceOp`，不进入模型历史，并由仅追加日志跨压缩（compaction）保留。格式错误的当前版本 payload 属于损坏；本运行时无法对不受支持的版本进行分类。

 ## 委派深度

@@ -77,9 +60,9 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委

 ## 可继续子 agent 与 Activation

-可继续子 agent 拥有一个持久化 Session 和至多一个进程内 **Activation**——即被重建的子 agent 的一个驻留时段，而不是请求、结果、取消或 Task 边界。Agent inbox 是唯一的轮次队列，因此继续执行管理器负责驻留，而 Agent 循环负责所有轮次排序与执行。任何可继续路径都不会创建 Task 或中间的承载结果的包装器。
+可继续子 agent 拥有一个持久化 Session 和至多一个进程内 **Activation**——即被重建的子 agent 的一个驻留时段，而不是请求、结果、取消或 Task 边界。Agent inbox 是唯一的轮次队列，因此继续执行管理器负责驻留，而 agent loop（智能体循环）负责所有轮次排序与执行。任何可继续路径都不会创建 Task 或中间的承载结果的包装层。

-管理器根据 Agent 停稳状态和所拥有子集推导三个内部驻留条件，而非维护第二个状态机：running（存在活跃准入、进行中的轮次或唤醒型 inbox 工作）、waiting（已停稳但仍拥有至少一个未 dispose 的子 agent）、settled（已停稳且所有拥有的子 agent 都已 dispose，因此管理器 dispose `AgentHandle` 并移除 Activation）。每条后续消息都使用 `Agent.followup()` 并成为一个 FIFO 轮次，且不会对当前轮次进行 steering（中途引导）。路由只取决于驻留状态：running 入队、waiting 唤醒同一 Agent，无 Activation 时则冷恢复一个新的。
+管理器根据 Agent 停稳状态和所拥有的子 agent 集合推导三个内部驻留条件，而非维护第二个状态机：running（存在活跃准入、进行中的轮次或唤醒型 inbox 工作）、waiting（已停稳但仍拥有至少一个未 dispose 的子 agent）、settled（已停稳且所有拥有的子 agent 都已 dispose，因此管理器 dispose `AgentHandle` 并移除 Activation）。每条后续消息都使用 `Agent.followup()` 并成为一个 FIFO 轮次，且不会对当前轮次进行 steering（中途引导）。路由只取决于驻留状态：running 入队、waiting 唤醒同一 Agent，无 Activation 时则冷恢复一个新的。

 管理器预留子 agent 身份、解析持久化描述符，通过私有的 activation-owner 作用域调用 `ctx.agents.create()`（冷恢复时为 `ctx.agents.resume()`），把返回的 `AgentHandle` 安装到 Activation 中，建立任何可继续父级所有权，然后提交提示词。冷恢复绝不通过提供方分发，因为持久化 Session 已持有初始前缀，折叠后的描述符即是全部重建输入。

@@ -87,17 +70,17 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委

 ## 生命周期事件

-服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不发出任何事件。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段是生命周期来源信息，而非提供方仍在注册的声明：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。
+服务会为每次一次性运行以及每个已驻留的可继续 Activation 时段发出一对 `subagent/start`/`subagent/end`，因此可继续子 agent 可用与一次性运行相同的词汇观察，且不会暴露管理器是物化、唤醒还是冷恢复了它们。对于一次性启动，它会在同步的 `subagent/start` 之前附加结果观察器，因此即使子 agent 已经结算，也仍会先产生 `subagent/start`，再产生 `subagent/end`；在驻留前失败的可继续时段不会发出这对生命周期事件中的任何一个。这对事件共享服务生成的 `runId`；`local` 标志取自提供方准确 `localAgent` 的快照（可继续子 agent 恒为 true），因此观察器绝不会从可复用的提供方/会话名称推断运行身份或本地性。`provider` 字段是生命周期来源信息，而非提供方仍在注册的声明：已接受的一次性 run 可在提供方移除后才结算，冷恢复时段也会保留描述符中的初始提供方名称，而不要求该提供方仍处于注册状态。

 运行事件受执行委派的父级作用域约束。每个监听器都独立隔离：同步抛出或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变运行。

 提供方新增和移除还会发出 `subagent/provider-added` 与 `subagent/provider-removed`。面向模型的工具等消费方使用这些事件，因为 Cordis 可能并发加载同级插件；配置顺序不能证明注册顺序。

-可继续子级不会创建 `SubagentRun` 或 Task。延续管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由准确的实时直接父级身份授权。上报则由准确的实时子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。
+可继续子级不会创建 `SubagentRun` 或 Task。继续执行管理器为每个驻留子 Session 直接拥有一个仅存在于当前进程的 Activation 和一个留存的 `AgentHandle`，使用 Agent inbox 作为唯一 FIFO，并从持久化描述符冷恢复。父到子投递由确切在线的直接父级身份授权。上报则由确切在线的子级身份授权；管理器根据持久化的 `parentSession` 推导接收方，`MessageSource` 仍只表示来源，不表示权限。

 当 `ctx.sessionProjections` 可用时，服务会注册 `subagentTiming`。该投影会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界。在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。

-`registerContinuableSetup()` 允许可选包添加子级作用域功能，而无需让延续管理器知道这些功能的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
+`registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。

 ## 收集模型

@@ -113,9 +96,9 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委

 不会直接使缓存失效；具名消费方共同负责请求前缀的任何变化。

-## 已知限制与延期工作
+## 已知限制与暂缓事项

- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，并按子 agent 声明继续执行功能，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
+- **ACP 子 agent 仍为一次性，且无法通过追踪枚举**：ACP 运行在 parent 会话语料中没有本地 child 会话。ACP 的 `prepareContinuable` 需要在提供方专用描述符数据中持久化远端会话 id，以及逐子 agent 的继续执行能力声明，因为 ACP 的 `loadSession` 支持按子 agent 协商，而不是通过方法是否存在来确定。远程提供方还需要一份独立的 Activation 所有权契约，具备等效的经认证控制和子先于父的停稳保证，才能支持可继续子 agent。
 - **无 host-user 继续执行**：`followup()` 要求确切在线直接父级。未来 host 适配器需要具体的经认证交互，才能让该 seam 获得单独的用户能力。
 - **不对当前轮次进行 steering**：可继续消息和唤醒式 report 会排入后续轮次，均不会重定向正在进行的轮次。
 - **驻留仅限进程内**：Activation inbox 与所有权图不会在两个 harness 进程之间协调；对单个持久化存储的并发访问仍然需要持久化邮箱和跨进程租约协议。
--- a/packages/subagent/subagent/package.json
+++ b/packages/subagent/subagent/package.json
@@ -26,9 +26,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/types/**/*.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "dependencies": {
--- a/packages/subagent/subagent/src/continuation.ts
+++ b/packages/subagent/subagent/src/continuation.ts
@@ -47,6 +47,8 @@ import type SubagentActivationSetupRegistry from './activation-setup-registry.ts
 /** Attribution for a model coordinator's follow-up to one of its children. */
 export interface CoordinatorMessageSource {
  readonly kind: 'coordinator'
+  /** A message another agent addressed to this one (`relay` context form). */
+  readonly form: 'relay'
  /** Session id of the agent whose tool call produced the follow-up. */
  readonly senderSessionId: SessionId
 }
@@ -54,6 +56,8 @@ export interface CoordinatorMessageSource {
 /** Durable attribution for a continuable child's explicit parent report. */
 export interface SubagentReportMessageSource {
  readonly kind: 'subagent-report'
+  /** A message another agent addressed to this one (`relay` context form). */
+  readonly form: 'relay'
  /** Session id of the reporting child. */
  readonly senderSessionId: SessionId
 }
@@ -283,7 +287,7 @@ export class SubagentContinuationManager {
    // child-first ordering.
    const scope = ctx.plugin(function activationOwner() {})
    this.ownerCtx = scope.ctx
-    ctx.on('agent/disposed', (agent) => {
+    ctx.on('agent/disposed', ({ agent }) => {
      this.closingScopes.delete(agent)
    })
    ctx.effect(function* (this: SubagentContinuationManager) {
@@ -481,6 +485,7 @@ export class SubagentContinuationManager {
      ],
      source: {
        kind: 'subagent-report' as const,
+        form: 'relay' as const,
        senderSessionId: activation.childId,
      },
    })
@@ -688,7 +693,7 @@ export class SubagentContinuationManager {
  }

  /**
-   * Cold-resume a persisted child: load and authorize its Session, fold the
+   * Cold-resume a persisted child: inspect and authorize its Session, fold the
   * generic descriptor, create the Activation through `ctx.agents.resume()`,
   * and submit the waiting turn. This never dispatches through a subagent
   * provider — the persisted Session already holds the initial prefix and the
@@ -701,13 +706,13 @@ export class SubagentContinuationManager {
    options: SubagentFollowupOptions,
  ): Promise<MessageId> {
    const persistence = this.requirePersistence()
-    let loaded: Awaited<ReturnType<typeof persistence.load>>
+    let loaded: Awaited<ReturnType<typeof persistence.inspect>>
    try {
-      loaded = await persistence.load(childId)
+      loaded = await persistence.inspect(childId, options.signal)
    } catch (error: unknown) {
+      options.signal.throwIfAborted()
      throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error })
    }
-    // The persistence seam takes no signal; recheck before any child work.
    options.signal.throwIfAborted()
    this.assertAdmitting(parent)
    // Authorize the persisted header before folding: only the durable child's
@@ -724,17 +729,24 @@ export class SubagentContinuationManager {
        'NOT_RESUMABLE',
      )
    }
-    const activation = await this.materialize({
-      childId,
-      provider: descriptor.provider,
-      parent,
-      agentOptions: {
-        ...descriptor.agentProvider !== undefined ? { provider: descriptor.agentProvider } : {},
-        ...descriptor.agentModel !== undefined ? { model: descriptor.agentModel } : {},
-      },
-      composition: { persona: descriptor.persona, toolFilter: descriptor.toolFilter },
-      signal: options.signal,
-    })
+    let activation: Activation
+    try {
+      activation = await this.materialize({
+        childId,
+        provider: descriptor.provider,
+        parent,
+        agentOptions: {
+          ...descriptor.agentProvider !== undefined ? { provider: descriptor.agentProvider } : {},
+          ...descriptor.agentModel !== undefined ? { model: descriptor.agentModel } : {},
+        },
+        composition: { persona: descriptor.persona, toolFilter: descriptor.toolFilter },
+        signal: options.signal,
+      })
+    } catch (error: unknown) {
+      options.signal.throwIfAborted()
+      if (error instanceof SubagentError) throw error
+      throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error })
+    }
    return this.submitMaterialized(activation, content, options.source, parent, options.signal)
  }

@@ -847,16 +859,13 @@ export class SubagentContinuationManager {
      // quiet Agent from one whose accepted turn has not been admitted yet.
      // Registered through the child's own scoped context, so scope filtering
      // already restricts both listeners to this exact agent.
-      handle.agent.ctx.on('agent/inbox/dequeue', (_agent, item) => {
-        /* v8 ignore next -- a dequeue of an id this manager never admitted needs
+      handle.agent.ctx.on('agent/inbox/claimed', ({ message }) => {
+        /* v8 ignore next -- a claim of an id this manager never admitted needs
         * another sender on the same child, which no current path allows. */
-        if (activation.accepted.delete(item.message.id)) this.wake(activation)
+        if (activation.accepted.delete(message.id)) this.wake(activation)
      })
-      handle.agent.ctx.on('agent/inbox/discard', (_agent, items) => {
-        // Deleting every id in the batch is unconditional; waking once afterwards
-        // costs nothing and avoids branching on which ids this manager admitted.
-        for (const item of items) activation.accepted.delete(item.message.id)
-        this.wake(activation)
+      handle.agent.ctx.on('agent/inbox/discarded', ({ message }) => {
+        if (activation.accepted.delete(message.id)) this.wake(activation)
      })
      // Agent creation committed setup at its publication boundary;
      // revocations from here on are immediate live revocation.
--- a/packages/subagent/subagent/src/descriptor-seed.ts
+++ b/packages/subagent/subagent/src/descriptor-seed.ts
@@ -25,7 +25,7 @@ export function seedDescriptorTurn(
  seed: readonly SessionEvent[] | undefined,
  descriptor: SubagentDescriptorData,
 ): SessionEvent[] {
-  const staged = new Session(childId, seed)
+  const staged = Session.create(childId, seed)
  staged.append('subagent/descriptor', descriptor)
  return [...staged.events]
 }
--- a/packages/subagent/subagent/src/lifecycle.ts
+++ b/packages/subagent/subagent/src/lifecycle.ts
@@ -207,7 +207,6 @@ function epochStopReason(events: readonly SessionEvent[]): SubagentResult['stopR
      return 'max-tokens'
    case 'aborted':
    case 'interrupted':
-    case 'disposed':
      return 'aborted'
    case 'error':
      return 'error'
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,8 +1,9 @@
 /**
 * Read-only interpretation of session-query lineage as durable subagent
- * children. The module owns no catalog state and does not consult Activation,
- * Agent-registry, continuation-manager, or provider state. A child's
- * descriptor distinguishes one-shot work from a continuable conversation.
+ * children. Only descendants with durable `origin: 'subagent'` enter per-child
+ * inspection. The module owns no catalog state and does not consult Activation,
+ * Agent-registry, continuation-manager, or provider state. A child's descriptor
+ * distinguishes one-shot work from a continuable conversation.
 *
 * @module @deepseek-ai/dsh-subagent
 */
@@ -20,12 +21,13 @@ type SessionQueryRuntime = Pick<
 >

 /**
- * One entry of a {@link listChildren} result in trace candidate order. A valid
- * descriptor produces a `child`, a per-child inspection failure produces a
- * `diagnostic`, and a descriptor-less ordinary child is omitted. Healthy rows
- * include a one-level, origin-classified descendant hint. Diagnostics are
- * transient query results, never session events or catalog state, and never
- * expose model-hidden descriptor content.
+ * One entry of a {@link listChildren} result in trace candidate order. Only a
+ * candidate whose durable header has `origin: 'subagent'` is inspected. A
+ * valid descriptor produces a `child`, a per-child inspection failure produces
+ * a `diagnostic`, and a candidate without its own descriptor is omitted.
+ * Healthy rows include a one-level, origin-classified descendant hint.
+ * Diagnostics are transient query results, never session events or catalog
+ * state, and never expose model-hidden descriptor content.
 */
 export type SubagentListEntry =
  | {
@@ -69,8 +71,9 @@ export type SubagentListEntry =
  }

 /**
- * Interpret one parent's direct session descendants as session-backed subagents
- * without loading or resuming an Agent.
+ * Interpret one parent's origin-classified direct descendants as session-backed
+ * subagents without loading or resuming an Agent. Ordinary forks are skipped
+ * before per-child event inspection.
 * @see {@link SubagentService.listChildren} for the public cancellation and
 *   failure contract.
 * @param ctx - context carrying the optional session-query service.
@@ -103,6 +106,7 @@ export async function listChildren(
  )
  const entries: SubagentListEntry[] = []
  for (const node of trace.descendants) {
+    if (node.session.header.origin !== 'subagent') continue
    const hasChildren = node.descendants.some(
      descendant => descendant.session.header.origin === 'subagent',
    )
@@ -218,6 +222,8 @@ function perChildDiagnosticReason(
 ): 'corrupt' | 'unavailable' | undefined {
  if (!(error instanceof SessionQueryError)) return undefined
  switch (error.code) {
+    case 'SESSION_QUERY_CORRUPT_SESSION':
+      return 'corrupt'
    case 'SESSION_QUERY_SESSION_NOT_FOUND':
    case 'SESSION_QUERY_EVENT_NOT_FOUND':
    case 'SESSION_QUERY_PERSISTENCE_FAILED':
--- a/packages/subagent/subagent/tests/continuation.spec.ts
+++ b/packages/subagent/subagent/tests/continuation.spec.ts
@@ -142,14 +142,27 @@ async function waitNoActivation(ctx: Context, childId: SessionId): Promise<void>
  }, { timeout: 5_000 })
 }

+/** Observe calls at the Agent cancellation boundary without a production event. */
+function observeCancel(agent: Agent, callback: () => void): void {
+  const cancel = agent.cancel.bind(agent)
+  let observed = false
+  vi.spyOn(agent, 'cancel').mockImplementation((cause, options) => {
+    if (!observed) {
+      observed = true
+      callback()
+    }
+    cancel(cause, options)
+  })
+}
+
 describe('SubagentService.startContinuable', () => {
  it('returns both identities at inbox acceptance, without waiting for the turn or the log', async () => {
    const { ctx, parent, adapter } = await setup([textResponse('first answer')])
    const enqueued: { id: MessageId; loggedYet: boolean }[] = []
-    ctx.on('agent/inbox/enqueue', (agent, accepted) => {
+    ctx.on('agent/inbox/inserted', ({ agent, message }) => {
      // Acceptance is the boundary `startContinuable` resolves at, so observe
      // the log state exactly there rather than after later microtasks.
-      enqueued.push({ id: accepted.message.id, loggedYet: hasUserText(agent.session.events, 'child task') })
+      enqueued.push({ id: message.id, loggedYet: hasUserText(agent.session.events, 'child task') })
    })

    const started = await ctx.subagents.startContinuable(startSpec(parent))
@@ -218,7 +231,7 @@ describe('SubagentService.startContinuable', () => {
    const { ctx, parent } = await setup([textResponse('unused')])
    const controller = new AbortController()
    // Abort inside the child's creation window: setup runs before publication.
-    ctx.on('agent/created', (child) => {
+    ctx.on('agent/created', ({ agent: child }) => {
      if (child !== parent) controller.abort('caller gave up')
    })

@@ -555,6 +568,47 @@ describe('SubagentService.followup residency routing', () => {
      .rejects.toMatchObject({ code: 'NOT_RESUMABLE' })
  })

+  it('propagates cancellation while inspecting a cold child', async () => {
+    const { ctx, parent } = await setup([textResponse('first')])
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await waitNoActivation(ctx, started.childId)
+    const inspectStarted = Promise.withResolvers<undefined>()
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect').mockImplementation((_id, signal) => {
+      return new Promise<never>((_resolve, reject) => {
+        if (signal === undefined) {
+          reject(new Error('cold inspection must receive the followup signal'))
+          return
+        }
+        inspectStarted.resolve(undefined)
+        signal.addEventListener('abort', () => {
+          reject(reason)
+        }, { once: true })
+      })
+    })
+    const controller = new AbortController()
+    const reason = new Error('cold inspection cancelled')
+
+    try {
+      const delivery = followup(ctx, parent, started.childId, message('cancel me'), controller.signal)
+      await inspectStarted.promise
+      controller.abort(reason)
+      await expect(delivery).rejects.toBe(reason)
+    } finally {
+      inspect.mockRestore()
+    }
+  })
+
+  it('preserves a SubagentError raised while cold-materializing a child', async () => {
+    const { ctx, parent } = await setup([textResponse('first')])
+    const started = await ctx.subagents.startContinuable(startSpec(parent))
+    await waitNoActivation(ctx, started.childId)
+    const failure = new SubagentError('materialization denied', 'UNAUTHORIZED')
+    ctx.agents.resume = () => Promise.reject(failure)
+
+    await expect(followup(ctx, parent, started.childId, message('continue')))
+      .rejects.toBe(failure)
+  })
+
  it('cold-resumes a delivery that lost the race with final disposal', async () => {
    const { ctx, parent } = await setup([textResponse('first'), textResponse('after the race')])
    const started = await ctx.subagents.startContinuable(startSpec(parent))
@@ -699,7 +753,7 @@ describe('continuable durability and teardown', () => {
    await vi.waitFor(() => { expect(ctx.agents.get(grandchild.childId)).toBeDefined() })

    const disposals: SessionId[] = []
-    ctx.on('agent/disposed', (agent) => { disposals.push(agent.id) })
+    ctx.on('agent/disposed', ({ agent }) => { disposals.push(agent.id) })
    const drained = drainManager(ctx)
    // Let the held model call observe its cancellation so quiescence can settle.
    hold.resolve(undefined)
@@ -737,7 +791,9 @@ describe('continuable durability and teardown', () => {
    const grandchild = await ctx.subagents.startContinuable(startSpec(targetChild))
    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(3) })
    const cancellations: SessionId[] = []
-    ctx.on('agent/cancel-requested', (agent) => { cancellations.push(agent.id) })
+    observeCancel(targetChild, () => { cancellations.push(targetChild.id) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    observeCancel(grandchildAgent, () => { cancellations.push(grandchildAgent.id) })

    const drained = ctx.subagents.drainContinuableDescendants([parent])
    const convergedDrain = ctx.subagents.drainContinuableDescendants([parent])
@@ -784,7 +840,8 @@ describe('continuable durability and teardown', () => {
    const grandchild = await ctx.subagents.startContinuable(startSpec(child))
    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(2) })
    const cancellations: SessionId[] = []
-    ctx.on('agent/cancel-requested', (agent) => { cancellations.push(agent.id) })
+    const grandchildAgent = ctx.agents.get(grandchild.childId)!
+    observeCancel(grandchildAgent, () => { cancellations.push(grandchildAgent.id) })

    const drained = ctx.subagents.drainContinuableDescendants([child])

@@ -828,7 +885,8 @@ describe('continuable durability and teardown', () => {
    expect(ctx.agents.get(intermediateId)).toBeUndefined()
    expect(ctx.agents.get(descendant.childId)).toBeDefined()
    const cancellations: SessionId[] = []
-    ctx.on('agent/cancel-requested', (agent) => { cancellations.push(agent.id) })
+    const descendantAgent = ctx.agents.get(descendant.childId)!
+    observeCancel(descendantAgent, () => { cancellations.push(descendantAgent.id) })

    const drained = ctx.subagents.drainContinuableDescendants([parent])

@@ -926,7 +984,7 @@ describe('continuable durability and teardown', () => {
    const drains: Promise<void>[] = []
    const accepted: MessageId[] = []
    ctx.on('subagent/start', () => { drains.push(drainManager(ctx)) })
-    ctx.on('agent/inbox/enqueue', (_agent, item) => { accepted.push(item.message.id) })
+    ctx.on('agent/inbox/inserted', ({ message }) => { accepted.push(message.id) })

    await expect(ctx.subagents.startContinuable(startSpec(parent)))
      .rejects.toMatchObject({ code: 'DRAINING' })
@@ -940,12 +998,12 @@ describe('continuable durability and teardown', () => {
    const { ctx, parent } = await setup([])
    const order: string[] = []
    const drains: Promise<void>[] = []
-    ctx.on('agent/created', (child) => {
+    ctx.on('agent/created', ({ agent: child }) => {
      if (child === parent) return
      const draining = drainManager(ctx).then(() => { order.push('drain') })
      drains.push(draining)
    })
-    ctx.on('agent/disposed', (child) => {
+    ctx.on('agent/disposed', ({ agent: child }) => {
      if (child !== parent) order.push('disposed')
    })

@@ -967,12 +1025,12 @@ describe('continuable durability and teardown', () => {
    await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) })
    const child = ctx.agents.get(started.childId)!
    const order: string[] = []
-    child.ctx.on('agent/inbox/enqueue', (_agent, accepted) => {
-      if (accepted.message.content.some(block => block.type === 'text' && block.text === 'before drain')) {
+    child.ctx.on('agent/inbox/inserted', ({ message }) => {
+      if (message.content.some(block => block.type === 'text' && block.text === 'before drain')) {
        order.push('enqueue')
      }
    })
-    child.ctx.on('agent/cancel-requested', () => { order.push('cancel') })
+    observeCancel(child, () => { order.push('cancel') })

    const delivery = followup(ctx, parent, started.childId, message('before drain'))
    // Let the child-lock operation reach the live admission cutoff. Admission
@@ -1150,9 +1208,9 @@ describe('continuable review regressions', () => {
    const ends: SubagentRunEndInfo[] = []
    ctx.on('subagent/end', (info) => { ends.push(info) })
    // Block the resumed prompt so this epoch produces nothing of its own.
-    ctx.on('agent/prompt-submit', async (subject, _message, _signal, next) => {
+    ctx.on('agent/pre-step', async ({ agent: subject }, next) => {
      if (subject === parent) return next()
-      return { kind: 'block', reason: 'blocked by policy' }
+      return { kind: 'reject' }
    })
    await followup(ctx, parent, started.childId, message('again'))
    await waitNoActivation(ctx, started.childId)
@@ -1258,7 +1316,7 @@ describe('continuable review regressions', () => {
      expect(found).toBeDefined()
      return found!
    })
-    child.ctx.on('agent/cancel-requested', () => { order.push('cancel') })
+    observeCancel(child, () => { order.push('cancel') })

    const drained = drainManager(ctx)
    hold.resolve(undefined)
@@ -1298,8 +1356,8 @@ describe('continuable review regressions', () => {

    // Cancel from the synchronous enqueue observer: the discard fires after the
    // id is recorded but before `followup()` returns.
-    const off = child.ctx.on('agent/inbox/enqueue', (_agent, accepted) => {
-      if (accepted.message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
+    const off = child.ctx.on('agent/inbox/inserted', ({ message }) => {
+      if (message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
        child.cancel({ kind: 'user' })
      }
    })
@@ -1330,8 +1388,8 @@ describe('continuable review regressions', () => {

    await followup(ctx, parent, started.childId, message('queued'))
    expect(activation.accepted.size).toBe(1)
-    const off = child.ctx.on('agent/inbox/enqueue', (_agent, accepted) => {
-      if (accepted.message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
+    const off = child.ctx.on('agent/inbox/inserted', ({ message }) => {
+      if (message.content.some(block => block.type === 'text' && block.text === 'doomed')) {
        child.cancel({ kind: 'user' })
      }
    })
@@ -1348,9 +1406,9 @@ describe('continuable review regressions', () => {
    const ends: SubagentRunEndInfo[] = []
    ctx.on('subagent/end', (info) => { ends.push(info) })
    // Block admission so the child's only turn never opens.
-    ctx.on('agent/prompt-submit', async (subject, _message, _signal, next) => {
+    ctx.on('agent/pre-step', async ({ agent: subject }, next) => {
      if (subject === parent) return next()
-      return { kind: 'block', reason: 'blocked by policy' }
+      return { kind: 'reject' }
    })

    const started = await ctx.subagents.startContinuable(startSpec(parent))
@@ -1370,7 +1428,7 @@ describe('continuable review regressions', () => {
    const registeredAtEnqueue: boolean[] = []
    // A synchronous inbox observer runs before the admitting microtask, the
    // exact window where `Agent.status` is still idle.
-    ctx.on('agent/inbox/enqueue', (agent) => {
+    ctx.on('agent/inbox/inserted', ({ agent }) => {
      if (agent.session.header.parentSession !== undefined) {
        registeredAtEnqueue.push(ctx.agents.get(agent.id) === agent)
      }
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -113,10 +113,11 @@ describe('SubagentService.listChildren', () => {
    const parentId = SessionId('query-only-parent')
    ctx.sessions.create(parentId)
    const childId = SessionId('query-only-child')
-    const child = ctx.sessions.create(childId, { meta: { parentSession: parentId } })
+    const child = ctx.sessions.create(childId, {
+      meta: { parentSession: parentId, origin: 'subagent' },
+    })
    child.append('turn/start', {
      turn: 1,
-      trigger: { kind: 'message', source: { kind: 'user' } },
    })
    child.append('subagent/descriptor', descriptorPayload('query-only child'))

@@ -193,6 +194,7 @@ describe('SubagentService.listChildren', () => {
    ] as SessionEvent[])
    const childId = await authorChild(ctx, '00000000-0000-4000-8000-00000000cdcd', {
      parentSession: coldParent,
+      origin: 'subagent',
    }, childEvents(descriptorPayload('persisted parent case')))
    const entries = await ctx.subagents.listChildren(coldParent)
    expect(entries).toEqual([
@@ -203,28 +205,33 @@ describe('SubagentService.listChildren', () => {
    ])
  })

-  it('orders children by createdAt then id and omits ordinary forks without a diagnostic', async () => {
+  it('orders children by createdAt then id without inspecting ordinary forks', async () => {
    const { ctx, parent } = await setup([])
    // Authored headers pin the ordering key deterministically: same createdAt
    // ties break on id, different createdAt orders ascending.
    const late = await authorChild(ctx, '00000000-0000-4000-8000-000000000003', {
      parentSession: parent.id,
      createdAt: 9,
+      origin: 'subagent',
    }, childEvents(descriptorPayload('late child')))
    const tieB = await authorChild(ctx, '00000000-0000-4000-8000-000000000002', {
      parentSession: parent.id,
      createdAt: 5,
+      origin: 'subagent',
    }, childEvents(descriptorPayload('tie b')))
    const tieA = await authorChild(ctx, '00000000-0000-4000-8000-000000000001', {
      parentSession: parent.id,
      createdAt: 5,
+      origin: 'subagent',
    }, childEvents(descriptorPayload('tie a')))
-    // An ordinary session fork shares parentSession but has no descriptor.
+    // An ordinary session fork shares parentSession but has no subagent origin.
    const fork = ctx.sessions.fork(parent.session, undefined, SessionId('plain-fork'))
    await ctx.sessions.flush(fork)
+    const listEvents = vi.spyOn(ctx.sessionQuery, 'listEvents')
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries.map(entry => entry.id)).toEqual([tieA, tieB, late])
    expect(entries.every(entry => entry.kind === 'child')).toBe(true)
+    expect(listEvents).not.toHaveBeenCalledWith(fork.id)
  })

  it('reports a live child as running while keeping settled siblings complete', async () => {
@@ -233,8 +240,10 @@ describe('SubagentService.listChildren', () => {
    // A live child session outside persistence: publish a live session with a
    // descriptor and the parent lineage, without starting an Activation.
    const liveId = SessionId('live-child')
-    const live = ctx.sessions.create(liveId, { meta: { parentSession: parent.id } })
-    live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    const live = ctx.sessions.create(liveId, {
+      meta: { parentSession: parent.id, origin: 'subagent' },
+    })
+    live.append('turn/start', { turn: 1 })
    live.append('subagent/descriptor', descriptorPayload('live child'))
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries).toContainEqual({
@@ -260,6 +269,7 @@ describe('SubagentService.listChildren', () => {
    events[4] = { ...events[4]!, seq: 4 }
    const corrupt = await authorChild(ctx, '00000000-0000-4000-8000-00000000dupe', {
      parentSession: parent.id,
+      origin: 'subagent',
    }, events)
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries).toContainEqual({ kind: 'diagnostic', id: corrupt, reason: 'corrupt' })
@@ -269,12 +279,13 @@ describe('SubagentService.listChildren', () => {
    })
  })

-  it('diagnoses an invalid child event surface as corrupt', async () => {
+  it('diagnoses a child rejected by persisted Session preparation as corrupt', async () => {
    const { ctx, parent } = await setup([])
-    // The surface-eligible user/message lacks its required surfaceOp, so the
-    // per-child listEvents fold fails with SESSION_QUERY_INVALID_SURFACE.
+    // The surface-eligible user/message lacks its required surfaceOp. The
+    // first-party persistence inspection rejects before session-query can fold it.
    const invalid = await authorChild(ctx, '00000000-0000-4000-8000-0000000000ee', {
      parentSession: parent.id,
+      origin: 'subagent',
    }, [
      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
      {
@@ -293,6 +304,7 @@ describe('SubagentService.listChildren', () => {
    const { ctx, parent } = await setup([])
    const malformed = await authorChild(ctx, '00000000-0000-4000-8000-0000000000ff', {
      parentSession: parent.id,
+      origin: 'subagent',
    }, childEvents({ version: SUBAGENT_DESCRIPTOR_VERSION, mode: 'continuable', provider: 7 }))
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries).toEqual([{ kind: 'diagnostic', id: malformed, reason: 'corrupt' }])
@@ -302,6 +314,7 @@ describe('SubagentService.listChildren', () => {
    const { ctx, parent } = await setup([])
    const future = await authorChild(ctx, '00000000-0000-4000-8000-0000000000aa', {
      parentSession: parent.id,
+      origin: 'subagent',
    }, childEvents(descriptorPayload('from the future', SUBAGENT_DESCRIPTOR_VERSION + 1)))
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries).toEqual([{ kind: 'diagnostic', id: future, reason: 'unsupported' }])
@@ -315,6 +328,7 @@ describe('SubagentService.listChildren', () => {
    await authorChild(ctx, '00000000-0000-4000-8000-0000000000f0', {
      parentSession: parent.id,
      seedLength: seed.length,
+      origin: 'subagent',
    }, seed)
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries).toEqual([])
@@ -324,6 +338,7 @@ describe('SubagentService.listChildren', () => {
    const { ctx, parent } = await setup([])
    const foreign = await authorChild(ctx, '00000000-0000-4000-8000-0000000000bb', {
      parentSession: parent.id,
+      origin: 'subagent',
    }, childEvents({
      version: SUBAGENT_DESCRIPTOR_VERSION,
      mode: 'continuable',
@@ -354,16 +369,30 @@ describe('SubagentService.listChildren', () => {
    expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'unavailable' }])
  })

-  it('maps a mid-scan disappearance to unavailable', async () => {
+  it.each([
+    ['session', 'SESSION_QUERY_SESSION_NOT_FOUND'],
+    ['descriptor event', 'SESSION_QUERY_EVENT_NOT_FOUND'],
+  ] as const)('maps a missing child %s to unavailable', async (_target, code) => {
    const { ctx, parent } = await setup([textResponse('done')])
    const childId = await startChild(ctx, parent, 'vanishing child')
    const query = ctx.get('sessionQuery')!
    query.listEvents = () =>
-      Promise.reject(new SessionQueryError('gone', 'SESSION_QUERY_SESSION_NOT_FOUND'))
+      Promise.reject(new SessionQueryError('gone', code))
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'unavailable' }])
  })

+  it('maps an invalid child surface to corrupt', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    const childId = await startChild(ctx, parent, 'invalid surface')
+    const query = ctx.get('sessionQuery')!
+    query.listEvents = () =>
+      Promise.reject(new SessionQueryError('invalid surface', 'SESSION_QUERY_INVALID_SURFACE'))
+
+    const entries = await ctx.subagents.listChildren(parent.id)
+    expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'corrupt' }])
+  })
+
  it('diagnoses a read whose header no longer names this parent as corrupt', async () => {
    const { ctx, parent } = await setup([textResponse('done')])
    const childId = await startChild(ctx, parent, 'reparented child')
@@ -429,6 +458,7 @@ describe('SubagentService.listChildren', () => {
    const plain = await authorChild(ctx, '00000000-0000-4000-8000-00000000c0de', {
      parentSession: parent.id,
      createdAt: 1,
+      origin: 'subagent',
    }, childEvents(descriptorPayload('twin child')))
    // The compacted twin: a compaction checkpoint replaces the whole surface,
    // while the append-only log retains the model-hidden descriptor event.
@@ -447,6 +477,7 @@ describe('SubagentService.listChildren', () => {
    const compacted = await authorChild(ctx, '00000000-0000-4000-8000-00000000c1de', {
      parentSession: parent.id,
      createdAt: 2,
+      origin: 'subagent',
    }, compactedEvents)
    const entries = await ctx.subagents.listChildren(parent.id)
    expect(entries).toEqual([