diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
index e897122368..e292482740 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.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 .agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
-2026-07-19-package-invariant-runtime-contracts.md: 40d152b2320ac65f9ea7d8732b1a667236d2780a
-2026-07-19-package-invariant-runtime-contracts.zh.md: a734b1a3deb739c214d1c4c2565fc697b5e4b89b
+2026-07-19-package-invariant-runtime-contracts.md: 86d86f69b606c348e85d1ae654b6b35c4326985a
+2026-07-19-package-invariant-runtime-contracts.zh.md: 386a294b577561d08493a3b2925910ee5ba971b4
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
index 40d152b232..86d86f69b6 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
@@ -50,7 +50,7 @@ The current 103-package workspace has 21 executable companions and 82 justified
 | `dsh-user-approval` | Approval asked/decided records pair by call and use valid outcomes and policies. |
 | `dsh-workflow` | Workflow and child-agent start/end events preserve run metadata, identity, outcome, count, and error relations. |
 | `dsh-tasks` | Current and terminal task snapshots preserve id/kind, owner, status, and timestamp relationships. |
-| `dsh-tool-todo` | Durable whole-list snapshots use unique trimmed items, closed statuses, and at most one active item. |
+| `dsh-tool-todo` | Durable whole-list snapshots use unique trimmed items and closed statuses. |
 | `dsh-time-context` | Plugin-attributed clock readings agree with the session's open turn, next pre-step position, and elapsed baseline; rendered time parses and does not postdate its event. |
 
 Session-backed companions validate existing durable events when they load, using the prefix preceding each candidate where the relationship depends on event order. Other checks observe the authoritative live event boundary or mutable service result. Validation runs before publication where accepting an invalid event would otherwise commit bad state.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
index a734b1a3de..386a294b57 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
@@ -50,7 +50,7 @@ Status: implemented
 | `dsh-user-approval` | approval asked/decided 记录按 call 配对，并使用有效 outcome 和 policy。 |
 | `dsh-workflow` | 工作流和 child-agent start/end 事件保持 run metadata、身份、outcome、数量和 error 关系。 |
 | `dsh-tasks` | 当前与终态 task 快照保持 id/kind、owner、status 和 timestamp 关系。 |
-| `dsh-tool-todo` | 持久化全量快照使用唯一且已 trim 的条目、封闭 status，并且最多有一个活动条目。 |
+| `dsh-tool-todo` | 持久化全量快照使用唯一且已 trim 的条目和封闭 status。 |
 | `dsh-time-context` | 标注插件来源的时钟 reading 必须匹配会话当前打开的轮次、下一个步骤开始前的位置和 elapsed baseline；渲染时间必须可解析，且不得晚于对应事件。 |
 
 基于会话的 companion 在加载时验证已有持久化事件；关系依赖事件顺序时，会使用每个候选事件之前的事件前缀。其他检查观测权威实时事件边界或可变服务结果。如果接受无效事件会提交错误状态，验证就在发布前执行。
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
index 70d44e1767..9994bcb3b9 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.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 .agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
-2026-07-27-dispose-ladder-to-consumer.md: 97b551ff509e3b424f6bf5725939cf54acc961a7
-2026-07-27-dispose-ladder-to-consumer.zh.md: 7fff744e64109549a65d4f5bb17ff2d6ddfc6888
+2026-07-27-dispose-ladder-to-consumer.md: e9af88e8e7ef962213a74e96a249241cbe8d5994
+2026-07-27-dispose-ladder-to-consumer.zh.md: 89f8e107c56d42787c59bc6f8fa8fc7b3ef73208
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
index 97b551ff50..e9af88e8e7 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.md
@@ -10,7 +10,7 @@ English | [中文](2026-07-27-dispose-ladder-to-consumer.zh.md)
 
 ## Decision
 
-The ladder moves to its one consumer. `dsh-subagent-acp` owns `disposeAcpChild(child, eofGraceMs, graceMs)`, built entirely on the seam's public verbs: close `stdin`, bound a `waitForExit` on `eofGraceMs`, then `terminate()` (whose SIGTERM→spec-grace→SIGKILL escalation already encodes the signal tiers), then a final bounded whole-tree wait that throws if survivors remain. The seam keeps `kill`/`terminate`/`waitForExit` — mechanisms, not policy — and `waitForExit(signal?)` is exactly the quiescence probe a consumer ladder needs to hold each tier on real tree exit. `dsh-subprocess-local` drops its `dsh-timeout` dependency; the seam's handle loses one method and one exported interface.
+The ladder moves to its one consumer. `dsh-subagent-acp` owns `disposeAcpChild(child, eofGraceMs)`, built entirely on the seam's public verbs: close `stdin`, bound a `waitForExit` on `eofGraceMs`, then call `terminate()`, whose SIGTERM→spec-grace→SIGKILL escalation already owns the signal timer, and await an unbounded `waitForExit()` for the subprocess owner's whole-tree exit proof. The seam keeps `kill`/`terminate`/`waitForExit` — mechanisms, not policy — and `waitForExit(signal?)` is exactly the quiescence probe a consumer ladder needs to hold the cooperative tier on real tree exit without deriving another timer from the termination grace. The seam's handle loses one method and one exported interface.
 
 ## Alternatives considered
 
@@ -20,4 +20,4 @@ The ladder moves to its one consumer. `dsh-subagent-acp` owns `disposeAcpChild(c
 
 ## Consequences
 
-Bought: the seam is one method and one type smaller; implementations owe four verbs and no teardown policy; `dsh-subprocess-local` loses a dependency; the ladder's tier windows live beside the config fields that tune them. Cost: a future backend wanting EOF-first teardown writes ~20 lines against the verbs (or lifts the ACP helper); the ladder's tier-tier tests moved from the seam suite to the ACP suite, and the seam suite pins the verbs the ladder composes (bounded `waitForExit` false-then-true across an escalation) instead of the composed policy.
+Bought: the seam is one method and one type smaller; implementations owe four verbs and no teardown policy; the cooperative EOF window lives beside the ACP config field that tunes it, while the subprocess owner alone owns the termination window and final join. Cost: a future backend wanting EOF-first teardown writes ~20 lines against the verbs (or lifts the ACP helper); the ladder's tier tests live in the ACP suite, and the seam suite pins the verbs the ladder composes (bounded `waitForExit` false before escalation and an unbounded whole-tree join after it) instead of the composed policy.
diff --git a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
index 7fff744e64..89f8e107c5 100644
--- a/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-27-dispose-ladder-to-consumer.zh.md
@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs, graceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已编码了信号层级），最后进行有界的整树等待，若仍有存活进程则抛出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在每一层确认进程树真正退出所需的完全停稳探针。`dsh-subprocess-local` 卸下 `dsh-timeout` 依赖；seam 的句柄少了一个方法和一个导出接口。
+阶梯移入其唯一消费方。`dsh-subagent-acp` 拥有 `disposeAcpChild(child, eofGraceMs)`，完全构建在 seam 的公开动词之上：关闭 `stdin`，以 `eofGraceMs` 约束一次 `waitForExit`，随后调用 `terminate()`（其 SIGTERM→spec 宽限期→SIGKILL 升级已拥有信号定时器），再无界等待 `waitForExit()`，由子进程责任方证明整棵进程树已经退出。seam 保留 `kill`／`terminate`／`waitForExit`——机制而非策略——而 `waitForExit(signal?)` 恰是消费方阶梯在协作层确认进程树真正退出所需的停稳探针，无需从终止宽限期再派生一个定时器。seam 的句柄少了一个方法和一个导出接口。
 
 ## 曾考虑的替代方案
 
@@ -20,4 +20,4 @@ Status: implemented
 
 ## 后果
 
-换来的是：seam 少了一个方法和一个类型；实现只需提供四个动词，无需提供拆卸策略；`dsh-subprocess-local` 少了一个依赖；阶梯的层级时间窗与调节它们的配置字段住在一起。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试从 seam 套件移入 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前后有界 `waitForExit` 先假后真），而非组合后的策略。
+买到的：seam 少了一个方法和一个类型；实现只欠四个动词，不欠拆卸策略；协作式 EOF 时间窗与调节它的 ACP 配置字段住在一起，而终止时间窗与最终的整树退出等待仅由子进程责任方拥有。代价：未来想要 EOF 打头拆卸的后端需针对这些动词写约 20 行（或直接搬 ACP 的辅助函数）；阶梯的层级测试位于 ACP 套件，seam 套件转而钉住阶梯所组合的动词（升级前有界 `waitForExit` 返回假，升级后无界等待整棵进程树退出），而非组合后的策略。
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
new file mode 100644
index 0000000000..0168528557
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
+2026-08-06-subagent-list-identity-projection.md: ba023d04805ff3335c8f243510aa8ddc15fe13d6
+2026-08-06-subagent-list-identity-projection.zh.md: 368a70f5b3e5a27e4e1c648e8819476d40a57709
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
new file mode 100644
index 0000000000..ba023d0480
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md
@@ -0,0 +1,184 @@
+# Agent Note: Subagent list identity via the projection unit
+
+Status: implemented
+
+English | [中文](2026-08-06-subagent-list-identity-projection.zh.md)
+
+## Problem
+
+Before the rewrite, `SubagentService.listChildren` ran two full-log materializations — `listEvents` plus `readEvent` — on every listing for each direct child with `header.origin === 'subagent'`, each materialization accompanied by a full-log structuredClone, all to fold two fields, mode and label, out of the descriptor event. The descriptor's position in the log is not fixed — the fork prefix is arbitrarily long, and zstd-compressed frames carry no seq index — so there is no shortcut to locating it; this path had no cache whatsoever, and its cost amplifies with transcript length × child count × listing frequency. It also dragged session-query in as a hard dependency of listing: in a deployment without a query backend, `list_agents` rejects wholesale with `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`, even though enumeration needs nothing but header facts.
+
+The same root cause has a second symptom: on every Agent-bound RPC's owner check, the host-side `hasSubagentDescriptor()` scans the target session's own suffix, even though `SessionHeader.origin` already answers the vast majority of the same question.
+
+The root cause is that the [durable-subagent-catalog decision](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) made the descriptor event (`subagent/descriptor`) the catalog's sole durable authority yet paired descriptor reads with no cache layer, and explicitly accepted the per-child double read as the "no-index correctness baseline". [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md) (#1569) already put "is this a subagent" into the header (`SessionHeader.origin`), so identity determination no longer reads the log; mode and label still had to be scanned.
+
+## Decision
+
+mode and label are folded by the new `subagent` projection unit (pure identity, two arms), and the unit is the sole authority over the fold rules; `listChildren` no longer depends on session-query — enumeration is a subagent-owned live-preferred merge, and value retrieval walks a three-rung compute-and-discard ladder: a live child synchronously reads the registry's existing watermark cache (zero log reads); a cold child first asks the optional `sessionProjectionCache` checkpoint, and a served identity that passes the seq gate is final; otherwise it pays one full `persistence.inspect` read plus one `registry.restore` fold. No index, no cache of its own, no write-back.
+
+There are three families of escape from the per-child scan: promote mode/label into the header (the write path pays); build a durable derivation for the projection (a checkpoint ladder, or values landed during query-index rebuild with read-side reconciliation); or compute at read time (live from the watermark cache, cold from one full read). This note takes the third. "Values landed with the query index" was once this note's settled direction and was under construction for a time, then retired wholesale: query infrastructure was forced to learn domain vocabulary while the sole consumer is satisfied by read-time computation — the live child's zero reads come for free from session-projection's existing watermark cache, and the cold child's single full read is explicitly accepted as compute-and-discard. The first two routes and the retirement rationale are detailed under Alternatives considered.
+
+Key points:
+
+- **The subagent list does not depend on session-query**: enumeration is completed by a subagent-owned live-preferred merge, and mode/label is retrieved through `ctx.sessionProjections`; deployments without a query backend list as usual.
+- **Value retrieval is a three-rung compute-and-discard ladder**: a live child reads `sessionProjections.snapshot()` (the registry's existing watermark cache, zero log reads); a cold child first reads the optional `sessionProjectionCache.cachedSnapshot(header)`, using the value directly when a non-null `subagent` identity passing the seq gate (`seq >= seedLength ?? 0`) is among its values; otherwise it pays one full `persistence.inspect` read plus one `registry.restore({}, events, 0)` fold; beyond that, absent is absent — no cache of its own, no write-back, no index.
+- **The `subagent` projection unit is the sole authority over the fold rules**: the live snapshot, the cold restore, and GUI history's detached fold all compute through the registry; no second copy of descriptor-interpretation logic exists.
+- **The header, the descriptor (v2), session-persistence, session-projection(-cache), and session-query(-sqlite) are all untouched**; pre-existing data acquires exact values through one `inspect` computation the first time it is listed — no degraded unknown state, no migration.
+
+Relationship to existing notes:
+
+- This note supersedes two designs on the list read path in [durable-subagent-catalog](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md): enumeration through `sessionQuery.traceSession`, and per-child descriptor-event reads (the `listEvents`-plus-exact-`readEvent` double read with in-place diagnostic classification). The diagnostic row semantics is retained, with classification now derived by the list from projection-value absence and activity; the descriptor event remains the sole durable authority for mode/label and the fold input, and the resume authorization and Activation contracts are untouched. This is partial supersession; the two notes stay cross-linked.
+- The [session-projection RFC](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)'s registry contract (`ProjectionDefinition`, `snapshot`, `restore`) is untouched; this note only adds one registration to it — the `subagent` identity unit — and becomes another consumer instance of the two existing reads, snapshot (live) and restore (cold) — GUI history's cold read is already the same shape. The fold rules are registered with the registry exactly once; every consuming surface computes through the registry, and no second copy of the fold logic exists.
+
+### `subagent` projection unit
+
+It hangs beside the existing `subagentTiming` ([projection.ts](../../../../packages/subagent/subagent/src/projection.ts), [projection-types.ts](../../../../packages/subagent/subagent/src/projection-types.ts)), under key `subagent`:
+
+```ts ignore-check
+export type SubagentIdentityProjection =
+  | { mode: 'one-shot'; label?: string; seq: number }
+  | { mode: 'continuable'; label: string; seq: number }
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    subagent: SubagentIdentityProjection | null
+  }
+}
+```
+
+- The projection is pure identity, and **the projection system has no failure channel**: a unit never throws; a corrupt payload or an unrecognized version folds exactly like a log with no descriptor at all — the result is a **serializable null sentinel**: the map entry is `SubagentIdentityProjection | null`, non-optional, never undefined or an absent key. The reason: the registry's onChanged push goes through JSON serialization, where an undefined field is dropped by stringify, the client's frame validation rejects the frame, and a consumer's stored old identity would never update; null passes frames intact, and consumers replace the old identity with the sentinel. The judging discipline: consuming surfaces treat null and undefined (which only a JSON boundary dropping the key can produce) alike as no value. How "computed to nothing" is presented is the consumer's own business (see the `listChildren` four-state mapping below).
+- Label strength is decided by the descriptor schema: a continuable's label is mandatory at parse, a one-shot's was always optional; the mode/label discriminant matches the child row's strong contract below exactly (the row carries no `seq` — it is the projection's internal own-suffix proof).
+- The identity carries `seq`: the seq of the `subagent/descriptor` event it was folded from, mandatory on both arms and absent on the null sentinel — `seq >= header.seedLength ?? 0` proves the identity was folded from the child's own suffix rather than a fork seed's replayed ancestor descriptor. The state gaining `seq` bumps the unit's `stateVersion` to 2, and existing checkpoint rows are invalidated by version mismatch per the registry contract, falling to the authoritative refold.
+- Fold rule: `subagent/descriptor` is last-wins, under the same descriptor-reset discipline as `subagentTiming` — ancestor descriptors in the fork prefix are overridden by the session's own descriptor. A corrupt or unrecognized-version payload is last-wins all the same: it resets to the null sentinel rather than keeping the prior identity, so a fork of a healthy ancestor does not inherit an identity its own descriptor cannot stand up.
+
+### Enumeration: subagent-owned live-preferred merge
+
+`listChildren`'s ([list-children.ts](../../../../packages/subagent/subagent/src/list-children.ts)) enumeration goes through no query service: the two sources `ctx.sessions.list()` and `ctx.get('sessionPersistence')?.list()` merge by id, with a live record overriding the same-id persisted record wholesale and no header consistency check. Everything enumeration needs is header facts:
+
+- Filtering: `header.origin === 'subagent' && header.parentSession === parentSessionId`.
+- `hasChildren`: the same merged material, looked at one level down — a direct descendant exists with `origin === 'subagent'` whose `parentSession` is that child.
+- `activity`: a live record is `running`; one present only in persistence is `inactive`.
+- Ordering: `createdAt` ascending, then child id ascending (matching the old contract).
+- **Absent persistence degrades to live-only enumeration, not an error**: in a deployment without persistence, a cold child could not be resumed anyway, and listing live children remains meaningful. (Contrast: the old implementation rejected wholesale when sessionQuery was missing.)
+- A persistence listing failure fails the whole enumeration; per-child isolation applies only to the per-child cold reads.
+
+### Value retrieval: the three-rung compute-and-discard ladder
+
+For each enumerated child, mode/label retrieval walks a three-rung ladder — compute-and-discard, no cache of its own, no write-back (the third rung is the same shape as apiproxy `session.history`'s cold read):
+
+| Rung | Read | Cost |
+| --- | --- | --- |
+| 1: live child | `ctx.sessionProjections.snapshot(session).values.subagent` | Zero log reads — the registry's existing watermark cache, synchronous retrieval |
+| 2: cold child, cache hit | The optional `sessionProjectionCache.cachedSnapshot(header)`, used directly only when a non-null `subagent` identity satisfies `identity.seq >= header.seedLength ?? 0` — an own descriptor is immutable once appended, and the seq gate proves the value was folded from the child's own suffix, regardless of the row's watermark | Zero log reads |
+| 3: cold child, fallback | One full `persistence.inspect(id)` read + `registry.restore({}, events, 0).snapshot.values.subagent` | One full read computed per listing |
+
+- Error contract: an unmounted `ctx.sessionProjections` is a configuration error; `listChildren` checks unconditionally before enumerating and fails loudly with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` — a deployment with zero children fails just as deterministically, so an empty listing cannot mask the misconfiguration. The session store gets the same posture: an absent `ctx.get('sessions')` (a strict global read, never the caller-scope-bound property proxy) fails with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. The two codes map differently on the wire: apiproxy gives only `PROJECTIONS_UNAVAILABLE` a dedicated wire face, and `SESSION_STORE_UNAVAILABLE` goes through the generic internal fallback — the apiproxy composition injects `sessions` itself, so that error is unreachable in its deployment, and a dedicated mapping would violate the need principle. `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` is deleted along with the session-query dependency.
+- The cache is a purely optional acceleration layer: an absent service is skipped on a null check — no error code, no part in configuration validation (in contrast to `sessionProjections`' loud contract). Anything the second rung throws (including a poisoned unit row in the cache detonating `viewCheckpoint`) silently falls to the third rung — the cache is derived data, so its faults never produce a `corrupt` verdict; the final judgment belongs to the authoritative refold. A row whose checkpoint cut predates the descriptor naturally lacks the `subagent` key and falls through automatically, with no special-casing; a null sentinel in the row does not count either — it falls to the third rung for the authoritative refold's verdict. A count/interval checkpoint inside the creation window can land a fork seed's replayed ancestor identity in the row — the ancestor's seq falls inside the seed range, the seq gate rejects it, and it likewise falls to the third rung's verdict.
+- Per-child isolation: a single child's failed cold full read only turns that row into an `unavailable` diagnostic, naturally retried on the next listing, without affecting siblings (see the four-state mapping).
+- The cold path's lifecycle witness: preparation's result must still point at the lifecycle that was enumerated — the witness field set is the same seven fields as the old SOURCE_CONFLICT check (version, id, createdAt, cwd, parentSession, seedLength, delegationDepth); a session deleted and republished under the same id degrades to a `corrupt` row in the old parent's catalog, leaking nothing of the new owner's child.
+- Cold-read concurrency is bounded by the constant 4 — it constrains a read-only scan of local media, not deployment behavior; when a networked persistence backend appears, it is promoted to a validated `Config` field.
+- The cold-read cost, recorded honestly: only with the cache unmounted or missed does a cold child pay one full read per listing, at a cost proportional to its transcript size; the settled stance is compute-and-discard, and no cache of its own is built. The full read goes through `inspect()` into the [Session preparation](2026-08-05-session-preparation.md) cold read, so short-term repeated reads of the same id can hit its LRU for reuse, but listing does not depend on this. A live child reads zero log throughout.
+- Cancellation: the caller's signal is checked before and after each persistence read, and a read that settles only after abort is rejected, normalized to the stable error code `CANCELLED`.
+
+### Authority model
+
+- The session log is the sole authority; this design adds no derived persistence of any kind — no index values, no checkpoints of its own, no in-process memo; the `sessionProjectionCache` checkpoint the second rung reads is an existing composition item's derived data, which this design only reads and never writes. Values are computed on read and discarded, and a value's freshness is exactly the live state or persisted revision at the moment of the read (an own descriptor is immutable once appended — a cached identity past the seq gate has no staleness problem; the gate guards against seed-replayed ancestor identities).
+- The Session and persistence write paths are entirely unaware of listing and projection consumption: no event-listener write-back, no fold-on-write.
+- Enumeration and value retrieval constitute no second authorization source and make no unpublished child visible — the two sources see only published live records and durably written persisted records, consistent with the rule the durable-subagent-catalog note laid down for derived read surfaces.
+
+### `listChildren` row shape and consuming surfaces
+
+The `SubagentListEntry` **data structure is identical to before the rewrite** — the child and diagnostic arms, the `kind` discriminant, the three-valued `reason`, and the child arm's strong mode/label contract are all retained; the only change is the diagnostics' information source: the projection system has no failure channel, so diagnostics are derived by the list from projection-value absence and activity, and the list itself parses zero events. The "no value means await the hard read" rule guarantees the ladder always computes mode/label for healthy data.
+
+```ts ignore-check
+export type SubagentListEntry =
+  | ({
+    readonly kind: 'child'
+    readonly id: SessionId
+    readonly activity: 'running' | 'inactive'
+    readonly hasChildren: boolean
+  } & (
+    | { readonly mode: 'one-shot'; readonly label?: string }
+    | { readonly mode: 'continuable'; readonly label: string }
+  ))
+  | {
+    readonly kind: 'diagnostic'
+    readonly id: SessionId
+    readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
+  }
+```
+
+For each enumerated child, the ladder's result maps to a row through four states:
+
+| Ladder result | Row |
+| --- | --- |
+| Snapshot carries a non-null `subagent` identity | child row |
+| Snapshot present, `subagent` null sentinel or key absent, and the child is **inactive** | diagnostic row, reason `corrupt` (settled debris: a missing, corrupt, or unrecognized-version descriptor, no longer subdivided) |
+| Snapshot present, `subagent` null sentinel or key absent, and the child is **running** | no row (creation window: the descriptor is not yet appended — the same window the old implementation omitted) |
+| The cold full read fails | diagnostic row, reason `unavailable` |
+
+- `unsupported` is no longer produced: the type and the wire enum retain the member under "data structures stay as they are", and this note records it as no longer produced.
+- Descriptor-less settled debris moves from the old implementation's omit into the `corrupt` diagnostic — damaged, dead child sessions in the corpus are visible rather than silently vanishing, which is exactly the original motivation for keeping diagnostics.
+- Any registered unit whose fold/schema throws on this child's log is likewise contained as that child's diagnostic row, reason `corrupt` — a deterministic data fault, aligned with the old implementation's `SESSION_QUERY_CORRUPT_SESSION`→`corrupt` mapping semantics; live and cold are treated alike, isolation is per-child, and siblings and the listing itself are unaffected. It is orthogonal to "value absent + running → omit": the creation window means "no data yet", a fold throw means "the data is bad" — a poisoned running child also gets a `corrupt` row rather than an omit.
+
+Known boundary deviations (deliberately accepted, recorded with this note):
+
+- A fork child that died in its publication window, with an ancestor descriptor in its seed, gets the ancestor identity from last-wins and wrongly surfaces as a child row; resume still fails against the own-suffix fold authority (`NOT_RESUMABLE`). The old implementation omitted it via `seedLength` filtering; the projection unit cannot see the header, and this debris-grade deviation is accepted (`subagentTiming` has the same kind of pre-existing exposure).
+- Multiple descriptors in the own suffix: the old implementation judged corrupt; last-wins now takes the final one (the provider contract guarantees exactly one anyway).
+- A live/persisted header conflict: the old implementation made it per-child corrupt; enumeration now prefers live with no consistency check, the conflict goes unnoticed, and the live record forms the row.
+- A source-read failure on damaged storage (e.g. a bad surface rejected by the cold full read): the old implementation mapped it to per-child `corrupt`; it is now uniformly an `unavailable` row (the read side cannot tell the causes apart).
+- An unknown parent: the old implementation threw not-found through session-query ('parent session … was not found'); the subagent-owned merge now yields an empty subset for a nonexistent parent, enumeration returns an empty list, and later operations on the wire land as child-level subagent-not-found — a silent change of semantics and wording, recorded as explicitly accepted.
+- Rung 2's later-event window: a cache row lands right after the first own descriptor, the log then appends a second own descriptor (or a malformed payload setting the null sentinel), and the process crashes before the next checkpoint — from then on a cold listing's rung 2, admitted by the seq≥seedLength gate, keeps serving the row's old identity (the first own descriptor's value), diverging from the authoritative refold (last-wins, the second), and a rung-2 hit triggers no refold, so nothing notices. Three boundaries: ① the precondition is a second own descriptor on the same child, violating the establishing provider's append-exactly-once contract — corruption-class data, same family and source as the multi-descriptor deviation; ② it takes both "corruption + a crash missing every checkpoint (the two mandatory points, turn/end and disposal, and the count/interval throttle points all unmet)" at once; ③ a healthy child (exactly one own descriptor) is unaffected — what the seq gate admits is precisely the only true identity. Self-healing: any live run of that child (the turn/end mandatory checkpoint) or any moment that triggers cache.write overwrites the whole row with a fresh fold (whole-record replace), and rung 2 serves correctly from then on; the authoritative paths (the rung-3 refold, the live snapshot, the resume fold) are correct from the start, and the divergence exists only in listing reads while the child stays cold and the row is never rewritten. The mechanical fixes were not taken: gate reconciliation would need the log-end seq, unavailable to a zero-read cold path; a cache row carrying the revision is an opaque token, incomparable and a cross-domain schema change — filed as accepted under the "the cache is never authoritative" doctrine.
+
+Consuming surfaces: diagnostic handling across wire, tool, and GUI **stays entirely as it was, zero changes** (the `list_agents` description and output schema are untouched; the plugin only narrows its load requirement — `sessionQuery` dropped from inject). The only behavioral changes are in apiproxy: on the route segment, the `hasSubagentDescriptor()` scan is deleted and `hasSubagentOwner` looks only at `header.origin` — pre-#1569 data without `origin` is no longer recognized as a subagent owner; it never entered the catalog anyway, and the pre-release stance accepts this; and `subagents.history` is aligned with `session.history`'s source — a live child served from in-memory events and the registry's watermark snapshot, a cold child from `inspectServable` reading persistence directly with a detached fold, no query service involved, the SESSION_QUERY_* error arms retired with it, and the wire shape unchanged (the `history` JSDoc wording becomes the live in-memory snapshot / cold persisted log dual arm).
+
+### Change footprint
+
+| Area | Files | Change |
+| --- | --- | --- |
+| subagent | projection.ts, projection-types.ts, index.ts | New `subagent` unit and its registration |
+| subagent | list-children.ts and its types | Rewritten as subagent-owned enumeration plus the projection-ladder four-state mapping; the session-query dependency, per-child event reads, and in-place classification machinery deleted; error code `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` replaced by `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`; new optional dependency dsh-session-projection-cache (pure read acceleration, skipped when absent) |
+| host/apiproxy | api-proxy.ts | `hasSubagentDescriptor` deleted; the owner check looks only at `header.origin`; `subagents.history` shares `session.history`'s source — live from in-memory events and the registry's watermark snapshot, cold from `inspectServable` reading persistence directly with a detached fold, no query service, the SESSION_QUERY_* error arms retired with it |
+| tool | tool-subagent-control/list-agents.ts | Load requirement narrowed (`sessionQuery` dropped from inject); model-visible schema, description, and rendering unchanged |
+| wire/client | api/subagents.ts, runtime sessions/service.ts, GUI | Types, row shape, and diagnostic handling **unchanged**; api/subagents.ts only reworded the `history` JSDoc to the dual arm |
+| core/session, session-persistence, session-projection(-cache), session-query(-sqlite) | — | **Zero changes** |
+
+## Alternatives considered
+
+**mode/label into SessionHeader.** The strongest zero-read guarantee — rows form from the header alone. But a header shape change propagates into both persistence backends and the header compatibility check; SQLite rejects pre-existing data outright, and JSONL pre-existing data can only degrade to unknown or be backfilled. Read-time computation's answer for pre-existing data is "one `inspect` computation on first listing", touching no durable format.
+
+**The projection-cache ladder (v3 draft: `cachedSnapshot ?? coldSnapshot` plus fail-soft write-back).** The mechanism works — session-projection-cache's checkpoint ladder is designed for cold reads in the first place. But checkpoint write-back is a whole list-driven body of derived-data persistence and invalidation orchestration (floor/identity/putSoft); what was rejected is that orchestration as the primary mechanism. The settled three-rung ladder later reuses this cache opportunistically, read-only, as its second rung — no write-back, no orchestration, skipped when absent.
+
+**A bounded-read primitive on persistence to rescue pre-existing data.** Opens a new seam primitive for a one-time problem; superseded by the read-time `inspect` full read — the full read the first time pre-existing data is listed is itself the value retrieval.
+
+**Optional mode/label on list rows (one v4 draft).** Healthy data is always computable; optionality merely spills garbage-data handling complexity onto every consumer — each consuming surface has to grow filter branches and an unknown display state. The strong contract plus omit-when-uncomputable is cleaner.
+
+**Deleting diagnostic rows outright (one v5 draft).** Deletion turns corpus-corruption visibility into rows silently vanishing, and wire/tool/GUI would each have to absorb contract and snapshot changes; retention only asks the list side to derive the classification from projection-value absence and activity, at zero cost. That damaged, dead child sessions in the corpus must be visible is the original motivation for diagnostics' existence, and with retention the consuming surfaces stay wholly unchanged.
+
+**A registry computation failure channel (per-unit fault tolerance plus a supplementary `failures` field).** To report corruption and unrecognized versions to consumers, we once considered having the registry catch unit exceptions and attach a per-key failure state beside the snapshot. Rejected: a failure is not a value and needs no channel — a unit never throws, absence is itself the signal, worst case the computation comes back empty, and how that is presented is the consumer's problem. The discussion of this route left one independent observation behind: the vendored Cordis `emit` ([vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)) catches nothing a listener throws, so with the projection driver hanging off `session/event`, a unit exception would escape along emit — which adds weight to the "a unit never throws" discipline, but fixing emit fault tolerance is outside this note's scope.
+
+**Values landed with query index preparation (the v4/v5 settled design, built for a time).** Projection values folded into session index rows during the sqlite backend's reconciliation rebuild, for zero log reads in the steady read state; the `projectionsFor` bulk read face, the invalidation reconciliation of row values stored against the `(key → stateVersion)` registration set, and the SCHEMA bump were all actually built. Retired wholesale: the direction was backwards — query infrastructure was forced to learn domain vocabulary (projection columns, registration-set reconciliation) while the sole consumer, the subagent list, is satisfied by read-time computation; with consumers down to zero, this derived persistence has no reason to exist. `SESSION_QUERY_PROJECTIONS_UNAVAILABLE` was deleted along with the read face.
+
+**Subagent hand-rolled parsing plus an in-process memo plus creation seeding (v6 draft).** To excise the session-query dependency, we once considered the subagent package parsing descriptor events itself, avoiding repeated full reads with an in-process memo, and seeding initial values at creation. Superseded by the v7 ladder: live goes through the `sessionProjections` watermark cache and cold through `registry.restore`, reusing the registry's single fold authority — no second copy of descriptor-interpretation logic appears, and no process-state cache or seeding ordering is introduced.
+
+**DeepReadonly on the session-query output surface (a read-path overhaul experiment).** Make the public query outputs deeply readonly to pin immutable borrowing at the type level. Rejected on evidence: 3 TS2589 occurrences (excessively deep type instantiation) plus 17 sites of array-position contagion (consumers' array methods and spread sites forced to follow); deep immutability is guaranteed by core/session's runtime deep freeze, and that read-path overhaul is not part of this note.
+
+## Verification
+
+`packages/subagent/subagent/tests/list-children.spec.ts` is rewritten to this contract: live-only listing without persistence, query services, or the continuation runtime; with the registry absent, even zero children loudly report `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`; a live child incurs zero `inspect` throughout while a cold child incurs exactly one per listing; multiple descriptors resolve last-wins to the final one; corrupt payloads and unknown versions fold to `corrupt`; a cold-read failure maps to `unavailable` and retries on the next listing; the ancestor descriptor in a fork seed forms a row under that identity (pinning deviation one); ordinary forks and descendants without a subagent origin neither enter the list nor count toward `hasChildren`; `createdAt`-then-id ordering; an unmounted provider does not affect listing; compacted and uncompacted twins list identically; the three cases of pre-abort, persistence listing, and cold-read cancellation all normalize to `CANCELLED`; the empty list and stable error codes. A hostile-unit dual-path probe (`apply` lazily poisons, `view` detonates) proves that any registered unit's fold/schema throw on this child's log is contained as that child's `corrupt` row on both the live and the cold retrieval paths, with siblings and the listing itself unaffected. Second-rung cases: an own-seq identity used directly with zero `inspect`, a fork seed's ancestor identity (seq inside the seed range) rejected by the gate and falling through, an in-row identity absence (null sentinel or absent key) falling through, an absent cache service falling through, and a poisoned cache row silently falling through to the refold; cold-path lifecycle tampering degrades to `corrupt` field by witness field (`it.each` over the seven). The `tool-subagent-control` list-agents tests are updated for the narrowed load requirement; `optional-session-query.spec.ts` is deleted with the dependency it guarded; the existing keyless snapshots (`subagent-list-agents` among others) are unchanged, pinning that the healthy path's wire and model-visible surfaces did not move; a new keyless snapshot, `subagent-diagnostic` (examples/headless-agent), pins the four-state mapping's diagnostic classification — the model-visible changes such as descriptor-less settled debris becoming a `corrupt` row.
+
+## Consequences
+
+- Listing a live child reads zero log throughout; with the cache unmounted or missed, a cold child pays one full `inspect` read per listing, at a cost proportional to its transcript size and repeated with listing frequency — compute-and-discard is the settled stance: no cache of its own is built, nothing is written back, and short-term repeated full reads of the same id can hit the preparation-phase LRU, though listing does not depend on it.
+- The subagent list no longer requires a query backend: both pure-live and persistence-less deployments can list; `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` is gone, and loading the `list_agents` plugin no longer requires `sessionQuery`.
+- Identity interpretation exists only in the single unit registered with the registry: the list's three-rung ladder and GUI history's cold read all use the registry's and the cache's existing reads (snapshot, cachedSnapshot, restore), and no bypass fold exists; if some future consuming surface bypasses the registry with a hand-written fold, values will drift across read faces — a discipline this design requires be maintained, not a mechanical guarantee.
+- Per-child isolation is back: a single child's cold-read failure loses only that row and healthy siblings are unaffected; a persistence listing failure still fails the whole enumeration.
+- The diagnostic and enumeration semantics leaves six boundary deviations (a stillborn fork surfacing under its ancestor's identity, multiple descriptors resolving to the last, header conflicts going unnoticed, damaged-source read failures shifting from `corrupt` to `unavailable`, an unknown parent yielding an empty list instead of not-found, and rung 2's later-event window); the full semantics is in the known-boundary-deviations list; the first four are display or classification deviations on debris-grade data, the unknown-parent one is a silent query-semantics change, and the rung-2 window is a self-healing cache-serving divergence under the double condition of corruption plus a crash; resume authorization is unaffected throughout, all explicitly accepted.
+- Pre-#1569 data without `origin` is no longer recognized as a subagent owner; it never entered the catalog anyway, and pre-release carries no compatibility promise.
+
+## Related
+
+- [Durable subagent catalog and list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) — partially superseded by this note: the descriptor remains the durable authority for mode/label and the fold input, while the list's enumeration and value retrieval move to the subagent-owned merge plus the projection ladder.
+- [Session projections and command lifecycle logging](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md) — the authority for the registry contract; this note adds the `subagent` identity unit to it and becomes a consumer instance of the two existing reads, snapshot and restore.
+- [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md) — the origin of `SessionHeader.origin` (#1569), the first half of taking identity determination off the log; its history cold read (inspect prefix plus registry fold) is the same-shape precedent for this note's value ladder.
+- [Reusable Session preparation before publication](2026-08-05-session-preparation.md) — the `inspect()` cold read and LRU reuse; the cold child's full-read cost model builds on it.
diff --git a/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
new file mode 100644
index 0000000000..368a70f5b3
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md
@@ -0,0 +1,184 @@
+# Agent Note: subagent 列表经投影单元读取身份
+
+Status: implemented
+
+[English](2026-08-06-subagent-list-identity-projection.md) | 中文
+
+## 问题
+
+重写前的 `SubagentService.listChildren` 对每个 `header.origin === 'subagent'` 的直接 child，每次列表都执行 `listEvents` 加 `readEvent` 两次整日志物化，且每次物化都伴随整日志 structuredClone，只为从描述符事件里折出 mode 与 label 两个字段。描述符在日志中的位置不固定——fork 前缀任意长，zstd 压缩帧没有 seq 索引——因此定位没有捷径；这条路径没有任何缓存，代价随 transcript 长度 × child 数量 × 列表频率放大。它还把 session-query 拉成列表的硬依赖：没有 query backend 的部署，`list_agents` 以 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 整体拒绝，尽管枚举所需只是 header 事实。
+
+同一根因还有第二个症状：host 侧的 `hasSubagentDescriptor()` 在每次 Agent 绑定 RPC 的属主判定上扫描目标会话的 own suffix，即便 `SessionHeader.origin` 已经回答了同一个问题的绝大部分。
+
+根因在于 [durable-subagent-catalog 决策](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)把描述符事件（`subagent/descriptor`）定为目录的唯一持久权威，却没有为描述符读取配任何缓存层，并把逐 child 双读明确接受为"无索引的正确性基线"。[web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)（#1569）已把"是不是 subagent"放进了 header（`SessionHeader.origin`），身份判定不再读日志；mode 与 label 仍然要扫。
+
+## 决策
+
+mode 与 label 由新的 `subagent` projection unit（纯身份两臂）折叠，unit 是折叠规则的唯一权威；`listChildren` 不再依赖 session-query——枚举是 subagent 自管的 live-preferred 合并，取值走三级"算完即止"阶梯：live child 同步读注册表的既有水位缓存（零日志读）；cold child 先问可选的 `sessionProjectionCache` checkpoint，取到过 seq 门的身份即定值；否则一次 `persistence.inspect` 整读加 `registry.restore` 折叠。无索引、不自建缓存、无回写。
+
+消除逐 child 扫描的出路有三类：把 mode/label 提升进 header（写路承担）；为投影建持久派生（checkpoint 阶梯，或随查询索引重建落值、读端对账）；读时现算（live 走水位缓存，cold 一次整读）。本记录取第三条。"值随查询索引落库"曾是本记录的定稿方向并一度施工，最终整体退役：查询基础设施被迫认识领域词汇，而唯一消费方读时现算即可满足——live child 的零读由 session-projection 既有水位缓存白拿，cold child 的一次整读被"算完即止"显式接受。前两条与退役理由详见考虑过的替代方案一节。
+
+要点：
+
+- **subagent 列表不依赖 session-query**：枚举由 subagent 自管的 live-preferred 合并完成，mode/label 经 `ctx.sessionProjections` 取值；没有 query backend 的部署照常列表。
+- **取值三级"算完即止"阶梯**：live child 读 `sessionProjections.snapshot()`（注册表既有水位缓存，零日志读）；cold child 先读可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 且过 seq 门（`seq >= seedLength ?? 0`）的 `subagent` 身份即直接用；否则一次 `persistence.inspect` 整读加 `registry.restore({}, events, 0)` 折叠；再没有就没有——不自建缓存、无回写、无索引。
+- **`subagent` projection unit 是折叠规则唯一权威**：live snapshot、cold restore、GUI history 的 detached 折叠全部经 registry 计算，不存在第二份描述符解释逻辑。
+- **header、描述符（v2）、session-persistence、session-projection(-cache)、session-query(-sqlite) 全部零改动**；存量数据第一次被列表时一次 `inspect` 现算获得精确值，无 unknown 降级态、无迁移。
+
+与既有记录的关系：
+
+- 本记录取代 [durable-subagent-catalog](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md) 中列表读路径的两项设计：经 `sessionQuery.traceSession` 枚举，与逐 child 读取描述符事件（`listEvents` 加精确 `readEvent` 双读、就地诊断分类）。diagnostic 行语义保留，分类改由列表按投影值缺席与 activity 派生；描述符事件仍是 mode/label 的唯一持久权威与折叠输入，恢复鉴权与激活契约不动。属部分取代，两记录保持交叉链接。
+- [session-projection RFC](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md) 的 registry 契约（`ProjectionDefinition`、`snapshot`、`restore`）零改动，本记录只为其新增 `subagent` 身份 unit 一个注册项，并成为 snapshot（live）与 restore（cold）两处既有读法的又一消费实例——GUI history 的冷读已是同款。折叠规则只在 registry 注册一份；任何消费面都经 registry 计算，不存在第二份折叠逻辑。
+
+### `subagent` projection unit
+
+挂在现有 `subagentTiming` 旁（[projection.ts](../../../../packages/subagent/subagent/src/projection.ts)、[projection-types.ts](../../../../packages/subagent/subagent/src/projection-types.ts)），key 为 `subagent`：
+
+```ts ignore-check
+export type SubagentIdentityProjection =
+  | { mode: 'one-shot'; label?: string; seq: number }
+  | { mode: 'continuable'; label: string; seq: number }
+
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    subagent: SubagentIdentityProjection | null
+  }
+}
+```
+
+- 投影是纯身份，**projection 体系不做失败通道**：unit 永不抛错；载荷损坏、版本不认识与整日志没有描述符一样，折叠结果是**可序列化的 null 哨兵**——map 条目为 `SubagentIdentityProjection | null`，非可选、非 undefined/缺 key。理由：registry 的 onChanged 推送经 JSON 序列化，undefined 字段被 stringify 丢弃，客户端帧校验拒收，消费方存储的旧身份将永不更新；null 完好过帧，消费方以哨兵替换旧身份。判定纪律：消费面把 null 与 undefined（仅 JSON 边界丢 key 可产生）一律视为无值。"算出来没有"如何呈现是消费方自己的事（见下文 `listChildren` 四态映射）。
+- label 强度由描述符 schema 决定：continuable 的 label 解析强制必有，one-shot 的本就可选；mode/label 判别与下文 child 行的强契约完全一致（行不携带 `seq`——它是投影内部的 own-suffix 证明）。
+- 身份携带 `seq`：折出该身份的 `subagent/descriptor` 事件 seq，两臂必有、null 哨兵无——`seq >= header.seedLength ?? 0` 证明身份折叠自 child 自身后缀，而非 fork 种子回放的祖先描述符。state 增 `seq` 使 unit `stateVersion` 升至 2，既存 checkpoint 行按 registry 契约版本失配失效、落权威重折。
+- 折叠规则：`subagent/descriptor` last-wins，与 `subagentTiming` 同一条 descriptor-reset 纪律——fork 前缀里的祖先描述符被自身描述符覆盖。损坏或版本不认识的载荷同样 last-wins：重置为 null 哨兵而非保留先前身份，健康祖先的 fork 不会继承自身描述符立不住的身份。
+
+### 枚举：subagent 自管 live-preferred 合并
+
+`listChildren`（[list-children.ts](../../../../packages/subagent/subagent/src/list-children.ts)）的枚举不经任何查询服务：`ctx.sessions.list()` 与 `ctx.get('sessionPersistence')?.list()` 两个来源按 id 合并，live 记录整条覆盖同 id 持久化记录、不做 header 一致性校验。枚举所需全部是 header 事实：
+
+- 过滤：`header.origin === 'subagent' && header.parentSession === parentSessionId`。
+- `hasChildren`：同一份合并材料向下看一层——存在 `origin === 'subagent'` 且 `parentSession` 为该 child 的直接后代。
+- `activity`：live 记录为 `running`，仅存在于持久化的为 `inactive`。
+- 排序：`createdAt` 升序、再按 child id 升序（与旧契约一致）。
+- **persistence 缺席退为 live-only 枚举，不报错**：没有 persistence 的部署，cold child 本就无法 resume，列出 live child 仍然有意义。（对照：旧实现在 sessionQuery 缺失时整体拒绝。）
+- persistence 列表失败使整次枚举失败；per-child 隔离只作用于逐 child 的冷读。
+
+### 取值：三级"算完即止"阶梯
+
+对每个枚举出的 child，mode/label 取值走三级阶梯——算完即止，不自建缓存、无回写（第三级与 apiproxy `session.history` 的冷读同款）：
+
+| 级 | 读法 | 成本 |
+| --- | --- | --- |
+| 1：live child | `ctx.sessionProjections.snapshot(session).values.subagent` | 零日志读——注册表既有水位缓存，同步取值 |
+| 2：cold child，cache 命中 | 可选 `sessionProjectionCache.cachedSnapshot(header)`，values 含非 null 的 `subagent` 身份且 `identity.seq >= header.seedLength ?? 0` 才直接用——own descriptor 一经追加不可变，seq 门证明该值折叠自 child 自身后缀，无视行水位 | 零日志读 |
+| 3：cold child，兜底 | `persistence.inspect(id)` 整读 + `registry.restore({}, events, 0).snapshot.values.subagent` | 每次列表一次整读现算 |
+
+- 错误契约：`ctx.sessionProjections` 未挂载是配置错误，`listChildren` 在枚举前无条件检查并以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败——零 children 的部署同样确定失败，不因列表恰好为空而掩盖配置问题。会话存储同理：`ctx.get('sessions')`（严格全局读取，不走调用方作用域的属性代理）缺席以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 失败。两码的 wire 映射有别：apiproxy 只为 `PROJECTIONS_UNAVAILABLE` 设专门 wire 脸，`SESSION_STORE_UNAVAILABLE` 走通用 internal 兜底——apiproxy 组合自身就 inject `sessions`，该错误在其部署不可达，专门映射违反 need 原则。`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 已随 session-query 依赖删除。
+- cache 是纯可选加速层：服务缺席判空跳过——无错误码、不进配置校验（与 `sessionProjections` 的响亮契约相对）。第二级任何抛错（包括缓存内任一 unit 行中毒使 `viewCheckpoint` 引爆）静默落第三级——缓存是派生数据，其故障不产生 `corrupt` 判决，终审归权威重折；checkpoint 切面早于描述符的行，`subagent` key 天然缺席，自动落底，无特判；行里的 null 哨兵同样不作数——一律落第三级，由权威重折裁决。创建窗口内的 count/interval checkpoint 可能把 fork 种子回放的祖先身份落进行——祖先 seq 落在 seed 区间，被 seq 门拒绝，同样落第三级裁决。
+- per-child 隔离：单 child 的 cold 整读失败只使该行成为 `unavailable` diagnostic，下次列表自然重试，不影响 sibling（见四态映射）。
+- 冷路径的生命周期见证：preparation 的结果必须仍指向枚举时的那个生命周期——见证字段集与旧 SOURCE_CONFLICT 检查同款七字段（version、id、createdAt、cwd、parentSession、seedLength、delegationDepth）；同 id 删除后重新发布的会话对旧 parent 的目录降级为 `corrupt` 行，不外漏新 owner 的 child。
+- 冷读并发以常数 4 有界——它约束的是本地介质的一次只读扫描而非部署行为；出现联网 persistence backend 时提升为验证过的 `Config` 字段。
+- 冷读成本如实记录：cache 未挂载或未命中时，cold child 每次列表才付一次整读，成本与其 transcript 大小成正比；定案"算完即止"，不自建缓存。整读经 `inspect()` 走 [Session 准备阶段](2026-08-05-session-preparation.md)的冷读，同 id 短期重复读取可命中其 LRU 复用，但列表不依赖此。live child 全程零日志读。
+- 取消：每次 persistence 读前后检查调用方 signal，abort 之后才结算的读拒绝归一化为稳定错误码 `CANCELLED`。
+
+### 权威模型
+
+- session log 是唯一权威；本方案不新增任何派生持久化——没有索引值、没有自己的 checkpoint、没有进程 memo；第二级读取的 `sessionProjectionCache` checkpoint 是既有组合项的派生数据，本方案只读不写。取值现算现弃，值的新鲜度就是读取时点的 live 状态或持久化 revision（own descriptor 一经追加不可变——缓存身份过 seq 门后无陈旧性问题，门防的是种子回放的祖先身份）。
+- Session 与 persistence 写路完全不感知列表与投影消费：没有事件监听回写，没有写时折叠。
+- 枚举与取值不构成第二个鉴权来源，也不让尚未发布的 child 可见——两个来源只见已发布的 live 记录与已落盘的持久化记录，与 durable-subagent-catalog 记录对派生读面立下的规则一致。
+
+### `listChildren` 行形状与消费面
+
+`SubagentListEntry` **数据结构与重写前完全一致**——child 与 diagnostic 两臂、`kind` 判别、reason 三值、child 臂的 mode/label 强契约全部保留；变化只在诊断的信息来源：投影体系没有失败通道，diagnostic 由列表按投影值缺席与 activity 派生，列表本身零事件解析。"没有就等待硬读取"保证阶梯对健康数据必然算得出 mode/label。
+
+```ts ignore-check
+export type SubagentListEntry =
+  | ({
+    readonly kind: 'child'
+    readonly id: SessionId
+    readonly activity: 'running' | 'inactive'
+    readonly hasChildren: boolean
+  } & (
+    | { readonly mode: 'one-shot'; readonly label?: string }
+    | { readonly mode: 'continuable'; readonly label: string }
+  ))
+  | {
+    readonly kind: 'diagnostic'
+    readonly id: SessionId
+    readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
+  }
+```
+
+对每个枚举出的 child，阶梯取值结果按四态映射成行：
+
+| 阶梯取值结果 | 行 |
+| --- | --- |
+| 快照含非 null 的 `subagent` 身份 | child 行 |
+| 快照在、`subagent` 为 null 哨兵或 key 缺席，且 child **inactive** | diagnostic 行，reason `corrupt`（定局残骸：无、损坏或版本不认识的描述符，不再细分） |
+| 快照在、`subagent` 为 null 哨兵或 key 缺席，且 child **running** | 行不出现（创建窗口：描述符尚未追加，与旧实现同窗口 omit） |
+| cold 整读失败 | diagnostic 行，reason `unavailable` |
+
+- `unsupported` 不再被产出：类型与 wire 枚举按"数据结构保持现状"留存该成员，本记录留档其为不再产出。
+- descriptor-less 定局残骸从旧实现的 omit 归入 `corrupt` diagnostic——库里的坏、死子会话可见，不静默消失，这正是保留 diagnostic 的原始动机。
+- 任一注册 unit 的 fold/schema 在该 child 日志上抛错，同样收纳为该 child 的 diagnostic 行，reason `corrupt`——确定性数据故障，对齐旧实现 `SESSION_QUERY_CORRUPT_SESSION`→`corrupt` 的映射语义；live 与 cold 同待遇，逐 child 隔离，sibling 与列表本身不受影响。它与「无值 + running → omit」正交：创建窗口是"尚无数据"，fold 抛错是"数据坏了"——running 的中毒 child 也出 `corrupt` 行而非 omit。
+
+已知边界偏差（有意接受，随本记录留档）：
+
+- 死于发布窗口的 fork child，seed 里若有祖先描述符，last-wins 会给出祖先身份，误现为 child 行；恢复仍按 own-suffix 折叠权威失败（`NOT_RESUMABLE`）。旧实现靠 `seedLength` 过滤将其 omit；projection unit 看不到 header，接受此残骸级偏差（`subagentTiming` 有同类既有暴露）。
+- own suffix 出现多个描述符，旧实现判 corrupt，现 last-wins 取末者（provider 契约本就保证恰一）。
+- live/persisted header 冲突，旧实现是 per-child corrupt；现枚举 live 优先、不做一致性校验，冲突不再被察觉，以 live 记录成行。
+- 损坏存储的源读失败（如坏 surface 被冷读整读拒收），旧实现映射 per-child `corrupt`，现统一成 `unavailable` 行（读侧无从区分成因）。
+- 未知 parent，旧实现经 session-query 抛 not-found（'parent session … was not found'）；现自管合并对不存在的 parent 得到空子集，枚举返回空列表，wire 上后续操作落到 child 级 subagent-not-found——语义与文案的静默变化，显式接受。
+- rung 2 的更晚事件窗口：cache 行恰在首个自有描述符之后落盘，日志随后追加第二个自有描述符（或 malformed 载荷置 null 哨兵），且进程在下一次 checkpoint 前崩溃——此后冷列表的 rung 2 凭 seq≥seedLength 门持续供出行内旧身份（第一个自有描述符的值），与权威重折（last-wins 第二个）分歧，且 rung 2 命中期间不触发重折、无从察觉。边界三条：①前提是同一 child 出现第二个自有描述符，违反 establishing provider"恰追加一次"契约，属损坏类数据，与多描述符偏差同族同源；②需"损坏 + 崩溃错过 checkpoint（turn/end 与 disposal 两个 mandatory 点及 count/interval 节流点全部未及）"双条件同时成立；③健康 child（恰一自有描述符）不受影响——seq 门放行的正是唯一真身份。自愈条件：该 child 任一次 live 运行（turn/end mandatory checkpoint）或任何触发 cache.write 的时点，都会以新 fold 整行覆写（whole-record replace），rung 2 随即供正；权威路径（rung 3 重折、live snapshot、resume 折叠）自始正确，分歧只存在于持续冷、行未再更新期间的列表读。机制修法不采：gate 对账需知日志末端 seq，冷路径零读不可得；cache 行携 revision 是 opaque token，无法比较且跨域改 schema——按"cache 永不为权威"总纲归档为接受项。
+
+消费面：wire、tool、GUI 的 diagnostic 处理**全部保持原状零改动**（`list_agents` 的 description 与 output schema 未动；该插件仅加载要求收窄——inject 去掉 `sessionQuery`）。行为上动的只有 apiproxy：路由段的 `hasSubagentDescriptor()` 扫描已删除，`hasSubagentOwner` 只看 `header.origin`——pre-#1569 的无 `origin` 存量不再被认作 subagent 属主，其本就不进目录，pre-release 立场接受；`subagents.history` 与 `session.history` 同源对齐——live child 用内存事件与注册表水位快照，cold child 用 `inspectServable` 直读持久化并 detached 折叠，不经查询服务，SESSION_QUERY_* 错误臂随之退役，wire 形状不变（`history` 的 JSDoc 措辞改为 live 内存快照／cold 持久日志双臂）。
+
+### 改动落点
+
+| 区域 | 文件 | 改动 |
+| --- | --- | --- |
+| subagent | projection.ts、projection-types.ts、index.ts | 新 `subagent` unit 与注册 |
+| subagent | list-children.ts 及类型 | 重写为自管枚举 + 投影阶梯四态映射；删 session-query 依赖、逐 child 事件读取与就地分类机器；错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 换 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`；新增可选依赖 dsh-session-projection-cache（纯加速读取，缺席跳过） |
+| host/apiproxy | api-proxy.ts | 删 `hasSubagentDescriptor`，属主判定只看 `header.origin`；`subagents.history` 与 `session.history` 同源——live 用内存事件与注册表水位快照，cold 用 `inspectServable` 直读持久化并 detached 折叠，不经查询服务，SESSION_QUERY_* 错误臂随之退役 |
+| tool | tool-subagent-control/list-agents.ts | 加载要求收窄（inject 去 `sessionQuery`）；model-visible schema、描述与渲染零改动 |
+| wire/client | api/subagents.ts、runtime sessions/service.ts、GUI | 类型、行形状与 diagnostic 处理**零改动**；api/subagents.ts 仅 `history` 的 JSDoc 措辞改为双臂 |
+| core/session、session-persistence、session-projection(-cache)、session-query(-sqlite) | — | **零改动** |
+
+## 考虑过的替代方案
+
+**mode/label 进 SessionHeader。** 零读保证最强——列表只看 header 就能成行。但 header 形状变更传导两个 persistence backend 与 header 兼容检查；SQLite 存量直接拒收，JSONL 存量只能 unknown 降级或 backfill。读时现算对存量的答案是"第一次列表一次 `inspect` 现算"，不碰持久格式。
+
+**projection-cache 阶梯（v3 稿：`cachedSnapshot ?? coldSnapshot` 加 fail-soft 写回）。** 机制成立——session-projection-cache 的 checkpoint 阶梯本就为冷读设计。但 checkpoint 写回是一套由列表驱动的派生数据持久化与失效编排（floor/identity/putSoft）；被否的是这套编排作为主机制。定稿的第三级阶梯后来以只读方式机会性复用该缓存作第二级——无写回、无编排、缺席即跳过。
+
+**给 persistence 加有界读原语抢救存量。** 为一次性问题新开 seam 原语；被读时 `inspect` 整读取代——存量第一次被列表时的整读就是取值本身。
+
+**list 行 mode/label 可选化（v4 一稿）。** 健康数据必然可算；可选化只是把垃圾数据的处理复杂度外溢给全部消费方——每个消费面都要长出过滤分支和 unknown 展示态。强契约加算不出即 omit 更干净。
+
+**彻底删除 diagnostic 行（v5 一稿）。** 删除把库损坏的可见性外溢为行静默消失，wire/tool/GUI 反要各自承担契约与快照变更；而保留只需列表侧按投影值缺席与 activity 派生分类，零成本。库里的坏、死子会话必须可见是 diagnostic 存在的原始动机，保留后消费面整体零改动。
+
+**registry 计算失败通道（per-unit 容错加 `failures` 附加字段）。** 为把损坏、版本不认识报告给消费方，曾考虑让 registry 捕获 unit 异常并在 snapshot 旁附 per-key 失败态。被否：failure 不是值，也不必是通道——unit 永不抛错，缺席本身就是信号，"大不了算出来没有"，如何呈现是消费方要考虑的事。该路线讨论顺带留下一个独立观察：vendor cordis 的 `emit`（[vendor/cordis/src/events.ts](../../../../vendor/cordis/src/events.ts)）对 listener 抛错零捕获，投影驱动挂在 `session/event` 上时 unit 异常会沿 emit 逃逸——这加重了"unit 永不抛错"纪律的分量，但 emit 容错的修复不属于本记录范围。
+
+**值随 query 索引 preparation 落库（v4/v5 定稿，一度施工）。** 投影值在 sqlite backend 的对账重建里折叠落进 session 索引行，读稳态零日志；`projectionsFor` 批量读面、行值随 `(key → stateVersion)` 注册集存储的失效对账与 SCHEMA bump 均已施工过。整体退役：方向反了——查询基础设施被迫认识领域词汇（投影列、注册集对账），而唯一消费方 subagent 列表读时现算即可满足；消费方归零后，这套派生持久化没有存在理由。`SESSION_QUERY_PROJECTIONS_UNAVAILABLE` 随读面一并删除。
+
+**subagent 手工 parse 加进程 memo 加创建播种（v6 稿）。** 为摘除 session-query 依赖，曾考虑 subagent 自己解析描述符事件、以进程内 memo 避免重复整读、创建时播种初值。被 v7 阶梯取代：live 走 `sessionProjections` 水位缓存、cold 走 `registry.restore`，复用 registry 这一份折叠权威，不再出现第二份描述符解释逻辑，也不引入进程态缓存与播种时序。
+
+**session-query 输出面 DeepReadonly（读路径改造实验）。** 公开查询输出深只读化，以在类型层面钉死不可变借用。实证否决：3 处 TS2589（类型实例化过深）加 17 处数组位传染（消费方数组方法与展开处被迫跟改）；深层不可变由 core/session 的运行时深冻结保证，该读路径改造未纳入本记录。
+
+## 验证
+
+`packages/subagent/subagent/tests/list-children.spec.ts` 重写为本契约：无 persistence、query 服务与继续运行时的 live-only 列表；registry 缺席时零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`；live child 全程零 `inspect`、cold child 每次列表恰一次；多描述符 last-wins 取末者；损坏载荷与未知版本折为 `corrupt`；冷读失败映射 `unavailable` 且下次列表重试；fork seed 里的祖先描述符按该身份成行（偏差一钉住）；普通 fork 与无 subagent origin 的后代不入列也不计入 `hasChildren`；`createdAt`→id 排序；provider 未挂载不影响列表；压缩与未压缩孪生一致；预中止、持久化列表与冷读取消三例归一 `CANCELLED`；空列表与稳定错误码。敌意 unit 双路探针（`apply` 惰性置毒、`view` 引爆）证明任一注册 unit 在该 child 日志上的 fold/schema 抛错，在 live 与 cold 两条取值路径上都收纳为该 child 的 `corrupt` 行，sibling 与列表本身不受影响。第二级例：own-seq 身份直用零 `inspect`、fork 种子祖先身份（seq 落在 seed 区间）被门拒绝落底、行内无身份（null 哨兵或 key 缺席）落底、cache 服务缺席落底、缓存行中毒静默落底重折；冷路径 lifecycle 篡改按见证七字段逐一（`it.each`）降级为 `corrupt`。`tool-subagent-control` 的 list-agents 测试随加载要求收窄更新；`optional-session-query.spec.ts` 随依赖消失删除；既有无密钥快照（`subagent-list-agents` 等）零变化，钉住健康路径的 wire 与 model-visible 面不变；新增无密钥快照 `subagent-diagnostic`（examples/headless-agent）钉住四态映射的诊断分类——descriptor-less 定局残骸成 `corrupt` 行等模型可见变化。
+
+## 后果
+
+- live child 的列表全程零日志读；cold child 在 cache 未挂载或未命中时每次列表一次 `inspect` 整读，成本与其 transcript 大小成正比、随列表频率重复——定案"算完即止"，不自建缓存、不回写，同 id 短期重复整读可命中准备阶段 LRU 但列表不依赖它。
+- subagent 列表不再要求 query backend：纯 live 与无 persistence 的部署都能列表；`SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 消失，`list_agents` 插件加载不再要求 `sessionQuery`。
+- 身份解释只存在于 registry 注册的一份 unit：列表三级阶梯与 GUI history 冷读走的都是 registry 与 cache 的既有读法（snapshot、cachedSnapshot、restore），不存在旁路折叠；若未来某消费面绕开 registry 手写折叠，各读面的值将漂移——这是本设计要求维持的纪律，不是机制保证。
+- per-child 隔离回归：单 child 冷读失败只损失该行，healthy sibling 不受影响；persistence 列表失败仍使整次枚举失败。
+- 诊断与枚举语义留下六处边界偏差（stillborn fork 祖先身份误现、多描述符取末者、header 冲突不再被察觉、损坏源读失败由 `corrupt` 转 `unavailable`、未知 parent 由 not-found 改为空列表、rung 2 更晚事件窗口），完整语义见已知边界偏差清单；前四处为残骸级数据的展示或分类偏差，未知 parent 一处是查询语义的静默变化，rung 2 窗口一处是损坏加崩溃双条件下可自愈的缓存供值分歧；恢复鉴权均不受影响，显式接受。
+- pre-#1569 的无 `origin` 存量不再被认作 subagent 属主；其本就不进目录，pre-release 无兼容承诺。
+
+## 相关
+
+- [durable-subagent-catalog 与 list_agents](../feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)——被本记录部分取代：描述符仍是 mode/label 的持久权威与折叠输入，列表的枚举与取值改为自管合并加投影阶梯。
+- [session projections 与命令生命周期日志](../../proposed/architecture/2026-07-27-session-projection-and-command-log.md)——registry 契约的权威；本记录为其新增 `subagent` 身份 unit，并成为 snapshot/restore 两处既有读法的消费实例。
+- [web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)——`SessionHeader.origin` 的出处（#1569），身份判定去日志化的前半步；其 history 冷读（inspect 前缀加 registry 折叠）是本记录取值阶梯的同款先例。
+- [发布前可复用的 Session 准备阶段](2026-08-05-session-preparation.md)——`inspect()` 冷读与 LRU 复用；cold child 整读的成本模型建立其上。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
index 483bfd9e86..967a0ebcf4 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.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 .agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
-2026-07-28-web-agent-runtime-context.md: 449c9d4ba2b144d02dee4b98ae80c86815aec5c1
-2026-07-28-web-agent-runtime-context.zh.md: def1674be5f193739bfb214a24f34590ee075d5f
+2026-07-28-web-agent-runtime-context.md: 6c2bb8faf0db56d2a29b47726ab295c3501cce2d
+2026-07-28-web-agent-runtime-context.zh.md: 09cbbdeabc244c265381b1ad67c3629b4c0763f5
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
index 449c9d4ba2..6c2bb8faf0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.md
@@ -10,13 +10,13 @@ The shared CLI base configured an empty deployment persona, the Web overlay did
 
 ## Decision
 
-The shared Web/headless overlay (`apps/cli/config/web.cordis.yml`) supplies a concise coding-agent persona containing the resolved `{{model}}` and session `{{cwd}}`. `dsh web` additionally resolves the harness checkout from the launcher's module URL, installs the existing `harness:source` section, and adds an `app:web-surface` section before serving requests. The launcher registers that setup before mounting the config tree; its `systemPrompt` injection therefore installs both sections before later prompt consumers such as the agent loop can activate and emit a request header. The [source-checkout/workdir decision](2026-07-30-source-checkout-workdir-distinction.md) owns the source section's wording and its warning not to infer one path from the other.
+The Web profile composes the `dsh-base` and `dsh-web-app` bundles. The Web bundle supplies a concise coding-agent persona containing the resolved `{{model}}` and session `{{cwd}}`; its `web-runtime` plugin adds the `app:web-surface` section when `surfaceContext` is true. Before mounting the profile tree, the `dsh web` alias reads that same composed setting and installs the existing `harness:source` section only when the surface context is enabled. The headless bundle and a profile that owns its complete prompt set `surfaceContext: false`, suppressing the Web prompt and managed shell facts; the Web alias also suppresses the source section without checking an overlay path. Every mounted prompt contribution still activates before consumers such as the agent loop can emit a request header. The [source-checkout/workdir decision](2026-07-30-source-checkout-workdir-distinction.md) owns the source section's wording and its warning not to infer one path from the other.
 
 The Web section treats unqualified references to “this page,” “this GUI,” or “this app” as references to the DeepSeek Harness Web GUI. It also states that the browser provides no implicit DOM, route, or screenshot context, so the model can identify the product without claiming visual state it did not receive. The assembled text is logged in `request/header`, preserving the model-visible/logged invariant.
 
 ## Verification
 
-The focused startup-order test registers a later `systemPrompt` consumer and proves that it observes both launcher sections on its first activation. The keyless fresh-round-trip Web scenario boots the shipped base plus Web overlay, registers the same launcher context as `dsh web`, runs a real session through the HTTP/SSE application, and snapshots the first four system-prompt sections with source and working-directory paths normalized. The snapshot pins the harness identity, source checkout, Web orientation, and resolved coding-agent persona in request order.
+The Web runtime unit tests pin both enabled and disabled `surfaceContext` behavior, while the Web alias unit test pins default-on and explicit-off source-section gating from the composed row. The keyless fresh-round-trip Web scenario boots the shipped base plus Web bundle, runs a real session through the HTTP/SSE application, and snapshots the system-prompt prefix with source and working-directory paths normalized. The snapshot pins the harness identity, source checkout, Web orientation, and resolved coding-agent persona in request order. The Core Web snapshot applies the RL overlay and pins its complete system prompt with no source or Web section.
 
 ## Alternatives considered
 
@@ -30,4 +30,4 @@ The focused startup-order test registers a later `systemPrompt` consumer and pro
 
 ## Consequences
 
-Web requests gain a short stable prompt prefix and may invalidate provider prefix caches once when this change is deployed. Agents can distinguish the GUI source checkout from the selected Workspace and resolve ordinary references to the current app without a clarification round trip. References to a specific visual state remain bounded by the explicit no-DOM/no-route/no-screenshot statement and may still require a path, description, or attachment.
+Ordinary Web requests gain a short stable prompt prefix and may invalidate provider prefix caches once when this change is deployed. Agents can distinguish the GUI source checkout from the selected Workspace and resolve ordinary references to the current app without a clarification round trip. References to a specific visual state remain bounded by the explicit no-DOM/no-route/no-screenshot statement and may still require a path, description, or attachment. Complete-prompt profiles can opt out through the Web runtime's composition setting without a launcher path check.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
index def1674be5..09cbbdeabc 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-agent-runtime-context.zh.md
@@ -10,13 +10,13 @@ CLI 共享 base 配置了空的部署 persona，Web overlay 没有替换它，
 
 ## 决策
 
-`apps/cli/config/web.cordis.yml` 这份 Web／无头共享 overlay 提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`。`dsh web` 还会根据启动器模块的 URL 解析 harness checkout，安装现有的 `harness:source` 提示词段，并在对外提供请求服务前添加 `app:web-surface` 提示词段。启动器会在挂载配置树前注册这项设置；因此，它的 `systemPrompt` 注入会在 agent loop（智能体循环）等后续提示词消费方激活并发出 request header 之前安装这两个提示词段。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
+Web profile 会组合 `dsh-base` 与 `dsh-web-app` 两个组合包。Web 组合包提供一段简洁的编码 agent persona，其中包含解析后的 `{{model}}` 与会话 `{{cwd}}`；当 `surfaceContext` 为 true 时，其 `web-runtime` 插件会添加 `app:web-surface` 提示词段。挂载 profile 配置树前，`dsh web` 别名会读取组合后的同一项设置，并且仅在启用表层上下文时安装现有的 `harness:source` 提示词段。无头组合包和拥有完整提示词的 profile 都会设置 `surfaceContext: false`，从而抑制 Web 提示词与受管 shell 事实；Web 别名也会抑制源码提示词段，而无需检查 overlay 路径。每项已挂载的提示词贡献仍会在 agent loop（智能体循环）等消费方发出 request header 前激活。源码提示词段的措辞，以及其中不得从一条路径推断另一条路径的警告，均由另行记录的[源码 checkout 与工作目录区分决策](2026-07-30-source-checkout-workdir-distinction.md)负责。
 
 Web 提示词段把未限定的「这个页面」「这个 GUI」或「这个应用」解释为 DeepSeek Harness Web GUI。同时，它会明确说明浏览器不会隐式提供 DOM、路由或截图上下文，使模型能够识别产品，但不会声称掌握未收到的视觉状态。组装后的文本会记录在 `request/header` 中，从而保持「模型可见内容必须有日志记录」这一不变量。
 
 ## 验证
 
-聚焦启动顺序的测试会注册一个后续的 `systemPrompt` 消费方，并证明该消费方首次激活时就能观察到启动器的两个提示词段。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web overlay，注册与 `dsh web` 相同的启动器上下文，并通过 HTTP／SSE 应用运行一个真实会话。测试会把源码路径和工作目录规范化，然后对系统提示词的前四个段落生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。
+Web 运行时单元测试会固定启用和禁用 `surfaceContext` 时的行为，Web 别名单元测试则会固定组合后配置行对源码提示词段的默认启用与显式禁用门控。无密钥的 Web fresh-round-trip 场景会启动已交付的 base 与 Web 组合包，通过 HTTP／SSE 应用运行一个真实会话，并在规范化源码路径与工作目录后对系统提示词前缀生成快照。该快照按请求顺序固定 harness 身份、源码 checkout、Web 界面定位，以及解析后的编码 agent persona。Core Web 快照会应用 RL overlay，并固定不含源码提示词段或 Web 提示词段的完整系统提示词。
 
 ## 考虑过的替代方案
 
@@ -30,4 +30,4 @@ Web 提示词段把未限定的「这个页面」「这个 GUI」或「这个应
 
 ## 影响
 
-Web 请求会增加一段较短且稳定的提示词前缀；部署此变更时，模型提供方的前缀缓存可能失效一次。agent 可以区分 GUI 源码 checkout 与所选 Workspace，并且无需再经过一轮澄清即可解析对当前应用的一般指代。对特定视觉状态的指代仍受「无 DOM／无路由／无截图」这一显式边界约束，必要时仍需用户提供路径、描述或附件。
+常规 Web 请求会增加一段较短且稳定的提示词前缀；部署此变更时，模型提供方的前缀缓存可能失效一次。agent 可以区分 GUI 源码 checkout 与所选 Workspace，并且无需再经过一轮澄清即可解析对当前应用的一般指代。对特定视觉状态的指代仍受「无 DOM／无路由／无截图」这一显式边界约束，必要时仍需用户提供路径、描述或附件。拥有完整提示词的 profile 可以通过 Web 运行时的组合设置选择退出，而无需检查启动器路径。
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
index 6feeb0e71f..0e8b50db1a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.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 .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
-2026-07-28-web-gui-feedback-loop.md: 039d2aebeeef903d10838a46b48e5172f0195126
-2026-07-28-web-gui-feedback-loop.zh.md: 34b6b26d4ce7c7e194e641536fffc503c013188b
+2026-07-28-web-gui-feedback-loop.md: aa488e1df087722c072d98c67d47cdf63a42f6b8
+2026-07-28-web-gui-feedback-loop.zh.md: d9de988e5a2cc57794ff628b65eb050dee610747
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
index 039d2aebee..aa488e1df0 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.md
@@ -12,7 +12,7 @@ The [incident post-mortem](../../../../docs/postmortem/0003-web-agent-gui-feedba
 
 ## Decision
 
-`dsh web` publishes one canonical loopback URL and its actual runtime mode as both model-visible orientation and managed shell facts. The `app:web-surface` prompt section says that unqualified references identify this GUI and names the URL; `DSH_WEB_URL` and `DSH_WEB_MODE=production|development` carry the same facts into every foreground or managed background bash call. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address.
+The ordinary `dsh web` composition mounts the Web bundle's `web-runtime` plugin, which publishes one canonical loopback URL and its actual runtime mode as both model-visible orientation and managed shell facts. The `app:web-surface` prompt section says that unqualified references identify this GUI and names the URL; `DSH_WEB_URL` and `DSH_WEB_MODE=production|development` carry the same facts into every foreground or managed background bash call. The section preserves the no-implicit-DOM, route, or screenshot boundary and does not claim that a LAN alias equals the browser's literal address. A complete-prompt profile sets the row's `surfaceContext` to false and receives neither the prompt section nor the managed variables; the Web launcher uses the same setting to suppress its source-checkout prompt section.
 
 The mode-specific prompt makes the agent, rather than the user, own the hidden startup contract. Production mode defines acceptance as rebuilding the affected artifacts and refreshing the existing URL. Development mode states that `dsh web --dev` activates only the HMR receiver: automatic client-plugin reload additionally requires a same-checkout `pnpm run dev:web` watcher, which the agent verifies before promising no-refresh updates. Shell and other plain-package changes still require rebuild plus refresh. An agent in production mode explains both commands when a user requests no-refresh updates; it does not launch a replacement GUI unless asked.
 
@@ -36,4 +36,4 @@ The keyless fresh-round-trip browser scenario boots the shipped production Web c
 
 ## Consequences
 
-Web prompts gain a dynamic URL-and-mode paragraph, so provider prefix reuse now varies by bound port and mode. Bash processes gain two non-secret managed environment variables. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the agent can teach the user the exact update behavior of the process actually serving their session, and the unsupported startup path fails before a white screen. The URL/mode contract guides the agent away from replacement ports; it does not prohibit arbitrary shell commands from starting one.
+Ordinary Web prompts gain a dynamic URL-and-mode paragraph, so provider prefix reuse now varies by bound port and mode. Their Bash processes gain two non-secret managed environment variables. Bare Vite can no longer be used as a shell-only visual sandbox; developers use the full host or build mode instead. In exchange, GUI work has one mechanically observable target, the agent can teach the user the exact update behavior of the process actually serving their session, and the unsupported startup path fails before a white screen. The URL/mode contract guides the agent away from replacement ports; it does not prohibit arbitrary shell commands from starting one. Profiles that disable `surfaceContext` also give up this feedback-loop guidance and shell context.
diff --git a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
index 34b6b26d4c..d9de988e5a 100644
--- a/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md
@@ -12,7 +12,7 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 决策
 
-`dsh web` 发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。
+常规 `dsh web` 组合会挂载 Web 组合包的 `web-runtime` 插件，由它发布一个规范的回环 URL 及其实际运行时模式，同时将二者作为模型可见的界面定位信息和受管 shell 事实。`app:web-surface` 提示词段说明：未加限定的指代指向此 GUI，并给出 URL；`DSH_WEB_URL` 和 `DSH_WEB_MODE=production|development` 会把同样的事实传入每次前台或受管后台 bash 调用。该段保留「不会隐式获得 DOM、路由或截图」这一边界，也不声称局域网别名等于浏览器中的实际地址。拥有完整提示词的 profile 会把该配置行的 `surfaceContext` 设为 false，并且不会收到该提示词段和这些受管变量中的任何一个；Web 启动器也会使用同一项设置来抑制其源码 checkout 提示词段。
 
 按模式区分的提示词让 agent 而非用户负责隐藏的启动契约。生产模式将验收定义为重新构建受影响的产物并刷新现有 URL。开发模式说明，`dsh web --dev` 只会启用 HMR（热模块替换）接收端：客户端插件要自动重新加载，还需要在同一检出中运行 `pnpm run dev:web` 监听进程，agent 会在承诺无需刷新即可更新前验证这一点。外壳和其他普通包的变更仍然需要重新构建并刷新。生产模式下的 agent 会在用户要求无需刷新即可更新时说明这两个命令；除非用户要求，否则不会启动替代 GUI。
 
@@ -36,4 +36,4 @@ Web agent（智能体）既无法识别承载当前会话的 GUI，也不知道
 
 ## 影响
 
-Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。
+常规 Web 提示词会增加一个动态 URL 和模式段落，因此模型提供方的前缀复用会随绑定端口和模式变化。相应的 Bash 进程会增加两个非敏感的受管环境变量。裸 Vite 不再能用作只依赖 shell 的视觉沙箱；开发者应改用完整宿主或构建模式。作为交换，GUI 工作有了一个可由机制观察的唯一目标，agent 可以向用户说明实际承载其会话的进程究竟如何更新，不受支持的启动路径也会在出现白屏前失败。URL／模式契约会引导 agent 避免使用替代端口，但不会禁止任意 shell 命令启动替代服务。禁用 `surfaceContext` 的 profile 也会放弃这项反馈闭环指引与 shell 上下文。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
new file mode 100644
index 0000000000..754ca8bbd0
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
+2026-08-04-conversation-column-one-axis-scroll.md: 9a487c506a75033d0854f08e95da24704309003d
+2026-08-04-conversation-column-one-axis-scroll.zh.md: 23441a7c8655d1f19d3c0fe0f661f81f69b55dba
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
new file mode 100644
index 0000000000..9a487c506a
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.md
@@ -0,0 +1,37 @@
+# Agent Note: The conversation column scrolls on one axis
+
+Status: implemented
+
+English | [中文](2026-08-04-conversation-column-one-axis-scroll.zh.md)
+
+## Problem
+
+Narrowing the center column — by the window or by the sidebar drag — put a horizontal scrollbar under the whole conversation column on the hero. The bleeding element is the hero's decorative backdrop ellipse: `.heroGlow` is sized `1051/776` of the hero box so its blur scales in userSpace with the input card, which means it reaches past the column whenever the column is narrower than the glow.
+
+That bleed is by construction and stays. What made it user-visible is the scroll container it sits in. `[data-conversation-scroll]` declared `overflow-y: auto` and left the other axis at its initial `visible`, and a box that scrolls in one axis computes `visible` to `auto` in the other. Every column narrower than the glow therefore offered a real horizontal scroll range — measured at 24–95px across the widths a laptop actually produces.
+
+## Decision
+
+`.scrollBody` declares `overflow-x: hidden`. The column states that it is a one-axis scroller instead of leaving the second axis to be derived.
+
+Clipping does not change. `overflow-y: auto` had already made the box a scroll container that clips both axes, so the declaration withdraws only the scrollbar and the user gesture; the glow keeps its bleed, its blur radius, and the same painted extent, and the column keeps its vertical scroll. Nothing in the composer chain moves.
+
+## Alternatives considered
+
+**Size the glow to fit the column.** Rejected. The glow's width is what scales its `stdDeviation="50"` blur with the input card (figma 313:14109); constraining it would make the blur tighten as the column narrows, which is a visual regression to fix a scrollbar.
+
+**Wrap the glow in a clipping box.** Rejected. It adds a box whose only job is to undo an overflow the column already clips, and it leaves the derived `overflow-x: auto` in place for the next element that bleeds — the transcript is full of candidates.
+
+**Rely on the frame's `.centerCol { overflow: hidden }`.** It cannot help. That clip is outside the scroll container, so it hides the glow's overhang at the column border while the container inside it still scrolls to reach it. The reported bar was that container's.
+
+**Assert `scrollWidth === clientWidth` in the test.** Rejected as the signal, because it does not distinguish the states: `hidden` clips the bleed rather than reflowing it away, so the scroll range reads the same on both sides of the fix. Only refusing a user gesture differs, which is what the scenario measures.
+
+## Testing
+
+[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) sweeps viewport widths bracketing the glow and, at each stop, wheels horizontally over the column and reads `scrollLeft`. The committed golden records the relation per stop; the widest stop is the control where the glow does not bleed at all.
+
+Two guards keep the scenario honest. The vacuity guard asserts the glow still reaches past the column at the narrow stops, so the claim cannot pass by the symptom having disappeared for an unrelated reason. The mutation control forces `overflow-x: auto` back on in the page and shows the same gesture, at the same timing, carrying the column to its positive scroll boundary; the test measures that boundary directly because a stable scrollbar gutter can leave some overflow on the negative side of the scroll origin. Without the control, a `scrollLeft` of 0 could equally mean the wheel never arrived.
+
+## Consequences
+
+The conversation column no longer offers a horizontal scrollbar at any width, and decorative bleed in the composer chain is now clipped rather than exposed as scroll range. The cost is that genuinely wide content under this column is clipped instead of reachable by scrolling: any such surface owns its own scroller, as the markdown code block and the trajectory table already do.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
new file mode 100644
index 0000000000..23441a7c86
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-04-conversation-column-one-axis-scroll.zh.md
@@ -0,0 +1,37 @@
+# Agent Note：会话列只在一个轴上滚动
+
+状态：已实现
+
+[English](2026-08-04-conversation-column-one-axis-scroll.md) | 中文
+
+## 问题
+
+当中间列被拉窄——无论是拖窗口还是拖侧边栏——hero 态的整条会话列下方就会出现一条横向滚动条。溢出的元素是 hero 的装饰性背景椭圆：`.heroGlow` 的宽度取 hero 盒子的 `1051/776`，好让它的模糊在 userSpace 中随输入卡片一同缩放；这也意味着只要列比它窄，它就会伸出列外。
+
+这处外溢是设计使然，保持不变。真正让它对用户可见的是它所处的滚动容器。`[data-conversation-scroll]` 只声明了 `overflow-y: auto`，另一个轴留在初始值 `visible`；而一个在某一轴上滚动的盒子，会把另一轴的 `visible` 计算为 `auto`。于是每一条比该椭圆窄的列都真的给出了一段横向滚动范围——在笔记本实际会产生的几档宽度上，实测为 24–95px。
+
+## 决定
+
+`.scrollBody` 声明 `overflow-x: hidden`。这条列明确声明自己是单轴滚动容器，而不是把第二个轴交给推导。
+
+裁剪行为不变。`overflow-y: auto` 早已使该盒子成为在两个轴上都裁剪的滚动容器，因此这条声明收回的只是滚动条和用户手势；椭圆保留它的外溢、模糊半径和同样的绘制范围，列也保留纵向滚动。输入区那条链路上没有任何东西移动。
+
+## 曾考虑的替代方案
+
+**把椭圆缩到列内。** 否决。椭圆的宽度正是让它 `stdDeviation="50"` 的模糊随输入卡片缩放的依据（figma 313:14109）；约束宽度会使列越窄模糊越紧，等于为修一条滚动条而制造一处视觉回归。
+
+**给椭圆套一层裁剪盒。** 否决。这层盒子唯一的职责是抵消列本就会裁剪的溢出，而推导出的 `overflow-x: auto` 仍然留在原处，等着下一个外溢的元素——会话流里这样的候选者不少。
+
+**依赖外框的 `.centerCol { overflow: hidden }`。** 它帮不上忙。那处裁剪在滚动容器之外，只能在列边界处遮住椭圆探出的部分，而里面的容器照样可以滚过去够到它。用户报告的那条滚动条属于内层容器。
+
+**在测试里断言 `scrollWidth === clientWidth`。** 作为判据被否决，因为它区分不出两种状态：`hidden` 裁剪外溢，而不是把它重排掉，所以修复前后读到的滚动范围一样。唯一有差别的是拒绝用户手势，这正是该场景所测量的。
+
+## 测试
+
+[apps/web/tests/conversation-column-overflow.e2e.ts](../../../../apps/web/tests/conversation-column-overflow.e2e.ts) 扫过一组把椭圆宽度夹在中间的视口宽度，在每一档上向列横向滚轮并读取 `scrollLeft`。提交的 golden 逐档记录该关系；最宽的一档是椭圆根本不外溢的对照。
+
+两道防线保证该场景不流于形式。空断言防线断言窄档上椭圆确实仍伸出列外，使这项主张不可能因为症状出于无关原因消失而通过。变异对照则在页面内把 `overflow-x: auto` 强制改回，证明同一手势在同一时序下能把列带到正向滚动边界。测试直接测量该边界，因为稳定的滚动条槽可能让部分外溢处于滚动原点的负向。没有这项对照，`scrollLeft` 读到 0 同样可以解释为滚轮根本没送达。
+
+## 后果
+
+会话列在任何宽度下都不再给出横向滚动条，输入区链路上的装饰性外溢从暴露为滚动范围改为被裁剪。代价是这条列下真正过宽的内容会被裁掉而非可滚动够到：这类界面各自拥有自己的滚动容器，markdown 代码块和轨迹表格已经如此。
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
new file mode 100644
index 0000000000..a08d6323dd
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md
+2026-08-06-onboarding-step-owned-takeover-chrome.md: 4b3bbbc03c4494359297ae6e54bcc9a74c387e80
+2026-08-06-onboarding-step-owned-takeover-chrome.zh.md: 548285d285939325a26df3b8d70c43fe952813a9
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md
new file mode 100644
index 0000000000..4b3bbbc03c
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.md
@@ -0,0 +1,35 @@
+# Agent Note: onboarding takeover chrome moves into the step
+
+Status: implemented
+
+English | [中文](2026-08-06-onboarding-step-owned-takeover-chrome.zh.md)
+
+## Problem
+
+The settings shell mounted the onboarding takeover chrome — a body-portaled overlay with an opaque `--dsw-alias-bg-layer-1` stage, a blur mask, and `#root` set inert — the moment a `settings.onboarding` step was registered and not yet locally completed. Every step decides whether it actually needs to show by loading a private fact first (WelcomeNotice: the acknowledgement bit through its settings join; DeepSeekOnboardingDialog: credential readiness through the Models join) and renders `null` while that fact is in flight. Rendering `null` could not suppress the chrome, because the opaque stage was painted by the shell around the slot outlet, not by the step.
+
+On every reload while the hero (blank or no session) was current, the sessions list turning `ready` therefore popped a full-screen opaque layer — white in the light palette — and blocked all interaction for exactly one credential/settings RPC round-trip, after which the already-configured steps self-completed and the layer vanished. Users saw the app flash white each refresh the moment the workspace/session lists landed.
+
+## Decision
+
+The takeover chrome belongs to the step, not the shell. A new zero-cordis primitive, `OnboardingSurface` (ui-primitives), renders the body-portaled overlay/mask/stage — CSS class names and geometry moved verbatim from `SettingsRoot.module.css` — and holds `#root` inert for exactly its own mount lifetime. Both step components wrap only their **visible** branch in it; their existing `null` branches now paint and block nothing by construction, because the chrome is part of the same render decision.
+
+`SettingsRoot` keeps the coordinator exactly as it was (ordered ledger projection, one mounted step, local completed set, `stepId`/`complete`/`openSection` currency) but renders the elected step bare — no portal, no stage, no inert effect. The `settings.onboarding` slot contract now states that registrants own the surface wrap and must render `null` while their private facts are undecided.
+
+## Alternatives considered
+
+**Register steps conditionally (ledger as the has-content signal).** Register the entry only after the private join resolves to "needs intervention". Architecturally clean (publish at the commit point) but a larger change: the join load must move from the dialogs into each plugin's apply, and registration/disposal becomes reactive plumbing in two packages. Rejected as oversized for the defect.
+
+**Convert `settings.onboarding` to a chain with an externalized completed-set store.** The composer-takeover pattern; prototyped and reverted. Selectors can only judge owner props, so the private readiness facts still had to be resolved inside the components — the chain bought routing generality the two current steps do not need, at the cost of a contract change across three packages.
+
+**Detect empty slot output at the render site.** `renderSlot` returns an outlet element unconditionally, so the owner cannot branch on a step's `null`; probing rendered DOM emptiness needs a commit-then-retract dance whose dynamic transitions lose the pre-paint guarantee.
+
+## Consequences
+
+While a step is mounted but undecided, the application stays visible and interactive: `#root` is no longer inert during the decision window (previously it was inert behind an opaque layer). For a genuinely unconfigured user the takeover now appears one join round-trip later than before — but with its content already present, instead of an empty stage that fills in.
+
+A future step that registers without wrapping its visible content in `OnboardingSurface` renders bare over the app with no mask; the slot contract JSDoc names the wrap as the registrant's obligation.
+
+## Testing
+
+`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` pins the primitive: body portal around the content, mask/stage class presence, `#root` inert held for exactly the mount lifetime, and the no-`#root` composition. `packages/client/ui-settings/tests/settings-root.spec.tsx` pins the inverted shell contract: no takeover chrome and no inert while a mounted step renders nothing. `apps/web/tests/onboarding-deepseek-config.e2e.ts` gains the defect's assembled regression pin: a configured world reloads while every `settings.describe` response is held open at the browser's network boundary — widening the steps' deciding window from loopback-invisible to hundreds of milliseconds, which is what keeps the assertions non-vacuous — and an 8 ms in-page sampler proves the takeover chrome never mounts and `#root` never turns inert. The file's existing scenarios and the step specs (`ui-settings-general`, `ui-models`) pass unchanged — the mask selector and geometry pins survive because the stylesheet moved verbatim.
diff --git a/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
new file mode 100644
index 0000000000..548285d285
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md
@@ -0,0 +1,35 @@
+# Agent Note：首次使用引导的接管界面框架移入步骤自身
+
+状态：已实现
+
+[English](2026-08-06-onboarding-step-owned-takeover-chrome.md) | 中文
+
+## 问题
+
+设置外壳在 `settings.onboarding` 有已注册且本地未完成的步骤时，就立即挂出首次使用引导的接管界面框架——portal 到 body 的浮层，带不透明的 `--dsw-alias-bg-layer-1` 展示层、模糊遮罩，并把 `#root` 置为 `inert`。而每个步骤都要先加载私有事实才能判定自己是否需要出场（WelcomeNotice：经其设置 join 读取确认位；DeepSeekOnboardingDialog：经 Models join 读取凭据就绪状态），判定期间渲染 `null`。渲染 `null` 无法抑制界面框架，因为不透明展示层是外壳画在 slot outlet 外面的，不属于步骤。
+
+于是每次在 hero（空白或无会话）状态下刷新页面，会话列表一变 `ready` 就弹出整屏不透明层——亮色主题下是白色——并阻断全部交互，时长恰好等于一次凭据/设置 RPC 往返；之后已配置好的步骤自我完成，图层消失。用户看到的就是每次刷新在 workspace/会话列表落地的瞬间闪一下白屏。
+
+## 决定
+
+接管界面框架属于步骤，不属于外壳。新增零 cordis 原语 `OnboardingSurface`（ui-primitives）：渲染 portal 到 body 的浮层／遮罩／展示层——CSS 类名与几何从 `SettingsRoot.module.css` 逐字迁移——并在自身挂载生命周期内保持 `#root` 为 `inert`。两个步骤组件只把各自的**可见**分支包进该原语；既有的 `null` 分支由此在构造上不绘制、不阻塞任何内容，因为界面框架已是同一次渲染决策的一部分。
+
+`SettingsRoot` 的协调器原样保留（有序账本投影、每次挂载一个步骤、本地完成集合、`stepId`／`complete`／`openSection` currency），但对当选步骤裸渲染——不再有 portal、展示层和 inert 效果。`settings.onboarding` 的 slot 契约现在写明：注册方持有外层包裹，且在私有事实未决时必须渲染 `null`。
+
+## 曾考虑的替代方案
+
+**条件注册（账本即有内容信号）。** 私有 join 解析出「需要介入」后才注册条目。架构上干净（在 commit point 发布），但改动更大：join 的加载必须从对话框上移到各插件的 apply，注册／销毁在两个包里都变成响应式接线。对本缺陷而言过重，否决。
+
+**把 `settings.onboarding` 改成 chain 并把完成集合外置为 store。** composer takeover 的版型；做过原型后回退。selector 只能判定 owner props，私有就绪事实仍然只能在组件内部解析——chain 买来的是当前两个步骤并不需要的路由通用性，代价却是跨三个包的契约变更。
+
+**在渲染点探测 slot 输出为空。** `renderSlot` 无条件返回 outlet 元素，owner 无法据步骤的 `null` 分支；探测已渲染 DOM 是否为空需要先提交再撤回的手法，其动态翻转会失去 paint 前的保证。
+
+## 后果
+
+步骤已挂载但尚未判定期间，应用保持可见且可交互：判定窗口内 `#root` 不再是 `inert`（此前是在不透明图层背后被置灰）。对真正未配置的用户，接管层比从前晚一个 join 往返出现——但一出现就带着内容，而不是先露出空白展示层再填充。
+
+未来若有步骤注册后不把可见内容包进 `OnboardingSurface`，会无遮罩地裸渲染在应用之上；slot 契约的 JSDoc 已把包裹写为注册方的义务。
+
+## 测试
+
+`packages/client/ui-primitives/tests/onboarding-surface.spec.tsx` 钉住原语行为：内容外的 body portal、遮罩／展示层类名存在、`#root` 的 `inert` 恰好持续挂载生命周期，以及无 `#root` 的组合。`packages/client/ui-settings/tests/settings-root.spec.tsx` 钉住反转后的外壳契约：已挂载步骤什么都不渲染时，无接管界面框架、无 inert。`apps/web/tests/onboarding-deepseek-config.e2e.ts` 新增本缺陷的整装回归钉：已配置世界刷新页面，同时在浏览器网络边界扣住所有 `settings.describe` 响应——把步骤的判定窗口从 loopback 下不可见拉宽到数百毫秒，这正是断言保持非空洞的关键——页内 8ms 采样器证明接管界面框架从未挂载、`#root` 从未变为 inert。该文件的既有场景与步骤 spec（`ui-settings-general`、`ui-models`）原样通过——样式表逐字迁移，遮罩选择器与几何钉子得以幸存。
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
index feb73d00dd..1884c12c93 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.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 .agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
-2026-06-21-subagent-capability-seam.md: 043092884731c403a11b71ef8b5a410e9e5af7e0
-2026-06-21-subagent-capability-seam.zh.md: 6a4a5798199ca7d6d7c011668a319d65a0553208
+2026-06-21-subagent-capability-seam.md: 752e639b09ea2ac0ba19841ddfe38b15b44d22e9
+2026-06-21-subagent-capability-seam.zh.md: 6009aeda6773357a4217f8956fb510c2116bbe3f
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
index 0430928847..752e639b09 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md
@@ -4,7 +4,7 @@ Status: implemented
 
 English | [中文](2026-06-21-subagent-capability-seam.zh.md)
 
-> The full seam is shipped: the `dsh-subagent` interface and `dsh-tool-subagent` consumer; the two in-process backends (`dsh-subagent-spawn`, `dsh-subagent-fork`); the nested-agent snapshot infrastructure ([per-session snapshot replay](../testing/2026-06-22-subagent-snapshot-replay.md)); and the out-of-process `dsh-subagent-acp` backend ([its Agent Note](2026-06-22-acp-subagent-backend.md)).
+> The full seam is shipped: the `dsh-subagent` interface and `dsh-tool-subagent` consumer; the two in-process backends (`dsh-subagent-spawn`, `dsh-subagent-fork`); the nested-agent snapshot infrastructure ([per-session snapshot replay](../testing/2026-06-22-subagent-snapshot-replay.md)); and the out-of-process ACP, Codex, and Claude Code backends ([ACP Agent Note](2026-06-22-acp-subagent-backend.md), [product-provider Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)).
 
 ## Problem
 
@@ -14,7 +14,8 @@ The distinctive requirement — the one that shapes the whole design — is that
 
 - **in-process** — a child concrete `Agent` on the same `Context` (the cheapest, and nearly free given the existing agent factory);
 - **ACP** — act as an ACP *client* driving another agent process (which can be another instance of ourselves);
-- later: **A2A**, the **Codex app-server**, and the **Claude Code Agent SDK** — each the same out-of-process "start a child, prompt it, stream updates, cancel" shape as the ACP backend.
+- **Codex app-server and Claude Code Agent SDK** — current one-shot siblings that apply the same named-provider seam to official product processes ([product-provider Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md));
+- later: **A2A** using the same out-of-process "start a child, prompt it, settle, cancel" shape.
 
 ## Alternatives considered
 
@@ -34,6 +35,8 @@ A new package group `packages/subagent/`:
 | `@deepseek-ai/dsh-subagent-spawn` | implementation: a fresh in-process child via `ctx.agents.create` |
 | `@deepseek-ai/dsh-subagent-fork` | implementation: an in-process child seeded with a snapshot of the parent's log |
 | `@deepseek-ai/dsh-subagent-acp` | implementation: an ACP client driving a configured child process |
+| `@deepseek-ai/dsh-subagent-codex` | implementation: a one-shot official Codex app-server process |
+| `@deepseek-ai/dsh-subagent-claude-code` | implementation: a one-shot official Claude Code process through the Agent SDK |
 | `@deepseek-ai/dsh-tool-subagent` | consumer: the model-facing `subagent` tool over `ctx.subagents` |
 
 ### The primitive: async `start → SubagentRun`
@@ -51,7 +54,7 @@ Fresh and forked children are separate providers, not a request flag. `dsh-subag
 
 ### Child isolation and the parent log
 
-Each subagent runs in its **own `Session`** (own id, `parentSession` lineage), persisted independently. The parent's log records only the spawn `tool/call` and its `tool/result` (the child's final output) — the child's internal steps and tool calls stay in the child's own session, never injected into the parent log. This is the only design that is identical across transports: an ACP child's internal events physically cannot be injected into our parent log, so making in-process behave the same keeps the seam transport-agnostic.
+Each in-process subagent runs in its **own `Session`** (own id, `parentSession` lineage), persisted independently. Remote ACP and one-shot product providers instead mint a parent-scoped lifecycle id and expose no local `Agent` or child `Session`; their internal state remains in the remote process. Across both forms, the parent's log records only the spawn `tool/call` and its `tool/result` (the child's final output), while child steps and tool calls remain outside the parent log.
 
 ### Synchronous collect (first cut)
 
diff --git a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
index 6a4a579819..6009aeda67 100644
--- a/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md
@@ -4,7 +4,7 @@ Status: implemented
 
 [English](2026-06-21-subagent-capability-seam.md) | 中文
 
-> 完整 seam 已交付：`dsh-subagent` 接口与 `dsh-tool-subagent` 消费方；两个进程内后端（`dsh-subagent-spawn`、`dsh-subagent-fork`）；嵌套 agent 快照基础设施（[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)）；以及进程外后端 `dsh-subagent-acp`（[其 Agent Note](2026-06-22-acp-subagent-backend.md)）。
+> 完整 seam 已交付：`dsh-subagent` 接口与 `dsh-tool-subagent` 消费方；两个进程内后端（`dsh-subagent-spawn`、`dsh-subagent-fork`）；嵌套 agent 快照基础设施（[逐会话快照回放](../testing/2026-06-22-subagent-snapshot-replay.md)）；以及进程外的 ACP、Codex 与 Claude Code 后端（[ACP Agent Note](2026-06-22-acp-subagent-backend.md)、[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）。
 
 ## 问题
 
@@ -14,7 +14,8 @@ harness 有一个长期搁置的 seam 用于 **subagent**：一个 agent（智
 
 - **进程内**：在同一个 `Context` 上创建一个具体的子 `Agent`（最廉价，且鉴于现有 agent 工厂几乎零成本）；
 - **ACP**：作为 ACP *客户端*驱动另一个 agent 进程（可以是自身的另一个实例）；
-- 后续：**A2A**、**Codex app-server** 与 **Claude Code Agent SDK**——每种都与 ACP 后端相同的进程外形状：「启动子 agent、发送提示词、流式接收更新、取消」。
+- **Codex app-server 与 Claude Code Agent SDK**：当前的一次性兄弟提供方，将同一个命名提供方 seam 应用于官方产品进程（[产品提供方 Agent Note](2026-08-04-claude-code-and-codex-subagent-backends.md)）；
+- 后续：**A2A**，采用同样的进程外形态：「启动子 agent、发送提示词、结算、取消」。
 
 ## 曾考虑的替代方案
 
@@ -34,6 +35,8 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 | `@deepseek-ai/dsh-subagent-spawn` | 实现：通过 `ctx.agents.create` 创建全新的进程内子 agent |
 | `@deepseek-ai/dsh-subagent-fork` | 实现：用父 agent 日志快照初始化的进程内子 agent |
 | `@deepseek-ai/dsh-subagent-acp` | 实现：作为 ACP 客户端驱动已配置的子进程 |
+| `@deepseek-ai/dsh-subagent-codex` | 实现：一次性官方 Codex app-server 进程 |
+| `@deepseek-ai/dsh-subagent-claude-code` | 实现：通过 Agent SDK 运行的一次性官方 Claude Code 进程 |
 | `@deepseek-ai/dsh-tool-subagent` | 消费方：基于 `ctx.subagents` 的面向模型的 `subagent` 工具 |
 
 ### 原语：异步 `start → SubagentRun`
@@ -51,7 +54,7 @@ bash seam（[能力 seam](../architecture/2026-06-13-capability-seams.md)）在
 
 ### 子 agent 隔离与父日志
 
-每个 subagent 运行在**自己的 `Session`** 中（独立 id、`parentSession` 谱系），独立持久化。父日志仅记录 spawn `tool/call` 及其 `tool/result`（子 agent 的最终输出）——子 agent 的内部步骤和工具调用留在子 agent 自己的会话中，绝不注入父日志。这是唯一在所有传输方式下行为一致的设计：ACP 子 agent 的内部事件在物理上无法注入我们的父日志，因此让进程内行为保持一致，使 seam 真正与传输方式无关。
+每个进程内 subagent 运行在**自己的 `Session`** 中（独立 id、`parentSession` 谱系），独立持久化。远端 ACP 和一次性产品提供方则会生成一个父级作用域的生命周期 id，且不暴露本地 `Agent` 或子 `Session`；其内部状态留在远端进程中。两种形式下，父日志都仅记录 spawn `tool/call` 及其 `tool/result`（子 agent 的最终输出），而子 agent 的步骤和工具调用均留在父日志之外。
 
 ### 同步收集（首版）
 
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
index bab63f5149..9540bb6f0e 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.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 .agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
-2026-06-22-acp-subagent-backend.md: 5f12aa1c08d4f4cfaa35f2f7f4b09ad341c3eae8
-2026-06-22-acp-subagent-backend.zh.md: ba9d4255723367ab4afc5ab87e056f12f5c3a285
+2026-06-22-acp-subagent-backend.md: c994ebfa69649bb9e79d3aa389a0e13c178131c7
+2026-06-22-acp-subagent-backend.zh.md: 62d631e95b5d1f299bed1fd00353b5ac9349b9a0
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
index 5f12aa1c08..c994ebfa69 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.md
@@ -57,6 +57,6 @@ Persistent-process pooling (reuse a warm child across runs) is a performance opt
 
 Every run pays a fresh subprocess (spawn + `initialize` + `newSession`). The parent surfaces only the child's final answer: `session/update` thoughts and tool-call cards are consumed and dropped, and permission prompts never reach a human — the configured policy answers them. The child's environment is credential-scrubbed by default, so its own model key is supplied explicitly via `config.env`.
 
-## Future providers
+## Product-provider siblings
 
-The same out-of-process spawn/prompt/stream/cancel shape generalizes to other transports named in the seam Agent Note — A2A, the Codex app-server, and the Claude Code Agent SDK — each a sibling provider registered by name. The ACP backend is the proof that the seam supports the boundary; those are mechanically similar.
+The [Codex app-server and Claude Code Agent SDK providers](2026-08-04-claude-code-and-codex-subagent-backends.md) apply the same out-of-process spawn/prompt/settle/cancel boundary as siblings registered by name. A2A remains a future sibling transport; the ACP backend proves that the common seam supports this boundary without owning product-private protocols.
diff --git a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
index ba9d425572..62d631e95b 100644
--- a/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-22-acp-subagent-backend.zh.md
@@ -57,6 +57,6 @@ ACP `StopReason` → harness `SubagentStopReason`：`end_turn`→`completed`、`
 
 每次运行都要付出一个全新子进程的代价（spawn + `initialize` + `newSession`）。父进程仅暴露子 agent 的最终回答：`session/update` 中的思考和工具调用卡片被消费后丢弃，权限提示从不到达人类——由配置的策略应答。子进程环境默认经过凭证清洗，因此其自身的模型密钥需通过 `config.env` 显式提供。
 
-## 后续提供方
+## 兄弟产品提供方
 
-同样的进程外启动/提示词/流式输出/取消形态可泛化到 seam Agent Note 中列出的其他传输方式——A2A、Codex app-server 和 Claude Code Agent SDK——每个都是按名称注册的兄弟提供方。ACP 后端证明了 seam 支持跨进程边界；其余在机制上类似。
+[Codex app-server 与 Claude Code Agent SDK 提供方](2026-08-04-claude-code-and-codex-subagent-backends.md)作为按名称注册的兄弟提供方，采用同样的进程外启动/提示词/结算/取消边界。A2A 仍是未来的兄弟传输方式；ACP 后端证明了通用 seam 能够支持这项边界，而无需负责产品私有协议。
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml b/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
index 5f045324dd..170631b6a4 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.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 .agents/notes/implemented/feature/2026-06-24-workspace-context.md
-2026-06-24-workspace-context.md: df7ae58f8a42a8c1aac8113a429ef0f50b2fb795
-2026-06-24-workspace-context.zh.md: aecc57a5c63b4c6282260863f4183944c14b5cf8
+2026-06-24-workspace-context.md: 3c21b7599e6bb2dd759e4a040c1b999f1b0516cd
+2026-06-24-workspace-context.zh.md: e913ecb22b4692e1ee7b96d4f5effe2606775cf8
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
index df7ae58f8a..3c21b7599e 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.md
@@ -30,9 +30,9 @@ The user-global file is fixed at `$DSH_HOME/AGENTS.md`, is not affected by eithe
 
 At the first `agent/pre-step` of an agent-loop instance, the plugin composes one sourced user-role baseline. When the downstream decision enters a nonempty first-step batch, the plugin folds the baseline into that final batch right after the claimed prompt, so it becomes durable with the direct prompt and reaches the first request. Rejection or an empty first-step decision leaves the baseline in the next-step inbox for a later wakeup. The plugin loads the user-global file first, then finds the project root by walking upward from `agent.session.header.cwd` to a configured root marker (default `.git`), then loads the configured candidates from each directory from the root to the cwd. A `.git` file and a `.git` directory are both valid markers, covering linked worktrees and submodules. Without a marker, the cwd itself is the root.
 
-The baseline becomes a durable `user/message` with a typed `workspace-instructions` source. Its `baseline: true` marker distinguishes the complete startup or resume baseline from later deltas, and its change list persists the included scopes and content digests. If a previously queued workspace baseline is still pending, the plugin removes that exact message and prepends its replacement instead of accumulating duplicates.
+The baseline becomes a durable `user/message` with a typed `workspace-instructions` source. Its `baseline: true` marker distinguishes a complete baseline from later deltas, its `baselineIdentity` records normalized discovery, precedence, project-root, and budget semantics, and its change list persists the included scopes and content digests. If a previously queued workspace baseline is still pending, the plugin removes that exact message and prepends its replacement instead of accumulating duplicates.
 
-A resumed agent creates a new loop instance and injects a baseline composed from current files before its first request. This permits current baseline content on resume without mutating an earlier history event. A resume and a hot plugin remount both face a log that may already hold a baseline; they are told apart by `agent/session-start`, which a startup or resume emits before the first step while a remount attaches to an already-live session and never sees it. A remount retains the existing baseline only when its typed event remains in the current visible surface, and still rebuilds scope and provider-version tracking from current files. If compaction has shadowed that event, the remount injects a current baseline. A resume always re-composes.
+A resumed agent creates a new loop instance over persisted history. At its first `agent/pre-step`, a visible baseline with the current identity remains authoritative while the plugin compares its retained scopes with a complete current rendering. Unchanged and budget-omitted files append nothing; offline additions, edits, removals, and files that leave the retained budget set append `set`, `replace`, or `remove` transitions in the entering batch without mutating or duplicating the original baseline. An incompatible visible baseline is superseded by one complete baseline in current precedence order with explicit replacement language; when no current candidate exists, an explicit empty baseline clears the earlier scopes. A hot plugin remount follows the same rule. If compaction has shadowed the typed baseline, the next entering pre-step composes one complete current baseline and carries it in the same request.
 
 The baseline is a user-role `<system-reminder>` with `Instructions from: <path>` sections and explicit authority and precedence language. This familiar model-facing frame avoids a harness-specific XML vocabulary. Project paths are root-relative and the user-global path is `~/.dsh/AGENTS.md` for the default home or `$DSH_HOME/AGENTS.md` for a configured home. The final rendering boundary escapes a literal `</system-reminder>` anywhere in instruction content or model-visible path, scope, and budget metadata before byte accounting completes. The package README owns the exact current [prompt shape](../../../../packages/context/workspace-context/README.md#prompt-shape).
 
@@ -48,15 +48,15 @@ Shell commands are not discovery triggers. Local bash calls start fresh shells,
 
 ### Duplicate Suppression And Change Detection
 
-Every workspace context event stores versioned metadata with `{ action, scope, path, digest? }`, where `digest` is SHA-1 over the loaded content. Baselines additionally carry `baseline: true`. The model-facing prompt has no HTML comments, hidden markers, or headings that are parsed back into state.
+Every workspace context event stores versioned metadata with `{ action, scope, path, digest? }`, where `digest` is SHA-1 over the loaded content. Complete baselines additionally carry `baseline: true` and `baselineIdentity`. The model-facing prompt has no HTML comments, hidden markers, or headings that are parsed back into state.
 
 At reconciliation time the plugin scans workspace-sourced `user/message` events and derives the latest state for each visible scope. A short per-session pending map begins only after the immutable top-level `tools/result` proves an `additionalContexts` entry survived every post-execute listener, then covers the interval before the loop appends that context to the log. Each entry records the open `{ turn, step }`: an equal durable `user/message` at or after its sequence boundary confirms and removes it, while a matching `step/end` arriving first means the loop discarded its context buffer, so the plugin removes both the pending entry and its version-cache fast path. A nested Code Mode result stages its changes under the parent's opaque execution token so repeated sub-dispatches in one run do not duplicate them; the parent result rolls that provisional state back and commits only contexts retained by outer policy.
 
-An unchanged path and digest is suppressed. A logged removal is a tombstone, so a reappearing candidate becomes a new `set`. Resume works from persisted metadata. If compaction removes an instruction event from the visible surface, that state no longer suppresses a later load, matching the fact that the model can no longer see it. Only changes actually included under the byte budget enter metadata or pending state, so an omitted file remains eligible on a later touch.
+An unchanged path and digest is suppressed. A logged removal is a tombstone, so a reappearing candidate becomes a new `set`. Resume works from persisted metadata: a compatible visible baseline supplies comparison state rather than causing another complete baseline to be appended. If compaction removes an instruction event from the visible surface, that state no longer suppresses a later load, matching the fact that the model can no longer see it. Only changes actually included under the byte budget enter metadata or pending state, so an omitted file remains eligible on a later touch.
 
-The initial baseline's typed changes are comparison state only while its event remains in the visible session surface. A later successful filesystem touch re-adds an unchanged baseline scope after compaction, or appends baseline edits or removals as dynamic messages; it never rewrites the original event. The in-memory scope marker and provider-version cache only select and accelerate probes, so neither can suppress context the model no longer sees. During resumed baseline preparation the plugin also reconciles visible dynamic scopes, so nested changes made while the agent was offline can append an update before the first resumed request.
+The initial baseline's typed changes are comparison state only while its event remains in the visible session surface. Resume retains a compatible baseline and reconciles current baseline and visible dynamic scopes, so changes made while the agent was offline append transitions before the first resumed request. When compaction shadows the baseline event, the next entering pre-step composes the complete current baseline and records it in the same request; a successful filesystem touch can instead re-add an unchanged baseline scope or append baseline edits or removals as dynamic messages. Neither path rewrites the original event. The in-memory scope marker and provider-version cache only select and accelerate probes, so neither can suppress context the model no longer sees.
 
-There is intentionally no watcher. Detection occurs at the next successful structured filesystem touch or resumed baseline preparation. A provider failure produces no removal; absence is only accepted when all configured candidates in that scope were probed successfully.
+There is intentionally no watcher. Detection occurs at the next successful structured filesystem touch, resumed-baseline reconciliation, or entering pre-step that restores a shadowed baseline. A provider failure produces no removal; absence is only accepted when all configured candidates in that scope were probed successfully.
 
 ### Byte Budget And Bounded Reads
 
@@ -82,7 +82,7 @@ Workspace guidance is isolated per session and shared by the demo front doors, W
 
 Repository text remains untrusted input. Lower-authority user-role framing, explicit precedence language, and delimiter escaping reduce risk but do not eliminate prompt injection. Following a candidate symlink to its target widens that surface to off-tree content, so the permission and sandbox layers that confine `ctx.fs` to trusted roots are the boundary that treats workspace files as data rather than authority (the [instruction-symlink follow note](2026-07-21-follow-instruction-symlinks.md) owns the residual risk).
 
-The system is event-driven rather than watch-driven. Edits are not visible at the exact filesystem mutation instant unless that mutation goes through a structured tool; externally changed files are noticed on the next successful structured touch or resume. This keeps the design deterministic and provider-neutral.
+The system is event-driven rather than watch-driven. Edits are not visible at the exact filesystem mutation instant unless that mutation goes through a structured tool; externally changed files are noticed on the next successful structured touch, resume reconciliation, or restoration of a shadowed baseline. This keeps the design deterministic and provider-neutral.
 
 ## Deferred
 
diff --git a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
index aecc57a5c6..e913ecb22b 100644
--- a/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-24-workspace-context.zh.md
@@ -30,9 +30,9 @@ Status: implemented
 
 在 agent loop（智能体循环）实例的第一个 `agent/pre-step`，插件会组合一条带来源的 user 角色基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使其与直接提示词一同成为持久记录并抵达第一次请求。reject 或空的第一步决策会将基线留在 next-step inbox，等待后续唤醒。插件先加载用户全局文件，再从 `agent.session.header.cwd` 向上遍历至配置的根标记（默认为 `.git`）以确定项目根目录，随后从根目录至 cwd 的每级目录加载已配置候选项。`.git` 文件与 `.git` 目录都是有效标记，因而能覆盖链接 worktree 和 submodule。找不到标记时，cwd 本身就是根目录。
 
-该基线会成为一条持久 `user/message`，并携带带类型的 `workspace-instructions` 来源。其 `baseline: true` 标记将完整的启动或恢复基线与后续增量区分开来，变更列表则持久保存已纳入的作用域和内容 digest。若先前排队的 workspace 基线仍在等待，插件会删除该确切消息并 prepend 替代值，而不会累积副本。
+该基线会成为一条持久 `user/message`，并携带带类型的 `workspace-instructions` 来源。其 `baseline: true` 标记将完整基线与后续增量区分开来，`baselineIdentity` 记录规范化的发现、优先级、项目根目录和预算语义，变更列表则持久保存已纳入的作用域和内容 digest。若先前排队的 workspace 基线仍在等待，插件会删除该确切消息并 prepend 替代值，而不会累积副本。
 
-恢复 agent 会创建新的循环实例，并在其第一次请求前注入由当前文件组合的基线。这样，恢复时可以使用当前基线内容，而无需修改先前的历史事件。恢复与插件热重挂都会面对日志中可能已存在基线的情况；二者通过 `agent/session-start` 区分：启动或恢复会在第一步前发出该事件，而热重挂附着到一个已存活的会话、永远不会看到它。只有当基线的类型化事件仍在当前可见表层中时，热重挂才保留既有基线，同时仍会根据当前文件重建 scope 与提供方版本跟踪。如果压缩（compaction）已遮蔽该事件，热重挂会注入当前基线。恢复则始终重新组合。
+恢复 agent 会基于持久化历史创建新的 loop 实例。在第一个 `agent/pre-step`，具有当前标识的可见基线仍是权威状态；插件会将其保留的 scope 与当前完整渲染进行比较。未变化和被预算省略的文件不追加任何内容；agent 离线期间新增、编辑、移除或不再属于预算保留集的文件，会在进入步骤的批次中追加 `set`、`replace` 或 `remove` 转换，既不改写也不重复原始基线。不兼容的可见基线会被一条按当前优先级排列的完整基线取代，并以明确措辞说明替换关系；如果当前不存在任何候选文件，一条显式空基线会清除先前的 scope。插件热重挂遵循相同规则。如果压缩（compaction）已遮蔽带类型的基线，下一次进入步骤的 pre-step 会组合一条完整的当前基线，并在同一请求中携带它。
 
 基线是一条 user 角色的 `<system-reminder>`，包含 `Instructions from: <path>` 章节，以及明确的权威性与优先级说明。这种熟悉的模型可见框架避免引入 harness 专用的 XML 词汇。项目路径相对于根目录；使用默认 home 时，用户全局路径为 `~/.dsh/AGENTS.md`，使用已配置 home 时则为 `$DSH_HOME/AGENTS.md`。最终渲染边界会在完成字节核算前，转义指令内容或模型可见的路径、scope 与预算元数据中出现的字面量 `</system-reminder>`。包 README 负责规定当前准确的[提示词形态](../../../../packages/context/workspace-context/README.md#prompt-shape)。
 
@@ -48,15 +48,15 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，
 
 ### 重复抑制与变更检测
 
-每个工作区上下文事件都会存储带版本的元数据，其形态为 `{ action, scope, path, digest? }`；`digest` 是对已加载内容计算的 SHA-1。基线还会额外携带 `baseline: true`。模型可见提示词中没有 HTML 注释、隐藏标记，也没有会被解析回状态的标题。
+每个工作区上下文事件都会存储带版本的元数据，其形态为 `{ action, scope, path, digest? }`；`digest` 是对已加载内容计算的 SHA-1。完整基线还会额外携带 `baseline: true` 和 `baselineIdentity`。模型可见提示词中没有 HTML 注释、隐藏标记，也没有会被解析回状态的标题。
 
 协调时，插件扫描带工作区来源的 `user/message` 事件，并派生每个可见作用域的最新状态。一个简短的逐会话待处理映射只会在不可变的顶层 `tools/result` 证明某个 `additionalContexts` 条目经过所有 post-execute 监听器后仍然保留时开始记录；随后，它覆盖循环将该上下文追加到日志之前的间隔。每个条目记录开启状态的 `{ turn, step }`：如果相同的持久 `user/message` 出现在其序列边界或之后，该条目得到确认并被移除；如果匹配的 `step/end` 先到达，则说明循环丢弃了上下文缓冲区，插件会同时移除待处理条目及其版本缓存快速路径。嵌套的 Code Mode 结果会把变更暂存在父级的不透明执行 token 下，确保一次运行中的重复子分发不会产生重复项；父级结果会回滚这份临时状态，并且只提交外层策略保留的上下文。
 
-路径和 digest 均未变化时会被抑制。日志中的移除操作是一条墓碑记录，因此重新出现的候选项会成为新的 `set`。恢复操作从持久化元数据继续工作。如果压缩从可见表面移除某条指令事件，该状态不再抑制后续加载，这与模型已经无法看见它的事实一致。只有真正纳入字节预算的变更才会进入元数据或待处理状态，因此被省略的文件在之后的触碰中仍有资格加载。
+路径和 digest 均未变化时会被抑制。日志中的移除操作是一条墓碑记录，因此重新出现的候选项会成为新的 `set`。恢复操作从持久化元数据继续工作：兼容的可见基线会提供比较状态，而不会导致再次追加完整基线。如果压缩从可见表面移除某条指令事件，该状态不再抑制后续加载，这与模型已经无法看见它的事实一致。只有真正纳入字节预算的变更才会进入元数据或待处理状态，因此被省略的文件在之后的触碰中仍有资格加载。
 
-只有当初始基线事件仍在可见会话表层中时，其类型化变更才用作比较状态。后续成功的文件系统触碰会在压缩后重新添加未变化的基线 scope，或把基线编辑或移除操作追加为动态消息；它绝不重写原始事件。内存中的 scope 标记和提供方版本 cache 只用于选择探测对象并加速探测，因此二者都不能抑制模型已无法看见的上下文。恢复时准备基线的过程中，插件还会协调可见的动态作用域，因此 agent 离线期间发生的嵌套变更可以在第一次恢复请求前追加更新。
+只有当初始基线事件仍在可见会话表层中时，其类型化变更才用作比较状态。恢复会保留兼容的基线，并对账当前基线和可见的动态 scope，因此 agent 离线期间的变更会在第一次恢复请求前追加为转换。当压缩遮蔽基线事件时，下一次进入步骤的 pre-step 会组合完整的当前基线，并在同一请求中记录它；也可以改由一次成功的文件系统触碰重新添加未变化的基线 scope，或把基线编辑或移除操作追加为动态消息。两条路径都不会重写原始事件。内存中的 scope 标记和提供方版本 cache 只用于选择探测对象并加速探测，因此二者都不能抑制模型已无法看见的上下文。
 
-系统刻意不使用文件监视器。检测发生在下一次成功的结构化文件系统触碰或恢复时的基线准备。提供方失败不会产生移除；只有该作用域中的全部已配置候选项都成功完成探测后，系统才接受「不存在」这一结论。
+系统刻意不使用文件监视器。检测发生在下一次成功的结构化文件系统触碰、恢复时的基线对账，或进入步骤的 pre-step 恢复被遮蔽的基线时。提供方失败不会产生移除；只有该作用域中的全部已配置候选项都成功完成探测后，系统才接受「不存在」这一结论。
 
 ### 字节预算与有界读取
 
@@ -82,7 +82,7 @@ shell 命令不会触发发现。本地 bash 调用会启动全新的 shell，
 
 仓库文本仍是不受信任的输入。低权威 user 角色框架、显式优先级说明和分隔符转义可以降低风险，但无法消除提示词注入。跟随候选符号链接到目标，会把该攻击面扩大至树外内容；因此，把 `ctx.fs` 限制在可信根目录内的权限与沙箱层才是真正的边界，它们让系统把工作区文件当作数据而不是权威（[跟随指令符号链接记录](2026-07-21-follow-instruction-symlinks.md)负责说明残余风险）。
 
-系统由事件驱动，而不是文件监视器驱动。除非文件系统变更通过结构化工具完成，否则编辑不会在确切的文件系统变更时刻可见；外部文件变更会在下一次成功的结构化触碰或恢复时被发现。这使设计保持确定性并且与提供方无关。
+系统由事件驱动，而不是文件监视器驱动。除非文件系统变更通过结构化工具完成，否则编辑不会在确切的文件系统变更时刻可见；外部文件变更会在下一次成功的结构化触碰、恢复对账，或恢复被遮蔽的基线时被发现。这使设计保持确定性并且与提供方无关。
 
 ## 延后事项
 
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
index 0875df143d..5ea74ca411 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.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 .agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
-2026-06-29-todo-write-tool.md: 288932f641a37c13ea6beeb069ac360c4a8447c1
-2026-06-29-todo-write-tool.zh.md: 2eced2e1670c20726989137d441d1c78df289641
+2026-06-29-todo-write-tool.md: c4cf64b7876bd8b80df80fe6fc27005715f96b5e
+2026-06-29-todo-write-tool.zh.md: 1f797c5517df8affd66addecf2a8db43c1da3332
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
index 288932f641..c4cf64b787 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md
@@ -6,7 +6,7 @@ English | [中文](2026-06-29-todo-write-tool.zh.md)
 
 ## Problem
 
-The harness gives the model bash and subagent tools but no way to record a structured task list. A todo list serves two co-equal purposes: it steers the model to plan multi-step work and keep the active task unambiguous (at most one active, exactly one while work remains), and it gives an interactive host a live progress checklist. Every reference coding agent surveyed (claude-code, opencode, codex, oh-my-pi, pi) ships some form of this; the harness had nothing.
+The harness gives the model bash and subagent tools but no way to record a structured task list. A todo list serves two co-equal purposes: it steers the model to plan multi-step work and keep the active work unambiguous, and it gives an interactive host a live progress checklist. Every reference coding agent surveyed (claude-code, opencode, codex, oh-my-pi, pi) ships some form of this; the harness had nothing.
 
 ## Decision
 
@@ -34,7 +34,7 @@ Each list belongs to the calling agent session, and non-agent calls are rejected
 
 ### Validation: the cheap middle
 
-The schema enforces type/required/enum. Beyond that, `execute` rejects empty or duplicate `content` and more than one `in_progress` task. claude-code leaves single-in-progress to the prompt; oh-my-pi enforces it in code. We take the middle: enforce the cheap invariants that make a plan *coherent* (no blank tasks, no dupes, at most one active), but leave ordering and the discipline of keeping the list current to the model via the tool description. A rejected write returns an `isError` result so the model self-corrects.
+The schema enforces type/required/enum. Beyond that, `execute` rejects empty or duplicate `content` and, when `allowParallelInProgress` is `false`, more than one active task. Ordering and keeping the list current remain model disciplines expressed in the tool description. A rejected write returns an `isError` result so the model self-corrects. The required deployment policy and the durable invariant's independence from it are owned by the [parallel in-progress Agent Note](2026-07-26-todo-parallel-in-progress.md).
 
 ## Why no cordis-catalog entry / no `@mode`
 
diff --git a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
index 2eced2e167..1f797c5517 100644
--- a/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md
@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃任务明确（最多一个活跃，有剩余工作时恰好一个）；同时为交互式宿主提供实时进度清单。调研的所有参考编码 agent（智能体），包括 claude-code、opencode、codex、oh-my-pi 和 pi，都提供了某种形式的此功能；本 harness 此前没有。
+harness 为模型提供了 bash 和 subagent 工具，却没有办法记录结构化的任务列表。todo 列表有两个同等重要的用途：引导模型规划多步骤工作并保持当前活跃任务明确；同时为交互式宿主提供实时进度清单。调研的所有参考编码 agent（智能体），包括 claude-code、opencode、codex、oh-my-pi 和 pi，都提供了某种形式的此功能；本 harness 此前没有。
 
 ## 决策
 
@@ -34,7 +34,7 @@ claude-code V1 的条目是 `{ content, status, activeForm }`；后来（V2）
 
 ### 校验：低成本的中间路线
 
-schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，以及超过一个 `in_progress` 任务。claude-code 将单一 in_progress 交给提示词约束；oh-my-pi 在代码中强制。我们取中间路线：强制执行使计划*连贯*的低成本不变式（无空任务、无重复、最多一个活跃），但将排序和保持列表最新的纪律通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。
+schema 强制 type/required/enum。在此之上，`execute` 拒绝为空或重复的 `content`，并在 `allowParallelInProgress` 为 `false` 时拒绝超过一个活跃任务。排序和保持列表最新仍通过工具描述交给模型。被拒绝的写入返回 `isError` 结果，使模型自行修正。必填的部署策略及持久日志不变式独立于该策略这一约定，由[并行 in-progress Agent Note](2026-07-26-todo-parallel-in-progress.md) 负责。
 
 ## 为何没有 cordis-catalog 条目 / 没有 `@mode`
 
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
index aefda46d41..2acc3dd5b5 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.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 .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
-2026-07-22-durable-subagent-catalog-and-list-agents.md: 0dd7eebac74689004014248c7178dba540ef4662
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: 33b0296cf9914d1975fb1dc84564b498a09bd511
+2026-07-22-durable-subagent-catalog-and-list-agents.md: b96d6e1dd36c58af67c8e93e62515672790ad009
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: 856bac615db84bfe2898ec0838094c6bc29f77b2
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
index 0dd7eebac7..b96d6e1dd3 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md
@@ -12,6 +12,8 @@ Enumeration must cross-check immutable session lineage, descriptor validity, and
 
 ## Decision
 
+**Superseded read path.** [Subagent list identity via the projection unit](../architecture/2026-08-06-subagent-list-identity-projection.md) replaces this note's enumeration and per-child read design: `listChildren` now merges the live session store with optional session persistence directly and serves each child's mode/label from the registered `subagent` projection unit — no session-query dependency, no list-time descriptor scan — and that note owns the current listing semantics, including the diagnostic mapping. This note remains the authority for descriptor persistence, the mode-discriminated descriptor as durable identity, direct-parent authorization, and the model-facing `list_agents` projection; the trace-based read mechanics below are decision context, not current behavior.
+
 Parent-to-child enumeration is a service capability with consumer-specific projections. `SubagentService.listChildren(parentSessionId: SessionId)` ([subagent/src/index.ts](../../../../packages/subagent/subagent/src/index.ts)) does the following:
 
 - use `ctx.sessionQuery.traceSession(parentSessionId)` to obtain the parent's direct live-preferred child sessions;
@@ -33,7 +35,7 @@ Session lineage is broader than subagent identity: an ordinary `ctx.sessions.for
 
 The published logical record is also the activity source: `SessionRecord.live` means `running`, while `live: false, persisted: true` means `inactive`. Activity comes directly from the trace and causes no additional child-log load. `inactive` encodes neither successful completion nor resumability: it may describe settled one-shot history or a continuable child for which `send_message` can materialize another Activation. Conversely, `running` says only that the session is live: a live continuable Agent outside the continuation manager's matching Activation still appears as `running`, but `send_message` rejects it as an ownership conflict. A child is not visible before its session is published, and no process-local Activation entry is added as a second candidate or activity source. Listing is a snapshot that may race publication, disposal, or a later message; `send_message` remains the authoritative delivery-time operation.
 
-The subagent service keeps `sessionQuery` optional so start and follow-up remain available without it. Its public `listChildren(parentSessionId: SessionId)` method resolves the optional service and dynamically loads the optional session-query runtime only when called; ordinary subagent imports, start, and follow-up therefore do not evaluate that package. Listing belongs directly to `SubagentService`: it interprets the query's lineage, events, and live state without resolving the Activation-based continuation manager or consulting Agent registrations, Activations, or providers, so a deployment with sessions, `subagents`, and `sessionQuery` can list even when `agents` is absent. The method throws `SubagentError` with stable code `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` before loading the runtime or doing query work when the query service is absent. `@deepseek-ai/dsh-tool-subagent-control` exports separately loadable tool plugins: the `send_message` adapter requires only `subagents`, while the `list_agents` adapter requires both `subagents` and `sessionQuery` at load. A deployment may therefore use `send_message` without installing or loading session query; the list-tool fiber remains inactive until the required service is available, while another direct service consumer receives the same explicit call-time contract.
+The subagent service keeps `sessionQuery` optional so start and follow-up remain available without it. Its public `listChildren(parentSessionId: SessionId)` method resolves the optional service and dynamically loads the optional session-query runtime only when called; ordinary subagent imports, start, and follow-up therefore do not evaluate that package. Listing belongs directly to `SubagentService`: it interprets the query's lineage, events, and live state without resolving the Activation-based continuation manager or consulting Agent registrations, Activations, or providers, so a deployment with sessions, `subagents`, and `sessionQuery` can list even when `agents` is absent. The method throws `SubagentError` with stable code `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` before loading the runtime or doing query work when the query service is absent. `@deepseek-ai/dsh-tool-subagent-control` exports separately loadable tool plugins: the `send_message` adapter requires only `subagents`, while the `list_agents` adapter requires both `subagents` and `sessionQuery` at load. A deployment may therefore use `send_message` without installing or loading session query; the list-tool fiber remains inactive until the required service is available, while another direct service consumer receives the same explicit call-time contract. This dependency posture — the optional `sessionQuery`, its error code, and the list tool's load requirement — is part of the superseded read path: the current codes (`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`) and the narrowed load requirement live in the [superseding note](../architecture/2026-08-06-subagent-list-identity-projection.md).
 
 `listChildren(parentSessionId, signal?)` forwards the caller's signal to `traceSession()` and the conditional exact `readEvent()` operation. `listEvents()` has no cancellation parameter, so the listing path checks the signal before and after that await and after each candidate settles. If any query operation rejects after the signal aborts, the service normalizes the result to `SubagentError` with stable code `CANCELLED`; a backend abort error or a diagnostic-mapped query error cannot escape or become a successful partial listing.
 
@@ -91,9 +93,10 @@ The first version has no child deletion operation. If later product behavior del
 ## Testing
 
 - `packages/subagent/subagent/tests/service.spec.ts` pins descriptor v2 parsing for both modes and proves an unlabeled raw start resolves a one-shot descriptor before provider dispatch. `packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` proves the local driver appends that descriptor inside the initial turn, returns the published id when cancellation lands in the factory-to-run handoff, and keeps result and handle-disposal failures on separate channels. Delegation-tool tests pin propagation of their existing display description and preserve independent result and disposal diagnostics.
-- `packages/subagent/subagent/tests/list-children.spec.ts` pins a query-only composition with sessions, `subagents`, and `sessionQuery` but no `agents`, then drives the full real stack (agent loop, JSONL persistence, spawn/fork providers, the subagent service, and a concrete session-query service) keylessly: one-shot and continuable children from one real trace; a persisted (restart-shaped) parent target; `createdAt`-then-id ordering with authored ties; ordinary-fork and fork-seed ancestor-descriptor exclusion without diagnostics; live `running` vs persisted `inactive`; duplicate-descriptor, malformed-payload, invalid-surface, mismatched-header, and changed-read-target corruption diagnostics that leave healthy siblings visible; unsupported-version and per-child unavailable diagnostics; provider absence without child omission; compacted/uncompacted twins listing identically; grandchild exclusion; trace-phase failure failing the whole call while candidate-phase failures isolate to one child; configuration/window and unrecognized failures propagating as operation failures; forwarded trace/exact-read cancellation with stable `CANCELLED` normalization; and the `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` no-service contract. `packages/subagent/subagent/tests/optional-session-query.spec.ts` rejects eager evaluation of the optional runtime while importing the ordinary subagent surface.
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` pins the `list_agents` schema (no parameters), the continuable-only projection that omits a healthy one-shot sibling while preserving diagnostics, the fixed child/diagnostic/empty text forms, an end-to-end settled-child listing with its durable label, forwarding of the tool cancellation signal, the no-agent rejection, load-time `sessionQuery` injection, and HMR disposal.
-- The keyless ACP snapshot scenario `subagent-list-agents` (examples/acp-agent) fences its second parent turn on a snapshot-only `subagent/end` marker, then executes `list_agents` for real against the subagent service, session query, and JSONL persistence, rendering `<id> [complete] — <label>`.
+- `packages/subagent/subagent/tests/list-children.spec.ts` pins the current read path against a real composition of the session store, JSONL persistence, spawn/fork providers, the subagent service, and the projection registry — no query service — keylessly: live-only listing without persistence; loud `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` even with zero children; the three-rung ladder (a live child never inspected, a cold child inspected exactly once, and the cache-hit, absent-key, absent-service, and poisoned-row second-rung cases); last-wins over multiple descriptors; malformed payloads and unknown versions diagnosed as `corrupt`; a failed cold inspection as one `unavailable` diagnostic retried on the next listing; a fork seed's ancestor descriptor listed under that identity; foreign-unit fold failures contained per child as `corrupt` on both the live and cold paths; `createdAt`-then-id ordering without ordinary forks; provider absence without child omission; compacted/uncompacted twins listing identically; a persisted-listing failure failing the whole enumeration; cancellation normalized to stable `CANCELLED`; and typed stable error codes. A companion spec (retired together with the query-backed read path) rejected eager evaluation of the optional session-query runtime while importing the ordinary subagent surface.
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` pins the `list_agents` schema (no parameters), the continuable-only projection that omits a healthy one-shot sibling while preserving diagnostics, the fixed child/diagnostic/empty text forms, an end-to-end settled-child listing with its durable label, forwarding of the tool cancellation signal, the no-agent rejection, the narrowed load requirement without `sessionQuery`, and HMR disposal.
+- The keyless ACP snapshot scenario `subagent-list-agents` (examples/acp-agent) fences its second parent turn on a snapshot-only `subagent/end` marker, then executes `list_agents` for real against the subagent service, the projection registry, and JSONL persistence, rendering `<id> [complete] — <label>`.
+- The keyless snapshot scenario `subagent-diagnostic` (examples/headless-agent) pins the current listing's model-visible diagnostic classification, including a descriptor-less settled child surfacing as a `corrupt` diagnostic.
 - The keyless ACP snapshot scenario `subagent-published-run-failure` publishes a real one-shot child, injects independent run-result and handle-disposal failures, and preserves both diagnostics in the parent tool result.
 
 ## Consequences
diff --git a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
index 33b0296cf9..856bac615d 100644
--- a/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md
@@ -12,6 +12,8 @@ Status: implemented
 
 ## 决策
 
+**列表读路径已被取代。**[subagent 列表经投影单元读取身份](../architecture/2026-08-06-subagent-list-identity-projection.md)取代了本记录的枚举与逐 child 读取设计:`listChildren` 现在直接合并存活会话存储与可选的会话持久化,并从注册的 `subagent` projection unit 读取每个 child 的 mode/label——不依赖会话查询,也不在列表时扫描描述符;当前的列表语义(含 diagnostic 映射)以该记录为准。本记录仍是描述符持久化、以 mode 判别的描述符作为持久身份、直接 parent 鉴权与面向模型的 `list_agents` 投影的权威;下文基于追踪的读取机制是决策背景,不再是当前行为。
+
 parent 到 child 的枚举是一项带消费方专用投影的服务功能。`SubagentService.listChildren(parentSessionId: SessionId)`（[subagent/src/index.ts](../../../../packages/subagent/subagent/src/index.ts)）执行以下操作：
 
 - 使用 `ctx.sessionQuery.traceSession(parentSessionId)` 获取 parent 的直接且实时优先的 child 会话；
@@ -33,7 +35,7 @@ parent 到 child 的枚举是一项带消费方专用投影的服务功能。`Su
 
 已发布的逻辑记录同时也是活动状态来源：`SessionRecord.live` 表示 `running`，而 `live: false, persisted: true` 表示 `inactive`。活动状态直接来自追踪结果，不会导致额外加载 child 日志。`inactive` 既不表示执行成功，也不表示可恢复：它可能表示已结算的一次性历史，也可能表示 `send_message` 可以为其物化另一次 Activation 的可继续 child。反过来，`running` 只表示会话存活：位于继续执行管理器对应 Activation 之外的存活可继续 Agent 仍会显示为 `running`，但 `send_message` 会将其作为所有权冲突拒绝。child 会话发布前不可见，也不会添加进程内 Activation 条目作为第二个候选来源或活动状态来源。列表查询是一份快照，可能与发布、dispose 或后续消息发生竞态；`send_message` 仍是消息送达时的权威操作。
 
-subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时契约。
+subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法只在被调用时才会解析这个可选服务，并动态加载可选的会话查询运行时；因此，普通 subagent 导入、start 和 follow-up 都不会触发该包求值。列表查询直接由 `SubagentService` 负责：它解释查询返回的谱系、事件和存活状态，无需解析基于 Activation 的继续执行管理器，也不会查询 Agent 注册信息、Activation 或提供方；因此，仅包含会话、`subagents` 和 `sessionQuery` 的部署即使缺少 `agents` 也能执行列表查询。如果查询服务缺失，该方法会在加载运行时或执行查询工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在既不安装也不加载会话查询的情况下使用 `send_message`；列表工具 fiber 会在必需服务可用前保持未激活状态，而其他直接服务消费方会收到同一项明确的调用时契约。这一段的依赖姿态——可选 `sessionQuery`、其错误码与列表工具的加载要求——同属被取代的读路径：现行错误码（`SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`、`SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`）与收窄后的加载要求以[取代记录](../architecture/2026-08-06-subagent-list-identity-projection.md)为准。
 
 `listChildren(parentSessionId, signal?)` 会把调用方的取消信号转发给 `traceSession()` 和条件性精确 `readEvent()` 操作。`listEvents()` 不接受取消参数，因此列表查询路径会在等待该操作的前后，以及每个候选处理完成后检查信号。如果取消信号触发后有查询操作以拒绝结算，服务会将结果归一化为 `SubagentError`，并携带稳定错误码 `CANCELLED`；后端中止错误或可映射为 diagnostic 的查询错误均不会逃逸，也不会使调用以成功的部分列表返回。
 
@@ -91,9 +93,10 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 ## 测试
 
 - `packages/subagent/subagent/tests/service.spec.ts` 固定两种模式下的描述符 v2 解析，并证明无标签的底层启动会在分发给提供方之前解析出一次性描述符。`packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts` 证明本地驱动会在初始轮次内追加该描述符，在取消落入工厂到 run 的交接窗口时返回已发布 id，并让结果与句柄释放失败保留在独立通道中。委派工具测试固定其现有显示说明的传递，并保留相互独立的结果与 dispose diagnostic。
-- `packages/subagent/subagent/tests/list-children.spec.ts` 先固定一个只有会话、`subagents` 和 `sessionQuery` 而没有 `agents` 的纯查询组合，再以无密钥方式驱动完整真实栈（agent loop、JSONL 持久化、spawn/fork 提供方、subagent 服务，以及一个具体的会话查询服务）：来自同一真实追踪的一次性与可继续 child；只存在于持久化存储中（重启形态）的 parent 目标；带有人工构造并列项的按 `createdAt` 再按 id 排序；排除普通 fork 和 fork seed 中祖先描述符且不产生 diagnostic；存活 `running` 与持久化 `inactive` 的对比；重复描述符、载荷格式错误、无效 surface、header 不匹配和读取目标已变化的损坏 diagnostic 均不隐藏健康的 sibling；不受支持版本与逐 child unavailable diagnostic；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；排除孙代会话；追踪阶段失败导致整次调用失败而候选阶段失败只隔离到单个 child；配置／窗口错误和无法识别的失败作为操作失败向上传播；转发 trace／精确读取取消并稳定归一化为 `CANCELLED`；以及 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` 缺服务契约。`packages/subagent/subagent/tests/optional-session-query.spec.ts` 会在导入普通 subagent surface 时拒绝对可选运行时的 eager 求值。
-- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（无参数）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、child／diagnostic／空结果的固定文本形式、带持久化 label 的已结束 child 端到端列表、工具取消信号的转发、无调用 agent 时的拒绝、加载时的 `sessionQuery` 注入，以及 HMR dispose。
-- 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、会话查询和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
+- `packages/subagent/subagent/tests/list-children.spec.ts` 针对由会话存储、JSONL 持久化、spawn/fork 提供方、subagent 服务与投影注册表构成的真实组合——不含查询服务——以无密钥方式钉住现行读取路径：无持久化时的仅存活列表；零 children 也响亮报 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 与 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`；三级阶梯（存活 child 从不检查、冷 child 恰好检查一次，以及缓存命中、key 缺席、服务缺席、行中毒四个第二级用例）；多描述符 last-wins 取末者；载荷格式错误与未知版本诊断为 `corrupt`；冷检查失败成一条 `unavailable` diagnostic 并在下次列表重试；fork seed 中的祖先描述符按该身份列出；外部 unit 折叠失败在存活与冷两条路径上按 child 收纳为 `corrupt`；按 `createdAt` 再按 id 排序且不列普通 fork；提供方缺失时不排除 child；压缩与未压缩的孪生 child 列表结果一致；持久化列表失败使整次枚举失败；取消稳定归一化为 `CANCELLED`；以及带类型的稳定错误码。一个伴随规格(已随查询式读取路径一起退役)曾在导入普通 subagent surface 时拒绝对可选 session-query 运行时的 eager 求值。
+- `packages/subagent/tool-subagent-control/tests/list-agents.spec.ts` 固定 `list_agents` 的 schema（无参数）、只保留可继续 child 且排除健康的一次性 sibling、同时保留 diagnostic 的投影、child／diagnostic／空结果的固定文本形式、带持久化 label 的已结束 child 端到端列表、工具取消信号的转发、无调用 agent 时的拒绝、收窄后的加载要求（不再注入 `sessionQuery`），以及 HMR dispose。
+- 无密钥 ACP 快照场景 `subagent-list-agents`（examples/acp-agent）使用仅限快照的 `subagent/end` 标记为第二个 parent 轮次设置边界，随后针对 subagent 服务、投影注册表和 JSONL 持久化真实执行 `list_agents`，渲染 `<id> [complete] — <label>`。
+- 无密钥快照场景 `subagent-diagnostic`（examples/headless-agent）钉住现行列表的模型可见诊断分类，包括无描述符的定局 child 以 `corrupt` diagnostic 出现。
 - 无密钥 ACP 快照场景 `subagent-published-run-failure` 会发布一个真实的一次性 child，注入相互独立的 run result 与 handle dispose 失败，并在 parent 工具结果中保留两项 diagnostic。
 
 ## 影响
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
index e7e459429b..cc872a60c3 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.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 .agents/notes/implemented/feature/2026-07-23-web-todo-display.md
-2026-07-23-web-todo-display.md: d5939c0fa6ab83a61f1932622c4b6a150ccaded7
-2026-07-23-web-todo-display.zh.md: b1ecf679efe81016e00c5c1221c04730b3ce98bb
+2026-07-23-web-todo-display.md: 9e6e4914cd24d1db9271baa3d3fb6fdc56a9ac65
+2026-07-23-web-todo-display.zh.md: 5a5ac554b37c255a7d8c1ce821ebeb1b3f9f091f
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md
index d5939c0fa6..9e6e4914cd 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.md
@@ -18,11 +18,11 @@ Consume `todo/write` as a Session side effect, not a surface node, and render it
 
 ### TodoPanel: the durable list as a persistent strip
 
-The panel mounts through the `conversation.input.dock` slot (a plain registrant plugin, `todoDockEntry`, using `ctx.slots.inject` with no `ConversationService` edge, `order: -1` above the queue rows), hidden while empty, collapsible to a header of title + `"<done>/<total> tasks · <n> in progress"` (no in-progress content hint when collapsed). Status glyphs are the figma todo set (green check ring / blue fading ring / dashed pending ring) on a tip-surface card (`--dsw-specific-tip`, 14px radius, `width: calc(100% - 88px)` / `max-width: 776px` centered; InputBar top pad 6px is the gap to the composer card). It reads `snapshot.todos` via the standard-kit `useSession` hook the dock entry receives — no store, no service, no ctx. The inner component stays props-complete and framework-free; the dock adapter is a one-line wrapper.
+The panel mounts through the `conversation.input.dock` slot (a plain registrant plugin, `todoDockEntry`, using `ctx.slots.inject` with no `ConversationService` edge, `order: 0` above the queue rows), hidden while empty, collapsible to a header of title + `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted; no in-progress content hint when collapsed). Status glyphs are the figma todo set (green check ring / blue fading ring / dashed pending ring) on a tip-surface card (`--dsw-specific-tip`, 14px radius, `width: calc(100% - 88px)` / `max-width: 776px` centered; InputBar top pad 6px is the gap to the composer card). It reads the host-computed `todos` projection via the standard-kit `useProjection` hook the dock entry receives — no store, no service, no ctx. The inner component stays props-complete and framework-free; the dock adapter is a one-line wrapper.
 
 ### TodoRow: the per-call row through the keyed toolview slot
 
-The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`, mounted from `apply`) that registers into the keyed `conversation.chat.toolview` slot through `ctx.slots.inject`, the same declaration-lifetime posture as the bash sample but a product registration. The summary derives from call args (`N/M done · active item`); unparseable args fall back to the generic row summary; clicking opens the details column with the raw args. No `ToolEventView` is added for todo — presentation is client-owned, and the durable list renders from the session event, not the tool card.
+The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`, mounted from `apply`) that registers into the keyed `conversation.chat.toolview` slot through `ctx.slots.inject`, the same declaration-lifetime posture as the bash sample but a product registration. The summary derives from call args (`N/M done · first active item`, with a `+<n>` count of the other active ones in `ToolRow`'s non-shrinking `summarySuffix` slot); unparseable args fall back to the generic row summary; clicking opens the details column with the raw args. No `ToolEventView` is added for todo — presentation is client-owned, and the durable list renders from the session event, not the tool card.
 
 ## Alternatives considered
 
@@ -33,4 +33,4 @@ The dedicated `todo_write` chat row is a plain registrant plugin (`todoToolview`
 
 ## Consequences
 
-Replay correctness is owned by one code path: any future change to window rebuild keeps todos consistent for free, and the fixture (fx-alpha turn 65) plus the assembled keyless snapshot (`apps/web/tests/todo-display.snapshot.ts`) pin the full chain (row summary and state, dock panel content, collapse round-trip) over the built client graph. `todos` is a required `ConversationSnapshot` field, so scripted fakes in specs must carry it. The TUI panel shares the same turn-scoped lifetime (the automation-only ACP bridge deliberately omits todo presentation); the web surfaces render the same event, adding one wire field and no new event type. That field is how cold-load reconstruction stays host-backed: the tail history page carries `todos` — the full-log standing plan (latest `todo/write` with no later `turn/start`), computed independently of the page window (the same backscan posture the view pairing uses) — so a reopened session restores the plan when it still stands and the last write precedes the window; that value survives an older-page prepend, is overwritten by any later write, clears on a later `turn/start`, and resets to empty when a tail response carries no projection.
+Replay correctness is owned by one code path: any future change to window rebuild keeps todos consistent for free, and the fixture (fx-alpha turn 71) plus `packages/client/ui-conversation/tests/todo-panel.spec.tsx` pin the full chain (row summary and state, dock panel content, collapse round-trip). `todos` is a required `ConversationSnapshot` field, so scripted fakes in specs must carry it. The automation-only ACP bridge deliberately omits todo presentation; the web surfaces render the same event, adding one wire field and no new event type. That field is how cold-load reconstruction stays host-backed: the tail history page carries `todos` — the full-log standing plan (latest `todo/write` with no later `turn/start`), computed independently of the page window (the same backscan posture the view pairing uses) — so a reopened session restores the plan when it still stands and the last write precedes the window; that value survives an older-page prepend, is overwritten by any later write, clears on a later `turn/start`, and resets to empty when a tail response carries no projection.
diff --git a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
index b1ecf679ef..5a5ac554b3 100644
--- a/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md
@@ -18,11 +18,11 @@ Status: implemented
 
 ### TodoPanel：持久化列表作为一条常驻横条
 
-面板经 `conversation.input.dock` slot 挂载（普通注册者插件 `todoDockEntry` 使用 `ctx.slots.inject`，不依赖 `ConversationService`，`order: -1` 排在队列条上方），空列表时隐藏，可折叠为标题加 `"<已完成>/<总数> tasks · <n> in progress"` 的表头（折叠态不再附带进行中条目正文）。状态图标为 figma todo 套件（绿色勾选环／蓝色渐隐环／虚线未开始环），卡片使用 tip 表面（`--dsw-specific-tip`、14px 圆角、`width: calc(100% - 88px)`／`max-width: 776px` 居中；InputBar 顶部 6px 内边距是到输入卡的间距）。它经 dock entry 收到的标准件 `useSession` hook 读取 `snapshot.todos`——无 store、无 service、无 ctx。内部组件保持 props 完备且框架无关；dock 适配件只是一行包装。
+面板经 `conversation.input.dock` slot 挂载（普通注册者插件 `todoDockEntry` 使用 `ctx.slots.inject`，不依赖 `ConversationService`，`order: 0` 排在队列条上方），空列表时隐藏，可折叠为标题加以 `·` 连接的各状态计数的表头（本地化，形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略；折叠态不再附带进行中条目正文）。状态图标为 figma todo 套件（绿色勾选环／蓝色渐隐环／虚线未开始环），卡片使用 tip 表面（`--dsw-specific-tip`、14px 圆角、`width: calc(100% - 88px)`／`max-width: 776px` 居中；InputBar 顶部 6px 内边距是到输入卡的间距）。它经 dock entry 收到的标准件 `useProjection` hook 读取 host 计算的 `todos` 投影——无 store、无 service、无 ctx。内部组件保持 props 完备且框架无关；dock 适配件只是一行包装。
 
 ### TodoRow：经 keyed toolview slot 的逐调用行
 
-专用的 `todo_write` 对话行是一个普通注册者插件（`todoToolview`，由 `apply` 挂载），经 `ctx.slots.inject` 注册进 keyed 的 `conversation.chat.toolview` slot，遵循与 bash 样例相同的声明生命周期，但属产品级注册。摘要由调用 args 推导（`N/M done · active item`）；无法解析的 args 回退到通用行摘要；点击会以原始 args 打开 details 列。todo 不新增任何 `ToolEventView`——呈现归客户端所有，常驻列表从会话事件渲染，而非工具卡。
+专用的 `todo_write` 对话行是一个普通注册者插件（`todoToolview`，由 `apply` 挂载），经 `ctx.slots.inject` 注册进 keyed 的 `conversation.chat.toolview` slot，遵循与 bash 样例相同的声明生命周期，但属产品级注册。摘要由调用 args 推导（`N/M done · first active item`，其余活跃项的 `+<n>` 计数放在 `ToolRow` 的不收缩 `summarySuffix` 位里）；无法解析的 args 回退到通用行摘要；点击会以原始 args 打开 details 列。todo 不新增任何 `ToolEventView`——呈现归客户端所有，常驻列表从会话事件渲染，而非工具卡。
 
 ## 考虑过的替代方案
 
@@ -33,4 +33,4 @@ Status: implemented
 
 ## 后果
 
-回放正确性由一条代码路径掌管：未来对窗口重建的任何改动都会自然保持 todos 一致；fx-alpha 第 65 轮的 fixture（测试前置数据）加上组装后的无密钥快照（`apps/web/tests/todo-display.snapshot.ts`）在构建后的完整客户端依赖图中固定整条链（行摘要与状态、dock 面板内容、折叠往返）。`todos` 是 `ConversationSnapshot` 的必填字段，所以 spec 里脚本化的 fake 必须带上它。TUI 面板共用同一按轮次界定的生命周期（自动化专用的 ACP 桥接刻意不做 todo 呈现）；Web 各面渲染同一个事件，只新增一个协议字段，不新增事件类型。这个由 host 提供的字段正是冷加载重建的依据：history 尾页附带 `todos`——全量 log 上当前有效的计划（其后没有更晚 `turn/start` 的最近一次 `todo/write`），独立于分页窗口计算（与 view 配对同一种 backscan 姿势）——因此重开会话时若计划仍然有效且最后一次写入落在窗口之前，计划也照常恢复；该值跨往前翻页保留，之后的任何写入照常覆盖，更晚的 `turn/start` 会清空，而尾页响应不带投影时复位为空。
+回放正确性由一条代码路径掌管：未来对窗口重建的任何改动都会自然保持 todos 一致；fx-alpha 第 71 轮的 fixture（测试前置数据）加上 `packages/client/ui-conversation/tests/todo-panel.spec.tsx` 固定整条链（行摘要与状态、dock 面板内容、折叠往返）。`todos` 是 `ConversationSnapshot` 的必填字段，所以 spec 里脚本化的 fake 必须带上它。自动化专用的 ACP 桥接刻意不做 todo 呈现；Web 各面渲染同一个事件，只新增一个协议字段，不新增事件类型。这个由 host 提供的字段正是冷加载重建的依据：history 尾页附带 `todos`——全量 log 上当前有效的计划（其后没有更晚 `turn/start` 的最近一次 `todo/write`），独立于分页窗口计算（与 view 配对同一种 backscan 姿势）——因此重开会话时若计划仍然有效且最后一次写入落在窗口之前，计划也照常恢复；该值跨往前翻页保留，之后的任何写入照常覆盖，更晚的 `turn/start` 会清空，而尾页响应不带投影时复位为空。
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
new file mode 100644
index 0000000000..6b0ce3f378
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
+2026-07-26-todo-parallel-in-progress.md: 2805ef894050d1b1cffe06fce59a4984d463f8d1
+2026-07-26-todo-parallel-in-progress.zh.md: 16b32daa05b10f24eacde4cec9622b2159cdef09
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
new file mode 100644
index 0000000000..2805ef8940
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md
@@ -0,0 +1,54 @@
+# Agent Note: Allow several `in_progress` todos at once
+
+Status: implemented
+
+English | [中文](2026-07-26-todo-parallel-in-progress.zh.md)
+
+## Problem
+
+The [original `todo_write` design](2026-06-29-todo-write-tool.md) enforced at most one `in_progress` task per list, both in `execute` and in the durable-log invariant. That invariant assumes sequential work, but the harness runs genuinely parallel work — concurrent subagents through the delegation tool, background bash commands, workflow fan-out — and a list that can name only one active task cannot represent it. The model was forced to either mislabel parallel tasks as `pending` or merge them into one vague item, and the UI progress checklist under-reported what was actually running.
+
+## Decision
+
+Make the single-`in_progress` cap a deployment policy instead of a fixed rule, requiring every composition to choose:
+
+- `packages/todo/tool-todo/src/index.ts` gains the required `Config.allowParallelInProgress` field. At `true`, `execute` accepts any number of active items and the description instructs the model to mark every actively-worked task — several during parallel work, one for sequential work — keeping at least one while work remains. At `false`, the description asks for exactly one and `execute` rejects a call marking more.
+- The durable-log invariant in `packages/todo/tool-todo/src/invariant.ts` no longer rejects snapshots with several active items, and does not follow the config, so previously-persisted logs are unaffected and parallel snapshots replay cleanly under either policy.
+
+The remaining coded invariants are unchanged: non-empty trimmed unique `content`, valid status enum. This supersedes the "at most one active" clause of the [original design's validation decision](2026-06-29-todo-write-tool.md); the rest of that Agent Note (whole-list replace, log-backed state, single owner) stands.
+
+## Why guidance, not a parallelism-aware invariant
+
+A coded invariant can only see the list, not the runtime: whether two `in_progress` items are legitimate depends on whether work is actually running concurrently, which the tool cannot observe. Enforcing a cap was therefore wrong in exactly the cases parallelism made it matter, and any replacement (for example, capping active items at the live subagent count) would couple the tool to runtimes it deliberately knows nothing about. The discipline of matching `in_progress` marks to genuinely concurrent work moves to the tool description, the same place ordering and list freshness already live.
+
+## The policy is a deployment choice
+
+Whether concurrent active tasks are legitimate depends on runtime concurrency the tool cannot observe — but whether a deployment's agents ever run work concurrently is knowable at composition time. That makes the policy a required `Config` field rather than a constant or default: every cordis.yml composition sets `allowParallelInProgress` deliberately, choosing `true` for agents that may fan out work or `false` for the single-active discipline.
+
+The flag moves the model-facing instruction and the accepted input together. Splitting them would be the bug: a description asking for one active task while `execute` accepts several teaches the model a rule the tool does not hold, and the reverse rejects calls the description invited. Only the active-status clause of the description varies, because that is the only instruction the policy changes.
+
+The durable-log invariant deliberately does NOT follow the flag. A log written while parallel work was allowed must still replay after a deployment tightens the policy, so tying `invariant.ts` to the current config would reject history that was valid when it was written. The invariant stays silent on the active count; the tool is where the policy applies, at the moment of the write.
+
+## Alternatives considered
+
+- **Keep the cap and add an explicit parallel opt-in flag** — an extra argument on every call to serve the common case; the flag would be noise for sequential work and still unverifiable.
+- **Cap active items at a configured maximum** — any fixed number is arbitrary. This is why the config field is a boolean policy switch and not a count: "may several tasks be active" is a property of the deployment, while "at most N" invents a threshold nothing can justify.
+- **Hardcode the parallel policy** — the first revision of this branch did, which is what made `allowParallelInProgress` necessary: a deployment running strictly sequential agents had no way back to the discipline it wanted.
+
+## The display surfaces are part of the change
+
+Lifting the cap makes a list shape reachable that no renderer had ever received, so this branch stacks on the [web todo display](2026-07-23-web-todo-display.md) rather than landing beside it: both change `tool-todo`, and the GUI is where a parallel plan becomes visible. Two web sites derived their one-line summary with `todos.find(t => t.status === 'in_progress')` — the collapsed plan-strip header and the `todo_write` row — and under the old cap that `find` was total, since at most one item could match. With several active it silently dropped every active item but the first: a four-item plan with three running tasks collapsed to the name of one, and the row read `1/4 已完成 · <one task>` while two others were in flight. The expanded list was always correct (it maps every item), which is why neither PR's tests caught it — only the collapsed header and the row lost information. The panel redesign in [#740](https://github.com/deepseek-harness/deepseek-harness/pull/740) has since replaced the collapsed header's named hint with `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted), which reports parallel work correctly and needs no name to truncate; the row is the one site this branch still had to fix.
+
+The row takes `planSummary` in `toolviews/plan-summary.ts`. It names the first active item and counts the rest, so the row reports how many tasks are running instead of implying one. Naming every active item was rejected: the row is a single line, and an unbounded join would overflow it — the count degrades predictably where a list does not. The derivation sits inside the toolviews domain rather than in `contract/`, the inter-domain face: the panel computes its own counts inline and shares nothing with the row, so a contract module would declare a sharing relationship that no longer exists.
+
+`planSummary` returns the name and the count as separate fields rather than one joined string, because the row truncates its summary with `overflow: hidden` / `text-overflow: ellipsis`. A count appended to the task name sits at the far end of the truncatable text, so exactly the narrow viewports and long task names that make the count informative are the ones that clip it away, leaving a parallel plan indistinguishable from a sequential one. The row therefore hands the count to the shared `ToolRow` as `summarySuffix`, a non-shrinking slot beside the ellipsized summary text; a pre-joined string could not express that split, and pushing the count in front of the name was rejected because the task name is what the reader is looking for first.
+
+`summarySuffix` is a slot on `ToolRow` rather than markup owned by the todo row: every toolview renders through that shared component, whose `summary` is a plain ellipsized string with no place for a fragment that must survive the clip. Sitting outside the `.summary` rule, the suffix repeats that rule's `font-size` and `line-height` — the web shell leaves body text at the browser default rather than the row's 14px, so an unstyled span renders visibly larger than the text beside it on a 24px row. An error row drops the suffix, because its collapsed summary is the failure line rather than anything derived from the call args.
+
+## Deferred
+
+Two review findings are recorded here rather than fixed on this branch. The `summarySuffix` span carries no accessible name, so a screen reader reads the count without its noun (`… 实现 fixture 样本 +1`); naming it introduces localized copy with its own test contract, which belongs to an accessibility pass over the whole `ToolRow` summary line rather than to one row. And when the *first* active item's content is unusable — missing, mistyped, or blank once trimmed — the row drops the active clause and the count with it, so a parallel plan renders as bare counts; skipping forward to the first usable active item was rejected because call args are an explicitly unvalidated boundary where model order is the only ordering the row can honour, and dropping the unusable clause alone keeps the `done`/`total` counts, which are trustworthy regardless.
+
+## Consequences
+
+A todo list can now faithfully mirror parallel execution, and every surface renders several active markers at once: the plan strip's header counts the active items, and the row needed the derivation above. A composition that sets `allowParallelInProgress: true` no longer rejects a formerly-invalid snapshot shape; one that sets `false` keeps the old rejection, and the durable-log invariant accepts both. The model-facing description changed, which re-recorded the tool-catalog page and every snapshot sidecar carrying the todo schema. No count is recorded here: the set grows with every pinning scenario that lands, and the two point-in-time censuses this note previously carried were both stale within days. The operative rule is that a branch changing the tool description must refresh whichever sidecars landed after it branched — including the numbered `tool-schemas.<n>.expected.json` files pinning a subagent class, whose schemas the parent scenario does not cover — and `pnpm run test:snapshot:refresh` does it keylessly over the whole corpus. The web fixture's todo sample now runs two items `in_progress`, so both fixture-driven surfaces render a parallel plan. `packages/client/ui-conversation/tests/todo-panel.spec.tsx` pins the row summary and the plan strip over src, the ACP `todo-write` scenario records a three-todo plan with two active, and `apps/web/tests/todo-row.snapshot.ts` pins both surfaces in the assembled application — booted from the built `packages/client/*/lib/client.js` bundles, so it is the one place the keyed registration and the bundled wiring are under test. That last file records `summary`, `suffix`, and the strip's header as separate fields, so folding the `+N` count back into the summary string changes the expected output even though the concatenated text would read the same.
diff --git a/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
new file mode 100644
index 0000000000..16b32daa05
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md
@@ -0,0 +1,54 @@
+# Agent Note: 允许同时存在多个 `in_progress` todo
+
+Status: implemented
+
+[English](2026-07-26-todo-parallel-in-progress.md) | 中文
+
+## 问题
+
+[原始 `todo_write` 设计](2026-06-29-todo-write-tool.md)在 `execute` 和持久日志不变式中都强制每个列表至多一个 `in_progress` 任务。该不变式假设工作是顺序进行的，但 harness 会运行真正并行的工作（通过委派工具启动的并发 subagent、后台 bash 命令、工作流扇出），而一个只能标出单个活跃任务的列表无法表示这种情况。模型被迫要么把并行任务错误标记为 `pending`，要么把它们合并成一个含糊的条目，导致 UI 进度清单少报了实际正在运行的工作。
+
+## 决策
+
+把单一 `in_progress` 上限从固定规则改为部署策略，并要求每个组合都作出选择：
+
+- `packages/todo/tool-todo/src/index.ts` 新增必填的 `Config.allowParallelInProgress` 字段。为 `true` 时，`execute` 接受任意数量的活跃条目，描述指示模型把每个正在处理的任务标记为 `in_progress`（并行工作时可以有多个，顺序工作时只有一个），并在仍有工作未完成时至少保留一个；为 `false` 时，描述要求恰好一个，`execute` 拒绝标记更多的调用。
+- `packages/todo/tool-todo/src/invariant.ts` 中的持久日志不变式不再拒绝含多个活跃条目的快照，且不跟随该配置，因此此前持久化的日志不受影响，并行快照在任一策略下都能干净回放。
+
+其余编码的不变式保持不变：`content` 去除首尾空白后非空且唯一、status 为合法枚举值。本决定取代[原始设计的校验决策](2026-06-29-todo-write-tool.md)中「至多一个活跃」的条款；该 Agent Note 的其余部分（整列表替换、日志支撑的状态、单一所有者）依然成立。
+
+## 为何用指引而非感知并行的不变式
+
+编码的不变式只能看到列表，看不到运行时：两个 `in_progress` 条目是否合理，取决于工作是否真的在并发运行，而这一点工具无法观测。因此，恰恰在并行让上限变得重要的场景里，强制上限反而是错的；任何替代方案（例如把活跃条目数限制为在线 subagent 的数量）都会把工具耦合到它有意一无所知的运行时上。把 `in_progress` 标记与真正并发的工作对应起来这一纪律，转移到工具描述中，也就是排序与列表新鲜度已经所在的地方。
+
+## 该策略是部署层的选择
+
+并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况——但一个部署的 agent 是否会并发展开工作，在组装期就是可知的。因此该策略是必填的 `Config` 字段，而非常量或默认值：每个 cordis.yml 组合都会有意设置 `allowParallelInProgress`，为可能并行展开工作的 agent 选择 `true`，或为单活跃项纪律选择 `false`。
+
+该开关会同时改变面向模型的指令与接受的输入。把两者拆开才是 bug：描述要求只保留一个活跃任务、而 `execute` 却接受多个，等于教给模型一条工具并不遵守的规则；反过来则会拒绝描述所邀请的调用。描述中只有活跃状态那一句会变化，因为这是该策略唯一改变的指令。
+
+持久日志不变式刻意**不**跟随该开关。在允许并行时写下的日志，在部署收紧策略之后仍必须可回放，因此把 `invariant.ts` 绑定到当前配置会拒绝在写入当时合法的历史。不变式对活跃数量保持沉默；策略生效之处是工具，时机是写入的那一刻。
+
+## 曾考虑的替代方案
+
+- **保留上限并增加一个显式的并行 opt-in 标志**——为服务常见场景而给每次调用增加一个额外参数；这个标志对顺序工作而言只是噪声，而且仍然无法验证。
+- **把活跃条目限制在一个可配置的上限内**——任何固定数字都是任意的。这正是该配置字段是布尔策略开关而非数量的原因：「是否允许多个任务同时活跃」是部署的属性，而「最多 N 个」凭空发明了一个无从论证的阈值。
+- **把并行策略硬编码**——本分支的第一版就是如此，这也是 `allowParallelInProgress` 之所以必要的原因：运行严格顺序 agent 的部署没有任何办法回到它想要的纪律。
+
+## 展示面是本次改动的一部分
+
+解除上限使一种此前任何渲染器都不曾收到的列表形状变得可达，因此本分支 stack（栈叠）在 [web todo 展示](2026-07-23-web-todo-display.md)之上，而不是与之并行落地：两者都改 `tool-todo`，而 GUI 正是并行计划变得可见的地方。web 有两处用 `todos.find(t => t.status === 'in_progress')` 推导单行摘要——折叠态的计划横条表头与 `todo_write` 工具行——在旧上限下这个 `find` 是完备的，因为最多只能有一个条目匹配。一旦有多个活跃项，它会静默丢掉除第一个之外的全部活跃条目：一个四条目、三个任务在跑的计划折叠后只显示其中一个的名字，工具行读作 `1/4 已完成 · <一个任务>`，而另外两个仍在进行。展开态的列表始终正确（它遍历每个条目），这也是两个 PR 的测试都没抓到它的原因——只有折叠表头与工具行丢失了信息。其后 [#740](https://github.com/deepseek-harness/deepseek-harness/pull/740) 的面板重做已把折叠表头的具名提示换成以 `·` 连接的各状态计数（本地化后形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略），它能正确报告并行工作，且不需要任何可被截断的名字；工具行才是本分支仍需修的那一处。
+
+工具行改用 `toolviews/plan-summary.ts` 中的 `planSummary`。它给出第一个活跃条目，并计数其余活跃项，因此工具行报告的是有多少任务在跑，而不是暗示只有一个。列出全部活跃条目被否决了：工具行是单行，无上界的拼接会溢出——在列表做不到的地方，计数能够可预测地降级。该推导放在 toolviews 域内而非 `contract/`（域间共享面）：面板自行内联计算其计数，与工具行不共享任何东西，因此放进 contract 会声明一种已不存在的共享关系。
+
+`planSummary` 把任务名与计数作为两个独立字段返回，而不是一个拼好的字符串，因为工具行用 `overflow: hidden` / `text-overflow: ellipsis` 截断其摘要文本。计数接在任务名之后时位于可截断文本的末端，于是恰恰是让计数变得有意义的那些场景——窄视口、长任务名——会把它裁掉，让并行计划看起来与顺序计划无异。因此工具行把计数交给共享的 `ToolRow`，作为 `summarySuffix`——一个紧邻被省略号截断的摘要文本、且不会收缩的槽位；一个预先拼好的字符串无法表达这个切分，而把计数放到任务名之前也被否决了：读者首先要找的是任务名。
+
+`summarySuffix` 是 `ToolRow` 上的槽位，而不是 todo 工具行自有的标记：每个 toolview 都经由这个共享组件渲染，而它的 `summary` 是一个会被省略号截断的普通字符串，容不下一个必须挺过截断的片段。该后缀落在 `.summary` 规则之外，因此重复了该规则的 `font-size` 与 `line-height`——Web 外壳把正文字号留在浏览器默认值而非该行的 14px，所以未加样式的 span 会明显大于同一 24px 行内与之并列的文本。错误行会丢弃该后缀，因为它折叠态的摘要是失败行，而非任何由调用 args 推导出的内容。
+
+## 暂缓项
+
+两条 review 结论在此记录而非在本分支修复。`summarySuffix` 这个 span 没有无障碍名称，屏幕阅读器读出的数量缺少它所修饰的名词（`… 实现 fixture 样本 +1`）；为它命名会引入带自身测试契约的本地化文案，这属于对整条 `ToolRow` 摘要行做的无障碍专项，而不属于某一行。以及，当*第一个*活跃条目的 content 不可用时——缺失、类型不对、或 trim 后为空——行会连同数量一起丢掉活跃子句，于是并行计划渲染成裸计数；向后跳到第一个可用活跃条目的方案被否决，因为调用 args 是一处明确未经校验的边界，模型给出的顺序是该行唯一能遵循的顺序，而只丢掉不可用的那个子句可以保住 `done`/`total` 计数——这两个数无论如何都是可信的。
+
+## 后果
+
+现在 todo 列表可以忠实反映并行执行，并且每个展示面都能一次渲染多个活跃标记：计划横条的表头会计数活跃条目，工具行则需要上述推导。设置 `allowParallelInProgress: true` 的组合不再拒绝一种此前无效的快照形状；设置为 `false` 的组合仍保留旧的拒绝行为，而持久日志不变式两者都接受。面向模型的描述发生了变化，这重新记录了 tool-catalog 页面以及每个带有 todo schema 的快照 sidecar。此处不记录数量：该集合会随每个新落地的 pin 场景增长，而本 Note 先前记过的两次点时刻计数都在几天内失实。有效规则是：改动工具描述的分支必须刷新它分叉之后落地的那些 sidecar —— 包括固定 subagent 类工具的编号文件 `tool-schemas.<n>.expected.json`，其 schema 不被父场景覆盖 —— `pnpm run test:snapshot:refresh` 可以无 key 地对整个语料完成刷新。web fixture 的 todo 样本现在有两个条目处于 `in_progress`，因此两个由 fixture 驱动的展示面渲染的都是并行计划。`packages/client/ui-conversation/tests/todo-panel.spec.tsx` 在 src 上固定工具行摘要与计划横条，ACP `todo-write` 场景录制的是三条目、两个活跃的计划，而 `apps/web/tests/todo-row.snapshot.ts` 在组装后的应用中固定这两个面——它从构建产物 `packages/client/*/lib/client.js` 启动，因此是唯一覆盖 keyed 注册与打包接线的地方。该文件把 `summary`、`suffix` 与横条表头记录为独立字段，因此即便拼接后的文本读起来一样，把 `+N` 计数折回摘要字符串也会改变预期输出。
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
index e35daaaf42..d5dbd53881 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.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 .agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
-2026-07-29-persistent-bash-str-replace-editor.md: 22851078c1cc8fa9d5716afa41c8a2e2b7e7725c
-2026-07-29-persistent-bash-str-replace-editor.zh.md: 23f80d1a5911f4f3820d526c2221d3002507d774
+2026-07-29-persistent-bash-str-replace-editor.md: c4750e30370bfd253064c39cb1adc0f5b2baa60d
+2026-07-29-persistent-bash-str-replace-editor.zh.md: 62073571ce2164d88897d4959caafd9cb1dbdd93
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
index 22851078c1..c4750e3037 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
@@ -18,7 +18,7 @@ Some deployments need a one-call Bash schema whose shell state survives across m
 
 Both plugins are included in the Python runtime closure. The persistent Bash closure also includes the PTY service/local backend and the sandbox services required by that backend. Because `node-pty` executes a native `spawn-helper` on macOS, each packaged macOS runtime executable ships with a `-spawn-helper` sibling; Linux uses `forkpty` directly. A pinned `node-pty` patch checks `DSH_NODE_PTY_SPAWN_HELPER` first, so it remains a true override for a current external consumer that supplies a non-sibling helper. When the override is unset, the patch resolves the packaged executable sibling if present and otherwise preserves upstream lookup in ordinary Node runs. The macOS builders fail before publication when the helper is absent or not executable.
 
-The shipped [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay composes both plugins over the ordinary Web surface, disables its other model-facing consumers, and leaves the Web host, browser, Workspace, persistence, sandbox, and permission stack in place. The local PTY backend resolves the effective session sandbox mode when it creates the shell. While that owner has an open shell or a spawn in progress, a different permission mode is rejected before its session event commits; the editor continues through the Web filesystem sandbox.
+The shipped [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay composes both plugins over the ordinary Web surface for the Claude SWE-compatible RL contract. It pins native tool mode and makes the complete system prompt `DSH_SYSTEM_PROMPT` when set or `You are a helpful software engineer assistant.` otherwise, with no harness identity, source-checkout section, Web orientation, Workspace instructions, or tool-mode guidance. It disables every other model-facing consumer, so the model receives exactly the persistent `bash` and `str_replace_editor` schemas, while the Web host, browser, Workspace, persistence, sandbox, and permission stack remains in place. The local PTY backend resolves the effective session sandbox mode when it creates the shell. While that owner has an open shell or a spawn in progress, a different permission mode is rejected before its session event commits; the editor continues through the Web filesystem sandbox.
 
 ## Alternatives considered
 
diff --git a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
index 23f80d1a59..62073571ce 100644
--- a/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 两个插件都进入 Python runtime 闭包。持久 Bash 的闭包还包含 PTY 服务／本地后端，以及该后端要求的沙箱服务。由于 `node-pty` 在 macOS 上会执行原生 `spawn-helper`，每个打包后的 macOS 运行时可执行文件都会携带一个 `-spawn-helper` 伴随文件；Linux 直接使用 `forkpty`。固定版本的 `node-pty` 补丁会先检查 `DSH_NODE_PTY_SPAWN_HELPER`，因此对当前提供非伴随 helper 的外部消费方而言，该变量仍是真正的覆盖项。未设置该覆盖时，补丁会在打包可执行文件的伴随文件存在时解析它，否则在普通 Node 运行中保留上游查找方式。若 helper 缺失或不可执行，macOS 构建器会在发布前失败。
 
-已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) 覆盖层在常规 Web 界面之上组合这两个插件，禁用该界面的其他面向模型的消费方，并保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
+已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay 会在常规 Web 界面之上组合这两个插件，以满足与 Claude SWE 兼容的 RL 契约。它固定使用原生工具模式；完整的系统提示词在设置 `DSH_SYSTEM_PROMPT` 时采用其值，否则采用 `You are a helpful software engineer assistant.`，且不包含 harness 身份、源码 checkout 提示词段、Web 界面定位、Workspace 指令或工具模式指引。它会禁用其他所有面向模型的消费方，使模型恰好只收到持久 `bash` 和 `str_replace_editor` 两个 schema，同时保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
 
 ## 考虑过的替代方案
 
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
new file mode 100644
index 0000000000..4673ffaab7
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
+2026-08-04-claude-code-and-codex-subagent-backends.md: e81d1fb14f719331c503dba539d6a5ec0f1eed4f
+2026-08-04-claude-code-and-codex-subagent-backends.zh.md: 3c78e8d5a4ca1a86942971721ad05c631901f231
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
new file mode 100644
index 0000000000..e81d1fb14f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
@@ -0,0 +1,94 @@
+# Agent Note: Claude Code and Codex subagent backends
+
+Status: implemented
+
+English | [中文](2026-08-04-claude-code-and-codex-subagent-backends.zh.md)
+
+## Problem
+
+The named [`ctx.subagents`](2026-06-21-subagent-capability-seam.md) registry lets a parent agent delegate work without knowing how the child runs, but the harness needs first-party routes to the real Codex and Claude Code products. Each route must hand the product one self-contained task, let it work in the parent Session's workspace, return a final answer or an explicit failure or cancellation, and leave no managed product process behind.
+
+The product integrations must not become second owners for task text, cwd, cancellation, result settlement, or process trees. Required evidence therefore separates three facts: a keyless real-product test proves the official integration, native authentication shape, deterministic answer, and teardown; a Loader composition test proves that the public package and documented tool configuration load without starting the product; and a credentialed e2e proves that the production provider and real product can obtain a unique answer from the real DeepSeek service. Direct model HTTP or a product double cannot replace either product-running tier, and a hand-mounted plugin cannot replace the Loader tier.
+
+## Decision
+
+The harness publishes two sibling one-shot providers as independently installable, opt-in packages. A user loads a provider and the existing common subagent tool in their own `cordis.yml`: `subagent_codex` binds `codex`, while `subagent_claude_code` binds `claude-code`. The shipped CLI dependency closure and base, Web, and headless configurations load neither provider. Each tool accepts only a standalone text task; product selection and background execution are not model arguments.
+
+Both providers report `inheritsParentContext: false`, advertise no optional start capabilities, and pass the parent Session cwd without copying the parent conversation. Their documented tools disable background execution and use `maxDepth: 'provider-managed'`, leaving recursion policy with the out-of-process product instead of sending a limit the provider cannot enforce. Every call creates a fresh product process and a non-resumable product conversation. The shared subagent service continues to own request resolution, lifecycle events, result settlement, and foreground collection; the shared subprocess service owns credential scrubbing, process-tree termination, and whole-tree exit observation.
+
+```text
+fixed tool → shared subagent service → product provider → official product process
+     ← final answer / explicit error / cancellation ← terminal product fact
+     → foreground disposal → shared process-tree termination → whole-tree exit
+```
+
+### Ownership and lifecycle
+
+| Phase | Shared owner | Product-specific responsibility | Observable result |
+| --- | --- | --- | --- |
+| Resolve | `dsh-tool-subagent` and `ctx.subagents` | Validate the product's text-only input and derive native startup parameters | Unsupported context or malformed input fails before a run is published |
+| Start | `dsh-subprocess` owns every acquired process tree | Reach the smallest native point at which the product conversation and process can both be controlled | `start()` publishes one existing `SubagentRun`, or cleans up and rejects |
+| Run | The product owns its native protocol facts; the holder owns their mapping | Submit exactly one task and derive an existing shared stop reason; Codex uses `max-tokens` only for explicit context exhaustion | The parent receives only a final answer or an explicit failure |
+| Dispose | The foreground consumer requests release; `dsh-subprocess` proves exit | Close the native protocol and express any best-effort native cancellation | Disposal is idempotent and returns only after the whole process tree exits |
+
+## Codex provider
+
+`@deepseek-ai/dsh-subagent-codex` registers the fixed `codex` provider and starts `codex app-server --stdio` from `PATH`. Its public configuration contains only an explicit `env` overlay and a positive finite `disposeGraceMs` no greater than the repository's shared `MAX_TIMER_DELAY_MS`. Installation, login, `CODEX_HOME`, model selection, base URL, sandbox, approval policy, and product-session settings remain native Codex or deployment responsibilities.
+
+Before publication, the provider validates a non-empty text-only task, starts the managed app-server in the parent workspace, completes `initialize` → `initialized`, and creates an `ephemeral: true` thread. The published run owns exactly one `turn/start`; its thread and turn ids remain private and are never persisted in the parent Session.
+
+`turn/completed` is the authoritative remote terminal fact. The latest `agentMessage` with `phase: "final_answer"` wins, and that selected message must contain nonblank text. When the product emits no explicit final phase, the latest message with `phase: null` is the compatibility fallback and must likewise be nonblank; commentary never replaces either answer. A failed turn with `error.codexErrorInfo: "contextWindowExceeded"` becomes `max-tokens`. A completed turn without an answer, every other failed or interrupted remote turn, malformed required fields in a recognized app-server frame, protocol closure, early process exit, or unknown server request becomes `error`; this version has no native refusal terminal and therefore produces no `refusal`. Local cancellation wins its race and remains `aborted`.
+
+For command and file approvals, the unattended wire selects a non-approval decision offered by the request, preferring `cancel`; the stable 0.146.0 request shape without an offered-decision list falls back to `decline`. It grants no requested permissions for the turn, answers user-input requests with no answers, and declines MCP elicitation. A request with no legal unattended response, or any unknown server request, fails the run instead of waiting for a user interface the provider does not supply.
+
+An unpublished startup failure closes the wire, terminates the acquired process tree, waits for exit, and then rejects `start()`. Published disposal best-effort interrupts a known turn, closes the wire, ends stdin, invokes the shared termination escalation, and waits for whole-tree exit. Result failure and teardown failure stay independently observable.
+
+Codex 0.146.0 speaks the Responses protocol, while DeepSeek's public OpenAI-compatible endpoint speaks Chat Completions. The credentialed Codex e2e therefore uses a loopback-only, test-private bridge for one no-tool nonce request: real Codex sends Responses to the bridge, the bridge forwards the received bearer credential and extracted task to the fixed official DeepSeek endpoint, and it wraps the real text in the minimal Responses SSE lifecycle. The bridge is neither a production proxy nor evidence that Codex connects to DeepSeek Chat Completions natively.
+
+## Claude Code provider
+
+`@deepseek-ai/dsh-subagent-claude-code` registers the fixed `claude-code` provider and invokes `@anthropic-ai/claude-agent-sdk@0.3.220`. The SDK's platform `optionalDependency` supplies the real Claude Code 2.1.220 CLI. The provider uses the official `query()` entrypoint and passes the SDK's `spawnClaudeCodeProcess` command, arguments, cwd, environment, and forwarded signal unchanged to `dsh-subprocess`; its private `SpawnedProcess` adapter exposes only the stream, event, kill, and exit facts the SDK requires.
+
+The public configuration contains the same two deployment-owned values as the Codex sibling: an explicit `env` overlay and a positive finite `disposeGraceMs` no greater than the repository's shared `MAX_TIMER_DELAY_MS`. Each run creates its own `AbortController`, sets `persistSession: false`, and disables `AskUserQuestion`. The provider deliberately omits `settingSources`, so the SDK reads the host's normal user, project, and local Claude settings relative to the parent Session cwd. It neither copies nor filters those settings and does not create or modify login state. It supplies no `canUseTool`, elicitation, or dialog callback, so unattended interactions fail through the SDK rather than waiting for a user interface the provider does not own.
+
+The provider publishes only after both the SDK `Query` and a live managed CLI handle exist. It consumes the complete SDK stream and completes only when a `result` message has `subtype: "success"`, `is_error: false`, and a nonblank `result`, and the iterator then ends normally. Every SDK error subtype, an error-marked success, a missing result, iterator failure, protocol failure, or process failure becomes `error`. SDK turn, budget, and structured-output limits are not token-window facts, and the SDK exposes no native refusal terminal, so this provider produces neither `max-tokens` nor `refusal`. Local cancellation wins and becomes `aborted`.
+
+Startup rollback and published disposal close the SDK query, abort the per-run controller, invoke shared process-tree termination, and wait for whole-tree exit. `Query.close()` expresses graceful protocol intent but does not replace the subprocess owner's exit proof. Query-close failure, process failure, and teardown failure remain independently observable.
+
+The credentialed Claude Code e2e uses the official DeepSeek Claude Code contract directly: the runtime-only DeepSeek key becomes `ANTHROPIC_AUTH_TOKEN`, the fixed official base gains `/anthropic`, and the main and subagent model variables select the documented DeepSeek models. It starts the production provider and real SDK/CLI, requires one random nonce as the complete answer, persists no credential in settings, and waits for every managed handle to exit.
+
+## Distribution and evidence
+
+Each product owns branch-complete package tests, a required keyless real-product spec, a Loader composition e2e, and a credentialed DeepSeek e2e. The keyless product tier uses the exact official distribution under test, a non-empty fake product key, an isolated temporary workspace and product home, and a loopback fixed-answer model. Missing product requests, wrong authentication, altered task text, a non-exact answer, a skipped real product, or a surviving managed handle fails the required test. The Loader tier boots the README-shaped user configuration, verifies both fixed foreground-only tools in one context, and starts neither product process. The credentialed tier starts the same production provider and real product with a runtime-only key, requires a unique nonce from the fixed official DeepSeek service, and proves quiescence again; it self-skips only when a local operator supplied no key, while trusted CI preflights the secret.
+
+The Codex evidence pins `@openai/codex@0.146.0` and `codex-cli 0.146.0`. Its real-product spec observes the exact Bearer key, original task, byte-exact final answer, unattended command rejection with no file side effect, local cancellation, and whole-tree exit. Production still supplies `codex` on `PATH`.
+
+The Codex credentialed e2e registers the production provider, starts the same real app-server, and requests one random nonce through the test-private bridge described above. It fixes the external endpoint and model, stores no credential or request payload, requires exactly one completed upstream response, compares the trimmed product answer byte-for-byte with the nonce, and waits for every managed handle to exit.
+
+The Claude Code evidence pins Agent SDK 0.3.220 and its platform-distributed Claude Code 2.1.220 CLI. Its real-product spec observes the exact `x-api-key`, original task, byte-exact final answer, inherited temporary host-setting marker, process failure, local cancellation, and whole-tree exit. The Loader e2e resolves both product packages by name while neither product command is available and records zero child starts.
+
+The Claude Code credentialed e2e maps the key and fixed official endpoint only in the provider's in-memory environment, uses the documented `deepseek-v4-pro[1m]` and `deepseek-v4-flash` model variables, and traverses the production provider, official SDK, and real CLI. It compares the trimmed result with a random nonce and proves whole-tree exit without calling the Messages API directly from the test.
+
+The project owner's distribution authorization is scoped to the official `@anthropic-ai/claude-agent-sdk` identity and the official Claude Code CLI/platform payloads each SDK version declares through `optionalDependencies`. [`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) derives and discloses the current payload set without reclassifying its declared terms as permissive. Version, license-field, and payload-set changes still undergo ordinary dependency, lockfile, compatibility, terms, and notices review; unrelated non-permissive runtime packages continue to fail closed.
+
+## Alternatives considered
+
+**Direct model HTTP, `codex exec`, or a hand-written Claude CLI protocol.** These paths bypass the products' official extensible integration surfaces and cannot prove native configuration, tools, approvals, result semantics, or teardown. Each provider uses its official product integration instead.
+
+**A shared product-process helper package.** The existing subagent and subprocess seams already own every shared task, result, environment, and process-tree concern. A new helper would duplicate ownership without deleting either private product adapter, so each adapter calls the existing seams directly.
+
+**A model-visible product selector.** Product availability and authentication are deployment facts. Two fixed tools keep each schema and provider binding explicit and avoid adding dynamic selection state to the common service.
+
+**Product doubles as required evidence.** Doubles cover exhaustive private protocol branches but do not prove package exports, official distributions, authentication, or real process behavior. Required evidence drives each official product against a loopback model fixture.
+
+**Plugin-managed login, product home, models, settings, or permissions.** Those choices would create another authority beside each product's native configuration and enlarge a one-shot provider into account management. The providers expose only an explicit environment overlay and teardown grace; unattended interaction fails closed.
+
+**Continuation, progress, background collection, and shared parent context.** The delivered user result is one self-contained task and one final answer. Product sessions, resume, follow-up, intermediate messages, parent transcript transfer, structured output, and background collection need separate user contracts and are not prebuilt.
+
+## Consequences
+
+Users can install either or both product providers, bind stable foreground tools in their own Cordis configuration, and delegate one self-contained task through the existing subagent contract. Official product integrations preserve native settings and behavior while shared services retain the sole ownership of task settlement and process-tree quiescence.
+
+Every delegation pays for a fresh product process and independent model context, and only final text reaches the parent. Product-native configuration makes behavior depend on the deployment's installed product, account state, and workspace settings. Credentialed e2e runs also spend external API quota and depend on the official DeepSeek endpoint; deterministic protocol, failure, cancellation, and approval coverage remains in the keyless tier. The providers do not resume sessions, stream progress, accept new human interaction, roll back tool or file side effects, or impose a wall-clock timeout.
+
+Compatibility is pinned by package-level unit coverage, keyless real-product loopback tests, credentialed DeepSeek nonce tests, public Loader composition, built-package and NodeNext consumer checks, generated documentation and notices, and the repository CI matrix. A supported product or DeepSeek endpoint/model baseline change must refresh those facts; production performs no separate runtime version probe.
diff --git a/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
new file mode 100644
index 0000000000..3c78e8d5a4
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md
@@ -0,0 +1,94 @@
+# Agent Note: Claude Code 与 Codex subagent 后端
+
+Status: implemented
+
+[English](2026-08-04-claude-code-and-codex-subagent-backends.md) | 中文
+
+## 问题
+
+命名的 [`ctx.subagents`](2026-06-21-subagent-capability-seam.md) 注册表让父 agent（智能体）无需了解子级的运行方式即可委派工作，但 harness 需要通往真实 Codex 与 Claude Code 产品的第一方路径。每条路径都必须向产品交付一项自包含任务，让它在父会话的工作区中执行，返回最终回答或明确的失败或取消结果，并且不留下任何受管的产品进程。
+
+产品集成不得成为任务文本、cwd、取消、结果结算或进程树的第二责任方。因此，所需证据要区分三个事实：无密钥真实产品测试证明官方集成、原生身份验证形态、确定性答案与资源清理；Loader 组合测试证明公开包（package）和文档所示的工具配置无需启动产品即可加载；带密钥 e2e 证明生产提供方与真实产品能够从真实 DeepSeek 服务取得唯一答案。直接发起模型 HTTP 请求或使用产品替身无法取代上述任一产品运行层级；手工挂载插件无法取代 Loader 层级。
+
+## 决策
+
+harness 将两个一次性兄弟提供方作为可独立安装、选择启用的包交付。用户在自己的 `cordis.yml` 中加载提供方与现有的通用 subagent 工具：`subagent_codex` 绑定 `codex`，`subagent_claude_code` 绑定 `claude-code`。随产品交付的 CLI（命令行界面）依赖闭包，以及基础、Web 与 headless 配置都不会加载任一提供方。每个工具只接受独立文本任务；产品选择与后台执行都不作为模型参数。
+
+这两个提供方都报告 `inheritsParentContext: false`，不声明任何可选的启动能力，并传递父会话 cwd，但不会复制父级对话。文档所示的工具会禁用后台执行，并使用 `maxDepth: 'provider-managed'`，将递归策略留给进程外产品，而不是发送提供方无法强制执行的限制。每次调用都会创建一个全新的产品进程和一次不可续接的产品对话。共享 subagent 服务继续负责请求解析、生命周期事件、结果结算和前台收集；共享子进程服务负责凭证清洗、进程树终止以及整棵进程树的退出观测。
+
+```text
+fixed tool → shared subagent service → product provider → official product process
+     ← final answer / explicit error / cancellation ← terminal product fact
+     → foreground disposal → shared process-tree termination → whole-tree exit
+```
+
+### 归属与生命周期
+
+| 阶段 | 共享责任方 | 产品特定职责 | 可观察结果 |
+| --- | --- | --- | --- |
+| 解析 | `dsh-tool-subagent` 与 `ctx.subagents` | 验证产品的纯文本输入并推导原生启动参数 | 不受支持的上下文或格式错误的输入会在发布运行前报错 |
+| 启动 | `dsh-subprocess` 负责每棵已获取的进程树 | 到达能够同时控制产品对话与进程的最小原生控制点 | `start()` 发布一个已存在的 `SubagentRun`，否则清理后拒绝调用 |
+| 运行 | 产品负责其原生协议事实；持有方负责映射这些事实 | 只提交一项任务，并推导出一种现有的共享停止原因；Codex 仅在明确发生上下文耗尽时使用 `max-tokens` | 父级只会收到最终回答或明确失败 |
+| dispose（资源释放） | 前台消费方请求释放；`dsh-subprocess` 证明进程已退出 | 关闭原生协议，并发出尽力而为的原生取消请求 | 释放操作具有幂等性，且仅在整棵进程树退出后才返回 |
+
+## Codex 提供方
+
+`@deepseek-ai/dsh-subagent-codex` 注册固定的 `codex` 提供方，并启动 `codex app-server --stdio`，该命令从 `PATH` 解析。其公开配置仅包含显式的 `env` 覆盖项和须为正有限值的 `disposeGraceMs`，且后者不得大于仓库共享的 `MAX_TIMER_DELAY_MS`。安装、登录、`CODEX_HOME`、模型选择、基础 URL、沙箱、审批策略和产品会话设置仍由 Codex 原生机制或部署环境负责。
+
+发布前，提供方会验证非空的纯文本任务，在父级工作区中启动受管的 app-server，完成 `initialize` → `initialized` 握手，并创建一个 `ephemeral: true` 线程。已发布的运行只拥有一次 `turn/start`；其线程 ID 与轮次 ID 保持私有，绝不会持久化到父会话。
+
+`turn/completed` 是权威的远端终止事实。以最后一条带有 `phase: "final_answer"` 的 `agentMessage` 为准，且选中的消息必须包含非空白文本。若产品没有发出明确的最终阶段，则以最后一条 `phase: null` 的消息作为兼容性回退，该消息也必须包含非空白文本；过程说明绝不会取代上述任一答案。带有 `error.codexErrorInfo: "contextWindowExceeded"` 的失败轮次会成为 `max-tokens`。轮次完成却没有答案、其他任何远端失败或中断轮次、已识别的 app-server 帧中必需字段格式错误、协议关闭、进程提前退出或未知的服务器请求，都会产生 `error`；本版本没有原生的拒绝终止状态，因此不会产生 `refusal`。本地取消在竞态中胜出并保持为 `aborted`。
+
+对于命令与文件审批，无人值守的协议连接会从请求给出的决策选项中选择一项不予批准的决策，并优先选择 `cancel`；稳定的 0.146.0 请求形态没有决策选项列表，因此回退到 `decline`。它不授予该轮次请求的任何权限，不向用户输入请求提供任何答案，并拒绝 MCP elicitation。若请求在无人值守模式下没有合法响应，或是未知服务器请求，此次运行就会失败，而不会等待本提供方没有提供的用户界面。
+
+若启动在发布前失败，提供方会关闭协议连接、终止已获取的进程树并等待其退出，然后拒绝 `start()`。对已发布的运行执行资源释放时，提供方会尽力中断已知轮次、关闭协议连接、结束标准输入、调用共享的逐级终止机制，并等待整棵进程树退出。结果失败与清理失败仍可彼此独立地观察。
+
+Codex 0.146.0 使用 Responses 协议，而 DeepSeek 的公开 OpenAI 兼容端点使用 Chat Completions。因此，带密钥 Codex e2e 会采用一个仅限回环、仅供测试内部使用的桥接层来处理一次不使用工具的随机数请求：真实 Codex 将 Responses 发送到桥接层，桥接层把收到的 Bearer 凭据与提取出的任务转发到固定的 DeepSeek 官方端点，再将真实文本包装进最小化的 Responses SSE（Server-Sent Events）生命周期。该桥接层既不是生产代理，也不能作为 Codex 原生连接 DeepSeek Chat Completions 的证据。
+
+## Claude Code 提供方
+
+`@deepseek-ai/dsh-subagent-claude-code` 注册固定的 `claude-code` 提供方，并调用 `@anthropic-ai/claude-agent-sdk@0.3.220`。SDK 的平台 `optionalDependency` 提供真实的 Claude Code 2.1.220 CLI。提供方使用官方 `query()` 入口点，并将 SDK 的 `spawnClaudeCodeProcess` 命令、参数、cwd、环境和转发的信号原样传入 `dsh-subprocess`；其私有 `SpawnedProcess` 适配器只公开 SDK 所需的流、事件、终止和退出事实。
+
+公开配置包含与 Codex 兄弟提供方相同、由部署方负责的两个值：显式的 `env` 覆盖项，以及须为正有限值且不得大于仓库共享 `MAX_TIMER_DELAY_MS` 的 `disposeGraceMs`。每次运行都会创建自己的 `AbortController`，设置 `persistSession: false` 并禁用 `AskUserQuestion`。提供方故意省略 `settingSources`，因此 SDK 会相对于父会话 cwd 读取宿主机常规的用户、项目和本地 Claude 设置。它既不复制也不过滤这些设置，也不会创建或修改登录状态。提供方不设置 `canUseTool`、elicitation 或对话回调，因此无人值守交互会经 SDK 失败，而不会等待本提供方不负责的用户界面。
+
+只有在 SDK `Query` 与受管的活动 CLI 句柄都已存在后，提供方才会发布运行。它会消费完整的 SDK 流；只有 `result` 消息具有 `subtype: "success"`、`is_error: false` 和非空白 `result`，且迭代器随后正常结束时，运行才会完成。所有 SDK 错误子类型、标记为错误的成功消息、结果缺失、迭代器失败、协议失败或进程失败都会成为 `error`。SDK 的轮次、预算和结构化输出限制不表示 token 窗口耗尽，而且 SDK 没有原生的拒绝终止状态，因此本提供方不会产生 `max-tokens` 或 `refusal`。本地取消会胜出并成为 `aborted`。
+
+启动回滚和已发布运行的资源释放都会关闭 SDK query、中止该次运行的控制器、调用共享的进程树终止机制，并等待整棵进程树退出。`Query.close()` 表达优雅的协议关闭意图，但不能取代子进程责任方的退出证明。Query 关闭失败、进程失败和清理失败仍可彼此独立地观察。
+
+带密钥 Claude Code e2e 直接使用官方 DeepSeek Claude Code 契约：仅在运行时提供的 DeepSeek 密钥会映射为 `ANTHROPIC_AUTH_TOKEN`，固定的官方基础 URL 会追加 `/anthropic`，主模型与 subagent 模型变量会选择文档所示的 DeepSeek 模型。该测试会启动生产提供方与真实 SDK 和 CLI，要求一个随机数作为完整答案，不会把任何凭据持久化到设置中，并等待所有受管句柄退出。
+
+## 分发与证据
+
+每个产品都负责覆盖所有分支的包测试、一项必跑的无密钥真实产品测试、一项 Loader 组合 e2e 和一项带密钥 DeepSeek e2e。无密钥产品层级使用被测的确切官方发行版、非空的伪产品密钥、隔离的临时工作区与产品主目录，以及能返回固定答案的回环模型。产品请求缺失、身份验证错误、任务文本被改动、答案不完全一致、真实产品被跳过或受管句柄仍存活，都会使这项必跑测试失败。Loader 层级会启动 README 所示形态的用户配置，在同一个上下文中验证两个固定且只支持前台执行的工具，并且不会启动任何产品进程。带密钥层级会使用仅在运行时提供的密钥启动同一生产提供方与真实产品，要求从固定的 DeepSeek 官方服务取得唯一随机数，并再次证明完全停稳；仅当本地操作者未提供密钥时才会自行跳过，而受信任的 CI 会预检该 secret。
+
+Codex 证据锁定 `@openai/codex@0.146.0` 与 `codex-cli 0.146.0`。其真实产品测试会观测确切的 Bearer 密钥、原始任务、逐字节完全一致的最终回答、不会产生文件副作用的无人值守命令拒绝、本地取消以及整棵进程树退出。生产环境仍提供 `codex`，并通过 `PATH` 解析。
+
+带密钥 Codex e2e 会注册生产提供方，启动同样的真实 app-server，并通过上述测试专用桥接层请求一个随机数。该测试固定外部端点与模型，不存储任何凭据或请求载荷，要求上游恰好完成一次响应，将去除首尾空白后的产品答案与该随机数逐字节比较，并等待所有受管句柄退出。
+
+Claude Code 证据锁定 Agent SDK 0.3.220 及其平台分发的 Claude Code 2.1.220 CLI。其真实产品测试会观测确切的 `x-api-key`、原始任务、逐字节完全一致的最终回答、继承的临时宿主设置标记、进程失败、本地取消以及整棵进程树退出。Loader e2e 会在两个产品命令均不可用时按名称解析两个产品包，并记录零次子级启动。
+
+带密钥 Claude Code e2e 仅在提供方的内存环境中映射密钥与固定的官方端点，把模型变量设为文档所示的 `deepseek-v4-pro[1m]` 与 `deepseek-v4-flash`，并实际经过生产提供方、官方 SDK 与真实 CLI。它将去除首尾空白后的结果与一个随机数比较，并证明整棵进程树退出，且测试不会直接调用 Messages API。
+
+项目所有者的分发授权范围限定为官方 `@anthropic-ai/claude-agent-sdk` 身份，以及每个 SDK 版本通过 `optionalDependencies` 声明的官方 Claude Code CLI 与平台载荷。[`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md) 会推导并披露当前载荷集合，但不会将其声明条款重新归类为宽松条款。版本、许可证字段和载荷集合发生变化时，仍须经过常规的依赖、锁文件、兼容性、条款和声明评审；无关的非宽松运行时包继续以默认拒绝方式失败。
+
+## 曾考虑的替代方案
+
+**直接模型 HTTP、`codex exec` 或手写的 Claude CLI 协议。** 这些路径会绕过产品的官方可扩展集成接口，无法证明原生配置、工具、审批、结果语义或资源清理。每个提供方都改用相应的官方产品集成。
+
+**共享产品进程辅助包。** 现有 subagent 与子进程 seam 已负责围绕任务、结果、环境和进程树的全部共享职责。新辅助包无法删除任一私有产品适配器，只会造成责任重复，因此每个适配器都会直接调用现有 seam。
+
+**面向模型的产品选择器。** 产品可用性和身份验证属于部署事实。两个固定工具使各自的 schema 与提供方绑定保持明确，也避免在通用服务中添加动态选择状态。
+
+**以产品替身作为强制证据。** 替身可以穷尽覆盖私有协议分支，但无法证明包导出、官方发行版、身份验证或真实进程行为。强制证据会驱动每个官方产品连接回环模型 fixture（测试前置数据）。
+
+**由插件管理登录、产品主目录、模型、设置或权限。** 这些选择会在每个产品的原生配置之外建立另一套权威来源，并将一次性提供方扩张为账户管理功能。提供方只公开显式环境覆盖项和清理宽限期；无人值守交互会以默认拒绝方式失败。
+
+**续接、进度、后台收集和共享父级上下文。** 已交付的用户结果是一项自包含任务和一个最终回答。产品会话、恢复、后续交互、中间消息、父级 transcript（文本记录）传递、结构化输出和后台收集都需要独立的用户契约，当前实现不会预先构建这些功能。
+
+## 后果
+
+用户可以安装任一或两个产品提供方，在自己的 Cordis 配置中绑定稳定的前台工具，并通过现有 subagent 契约委派一项自包含任务。官方产品集成会保留原生设置与行为，而共享服务继续独占任务结算与进程树完全停稳的责任。
+
+每次委派都要承担新建产品进程和独立模型上下文的开销，且只有最终文本会到达父级。产品原生配置使行为取决于部署环境中安装的产品、账户状态和工作区设置。带密钥 e2e 运行还会消耗外部 API 配额，并依赖 DeepSeek 官方端点；对协议、失败、取消与审批的确定性覆盖仍由无密钥层级承担。提供方不会恢复会话、以流式方式传送进度、接受新的人工交互、回滚工具或文件副作用，也不会施加按实际经过时间触发的超时。
+
+兼容性由包级单元测试覆盖率、无密钥真实产品回环测试、带密钥 DeepSeek 随机数测试、公开 Loader 组合、已构建包与 NodeNext 消费方检查、生成的文档与声明以及仓库 CI 矩阵共同锁定。更改受支持的产品基线或 DeepSeek 端点／模型基线时必须刷新这些事实；生产环境不会另行执行运行时版本探测。
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
index d65dae2802..da2fdfd101 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.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 .agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
-2026-07-30-generated-third-party-notices.md: e480954d29d5dc09ef8ecd4069059a1f0c8b1043
-2026-07-30-generated-third-party-notices.zh.md: 78ba7250e797c57048078d1b4f62b7a9a5d9d561
+2026-07-30-generated-third-party-notices.md: cbabd1142ad292f78a3184723182a834dfb234fc
+2026-07-30-generated-third-party-notices.zh.md: b135c3626b661f1a5b0317a90b700a26d679bf1e
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
index e480954d29..cbabd1142a 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.md
@@ -18,7 +18,7 @@ A hand-written inventory answers none of those durably. Roughly a hundred rows o
 
 One trigger gap is accepted rather than worked around: lefthook inspects only files present on disk, so **deleting** a manifest runs no job, and removing a package reaches the assertion in the test lane instead. Reconstructing the staged file list to include deletions was tried and does not work — lefthook filters the list against the working tree either way. The assertion is the backstop for exactly this case.
 
-The file discloses **direct** dependencies only. The complete npm closure with pinned versions already lives in `pnpm-lock.yaml` (`pnpm licenses list` renders it) and the Python closure in `python/sdk/uv.lock`; re-materializing either as prose would be a second, worse copy.
+The file discloses **direct** dependencies by default. The complete npm closure with pinned versions already lives in `pnpm-lock.yaml` (`pnpm licenses list` renders it) and the Python closure in `python/sdk/uv.lock`; re-materializing either as prose would be a second, worse copy. The one explicit transitive disclosure is the official Claude platform payload set declared by `@anthropic-ai/claude-agent-sdk` through `optionalDependencies`, because those packages carry the distributed Claude Code executable rather than ordinary library implementation detail.
 
 **Tiering is by declaring area, not by manifest section.** A package is a runtime dependency when any manifest outside `DEV_ONLY_AREAS` — the root manifest, `packages/support/`, `packages/client/test-runtime/`, `website/`, `examples/`, `native/` — names it under `dependencies` or `optionalDependencies`. Section names alone are wrong in both directions: a test-support package declares `vitest` under `dependencies` without shipping it, and the `bin/dsh` launcher execs through `tsx`, which no manifest declares as a runtime dependency at all (the generator marks it runtime explicitly).
 
@@ -26,10 +26,14 @@ The runtime tier deliberately covers **every mountable plugin**, not just what t
 
 The manifest set is derived from the `packages:` members each `pnpm-workspace.yaml` declares — the root one and the nested Landlock workspace's — so a new member area is read the day it is declared rather than the day someone remembers to extend a list. License and repository metadata come from the installed pnpm stores, both the root one and the Landlock workspace's, so the generator requires an installed tree and fails loud when a package resolves to neither, rather than emitting an empty cell. `OVERRIDES` carries the packages whose published manifest cannot answer — Rust-built npm bins that omit `license`, and the `modelcontextprotocol/servers` packages whose repository is mid MIT→Apache-2.0 relicensing, so their effective terms are per-contribution. A runtime dependency whose license is not on the permissive list is a hard error: shipping copyleft is a distribution decision, not something a regenerated table may absorb silently. Vendored packages are cross-checked against `vendor/README.md` and rejected if any is not MIT, and `pnpm-workspace.yaml`'s `patchedDependencies` are listed under the runtime table because pnpm applies those patches at install time — shipped artifacts carry modified copies of `@earendil-works/pi-tui` and `node-pty`, and the patch files are the record of what changed.
 
+The project owner separately authorizes distribution of every official `@anthropic-ai/claude-agent-sdk` version and the official Claude Code CLI/platform payloads that version declares through `optionalDependencies`. The generator represents this as one exact direct-package identity exception, not as a permissive-license override: `SEE LICENSE IN README.md` and `SEE LICENSE IN LICENSE.md` remain non-permissive classifications, and every unrelated non-permissive runtime still fails closed. When the SDK is present, the generator reads its installed manifest, rejects optional identities outside the official SDK payload prefix, derives the current SDK, CLI, and payload versions, verifies the installed host payload's identity, version, and declared-license field, and renders the complete SDK-declared payload set in a separate notices section. Version, declared-license, and payload-set changes do not require new identity authorization, but they still require ordinary dependency, lockfile, compatibility, terms, and notices review.
+
 ## Testing
 
 The same spec that asserts freshness pins the tiering rule against fixture manifests — including the two cases that motivate it, a `dependencies` entry of a test-support package and a plugin package no app mounts. It also pins the parsers against the shapes that would otherwise drop a package without a word: a `vendor/README.md` table that stops covering a vendored directory, a requirement array holding extras (`"httpx[http2]"`), a requirement with no version at all, an author-named `[dependency-groups]` table, and a workspace member area absent from any hardcoded list. Each of those is a silent-omission path, which is the failure mode a disclosure file cannot afford.
 
+The Claude distribution tests prove that only the exact direct SDK identity bypasses the ordinary non-permissive-runtime rejection, that the bypass does not change license classification, and that the payload set comes from the SDK manifest rather than a version or platform allowlist. Wrong SDK identities, missing payloads, and unrelated optional package identities all fail.
+
 ## Alternatives considered
 
 **Keep the hand-written file and review it at release time.** Reviewing a hundred derived rows by eye is exactly the work a generator does correctly, and the file's own claim — that it lists every direct dependency — would be unverified between releases.
@@ -42,6 +46,8 @@ The same spec that asserts freshness pins the tiering rule against fixture manif
 
 **Tier by reachability from the shipped assemblies only** (`apps/*` plus `python/sdk-runtime`). This produces a tighter runtime tier, but classifies the MCP client and the OpenTelemetry exporter as development-only even though a user running the installed repository can mount them. It understates the disclosure, which is the wrong direction to err for a legal notice.
 
+**Treat the Claude SDK terms as permissive or add a reusable non-permissive allowlist.** Either shape would misstate the upstream declaration and let an unrelated runtime inherit authorization it was never granted. The narrow exception keys only the official direct SDK identity, while its optional payload identities are accepted solely as data declared by that SDK and remain visibly non-permissive.
+
 **Emit the notices as a bilingual pair.** Every other root document is paired, but the file is a table of upstream package names, SPDX identifiers, and URLs; the translatable surface is a handful of section blurbs. `scripts/translation-pairing.ts` scopes discovery to `README*`, `.agents/notes/**`, `docs/**`, and `python/**`, so a root non-README file is outside the bilingual corpus by construction, and the README pair carries the bilingual entry points into it.
 
 ## Consequences
@@ -51,3 +57,5 @@ A dependency edit now carries a regenerated notices file into the same commit. C
 The generator needs an installed tree, which makes it heavier than a pure-source generator, and a new package with unusable published metadata needs an `OVERRIDES` entry rather than silently rendering a blank license. Both failures are loud and name the remedy.
 
 The tiering rule is a policy encoded in one constant. Adding a workspace area that never ships — a second test-infrastructure tier, another site — requires extending `DEV_ONLY_AREAS`, or its dependencies will be disclosed as runtime.
+
+The Claude identity exception is deliberately narrower than the payload disclosure it activates. Upgrading the SDK needs no new owner authorization, but regeneration fails unless the installed SDK exposes its version, CLI version, and at least one official platform payload, and unless the current host payload matches the SDK declaration. Maintainers still review changed terms and compatibility; the generator prevents the authorization from silently widening to another package.
diff --git a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
index 78ba7250e7..b135c3626b 100644
--- a/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
+++ b/.agents/notes/implemented/process/2026-07-30-generated-third-party-notices.zh.md
@@ -18,7 +18,7 @@ Status: implemented
 
 有一处触发缺口是接受而非绕过的：lefthook 只检视磁盘上存在的文件，因此**删除**清单文件不会触发任何任务，移除一个包会落到测试 lane 的断言上。重构暂存文件列表以纳入删除的做法试过，不成立——无论怎么给列表，lefthook 都会拿工作树过滤一遍。这个场景正由断言兜底。
 
-文件只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。
+文件默认只披露**直接**依赖。完整的 npm 闭包连同锁定版本已记录在 `pnpm-lock.yaml`（`pnpm licenses list` 可渲染），Python 闭包记录在 `python/sdk/uv.lock`；再用散文誊一遍只会得到一份更差的副本。唯一明确披露的传递依赖，是 `@anthropic-ai/claude-agent-sdk` 通过 `optionalDependencies` 声明的官方 Claude 平台载荷集合，因为这些包承载随产品分发的 Claude Code 可执行文件，而非普通的库实现细节。
 
 **分层依据是声明方所在区域，而非清单字段名。** 只要 `DEV_ONLY_AREAS` 之外的任一清单——即根清单、`packages/support/`、`packages/client/test-runtime/`、`website/`、`examples/`、`native/` 之外——在 `dependencies` 或 `optionalDependencies` 里点名某个包，它就是运行时依赖。单看字段名在两个方向上都会出错：测试支撑包把 `vitest` 写在 `dependencies` 里却并不交付它；而 `bin/dsh` 启动器 exec 经过的 `tsx`，根本没有任何清单把它声明为运行时依赖，只能由生成器显式标记。
 
@@ -26,10 +26,14 @@ Status: implemented
 
 清单集合由两个 `pnpm-workspace.yaml`——根工作区与嵌套的 Landlock 工作区——各自声明的 `packages:` 成员派生，因此新增成员区域在声明当天就会被读取，而不必等谁想起来去补一份列表。许可证与仓库地址取自已安装的 pnpm store，根 store 与 Landlock 工作区的 store 都会查；某个包两处都解析不到时直接失败，而不是留下空单元格。`OVERRIDES` 收录已发布清单答不上来的包：用 Rust 构建、发布时省略 `license` 字段的 npm 可执行包，以及 `modelcontextprotocol/servers` 系列——该仓库正处在 MIT 向 Apache-2.0 的重新许可过程中，实际条款按贡献逐条而定。运行时依赖的许可证若不在宽松清单内即为硬失败：交付 copyleft 是一项分发决策，不该被一次重新生成悄悄吸收。被源码收编的包会与 `vendor/README.md` 交叉核对，出现非 MIT 即报错；`pnpm-workspace.yaml` 的 `patchedDependencies` 列在运行时表格之后，因为 pnpm 在安装期就会打上这些补丁——交付产物携带的是改动过的 `@earendil-works/pi-tui` 与 `node-pty`，补丁文件本身就是改动的完整记录。
 
+项目所有者另行授权分发每个官方 `@anthropic-ai/claude-agent-sdk` 版本，以及该版本通过 `optionalDependencies` 声明的官方 Claude Code CLI 与平台载荷。生成器将其表示为一项精确匹配直接包身份的例外，而非宽松许可证覆盖项：`SEE LICENSE IN README.md` 与 `SEE LICENSE IN LICENSE.md` 仍归类为非宽松，所有无关的非宽松运行时依赖仍以默认拒绝方式失败。存在该 SDK 时，生成器会读取其已安装清单，拒绝不符合官方 SDK 载荷前缀的可选包身份，推导当前 SDK、CLI 与载荷版本，核验已安装宿主载荷的身份、版本和声明许可证字段，并在单独的声明章节中渲染 SDK 声明的完整载荷集合。版本、声明许可证和载荷集合发生变化时无需新的身份授权，但仍须经过常规的依赖、锁文件、兼容性、条款和声明评审。
+
 ## Testing
 
 断言新鲜度的同一个 spec 也用夹具清单钉住分层规则，覆盖促成该规则的两个场景：测试支撑包的 `dependencies` 条目，以及没有任何应用挂载的插件包。它还把各解析器钉在那些原本会让某个包无声消失的形态上：不再覆盖全部收编目录的 `vendor/README.md` 表、含 extras 的依赖数组（`"httpx[http2]"`）、完全不带版本的依赖、作者自取名字的 `[dependency-groups]` 表，以及任何硬编码列表都不含的工作区成员区域。这些都是静默漏报路径——正是披露文件最担不起的失败方式。
 
+Claude 分发测试证明：只有精确匹配的直接 SDK 身份会绕过通常的非宽松运行时拒绝；该绕过不会改变许可证分类；载荷集合来自 SDK 清单，而非版本或平台允许列表。SDK 身份错误、载荷缺失或存在无关的可选包身份时，测试都会失败。
+
 ## Alternatives considered
 
 **保留手写文件，发版时人工过一遍。** 用肉眼审阅上百行推导数据，恰恰是生成器能做对的活；而且在两次发版之间，文件自称「列出全部直接依赖」这句话无人验证。
@@ -42,6 +46,8 @@ Status: implemented
 
 **只按已交付装配的可达性分层**（`apps/*` 加 `python/sdk-runtime`）。这样得到的运行时层更紧凑，但会把 MCP 客户端与 OpenTelemetry 导出器判为仅开发用途——而运行已安装仓库的用户完全可以挂载它们。这会低估披露，对法务通告来说错在了更危险的一侧。
 
+**将 Claude SDK 条款视为宽松条款，或新增可复用的非宽松允许列表。** 两种方案都会误述上游声明，并让无关运行时依赖继承从未授予它的授权。这项窄例外只匹配官方直接 SDK 身份；其可选载荷身份仅作为该 SDK 声明的数据被接受，并继续明确归类为非宽松。
+
 **把披露文件做成双语对。** 其他根文档都是成对的，但这份文件是上游包名、SPDX 标识与网址构成的表格，可翻译的只有寥寥几段章节导语。`scripts/translation-pairing.ts` 的发现范围限定在 `README*`、`.agents/notes/**`、`docs/**` 与 `python/**`，根目录下的非 README 文件在构造上就不属于双语语料；双语入口由 README 对承担。
 
 ## Consequences
@@ -51,3 +57,5 @@ Status: implemented
 生成器需要已安装的工作树，因此比纯源码生成器更重；发布元数据不可用的新包需要补一条 `OVERRIDES`，而不是默默渲染出空白许可证。这两类失败都会明确报错并指出补救方式。
 
 分层规则是编码在一个常量里的政策。若新增了不参与交付的工作区区域——第二层测试基础设施、另一个站点——就要同步扩展 `DEV_ONLY_AREAS`，否则其依赖会被当作运行时依赖披露出去。
+
+Claude 身份例外刻意比其启用的载荷披露范围更窄。升级 SDK 无需新的所有者授权，但如果已安装的 SDK 未公开自身版本、CLI 版本和至少一个官方平台载荷，或当前宿主载荷与 SDK 声明不符，重新生成就会失败。维护者仍须评审发生变化的条款与兼容性；生成器会阻止授权悄然扩大到其他包。
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
index 5fabe8a942..1c070a03a2 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.i18n.yaml
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.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 .agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
-2026-07-27-session-projection-and-command-log.md: 6a073c956c27bbfc65cff2d4f44ca12023df0cd5
-2026-07-27-session-projection-and-command-log.zh.md: a22ebe57811339a0e583ae00909e60482ddb57b1
+2026-07-27-session-projection-and-command-log.md: 789e79f2ecab1a9f3ac717df86059150ed2d4da9
+2026-07-27-session-projection-and-command-log.zh.md: 4d680b37f5d49a243447542706c8b7ced8d80e2a
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
index 6a073c956c..789e79f2ec 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md
@@ -56,6 +56,10 @@ declare module 'cordis' {
 - Registration is an effect (disposer with the fiber): an unloaded plugin's key disappears from subsequent responses and the client reads it as capability absence — HMR semantics for free. Duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
 - The package owns `./invariant` (every served key has a live registration).
 
+### Shipped consumer: the subagent identity unit
+
+The registry's two read faces already serve a shipped consumer beyond this RFC's wire plan: [subagent list identity via the projection unit](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md) registers a `subagent` unit — the durable mode/label identity folded last-wins from `subagent/descriptor` — and `SubagentService.listChildren` reads it through `snapshot()` for a live child (the watermark cache, zero log reads) and `restore({}, events, 0)` over one persistence inspection for a cold one. The registry contract is unchanged: no failure channel and no new read face — a unit never throws, an absent value is the signal, and how absence renders is that consumer's decision.
+
 ### Wire: projections block on the history tail page
 
 ```ts ignore-check
diff --git a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
index a22ebe5781..4d680b37f5 100644
--- a/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
+++ b/.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md
@@ -56,6 +56,10 @@ declare module 'cordis' {
 - 注册是 effect（disposer 随 fiber 走）：插件卸载后其 key 从后续响应中消失，客户端将其读作能力缺失——HMR（热模块替换）语义随之自动成立。key 重复直接 throw。领域插件在 `ctx.inject(['sessionProjections'], …)` 下注册，因此不带注册表的 headless 组装完全不受影响。
 - 该包拥有 `./invariant`（每个被服务的 key 都有一条存活的注册）。
 
+### 已交付的消费方：subagent 身份单元
+
+注册表的两处读面已经服务于本 RFC 协议计划之外的一个已交付消费方：[subagent 列表经投影单元读取身份](../../implemented/architecture/2026-08-06-subagent-list-identity-projection.md)注册了 `subagent` 单元——从 `subagent/descriptor` 以 last-wins 折叠出的持久 mode/label 身份——`SubagentService.listChildren` 对 live child 经 `snapshot()` 读取（水位缓存，零日志读），对 cold child 经一次持久化检查上的 `restore({}, events, 0)` 读取。注册表契约不变：没有失败通道、没有新读面——单元永不抛错，值缺席本身就是信号，缺席如何呈现是该消费方自己的决定。
+
 ### 协议层：历史尾页上的 projections 块
 
 ```ts ignore-check
diff --git a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.i18n.yaml b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.i18n.yaml
deleted file mode 100644
index 8552e86644..0000000000
--- a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# 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 .agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md
-2026-07-07-claude-code-and-codex-subagent-backends.md: ee8576f97a9fdef8c88dcad3a73f28b63ca3ebe1
-2026-07-07-claude-code-and-codex-subagent-backends.zh.md: bd76a8f34d86b704494b56331c47ea89bfc8a0aa
diff --git a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md
deleted file mode 100644
index ee8576f97a..0000000000
--- a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# Agent Note: Claude Code and Codex subagent backends (out-of-process delegation to external coding agents)
-
-Status: proposed
-
-English | [中文](2026-07-07-claude-code-and-codex-subagent-backends.zh.md)
-
-## Problem
-
-The subagent seam ([the seam Agent Note](../../implemented/feature/2026-06-21-subagent-capability-seam.md)) hosts multiple named providers on `ctx.subagents`, and the ACP backend ([the ACP backend Agent Note](../../implemented/feature/2026-06-22-acp-subagent-backend.md)) proved the seam generalizes across a process boundary; its Future-providers section explicitly named the Codex app-server and the Claude Code Agent SDK as mechanically similar siblings. Those two are the engines actually worth delegating to today: a harness turn should be able to hand a self-contained task to a real Claude Code or a real Codex — a separate product with its own model, tools, and sandbox — and get back one final answer, without the parent deployment leaking its secrets into the child or the child's behavior silently depending on whatever `~/.claude` / `~/.codex` state exists on the host machine.
-
-## Proposal
-
-Two sibling provider packages, structural variants of the ACP backend, plus one extraction:
-
-- `@deepseek-ai/dsh-subagent-claude-code` — drives a Claude Code child through `@anthropic-ai/claude-agent-sdk`'s `query()` (the SDK runs in the parent process and spawns its bundled `claude` CLI as the subprocess). Provider name `claude-code`: the child is the Claude Code *product*, not an Anthropic model adapter — "claude" stays reserved for a future `dsh-llm` adapter.
-- `@deepseek-ai/dsh-subagent-codex` — spawns `codex app-server` and drives one thread/turn over its JSON-RPC-over-stdio protocol with a hand-rolled newline-JSON client (~200–300 lines) in the package.
-- `@deepseek-ai/dsh-subagent-process` — a pure library (the `subagent-inprocess` precedent) extracting what `dsh-subagent-acp` already carries and both new backends need: the credential env scrub (`buildChildEnv`), the EOF → SIGTERM → SIGKILL dispose ladder, and new isolated-config-dir helpers (`mkdtemp` create, best-effort remove). The ACP backend migrates onto it; `bash-local`'s sibling copy is left alone to bound the change.
-
-Both providers copy the ACP backend's seam posture verbatim: fresh child per `start`, exactly one prompt round-trip, capabilities all `false`, `inheritsParentContext: false`, `request.parent`/`request.agentOptions` ignored, `id = SessionId(randomUUID())`, `result` never rejects — child-level failure flattens to a stop reason and the original error goes to `ctx.logger` via an `onError` spec callback. Model exposure is zero new code: `dsh-tool-subagent` is loaded once per provider with a distinct `toolName` (`subagent_claude_code`, `subagent_codex`). No new session events are needed — the only model-visible artifact is the tool result, so reconstructability holds exactly as it did for ACP. To be explicit about the boundary: the session log reconstructs the model-visible transcript, not workspace mutation history — a child granted write access mutates files as an ambient side effect outside the log, exactly as the bash tools and the ACP backend already do; replay reproduces requests, not the disk.
-
-## Verified interface facts (pinned versions)
-
-Both integration surfaces were verified against pinned implementations before this proposal — types and bundled source read, keyless spikes run — not from vendor docs alone. The pins are the verification baseline, not a runtime contract: the backends perform no runtime version probe (no `codex --version` gate, no SDK version sniffing). Compatibility is enforced at development time — every dependency bump re-runs the keyless suites against the real load path — and at runtime by failing loudly: a protocol-level surprise settles `error` via `onError`, never a silent misbehavior.
-
-**`@anthropic-ai/claude-agent-sdk` 0.3.202.** `options.env` REPLACES the child environment (no merge with `process.env`), which is exactly what the scrub needs. `settingSources` defaults to loading ALL filesystem settings — isolation requires explicitly passing `[]`. Result subtypes are `success` | `error_during_execution` | `error_max_turns` | `error_max_budget_usd` | `error_max_structured_output_retries`. On abort the SDK escalates the CLI child itself: stdin EOF immediately, SIGTERM ~2s later if the child ignores it (observed; no leftover processes) — no bespoke kill fallback needed. `outputFormat: {type: 'json_schema'}` and an `agents` option exist, giving future landing points for the seam's `outputSchema` capability and named subagent types; both are out of scope here.
-
-**codex CLI 0.142.5, `codex app-server` (v2 vocabulary).** LF-delimited JSON, JSON-RPC 2.0 shapes with the `"jsonrpc"` header omitted.
-
-- Lifecycle: `initialize{clientInfo}` + `initialized` → `thread/start` (accepts `cwd`, `model`, `sandbox`, `approvalPolicy`, `ephemeral`; succeeds unauthenticated) → `turn/start{threadId, input:[{type:'text',text}]}` returns an `inProgress` turn immediately; the terminal signal is the `turn/completed` notification carrying `Turn{status: completed|interrupted|failed|inProgress, error}`.
-- Approvals are server-initiated requests — `item/commandExecution/requestApproval`, `item/fileChange/requestApproval`, `item/permissions/requestApproval`, `item/tool/requestUserInput`, `mcpServer/elicitation/request` — answered with `accept`/`decline`-family decisions.
-- Auth: `account/login/start{type:'apiKey', apiKey}` is a first-class RPC and `account/read` reports `requiresOpenaiAuth` — and an unauthenticated `turn/start` does NOT fail fast (it hangs in retry), so the backend MUST pre-check auth and settle `error` loudly instead of waiting on the turn.
-- Isolation: `CODEX_HOME` redirection is honored (the `initialize` response echoes it, so tests can assert isolation), and `ephemeral: true` threads leave no session files at all.
-
-## Isolation and credentials
-
-Deployments authenticate with API keys only, and the child must not see the host user's Claude Code / Codex configuration: behavior has to be a function of `cordis.yml` alone. Each run gets a fresh `mkdtemp` config dir — `CLAUDE_CONFIG_DIR` for Claude Code (paired with an explicit `settingSources: []`), `CODEX_HOME` for Codex — removed best-effort on dispose; a config field can pin a persistent dir instead. The child env reuses the ACP backend's `buildChildEnv` semantics verbatim via the extraction: the ambient env is forwarded MINUS credential-shaped vars (`/KEY|SECRET|TOKEN/i`), with `config.env` layered on top — so `PATH`, `HOME`, `TMPDIR`, locale, and proxy vars survive and the CLIs run normally, while only credential-shaped ambient vars are scrubbed (`ANTHROPIC_API_KEY` enters explicitly through `config.env` for Claude Code), and the Codex key travels via the `account/login/start` RPC into the isolated `CODEX_HOME` rather than a hand-written `auth.json`.
-
-## Permission and approval policy
-
-Instead of collapsing to ACP's single `permission: allow|reject` knob, each backend exposes its engine's native vocabulary as config, with conservative defaults: Claude Code gets `permissionMode` (default `default`) plus `permission: allow|reject` (default `reject`) as the `canUseTool` auto-answer for whatever falls through; Codex gets `sandboxMode` (default `read-only`) and `approvalPolicy` (default `never`) plus the same `permission` fallback for approval requests that still arrive. Defaults are deliberately do-no-harm (the out-of-box child cannot write files); examples demonstrate opening up (`acceptEdits` / `workspace-write`). The mechanical rule: EVERY server-initiated request is settled programmatically and promptly — the enumerated approval/user-input/elicitation requests by the configured policy, an unknown request method with a JSON-RPC method-not-found error response (never left pending), unknown notifications consumed — so no child request can wedge a turn waiting on an answer that will never come. Prompts never reach a human in this cut, matching ACP.
-
-## StopReason mapping
-
-Claude Code: `success` → `completed`; `error_max_turns`, `error_during_execution`, `error_max_budget_usd`, `error_max_structured_output_retries` → `error` (aligning with the ACP call on `max_turn_requests`: an unfinished task is not success); generator abort → `aborted`; anything unknown → `error`. Codex: `Turn.status` `completed` → `completed`; `interrupted` → `aborted`; `failed` with `codexErrorInfo: 'contextWindowExceeded'` → `max-tokens`, any other `failed` → `error`; transport/spawn/auth-precheck failure → `error` (or `aborted` if cancel was requested). In both, `cancel()` is the ACP shape: flag + abort/interrupt + a cancel-settled race arm so an uncooperative child cannot stall the result.
-
-Liveness posture, stated explicitly: teardown timing is config, turn duration is not. Both backends take the dispose ladder's grace periods as defaulted validated config fields (the ACP backend's `disposeEofGraceMs`/`disposeGraceMs` shape, carried by the extraction), but there is deliberately NO turn-duration or startup timeout — matching ACP, liveness during a turn belongs to the caller via `cancel()`/the abort signal, a subagent turn is legitimately minutes long, and the Codex auth precheck removes the one verified guaranteed-hang; a deployment wanting a wall-clock bound cancels from the parent.
-
-## Testing
-
-Named at every tier per the root AGENTS.md rule, and de-risked up front:
-
-- **Keyless unit/integration**, mirroring the ACP spec list per backend (round-trip and output accumulation, every stop mapping, both cancel paths, already-aborted, permission auto-answer under both policies, unknown-message tolerance, bad-command spawn failure, HMR provider cleanup, export shape, isolation assertions on child env and temp-dir removal; Codex adds the auth-precheck failure path). Claude Code's harness is a scripted fake `claude` executable behind `pathToClaudeCodeExecutable` driven by the REAL SDK — a spike already passed end-to-end keyless in 24ms (the fake CLI answers one `control_request/initialize` and speaks plain stream-json, ~40 lines). Codex's harness is a scripted mock app-server subprocess speaking the verified wire protocol, the `mock-acp-server.ts` shape.
-- **With-key e2e** per backend: the real engine does real file work verified on disk, under a pinned opened-up config so acceptance and the do-no-harm defaults don't collide — `permissionMode: 'acceptEdits'` for Claude Code, `sandboxMode: 'workspace-write'` + `approvalPolicy: 'never'` for Codex; self-skips report exactly what is missing (binary vs key). CI has no secrets, so these run locally per the with-key policy.
-- **Snapshot**: deferred as `TODO(claude-code-subagent-replay)` / `TODO(codex-subagent-replay)` — the same distinct replay shape the ACP backend deferred ([the per-session replay Agent Note](../../implemented/testing/2026-06-22-subagent-snapshot-replay.md)); the keyless suites carry deterministic coverage meanwhile.
-
-## Alternatives considered
-
-### Why not the official `@openai/codex-sdk` instead of a hand-rolled client?
-
-The dispose ladder and env scrub require owning the child process (spawn args, env, signals, exit await); the SDK hides the process. The wire format is trivial to frame (LF JSON), the shapes are generatable per pinned version (`codex app-server generate-json-schema`), and the repo precedent (`hook-protocol`) is to own thin protocol cores rather than wrap someone's runtime. The SDK would save protocol-evolution maintenance but costs the exact control this backend exists to have.
-
-### Why not a model-visible `subagent_type` parameter (one Task-style tool)?
-
-Claude Code's own Task tool puts the subagent type in the model-facing schema, selecting a prompt-plus-toolset persona. Here the choice is between EXECUTION ENGINES, and only the deployer knows which engines have credentials configured — so selection stays deployment config, preserving `dsh-tool-subagent`'s documented one-provider-per-tool contract. A persona-style type selector would be a separate Agent Note against the tool, not the backends.
-
-### Why not login-state credentials and the user's own config?
-
-Inheriting `~/.claude` / `~/.codex` (subscription login, user settings, skills, MCP servers) would make child behavior depend on host-machine state and punch an implicit exception through the "credentials enter explicitly via `config.env`, never ambiently" rule the ACP backend and bash executor established. API-key-only plus forced config-dir isolation keeps runs reproducible; deployments wanting shared state can point the config-dir field at a persistent directory deliberately.
-
-### Why not a driver-injection seam for the Claude Code keyless tests?
-
-Injecting a fake `query()` would mock our own boundary and leave the real SDK load path untested (the real-over-mock policy in docs/testing.md). The risk that justified considering it — the SDK↔CLI stream-json control protocol being internal — was retired by the spike: the fake-CLI harness works against the real pinned SDK today. If an SDK upgrade breaks the mock, the keyless suite fails the upgrade PR, which is the gate working.
-
-### Why not ACP adapters (e.g. `claude-code-acp`) reusing the existing backend?
-
-Community shims wrap both engines in ACP, which would make them "just config" on `dsh-subagent-acp`. But that inserts an unofficial third-party layer between the harness and the engine, erases the native control surfaces this Agent Note exposes (permissionMode, sandboxMode/approvalPolicy, config-dir isolation, apiKey RPC), and trades first-party protocol stability for a shim's release cadence. First-party surfaces — the Agent SDK and the app-server — are the supported integration points.
-
-## Acceptance criteria
-
-On a machine with both engines and keys configured: a REPL-driven model completes one real file task through `subagent_claude_code` and one through `subagent_codex`, the tool result being the child's final answer, with only `tool/call` + `tool/result` in the parent session log. Keyless suites pass at 100% per-file coverage in a credential-less environment, asserting isolation (scrubbed child env, no temp config dirs left after dispose) and that child behavior is unchanged by the presence or absence of `~/.claude` / `~/.codex`. Cancelling a parent turn quiesces both backends in bounded time with no leftover child processes. E2e suites self-skip cleanly, naming the missing prerequisite.
-
-## Risks
-
-- `codex app-server` is CLI-flagged experimental and its v1/v2 vocabularies coexist; the client pins 0.142.5, implements v2 only, and consumes unknown methods/notifications without crashing, but a future codex bump can still force rework (regenerate schemas and re-run the keyless suite on every bump — the development-time enforcement behind the no-runtime-version-probe stance above).
-- The Claude Code fake-CLI mock rides an internal protocol: any SDK upgrade must go through the keyless suite, and a breaking control-protocol change means reworking the mock (fallback: the driver-injection seam rejected above becomes the escape hatch).
-- The SDK's optionalDependencies weigh ~280MB per platform — accepted, and confined to the one backend package.
-- The SDK's SIGKILL branch beyond EOF→SIGTERM was not observed and is trusted; e2e keeps a no-leftover-process assertion.
-- Codex is a deployment prerequisite (no npm-bundled binary); a missing or incompatible binary surfaces as a loud spawn/protocol `error`, not a version probe.
-- Every run pays a fresh child process and only the final answer surfaces — thoughts, tool cards, and usage are consumed and dropped; pooling, intermediate-progress surfacing, `sendMessage`/`resume`, `outputSchema` via the SDK's `outputFormat`, and named subagent types via the SDK's `agents` option are all deliberate deferrals.
diff --git a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.zh.md b/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.zh.md
deleted file mode 100644
index bd76a8f34d..0000000000
--- a/.agents/notes/proposed/feature/2026-07-07-claude-code-and-codex-subagent-backends.zh.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# Agent Note: Claude Code 与 Codex subagent 后端（向外部编码 agent 的进程外委派）
-
-Status: proposed
-
-[English](2026-07-07-claude-code-and-codex-subagent-backends.md) | 中文
-
-## 问题
-
-subagent seam（[seam Agent Note](../../implemented/feature/2026-06-21-subagent-capability-seam.md)）在 `ctx.subagents` 上托管多个命名提供方，ACP（Agent Client Protocol）后端（[ACP 后端 Agent Note](../../implemented/feature/2026-06-22-acp-subagent-backend.md)）证明了该 seam 能跨越进程边界泛化；其「未来提供方」一节明确将 Codex app-server 与 Claude Code Agent SDK 列为实现机制相似的同类方案。如今真正值得委派的就是这两个引擎：harness 的一个轮次应能把一个自包含任务交给真实的 Claude Code 或真实的 Codex——一个拥有自身模型、工具与沙箱的独立产品——并取回一个最终答案，同时父部署不向子进程泄漏密钥，子进程行为也不静默依赖宿主机上碰巧存在的 `~/.claude` / `~/.codex` 状态。
-
-## 提案
-
-两个兄弟提供方包，作为 ACP 后端的结构变体，另加一次提取：
-
-- `@deepseek-ai/dsh-subagent-claude-code`：通过 `@anthropic-ai/claude-agent-sdk` 的 `query()` 驱动一个 Claude Code 子进程（SDK 在父进程中运行，并将其内置的 `claude` CLI（命令行界面）作为子进程 spawn）。提供方名称为 `claude-code`：子进程是 Claude Code 这个*产品*，而非 Anthropic 模型适配器——「claude」保留给未来的 `dsh-llm` 适配器。
-- `@deepseek-ai/dsh-subagent-codex`：spawn `codex app-server`，通过其 JSON-RPC-over-stdio 协议驱动一个 thread 及其中的一个轮次，使用包内一个手写的换行 JSON 客户端（约 200–300 行）。
-- `@deepseek-ai/dsh-subagent-process`：纯库（沿用 `subagent-inprocess` 的先例），提取 `dsh-subagent-acp` 已有且两个新后端都需要的内容：凭证环境清洗（`buildChildEnv`）、EOF → SIGTERM → SIGKILL 的 dispose（资源释放）阶梯，以及新的隔离配置目录辅助函数（`mkdtemp` 创建、尽力删除）。ACP 后端迁移到该库上；`bash-local` 的兄弟副本保持不动以限制变更范围。
-
-两个提供方逐字复制 ACP 后端的 seam 姿态：每次 `start` 创建全新子进程、恰好一次提示词往返、所有能力均为 `false`、`inheritsParentContext: false`、忽略 `request.parent`/`request.agentOptions`、`id = SessionId(randomUUID())`，且 `result` 从不 reject——子进程级失败扁平化为 stop reason，原始错误则通过 `onError` spec 回调送到 `ctx.logger`。模型暴露无需新代码：每个提供方各加载一次 `dsh-tool-subagent`，使用不同的 `toolName`（`subagent_claude_code`、`subagent_codex`）。无需新的会话事件——唯一的模型可见产物是工具结果，因此可重建性与 ACP 完全相同。明确边界：会话日志重建模型可见的 transcript（文本记录），而不是工作区变更历史——获准写入的子进程将文件作为日志之外的环境副作用进行修改，与 bash 工具和 ACP 后端现有行为完全一致；回放复现请求，而非磁盘。
-
-## 已验证的接口事实（固定版本）
-
-两个集成面在本提案之前均已针对固定版本进行了验证——阅读类型与打包源码、运行无需密钥的 spike——而非仅依赖厂商文档。固定版本是验证基线，不是运行时契约：后端不执行运行时版本探测（无 `codex --version` 门禁、无 SDK 版本嗅探）。兼容性在开发时强制执行——每次依赖升级都会针对真实加载路径重跑无密钥套件——在运行时则通过显式失败来保障：协议层面的意外通过 `onError` 结算为 `error`，绝不静默异常。
-
-**`@anthropic-ai/claude-agent-sdk` 0.3.202。** `options.env` 会替换子进程环境（不与 `process.env` 合并），恰好满足清洗需求。`settingSources` 默认加载所有文件系统设置——隔离要求显式传入 `[]`。结果子类型为 `success` | `error_during_execution` | `error_max_turns` | `error_max_budget_usd` | `error_max_structured_output_retries`。中止时 SDK 自行逐级加强对 CLI 子进程的终止措施：立即关闭 stdin，约 2 秒后若子进程未退出则发送 SIGTERM（已观察到；无残留进程）——无需自定义 kill 回退。`outputFormat: {type: 'json_schema'}` 和 `agents` 选项已存在，为 seam 的 `outputSchema` 能力和命名 subagent 类型提供了未来着陆点；两者均不在本 Agent Note 范围内。
-
-**codex CLI 0.142.5，`codex app-server`（v2 词汇）。** LF 分隔的 JSON，JSON-RPC 2.0 形状但省略 `"jsonrpc"` 头。
-
-- 生命周期：`initialize{clientInfo}` + `initialized` → `thread/start`（接受 `cwd`、`model`、`sandbox`、`approvalPolicy`、`ephemeral`；未认证即可成功）→ `turn/start{threadId, input:[{type:'text',text}]}` 立即返回一个 `inProgress` 的轮次；终止信号是携带 `Turn{status: completed|interrupted|failed|inProgress, error}` 的 `turn/completed` 通知。
-- 审批是服务端发起的请求——`item/commandExecution/requestApproval`、`item/fileChange/requestApproval`、`item/permissions/requestApproval`、`item/tool/requestUserInput`、`mcpServer/elicitation/request`——以 `accept`/`decline` 系列决策应答。
-- 认证：`account/login/start{type:'apiKey', apiKey}` 是一等 RPC，`account/read` 报告 `requiresOpenaiAuth`——且未认证的 `turn/start` 不会快速失败（它会挂在重试中），因此后端必须预检认证状态，并在失败时明确结算为 `error`，而非等待轮次。
-- 隔离：`CODEX_HOME` 重定向被尊重（`initialize` 响应会回显它，测试可据此断言隔离），`ephemeral: true` 的 thread 不留任何会话文件。
-
-## 隔离与凭证
-
-部署只使用 API key 认证，子进程不得看到宿主用户的 Claude Code / Codex 配置：行为必须只由 `cordis.yml` 决定。每次运行获得一个全新的 `mkdtemp` 配置目录——Claude Code 使用 `CLAUDE_CONFIG_DIR`（并显式设置 `settingSources: []`），Codex 使用 `CODEX_HOME`——dispose 时尽力删除；配置字段也可以固定一个持久目录。子进程环境通过提取逐字复用 ACP 后端的 `buildChildEnv` 语义：转发环境变量，但移除凭证形态的变量（`/KEY|SECRET|TOKEN/i`），再叠加 `config.env`——因此 `PATH`、`HOME`、`TMPDIR`、locale 和代理变量保留，CLI 正常运行；只有环境中的凭证形态变量被清洗（Claude Code 的 `ANTHROPIC_API_KEY` 通过 `config.env` 显式进入），Codex key 则通过 `account/login/start` RPC 进入隔离的 `CODEX_HOME`，而非手写 `auth.json`。
-
-## 权限与审批策略
-
-每个后端不压缩为 ACP 单一的 `permission: allow|reject` 旋钮，而把引擎原生词汇作为配置暴露，并采用保守默认值：Claude Code 获得 `permissionMode`（默认 `default`）以及 `permission: allow|reject`（默认 `reject`），后者作为所有未被前者处理的请求的 `canUseTool` 自动应答；Codex 获得 `sandboxMode`（默认 `read-only`）和 `approvalPolicy`（默认 `never`），以及同一个 `permission` 后备值，用来应答仍然到达的审批请求。默认值刻意做到不造成损害（开箱即用的子进程无法写文件）；示例演示如何开放权限（`acceptEdits` / `workspace-write`）。机械规则是：每一个服务端发起的请求都由程序迅速结算——枚举出的审批/用户输入/elicitation 请求按配置策略应答，未知请求方法用 JSON-RPC method-not-found 错误响应（绝不保持 pending），未知通知被消费——因此任何子进程请求都不会因等待永远不会到来的应答而卡住轮次。这一版中提示词不会到达人类，与 ACP 一致。
-
-## StopReason 映射
-
-Claude Code：`success` → `completed`；`error_max_turns`、`error_during_execution`、`error_max_budget_usd`、`error_max_structured_output_retries` → `error`（与 ACP 对 `max_turn_requests` 的处理对齐：未完成的任务不是成功）；生成器中止 → `aborted`；未知值 → `error`。Codex：`Turn.status` 为 `completed` → `completed`；`interrupted` → `aborted`；`failed` 且 `codexErrorInfo: 'contextWindowExceeded'` → `max-tokens`，其他 `failed` → `error`；传输/spawn/认证预检失败 → `error`（若已请求取消则为 `aborted`）。两者中，`cancel()` 采用 ACP 形状：标志位 + abort/interrupt + 一个 cancel-settled 竞争分支，使不合作的子进程无法阻塞结果。
-
-活性姿态，明确声明：teardown 时序是配置项，轮次时长不是。两个后端将 dispose 阶梯的宽限期作为带默认值的已验证配置字段（ACP 后端的 `disposeEofGraceMs`/`disposeGraceMs` 形状，由提取库承载），但刻意不设轮次时长或启动超时——与 ACP 一致：轮次期间的活性由调用方通过 `cancel()`/abort signal 掌控，subagent 轮次持续数分钟也属合理，而 Codex 认证预检消除了唯一已验证的必然挂起场景；需要墙钟上限的部署从父侧取消即可。
-
-## 测试
-
-依照根 AGENTS.md 规则在每个层级明确命名，并预先消除风险：
-
-- **无密钥单元/集成测试**：每个后端都镜像 ACP spec 清单（往返和输出累积、每种 stop 映射、两条取消路径、已中止、两种策略下的权限自动应答、未知消息容错、错误命令的 spawn 失败、HMR（热模块替换）提供方清理、导出形状、对子进程环境隔离和临时目录删除的断言；Codex 另加认证预检失败路径）。Claude Code harness 是通过 `pathToClaudeCodeExecutable` 接入真实 SDK 的脚本化假 `claude` 可执行文件——一个 spike 已在 24 ms 内完成端到端无密钥验证（假 CLI 应答一次 `control_request/initialize`，并使用普通 stream-json 通信，约 40 行）。Codex harness 是讲已验证协议格式的脚本化 mock app-server 子进程，沿用 `mock-acp-server.ts` 形状。
-- **有密钥 e2e 测试**：每个后端的真实引擎执行真实文件操作，并通过磁盘状态进行验证，固定使用开放后的配置，以免验收与不造成损害的默认值冲突——Claude Code 使用 `permissionMode: 'acceptEdits'`，Codex 使用 `sandboxMode: 'workspace-write'` + `approvalPolicy: 'never'`；自跳过会准确报告缺失的是二进制还是 key。CI 没有密钥，因此依照有密钥策略在本地运行。
-- **快照测试**：以 `TODO(claude-code-subagent-replay)` / `TODO(codex-subagent-replay)` 推迟——即 ACP 后端也推迟的独立回放形状（[按会话回放 Agent Note](../../implemented/testing/2026-06-22-subagent-snapshot-replay.md)）；在此期间由无密钥套件提供确定性覆盖。
-
-## 曾考虑的替代方案
-
-### 为什么不用官方 `@openai/codex-sdk` 而手写客户端？
-
-dispose 阶梯和环境清洗要求拥有子进程（spawn 参数、env、信号、exit 等待）；SDK 隐藏了进程。协议格式（wire format）极其简单（LF JSON），形状可按固定版本生成（`codex app-server generate-json-schema`），仓库先例（`hook-protocol`）是拥有薄协议核心而非包装他人的运行时。SDK 能节省协议演进的维护成本，但代价是失去本后端存在的意义所在的精确控制。
-
-### 为什么不用模型可见的 `subagent_type` 参数（单一 Task 风格工具）？
-
-Claude Code 自身的 Task 工具将 subagent 类型放在模型可见的 schema 中，选择一个提示词 + 工具集人格。这里的选择是在执行引擎之间做出的，而只有部署者知道哪些引擎配置了凭证——因此选择留在部署配置层，保持 `dsh-tool-subagent` 文档中的「一个提供方对应一个工具」契约。人格风格的类型选择器应是针对工具的另一个 Agent Note，而非针对后端。
-
-### 为什么不用登录态凭证和用户自身的配置？
-
-继承 `~/.claude` / `~/.codex`（订阅登录、用户设置、skill（技能）、MCP 服务器）会使子进程行为依赖宿主机状态，并在 ACP 后端和 bash 执行器确立的「凭证通过 `config.env` 显式进入，绝不隐式继承」规则上打开一个隐式例外。仅 API key 加强制配置目录隔离使运行可复现；需要共享状态的部署可以有意将配置目录字段指向一个持久目录。
-
-### 为什么不为 Claude Code 无密钥测试注入驱动层 seam？
-
-注入假的 `query()` 会 mock 我们自己的边界，使真实 SDK 加载路径未被测试（docs/testing.md 中的 real-over-mock 策略）。曾考虑此方案的风险——SDK↔CLI 的 stream-json 控制协议是内部实现——已被 spike 消除：假 CLI harness 今天能对真实固定版本的 SDK 正常工作。如果 SDK 升级破坏了 mock，无密钥套件会让升级 PR（Pull Request）失败，这正是门禁在发挥作用。
-
-### 为什么不用 ACP 适配器（如 `claude-code-acp`）复用既有后端？
-
-社区 shim 将两个引擎包装为 ACP，这会使它们在 `dsh-subagent-acp` 上变成「仅配置」。但这在 harness 与引擎之间插入了一个非官方的第三方层，抹去了本 Agent Note 暴露的原生控制面（permissionMode、sandboxMode/approvalPolicy、配置目录隔离、apiKey RPC），并以 shim 的发布节奏替换了第一方协议的稳定性。第一方接口——Agent SDK 和 app-server——才是受支持的集成点。
-
-## 验收标准
-
-在两个引擎和密钥均已配置的机器上：一个 REPL 驱动的模型通过 `subagent_claude_code` 完成一个真实文件任务，通过 `subagent_codex` 完成另一个，工具结果为子进程的最终答案，父会话日志中仅有 `tool/call` + `tool/result`。无密钥套件在无凭证环境下以逐文件 100% 覆盖率通过，断言隔离（清洗后的子进程环境、dispose 后无残留临时配置目录），并断言 `~/.claude` / `~/.codex` 的存在与否不影响子进程行为。取消父轮次后，两个后端在有界时间内完全停稳，无残留子进程。e2e 套件干净地自跳过，命名缺失的前置条件。
-
-## 风险
-
-- `codex app-server` 被 CLI 标记为实验性，其 v1/v2 词汇共存；客户端固定 0.142.5、仅实现 v2、对未知方法/通知消费而不崩溃，但未来 codex 升级仍可能迫使返工（每次升级重新生成 schema 并重跑无密钥套件——这是上述「不做运行时版本探测」立场背后的开发时强制执行）。
-- Claude Code 假 CLI mock 依赖一个内部协议：任何 SDK 升级都必须通过无密钥套件，控制协议的破坏性变更意味着返工 mock（回退方案：上面否决的驱动注入 seam 成为逃生舱口）。
-- SDK 的 optionalDependencies 每平台约 280 MB——已接受，限制在单个后端包内。
-- SDK 的 SIGKILL 分支（EOF→SIGTERM 之后）未被观察到，信任其实现；e2e 保留无残留进程断言。
-- Codex 是部署前置条件（无 npm 内置二进制）；缺失或不兼容的二进制会明确报出 spawn/协议 `error`，而非版本探测。
-- 每次运行付出一个全新子进程的代价，且仅最终答案浮出——思考、工具卡片和用量被消费后丢弃；池化、中间进度浮出、`sendMessage`/`resume`、通过 SDK 的 `outputFormat` 实现 `outputSchema`、以及通过 SDK 的 `agents` 选项实现命名 subagent 类型，均为刻意推迟。
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index f77e5462f9..f70245d49d 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -3,9 +3,9 @@
 
 # Third-Party Notices
 
-DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms.
+DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
 
-This file lists **direct** dependencies declared by the workspace. It is generated from the workspace manifests by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
+This file lists **direct** dependencies declared by the workspace and the explicitly disclosed official Claude platform payload closure. It is generated from the workspace manifests by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
 
 The complete npm transitive closure, with exact pinned versions, is recorded in [`pnpm-lock.yaml`](pnpm-lock.yaml) — inspect it with `pnpm licenses list`. The Python closure is recorded in [`python/sdk/uv.lock`](python/sdk/uv.lock), and the Landlock launcher workspace keeps its own in [`native/landlock-run/pnpm-lock.yaml`](native/landlock-run/pnpm-lock.yaml).
 
@@ -32,6 +32,8 @@ External packages that a workspace package resolves at runtime. `scripts/install
 | Package | License |
 | --- | --- |
 | [`@agentclientprotocol/sdk`](https://github.com/agentclientprotocol/typescript-sdk) | Apache-2.0 |
+| [`@anthropic-ai/claude-agent-sdk`](https://github.com/anthropics/claude-agent-sdk-typescript) | SEE LICENSE IN README.md |
+| [`@anthropic-ai/sdk`](https://github.com/anthropics/anthropic-sdk-typescript) | MIT |
 | [`@babel/code-frame`](https://github.com/babel/babel) | MIT |
 | [`@clack/core`](https://github.com/bombshell-dev/clack) | MIT |
 | [`@clack/prompts`](https://github.com/bombshell-dev/clack) | MIT |
@@ -95,6 +97,24 @@ pnpm applies local patches to the following packages at install time, so shipped
 
 - `node-pty@1.1.0` — [`patches/node-pty@1.1.0.patch`](patches/node-pty@1.1.0.patch)
 
+## Official Claude Code platform payloads
+
+The project owner authorizes distribution of every version of the official `@anthropic-ai/claude-agent-sdk` package and the official Claude Code CLI/platform payloads that each version declares through `optionalDependencies`. This identity-scoped authorization does not classify their declared terms as permissive and does not cover any unrelated runtime package; version, declared-license, and payload-set changes still require the ordinary dependency, lockfile, compatibility, terms, and notices review.
+
+The installed SDK 0.3.220 declares the following optional platform packages. Each carries the official Claude Code 2.1.220 executable; the package identities and versions come from the SDK manifest, while the declared license field is verified against the platform payload installed for the current host.
+
+| Optional platform package | Version | Declared license |
+| --- | --- | --- |
+| [`@anthropic-ai/claude-agent-sdk-darwin-arm64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-darwin-arm64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-darwin-x64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-darwin-x64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-arm64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-arm64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-arm64-musl`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-arm64-musl) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-x64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-x64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-linux-x64-musl`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-linux-x64-musl) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-win32-arm64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-win32-arm64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+| [`@anthropic-ai/claude-agent-sdk-win32-x64`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk-win32-x64) | 0.3.220 | SEE LICENSE IN LICENSE.md |
+
+
 ## Development-only npm dependencies
 
 External packages **directly declared** only by repository tooling, test infrastructure, the documentation site, the demo leaves, or the native launcher's build workspace. No shipped surface names them itself. A package here may still be pulled in transitively by a runtime dependency — `pnpm-lock.yaml` is the authority on the full closure — so this tier records who declares a package, not what a build ultimately bundles.
@@ -104,6 +124,7 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@braintree/sanitize-url`](https://github.com/braintree/sanitize-url) | MIT |
 | [`@modelcontextprotocol/server-everything`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 |
 | [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 |
+| [`@openai/codex`](https://github.com/openai/codex) | Apache-2.0 |
 | [`@stylistic/eslint-plugin`](https://github.com/eslint-stylistic/eslint-stylistic) | MIT |
 | [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) | MIT |
 | [`@testing-library/react`](https://github.com/testing-library/react-testing-library) | MIT |
diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 462b528a30..618f25c667 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -40,6 +40,8 @@ flowchart LR
   cfg --> plugin_dsh_base_session_persistence_jsonl
   plugin_dsh_base_session_query_sqlite["session-query-sqlite<br/>@deepseek-ai/dsh-session-query-sqlite"]
   cfg --> plugin_dsh_base_session_query_sqlite
+  plugin_dsh_base_session_projection["session-projection<br/>@deepseek-ai/dsh-session-projection"]
+  cfg --> plugin_dsh_base_session_projection
   plugin_dsh_base_telemetry_otel["telemetry-otel<br/>@deepseek-ai/dsh-session-telemetry-otel"]
   cfg --> plugin_dsh_base_telemetry_otel
   plugin_dsh_base_subprocess["subprocess<br/>@deepseek-ai/dsh-subprocess-local"]
@@ -166,6 +168,7 @@ flowchart LR
 | `llm-pi-ai` | `@deepseek-ai/dsh-llm-pi-ai` |
 | `session-persistence-jsonl` | `@deepseek-ai/dsh-session-persistence-jsonl` |
 | `session-query-sqlite` | `@deepseek-ai/dsh-session-query-sqlite` |
+| `session-projection` | `@deepseek-ai/dsh-session-projection` |
 | `telemetry-otel` | `@deepseek-ai/dsh-session-telemetry-otel` |
 | `subprocess` | `@deepseek-ai/dsh-subprocess-local` |
 | `sandbox` | `@deepseek-ai/dsh-sandbox-local` |
diff --git a/apps/cli/config/core-web.cordis.yml b/apps/cli/config/core-web.cordis.yml
index 6b31c8f424..0d6960c2a3 100644
--- a/apps/cli/config/core-web.cordis.yml
+++ b/apps/cli/config/core-web.cordis.yml
@@ -1,6 +1,27 @@
-# Opt-in two-tool profile over the shipped Web composition. The default native
-# model surface is exactly persistent `bash` plus `str_replace_editor`; the
-# Web host, browser shell, workspace, persistence, and permission stack remain.
+# Opt-in Web shell for the RL core agent contract. The model receives exactly
+# the configured persona plus the native `bash` and `str_replace_editor`
+# schemas; the Web host, browser shell, persistence, and permission stack stay.
+
+# Match the Claude SWE-compatible RL core prompt. Disabling the Web runtime's
+# surface context removes its GUI orientation, managed shell variables, and the
+# launcher's source-checkout section through one configuration contract.
+# Workspace instructions are model-visible user context rather than a system
+# section, but RL core disables them as part of the same prompt contract.
+- id: system-prompt
+  config:
+    includeHarnessIdentity: false
+    persona: !!js process.env.DSH_SYSTEM_PROMPT ?? 'You are a helpful software engineer assistant.'
+
+- id: web-runtime
+  config:
+    surfaceContext: false
+
+- id: workspace-context
+  disabled: true
+
+- id: tools
+  config:
+    mode: native
 
 # Disable every model-facing consumer in the base/Web tree. plan-mode owns the
 # always-registered exit_plan_mode tool even while the session is not planning.
diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml
index 6be68170b9..07d7810529 100644
--- a/apps/cli/reference/README.i18n.yaml
+++ b/apps/cli/reference/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 apps/cli/reference/README.md
-README.md: 62275139809364d80296433e804ade3d447f37e6
-README.zh.md: e508caaf05622c0c177eaacd070978368ff84af3
+README.md: 8b8a0e7dbebafedd6a4f8d988adb3fd11c7bd026
+README.zh.md: d1d6d5a594596a8be5db30021163f0fcea4a95bf
diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md
index 6227513980..8b8a0e7dbe 100644
--- a/apps/cli/reference/README.md
+++ b/apps/cli/reference/README.md
@@ -53,7 +53,9 @@ All modes treat the invoking directory as the default workspace root, load appli
 
 New sessions default to the `workspace-write` permission preset. Bash and filesystem mutations are restricted to the session workspace and platform temporary roots; reads, network access, and process visibility are not confined. `DSH_PERMISSION_MODE` changes the process fallback. Stored General-settings permissions affect later Web sessions, not an already-open one.
 
-`DSH_TOOLS_MODE` selects `native`, `code`, or `both` for the process; another value fails at boot. [`config/core-web.cordis.yml`](../config/core-web.cordis.yml) is an optional `--patch` overlay that reduces the native model surface to persistent `bash` and `str_replace_editor` while retaining the shipped host, browser, workspace, persistence, and permission composition.
+`DSH_TOOLS_MODE` selects `native`, `code`, or `both` for the process; another value fails at boot. [`config/core-web.cordis.yml`](../config/core-web.cordis.yml) is an optional RL-compatible `--patch` overlay that pins native mode, renders only `DSH_SYSTEM_PROMPT` or `You are a helpful software engineer assistant.` as the system prompt, disables Workspace instructions and every Web runtime prompt contribution, and exposes only persistent `bash` and `str_replace_editor` while retaining the shipped host, browser, workspace, persistence, and permission composition.
+
+`DSH_SYSTEM_PROMPT` is passed as the system-prompt [`persona`](../../../packages/core/system-prompt/README.md#config): complete `{{…}}` groups use that contract's strict variable interpolation and have no literal-brace escape; any set value, including an empty string, is authoritative and an empty value therefore removes the system prompt, while only an unset variable selects the fallback.
 
 ## Shared deployment behavior
 
diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md
index e508caaf05..d1d6d5a594 100644
--- a/apps/cli/reference/README.zh.md
+++ b/apps/cli/reference/README.zh.md
@@ -53,7 +53,9 @@ dsh web --dump-config
 
 新会话默认使用 `workspace-write` 权限预设。Bash 和文件系统修改仅限于会话 workspace 与平台临时根目录；读取、网络访问和进程可见性不受限制。`DSH_PERMISSION_MODE` 更改进程后备值。General settings 中存储的权限影响后续 Web 会话，不改变已打开的会话。
 
-`DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 `--patch` overlay：它在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，把原生模型 surface 缩减为持久 `bash` 和 `str_replace_editor`。
+`DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 RL 兼容 `--patch` overlay：它固定使用 `native` 模式，仅将 `DSH_SYSTEM_PROMPT` 或 `You are a helpful software engineer assistant.` 渲染为系统提示词，禁用 Workspace 指令与所有 Web 运行时提示词贡献，并且在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，仅暴露持久 `bash` 和 `str_replace_editor`。
+
+`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该契约的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
 
 ## 共享部署行为
 
diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts
index 44c943a7aa..b69a938213 100644
--- a/apps/cli/src/profile-boot.ts
+++ b/apps/cli/src/profile-boot.ts
@@ -95,6 +95,9 @@ export function prepareProfile(name: string, userLayer = true): Profile {
   return profile
 }
 
+/** Read-only row index of a profile composition before launcher flag patches. */
+export type ProfileRows = ReadonlyMap<string, { name?: string; config?: unknown }>
+
 /** One profile's patch layers (application order) and the row index of its pre-flag composition. */
 interface ComposedProfile {
   profile: Profile
@@ -109,7 +112,7 @@ interface ComposedProfile {
    * for flag merges and row checks. Flag patches must not insert rows the
    * launcher consults here (they only override values and insert dev glue).
    */
-  rows: Map<string, { name?: string; config?: unknown }>
+  rows: ProfileRows
 }
 
 /** The full patch stack of one composed profile, in application order. */
@@ -155,11 +158,11 @@ export interface RunProfileOptions {
   /** `--patch` overlay paths, in argv order. */
   patchFiles: readonly string[]
   /** Launcher hook turning the pre-flag composed rows into flag patches (the web alias's flag family). */
-  deriveFlagPatches?: (rows: ComposedProfile['rows']) => PatchOptions[]
+  deriveFlagPatches?: (rows: ProfileRows) => PatchOptions[]
   /** One-shot task text; requires the composition to mount the headless runner row. */
   task?: string
   /** Surface setup registered after Loader installation and before any config-tree entry mounts. */
-  prepare?: (ctx: Context) => Promise<void> | void
+  prepare?: (ctx: Context, rows: ProfileRows) => Promise<void> | void
 }
 
 /**
@@ -231,7 +234,7 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
       }
       hostCtx.provide('headlessIo', io)
     }
-    await options.prepare?.(hostCtx)
+    await options.prepare?.(hostCtx, composed.rows)
   })
   app.current = ctx
   // A surface can dispose the whole tree while startup was still in flight
diff --git a/apps/cli/src/web.ts b/apps/cli/src/web.ts
index 4301af6e1a..64051416c4 100644
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -13,7 +13,7 @@ import { fileURLToPath } from 'node:url'
 import type { Context } from 'cordis'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot'
-import { runProfile } from './profile-boot.ts'
+import { runProfile, type ProfileRows } from './profile-boot.ts'
 
 const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
 
@@ -71,7 +71,7 @@ export interface WebFlags {
  * @returns the flag patch list, in application order.
  */
 function deriveWebFlagPatches(
-  rows: Map<string, { name?: string; config?: unknown }>,
+  rows: ProfileRows,
   flags: WebFlags,
 ): PatchOptions[] {
   const overrides = new Map<string, Record<string, unknown>>()
@@ -105,6 +105,18 @@ function deriveWebFlagPatches(
   return patches
 }
 
+/**
+ * Whether the composed Web runtime keeps its model- and shell-visible surface
+ * context. The bundle schema defaults the field to true, so only an explicit
+ * false suppresses both the bundle contributions and the launcher-owned
+ * source-checkout section.
+ * @param rows - the composed Web profile rows before launcher flag patches.
+ * @returns true unless the web-runtime row explicitly disables surface context.
+ */
+export function webSurfaceContextEnabled(rows: ProfileRows): boolean {
+  return (rows.get('web-runtime')?.config as { surfaceContext?: boolean } | undefined)?.surfaceContext !== false
+}
+
 /**
  * Serve the browser UI from the web profile. Host/port/workspace-root flags
  * are passed through only when given (absent, the composed profile values
@@ -118,7 +130,8 @@ export async function runWeb(flags: WebFlags): Promise<void> {
     profile: 'web',
     patchFiles: flags.patches,
     deriveFlagPatches: rows => deriveWebFlagPatches(rows, flags),
-    prepare: (ctx: Context) => {
+    prepare: (ctx: Context, rows: ProfileRows) => {
+      if (!webSurfaceContextEnabled(rows)) return
       ctx.inject(['systemPrompt'], (promptCtx) => {
         addHarnessSourceSection(promptCtx, SOURCE_ROOT)
       })
diff --git a/apps/cli/tests/built-bin.e2e.ts b/apps/cli/tests/built-bin.e2e.ts
index e8c7d18b18..ede3d17134 100644
--- a/apps/cli/tests/built-bin.e2e.ts
+++ b/apps/cli/tests/built-bin.e2e.ts
@@ -8,6 +8,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 /** Published-entry acceptance for argument errors, profile lifecycle, and boot-free config dumps. */
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const coreWebOverlay = fileURLToPath(new URL('../config/core-web.cordis.yml', import.meta.url))
 const invalidProvider = fileURLToPath(new URL('./fixtures/invalid-provider.cordis.yml', import.meta.url))
 
 async function runBuiltBin(
@@ -367,5 +368,16 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(stdout).toContain(`patched by ${profilePatch}, ${overlay}`)
       expect(stderr).toContain('patch: entry "absent-row" not found')
     }, 30_000)
+
+    it('shows the RL Web patch disabling runtime surface context', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['web', '--patch', coreWebOverlay, '--dump-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-web-app'")
+      expect(stdout).toContain('surfaceContext: false')
+    }, 30_000)
   })
 })
diff --git a/apps/cli/tests/trusted-hosts.spec.ts b/apps/cli/tests/trusted-hosts.spec.ts
index 11b925604a..5647d01536 100644
--- a/apps/cli/tests/trusted-hosts.spec.ts
+++ b/apps/cli/tests/trusted-hosts.spec.ts
@@ -1,7 +1,7 @@
 /** Single-sample LAN-trust resolution for the /api browser-trust fence (`resolveLanTrust`). */
 
 import { describe, expect, it, vi } from 'vitest'
-import { resolveLanTrust } from '../src/web.ts'
+import { resolveLanTrust, webSurfaceContextEnabled } from '../src/web.ts'
 
 vi.mock('node:os', () => ({
   networkInterfaces: () => ({
@@ -31,3 +31,15 @@ describe('resolveLanTrust', () => {
     expect(resolveLanTrust(undefined, ['lab.internal'])).toEqual({ lanAddresses: [], trustedHosts: ['lab.internal'] })
   })
 })
+
+describe('webSurfaceContextEnabled', () => {
+  it('defaults to enabled and honors an explicit complete-prompt disable', () => {
+    expect(webSurfaceContextEnabled(new Map())).toBe(true)
+    expect(webSurfaceContextEnabled(new Map([
+      ['web-runtime', { config: { mode: 'production' } }],
+    ]))).toBe(true)
+    expect(webSurfaceContextEnabled(new Map([
+      ['web-runtime', { config: { surfaceContext: false } }],
+    ]))).toBe(false)
+  })
+})
diff --git a/apps/web/tests/assembled-boot.ts b/apps/web/tests/assembled-boot.ts
new file mode 100644
index 0000000000..0e168ba9fe
--- /dev/null
+++ b/apps/web/tests/assembled-boot.ts
@@ -0,0 +1,133 @@
+// Shared scaffolding for the assembled-jsdom snapshots: the real built
+// `packages/client/*/lib/client.js` artifacts booted through AppWebEntry's
+// ModuleLoader path (loadBundle) against the keyless FixtureApiClient
+// transport. Every file that mounts this graph needs the same boot entry list,
+// the same bundle map, the same jsdom globals, and the same mount call, and
+// differs only in what it asserts afterwards, so the scaffolding lives here.
+//
+// Keyless and deterministic: the fixture is the fake server, so nothing here
+// reaches a model or the network.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { act, cleanup } from '@testing-library/react'
+import { afterEach, beforeEach, vi } from 'vitest'
+import type { WebBootEntry } from '@deepseek-ai/dsh-client-modules/client'
+import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
+
+/** Boot entries for the minimal assembled graph, each carrying the workspace directory its bundle is read from. */
+const PLUGINS: readonly (WebBootEntry & { dir: string })[] = [
+  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-locale', dir: 'locale', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
+  { id: '@deepseek-ai/dsh-client-ui-sidebar', dir: 'ui-sidebar', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  {
+    id: '@deepseek-ai/dsh-client-ui-workspace',
+    dir: 'ui-workspace',
+    url: '/plugins/ui-workspace.js',
+    rev: 'fx',
+    inject: [
+      '@deepseek-ai/dsh-client-runtime',
+      '@deepseek-ai/dsh-client-ui-conversation',
+      '@deepseek-ai/dsh-client-ui-sidebar',
+    ],
+  },
+  { id: '@deepseek-ai/dsh-client-ui-trajectory', dir: 'ui-trajectory', url: '/plugins/ui-trajectory.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
+]
+
+const bundles = new Map(PLUGINS.map(plugin => [
+  plugin.url,
+  readFileSync(join(process.cwd(), 'packages/client', plugin.dir, 'lib/client.js'), 'utf8'),
+]))
+
+interface FixtureWindow extends Window {
+  __DSH_BOOT__?: { rev: string; entries: WebBootEntry[] }
+  __ModuleLoader__?: unknown
+}
+
+class ResizeObserverStub {
+  observe(): void {}
+  disconnect(): void {}
+  unobserve(): void {}
+}
+
+const win = window as FixtureWindow
+let unmount: (() => void) | undefined
+
+/**
+ * Register the per-test jsdom setup and teardown the assembled boot needs:
+ * English pinned before boot so role/text locators stay deterministic across
+ * localized component migrations (the newEnglishPage e2e convention), the
+ * observers and frame callbacks jsdom lacks, and a full reset of the document,
+ * the boot globals, and the injected plugin styles afterwards.
+ */
+export function installAssembledBootEnv(): void {
+  beforeEach(() => {
+    localStorage.clear()
+    localStorage.setItem('dsh.locale', 'en')
+    document.title = 'DeepSeek Harness'
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+    vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+      setTimeout(() => { callback(0) }, 0) as unknown as number)
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => { clearTimeout(id) })
+  })
+
+  afterEach(() => {
+    act(() => { unmount?.() })
+    unmount = undefined
+    cleanup()
+    delete win.__DSH_BOOT__
+    delete win.__ModuleLoader__
+    document.body.innerHTML = ''
+    document.head.querySelectorAll('style[data-plugin]').forEach((style) => { style.remove() })
+    document.title = ''
+    history.replaceState(null, '', '/')
+    vi.unstubAllGlobals()
+  })
+}
+
+/**
+ * Mount the assembled application on the fixture transport; the teardown
+ * registered by installAssembledBootEnv disposes it.
+ */
+export function mountAssembledApp(): void {
+  history.replaceState(null, '', '/?fixture')
+  const root = document.createElement('div')
+  root.id = 'root'
+  document.body.appendChild(root)
+  win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ dir: _dir, ...plugin }) => plugin) }
+  act(() => {
+    const entry = new AppWebEntry(root, {
+      loadBundle: async (url) => {
+        const code = bundles.get(url)
+        if (code === undefined) throw new Error(`missing built bundle ${url}`)
+        ;(0, eval)(code)
+      },
+    })
+    void entry.run()
+    unmount = () => { entry.dispose() }
+  })
+}
+
+/**
+ * Match a CSS-module class by its logical name.
+ * Module class names carry a per-build hash in one of two schemes —
+ * ui-primitives emits `_<name>_<hash>` (name bounded by underscores),
+ * ui-conversation emits `<hash>_<name>` (name at the end) — and a longer name
+ * containing this one must not match (`line` must not hit `lineNumber`).
+ * @param el - element whose class list is inspected.
+ * @param name - logical (unhashed) module class name.
+ * @returns whether the element carries that module class.
+ */
+export function hasClass(el: Element, name: string): boolean {
+  return [...el.classList].some(cls => cls === name || cls.endsWith(`_${name}`) || cls.startsWith(`_${name}_`) || cls.includes(`_${name}_`))
+}
+
+/**
+ * Whether this run rewrites its golden instead of comparing against it, set by
+ * the snapshot gate's `DSH_SNAPSHOT` mode (`record` re-runs the scenarios from
+ * scratch, `refresh` re-derives the expected text from the existing ones).
+ */
+export const REFRESHING_GOLDEN = process.env.DSH_SNAPSHOT === 'record' || process.env.DSH_SNAPSHOT === 'refresh'
diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts
index b102dff8b8..3d1536e923 100644
--- a/apps/web/tests/built-boot.snapshot.ts
+++ b/apps/web/tests/built-boot.snapshot.ts
@@ -1,105 +1,23 @@
 // @vitest-environment jsdom
-// The built-bundle boot smoke: the ONE assembled-jsdom test that loads the
-// real `packages/client/*/lib/client.js` artifacts through AppWebEntry's
-// ModuleLoader path (loadBundle) and proves the boot graph
-// assembles — staged activation across the immediately tier and the inject
-// layers, per-plugin CSS injection, and a rendered journey reaching chat
-// content from the keyless FixtureApiClient transport.
+// The built-bundle boot smoke: the assembled-jsdom test that owns the boot
+// graph itself. Other files share the same scaffolding (assembled-boot.ts) to
+// reach a surface only the built bundles expose; this one asserts that the
+// graph assembles at all — staged activation across the immediately tier and
+// the inject layers, per-plugin CSS injection, and a rendered journey reaching
+// chat content from the keyless FixtureApiClient transport.
 //
 // Component behavior remains owned by per-package suites (SlotTestRuntime
 // benches over src). This smoke additionally pins the resident interaction
 // fixture's cross-plugin projection because only the built connection/runtime/
 // workspace graph can prove that transport-to-row path end to end.
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-library/react'
-import { afterEach, beforeEach, expect, it, vi } from 'vitest'
-import type { WebBootEntry } from '@deepseek-ai/dsh-client-modules/client'
-import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
+import { act, fireEvent, screen, waitFor, within } from '@testing-library/react'
+import { expect, it } from 'vitest'
+import { installAssembledBootEnv, mountAssembledApp } from './assembled-boot.ts'
 
-const PLUGINS: readonly (WebBootEntry & { dir: string })[] = [
-  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-locale', dir: 'locale', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
-  { id: '@deepseek-ai/dsh-client-ui-sidebar', dir: 'ui-sidebar', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
-  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
-  {
-    id: '@deepseek-ai/dsh-client-ui-workspace',
-    dir: 'ui-workspace',
-    url: '/plugins/ui-workspace.js',
-    rev: 'fx',
-    inject: [
-      '@deepseek-ai/dsh-client-runtime',
-      '@deepseek-ai/dsh-client-ui-conversation',
-      '@deepseek-ai/dsh-client-ui-sidebar',
-    ],
-  },
-  { id: '@deepseek-ai/dsh-client-ui-trajectory', dir: 'ui-trajectory', url: '/plugins/ui-trajectory.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
-]
-
-const bundles = new Map(PLUGINS.map(plugin => [
-  plugin.url,
-  readFileSync(join(process.cwd(), 'packages/client', plugin.dir, 'lib/client.js'), 'utf8'),
-]))
-
-interface FixtureWindow extends Window {
-  __DSH_BOOT__?: { rev: string; entries: WebBootEntry[] }
-  __ModuleLoader__?: unknown
-}
-
-class ResizeObserverStub {
-  observe(): void {}
-  disconnect(): void {}
-  unobserve(): void {}
-}
-
-const win = window as FixtureWindow
-let unmount: (() => void) | undefined
-
-beforeEach(() => {
-  localStorage.clear()
-  // English pinned before boot: role/text locators stay deterministic across
-  // localized component migrations (the newEnglishPage e2e convention).
-  localStorage.setItem('dsh.locale', 'en')
-  document.title = 'DeepSeek Harness'
-  vi.stubGlobal('ResizeObserver', ResizeObserverStub)
-  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-    setTimeout(() => { callback(0) }, 0) as unknown as number)
-  vi.stubGlobal('cancelAnimationFrame', (id: number) => { clearTimeout(id) })
-})
-
-afterEach(() => {
-  act(() => { unmount?.() })
-  unmount = undefined
-  cleanup()
-  delete win.__DSH_BOOT__
-  delete win.__ModuleLoader__
-  document.body.innerHTML = ''
-  document.head.querySelectorAll('style[data-plugin]').forEach((style) => { style.remove() })
-  document.title = ''
-  history.replaceState(null, '', '/')
-  vi.unstubAllGlobals()
-})
+installAssembledBootEnv()
 
 it('boots the built plugin graph and renders a fixture session end to end', async () => {
-  history.replaceState(null, '', '/?fixture')
-  const root = document.createElement('div')
-  root.id = 'root'
-  document.body.appendChild(root)
-  win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ dir: _dir, ...plugin }) => plugin) }
-  act(() => {
-    const entry = new AppWebEntry(root, {
-      loadBundle: async (url) => {
-        const code = bundles.get(url)
-        if (code === undefined) throw new Error(`missing built bundle ${url}`)
-        ;(0, eval)(code)
-      },
-    })
-    void entry.run()
-    unmount = () => { entry.dispose() }
-  })
+  mountAssembledApp()
 
   // The sidebar renders from the boot graph: every inject layer activated.
   const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 })
diff --git a/apps/web/tests/conversation-column-overflow.e2e.ts b/apps/web/tests/conversation-column-overflow.e2e.ts
new file mode 100644
index 0000000000..97e1fd1fa2
--- /dev/null
+++ b/apps/web/tests/conversation-column-overflow.e2e.ts
@@ -0,0 +1,339 @@
+// Web e2e scenario: the conversation column scrolls on one axis only, as the
+// browser actually lays it out. The reported symptom was a horizontal
+// scrollbar under the whole center column once the window (or the sidebar
+// drag) narrowed it — the hero's decorative backdrop ellipse bleeding past the
+// column and becoming user-scrollable.
+//
+// The bleed is by construction and stays: `.heroGlow` is sized 1051/776 of the
+// hero box (ConversationRoot.module.css) so the blur scales with the input
+// card. What changed is the scroll container: `[data-conversation-scroll]`
+// scrolls vertically, and a box that scrolls in one axis computes the other
+// axis's initial `visible` to `auto`, so the bleed came back as a bar. The
+// fix states `overflow-x: hidden` there.
+//
+// Only a real engine reports that pair — the bleed and the resulting scroll
+// range — so the scenario sweeps viewport widths that bracket the glow's
+// width and asserts both at each stop. Asserting no horizontal scroll alone
+// would go vacuous the moment the glow stopped bleeding for an unrelated
+// reason, which is why each stop also records whether it bleeds; the wide stop
+// is the control where it does not.
+//
+// Zero model calls: the hero is the boot state, so nothing is seeded and no
+// replay row mounts. A stray stream would fail loud with NO_ADAPTER.
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
+import {
+  assertFixtureInventory, compareOrRefreshGolden, launchWebScaffold, watchConsole, webSnapshotMode,
+  type WebScaffold,
+} from './scaffold.ts'
+import { newEnglishPage, saveFailureShot } from './support.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/conversation-column-overflow', import.meta.url))
+/**
+ * Committed golden of the one-axis relation at every stop. It records
+ * relations and booleans, never absolute coordinates: the column width follows
+ * the viewport and the sidebar, and a golden carrying pixels would document the
+ * platform instead of the change.
+ */
+const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
+const MODE = webSnapshotMode()
+/** Narrow sweep stop where the mutation control retains overflow across scrollbar implementations. */
+const CONTROL_VIEWPORT = 600
+/**
+ * Viewport widths bracketing the glow: the narrow stops retain the reported
+ * bleed while the widest stop proves the relation can also be false.
+ */
+const WIDTHS = [1680, 1200, 1000, 800, CONTROL_VIEWPORT]
+/** Element id of the mutation control's injected sheet, so the test can take it back out. */
+const CONTROL_STYLE_ID = 'dsh-column-overflow-control'
+/** Horizontal wheel delta per gesture; must exceed the widest bleed the sweep can produce. */
+const WHEEL_DELTA = 300
+
+/** One viewport stop: whether the glow bleeds past the column, and whether that bleed scrolls. */
+interface ColumnMetrics {
+  /** Viewport width the stop was measured at. */
+  width: number
+  /** The column's content width. Not committed to the golden — it is what settles after a resize, and what the sweep waits on. */
+  columnWidth: number
+  /** Resolved `overflow-x` on the conversation scroll container. */
+  overflowX: string
+  /** True when the glow's box reaches past the column's content edge — the condition the fix has to survive. */
+  glowBleeds: boolean
+  /**
+   * `scrollWidth - clientWidth`. Deliberately NOT the assertion: `hidden` and
+   * `auto` both report the same value, because `hidden` clips the bleed rather
+   * than reflowing it away. Recorded because it is the vacuity guard in
+   * numbers — it must stay positive at the narrow stops, or the scenario has
+   * stopped reproducing the situation the fix is for.
+   */
+  bleedRange: number
+  /** True when the column still scrolls vertically — the axis the fix must not take away. */
+  scrollsVertically: boolean
+}
+
+/**
+ * Measure the conversation column at the page's current viewport.
+ * @param page - the page under test.
+ * @param width - the viewport width already applied, recorded with the reading.
+ * @returns the stop's overflow relations.
+ */
+function measureColumn(page: Page, width: number): Promise<ColumnMetrics> {
+  return page.evaluate((viewportWidth) => {
+    const scroller = document.querySelector<HTMLElement>('[data-conversation-scroll]')
+    if (scroller === null) throw new Error('conversation scroll container not in the DOM')
+    const glow = scroller.querySelector<SVGElement>('[class*="heroGlow"]')
+    if (glow === null) throw new Error('hero glow not in the DOM — the boot state is not the hero')
+    const box = scroller.getBoundingClientRect()
+    const glowBox = glow.getBoundingClientRect()
+    return {
+      width: viewportWidth,
+      columnWidth: scroller.clientWidth,
+      overflowX: getComputedStyle(scroller).overflowX,
+      // `clientWidth` is the content edge, which is what the scrollable
+      // overflow region is measured against; either side counts as a bleed,
+      // though only the right one can produce a bar in this writing mode.
+      glowBleeds: glowBox.right > box.left + scroller.clientWidth + 0.5 || glowBox.left < box.left - 0.5,
+      bleedRange: scroller.scrollWidth - scroller.clientWidth,
+      scrollsVertically: getComputedStyle(scroller).overflowY === 'auto',
+    }
+  }, width)
+}
+
+/**
+ * Scroll the column sideways the way a user would and report where it landed.
+ *
+ * This is the one signal that separates the two states, and it is why the
+ * scenario needs a real engine: `overflow-x: hidden` leaves the box
+ * programmatically scrollable and leaves `scrollWidth` untouched, so every
+ * property reading agrees across the fix. Only refusing an actual input event
+ * differs — measured at the 1200px stop, the shipped column stays at 0 while
+ * the same page with `overflow-x: auto` forced on lands at its scroll boundary.
+ * @param page - the page under test.
+ * @returns `scrollLeft` after one horizontal wheel over the column.
+ */
+async function wheelHorizontally(page: Page): Promise<number> {
+  const origin = await page.evaluate(() => {
+    const scroller = document.querySelector<HTMLElement>('[data-conversation-scroll]')
+    if (scroller === null) throw new Error('conversation scroll container not in the DOM')
+    // Start from the origin so the reading is this gesture's own effect.
+    scroller.scrollLeft = 0
+    const box = scroller.getBoundingClientRect()
+    // Near the top of the column, clear of the centered hero card: the wheel
+    // must reach the column, not a nested scroller the composer owns.
+    return { x: box.left + box.width / 2, y: box.top + 60 }
+  })
+  await page.mouse.move(origin.x, origin.y)
+  await page.mouse.wheel(WHEEL_DELTA, 0)
+  // A fixed settle, then two frames. Polling for a settled value cannot be
+  // used here — the value under test is 0, which a poll starting at 0 accepts
+  // before the gesture has had any chance to move it — so the wait is
+  // generous enough to cover a smooth-scroll animation on any engine the lane
+  // runs on. The timing is identical on both sides of the mutation control
+  // below, which is what makes a 0 reading evidence rather than a race won.
+  await page.waitForTimeout(400)
+  return page.evaluate(() => new Promise<number>((resolve) => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        resolve(document.querySelector<HTMLElement>('[data-conversation-scroll]')?.scrollLeft ?? -1)
+      })
+    })
+  }))
+}
+
+/**
+ * Measure the positive horizontal scroll boundary without changing the
+ * shipped overflow mode. This is distinct from `scrollWidth - clientWidth`
+ * when a stable scrollbar gutter leaves part of the overflow on the negative
+ * side of the scroll origin.
+ * @param page - the page under test.
+ * @returns the greatest positive `scrollLeft` reachable by the control gesture.
+ */
+async function horizontalScrollLimit(page: Page): Promise<number> {
+  return page.evaluate((delta) => {
+    const scroller = document.querySelector<HTMLElement>('[data-conversation-scroll]')
+    if (scroller === null) throw new Error('conversation scroll container not in the DOM')
+    const previousScrollBehavior = scroller.style.scrollBehavior
+    scroller.style.scrollBehavior = 'auto'
+    scroller.scrollLeft = delta
+    const limit = scroller.scrollLeft
+    scroller.scrollLeft = 0
+    scroller.style.scrollBehavior = previousScrollBehavior
+    return limit
+  }, WHEEL_DELTA)
+}
+
+/** A stop's readings plus where a horizontal wheel over it landed. */
+type ColumnStop = ColumnMetrics & {
+  /** `scrollLeft` after one horizontal wheel: the user-facing claim, 0 at every stop. */
+  scrollLeftAfterWheel: number
+}
+
+/**
+ * Render the golden body: one line per stop, relations only.
+ *
+ * Absolute pixels are deliberately absent apart from `scrollLeftAfterWheel`,
+ * which the fix pins to 0 by construction. The bleed is recorded as a boolean
+ * rather than its width, so the golden survives any platform whose column
+ * lands a pixel off — a fixture that has to be re-recorded per platform
+ * documents the platform, not the change.
+ * @param stops - the measured stops, in sweep order.
+ * @returns the golden body, without a trailing newline.
+ */
+function renderGeometry(stops: ColumnStop[]): string {
+  return [
+    '# Conversation column horizontal overflow',
+    '',
+    '| viewport | overflow-x | glow bleeds past the column | scrollLeft after a horizontal wheel | scrolls vertically |',
+    '| --- | --- | --- | --- | --- |',
+    ...stops.map(stop => `| ${String(stop.width)}px | ${stop.overflowX} | ${String(stop.glowBleeds)} `
+      + `| ${String(stop.scrollLeftAfterWheel)}px | ${String(stop.scrollsVertically)} |`),
+  ].join('\n')
+}
+
+describe('web e2e: the conversation column scrolls on one axis', () => {
+  let scaffold: WebScaffold
+  let browser: Browser
+  let page: Page
+  let tripwire: ReturnType<typeof watchConsole>
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({})
+    browser = await chromium.launch()
+    page = await newEnglishPage(browser, 900)
+    tripwire = watchConsole(page)
+    await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
+    await page.waitForSelector('[data-conversation-scroll] [class*="heroGlow"]', { timeout: 30_000 })
+  }, 180_000)
+
+  afterAll(async () => {
+    await browser?.close()
+    await scaffold?.close()
+  })
+
+  /**
+   * Resize to a viewport and read the column once its width stops moving.
+   *
+   * The glow rides the hero box, which rides the column, and the frame eases
+   * its column tracks over `--ds-transition-duration-slow`: reading straight
+   * after a resize can report the previous viewport's relation, or a width
+   * caught mid-transition.
+   * @param width - viewport width to settle at.
+   * @returns the column's readings at that width.
+   */
+  const settleAt = async (width: number): Promise<ColumnMetrics> => {
+    await page.setViewportSize({ width, height: 900 })
+    let previous = -1
+    await expect.poll(async () => {
+      const current = (await measureColumn(page, width)).columnWidth
+      const settled = current === previous
+      previous = current
+      return settled
+    }, { timeout: 10_000 }).toBe(true)
+    return measureColumn(page, width)
+  }
+
+  /**
+   * Sweep the stops once per run and hand the SAME readings to every assertion
+   * below, so the golden and the assertions describe one measurement instead of
+   * two runs that could disagree. Memoized rather than re-run per test: the
+   * gestures below move the viewport, and a second sweep would be a second
+   * chance for a resize to settle differently.
+   * @returns the stops in {@link WIDTHS} order.
+   */
+  let swept: Promise<ColumnStop[]> | undefined
+  const sweep = (): Promise<ColumnStop[]> => {
+    swept ??= (async () => {
+      const stops: ColumnStop[] = []
+      for (const width of WIDTHS) {
+        stops.push({ ...await settleAt(width), scrollLeftAfterWheel: await wheelHorizontally(page) })
+      }
+      return stops
+    })()
+    return swept
+  }
+
+  it('never scrolls horizontally, at any width the glow bleeds past', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow'))
+    const stops = await sweep()
+    // The vacuity guard, in two halves: the glow has to reach past the column
+    // at the narrow stops, and that reach has to still register as scrollable
+    // overflow. Without both, the claim below holds for free.
+    expect(stops.filter(stop => stop.glowBleeds).map(stop => stop.width)).toEqual([
+      1200, 1000, 800, CONTROL_VIEWPORT,
+    ])
+    for (const stop of stops.filter(stop => stop.glowBleeds)) {
+      expect(stop.bleedRange, `viewport ${String(stop.width)}`).toBeGreaterThan(0)
+    }
+    for (const stop of stops) {
+      expect(stop.overflowX, `viewport ${String(stop.width)}`).toBe('hidden')
+      // The reported symptom, stated directly: a horizontal wheel over the
+      // column moves nothing, at every stop.
+      expect(stop.scrollLeftAfterWheel, `viewport ${String(stop.width)}`).toBe(0)
+      // The axis the column is a scroller for must survive the fix.
+      expect(stop.scrollsVertically, `viewport ${String(stop.width)}`).toBe(true)
+    }
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('reports the pre-fix state when the axis is opened back up', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow-control'))
+    // The mutation control, run in the page rather than against a second
+    // build: it restores exactly what the fix changed — the initial `visible`
+    // that a one-axis scroller computes to `auto` — and shows the same gesture,
+    // at the same timing, carrying the column to its positive scroll boundary.
+    // Without it a `scrollLeft` of 0 could equally mean the wheel never arrived.
+    // Injected with an id rather than through `addStyleTag`, so the teardown
+    // below can take the sheet out again by selector: it must not outlive this
+    // test, or the golden ends up reading the control.
+    await page.evaluate((id: string) => {
+      const sheet = document.createElement('style')
+      sheet.id = id
+      sheet.textContent = '[data-conversation-scroll] { overflow-x: auto !important; }'
+      document.head.append(sheet)
+    }, CONTROL_STYLE_ID)
+    try {
+      // Resolve the mutated layout at the narrowest sweep stop. At wider stops,
+      // a classic scrollbar can change the available box enough to remove the
+      // overflow that the control is meant to expose.
+      const before = await settleAt(CONTROL_VIEWPORT)
+      expect(before.overflowX).toBe('auto')
+      expect(before.bleedRange).toBeGreaterThan(0)
+      const scrollLimit = await horizontalScrollLimit(page)
+      // The control has a reachable horizontal range, and the gesture exceeds
+      // it so the equality below proves that the wheel reached the far edge.
+      expect(scrollLimit).toBeGreaterThan(0)
+      expect(scrollLimit).toBeLessThan(WHEEL_DELTA)
+      // Rounded: `scrollLeft` is fractional under a fractional layout while
+      // the claim is that the column reached the positive boundary, not that
+      // two engines agree on a sub-pixel.
+      expect(Math.round(await wheelHorizontally(page))).toBe(Math.round(scrollLimit))
+    } finally {
+      await page.evaluate((id: string) => {
+        document.getElementById(id)?.remove()
+      }, CONTROL_STYLE_ID)
+    }
+    // The override is gone and the shipped state is back: the later goldens
+    // read the product, not the control.
+    expect((await settleAt(CONTROL_VIEWPORT)).overflowX).toBe('hidden')
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('matches the committed column-overflow golden', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow-golden'))
+    await compareOrRefreshGolden(GEOMETRY_EXPECTED, renderGeometry(await sweep()), MODE)
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
+  it('commits exactly the fixtures it reads', async () => {
+    // No model calls, so no replay log: the golden is the whole inventory.
+    await assertFixtureInventory(SNAPSHOT_DIR, ['geometry.expected.md'])
+  })
+
+  it.skipIf(MODE === 'record')('issued zero model calls and stayed clean', () => {
+    expect(tripwire.warnings).toEqual([])
+    expect(tripwire.pageErrors).toEqual([])
+  })
+})
diff --git a/apps/web/tests/core-web-profile.snapshot.ts b/apps/web/tests/core-web-profile.snapshot.ts
index 58f2a34858..1178390837 100644
--- a/apps/web/tests/core-web-profile.snapshot.ts
+++ b/apps/web/tests/core-web-profile.snapshot.ts
@@ -3,21 +3,27 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import type { AgentHandle } from '@deepseek-ai/dsh-agent'
-import { CallId } from '@deepseek-ai/dsh-llm'
+import { CallId, createUserMessage } from '@deepseek-ai/dsh-llm'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import { launchWebScaffold, type WebScaffold } from './scaffold.ts'
+import { assertFixtureInventory, launchWebScaffold, type WebScaffold } from './scaffold.ts'
 
 const CORE_WEB_OVERLAY = fileURLToPath(new URL('../../cli/config/core-web.cordis.yml', import.meta.url))
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/core-web-profile', import.meta.url))
+const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
+const PROMPT = 'Reply exactly CORE_WEB_REQUEST_OK and stop.'
 
 describe('core Web profile', () => {
   let scaffold: WebScaffold
   let agentHandle: AgentHandle
 
   beforeAll(async () => {
-    scaffold = await launchWebScaffold({
-      extraOverlayPath: CORE_WEB_OVERLAY,
-      toolsMode: 'native',
-    })
+    const systemPrompt = process.env.DSH_SYSTEM_PROMPT
+    Reflect.deleteProperty(process.env, 'DSH_SYSTEM_PROMPT')
+    try {
+      scaffold = await launchWebScaffold({ extraOverlayPath: CORE_WEB_OVERLAY, replayFixture: FIXTURE })
+    } finally {
+      if (systemPrompt !== undefined) process.env.DSH_SYSTEM_PROMPT = systemPrompt
+    }
     agentHandle = await scaffold.ctx.agents.create({
       sessionId: SessionId('core-web-profile-smoke'),
       meta: { cwd: scaffold.workspaceCwd },
@@ -33,7 +39,16 @@ describe('core Web profile', () => {
     if (failures.length > 1) throw new AggregateError(failures, 'core Web profile smoke teardown failed')
   })
 
-  it('boots and executes both tools through the shipped Web composition', async () => {
+  it('sends the RL prompt and tool schemas through a real request, then executes both tools', async () => {
+    agentHandle.agent.followup(createUserMessage({
+      content: [{ type: 'text', text: PROMPT }],
+      source: { kind: 'user' },
+    }))
+    await agentHandle.agent.whenIdle()
+
+    const requestHeader = agentHandle.agent.session.requestHeader()
+    if (requestHeader === undefined) throw new Error('the core Web agent issued no model request')
+
     const seedPath = join(scaffold.workspaceCwd, 'profile-smoke.txt')
     await writeFile(seedPath, 'CORE_WEB_EDITOR_OK\n')
     const signal = new AbortController().signal
@@ -60,7 +75,8 @@ describe('core Web profile', () => {
       .trimEnd()
 
     expect({
-      tools: scaffold.ctx.tools.schemas().map(tool => tool.name),
+      prompt: requestHeader.system,
+      tools: requestHeader.tools?.map(tool => tool.name),
       bash: text(bash),
       editor: text(editor),
     }).toMatchInlineSnapshot(`
@@ -69,16 +85,53 @@ describe('core Web profile', () => {
         "editor": "Here's the content of {{cwd}}/profile-smoke.txt with line numbers (which has a total of 2 lines):
            1  CORE_WEB_EDITOR_OK
            2",
+        "prompt": "You are a helpful software engineer assistant.",
         "tools": [
           "bash",
           "str_replace_editor",
         ],
       }
     `)
+    expect(requestHeader.tools).toEqual(scaffold.ctx.tools.schemas(agentHandle.agent))
 
     const entries = [...scaffold.ctx.loader.entries()]
     expect(entries.find(entry => entry.options.id === 'persistent-bash')?.fiber).toBeDefined()
     expect(entries.find(entry => entry.options.id === 'pty-local')?.fiber).toBeDefined()
     expect(entries.find(entry => entry.options.id === 'str-replace-editor')?.fiber).toBeDefined()
+    expect(entries.find(entry => entry.options.id === 'web-runtime')?.fiber).toBeDefined()
+    expect(entries.find(entry => entry.options.id === 'workspace-context')?.fiber).toBeUndefined()
+    await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl'])
+  })
+
+  it('uses DSH_SYSTEM_PROMPT as the complete prompt when configured', async () => {
+    const previous = process.env.DSH_SYSTEM_PROMPT
+    process.env.DSH_SYSTEM_PROMPT = 'RL prompt override'
+    let overrideScaffold: WebScaffold | undefined
+    let overrideAgent: AgentHandle | undefined
+    try {
+      overrideScaffold = await launchWebScaffold({ extraOverlayPath: CORE_WEB_OVERLAY, replayFixture: FIXTURE })
+      overrideAgent = await overrideScaffold.ctx.agents.create({
+        sessionId: SessionId('core-web-profile-override'),
+        meta: { cwd: overrideScaffold.workspaceCwd },
+        agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })
+      overrideAgent.agent.followup(createUserMessage({
+        content: [{ type: 'text', text: PROMPT }],
+        source: { kind: 'user' },
+      }))
+      await overrideAgent.agent.whenIdle()
+      expect(overrideAgent.agent.session.requestHeader()?.system).toBe('RL prompt override')
+    } finally {
+      try {
+        await overrideAgent?.dispose()
+      } finally {
+        try {
+          await overrideScaffold?.close()
+        } finally {
+          if (previous === undefined) Reflect.deleteProperty(process.env, 'DSH_SYSTEM_PROMPT')
+          else process.env.DSH_SYSTEM_PROMPT = previous
+        }
+      }
+    }
   })
 })
diff --git a/apps/web/tests/onboarding-deepseek-config.e2e.ts b/apps/web/tests/onboarding-deepseek-config.e2e.ts
index 51fa84af3d..85eb76e3e3 100644
--- a/apps/web/tests/onboarding-deepseek-config.e2e.ts
+++ b/apps/web/tests/onboarding-deepseek-config.e2e.ts
@@ -161,6 +161,58 @@ describe.skipIf(MODE === 'record')('web e2e: first-run DeepSeek credential setup
     expect(tripwire.pageErrors).toEqual([])
   }, 60_000)
 
+  it('never paints the takeover chrome on a configured reload, even with the settings join held open', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-configured-reload'))
+    // Regression pin for the reload white flash: both steps are satisfied
+    // (welcome acknowledged, credential configured), yet each must LOAD its
+    // private join before it can decide not to show. The chrome lives inside
+    // the step (OnboardingSurface), so the deciding window paints and blocks
+    // nothing. Holding settings.describe widens that window from loopback
+    // RTT scale to a deterministic hundreds of milliseconds, removing all
+    // timing dependence from the sampler assertions below.
+    //
+    // The sampler init script persists across this shared page's later
+    // navigations (init scripts re-run per navigation); that stays harmless
+    // because no later scenario in this file legitimately shows the
+    // takeover, and only this test reads __takeoverSightings.
+    await page.addInitScript(() => {
+      const sightings: string[] = []
+      ;(window as unknown as { __takeoverSightings: string[] }).__takeoverSightings = sightings
+      setInterval(() => {
+        if (document.querySelector('[class*="onboardingStage"], [class*="onboardingMask"]') !== null) {
+          sightings.push('chrome')
+        }
+        if (document.getElementById('root')?.inert === true) sightings.push('inert')
+      }, 8)
+    })
+    // EVERY settings.describe issued before the release is held — not just
+    // the first — so the pin cannot silently collapse back to loopback
+    // timing if a second boot-time consumer of the join ever appears.
+    let released = false
+    const heldRoutes: Array<() => void> = []
+    const releaseDescribe = (): void => {
+      released = true
+      for (const resolve of heldRoutes.splice(0)) resolve()
+    }
+    await page.route('**/api/settings.describe', async (route) => {
+      if (!released) await new Promise<void>((resolve) => { heldRoutes.push(resolve) })
+      await route.continue()
+    })
+    const warningsBefore = tripwire.warnings.length
+    await page.reload({ waitUntil: 'commit' })
+    await page.waitForSelector('[class*="frame"]', { timeout: 15_000 })
+    // The app is painted and interactive while the steps are still deciding.
+    await page.waitForTimeout(600)
+    releaseDescribe()
+    await page.waitForTimeout(400)
+    await page.unroute('**/api/settings.describe')
+    acknowledgeReloadConnectionLoss(tripwire, warningsBefore)
+    expect(await page.evaluate(() =>
+      (window as unknown as { __takeoverSightings: string[] }).__takeoverSightings)).toEqual([])
+    expect(await page.locator('[class*="onboardingStage"]').count()).toBe(0)
+    expect(tripwire.pageErrors).toEqual([])
+  }, 60_000)
+
   it('configures arbitrary DeepSeek models and prompts after the selected model is removed', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-onboarding-deepseek-models'))
     // Opened here rather than inherited: the credential test reloads the page
diff --git a/apps/web/tests/scaffold.ts b/apps/web/tests/scaffold.ts
index dc68cbf67d..c84b25a332 100644
--- a/apps/web/tests/scaffold.ts
+++ b/apps/web/tests/scaffold.ts
@@ -33,7 +33,13 @@ import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import Include, { type PatchOptions } from '@cordisjs/plugin-include'
 import { scrubRequestHeaders } from '@deepseek-ai/dsh-acp-snapshot'
-import { assertEntriesLoaded, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
+import {
+  addHarnessSourceSection,
+  assertEntriesLoaded,
+  composeEntries,
+  healProfilesModuleFallback,
+  loadOverlayPatches,
+} from '@deepseek-ai/dsh-app-boot'
 import { dshHomePath } from '@deepseek-ai/dsh-paths'
 import {
   WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION,
@@ -54,7 +60,6 @@ import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 // Empty type imports carry the httpServer/agents/sessionPersistence Context merges.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-agent'
-import { addHarnessSourceSection, healProfilesModuleFallback } from '@deepseek-ai/dsh-app-boot'
 import { REPO_ROOT, requireDist } from './support.ts'
 
 /** Snapshot mode for the lane, from $DSH_SNAPSHOT (same vocabulary as the other snapshot suites). */
@@ -252,6 +257,11 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
   const extraOverlayPatches = options.extraOverlayPath === undefined
     ? []
     : loadOverlayPatches('web e2e scaffold', options.extraOverlayPath)
+  const composedRows = composeEntries([basePatches, surfacePatches, extraOverlayPatches])
+  const webRuntimeConfig = composedRows.find(row => row.id === 'web-runtime')?.config as {
+    surfaceContext?: boolean
+  } | undefined
+  const surfaceContext = webRuntimeConfig?.surfaceContext !== false
   const patches: PatchOptions[] = [
     ...basePatches,
     ...surfacePatches,
@@ -290,7 +300,9 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     },
     // The bundle's web-runtime row resolves the same built dist under test
     // (apps/web IS @deepseek-ai/dsh-frontend); only the URL line is silenced.
-    { id: 'web-runtime', config: { mode: 'production', printUrl: false } },
+    // Preserve the composed surface-context choice because a patch replaces
+    // the row's complete config.
+    { id: 'web-runtime', config: { mode: 'production', printUrl: false, surfaceContext } },
     ...options.remoteAuthority === undefined
       ? []
       : [{ id: 'connection', config: { trustedHosts: [options.remoteAuthority] } }],
@@ -346,7 +358,9 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     // The shipped CLI deliberately has no dependency on this opt-in package.
     // Keep the Loader row real without broadening the product installation.
     if (options.cordisTools === true) ctx.loader.builtins['tool-cordis'] = ToolCordis
-    ctx.inject(['systemPrompt'], (promptCtx) => { addHarnessSourceSection(promptCtx, REPO_ROOT) })
+    if (surfaceContext) {
+      ctx.inject(['systemPrompt'], (promptCtx) => { addHarnessSourceSection(promptCtx, REPO_ROOT) })
+    }
     await ctx.loader.create({
       name: 'cordis:include',
       config: { path: pathToFileURL(rootConfig).href, patches },
diff --git a/apps/web/tests/search-card.snapshot.ts b/apps/web/tests/search-card.snapshot.ts
index 2f72c8275c..626be993a6 100644
--- a/apps/web/tests/search-card.snapshot.ts
+++ b/apps/web/tests/search-card.snapshot.ts
@@ -14,69 +14,19 @@
 // derivation over the result view, pinned at every render site by the
 // ui-conversation suite; here the fixture turn exercises the assembled card
 // shape and its cap.
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-library/react'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import type { WebBootEntry } from '@deepseek-ai/dsh-client-modules/client'
-import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
+import { act, fireEvent, screen, waitFor, within } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { hasClass, installAssembledBootEnv, mountAssembledApp, REFRESHING_GOLDEN } from './assembled-boot.ts'
 
 const EXPECTED = join(process.cwd(), 'apps/web/tests/snapshots/search-card/grep-card.expected.txt')
-const refreshing = process.env.DSH_SNAPSHOT === 'record' || process.env.DSH_SNAPSHOT === 'refresh'
 
-const PLUGINS: readonly (WebBootEntry & { dir: string })[] = [
-  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-locale', dir: 'locale', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
-  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
-  { id: '@deepseek-ai/dsh-client-ui-sidebar', dir: 'ui-sidebar', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
-  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
-  {
-    id: '@deepseek-ai/dsh-client-ui-workspace',
-    dir: 'ui-workspace',
-    url: '/plugins/ui-workspace.js',
-    rev: 'fx',
-    inject: [
-      '@deepseek-ai/dsh-client-runtime',
-      '@deepseek-ai/dsh-client-ui-conversation',
-      '@deepseek-ai/dsh-client-ui-sidebar',
-    ],
-  },
-  { id: '@deepseek-ai/dsh-client-ui-trajectory', dir: 'ui-trajectory', url: '/plugins/ui-trajectory.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
-]
-
-const bundles = new Map(PLUGINS.map(plugin => [
-  plugin.url,
-  readFileSync(join(process.cwd(), 'packages/client', plugin.dir, 'lib/client.js'), 'utf8'),
-]))
-
-interface FixtureWindow extends Window {
-  __DSH_BOOT__?: { rev: string; entries: WebBootEntry[] }
-  __ModuleLoader__?: unknown
-}
-
-class ResizeObserverStub {
-  observe(): void {}
-  disconnect(): void {}
-  unobserve(): void {}
-}
-
-const win = window as FixtureWindow
-let unmount: (() => void) | undefined
+installAssembledBootEnv()
 
 /** Normalize a rendered search card to a stable text shape: the kind, the banner
  *  summary, each file header (path + count), each visible match line, the expand
- *  control label, and the recovery footer. CSS-module class names carry a
- *  per-build hash in one of two schemes — ui-primitives emits `_<name>_<hash>`
- *  (name bounded by underscores), ui-conversation emits `<hash>_<name>` (name at
- *  the end). `hasClass` matches a module class by its logical name under either,
- *  without matching a longer name that contains it (`line` must not hit
- *  `lineNumber`). */
-function hasClass(el: Element, name: string): boolean {
-  return [...el.classList].some(cls => cls === name || cls.endsWith(`_${name}`) || cls.startsWith(`_${name}_`) || cls.includes(`_${name}_`))
-}
-
+ *  control label, and the recovery footer. */
 function cardShape(root: Element): string {
   const card = root.querySelector('[data-search]')
   if (card === null) return '<no search card>'
@@ -94,49 +44,9 @@ function cardShape(root: Element): string {
   return lines.join('\n')
 }
 
-beforeEach(() => {
-  localStorage.clear()
-  // English pinned before boot so the sidebar's role/text locators stay
-  // deterministic (the built-boot smoke's convention).
-  localStorage.setItem('dsh.locale', 'en')
-  document.title = 'DeepSeek Harness'
-  vi.stubGlobal('ResizeObserver', ResizeObserverStub)
-  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
-    setTimeout(() => { callback(0) }, 0) as unknown as number)
-  vi.stubGlobal('cancelAnimationFrame', (id: number) => { clearTimeout(id) })
-})
-
-afterEach(() => {
-  act(() => { unmount?.() })
-  unmount = undefined
-  cleanup()
-  delete win.__DSH_BOOT__
-  delete win.__ModuleLoader__
-  document.body.innerHTML = ''
-  document.head.querySelectorAll('style[data-plugin]').forEach((style) => { style.remove() })
-  document.title = ''
-  history.replaceState(null, '', '/')
-  vi.unstubAllGlobals()
-})
-
 describe('assembled search card', () => {
   it('renders the grep card, its truncation summary, and its capped head/tail slice from the built bundles', async () => {
-    history.replaceState(null, '', '/?fixture')
-    const root = document.createElement('div')
-    root.id = 'root'
-    document.body.appendChild(root)
-    win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ dir: _dir, ...plugin }) => plugin) }
-    act(() => {
-      const entry = new AppWebEntry(root, {
-        loadBundle: async (url) => {
-          const code = bundles.get(url)
-          if (code === undefined) throw new Error(`missing built bundle ${url}`)
-          ;(0, eval)(code)
-        },
-      })
-      void entry.run()
-      unmount = () => { entry.dispose() }
-    })
+    mountAssembledApp()
 
     const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 })
     fireEvent.click(await within(tree).findByText('Fixture 历史会话'))
@@ -161,7 +71,7 @@ describe('assembled search card', () => {
       expect(grepRow.querySelector('[data-search]')).not.toBeNull()
     }, { timeout: 10_000 })
     const shape = cardShape(grepRow)
-    if (refreshing) {
+    if (REFRESHING_GOLDEN) {
       mkdirSync(dirname(EXPECTED), { recursive: true })
       writeFileSync(EXPECTED, shape)
     }
diff --git a/apps/web/tests/snapshots/composer-tab-geometry/geometry.expected.md b/apps/web/tests/snapshots/composer-tab-geometry/geometry.expected.md
index b226cb845d..9735019508 100644
--- a/apps/web/tests/snapshots/composer-tab-geometry/geometry.expected.md
+++ b/apps/web/tests/snapshots/composer-tab-geometry/geometry.expected.md
@@ -2,7 +2,7 @@
 
 ## Wide viewport (1680px, card at its cap)
 
-- Chat: scrollbar-gutter stable, overflow auto/auto
+- Chat: scrollbar-gutter stable, overflow hidden/auto
 - Chat scroller scrolls: true
 - Chat reserved band: 8px
 - Trajectory: scrollbar-gutter stable, overflow hidden/auto
@@ -14,7 +14,7 @@
 
 ## Narrow viewport (800px, card shrinking with the column)
 
-- Chat: scrollbar-gutter stable, overflow auto/auto
+- Chat: scrollbar-gutter stable, overflow hidden/auto
 - Chat scroller scrolls: true
 - Chat reserved band: 8px
 - Trajectory: scrollbar-gutter stable, overflow hidden/auto
@@ -26,7 +26,7 @@
 
 ## Wide viewport, reservation removed in the page (control)
 
-- Chat: scrollbar-gutter auto, overflow auto/auto
+- Chat: scrollbar-gutter auto, overflow hidden/auto
 - Chat scroller scrolls: true
 - Chat reserved band: 8px
 - Trajectory: scrollbar-gutter auto, overflow hidden/hidden
diff --git a/apps/web/tests/snapshots/conversation-column-overflow/geometry.expected.md b/apps/web/tests/snapshots/conversation-column-overflow/geometry.expected.md
new file mode 100644
index 0000000000..f9c807b43e
--- /dev/null
+++ b/apps/web/tests/snapshots/conversation-column-overflow/geometry.expected.md
@@ -0,0 +1,9 @@
+# Conversation column horizontal overflow
+
+| viewport | overflow-x | glow bleeds past the column | scrollLeft after a horizontal wheel | scrolls vertically |
+| --- | --- | --- | --- | --- |
+| 1680px | hidden | false | 0px | true |
+| 1200px | hidden | true | 0px | true |
+| 1000px | hidden | true | 0px | true |
+| 800px | hidden | true | 0px | true |
+| 600px | hidden | true | 0px | true |
diff --git a/apps/web/tests/snapshots/core-web-profile/session.jsonl b/apps/web/tests/snapshots/core-web-profile/session.jsonl
new file mode 100644
index 0000000000..04f0d62d15
--- /dev/null
+++ b/apps/web/tests/snapshots/core-web-profile/session.jsonl
@@ -0,0 +1,7 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785974400000,"cwd":"{{cwd}}"}
+{"type":"user/message","seq":0,"time":1785974400001,"data":{"content":[{"type":"text","text":"Reply exactly CORE_WEB_REQUEST_OK and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"}},"surfaceOp":"append"}
+{"type":"assistant/chunk","seq":1,"time":1785974400002,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":2,"time":1785974400003,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"CORE_WEB_REQUEST_OK"}}}
+{"type":"assistant/chunk","seq":3,"time":1785974400004,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CORE_WEB_REQUEST_OK"}}}}
+{"type":"assistant/chunk","seq":4,"time":1785974400005,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":4}}}}
+{"type":"assistant/chunk","seq":5,"time":1785974400006,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
diff --git a/apps/web/tests/snapshots/todo-row/parallel-plan.expected.txt b/apps/web/tests/snapshots/todo-row/parallel-plan.expected.txt
new file mode 100644
index 0000000000..22c2ac777a
--- /dev/null
+++ b/apps/web/tests/snapshots/todo-row/parallel-plan.expected.txt
@@ -0,0 +1,9 @@
+row=todo_write
+title=Update to-do list
+summary=1/4 completed · 实现 fixture 样本
+suffix=+1
+panel=1 completed · 2 in progress · 1 pending
+item=completed 梳理需求
+item=in_progress 实现 fixture 样本
+item=in_progress 跑后台构建
+item=pending 浏览器验收
\ No newline at end of file
diff --git a/apps/web/tests/todo-row.snapshot.ts b/apps/web/tests/todo-row.snapshot.ts
new file mode 100644
index 0000000000..c05057dddc
--- /dev/null
+++ b/apps/web/tests/todo-row.snapshot.ts
@@ -0,0 +1,71 @@
+// @vitest-environment jsdom
+// Assembled todo snapshot: boots the real built `packages/client/*/lib/
+// client.js` bundles through AppWebEntry's ModuleLoader path against the
+// keyless FixtureApiClient transport, opens the fixture session, and pins the
+// two surfaces the fixture's parallel plan (turn 71, two items `in_progress`)
+// reaches — the `todo_write` tool row and the dock's plan strip.
+//
+// The row is pinned as three separate fields on purpose. `summary=` is the
+// ellipsized text and `suffix=` is ToolRow's non-shrinking `summarySuffix`
+// slot, so a regression that folds the `+N` count back into the summary string
+// changes this file even though the concatenated text would read the same; the
+// jsdom package suites bench over src and cannot see the bundled registration.
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fireEvent, screen, waitFor, within } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { hasClass, installAssembledBootEnv, mountAssembledApp, REFRESHING_GOLDEN } from './assembled-boot.ts'
+
+const EXPECTED = join(process.cwd(), 'apps/web/tests/snapshots/todo-row/parallel-plan.expected.txt')
+
+installAssembledBootEnv()
+
+/** Normalize the todo row and the plan strip to a stable text shape: the row's
+ *  title, its truncatable summary, its non-shrinking suffix, then the panel's
+ *  per-status header and every list item with its status. */
+function todoShape(row: Element, panel: Element): string {
+  const pick = (from: Element, name: string): Element[] =>
+    [...from.querySelectorAll('*')].filter(el => hasClass(el, name))
+  const first = (from: Element, name: string): string =>
+    pick(from, name)[0]?.textContent?.trim() ?? '<absent>'
+  const items = [...panel.querySelectorAll('[data-status]')]
+    .map(item => `item=${item.getAttribute('data-status')} ${item.textContent?.trim() ?? ''}`)
+  return [
+    `row=${row.getAttribute('data-tool')}`,
+    `title=${first(row, 'title')}`,
+    `summary=${first(row, 'summary')}`,
+    `suffix=${first(row, 'summarySuffix')}`,
+    `panel=${first(panel, 'progress')}`,
+    ...items,
+  ].join('\n')
+}
+
+describe('assembled todo surfaces', () => {
+  it('renders the parallel plan as a row summary, a separate active count, and the dock plan strip', async () => {
+    mountAssembledApp()
+
+    const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 })
+    fireEvent.click(await within(tree).findByText('Fixture 历史会话'))
+    // The todo turn is the fixture's last, so wait for its keyed row rather
+    // than for chat content in general.
+    const row = await waitFor(() => {
+      const found = document.querySelector('[data-tool="todo_write"]')
+      expect(found).not.toBeNull()
+      return found!
+    }, { timeout: 10_000 })
+    // The panel is the standing plan the turn's `todo/write` event feeds; it
+    // mounts above the composer, outside the row, and starts collapsed — its
+    // list only exists once expanded.
+    const panel = await screen.findByTestId('todo-panel', undefined, { timeout: 10_000 })
+    const toggle = panel.querySelector('button[aria-expanded]')
+    if (toggle === null) throw new Error('the plan strip must expose its expand toggle')
+    if (toggle.getAttribute('aria-expanded') === 'false') fireEvent.click(toggle)
+
+    const shape = todoShape(row, panel)
+    if (REFRESHING_GOLDEN) {
+      mkdirSync(dirname(EXPECTED), { recursive: true })
+      writeFileSync(EXPECTED, shape)
+    }
+    await expect(shape).toMatchFileSnapshot(EXPECTED)
+  })
+})
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
index dd5fe879e7..c181a2adb0 100644
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -44,6 +44,7 @@
     "tests/hmr-live.e2e.ts",
     "tests/seeded-history.e2e.ts",
     "tests/sidebar-scrollbar.e2e.ts",
+    "tests/conversation-column-overflow.e2e.ts",
     "tests/code-mode-round.e2e.ts",
     "tests/composer-draft-scroll.e2e.ts",
     "tests/cordis-tool-round.e2e.ts",
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 0459323eea..8daacae254 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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 docs/architecture.md
-architecture.md: 40c20a1c9eeabe5ecbbc6edacde81c20071b8a04
-architecture.zh.md: 6fddaa883775cf8345aba01af52575c0f0e1aaa0
+architecture.md: 81464d9c8800556565c84d33239882dc750180a8
+architecture.zh.md: c02bca4f12c3758723b0fc818c89080dccf435d9
diff --git a/docs/architecture.md b/docs/architecture.md
index 40c20a1c9e..81464d9c88 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -156,9 +156,9 @@ Streaming uses raw chunks and `BlockAssembler`. Each `LlmAdapter.stream()` is on
 
 A swappable capability usually has **interface / implementation / consumer** layers: service/events, backend, and model-facing tools/prompts. Bash is the reference; the [capability graph](capability-seams.md) maps each family.
 
-Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, or use ACP children ([subagent.md](core-data-structures/subagent.md)).
+Exceptions combine LLM interface/consumer, filesystem policy, web registries, and named skill/subagent providers. Subagents spawn fresh, fork a completed-turn prefix, use ACP children, or delegate one self-contained turn to a real product provider such as Codex ([subagent.md](core-data-structures/subagent.md)).
 
-`dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)). `dsh-paths` owns shared paths.
+`dsh-workspace-context` composes its baseline on the first `agent/pre-step` and folds it into the final entering batch right after the claimed prompt, so it reaches the first request with the direct prompt; rejection keeps it in the next-step inbox. When compaction removes that baseline from the visible surface, the next entering pre-step composes the current baseline and carries it in the same request. Filesystem changes projected after tools are likewise folded into the next entering pre-step instead of creating a later context-only step ([decision](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)). `dsh-paths` owns shared paths.
 
 ### Bundles And Apps
 
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 6fddaa8837..c02bca4f12 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -156,9 +156,9 @@ idle inject:
 
 可替换功能通常具有**接口／实现／消费方**三层：服务和事件、后端、面向模型的工具和提示词。Bash 是参考实现；[功能图](capability-seams.md)映射了每个包族。
 
-例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀，或使用 ACP（Agent Client Protocol）子 agent（[subagent.md](core-data-structures/subagent.md)）。
+例外情况包括 LLM（大语言模型）合并接口和消费方、文件系统整合策略、web 使用注册表、skill 和 subagent 使用具名提供方。subagent 可以通过 spawn 创建全新实例、fork 一个已完成轮次的前缀、使用 ACP（Agent Client Protocol）子 agent，或将一个独立完整的轮次委派给 Codex 等真实产品提供方（[subagent.md](core-data-structures/subagent.md)）。
 
-`dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
+`dsh-workspace-context` 在第一次 `agent/pre-step` 组合基线并将它折入最终进入的批次、紧随已领取的直接提示词之后，使其与直接提示词一同抵达第一次请求；reject 则将它留在 next-step inbox。当压缩从可见表层移除该基线时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中携带它。工具执行后投影的文件系统变更也会折入下一次进入步骤的 pre-step，而不会另外创建稍后的纯上下文步骤（[决策](../.agents/notes/implemented/feature/2026-06-24-workspace-context.md)）。`dsh-paths` 负责共享路径。
 
 ### 组合包与应用
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index cb24cee7d5..6a8f7943c2 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -103,6 +103,8 @@ flowchart LR
   pkg_bash_sandbox["bash-sandbox"]
   pkg_lsp_local["lsp-local"]
   pkg_subagent_acp["subagent-acp"]
+  pkg_subagent_codex["subagent-codex"]
+  pkg_subagent_claude_code["subagent-claude-code"]
   pkg_bash["bash"]
   svc_bash["ctx.bash<br/>Bash executor seam"]
   pkg_pwsh_local["pwsh-local"]
@@ -135,6 +137,7 @@ flowchart LR
   svc_subagents["ctx.subagents<br/>Subagent provider and continuation service"]
   pkg_subagent_spawn["subagent-spawn"]
   pkg_subagent_fork["subagent-fork"]
+  pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
   pkg_tool_subagent_control["tool-subagent-control"]
   pkg_tool_ralph["tool-ralph"]
   pkg_tasks["tasks"]
@@ -228,6 +231,9 @@ flowchart LR
   pkg_storage_sqlite --> svc_storage
   pkg_subagent --> svc_subagents
   pkg_subagent_acp --> svc_subagents
+  pkg_subagent_claude_code --> svc_subagents
+  pkg_subagent_codex --> svc_subagents
+  pkg_subagent_dsh_sdk --> svc_subagents
   pkg_subagent_fork --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_subprocess --> svc_subprocess
@@ -318,6 +324,8 @@ flowchart LR
   svc_subprocess --> pkg_bash_sandbox
   svc_subprocess --> pkg_lsp_local
   svc_subprocess --> pkg_subagent_acp
+  svc_subprocess --> pkg_subagent_claude_code
+  svc_subprocess --> pkg_subagent_codex
   svc_systemPrompt --> pkg_agent_loop
   svc_systemPrompt --> pkg_tool_fs
   svc_systemPrompt --> pkg_tool_pty
@@ -377,7 +385,7 @@ flowchart LR
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
-| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp) | - | The bash executors, the LSP host, and the ACP subagent backend spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation. |
+| `ctx.subprocess` | `seam` | [`subprocess`](../packages/subprocess/subprocess) | [`subprocess-local`](../packages/subprocess/subprocess-local) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`lsp-local`](../packages/lsp/lsp-local), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | - | The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox), [`pwsh-local`](../packages/bash/pwsh-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them. |
 | `ctx.bashEnv` | `core` | [`bash-env`](../packages/bash/bash-env) | - | [`tool-bash`](../packages/bash/tool-bash), [`tool-pwsh`](../packages/bash/tool-pwsh) | - | Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace. |
 | `ctx.pty` | `seam` | [`pty`](../packages/pty/pty) | [`pty-local`](../packages/pty/pty-local) | [`tool-pty`](../packages/pty/tool-pty) | - | The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface. |
@@ -388,7 +396,7 @@ flowchart LR
 | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode). |
 | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate. |
 | `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred. |
-| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
+| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn), [`subagent-fork`](../packages/subagent/subagent-fork), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/workflow/tool-ralph) | - | Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route. |
 | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash), [`tool-pty`](../packages/pty/tool-pty), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-tasks`](../packages/tasks/tool-tasks) | - | Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry. |
 | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa), [`web-search-perplexity`](../packages/web/web-search-perplexity), [`web-search-deepseek`](../packages/web/web-search-deepseek), [`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names. |
 | `ctx.spillStore` | `seam` | [`spill`](../packages/spill/spill) | [`spill-local`](../packages/spill/spill-local) | [`spill-policy`](../packages/spill/spill-policy) | - | The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 0963f4d490..ad27aac3b9 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -223,7 +223,7 @@ export interface Config {
   maxOutputBytes?: number
   /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
   maxSpillBytes?: number
-  /** Grace period for kill escalation and for inherited pipes after shell exit. */
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
   graceMs?: number
 }
 ```
@@ -1065,7 +1065,7 @@ export interface Config {
   maxOutputBytes?: number
   /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
   maxSpillBytes?: number
-  /** Grace period for kill escalation and for inherited pipes after shell exit. */
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
   graceMs?: number
   /**
    * Explicit pwsh executable. When omitted, well-known Windows install
@@ -1628,10 +1628,11 @@ export interface Config {
   /**
    * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
    * window to flush persistence and tear down its own nested subprocesses
-   * before the parent escalates to a signal.
+   * before the parent escalates to a signal. Must not exceed
+   * `MAX_TIMER_DELAY_MS`.
    */
   disposeEofGraceMs?: number
-  /** Termination confirmation window (ms), including forced exit on every platform. */
+  /** Termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */
   disposeGraceMs?: number
 }
 
@@ -1639,7 +1640,45 @@ export interface Config {
 export type PermissionPolicy = 'allow' | 'reject'
 ```
 
-Source: [`packages/subagent/subagent-acp/src/index.ts:26`](../packages/subagent/subagent-acp/src/index.ts)
+Source: [`packages/subagent/subagent-acp/src/index.ts:27`](../packages/subagent/subagent-acp/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-claude-code`
+
+Requires: `subagents` · `subprocess`
+
+```ts config-catalog
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for Claude Code process-tree termination. */
+  disposeGraceMs?: number
+}
+```
+
+Source: [`packages/subagent/subagent-claude-code/src/index.ts:32`](../packages/subagent/subagent-claude-code/src/index.ts)
+
+## `@deepseek-ai/dsh-subagent-codex`
+
+Requires: `subagents` · `subprocess`
+
+```ts config-catalog
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for app-server process-tree termination. */
+  disposeGraceMs?: number
+}
+```
+
+Source: [`packages/subagent/subagent-codex/src/index.ts:30`](../packages/subagent/subagent-codex/src/index.ts)
 
 ## `@deepseek-ai/dsh-subagent-dsh-sdk`
 
@@ -1873,7 +1912,7 @@ export interface Config {
   searchMetaMaxBytes?: number
   /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
   rawOutputMaxBytes?: number
-  /** Terminate-escalation grace period (ms) for one search process, handed to the subprocess seam. */
+  /** Terminate-escalation grace (ms), handed to the subprocess seam and bounded by `MAX_TIMER_DELAY_MS`. */
   graceMs?: number
   /** Max bytes retained for one search's stderr tail; the excerpt is embedded in `SEARCH_*` error messages, never shown on success. */
   stderrMaxBytes?: number
@@ -1882,7 +1921,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/fs/tool-fs-search/src/index.ts:72`](../packages/fs/tool-fs-search/src/index.ts)
+Source: [`packages/fs/tool-fs-search/src/index.ts:73`](../packages/fs/tool-fs-search/src/index.ts)
 
 ## `@deepseek-ai/dsh-tool-goal`
 
@@ -2063,8 +2102,8 @@ export interface Config {
    * requires the provider's `depthLimit` capability (mount fails loud
    * otherwise). The provider checks the calling agent's current depth at every
    * start; the tool remains model-visible so runtime policy owns rejection.
-   * `'provider-managed'` is for an out-of-process provider (ACP) whose
-   * recursion budget belongs to the child harness's own deployment.
+   * `'provider-managed'` is for an out-of-process provider whose recursion
+   * budget belongs to the child runtime or its own deployment.
    */
   maxDepth?: number | 'provider-managed'
 }
@@ -2109,6 +2148,26 @@ export interface Config {
 
 Source: [`packages/tasks/tool-tasks/src/index.ts:23`](../packages/tasks/tool-tasks/src/index.ts)
 
+## `@deepseek-ai/dsh-tool-todo`
+
+Requires: `tools`
+
+```ts config-catalog
+/** Model-facing todo tool configuration. */
+export interface Config {
+  /**
+   * Required deployment choice for whether several todos may be `in_progress` at once. True suits
+   * agents that run work concurrently — subagents, background commands, workflow fan-out — and the
+   * description then instructs the model to mark every actively worked task. False restores the
+   * single-active discipline: the description asks for exactly one, and a call marking more is
+   * rejected.
+   */
+  allowParallelInProgress: boolean
+}
+```
+
+Source: [`packages/todo/tool-todo/src/index.ts:29`](../packages/todo/tool-todo/src/index.ts)
+
 ## `@deepseek-ai/dsh-tool-web`
 
 Requires: `tools` · `web` · `systemPrompt`
@@ -2423,7 +2482,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/context/workspace-context/src/config.ts:17`](../packages/context/workspace-context/src/config.ts)
+Source: [`packages/context/workspace-context/src/config.ts:18`](../packages/context/workspace-context/src/config.ts)
 
 ## Loadable plugins with no config
 
@@ -2471,7 +2530,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
 - `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
 - `@deepseek-ai/dsh-tool-subagent-control` — requires `tools` · `subagents` ([`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts))
-- `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts))
 - `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
 - `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
 - `@deepseek-ai/dsh-workspace` — requires `storageDomain` · `sessionPersistence` ([`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts))
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index 079bb5b3f1..acc8597d68 100644
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.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 docs/cookbook/extension-cookbook.md
-extension-cookbook.md: 1d5705672396d66d5625567aefec5006ae126e67
-extension-cookbook.zh.md: 2f8e0ccb745baefb857f1065040f3225142d264f
+extension-cookbook.md: 26f20b8f6cb57103b8e7340fcd21089ff1b0e5f6
+extension-cookbook.zh.md: b8bafdb73e91b56dd411cc5e96c21ccf2c5db123
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index 1d57056723..26f20b8f6c 100644
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -117,7 +117,7 @@ Every product feature maps to a listener on a documented extension seam — the
 | Subprocess sandbox (landlock / sandbox-exec) | use a `ctx.sandbox` backend through `dsh-bash-sandbox`; use `tools/pre-execute` for capability-level denial |
 | Permission system / AskUserQuestion | return `ask` from `tools/pre-execute` and answer through `ctx.approval`; register a separate model-facing ask tool for ordinary user questions |
 | Plan mode | Shipped: [`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — logged `plan/mode` state, the `plan:policy` guidance section, `/plan [message]` entry, `/plan off` direct exit, and the user-reviewed `exit_plan_mode` exit; enforcement stays on the independent sandbox/approval axes |
-| Sub-agent delegation | the `ctx.subagents` provider registry (`dsh-subagent-spawn`/`-fork`/`-acp`) + `dsh-tool-subagent` exposing one configured provider to the model |
+| Sub-agent delegation | the `ctx.subagents` provider registry (`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`) + `dsh-tool-subagent` exposing one configured provider to the model |
 | MCP | one plugin per server: discover tools → `ctx.tools.register()` |
 | Skills | section + tool registration; `inject()` skill content on invocation |
 | Memory | section provider + tool |
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index 2f8e0ccb74..b8bafdb73e 100644
--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -117,7 +117,7 @@ export function apply(ctx: Context) {
 | 子进程沙箱（landlock / sandbox-exec） | 通过 `dsh-bash-sandbox` 使用 `ctx.sandbox` 后端；能力级别的拒绝使用 `tools/pre-execute` |
 | 权限系统 / AskUserQuestion | 从 `tools/pre-execute` 返回 `ask` 并通过 `ctx.approval` 应答；为普通用户提问注册一个独立的面向模型的 ask 工具 |
 | Plan mode | 已交付：[`@deepseek-ai/dsh-plan-mode`](../../packages/plan/plan-mode/README.md) — 落日志的 `plan/mode` 状态、`plan:policy` 引导段、`/plan [message]` 入口、`/plan off` 直接退出，以及经用户评审的 `exit_plan_mode` 出口；强制约束留在独立的沙箱/审批轴上 |
-| 子 agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
+| 子 agent 委派 | `ctx.subagents` 提供方注册表（`dsh-subagent-spawn`/`-fork`/`-acp`/`-codex`/`-claude-code`/`-dsh-sdk`）+ `dsh-tool-subagent` 向模型暴露一个已配置的提供方 |
 | MCP | 每个服务器一个插件：发现工具 → `ctx.tools.register()` |
 | Skill（技能） | section + 工具注册；调用时通过 `inject()` 注入 skill 内容 |
 | 记忆 | section provider + 工具 |
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 44a44a139e..2ded3e4f07 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -2099,22 +2099,32 @@ registerContinuableSetup(contribution: ContinuableSetupContribution): () => void
 async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
 
 /**
- * Enumerate the parent's direct session-backed subagents from the
- * live-preferred session corpus without loading or resuming an Agent. Session
- * query supplies lineage, candidate order, event reads, and live state; this
- * service interprets descriptor mode, activity, and per-child diagnostics
- * without consulting Agent registrations, Activations, or providers.
+ * Enumerate the parent's direct session-backed subagents without loading or
+ * resuming an Agent and without any query seam: the listing merges the live
+ * session store with optional session persistence (live-preferred) and
+ * serves each child's durable mode/label from the registered `subagent`
+ * projection unit down a three-rung ladder — the registry's watermark
+ * snapshot for a live child; for a cold one, a durable projection-cache
+ * row when the optional cache serves an own-suffix identity (its `seq`
+ * gate proves the value postdates the fork seed, where a child's own
+ * descriptor is immutable once appended), else one persistence inspection
+ * folded through the registry. The
+ * projection fold is the single classification authority; per-child
+ * diagnostics relay a fold that served no identity or a failed inspection,
+ * never a list-time descriptor parse. Absent persistence, enumeration is
+ * live-only (a cold child cannot be resumed then either, so its absence is
+ * capability absence, not an error). This service consults no Agent
+ * registrations, Activations, or providers.
  *
- * The trace and exact descriptor read receive `signal`; the full event-list
- * read has no signal parameter, so the scan rechecks cancellation around
- * every await and between candidates. Query rejections that settle after an
- * abort become a stable `SubagentError` with code `CANCELLED`.
+ * Every persistence read receives `signal`, and the listing rechecks
+ * cancellation around each of those awaits. Read rejections that settle
+ * after an abort become a stable `SubagentError` with code `CANCELLED`.
  * @param parentSessionId - parent session whose direct children are listed.
- * @param signal - caller-owned cancellation forwarded where supported and
- *   observed around every query await.
- * @returns children and per-child diagnostics in stable trace order.
- * @throws {@link SubagentError} when session query is unavailable or the
- *   caller cancels the scan.
+ * @param signal - caller-owned cancellation forwarded to persistence reads
+ *   and observed around every read await.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
  */
 listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>
 
diff --git a/docs/core-data-structures/session.i18n.yaml b/docs/core-data-structures/session.i18n.yaml
index 87f705345c..78626957f6 100644
--- a/docs/core-data-structures/session.i18n.yaml
+++ b/docs/core-data-structures/session.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 docs/core-data-structures/session.md
-session.md: fac201b581e395865fd46d51bca1350cbbc46e8e
-session.zh.md: 53dc9d11de895deec72aaf5ea81c70ba87c9c6bd
+session.md: fb04ff3eb3c15d1f3c923ee73d4ba19537d36f11
+session.zh.md: 138159d97a5c368f28821715512632e0ca95b29e
diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md
index fac201b581..fb04ff3eb3 100644
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -144,7 +144,7 @@ The unit of the `todo/write` event's whole-list snapshot. Deliberately minimal 
 interface TodoItem {
   /** What this task is — a short imperative line shown in the UI. */
   content: string
-  /** Lifecycle state. `in_progress` marks the single task being worked now. */
+  /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
   status: 'pending' | 'in_progress' | 'completed'
 }
 ```
diff --git a/docs/core-data-structures/session.zh.md b/docs/core-data-structures/session.zh.md
index 53dc9d11de..138159d97a 100644
--- a/docs/core-data-structures/session.zh.md
+++ b/docs/core-data-structures/session.zh.md
@@ -144,7 +144,7 @@ interface SessionEventMap {
 interface TodoItem {
   /** What this task is — a short imperative line shown in the UI. */
   content: string
-  /** Lifecycle state. `in_progress` marks the single task being worked now. */
+  /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
   status: 'pending' | 'in_progress' | 'completed'
 }
 ```
diff --git a/docs/core-data-structures/subagent.i18n.yaml b/docs/core-data-structures/subagent.i18n.yaml
index a449388c60..eb708f33da 100644
--- a/docs/core-data-structures/subagent.i18n.yaml
+++ b/docs/core-data-structures/subagent.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 docs/core-data-structures/subagent.md
-subagent.md: 956b47cfa85efe7826fbde47d4405d20a6abed6c
-subagent.zh.md: 467fcd35bcde5fd01a2e18efbad862c72d7a4253
+subagent.md: 4d7552eb5749284d90e31e62d8ac02e3d7a21b1d
+subagent.zh.md: ebcb1ce445c164352109d6613028c7a36c10d6d4
diff --git a/docs/core-data-structures/subagent.md b/docs/core-data-structures/subagent.md
index 956b47cfa8..4d7552eb57 100644
--- a/docs/core-data-structures/subagent.md
+++ b/docs/core-data-structures/subagent.md
@@ -4,7 +4,7 @@ English | [中文](subagent.zh.md)
 
 The subagent seam — an agent delegating work to a child agent. Like [bash](bash.md) it is **one optional capability**, not part of the agent-loop spine, so its vocabulary lives here rather than in [core.md](core.md). But it differs from every other seam on one axis: **multiple provider implementations coexist** in one context, registered by name (`ctx.subagents`), where bash allows only one executor. The registry shape mirrors the [LLM adapter registry](llm-streaming.md), not the single-service bash executor.
 
-Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message` and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only direct-child discovery through optional session query. The rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
+Interface: [dsh-subagent](../../packages/subagent/subagent) (`ctx.subagents` + the vocabulary below). Implementations are sibling packages (`dsh-subagent-spawn`, `-fork`, `-acp`, `-codex`, `-claude-code`, `-dsh-sdk`); the model-facing consumers are [dsh-tool-subagent](../../packages/subagent/tool-subagent) (per-provider delegation), [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) (the optional global `send_message` and `list_agents` controls), and [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report) (the optional child-scoped `report` return channel). The same `ctx.subagents` service owns continuable-child orchestration through an internal activation manager and read-only direct-child discovery straight from the session store and optional session persistence. Product-provider rationale lives in [the Codex and Claude Code Agent Note](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md); common-seam rationale lives in [the subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), [the continuable subagents Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md), [the report-tool Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md), [the durable catalog Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md), and [the merged-service Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md).
 
 Sources: [`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts), [`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts), and [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
@@ -248,11 +248,11 @@ interface ContinuableCreateSpec {
 
 The descriptor (`SubagentDescriptorData` in [descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts)) is a mode-discriminated durable identity for every session-backed subagent. Both modes carry the provider name. A `one-shot` descriptor optionally carries a caller-owned display `label`; a `continuable` descriptor requires the delegation `description` as its durable creation label and additionally snapshots resolved child `agentOptions.provider`/`model` and optional `persona`/`toolFilter` for cold resume. It never snapshots the merge-extensible `AgentOptions` object, so an unrelated extension value cannot break continuation and a later composition input is a deliberate version change. It omits `subagentDepth` (cold resume trusts the persisted header's `delegationDepth` as the monotone floor) and `outputSchema` (one run or Activation's result contract, not durable identity).
 
-A local one-shot provider appends the descriptor inside the child's initial turn before its first request. The continuation manager appends the descriptor after any provider-supplied lineage and before the initial prompt is admitted; `header.seedLength` remains the fork-lineage boundary, so descriptor lookup reads the child's own suffix. The event is log-only: no `surfaceOp`, never in model history, and retained across compaction by the append-only log. Malformed current-version descriptors are corrupt; unsupported versions cannot be classified by this runtime.
+A local one-shot provider appends the descriptor inside the child's initial turn before its first request. The continuation manager appends the descriptor after any provider-supplied lineage and before the initial prompt is admitted; `header.seedLength` remains the fork-lineage boundary: resume-time descriptor authority reads the child's own suffix, while the list-serving identity projection folds `subagent/descriptor` last-wins so the child's own descriptor overrides a fork-seeded ancestor's. The event is log-only: no `surfaceOp`, never in model history, and retained across compaction by the append-only log. Malformed current-version descriptors are corrupt; unsupported versions cannot be classified by this runtime.
 
 ## Durable enumeration: `listChildren()` and `SubagentListEntry`
 
-`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from one `ctx.sessionQuery.traceSession()` observation, without loading or resuming any Agent. Session lineage is broader than subagent identity — ordinary forks share `parentSession` — so exactly one supported `subagent/descriptor` event in the child's own suffix (after `seedLength`, so a fork seed cannot leak an ancestor's descriptor) is the sole subagent discriminator. `SessionHeader.origin: 'subagent'` is only a coarse product-navigation classifier stamped before publication; it can suppress duplicate sidebar rows but cannot establish a valid descriptor, resumability, or authorization. The result is one `SubagentListEntry[]` in the trace's `createdAt`-then-id candidate order: a valid descriptor yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A per-child inspection failure yields a `diagnostic` entry (`corrupt`, `unsupported`, or `unavailable`) so one damaged sibling cannot hide healthy children; a missing descriptor yields no entry. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and maps activity to its existing `running`/`complete` vocabulary. A failure while building the initial trace fails the whole call — per-child isolation begins only after a trustworthy candidate set exists. The service keeps `sessionQuery` optional for by-id continuation: `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` when it is absent, while the list tool requires `ctx.subagents` and `ctx.sessionQuery` at plugin load. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict.
+`SubagentService.listChildren(parentSessionId)` enumerates the parent's direct session-backed subagents from the live-preferred merge of `ctx.sessions.list()` and optional `ctx.sessionPersistence.list()` — no query seam, and no Agent is loaded or resumed. Candidates are the direct children whose durable header carries `origin: 'subagent'`; the marker classifies enumeration and coarse generic-route denial but cannot establish a valid descriptor, resumability, or authorization — the projection fold owns identity, and the Activation contract owns resume. Each row's `mode`/`label` is the registered `subagent` projection unit's value, served through a three-rung ladder: the registry's watermark cache for a live child (zero log reads); the optional projection checkpoint cache for a cold one (`cachedSnapshot` — an identity passing the own-suffix seq gate is final, because an own descriptor is immutable once appended); otherwise one `persistence.inspect()` reading folded through the registry (bounded concurrency, recomputed per listing). The cache is a pure optional accelerator: absent, serving the `null` sentinel or missing the key, failing the seq gate, or faulting, it falls silently through to the authoritative refold. The fold is `subagent/descriptor` last-wins with no failure channel: the child's own descriptor overrides a fork-seeded ancestor's, and a malformed or unknown-version payload folds to a serializable `null` sentinel, treated as no value. The result is one `SubagentListEntry[]` in `createdAt`-then-id order: a served identity yields a `child` entry with `mode: 'one-shot' | 'continuable'` and `activity: 'running' | 'inactive'`; continuable entries always carry `label`, while one-shot entries carry it only when the start caller supplied presentation metadata. A settled candidate whose fold served no identity yields a `corrupt` diagnostic — missing, malformed, and unknown-version descriptors deliberately undistinguished, with `unsupported` kept in the type for consumers already routing on it but no longer produced; a running candidate without an identity is omitted (the creation window before its descriptor lands); a failed cold inspection yields one `unavailable` diagnostic retried on the next listing, so one damaged sibling cannot hide healthy children. `hasChildren` marks a direct descendant with durable subagent origin, read from the same merged material. Activity snapshots only whether the logical record is live in `ctx.sessions`, not outcome or resumability. Absent persistence, enumeration is live-only rather than an error — a cold child cannot be resumed then either. `listChildren()` throws `SubagentError` with code `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` when the `ctx.sessionProjections` registry is absent and `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` when the session store is, both checked before any read so a deployment with zero children still fails deterministically; the list tool requires `ctx.subagents` at plugin load. A service consumer such as a UI can display both modes and choose an unlabeled one-shot fallback, while the model-facing `list_agents` adapter (the separately loadable `/list-agents` plugin of [dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)) keeps only continuable entries and maps activity to its existing `running`/`complete` vocabulary. Listing does not consult the continuation manager's Activation map, Agent registry, or provider availability; `send_message` remains the authoritative delivery-time operation, and a listed running continuable child may still reject delivery as an ownership conflict. The read-path rationale lives in [the list-identity-projection Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md).
 
 ## The terminal result: `SubagentResult`
 
@@ -344,7 +344,7 @@ interface SubagentRun {
 }
 ```
 
-A local one-shot run MUST publish an ordinary child agent/session before `start()` fulfills, return that child session id as `SubagentRun.id`, expose the exact child as `localAgent`, record `request.parent.session.id` in the child's `parentSession` header, and append the resolved descriptor inside the child's initial turn before its first request. Runtime ownership may place the child under the parent, provider, or root scope. A remote provider instead returns a parent-scoped lifecycle id and `localAgent: undefined`; without a local child Session, it is absent from trace-backed enumeration.
+A local one-shot run MUST publish an ordinary child agent/session before `start()` fulfills, return that child session id as `SubagentRun.id`, expose the exact child as `localAgent`, record `request.parent.session.id` in the child's `parentSession` header, and append the resolved descriptor inside the child's initial turn before its first request. Runtime ownership may place the child under the parent, provider, or root scope. A remote provider instead returns a parent-scoped lifecycle id and `localAgent: undefined`; without a local child Session, it is absent from durable enumeration.
 
 ## The provider seam: `SubagentProvider`
 
diff --git a/docs/core-data-structures/subagent.zh.md b/docs/core-data-structures/subagent.zh.md
index 467fcd35bc..ebcb1ce445 100644
--- a/docs/core-data-structures/subagent.zh.md
+++ b/docs/core-data-structures/subagent.zh.md
@@ -4,7 +4,7 @@
 
 subagent seam：一个 agent（智能体）将工作委派给子 agent。与 [bash](bash.md) 一样，它是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此而非 [core.md](core.md) 中。但它在一个维度上与其他所有 seam 不同：**同一上下文中可共存多个提供方实现**，按名称注册（`ctx.subagents`），而 bash 只允许一个执行器。注册表的形状参照 [LLM（大语言模型）适配器注册表](llm-streaming.md)，而非单服务的 bash 执行器。
 
-接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为三个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并通过可选的会话查询负责只读的直接 child 发现。设计理由见 [subagent Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
+接口：[dsh-subagent](../../packages/subagent/subagent)（`ctx.subagents` + 下文词汇）。实现为六个兄弟包（package）：`dsh-subagent-spawn`、`-fork`、`-acp`、`-codex`、`-claude-code`、`-dsh-sdk`；面向模型的消费方包括 [dsh-tool-subagent](../../packages/subagent/tool-subagent)（按提供方委派）、[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control)（可选的全局 `send_message` 与 `list_agents` 控制工具）和 [dsh-tool-subagent-report](../../packages/subagent/tool-subagent-report)（可选的 child 作用域 `report` 返回通道）。同一个 `ctx.subagents` 服务通过内部激活管理器负责可继续子 agent 编排，并直接从会话存储与可选的会话持久化负责只读的直接 child 发现。产品提供方设计理由见 [Codex 与 Claude Code Agent Note（agent 决策记录）](../../.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md)；通用 seam 的设计理由见 [subagent Agent Note](../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)、[可继续 subagent Agent Note](../../.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md)、[report 工具 Agent Note](../../.agents/notes/implemented/feature/2026-07-30-continuable-subagent-report-tool.md)、[持久化目录 Agent Note](../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)和[服务合并 Agent Note](../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)。
 
 源码：[`packages/subagent/subagent/src/types.ts`](../../packages/subagent/subagent/src/types.ts)、[`packages/subagent/subagent/src/index.ts`](../../packages/subagent/subagent/src/index.ts)和 [`packages/subagent/subagent/src/continuation.ts`](../../packages/subagent/subagent/src/continuation.ts)
 
@@ -248,11 +248,11 @@ interface ContinuableCreateSpec {
 
 描述符（[descriptor.ts](../../packages/subagent/subagent/src/descriptor.ts) 中的 `SubagentDescriptorData`）是每个由会话支撑的 subagent 所使用、按模式判别的持久化身份。两种模式都携带提供方名称。`one-shot` 描述符可以携带调用方拥有的可选显示 `label`；`continuable` 描述符要求以委派 `description` 作为持久化创建标签，并另外对已解析的子 agent `agentOptions.provider`／`model` 与可选的 `persona`／`toolFilter` 建立快照，用于冷恢复。它绝不会对可合并扩展的 `AgentOptions` 对象建立快照，因此无关的扩展值不会破坏继续执行，后续新增组合配置输入则是一次有意的版本更改。描述符省略 `subagentDepth`（冷恢复以持久化 header 中的 `delegationDepth` 作为单调下界）和 `outputSchema`（单次运行或 Activation 的结果契约，而非持久化身份）。
 
-本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界，因此描述符查找会读取子 agent 自身的后缀。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
+本地一次性提供方会在子 agent 的初始轮次内、首次请求前追加描述符。继续执行管理器会在任何提供方提供的谱系之后、初始 prompt 获准之前追加描述符；`header.seedLength` 仍是 fork 谱系边界：恢复时的描述符权威读取子 agent 自身的后缀，而供列表使用的身份投影以 last-wins 折叠 `subagent/descriptor`，子 agent 自己的描述符会覆盖 fork seed 中祖先的描述符。该事件只进入日志：不含 `surfaceOp`，绝不进入模型历史，并由仅追加日志跨压缩保留。格式错误的当前版本描述符属于损坏；本运行时无法对不受支持的版本进行分类。
 
 ## 持久化枚举：`listChildren()` 与 `SubagentListEntry`
 
-`SubagentService.listChildren(parentSessionId)` 从一次 `ctx.sessionQuery.traceSession()` 观测中枚举 parent 直接且由会话支撑的 subagent，而不会加载或恢复任何 Agent。会话谱系的范围比 subagent 身份更广——普通 fork 也会共享 `parentSession`——因此，child 自身后缀中恰好一个受支持的 `subagent/descriptor` 事件（位于 `seedLength` 之后，避免 fork seed 泄漏祖先描述符）是唯一的 subagent 判别信息。`SessionHeader.origin: 'subagent'` 只是在发布前写入的粗粒度产品导航分类器；它可以隐藏重复的侧边栏行，却不能证明描述符有效、child 可恢复或操作已获授权。结果是一个按追踪结果中 `createdAt`、再按 id 排列候选顺序的 `SubagentListEntry[]`：有效描述符生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。逐 child 检查失败生成 `diagnostic` 条目（`corrupt`、`unsupported` 或 `unavailable`），因此一个损坏的 sibling 不会隐藏健康 child；缺少描述符则不生成条目。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并将活动状态映射到现有的 `running`／`complete` 词汇。构建初始追踪时的失败会让整个调用失败——只有得到可信候选集后才开始逐 child 隔离。服务将 `sessionQuery` 保持为按 id 继续执行时的可选依赖：缺少该服务时，`listChildren()` 抛出 `SubagentError`，并携带错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`；列表工具则在插件加载时要求 `ctx.subagents` 与 `ctx.sessionQuery`。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。
+`SubagentService.listChildren(parentSessionId)` 从 `ctx.sessions.list()` 与可选 `ctx.sessionPersistence.list()` 的实时优先合并中枚举 parent 直接且由会话支撑的 subagent——不经查询 seam，也不会加载或恢复任何 Agent。候选是持久 header 携带 `origin: 'subagent'` 的直接 child；该标记只负责枚举分类与粗粒度的通用路由拒绝，不能证明描述符有效、child 可恢复或操作已获授权——身份由投影折叠负责，恢复由 Activation 契约负责。每行的 `mode`／`label` 是已注册 `subagent` projection unit 的值，经三级阶梯供值：存活 child 由注册表水位缓存供值（零日志读取）；冷 child 先读可选的投影 checkpoint 缓存（`cachedSnapshot`——过 own-suffix seq 门的身份即定值，own descriptor 一经追加不可变）；否则在一次 `persistence.inspect()` 读取上经注册表折叠（有界并发，每次列表重新计算）。该缓存是纯可选加速层：服务缺席、行里是 `null` 哨兵或 key 缺席、seq 门不过、读取出错，都静默落到权威重折。折叠规则是 `subagent/descriptor` last-wins 且没有失败通道：子 agent 自己的描述符覆盖 fork seed 中祖先的描述符，格式错误或版本不认识的载荷折叠为可序列化的 `null` 哨兵，视同无值。结果是按 `createdAt`、再按 id 排序的 `SubagentListEntry[]`：取到身份即生成带有 `mode: 'one-shot' | 'continuable'` 和 `activity: 'running' | 'inactive'` 的 `child` 条目；可继续条目始终携带 `label`，一次性条目则只在启动调用方提供展示元数据时携带该字段。已定局而折叠无身份的候选生成 `corrupt` diagnostic——缺失、格式错误与版本不认识的描述符有意不再细分，`unsupported` 为已按其路由的消费方保留在类型中但不再产出；运行中而无身份的候选被省略（描述符落盘前的创建窗口）；冷检查失败生成一条 `unavailable` diagnostic 并在下次列表自然重试，因此一个损坏的 sibling 不会隐藏健康 child。`hasChildren` 标记存在持久 subagent origin 的直接后代，读取自同一份合并材料。活动状态只表示逻辑记录是否在 `ctx.sessions` 中存活，而不表示结果或可恢复性。缺少持久化时，枚举退化为仅存活枚举而不是报错——此时冷 child 本就无法恢复。缺少 `ctx.sessionProjections` 注册表时，`listChildren()` 抛出携带错误码 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 的 `SubagentError`，缺少会话存储时则抛出 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`，两者都在任何读取之前检查，因此零 child 的部署同样确定失败；列表工具在插件加载时只要求 `ctx.subagents`。UI 等服务消费方可以展示两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 适配器（[dsh-tool-subagent-control](../../packages/subagent/tool-subagent-control) 中可单独加载的 `/list-agents` 插件）则只保留可继续条目，并将活动状态映射到现有的 `running`／`complete` 词汇。枚举不会查询继续执行管理器的 Activation map、Agent 注册表或提供方可用性；`send_message` 仍是消息送达时的权威操作，列表中的运行中可继续 child 仍可能因所有权冲突而拒绝投递。读路径的设计理由见[列表身份投影 Agent Note](../../.agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.md)。
 
 ## 终态结果：`SubagentResult`
 
@@ -344,7 +344,7 @@ interface SubagentRun {
 }
 ```
 
-本地单次 run 必须在 `start()` fulfill 之前发布一个普通子 agent／会话，将该子会话 id 作为 `SubagentRun.id` 返回，以 `localAgent` 暴露确切的子 agent，在子 agent 的 `parentSession` header 中记录 `request.parent.session.id`，并在子 agent 的初始轮次内、首次请求前追加已解析的描述符。运行时所有权可以把子 agent 放在 parent、提供方或 root 作用域下。远程提供方则返回 parent 作用域的生命周期 id 与 `localAgent: undefined`；由于没有本地 child Session，它不会出现在基于追踪的枚举结果中。
+本地单次 run 必须在 `start()` fulfill 之前发布一个普通子 agent／会话，将该子会话 id 作为 `SubagentRun.id` 返回，以 `localAgent` 暴露确切的子 agent，在子 agent 的 `parentSession` header 中记录 `request.parent.session.id`，并在子 agent 的初始轮次内、首次请求前追加已解析的描述符。运行时所有权可以把子 agent 放在 parent、提供方或 root 作用域下。远程提供方则返回 parent 作用域的生命周期 id 与 `localAgent: undefined`；由于没有本地 child Session，它不会出现在持久化枚举结果中。
 
 <a id="the-provider-seam-subagentprovider"></a>
 
diff --git a/docs/core-data-structures/subprocess.i18n.yaml b/docs/core-data-structures/subprocess.i18n.yaml
index 01a6d57110..5d59f6fd16 100644
--- a/docs/core-data-structures/subprocess.i18n.yaml
+++ b/docs/core-data-structures/subprocess.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 docs/core-data-structures/subprocess.md
-subprocess.md: 922e7ad0ee8b5c0dbcd0a6a4553c9d2a580f3ee2
-subprocess.zh.md: ec9f41cfa9e3121f630bab2b6f1e921c81ad55b7
+subprocess.md: 8189795c5acf2fc1882d9e5bc1c006f49c327e2f
+subprocess.zh.md: 370a1a05807eefbe09a896ea8bcca1e4ab0a6b83
diff --git a/docs/core-data-structures/subprocess.md b/docs/core-data-structures/subprocess.md
index 922e7ad0ee..8189795c5a 100644
--- a/docs/core-data-structures/subprocess.md
+++ b/docs/core-data-structures/subprocess.md
@@ -8,7 +8,7 @@ Source: [`packages/subprocess/subprocess/src/types.ts`](../../packages/subproces
 
 ## Managed environment namespace and captured output
 
-`DSH_*` variables are Harness-owned child-process facts; implementations discard ambient `DSH_*` names before the caller's explicit `env` merges, so a current fact arrives only as a deliberate entry, and each collected stream reports its truncation and spill-recovery state through `CollectedOutput`.
+`DSH_*` variables are Harness-owned child-process facts; implementations discard ambient `DSH_*` names before the caller's explicit `env` merges, so a current fact arrives only as a deliberate string entry, while an explicit `undefined` tombstone removes an ordinary ambient value. Each collected stream reports its truncation and spill-recovery state through `CollectedOutput`.
 
 ```ts type-equiv
 /** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
@@ -101,10 +101,11 @@ interface SubprocessSpawnSpec {
   /** Per-stream stdio dispositions. */
   stdio: SubprocessStdio
   /**
-   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
-   * escalation and for draining still-open collected pipes after the process
-   * exits (an inherited descriptor held by a surviving descendant cannot hold
-   * the outcome open indefinitely).
+   * Positive finite grace period in milliseconds, no greater than
+   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
+   * and for draining still-open collected pipes after the process exits (an
+   * inherited descriptor held by a surviving descendant cannot hold the
+   * outcome open indefinitely).
    */
   graceMs: number
   /**
@@ -115,13 +116,12 @@ interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation:
-   * every entry is a deliberate caller opt-in, so a forwarded
-   * credential-shaped entry or a current `DSH_*` fact survives precisely
-   * because this layer merges after the scrub that drops its ambient
-   * namesake.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+   * string is a deliberate caller opt-in, so a forwarded credential-shaped
+   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
+   * tombstone that removes an ordinary ambient entry from the child.
    */
-  env?: Record<string, string> | undefined
+  env?: NodeJS.ProcessEnv | undefined
 }
 ```
 
diff --git a/docs/core-data-structures/subprocess.zh.md b/docs/core-data-structures/subprocess.zh.md
index ec9f41cfa9..370a1a0580 100644
--- a/docs/core-data-structures/subprocess.zh.md
+++ b/docs/core-data-structures/subprocess.zh.md
@@ -8,7 +8,7 @@
 
 ## 受管环境命名空间与捕获的输出
 
-`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的条目形式到达，每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
+`DSH_*` 变量是归 Harness 所有的子进程事实；实现会在合并调用方显式 `env` 之前丢弃环境中已有的 `DSH_*` 名称，因此当前事实只会以有意提供的字符串条目形式到达，而显式的 `undefined` tombstone 会删除普通环境中已有的值。每条被收集的流都通过 `CollectedOutput` 报告自身的截断与 spill 恢复状态。
 
 ```ts type-equiv
 /** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
@@ -101,10 +101,11 @@ interface SubprocessSpawnSpec {
   /** Per-stream stdio dispositions. */
   stdio: SubprocessStdio
   /**
-   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
-   * escalation and for draining still-open collected pipes after the process
-   * exits (an inherited descriptor held by a surviving descendant cannot hold
-   * the outcome open indefinitely).
+   * Positive finite grace period in milliseconds, no greater than
+   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
+   * and for draining still-open collected pipes after the process exits (an
+   * inherited descriptor held by a surviving descendant cannot hold the
+   * outcome open indefinitely).
    */
   graceMs: number
   /**
@@ -115,13 +116,12 @@ interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation:
-   * every entry is a deliberate caller opt-in, so a forwarded
-   * credential-shaped entry or a current `DSH_*` fact survives precisely
-   * because this layer merges after the scrub that drops its ambient
-   * namesake.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+   * string is a deliberate caller opt-in, so a forwarded credential-shaped
+   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
+   * tombstone that removes an ordinary ambient entry from the child.
    */
-  env?: Record<string, string> | undefined
+  env?: NodeJS.ProcessEnv | undefined
 }
 ```
 
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 3ad8ef0b7e..a50b658e2a 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -68,6 +68,8 @@ flowchart TD
   subgraph group_subagent["packages/subagent"]
     pkg_subagent["subagent"]
     pkg_subagent_acp["subagent-acp"]
+    pkg_subagent_claude_code["subagent-claude-code"]
+    pkg_subagent_codex["subagent-codex"]
     pkg_subagent_dsh_sdk["subagent-dsh-sdk"]
     pkg_subagent_fork["subagent-fork"]
     pkg_subagent_inprocess["subagent-inprocess"]
@@ -351,6 +353,7 @@ flowchart TD
   pkg_storage_sqlite --> pkg_storage
   pkg_subprocess_local --> pkg_invariants
   pkg_subprocess_local --> pkg_subprocess
+  pkg_subprocess_local --> pkg_timeout
   pkg_typert_loader --> pkg_invariants
   pkg_typert_loader --> pkg_typert_registry
   pkg_llm_deepseek --> pkg_credentials
@@ -727,6 +730,7 @@ flowchart TD
   pkg_tool_fs_search --> pkg_spill
   pkg_tool_fs_search --> pkg_subprocess
   pkg_tool_fs_search --> pkg_system_prompt
+  pkg_tool_fs_search --> pkg_timeout
   pkg_tool_fs_search --> pkg_tools
   pkg_tool_str_replace_editor --> pkg_fs
   pkg_tool_str_replace_editor --> pkg_invariants
@@ -753,7 +757,7 @@ flowchart TD
   pkg_subagent --> pkg_session
   pkg_subagent --> pkg_session_persistence
   pkg_subagent --> pkg_session_projection
-  pkg_subagent --> pkg_session_query
+  pkg_subagent --> pkg_session_projection_cache
   pkg_subagent --> pkg_tasks
   pkg_subagent --> pkg_tools
   pkg_tool_web --> pkg_invariants
@@ -926,6 +930,13 @@ flowchart TD
   pkg_subagent_acp --> pkg_session
   pkg_subagent_acp --> pkg_subagent
   pkg_subagent_acp --> pkg_subprocess
+  pkg_subagent_acp --> pkg_timeout
+  pkg_subagent_claude_code --> pkg_invariants
+  pkg_subagent_claude_code --> pkg_llm
+  pkg_subagent_claude_code --> pkg_session
+  pkg_subagent_claude_code --> pkg_subagent
+  pkg_subagent_claude_code --> pkg_subprocess
+  pkg_subagent_claude_code --> pkg_timeout
   pkg_subagent_inprocess --> pkg_agent
   pkg_subagent_inprocess --> pkg_invariants
   pkg_subagent_inprocess --> pkg_llm
@@ -944,7 +955,6 @@ flowchart TD
   pkg_tool_subagent_control --> pkg_invariants
   pkg_tool_subagent_control --> pkg_llm
   pkg_tool_subagent_control --> pkg_session
-  pkg_tool_subagent_control --> pkg_session_query
   pkg_tool_subagent_control --> pkg_subagent
   pkg_tool_subagent_control --> pkg_tools
   pkg_tool_subagent_report --> pkg_invariants
@@ -1021,6 +1031,13 @@ flowchart TD
   pkg_workflow_workerthread --> pkg_subagent
   pkg_workflow_workerthread --> pkg_tools
   pkg_workflow_workerthread --> pkg_workflow
+  pkg_subagent_codex --> pkg_invariants
+  pkg_subagent_codex --> pkg_llm
+  pkg_subagent_codex --> pkg_sdk_protocol
+  pkg_subagent_codex --> pkg_session
+  pkg_subagent_codex --> pkg_subagent
+  pkg_subagent_codex --> pkg_subprocess
+  pkg_subagent_codex --> pkg_timeout
   pkg_subagent_fork --> pkg_agent
   pkg_subagent_fork --> pkg_invariants
   pkg_subagent_fork --> pkg_session
@@ -1138,7 +1155,7 @@ flowchart TD
 | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
-| [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
 | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings), [`timeout`](../packages/util/timeout) |
@@ -1223,11 +1240,11 @@ flowchart TD
 | [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`bash-env`](../packages/bash/bash-env) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`paths`](../packages/util/paths), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
 | [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
 | [`tool-str-replace-editor`](../packages/fs/tool-str-replace-editor) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`tools`](../packages/core/tools) |
 | [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
 | [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
-| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-query`](../packages/session-query/session-query), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
 | [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
 | [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
@@ -1255,10 +1272,11 @@ flowchart TD
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | [`tool-pwsh`](../packages/bash/tool-pwsh) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`bash-env`](../packages/bash/bash-env), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
-| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) |
+| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
+| [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
-| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`tool-subagent-control`](../packages/subagent/tool-subagent-control) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`repository-plugin`](../packages/cordis/repository-plugin) | `cordis` | [`invariants`](../packages/support/invariants), [`mcp-client`](../packages/mcp/mcp-client), [`paths`](../packages/util/paths), [`skill-local`](../packages/skill/skill-local) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
@@ -1270,6 +1288,7 @@ flowchart TD
 | [`sdk-protocol`](../packages/sdk/sdk-protocol) | `sdk` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
 | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`subagent-codex`](../packages/subagent/subagent-codex) | `subagent` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/sdk-protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 65a2760517..d3dfa55ccb 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -7,7 +7,7 @@ Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`,
 
 This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator's boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).
 
-Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config. The registered tool NAME can be a load-time config (e.g. `tool-subagent`'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog's packages-only scope.
+Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog's packages-only scope.
 
 ## Tool Package Map
 
@@ -32,10 +32,10 @@ This table connects model-visible tool names to the plugin package and service s
 | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.agents`, `ctx.skills` | `tool/call`, `tool/result`, `user/message replacement catalogs via agent.inject()` | - | - |
 | `@deepseek-ai/dsh-tool-session-query` | `session_event_read`, `session_event_search`, `session_event_trace`, `session_search`, `session_trace` | `ctx.tools`, `ctx.systemPrompt`, `ctx.sessionQuery`, `a calling Agent for workspace authority` | `tool/call`, `tool/result` | - | The five read-only tools hide provider cursors and authorize every result from the immutable calling agent session. The package is opt-in; compositions that need enforced deadlines or bounded inline output also mount the generic timeout or spill policies. |
 | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `packages/bundle/base/cordis.patch.yml` and `examples/acp-agent/cordis.yml`. |
-| `@deepseek-ai/dsh-tool-subagent-control` | `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.sessionQuery (list_agents only)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (which additionally requires session query). |
+| `@deepseek-ai/dsh-tool-subagent-control` | `list_agents`, `send_message` | `ctx.tools`, `ctx.subagents`, `ctx.sessionProjections (list_agents catalog rows)` | `tool/call`, `tool/result`, `child session events through ctx.subagents` | - | The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry). |
 | `@deepseek-ai/dsh-tool-subagent-report` | `report` | `ctx.subagents`, `a live continuable in-process child Agent` | `tool/call`, `tool/result`, `a user-role message in the direct parent session` | - | Registered per continuable in-process child rather than globally, so this schema is visible only inside such a child and survives its global `toolFilter`. The parent-facing `send_message` tool is installed independently. |
 | `@deepseek-ai/dsh-tool-tasks` | `task_kill`, `task_list`, `task_output` | `ctx.tools`, `ctx.tasks`, `ctx.systemPrompt` | `tool/call`, `tool/result`, `user/message via agent.inject() for background completion notices` | - | The kind-agnostic background-task control surface: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers' `ctx.tasks.start()`. |
-| `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist. |
+| `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task. |
 | `@deepseek-ai/dsh-tool-workflow` | `workflow` | `ctx.tools`, `ctx.workflows`, `ctx.systemPrompt`, `a calling Agent (exec.agent parents the script children)` | `tool/call`, `tool/result` | - | - |
 | `@deepseek-ai/dsh-tool-web` | `web_fetch`, `web_search` | `ctx.tools`, `ctx.web`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | web_search and web_fetch keep provider selection behind ctx.web so model-visible schemas stay stable across backend swaps. |
 
@@ -1232,7 +1232,7 @@ Send a message to a background subagent by its subagent id, continuing the same
 
 Source: [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts)
 
-The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (which additionally requires session query).
+The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry).
 
 ## `@deepseek-ai/dsh-tool-subagent-report`
 
@@ -1334,7 +1334,7 @@ The kind-agnostic background-task control surface: background bash commands, PTY
 
 ### `todo_write`
 
-Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).
+Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).
 
 ```json
 {
@@ -1376,7 +1376,7 @@ Record and update a structured task list for the current work. Send the ENTIRE l
 
 Source: [`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts)
 
-todo_write is session-owned state; UIs render the latest todo/write event as a checklist.
+todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task.
 
 ## `@deepseek-ai/dsh-tool-workflow`
 
diff --git a/examples/acp-agent/composition.md b/examples/acp-agent/composition.md
index e4e21c785a..5e6a21e1ec 100644
--- a/examples/acp-agent/composition.md
+++ b/examples/acp-agent/composition.md
@@ -33,6 +33,8 @@ flowchart LR
   cfg --> plugin_acp_token_meter
   plugin_acp_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
   cfg --> plugin_acp_compact_basic
+  plugin_acp_session_projection["session-projection<br/>@deepseek-ai/dsh-session-projection"]
+  cfg --> plugin_acp_session_projection
   plugin_acp_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
   cfg --> plugin_acp_subagent
   plugin_acp_subagent_spawn["subagent-spawn<br/>@deepseek-ai/dsh-subagent-spawn"]
@@ -82,6 +84,7 @@ flowchart LR
 | `acp-agent` | `@deepseek-ai/dsh-acp-demo` |
 | `token-meter` | `@deepseek-ai/dsh-token-meter` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
+| `session-projection` | `@deepseek-ai/dsh-session-projection` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
 | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml
index 6edcee5cd8..1af9fa6316 100644
--- a/examples/acp-agent/cordis.yml
+++ b/examples/acp-agent/cordis.yml
@@ -80,6 +80,12 @@
     maxTokens: 8192
     compactionRetries: 1
 
+# Projection registry: subagent catalog identity (mode/label) folds through
+# its registered units; the catalog surfaces (`list_agents`, subagent listing)
+# fail loud without the capability.
+- id: session-projection
+  name: '@deepseek-ai/dsh-session-projection'
+
 # Expose fresh-child `spawn` and completed-prefix `fork` through separate tool
 # names so multi-child scenarios exercise both transports. These leaves follow
 # the app because it provides `ctx.agents` and `ctx.tools`.
@@ -98,8 +104,8 @@
 
 # Continuable background children are selected per delegation tool. The
 # separately loaded control package registers the global `send_message`; its
-# list plugin registers `list_agents` and requires the app's session query.
-# `report` is installed only in continuable child scopes.
+# list plugin registers `list_agents`, served through the sessionProjections
+# registry mounted above. `report` is installed only in continuable child scopes.
 - id: tool-subagent-control
   name: '@deepseek-ai/dsh-tool-subagent-control'
 
@@ -141,6 +147,8 @@
 # `todo_write` replaces the logged whole list for later model requests.
 - id: tool-todo
   name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
 
 # Identical repeat calls trigger advisory context, never a block, at the default
 # thresholds [3, 5, 8]. Only the repeat-tool-guard snapshot scenario reaches them.
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 225b033b56..bf4f7ac972 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -276,6 +276,8 @@ const SCENARIOS: Scenario[] = [
   // symlinked instruction file to its target's content. A second nested path
   // containing a literal closing tag is created at runtime: Git cannot check
   // that name out on Windows, so this delimiter-injection case is POSIX-only.
+  // The fixture also shadows the baseline after the first touch finishes its
+  // projection; the next entering pre-step restores it before request 2.
   // The scenario-specific config keeps home/root discovery hermetic, and the
   // resulting prefix needs its own pinned header class.
   {
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml
new file mode 100644
index 0000000000..2bfcd2af3f
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml
@@ -0,0 +1,40 @@
+# Test-only composition of both public opt-in providers and foreground tools.
+# The owning e2e boots this tree but never invokes a model or product process.
+- id: fixture
+  name: './fixture.ts'
+
+- id: subagent
+  name: '@deepseek-ai/dsh-subagent'
+
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
+- id: subagent-codex
+  name: '@deepseek-ai/dsh-subagent-codex'
+
+- id: subagent-claude-code
+  name: '@deepseek-ai/dsh-subagent-claude-code'
+
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: codex
+    toolName: subagent_codex
+    enableRunInBackground: false
+    maxDepth: 'provider-managed'
+
+- id: tool-subagent-claude-code
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: claude-code
+    toolName: subagent_claude_code
+    enableRunInBackground: false
+    maxDepth: 'provider-managed'
+
+- id: cli-agent
+  name: '@deepseek-ai/dsh-cli-demo'
+  config:
+    provider: mock
+    model: mock-delegate
+    persona: 'This composition test must not start a model turn.'
+    workspaceContext: false
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/driver.ts b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/driver.ts
new file mode 100644
index 0000000000..d7540e1a2d
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/driver.ts
@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/** Inspect both public product-provider compositions without invoking them. */
+
+import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import type {} from '@deepseek-ai/dsh-subagent'
+import type {} from '@deepseek-ai/dsh-tools'
+
+const configPath = process.argv[2]
+if (configPath === undefined) {
+  throw new Error('product-provider Loader composition driver requires a config path')
+}
+
+let starts = 0
+const ctx = await boot(
+  'product-provider-loader-composition',
+  resolveConfigPath(configPath, undefined),
+  undefined,
+  (hostCtx) => {
+    hostCtx.on('subagent/start', () => {
+      starts += 1
+    })
+  },
+)
+
+try {
+  const providerNames = ['codex', 'claude-code'] as const
+  const toolNames = ['subagent_codex', 'subagent_claude_code'] as const
+  const providers = providerNames.map((providerName) => {
+    const provider = ctx.subagents.getProvider(providerName)
+    if (provider === undefined) {
+      throw new Error(`${providerName} provider was not registered`)
+    }
+    return {
+      name: provider.name,
+      capabilities: provider.capabilities,
+      inheritsParentContext: provider.inheritsParentContext,
+    }
+  })
+  const tools = toolNames.map((toolName) => {
+    const tool = ctx.tools.schemas().find(schema => schema.name === toolName)
+    if (tool === undefined) throw new Error(`${toolName} tool was not registered`)
+    const properties = tool.parameters.properties
+    if (
+      typeof properties !== 'object'
+      || properties === null
+      || Array.isArray(properties)
+    ) {
+      throw new Error(`${toolName} has invalid parameter properties`)
+    }
+    return {
+      name: tool.name,
+      parameterNames: Object.keys(properties).sort(),
+      required: tool.parameters.required,
+    }
+  })
+
+  process.stdout.write(`${JSON.stringify({
+    registeredProviders: ctx.subagents.list(),
+    providers,
+    tools,
+    starts,
+  })}\n`)
+} finally {
+  await ctx.fiber.dispose()
+}
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/fixture.ts b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/fixture.ts
new file mode 100644
index 0000000000..a9f9cd5997
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/fixture.ts
@@ -0,0 +1,7 @@
+/** Reuse the composition-only parent adapter shared by the product providers. */
+
+export {
+  apply,
+  inject,
+  name,
+} from '../subagent-codex/fixture.ts'
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml
new file mode 100644
index 0000000000..be1af7c135
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml
@@ -0,0 +1,29 @@
+# Test-only composition of the public opt-in provider and foreground tool.
+# The owning e2e boots this tree but never invokes the model or Codex.
+- id: fixture
+  name: './fixture.ts'
+
+- id: subagent
+  name: '@deepseek-ai/dsh-subagent'
+
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
+- id: subagent-codex
+  name: '@deepseek-ai/dsh-subagent-codex'
+
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: codex
+    toolName: subagent_codex
+    enableRunInBackground: false
+    maxDepth: 'provider-managed'
+
+- id: cli-agent
+  name: '@deepseek-ai/dsh-cli-demo'
+  config:
+    provider: mock
+    model: mock-delegate
+    persona: 'This composition test must not start a model turn.'
+    workspaceContext: false
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-codex/driver.ts b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/driver.ts
new file mode 100644
index 0000000000..873f5e36de
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/driver.ts
@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/** Inspect the public Codex provider composition without invoking the product. */
+
+import { boot, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import type {} from '@deepseek-ai/dsh-subagent'
+import type {} from '@deepseek-ai/dsh-tools'
+
+const configPath = process.argv[2]
+if (configPath === undefined) {
+  throw new Error('subagent-codex Loader composition driver requires a config path')
+}
+
+let starts = 0
+const ctx = await boot(
+  'subagent-codex-loader-composition',
+  resolveConfigPath(configPath, undefined),
+  undefined,
+  (hostCtx) => {
+    hostCtx.on('subagent/start', () => {
+      starts += 1
+    })
+  },
+)
+
+try {
+  const provider = ctx.subagents.getProvider('codex')
+  if (provider === undefined) throw new Error('Codex provider was not registered')
+  const tool = ctx.tools.schemas().find(schema => schema.name === 'subagent_codex')
+  if (tool === undefined) throw new Error('subagent_codex tool was not registered')
+  const properties = tool.parameters.properties
+  if (typeof properties !== 'object' || properties === null || Array.isArray(properties)) {
+    throw new Error('subagent_codex tool has invalid parameter properties')
+  }
+
+  process.stdout.write(`${JSON.stringify({
+    providers: ctx.subagents.list(),
+    provider: {
+      name: provider.name,
+      capabilities: provider.capabilities,
+      inheritsParentContext: provider.inheritsParentContext,
+    },
+    tool: {
+      name: tool.name,
+      parameterNames: Object.keys(properties).sort(),
+      required: tool.parameters.required,
+    },
+    starts,
+  })}\n`)
+} finally {
+  await ctx.fiber.dispose()
+}
diff --git a/examples/acp-agent/tests/fixtures/subagent/subagent-codex/fixture.ts b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/fixture.ts
new file mode 100644
index 0000000000..e2dc946dfe
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/subagent/subagent-codex/fixture.ts
@@ -0,0 +1,22 @@
+/** Parent adapter that fails if the composition-only Loader test starts a turn. */
+
+import type { Context } from 'cordis'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import { LlmAdapter } from '@deepseek-ai/dsh-llm'
+
+class CompositionOnlyAdapter extends LlmAdapter {
+  async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    throw new Error('subagent-codex Loader composition must not invoke a model')
+  }
+}
+
+export const name = 'codex-loader-composition-fixture'
+export const inject = ['llm']
+
+/**
+ * Register a parent adapter solely so the host composition is complete.
+ * @param ctx - Loader context supplying the LLM seam.
+ */
+export function apply(ctx: Context): void {
+  ctx.llm.registerAdapter(['mock'], new CompositionOnlyAdapter())
+}
diff --git a/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts b/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
new file mode 100644
index 0000000000..e13e3cf6b3
--- /dev/null
+++ b/examples/acp-agent/tests/fixtures/workspace-context-compaction.ts
@@ -0,0 +1,36 @@
+import type { Context } from 'cordis'
+import type {} from '@deepseek-ai/dsh-agent'
+import { COMPACT_CHECKPOINT_SOURCE } from '@deepseek-ai/dsh-compact'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-tools'
+
+export const name = 'workspace-context-compaction'
+
+/** Replace the visible workspace baseline after the first touch is fully projected. */
+export function apply(ctx: Context): void {
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    const downstream = await next()
+    if (result.isError
+      || exec.agent === undefined
+      || exec.name !== 'read'
+      || typeof exec.arguments !== 'object'
+      || exec.arguments === null
+      || !('file_path' in exec.arguments)
+      || exec.arguments.file_path !== 'nested/task.txt') return downstream
+    const agent = exec.agent
+    const baseline = agent.session.surface.nodes
+      .map(seq => agent.session.events[seq])
+      .find(event => event?.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions'
+        && event.data.source.baseline === true)
+    if (baseline === undefined) throw new Error('workspace baseline missing before snapshot compaction')
+    agent.session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: 'Earlier context was compacted for this snapshot.' }],
+      source: COMPACT_CHECKPOINT_SOURCE,
+    }), {
+      surfaceOp: { op: 'replace', start: baseline.seq, end: baseline.seq },
+      sourceEventSeqs: [baseline.seq],
+    })
+    return downstream
+  })
+}
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
index 88814b1f40..e63807db59 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
@@ -160,7 +160,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */
+  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */
   todo_write: {
     /** The COMPLETE task list, replacing any previous list. */
     todos: ({
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
index f29ad6e332..98b866f841 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.expected.json
@@ -386,7 +386,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
index 3cd325eca2..7588c353cc 100644
--- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.expected.json
@@ -329,7 +329,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
index a000d6cd20..70a71c3673 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
+++ b/examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
@@ -143,7 +143,7 @@ interface ToolArgsMap {
     /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */
     timeout_ms?: number;
   } & Record<string, JsonValue>;
-  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */
+  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */
   todo_write: {
     /** The COMPLETE task list, replacing any previous list. */
     todos: ({
diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
index 6107589cb2..368a2262c8 100644
--- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl
@@ -4,7 +4,7 @@
 {"type":"agent/inbox/spliced","seq":2,"time":1785498825916,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":3,"time":1785901435161,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":4,"time":1785498825917,"data":{"content":[{"type":"text","text":"Using ONE run_code program, call tools.read on nested/task.txt. After the program finishes, answer the workspace handshake question using the newly discovered instructions: What is the Code Mode workspace handshake?"}],"source":{"kind":"user"},"role":"user","id":"3b04578e-7b22-4b44-b4cd-ef9d4d26fe8b"},"surfaceOp":"append"}
-{"type":"user/message","seq":5,"time":1785901435161,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nWorkspace snapshot root instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2119a7072358cc727f8d9c4cb7388e905b075fe6"}]},"role":"user","id":"ac92e76e-4861-47a6-87f8-4e9ca904eb24"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1785901435161,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nWorkspace snapshot root instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".git\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2119a7072358cc727f8d9c4cb7388e905b075fe6"}]},"role":"user","id":"ac92e76e-4861-47a6-87f8-4e9ca904eb24"},"surfaceOp":"append"}
 {"type":"user/message","seq":6,"time":1785730478198,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"d6d78330-05c0-4ebd-9e29-595df6440250"},"surfaceOp":"append"}
 {"type":"session/title","seq":7,"time":1785730478198,"data":{"title":"Using ONE run_code program, call","messageSeqs":[4],"source":{"kind":"fallback"}}}
 {"type":"request/header","seq":8,"time":1785498825920,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
diff --git a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
index ba920096e5..1fba9e71d5 100644
--- a/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/lsp-definition/tool-schemas.expected.json
@@ -345,7 +345,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
index 91e6b46f23..48b72040a0 100644
--- a/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/pty-tools/tool-schemas.expected.json
@@ -437,7 +437,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
index 00e8e8ab04..41fb8718c9 100644
--- a/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/session-query-spill/tool-schemas.expected.json
@@ -512,7 +512,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
index 273f70e766..519e8eac8c 100644
--- a/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-continuable/tool-schemas.1.expected.json
@@ -324,7 +324,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
index 273f70e766..519e8eac8c 100644
--- a/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-list-agents/tool-schemas.1.expected.json
@@ -324,7 +324,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
index 273f70e766..519e8eac8c 100644
--- a/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
+++ b/examples/acp-agent/tests/snapshots/subagent-report/tool-schemas.1.expected.json
@@ -324,7 +324,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
index 94d8a26660..08c1451f60 100644
--- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/todo-write/input.json b/examples/acp-agent/tests/snapshots/todo-write/input.json
index 6cc82bdcae..f53711516a 100644
--- a/examples/acp-agent/tests/snapshots/todo-write/input.json
+++ b/examples/acp-agent/tests/snapshots/todo-write/input.json
@@ -2,6 +2,6 @@
   "steps": [
     { "op": "initialize" },
     { "op": "newSession" },
-    { "op": "prompt", "text": "Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop." }
+    { "op": "prompt", "text": "Use the todo_write tool to record a plan with exactly three todos for work running in parallel: \"read the code\" (in_progress), \"watch the background build\" (in_progress), \"write the fix\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop." }
   ]
 }
diff --git a/examples/acp-agent/tests/snapshots/todo-write/session.jsonl b/examples/acp-agent/tests/snapshots/todo-write/session.jsonl
index 46461efaa1..08b553c6ec 100644
--- a/examples/acp-agent/tests/snapshots/todo-write/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/todo-write/session.jsonl
@@ -1,36 +1,37 @@
-{"type":"session","version":0,"id":"b0f1f758-dcf0-474e-851d-e62c11ec0a09","createdAt":1783352057652,"cwd":"{{cwd}}","delegationDepth":0}
-{"type":"agent/inbox/spliced","seq":0,"time":1785498772484,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"5ecf5e4b-6a18-447d-9341-48f38afdd12e"}]}}
-{"type":"turn/start","seq":1,"time":1785821376741,"data":{"turn":1}}
-{"type":"agent/inbox/spliced","seq":2,"time":1785821376741,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
-{"type":"step/start","seq":3,"time":1783352057657,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":4,"time":1785498772510,"data":{"content":[{"type":"text","text":"Use the todo_write tool to record a plan with exactly three todos: \"read the code\" (in_progress), \"write the fix\" (pending), \"run the tests\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"5ecf5e4b-6a18-447d-9341-48f38afdd12e"},"surfaceOp":"append"}
-{"type":"user/message","seq":5,"time":1785730425725,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"8d4ac045-8016-4cec-8b12-91d9459231e1"},"surfaceOp":"append"}
-{"type":"session/title","seq":6,"time":1785730425725,"data":{"title":"Use the todo_write tool to","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498772511,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
-{"type":"request/context","seq":8,"time":1785730425726,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
-{"type":"assistant/chunk","seq":9,"time":1783352058426,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"reasoning-chunks","seq0":10,"time0":1783352058466,"data":{"turn":1,"step":1,"index":0,"dt":[1,0,0,0,17,0,0,0,1,26,1,1,0,0,1,26,0,31,1,25,0,0,0,29,0,0,0,0,91,0],"texts":["The"," user"," wants"," me"," to"," use"," the"," todo","_write"," tool"," to"," record"," a"," plan"," with"," exactly"," three"," todos"," in"," the"," specified"," status","es",","," then"," reply"," with"," \"","D","ONE","\"."]}}
-{"type":"assistant/chunk","seq":41,"time":1783352058746,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
-{"type":"tool-call-chunks","seq0":42,"time0":1783352058747,"data":{"turn":1,"step":1,"index":1,"dt":[0,0,28,0,1,29,1,0,0,0,0,26,0,0,0,0,0,30,1,0,0,0,0,26,1,0,0,0,0,28,0,0,0,0,0,29,0,0,0,0,1,28,0,0,0,1,0,27,1,0,28,62,1],"id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","args":["","{","\"","t","odos","\"",": ","[","{\"","content","\":"," \"","read"," the"," code","\","," \"","status","\":"," \"","in","_pro","gress","\"},"," {\"","content","\":"," \"","write"," the"," fix","\","," \"","status","\":"," \"","pending","\"},"," {\"","content","\":"," \"","run"," the"," tests","\","," \"","status","\":"," \"","pending","\"","}]","}"]}}
-{"type":"assistant/chunk","seq":96,"time":1783352059096,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use the todo_write tool to record a plan with exactly three todos in the specified statuses, then reply with \"DONE\"."}}}}
-{"type":"assistant/chunk","seq":97,"time":1783352059096,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}, {\"content\": \"run the tests\", \"status\": \"pending\"}]}"}}}}
-{"type":"assistant/chunk","seq":98,"time":1785498772522,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2913,"outputTokens":121,"cacheReadTokens":0,"reasoningTokens":31}}}}
-{"type":"assistant/chunk","seq":99,"time":1785730425738,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":100,"time":1785730425738,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to use the todo_write tool to record a plan with exactly three todos in the specified statuses, then reply with \"DONE\"."},{"type":"tool-call","id":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}, {\"content\": \"run the tests\", \"status\": \"pending\"}]}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"08141496-5477-4d05-b2c7-414865ea9a17"},"usage":{"inputTokens":2913,"outputTokens":121,"cacheReadTokens":0,"reasoningTokens":31}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99],"surfaceOp":"append"}
-{"type":"tool/call","seq":101,"time":1785730425739,"data":{"turn":1,"step":1,"callId":"call_00_fjAnBThbDjxepBtp3hDt3264","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}, {\"content\": \"run the tests\", \"status\": \"pending\"}]}"}}
-{"type":"todo/write","seq":102,"time":1785730425747,"data":{"todos":[{"content":"read the code","status":"in_progress"},{"content":"write the fix","status":"pending"},{"content":"run the tests","status":"pending"}]}}
-{"type":"tool/result","seq":103,"time":1785730425748,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_fjAnBThbDjxepBtp3hDt3264"},"content":[{"type":"tool-result","toolCallId":"call_00_fjAnBThbDjxepBtp3hDt3264","content":[{"type":"text","text":"Updated todo list: 2 pending, 1 in progress, 0 completed."}],"isError":false}],"role":"user","id":"c178ad5b-7c1f-4239-9aa6-20d1c6b00a82"}},"sourceEventSeqs":[101],"surfaceOp":"append"}
-{"type":"step/end","seq":104,"time":1785730425748,"data":{"turn":1,"step":1}}
-{"type":"step/start","seq":105,"time":1785730425759,"data":{"turn":1,"step":2}}
-{"type":"assistant/chunk","seq":106,"time":1783352059835,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
-{"type":"reasoning-chunks","seq0":107,"time0":1783352059863,"data":{"turn":1,"step":2,"index":0,"dt":[0,1,0,28,0,1,0,27,0,1,0,0,29,0,0,0,1,0,28,0],"texts":["The"," todos"," have"," been"," written"," successfully","."," Now"," I"," just"," need"," to"," reply"," with"," the"," single"," word"," \"","D","ONE","\"."]}}
-{"type":"assistant/chunk","seq":128,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":129,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}}
-{"type":"assistant/chunk","seq":130,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
-{"type":"assistant/chunk","seq":131,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The todos have been written successfully. Now I just need to reply with the single word \"DONE\"."}}}}
-{"type":"assistant/chunk","seq":132,"time":1783352059980,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}}
-{"type":"assistant/chunk","seq":133,"time":1785498772545,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":237,"outputTokens":24,"cacheReadTokens":2816,"reasoningTokens":21}}}}
-{"type":"assistant/chunk","seq":134,"time":1785730425764,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":135,"time":1785730425764,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The todos have been written successfully. Now I just need to reply with the single word \"DONE\"."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"c4e454ce-14cc-4030-be47-0395ac9f12fb"},"usage":{"inputTokens":237,"outputTokens":24,"cacheReadTokens":2816,"reasoningTokens":21}},"sourceEventSeqs":[106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134],"surfaceOp":"append"}
-{"type":"step/end","seq":136,"time":1785730425764,"data":{"turn":1,"step":2}}
-{"type":"turn/end","seq":137,"time":1785730425764,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"d9d967e8-0112-471c-a3b5-dfdc171aba61","createdAt":1785987077399,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"agent/inbox/spliced","seq":0,"time":1785987077401,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use the todo_write tool to record a plan with exactly three todos for work running in parallel: \"read the code\" (in_progress), \"watch the background build\" (in_progress), \"write the fix\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"befb10e9-f992-4a19-9e1b-333ad7fd72f8"}]}}
+{"type":"turn/start","seq":1,"time":1785987077401,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":1785987077401,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":3,"time":1785987077430,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":4,"time":1785987077430,"data":{"content":[{"type":"text","text":"Use the todo_write tool to record a plan with exactly three todos for work running in parallel: \"read the code\" (in_progress), \"watch the background build\" (in_progress), \"write the fix\" (pending). Send all three in one todo_write call. Then reply with the single word DONE and stop."}],"source":{"kind":"user"},"role":"user","id":"befb10e9-f992-4a19-9e1b-333ad7fd72f8"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1785987077430,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"3893b488-4678-4b29-be9f-6365854b0ddc"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":1785987077430,"data":{"title":"Use the todo_write tool to","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":1785987077431,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":1785987077431,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":9,"time":1785987079233,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"reasoning-chunks","seq0":10,"time0":1785987079233,"data":{"turn":1,"step":1,"index":0,"dt":[152,51,2,0,0,61,55,0,1,0,47,53,0,1,0,46,1,0,0,1,45,1,0],"texts":["The"," user"," wants"," me"," to"," use"," todo","_write"," to"," create"," exactly"," three"," todos",","," then"," reply"," with"," \"","D","ONE","\""," and"," stop","."]}}
+{"type":"assistant/chunk","seq":34,"time":1785987079909,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}}
+{"type":"tool-call-chunks","seq0":35,"time0":1785987079910,"data":{"turn":1,"step":1,"index":1,"dt":[52,0,1,0,0,0,55,1,0,0,50,1,0,0,0,0,52,0,0,0,0,1,52,1,0,0,0,0,59,0,0,0,0,0,57,0,0,0,0,0,54,0,0,0,0,0,45,1,0,0,0,0,67,0,0,46],"id":"call_00_UHvM5RrwIkjNJ9xh3S735164","name":"todo_write","args":["","{","\"","t","odos","\"",": ","[","{\"","content","\":"," \"","read"," the"," code","\","," \"","status","\":"," \"","in","_pro","gress","\"},"," {\"","content","\":"," \"","watch"," the"," background"," build","\","," \"","status","\":"," \"","in","_pro","gress","\"},"," {\"","content","\":"," \"","write"," the"," fix","\","," \"","status","\":"," \"","pending","\"","}]","}"]}}
+{"type":"assistant/chunk","seq":92,"time":1785987080614,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to use todo_write to create exactly three todos, then reply with \"DONE\" and stop."}}}}
+{"type":"assistant/chunk","seq":93,"time":1785987080614,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_UHvM5RrwIkjNJ9xh3S735164","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"watch the background build\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}]}"}}}}
+{"type":"assistant/chunk","seq":94,"time":1785987080615,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":5778,"outputTokens":117,"cacheReadTokens":0,"reasoningTokens":24}}}}
+{"type":"assistant/chunk","seq":95,"time":1785987080615,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":96,"time":1785987080618,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to use todo_write to create exactly three todos, then reply with \"DONE\" and stop."},{"type":"tool-call","id":"call_00_UHvM5RrwIkjNJ9xh3S735164","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"watch the background build\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}]}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"600b618f-2403-4584-b7aa-84b474e7ef08"},"usage":{"inputTokens":5778,"outputTokens":117,"cacheReadTokens":0,"reasoningTokens":24}},"sourceEventSeqs":[9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95],"surfaceOp":"append"}
+{"type":"tool/call","seq":97,"time":1785987080619,"data":{"turn":1,"step":1,"callId":"call_00_UHvM5RrwIkjNJ9xh3S735164","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"read the code\", \"status\": \"in_progress\"}, {\"content\": \"watch the background build\", \"status\": \"in_progress\"}, {\"content\": \"write the fix\", \"status\": \"pending\"}]}"}}
+{"type":"todo/write","seq":98,"time":1785987080632,"data":{"todos":[{"content":"read the code","status":"in_progress"},{"content":"watch the background build","status":"in_progress"},{"content":"write the fix","status":"pending"}]}}
+{"type":"tool/result","seq":99,"time":1785987080633,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_00_UHvM5RrwIkjNJ9xh3S735164"},"content":[{"type":"tool-result","toolCallId":"call_00_UHvM5RrwIkjNJ9xh3S735164","content":[{"type":"text","text":"Updated todo list: 1 pending, 2 in progress, 0 completed."}],"isError":false}],"role":"user","id":"65e181f3-565f-4be4-9ffe-9d59c808f7f8"}},"sourceEventSeqs":[97],"surfaceOp":"append"}
+{"type":"step/end","seq":100,"time":1785987080633,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":101,"time":1785987080647,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":102,"time":1785987081239,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}}
+{"type":"assistant/chunk","seq":103,"time":1785987081239,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"Done"}}}
+{"type":"assistant/chunk","seq":104,"time":1785987081391,"data":{"turn":1,"step":2,"chunk":{"type":"reasoning-delta","index":0,"text":"."}}}
+{"type":"assistant/chunk","seq":105,"time":1785987081451,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":1,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":106,"time":1785987081452,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"D"}}}
+{"type":"assistant/chunk","seq":107,"time":1785987081452,"data":{"turn":1,"step":2,"chunk":{"type":"text-delta","index":1,"text":"ONE"}}}
+{"type":"assistant/chunk","seq":108,"time":1785987081453,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"Done."}}}}
+{"type":"assistant/chunk","seq":109,"time":1785987081453,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":110,"time":1785987081453,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":154,"outputTokens":5,"cacheReadTokens":5760,"reasoningTokens":2}}}}
+{"type":"assistant/chunk","seq":111,"time":1785987081453,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":112,"time":1785987081454,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"Done."},{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"e4db2f4e-732f-4b58-a44f-5d08b50ce234"},"usage":{"inputTokens":154,"outputTokens":5,"cacheReadTokens":5760,"reasoningTokens":2}},"sourceEventSeqs":[102,103,104,105,106,107,108,109,110,111],"surfaceOp":"append"}
+{"type":"step/end","seq":113,"time":1785987081455,"data":{"turn":1,"step":2}}
+{"type":"turn/end","seq":114,"time":1785987081455,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
index 01a910b06c..c242366100 100644
--- a/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
+++ b/examples/acp-agent/tests/snapshots/web-fetch/tool-schemas.expected.json
@@ -308,7 +308,7 @@
     },
     {
       "name": "todo_write",
-      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
+      "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).",
       "parameters": {
         "type": "object",
         "properties": {
diff --git a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
index d51a6c820a..179e61ade9 100644
--- a/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
+++ b/examples/acp-agent/tests/snapshots/workspace-context/session.jsonl
@@ -1,11 +1,11 @@
 {"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
-{"type":"agent/inbox/spliced","seq":0,"time":1785498790330,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Read nested/task.txt, then read scope</system-reminder>/task.txt with the read tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"22938d3b-c065-46c8-acb7-18f758285842"}]}}
+{"type":"agent/inbox/spliced","seq":0,"time":1785498790330,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Read nested/task.txt, then read scope</system-reminder>/task.txt with the read tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"81078e7a-6837-45c2-a6b4-a5a3dfce0d4a"}]}}
 {"type":"turn/start","seq":1,"time":1785821400350,"data":{"turn":1}}
 {"type":"agent/inbox/spliced","seq":2,"time":1785498790356,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":3,"time":1785901433981,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":4,"time":1785498790356,"data":{"content":[{"type":"text","text":"Read nested/task.txt, then read scope</system-reminder>/task.txt with the read tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"22938d3b-c065-46c8-acb7-18f758285842"},"surfaceOp":"append"}
-{"type":"user/message","seq":5,"time":1785901433982,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nRoot snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2e18766c26603608f321508caae00ea8f4434d59"}]},"role":"user","id":"ec039e95-6864-49ef-ad23-4f65b331dc29"},"surfaceOp":"append"}
-{"type":"user/message","seq":6,"time":1785730689193,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"cbea9bd9-3e08-48bf-951f-fe3e5aa4b5d9"},"surfaceOp":"append"}
+{"type":"user/message","seq":4,"time":1785498790356,"data":{"content":[{"type":"text","text":"Read nested/task.txt, then read scope</system-reminder>/task.txt with the read tool, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"81078e7a-6837-45c2-a6b4-a5a3dfce0d4a"},"surfaceOp":"append"}
+{"type":"user/message","seq":5,"time":1785901433982,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nRoot snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".dsh-project\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2e18766c26603608f321508caae00ea8f4434d59"}]},"role":"user","id":"4cba1848-cbb7-46fd-8cea-8497d54d0e63"},"surfaceOp":"append"}
+{"type":"user/message","seq":6,"time":1785730689193,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"e4406554-e400-49c6-b8a3-0fe36841160b"},"surfaceOp":"append"}
 {"type":"session/title","seq":7,"time":1785730689193,"data":{"title":"Read nested/task.txt, then read scope</s","messageSeqs":[4],"source":{"kind":"fallback"}}}
 {"type":"request/header","seq":8,"time":1785498790358,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
 {"type":"request/context","seq":9,"time":1785730689194,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
@@ -14,32 +14,33 @@
 {"type":"assistant/chunk","seq":12,"time":1784903339801,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}}}}
 {"type":"assistant/chunk","seq":13,"time":1785498790358,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
 {"type":"assistant/chunk","seq":14,"time":1785730689194,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":15,"time":1785730689194,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"cb229812-91a1-4aa6-8bce-d3b8d032f6dd"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}
+{"type":"assistant/message","seq":15,"time":1785730689194,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"9e9648c4-949e-4cf1-b9ef-0eb65897d36b"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[10,11,12,13,14],"surfaceOp":"append"}
 {"type":"tool/call","seq":16,"time":1785730689195,"data":{"turn":1,"step":1,"callId":"call_workspace_read","name":"read","arguments":"{\"file_path\":\"nested/task.txt\"}"}}
-{"type":"tool/result","seq":17,"time":1785730689204,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_workspace_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_read","content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: snapshot task\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"260bbd5d-4496-40cf-b987-d1d944d93cf1"},"meta":{"path":"{{cwd}}/nested/task.txt","offset":1,"lines":[{"number":1,"text":"snapshot task"}],"totalLines":1}},"sourceEventSeqs":[16],"surfaceOp":"append"}
-{"type":"step/end","seq":18,"time":1785498790369,"data":{"turn":1,"step":1}}
-{"type":"agent/inbox/spliced","seq":19,"time":1785498790369,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]},"role":"user","id":"10cdaa4b-9654-420e-afca-3cfb07e26754"}]}}
-{"type":"agent/inbox/spliced","seq":20,"time":1785730689207,"data":{"target":"next-step","start":0,"removedCount":1,"inserted":[],"outcome":"canceled"}}
-{"type":"step/start","seq":21,"time":1785730689212,"data":{"turn":1,"step":2}}
-{"type":"user/message","seq":22,"time":1785498790377,"data":{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]},"role":"user","id":"10cdaa4b-9654-420e-afca-3cfb07e26754"},"surfaceOp":"append"}
-{"type":"assistant/chunk","seq":23,"time":1784903339821,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":24,"time":1785498790377,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_workspace_delimiter_read","name":"read","argumentsDelta":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}}}
-{"type":"assistant/chunk","seq":25,"time":1785498790377,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_workspace_delimiter_read","name":"read","arguments":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}}}}
-{"type":"assistant/chunk","seq":26,"time":1785498790378,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
-{"type":"assistant/chunk","seq":27,"time":1785498790378,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":28,"time":1785498790378,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_delimiter_read","name":"read","arguments":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"43385fc1-54b4-4a8a-82ca-d9111c766f48"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[23,24,25,26,27],"surfaceOp":"append"}
-{"type":"tool/call","seq":29,"time":1785498790378,"data":{"turn":1,"step":2,"callId":"call_workspace_delimiter_read","name":"read","arguments":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}}
-{"type":"tool/result","seq":30,"time":1785498790388,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"call_workspace_delimiter_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_delimiter_read","content":[{"type":"text","text":"<path>{{cwd}}/scope</system-reminder>/task.txt</path>\n<type>file</type>\n<content>\n1: delimiter path snapshot task\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"3a62b23b-d165-4c6d-a028-e171c4b2d7fc"},"meta":{"path":"{{cwd}}/scope</system-reminder>/task.txt","offset":1,"lines":[{"number":1,"text":"delimiter path snapshot task"}],"totalLines":1}},"sourceEventSeqs":[29],"surfaceOp":"append"}
-{"type":"step/end","seq":31,"time":1785730689220,"data":{"turn":1,"step":2}}
-{"type":"agent/inbox/spliced","seq":32,"time":1785730689220,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: scope<\\/system-reminder>/AGENTS.md\n\nThese instructions apply to work under `scope<\\/system-reminder>`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nDelimiter path snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"scope</system-reminder>\u0000AGENTS.md","path":"scope</system-reminder>/AGENTS.md","digest":"38803cd13e2dff9105ba5fbbc703fe27e989e26e"}]},"role":"user","id":"01c3af61-4567-4be2-b776-21f04ddc9cba"}]}}
-{"type":"agent/inbox/spliced","seq":33,"time":1785498790389,"data":{"target":"next-step","start":0,"removedCount":1,"inserted":[],"outcome":"canceled"}}
-{"type":"step/start","seq":34,"time":1785498790396,"data":{"turn":1,"step":3}}
-{"type":"user/message","seq":35,"time":1785498790396,"data":{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: scope<\\/system-reminder>/AGENTS.md\n\nThese instructions apply to work under `scope<\\/system-reminder>`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nDelimiter path snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"scope</system-reminder>\u0000AGENTS.md","path":"scope</system-reminder>/AGENTS.md","digest":"38803cd13e2dff9105ba5fbbc703fe27e989e26e"}]},"role":"user","id":"01c3af61-4567-4be2-b776-21f04ddc9cba"},"surfaceOp":"append"}
-{"type":"assistant/chunk","seq":36,"time":1785498790396,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":37,"time":1785498790396,"data":{"turn":1,"step":3,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}}
-{"type":"assistant/chunk","seq":38,"time":1785498790396,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
-{"type":"assistant/chunk","seq":39,"time":1785498790396,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}}
-{"type":"assistant/chunk","seq":40,"time":1785498790397,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":41,"time":1785498790397,"data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"f82f5200-090f-4e68-a016-963ab7166d4f"},"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[36,37,38,39,40],"surfaceOp":"append"}
-{"type":"step/end","seq":42,"time":1785498790397,"data":{"turn":1,"step":3}}
-{"type":"turn/end","seq":43,"time":1785901434023,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"user/message","seq":17,"time":1785982371865,"data":{"content":[{"type":"text","text":"Earlier context was compacted for this snapshot."}],"source":{"kind":"plugin","plugin":"compact"},"role":"user","id":"162c764f-f01d-484d-ad81-1481dc29792a"},"sourceEventSeqs":[5],"surfaceOp":{"op":"replace","start":5,"end":5}}
+{"type":"tool/result","seq":18,"time":1785982371865,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"call_workspace_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_read","content":[{"type":"text","text":"<path>{{cwd}}/nested/task.txt</path>\n<type>file</type>\n<content>\n1: snapshot task\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"a46fded2-333a-4fb2-b01e-28520bffbc21"},"meta":{"path":"{{cwd}}/nested/task.txt","offset":1,"lines":[{"number":1,"text":"snapshot task"}],"totalLines":1}},"sourceEventSeqs":[16],"surfaceOp":"append"}
+{"type":"step/end","seq":19,"time":1785982371865,"data":{"turn":1,"step":1}}
+{"type":"agent/inbox/spliced","seq":20,"time":1785730689207,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nRoot snapshot instruction.\n\n</system-reminder>"},{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".dsh-project\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2e18766c26603608f321508caae00ea8f4434d59"},{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]},"role":"user","id":"09640903-80ea-4eb6-8635-90ddfb4e24e4"}]}}
+{"type":"agent/inbox/spliced","seq":21,"time":1785982371873,"data":{"target":"next-step","start":0,"removedCount":1,"inserted":[],"outcome":"canceled"}}
+{"type":"step/start","seq":22,"time":1785982371873,"data":{"turn":1,"step":2}}
+{"type":"user/message","seq":23,"time":1785982371873,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nRoot snapshot instruction.\n\n</system-reminder>"},{"type":"text","text":"<system-reminder>\nAdditional instructions from: nested/AGENTS.md\n\nThese instructions apply to work under `nested`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nNested snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".dsh-project\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"2e18766c26603608f321508caae00ea8f4434d59"},{"action":"set","scope":"nested\u0000AGENTS.md","path":"nested/AGENTS.md","digest":"c446df9a85c7e73a3055f394a4822a19ac9ead5a"}]},"role":"user","id":"09640903-80ea-4eb6-8635-90ddfb4e24e4"},"surfaceOp":"append"}
+{"type":"assistant/chunk","seq":24,"time":1785498790377,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":25,"time":1785498790377,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_workspace_delimiter_read","name":"read","argumentsDelta":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}}}
+{"type":"assistant/chunk","seq":26,"time":1785498790378,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_workspace_delimiter_read","name":"read","arguments":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}}}}
+{"type":"assistant/chunk","seq":27,"time":1785498790378,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":28,"time":1785982371874,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":29,"time":1785982371874,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_workspace_delimiter_read","name":"read","arguments":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"ba85f14b-5ff0-4b71-a3f8-0d9ea7f4893d"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[24,25,26,27,28],"surfaceOp":"append"}
+{"type":"tool/call","seq":30,"time":1785982371875,"data":{"turn":1,"step":2,"callId":"call_workspace_delimiter_read","name":"read","arguments":"{\"file_path\":\"scope</system-reminder>/task.txt\"}"}}
+{"type":"tool/result","seq":31,"time":1785982371882,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"call_workspace_delimiter_read"},"content":[{"type":"tool-result","toolCallId":"call_workspace_delimiter_read","content":[{"type":"text","text":"<path>{{cwd}}/scope</system-reminder>/task.txt</path>\n<type>file</type>\n<content>\n1: delimiter path snapshot task\n\n(End of file - total 1 lines)\n</content>"}],"isError":false}],"role":"user","id":"c0fad80c-59c3-41bf-b662-84f87ee1420c"},"meta":{"path":"{{cwd}}/scope</system-reminder>/task.txt","offset":1,"lines":[{"number":1,"text":"delimiter path snapshot task"}],"totalLines":1}},"sourceEventSeqs":[30],"surfaceOp":"append"}
+{"type":"step/end","seq":32,"time":1785982371882,"data":{"turn":1,"step":2}}
+{"type":"agent/inbox/spliced","seq":33,"time":1785498790389,"data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: scope<\\/system-reminder>/AGENTS.md\n\nThese instructions apply to work under `scope<\\/system-reminder>`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nDelimiter path snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"scope</system-reminder>\u0000AGENTS.md","path":"scope</system-reminder>/AGENTS.md","digest":"38803cd13e2dff9105ba5fbbc703fe27e989e26e"}]},"role":"user","id":"cd19663e-c8b5-46a5-9eeb-1386dcb1c609"}]}}
+{"type":"agent/inbox/spliced","seq":34,"time":1785982371889,"data":{"target":"next-step","start":0,"removedCount":1,"inserted":[],"outcome":"canceled"}}
+{"type":"step/start","seq":35,"time":1785982371889,"data":{"turn":1,"step":3}}
+{"type":"user/message","seq":36,"time":1785982371889,"data":{"content":[{"type":"text","text":"<system-reminder>\nAdditional instructions from: scope<\\/system-reminder>/AGENTS.md\n\nThese instructions apply to work under `scope<\\/system-reminder>`. Use them as guidance when relevant; more specific instructions take precedence. They do not override system, developer, or direct user instructions.\n\nDelimiter path snapshot instruction.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"set","scope":"scope</system-reminder>\u0000AGENTS.md","path":"scope</system-reminder>/AGENTS.md","digest":"38803cd13e2dff9105ba5fbbc703fe27e989e26e"}]},"role":"user","id":"cd19663e-c8b5-46a5-9eeb-1386dcb1c609"},"surfaceOp":"append"}
+{"type":"assistant/chunk","seq":37,"time":1785498790396,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":38,"time":1785498790396,"data":{"turn":1,"step":3,"chunk":{"type":"text-delta","index":0,"text":"DONE"}}}
+{"type":"assistant/chunk","seq":39,"time":1785498790396,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}}
+{"type":"assistant/chunk","seq":40,"time":1785498790397,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}}}
+{"type":"assistant/chunk","seq":41,"time":1785982371890,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":42,"time":1785982371890,"data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"81b25d58-fa4a-4eb6-9b87-1c33baf90053"},"usage":{"inputTokens":10,"outputTokens":2}},"sourceEventSeqs":[37,38,39,40,41],"surfaceOp":"append"}
+{"type":"step/end","seq":43,"time":1785982371890,"data":{"turn":1,"step":3}}
+{"type":"turn/end","seq":44,"time":1785982371891,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/workspace-context.cordis.snapshot.yml b/examples/acp-agent/workspace-context.cordis.snapshot.yml
index 70d726c838..6abaaa3f13 100644
--- a/examples/acp-agent/workspace-context.cordis.snapshot.yml
+++ b/examples/acp-agent/workspace-context.cordis.snapshot.yml
@@ -28,3 +28,5 @@
       - insert:
           - id: llm-replay
             name: '@deepseek-ai/dsh-llm-replay'
+          - id: workspace-context-compaction
+            name: './tests/fixtures/workspace-context-compaction.ts'
diff --git a/examples/headless-agent/composition.md b/examples/headless-agent/composition.md
index 7fd2c936a2..6ef139d3d9 100644
--- a/examples/headless-agent/composition.md
+++ b/examples/headless-agent/composition.md
@@ -31,6 +31,8 @@ flowchart LR
   cfg --> plugin_headless_token_meter
   plugin_headless_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
   cfg --> plugin_headless_compact_basic
+  plugin_headless_session_projection["session-projection<br/>@deepseek-ai/dsh-session-projection"]
+  cfg --> plugin_headless_session_projection
   plugin_headless_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
   cfg --> plugin_headless_subagent
   plugin_headless_subagent_spawn["subagent-spawn<br/>@deepseek-ai/dsh-subagent-spawn"]
@@ -71,6 +73,7 @@ flowchart LR
 | `cli-agent` | `@deepseek-ai/dsh-cli-demo` |
 | `token-meter` | `@deepseek-ai/dsh-token-meter` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
+| `session-projection` | `@deepseek-ai/dsh-session-projection` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
 | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
diff --git a/examples/headless-agent/cordis.yml b/examples/headless-agent/cordis.yml
index 937c976c67..f2d197d662 100644
--- a/examples/headless-agent/cordis.yml
+++ b/examples/headless-agent/cordis.yml
@@ -71,6 +71,11 @@
     maxTokens: 8192
     compactionRetries: 1
 
+# Projection registry: durable subagent identity (mode/label) folds through
+# its registered units; subagent catalog reads fail loud without the capability.
+- id: session-projection
+  name: '@deepseek-ai/dsh-session-projection'
+
 # Expose fresh-child `spawn` and completed-prefix `fork` through independent
 # in-process backends.
 - id: subagent
@@ -129,6 +134,8 @@
 # `todo_write` replaces the logged whole list.
 - id: tool-todo
   name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
 
 # Policy loads before the model-facing filesystem tools so writes and edits
 # require an observed file. Relative paths resolve from the process cwd.
diff --git a/examples/headless-agent/subagent-diagnostic.cordis.snapshot.yml b/examples/headless-agent/subagent-diagnostic.cordis.snapshot.yml
new file mode 100644
index 0000000000..2e89c3753d
--- /dev/null
+++ b/examples/headless-agent/subagent-diagnostic.cordis.snapshot.yml
@@ -0,0 +1,44 @@
+# Keyless real-Loader composition for the descriptor-less cold-child
+# diagnostic snapshot. The seeded parent owns one session-backed child whose
+# log carries `origin: 'subagent'` but no descriptor event, so the projection
+# fold produces no identity and `list_agents` must surface the child as a
+# `[diagnostic: corrupt]` row instead of silently dropping it.
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: none
+
+# file/override both default to their DSH_SNAPSHOT_* env vars.
+- id: replay
+  name: '@deepseek-ai/dsh-llm-replay'
+
+# This scenario probes the subagent catalog only, so the bash/filesystem
+# stacks are absent; the bundle must opt out of the tools that would wait
+# forever for executors this tree never mounts.
+- id: agent
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    agents: []
+    workspaceContext: false
+    skills:
+      enabled: false
+    toolBash: false
+    toolTasks: false
+    goals: false
+
+# Projection registry: the cold child's identity fold runs through it; the
+# catalog read fails loud when the capability is absent.
+- id: session-projection
+  name: '@deepseek-ai/dsh-session-projection'
+
+- id: subagent
+  name: '@deepseek-ai/dsh-subagent'
+
+- id: tool-subagent-list-agents
+  name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+# Await the persisted resume before the headless driver inspects root agents.
+- id: resumed-agent
+  name: './tests/fixtures/subagent-diagnostic-agent.ts'
diff --git a/examples/headless-agent/tests/fixtures/subagent-diagnostic-agent.ts b/examples/headless-agent/tests/fixtures/subagent-diagnostic-agent.ts
new file mode 100644
index 0000000000..f77afe7e0a
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/subagent-diagnostic-agent.ts
@@ -0,0 +1,26 @@
+/**
+ * Loader fixture that resumes the seeded diagnostic-scenario parent before
+ * CLI dispatch, so `list_agents` runs against its pre-seeded cold child.
+ * @module subagent-diagnostic-agent
+ */
+
+import type { Context } from 'cordis'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+
+/** Fixture plugin name. */
+export const name = 'subagent-diagnostic-agent'
+/** Services that must exist before the fixture resumes its agent. */
+export const inject = ['agents', 'agentLoop', 'sessionPersistence']
+
+/**
+ * Resume the seeded session and bind its exact handle to this fixture's lifetime.
+ * @param ctx - settled agent and persistence services from the Loader tree.
+ * @returns after the resumed agent is published.
+ */
+export async function apply(ctx: Context): Promise<void> {
+  const handle = await ctx.agents.resume({
+    resumeSessionId: 'subagent-diagnostic-parent' as SessionId,
+    agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+  })
+  ctx.effect(() => () => handle.dispose(), 'subagent-diagnostic-agent.handle')
+}
diff --git a/examples/headless-agent/tests/fixtures/workspace-context-resume-agent.ts b/examples/headless-agent/tests/fixtures/workspace-context-resume-agent.ts
new file mode 100644
index 0000000000..4cdf7d157a
--- /dev/null
+++ b/examples/headless-agent/tests/fixtures/workspace-context-resume-agent.ts
@@ -0,0 +1,25 @@
+/**
+ * Loader fixture that resumes the seeded workspace-context session.
+ * @module workspace-context-resume-agent
+ */
+
+import type { Context } from 'cordis'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+
+/** Fixture plugin name. */
+export const name = 'workspace-context-resume-agent'
+/** Services that must exist before the fixture resumes its agent. */
+export const inject = ['agents', 'agentLoop', 'sessionPersistence']
+
+/**
+ * Resume the seeded session and bind its handle to this fixture's lifetime.
+ * @param ctx - settled agent and persistence services from the Loader tree.
+ * @returns after the resumed agent is published.
+ */
+export async function apply(ctx: Context): Promise<void> {
+  const handle = await ctx.agents.resume({
+    resumeSessionId: 'workspace-context-resume' as SessionId,
+    agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+  })
+  ctx.effect(() => () => handle.dispose(), 'workspace-context-resume-agent.handle')
+}
diff --git a/examples/headless-agent/tests/harness.ts b/examples/headless-agent/tests/harness.ts
index b57a4c2d2d..9b953256b7 100644
--- a/examples/headless-agent/tests/harness.ts
+++ b/examples/headless-agent/tests/harness.ts
@@ -30,8 +30,9 @@ export const SYSTEM_PROMPT = 'You are a coding agent. Use bash for file operatio
 /** System prompt for the todo_write e2e: nudges the model to plan with the tool. */
 export const TODO_SYSTEM_PROMPT = 'You are a coding agent. For multi-step work, '
   + 'use the todo_write tool to track a task list: send the WHOLE list each call, '
-  + 'keep at most one task in_progress (exactly one while work remains), and mark '
-  + 'a task completed as soon as it is done.'
+  + 'mark every task being actively worked on in_progress (several at once when '
+  + 'work runs in parallel, at least one while work remains), and mark a task '
+  + 'completed as soon as it is done.'
 
 /** Options for {@link codingHarness}. */
 export interface CodingHarnessOptions {
@@ -65,7 +66,7 @@ export async function codingHarness(workdir: string, options: CodingHarnessOptio
   await ctx.plugin(BashEnvPlugin)
   await ctx.plugin(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 })
   await ctx.plugin(ToolBash)
-  await ctx.plugin(ToolTodo)
+  await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
   // Compaction is opt-in: only the compaction e2e loads the reusable meter and backend.
   if (options.compact !== undefined) {
     await ctx.plugin(TokenMeterService)
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
index 10c380057d..ff58bd3a43 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
@@ -6,7 +6,7 @@
 {"type":"step/start","seq":4,"time":1785730501506,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":5,"time":1785730501506,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"fc62f9e7-b8f6-441f-9ee8-17f1f9e4feca"},"surfaceOp":"append"}
 {"type":"session/title","seq":6,"time":1785730501506,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498583897,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":7,"time":1785498583897,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":8,"time":1785730501507,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":10,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
index d514d19b96..02c779e8f4 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
@@ -6,7 +6,7 @@
 {"type":"step/start","seq":4,"time":1785730501645,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":5,"time":1785730501645,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"093bfc20-c6fc-4573-b172-2c6ca40c188b"},"surfaceOp":"append"}
 {"type":"session/title","seq":6,"time":1785730501645,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498584067,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":7,"time":1785498584067,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":8,"time":1785730501646,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
 {"type":"assistant/chunk","seq":10,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
index fe5fa4dc8d..a168db4b8b 100644
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -5,7 +5,7 @@
 {"type":"step/start","seq":3,"time":1783957884486,"data":{"turn":1,"step":1}}
 {"type":"user/message","seq":4,"time":1785498583779,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: try a no-op temporary Cordis Plugin named snapshot-marker; use run_code to inspect the live temporary Plugins through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; stop dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"},"role":"user","id":"d2f4f71c-78bc-4a22-908d-c08fbb3ab9ef"},"surfaceOp":"append"}
 {"type":"session/title","seq":5,"time":1785498583779,"data":{"title":"Run this advanced flow exactly","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":6,"time":1785498583782,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":6,"time":1785498583782,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}.\n\nVerify your work by running the code or tests. Keep answers brief and factual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.\n\n## Writing code for run_code\n\nPass `run_code` the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped). Inside the program:\n\n- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools[\"my-tool\"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.\n- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.\n- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.\n- Emit results with `return` and/or `console.log(...)`. ONLY what you print or return comes back to you — intermediate tool results never enter the conversation, so extract just what you need.\n\nThe available tools:\n\n```ts\ntype JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }\n\ninterface ToolArgsMap {\n  /** Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. */\n  bash: {\n    /** The bash command to execute. */\n    command: string;\n    /** Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\". */\n    description: string;\n    /** Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry. */\n    timeoutMs?: number;\n    /** Working directory for this command. Defaults to the session workspace; a relative path is resolved against it. */\n    workdir?: string;\n    /** Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */\n  cordis_inspect: {\n    /** Limit the report to one section. Omit for all sections. */\n    what?: \"services\" | \"plugins\" | \"tools\" | \"temporary\" | \"api\" | \"events\";\n    /** Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\". */\n    name?: string;\n  } & Record<string, JsonValue>;\n  /** Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */\n  cordis_mount: {\n    /** JavaScript body returning a temporary Plugin; evaluated now and saved nowhere. */\n    code: string;\n  } & Record<string, JsonValue>;\n  /** Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins. */\n  cordis_unmount: {\n    /** The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart. */\n    id: string;\n  } & Record<string, JsonValue>;\n  /** Edit an existing UTF-8 text file by replacing literal text. */\n  edit: {\n    /** Path to edit, resolved by the filesystem backend. */\n    file_path: string;\n    /** Literal text to replace. Must match exactly. */\n    old_string: string;\n    /** Literal replacement text. Use an empty string to delete the match. */\n    new_string: string;\n    /** Replace all matches. Defaults to false; when false, old_string must appear exactly once. */\n    replace_all?: boolean;\n  } & Record<string, JsonValue>;\n  /** Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools. */\n  ralph: {\n    /** The immutable completion objective for every fresh Ralph round. */\n    objective: string;\n    /** Optional positive safe-integer round cap, bounded by the deployment ceiling. */\n    maxRounds?: number;\n  } & Record<string, JsonValue>;\n  /** Read a UTF-8 text file and return line-numbered content. */\n  read: {\n    /** Path to read, resolved by the filesystem backend. */\n    file_path: string;\n    /** 1-based first line to return. Defaults to 1. */\n    offset?: number;\n    /** Maximum number of lines to return. Defaults to 2000. */\n    limit?: number;\n  } & Record<string, JsonValue>;\n  /** Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered. */\n  send_message: {\n    /** The subagent id returned when the background subagent was started. */\n    subagent_id: string;\n    /** The message to deliver to the subagent. */\n    message: string;\n  } & Record<string, JsonValue>;\n  /** Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill. */\n  skill: {\n    /** The exact skill name from the available skills list. */\n    name: string;\n  } & Record<string, JsonValue>;\n  /** Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work. */\n  subagent_fork: {\n    /** A short (3-5 word) description of the delegated task, for display. */\n    description: string;\n    /** The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new. */\n    prompt: string;\n    /** Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message. */\n    run_in_background?: boolean;\n  } & Record<string, JsonValue>;\n  /** Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops. */\n  task_kill: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Optional short reason, recorded in the log and forwarded to the task. */\n    reason?: string;\n  } & Record<string, JsonValue>;\n  /** List your background tasks (running and finished) with their ids, kinds, and statuses. */\n  task_list: Record<string, JsonValue>;\n  /** Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap. */\n  task_output: {\n    /** Task id returned by the tool that started the background work. */\n    task_id: string;\n    /** Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive. */\n    wait?: boolean;\n    /** Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum. */\n    timeout_ms?: number;\n  } & Record<string, JsonValue>;\n  /** Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished). */\n  todo_write: {\n    /** The COMPLETE task list, replacing any previous list. */\n    todos: ({\n      /** What the task is — a short imperative line. */\n      content: string;\n      /** pending (not started) | in_progress (now) | completed (done). */\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n  } & Record<string, JsonValue>;\n  /** Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn. The workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result. Script-body hooks: - `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly. - `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages. - `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`. - `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim. Misused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`. Constraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes. */\n  workflow: {\n    /** The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`). */\n    script: string;\n    /** The workflow identity block (plain JSON — never code). */\n    meta: {\n      /** Short kebab-case workflow name. */\n      name: string;\n      /** One-line description of what the workflow does. */\n      description: string;\n      /** Optional guidance on when this workflow applies. */\n      whenToUse?: string;\n      /** Optional phase declarations matched by phase() calls. */\n      phases?: ({\n        /** The phase title phase() calls match by exact string. */\n        title: string;\n        /** Optional one-line description of the phase. */\n        detail?: string;\n        /** Optional provider override this phase is expected to use. */\n        provider?: string;\n        /** Optional model override this phase is expected to use. */\n        model?: string;\n      } & Record<string, JsonValue>)[];\n    } & Record<string, JsonValue>;\n    /** Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}). */\n    args?: Record<string, JsonValue>;\n  } & Record<string, JsonValue>;\n  /** Create or fully replace a UTF-8 text file. */\n  write: {\n    /** Path to write, resolved by the filesystem backend. */\n    file_path: string;\n    /** Full UTF-8 text content to write. */\n    content: string;\n  } & Record<string, JsonValue>;\n}\n\ninterface ToolOutputMap {\n  bash: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"foreground\";\n    exitCode: number | null;\n    signal: string | null;\n    timedOut: boolean;\n    aborted: boolean;\n    timeoutMs: number;\n    stdout: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    stderr: {\n      text: string;\n      truncated: boolean;\n      spillPath?: string;\n    };\n    sandbox?: {\n      mode: string;\n      denied: boolean;\n      enforcement?: string;\n      runnerFailed?: boolean;\n    };\n  };\n  cordis_inspect: string;\n  cordis_mount: {\n    id: string;\n    pluginName: string;\n    state: \"pending\" | \"loading\" | \"active\" | \"failed\" | \"disposed\" | \"unloading\";\n    provides: string[];\n    waitingFor: string[];\n  };\n  cordis_unmount: {\n    id: string;\n    pluginName: string;\n  };\n  edit: {\n    path: string;\n    before: string;\n    after: string;\n  };\n  ralph: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  read: {\n    path: string;\n    offset: number;\n    lines: {\n      number: number;\n      text: string;\n    }[];\n    totalLines: number;\n  };\n  send_message: {\n    messageId: string;\n  };\n  skill: {\n    name: string;\n    provider: string;\n    resourceBase?: {\n      kind: \"directory\";\n      path: string;\n    } | {\n      kind: \"url\";\n      url: string;\n    } | {\n      kind: \"opaque\";\n      description: string;\n    };\n    content: string;\n  };\n  subagent: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  subagent_fork: {\n    kind: \"background\";\n    taskId: string;\n  } | {\n    kind: \"continuable\";\n    subagentId: string;\n  } | {\n    kind: \"foreground\";\n    runId: string;\n    output: JsonValue[];\n  };\n  task_kill: {\n    outcome: \"cancellation-requested\" | \"already-finished\";\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  task_list: ({\n    id: string;\n    kind: string;\n    label: string;\n    status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n    detail?: string;\n    startedAt: number;\n    finishedAt?: number;\n  })[];\n  task_output: {\n    text: string;\n    task: {\n      id: string;\n      kind: string;\n      label: string;\n      status: \"running\" | \"stopping\" | \"completed\" | \"killed\" | \"failed\";\n      detail?: string;\n      startedAt: number;\n      finishedAt?: number;\n    };\n  };\n  todo_write: {\n    todos: ({\n      content: string;\n      status: \"pending\" | \"in_progress\" | \"completed\";\n    })[];\n    counts: {\n      pending: number;\n      inProgress: number;\n      completed: number;\n    };\n  };\n  workflow: {\n    runId: string;\n    agentsStarted: number;\n    result: JsonValue;\n  };\n  write: {\n    path: string;\n    operation: \"create\" | \"update\";\n    before: string | null;\n    after: string;\n  };\n}\n\ntype ToolName = keyof ToolOutputMap\n\ndeclare class ToolCallError extends Error {\n  readonly name: \"ToolCallError\";\n  readonly toolName: ToolName;\n}\n\ndeclare const tools: {\n  [K in ToolName]: (args: ToolArgsMap[K]) => Promise<ToolOutputMap[K]>;\n}\n```","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"cordis_inspect","description":"Inspect the live Cordis runtime in the current DSH process. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (all live plugin fibers with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `temporary` (only temporary Plugins created by cordis_mount: id, name, state, provided services, awaited services, and lifetime), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Temporary Plugins exist only in memory, remain active across later turns, and disappear after cordis_unmount, toolset unload, or DSH restart; they are not restored automatically. The `temporary` section is a subset of `plugins`. Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.","parameters":{"type":"object","properties":{"what":{"type":"string","description":"Limit the report to one section. Omit for all sections.","enum":["services","plugins","tools","temporary","api","events"]},"name":{"type":"string","description":"Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."}}}},{"name":"cordis_mount","description":"Mount a temporary Cordis Plugin in the current DSH process. This creates an in-memory runtime Plugin, not an installed or configured Plugin. It remains active across later turns until cordis_unmount, toolset unload, or DSH restart. It does not create files, install a package, change cordis.yml or personal/project config, survive restart, or automatically become permanent. To keep it, ask the Agent to implement a normal local, project, or repository Plugin through the regular development workflow. It may affect other sessions in the same process; the sandbox is not a security boundary, and injected services reach the real runtime. `code` runs now as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:\"api\" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:\"events\"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, output: { schema: { type: 'string' }, render(_args, value) { return [{ type: 'text', text: value }] } }, async execute(args) { return args.text } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'integer'|'boolean'|'null'|'object'|'array'|'json', required?: true, description?, enum?, const?, items?, properties? }; every direct DSL object declares additionalProperties: true|false, and oneOf: [schema, schema, ...] replaces type for an exact-one union. A raw JSON-Schema { type: 'object', properties, required?: […] } wrapper is also accepted with open-by-default objects. A tool's `execute` MUST return the lossless JSON value declared by `output.schema`; `output.render(args, value)` separately returns Native/model content blocks. Temporary Plugins can COMPOSE: one Plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically by cordis_unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned when unmounted) — cordis_inspect what:\"api\" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"JavaScript body returning a temporary Plugin; evaluated now and saved nowhere."}},"required":["code"]}},{"name":"cordis_unmount","description":"Unmount a current-process temporary Plugin created by cordis_mount. Waits for its tools, listeners, services, timers, and other owned effects to clean up completely. Only dyn-N temporary ids are accepted; this cannot remove Loader, configured, or installed Plugins.","parameters":{"type":"object","properties":{"id":{"type":"string","description":"The temporary Plugin id returned by cordis_mount (for example \"dyn-1\"); valid only in this process and invalid after unmount or restart."}},"required":["id"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"run_code","description":"Execute a TypeScript program against the available tools. Write the BODY of an async function (erasable syntax only; top-level `await` and `return` work) and call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return comes back — curate it.","parameters":{"type":"object","properties":{"code":{"type":"string","description":"The program: the body of an async TypeScript function."},"description":{"type":"string","description":"Clear, concise description of what this program does in active voice, 5-10 words (shown in the UI). Examples: \"Count TODO markers across packages\"; \"Read failing test and its fixture\"; \"Rename config key in every cordis.yml\"."}},"required":["code","description"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":7,"time":1785730501403,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":8,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":9,"time":1783950000008,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}
diff --git a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl
index ad7c100179..f4f592570a 100644
--- a/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/pty-tools/session.jsonl
@@ -6,7 +6,7 @@
 {"type":"user/message","seq":4,"time":1785498587436,"data":{"content":[{"type":"text","text":"Exercise the six PTY tools in order, including one missing-session signal error, then reply DONE."}],"source":{"kind":"user"},"role":"user","id":"39f39ecc-5772-4814-8feb-46433c71becd"},"surfaceOp":"append"}
 {"type":"user/message","seq":5,"time":1785730504659,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."}]},"role":"user","id":"a5ae9c04-0652-436f-9b5a-437a3a6ed235"},"surfaceOp":"append"}
 {"type":"session/title","seq":6,"time":1785730504659,"data":{"title":"Exercise the six PTY tools","messageSeqs":[4],"source":{"kind":"fallback"}}}
-{"type":"request/header","seq":7,"time":1785498587438,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse a terminal session only when work needs persistent terminal state or interactive stdin; prefer bash/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"terminal_close","description":"Close one persistent terminal and wait until its captured owned process tree is gone.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."}},"required":["sessionId"]}},{"name":"terminal_list","description":"List persistent terminal sessions owned by the current agent.","parameters":{"type":"object","properties":{}}},{"name":"terminal_open","description":"Create a persistent, owner-isolated terminal session from a registered backend type. Use this for shell or REPL state that must survive across tool calls.","parameters":{"type":"object","properties":{"type":{"type":"string","description":"Registered terminal backend type, usually \"shell\"."},"name":{"type":"string","description":"Optional owner-local display name such as \"main\" or \"gdb\"."},"cwd":{"type":"string","description":"Initial working directory. Defaults to the deployment workspace root."}},"required":["type"]}},{"name":"terminal_read","description":"Read a bounded page of retained output from a persistent terminal without sending input.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"offset":{"type":"number","description":"Newest-relative line offset (default 0)."},"count":{"type":"number","description":"Requested line count (default 500; backend caps apply)."}},"required":["sessionId"]}},{"name":"terminal_send","description":"Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id returned by terminal_open or terminal_list."},"text":{"type":"string","description":"UTF-8 text to write to the terminal."},"submit":{"type":"boolean","description":"Submit Enter after text (default true). Set false for control characters or incomplete REPL input."},"run_in_background":{"type":"boolean","description":"Return a task id immediately; collect with task_output or stop with task_kill."}},"required":["sessionId","text"]}},{"name":"terminal_signal","description":"Send an allowed signal to the current foreground process group of a persistent terminal.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"signal":{"type":"string","description":"Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.","enum":["SIGINT","SIGTERM","SIGKILL","SIGTSTP","SIGHUP"]}},"required":["sessionId","signal"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
+{"type":"request/header","seq":7,"time":1785498587438,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou are headless-agent, a coding assistant powered by the deepseek-v4-flash model.\n\nVerify your work by running the code or tests. Keep answers brief and\nfactual.\n\n\nUse the read tool — not shell commands like cat — to inspect text files. Results include line numbers. Use offset and limit to continue reading large files.\n\nUse the write tool to create files or completely replace file contents. Existing files are overwritten, so read an existing file first (the default fs-policy requires it) and prefer edit for targeted changes.\n\nUse the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-policy requires it), unless you just created or edited it in this session.\n\nCheck the [exit code: N] marker on every bash result; investigate failures before moving on.\n\nUse a terminal session only when work needs persistent terminal state or interactive stdin; prefer bash/read/write/edit for bounded one-shot operations. Track every terminal session id and close sessions that no longer matter. An inferred_idle or timeout result does not prove the foreground command exited.\n\nTrack every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering.\n\nUse the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls.\n\nUse the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.","tools":[{"name":"bash","description":"Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under <mode> mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`.","parameters":{"type":"object","properties":{"command":{"type":"string","description":"The bash command to execute."},"description":{"type":"string","description":"Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"."},"timeoutMs":{"type":"number","description":"Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry."},"workdir":{"type":"string","description":"Working directory for this command. Defaults to the session workspace; a relative path is resolved against it."},"run_in_background":{"type":"boolean","description":"Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies."}},"required":["command","description"]}},{"name":"edit","description":"Edit an existing UTF-8 text file by replacing literal text.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to edit, resolved by the filesystem backend."},"old_string":{"type":"string","description":"Literal text to replace. Must match exactly."},"new_string":{"type":"string","description":"Literal replacement text. Use an empty string to delete the match."},"replace_all":{"type":"boolean","description":"Replace all matches. Defaults to false; when false, old_string must appear exactly once."}},"required":["file_path","old_string","new_string"]}},{"name":"ralph","description":"Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.","parameters":{"type":"object","properties":{"objective":{"type":"string","description":"The immutable completion objective for every fresh Ralph round."},"maxRounds":{"type":"number","description":"Optional positive safe-integer round cap, bounded by the deployment ceiling."}},"required":["objective"]}},{"name":"read","description":"Read a UTF-8 text file and return line-numbered content.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to read, resolved by the filesystem backend."},"offset":{"type":"number","description":"1-based first line to return. Defaults to 1."},"limit":{"type":"number","description":"Maximum number of lines to return. Defaults to 2000."}},"required":["file_path"]}},{"name":"send_message","description":"Send a message to a background subagent by its subagent id, continuing the same conversation. It becomes the subagent's next turn: if it is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. This call returns no answer from the subagent — only confirmation that the message was delivered — so use it to give it more work. A failure means the message was NOT delivered.","parameters":{"type":"object","properties":{"subagent_id":{"type":"string","description":"The subagent id returned when the background subagent was started."},"message":{"type":"string","description":"The message to deliver to the subagent."}},"required":["subagent_id","message"]}},{"name":"skill","description":"Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.","parameters":{"type":"object","properties":{"name":{"type":"string","description":"The exact skill name from the available skills list."}},"required":["name"]}},{"name":"subagent","description":"Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"subagent_fork","description":"Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to start a background subagent that keeps its conversation: you receive only its subagent id, never its result, and it works on its own. Use this for work whose result you do not need returned by this call; `send_message` sends it more work.","parameters":{"type":"object","properties":{"description":{"type":"string","description":"A short (3-5 word) description of the delegated task, for display."},"prompt":{"type":"string","description":"The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."},"run_in_background":{"type":"boolean","description":"Run as a background subagent that keeps its conversation and return only its subagent id. This call never returns its result; send it more work with send_message."}},"required":["description","prompt"]}},{"name":"task_kill","description":"Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"reason":{"type":"string","description":"Optional short reason, recorded in the log and forwarded to the task."}},"required":["task_id"]}},{"name":"task_list","description":"List your background tasks (running and finished) with their ids, kinds, and statuses.","parameters":{"type":"object","properties":{}}},{"name":"task_output","description":"Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.","parameters":{"type":"object","properties":{"task_id":{"type":"string","description":"Task id returned by the tool that started the background work."},"wait":{"type":"boolean","description":"Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive."},"timeout_ms":{"type":"number","description":"Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum."}},"required":["task_id"]}},{"name":"terminal_close","description":"Close one persistent terminal and wait until its captured owned process tree is gone.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."}},"required":["sessionId"]}},{"name":"terminal_list","description":"List persistent terminal sessions owned by the current agent.","parameters":{"type":"object","properties":{}}},{"name":"terminal_open","description":"Create a persistent, owner-isolated terminal session from a registered backend type. Use this for shell or REPL state that must survive across tool calls.","parameters":{"type":"object","properties":{"type":{"type":"string","description":"Registered terminal backend type, usually \"shell\"."},"name":{"type":"string","description":"Optional owner-local display name such as \"main\" or \"gdb\"."},"cwd":{"type":"string","description":"Initial working directory. Defaults to the deployment workspace root."}},"required":["type"]}},{"name":"terminal_read","description":"Read a bounded page of retained output from a persistent terminal without sending input.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"offset":{"type":"number","description":"Newest-relative line offset (default 0)."},"count":{"type":"number","description":"Requested line count (default 500; backend caps apply)."}},"required":["sessionId"]}},{"name":"terminal_send","description":"Send text to a persistent terminal. By default Enter is submitted and the call waits for a prompt, stdin wait, output silence, timeout, or session exit. Background mode returns a task id for task_output/task_kill.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id returned by terminal_open or terminal_list."},"text":{"type":"string","description":"UTF-8 text to write to the terminal."},"submit":{"type":"boolean","description":"Submit Enter after text (default true). Set false for control characters or incomplete REPL input."},"run_in_background":{"type":"boolean","description":"Return a task id immediately; collect with task_output or stop with task_kill."}},"required":["sessionId","text"]}},{"name":"terminal_signal","description":"Send an allowed signal to the current foreground process group of a persistent terminal.","parameters":{"type":"object","properties":{"sessionId":{"type":"string","description":"Terminal session id."},"signal":{"type":"string","description":"Signal to deliver. Shell-targeted SIGKILL is rejected; use terminal_close.","enum":["SIGINT","SIGTERM","SIGKILL","SIGTSTP","SIGHUP"]}},"required":["sessionId","signal"]}},{"name":"todo_write","description":"Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).","parameters":{"type":"object","properties":{"todos":{"type":"array","description":"The COMPLETE task list, replacing any previous list.","items":{"type":"object","additionalProperties":false,"properties":{"content":{"type":"string","description":"What the task is — a short imperative line."},"status":{"type":"string","description":"pending (not started) | in_progress (now) | completed (done).","enum":["pending","in_progress","completed"]}},"required":["content","status"]}}},"required":["todos"]}},{"name":"workflow","description":"Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return <value>` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise<any>` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const/oneOf — no pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise<any[]>` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise<any[]>` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.","parameters":{"type":"object","properties":{"script":{"type":"string","description":"The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return <json-value>`)."},"meta":{"type":"object","description":"The workflow identity block (plain JSON — never code).","additionalProperties":true,"properties":{"name":{"type":"string","description":"Short kebab-case workflow name."},"description":{"type":"string","description":"One-line description of what the workflow does."},"whenToUse":{"type":"string","description":"Optional guidance on when this workflow applies."},"phases":{"type":"array","description":"Optional phase declarations matched by phase() calls.","items":{"type":"object","additionalProperties":true,"properties":{"title":{"type":"string","description":"The phase title phase() calls match by exact string."},"detail":{"type":"string","description":"Optional one-line description of the phase."},"provider":{"type":"string","description":"Optional provider override this phase is expected to use."},"model":{"type":"string","description":"Optional model override this phase is expected to use."}},"required":["title"]}}},"required":["name","description"]},"args":{"type":"object","description":"Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]}).","additionalProperties":true}},"required":["script","meta"]}},{"name":"write","description":"Create or fully replace a UTF-8 text file.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to write, resolved by the filesystem backend."},"content":{"type":"string","description":"Full UTF-8 text content to write."}},"required":["file_path","content"]}}]},"reason":"initial"}}
 {"type":"request/context","seq":8,"time":1785730504660,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
 {"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"pty-spawn","name":"terminal_open","argumentsDelta":"{\"type\":\"shell\",\"name\":\"main\"}"}}}
diff --git a/examples/headless-agent/tests/subagent-diagnostic-snapshots/descriptorless-child/parent.expected.jsonl b/examples/headless-agent/tests/subagent-diagnostic-snapshots/descriptorless-child/parent.expected.jsonl
new file mode 100644
index 0000000000..edf331d8e3
--- /dev/null
+++ b/examples/headless-agent/tests/subagent-diagnostic-snapshots/descriptorless-child/parent.expected.jsonl
@@ -0,0 +1,31 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1}}
+{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Start a background task."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"turn/end","seq":2,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session/end-seed","seq":3,"time":0,"data":{}}
+{"type":"agent/inbox/spliced","seq":4,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Call list_agents once and report what it shows."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}
+{"type":"turn/start","seq":5,"time":0,"data":{"turn":2}}
+{"type":"agent/inbox/spliced","seq":6,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":7,"time":0,"data":{"turn":2,"step":1}}
+{"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"Call list_agents once and report what it shows."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":9,"time":0,"data":{"title":"Start a background task.","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"request/context","seq":11,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"list-once","name":"list_agents","argumentsDelta":"{}"}}}
+{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"list-once","name":"list_agents","arguments":"{}"}}}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":17,"time":0,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"list-once","name":"list_agents","arguments":"{}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[12,13,14,15,16],"surfaceOp":"append"}
+{"type":"tool/call","seq":18,"time":0,"data":{"turn":2,"step":1,"callId":"list-once","name":"list_agents","arguments":"{}"}}
+{"type":"tool/result","seq":19,"time":0,"data":{"turn":2,"step":1,"message":{"source":{"kind":"tool","callId":"list-once"},"content":[{"type":"tool-result","toolCallId":"list-once","content":[{"type":"text","text":"{{sessionId}} [diagnostic: corrupt]"}],"isError":false}],"role":"user","id":"{{sessionId}}"}},"sourceEventSeqs":[18],"surfaceOp":"append"}
+{"type":"step/end","seq":20,"time":0,"data":{"turn":2,"step":1}}
+{"type":"step/start","seq":21,"time":0,"data":{"turn":2,"step":2}}
+{"type":"assistant/chunk","seq":22,"time":0,"data":{"turn":2,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":2,"step":2,"chunk":{"type":"text-delta","index":0,"text":"The stored subagent is unreadable. PARENT_DONE"}}}
+{"type":"assistant/chunk","seq":24,"time":0,"data":{"turn":2,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"The stored subagent is unreadable. PARENT_DONE"}}}}
+{"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":2,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":2,"step":2,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":27,"time":0,"data":{"turn":2,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"The stored subagent is unreadable. PARENT_DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[22,23,24,25,26],"surfaceOp":"append"}
+{"type":"step/end","seq":28,"time":0,"data":{"turn":2,"step":2}}
+{"type":"turn/end","seq":29,"time":0,"data":{"turn":2,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/subagent-diagnostic-snapshots/descriptorless-child/replay.override.json b/examples/headless-agent/tests/subagent-diagnostic-snapshots/descriptorless-child/replay.override.json
new file mode 100644
index 0000000000..2b9facf71f
--- /dev/null
+++ b/examples/headless-agent/tests/subagent-diagnostic-snapshots/descriptorless-child/replay.override.json
@@ -0,0 +1 @@
+[{"kind": "chunks", "chunks": [{"type": "block-start", "index": 0, "blockType": "tool-call"}, {"type": "tool-call-delta", "index": 0, "id": "list-once", "name": "list_agents", "argumentsDelta": "{}"}, {"type": "block-end", "index": 0, "block": {"type": "tool-call", "id": "list-once", "name": "list_agents", "arguments": "{}"}}, {"type": "usage", "usage": {"inputTokens": 10, "outputTokens": 5}}, {"type": "finish", "reason": {"kind": "tool-calls"}}]}, {"kind": "chunks", "chunks": [{"type": "block-start", "index": 0, "blockType": "text"}, {"type": "text-delta", "index": 0, "text": "The stored subagent is unreadable. PARENT_DONE"}, {"type": "block-end", "index": 0, "block": {"type": "text", "text": "The stored subagent is unreadable. PARENT_DONE"}}, {"type": "usage", "usage": {"inputTokens": 10, "outputTokens": 5}}, {"type": "finish", "reason": {"kind": "stop"}}]}]
diff --git a/examples/headless-agent/tests/subagent-diagnostic.snapshot.ts b/examples/headless-agent/tests/subagent-diagnostic.snapshot.ts
new file mode 100644
index 0000000000..dc978b37f6
--- /dev/null
+++ b/examples/headless-agent/tests/subagent-diagnostic.snapshot.ts
@@ -0,0 +1,119 @@
+/**
+ * Assembled-app regression: a persisted `origin: 'subagent'` child whose log
+ * carries no descriptor event is surfaced by `list_agents` as a
+ * `[diagnostic: corrupt]` row instead of being silently dropped.
+ */
+
+import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import { normalizeSessionLog, scrubRequestHeaders, type NormalizeContext } from '@deepseek-ai/dsh-acp-snapshot'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SESSION_FORMAT_VERSION, SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { describe, expect, it } from 'vitest'
+
+const fixtureDir = fileURLToPath(new URL('./subagent-diagnostic-snapshots/descriptorless-child', import.meta.url))
+const replayOverride = join(fixtureDir, 'replay.override.json')
+const parentExpected = join(fixtureDir, 'parent.expected.jsonl')
+const configPath = fileURLToPath(new URL('../subagent-diagnostic.cordis.snapshot.yml', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const parentId = SessionId('subagent-diagnostic-parent')
+const childId = SessionId('subagent-diagnostic-child')
+const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
+const task = 'Call list_agents once and report what it shows.'
+
+/**
+ * Seed a completed parent turn plus one cold child that durably classifies
+ * as a subagent (`origin`) but never appended its descriptor event — the
+ * publication-window death the diagnostic row exists for.
+ */
+async function seedDescriptorlessChild(root: string, cwd: string): Promise<void> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
+  const parentMeta: SessionHeader = {
+    version: SESSION_FORMAT_VERSION,
+    id: parentId,
+    createdAt: 1,
+    cwd,
+    delegationDepth: 0,
+  }
+  const parentEvents: SessionEvent[] = [
+    { type: 'turn/start', seq: 0, time: 10, data: { turn: 1 } },
+    { type: 'user/message', seq: 1, time: 11, data: createUserMessage({ content: [{ type: 'text', text: 'Start a background task.' }], source: { kind: 'user' } }), surfaceOp: 'append' },
+    { type: 'turn/end', seq: 2, time: 12, data: { turn: 1, reason: { kind: 'completed' } } },
+  ]
+  const childMeta: SessionHeader = {
+    version: SESSION_FORMAT_VERSION,
+    id: childId,
+    createdAt: 2,
+    cwd,
+    parentSession: parentId,
+    origin: 'subagent',
+    delegationDepth: 1,
+  }
+  const childEvents: SessionEvent[] = [
+    { type: 'turn/start', seq: 0, time: 20, data: { turn: 1 } },
+    { type: 'turn/end', seq: 1, time: 21, data: { turn: 1, reason: { kind: 'interrupted' } } },
+  ]
+  try {
+    await ctx.sessionPersistence.create(parentMeta)
+    await ctx.sessionPersistence.append(parentId, parentEvents)
+    await ctx.sessionPersistence.create(childMeta)
+    await ctx.sessionPersistence.append(childId, childEvents)
+  } finally {
+    await ctx.fiber.dispose()
+  }
+}
+
+describe('descriptor-less cold child diagnostic snapshot', () => {
+  it('surfaces the unreadable child as a corrupt diagnostic through the assembled headless app', async () => {
+    let cwd = ''
+    const result = await runLoaderSmoke({
+      label: 'subagent diagnostic headless stream-json snapshot',
+      tempDirPrefix: 'dsh-subagent-diag-',
+      binScript,
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'stream-json', task],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT_FILE: replayOverride,
+        DSH_SNAPSHOT_OVERRIDE: replayOverride,
+      },
+      prepare: async (runCwd) => {
+        cwd = runCwd
+        await seedDescriptorlessChild(join(runCwd, '.sessions'), runCwd)
+      },
+      inspect: async (runCwd) => {
+        const sessionsDir = join(runCwd, '.sessions')
+        const files = (await readdir(sessionsDir, { recursive: true })).filter(file => file.endsWith('.jsonl'))
+        const logs = await Promise.all(files.map(async file => readFile(join(sessionsDir, file), 'utf8')))
+        const parent = logs.find(content => content.includes('"subagent-diagnostic-parent"'))
+        if (parent === undefined) throw new Error('missing persisted parent log')
+
+        // THE model-visible fact: the descriptor-less child is reported, not
+        // silently dropped, and its reason is the corrupt classification.
+        expect(parent).toContain(`${childId} [diagnostic: corrupt]`)
+
+        const context: NormalizeContext = { sessionIds: [parentId, childId], cwd }
+        const normalizedParent = scrubRequestHeaders(normalizeSessionLog(parent, context))
+        if (refreshing) {
+          await writeFile(parentExpected, normalizedParent)
+        }
+        expect(normalizedParent).toBe(await readFile(parentExpected, 'utf8'))
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    const records = result.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    expect(records.at(-1)).toMatchObject({
+      type: 'result',
+      sessionId: parentId,
+      output: 'The stored subagent is unreadable. PARENT_DONE',
+    })
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
diff --git a/examples/headless-agent/tests/todo-write.e2e.ts b/examples/headless-agent/tests/todo-write.e2e.ts
index 246857ec47..8b1aa9691e 100644
--- a/examples/headless-agent/tests/todo-write.e2e.ts
+++ b/examples/headless-agent/tests/todo-write.e2e.ts
@@ -31,9 +31,10 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('todo_write: real model records a
 
     agent.followup(createUserMessage({
       content: [{ type: 'text', text:
-      'Use the todo_write tool to record a plan of exactly two steps: first '
-      + '"inspect the failing test" (in_progress), then "apply the fix" (pending). '
-      + 'Send both in one todo_write call, then reply with the single word DONE.' }], source: { kind: 'user' } }))
+      'Use the todo_write tool to record a plan of exactly three steps for work '
+      + 'running in parallel: "inspect the failing test" (in_progress), '
+      + '"watch the background build" (in_progress), then "apply the fix" (pending). '
+      + 'Send all three in one todo_write call, then reply with the single word DONE.' }], source: { kind: 'user' } }))
     await waitForIdle(ctx, agent)
 
     const events = [...agent.session.events]
@@ -42,13 +43,15 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('todo_write: real model records a
     const calls = events.filter(event => event.type === 'tool/call')
     expect(calls.some(event => event.data.name === 'todo_write')).toBe(true)
 
-    // And the tool wrote a todo/write event to the log — verify the WORLD.
+    // And the tool wrote a todo/write event to the log — verify the WORLD,
+    // including two simultaneously in_progress tasks (the parallel contract).
     const todoEvents = events.filter(event => event.type === 'todo/write')
     expect(todoEvents.length).toBeGreaterThan(0)
 
     const todos = (todoEvents.at(-1)!).data.todos
     expect(todos).toEqual([
       { content: 'inspect the failing test', status: 'in_progress' },
+      { content: 'watch the background build', status: 'in_progress' },
       { content: 'apply the fix', status: 'pending' },
     ])
   }, 120_000)
diff --git a/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/replay.jsonl b/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/replay.jsonl
new file mode 100644
index 0000000000..84501283f2
--- /dev/null
+++ b/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/replay.jsonl
@@ -0,0 +1 @@
+{"type":"session","version":0,"id":"workspace-context-resume-replay","createdAt":1,"delegationDepth":0}
diff --git a/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/replay.override.json b/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/replay.override.json
new file mode 100644
index 0000000000..1a431e6dcc
--- /dev/null
+++ b/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/replay.override.json
@@ -0,0 +1,11 @@
+[
+  {
+    "kind": "chunks",
+    "chunks": [
+      { "type": "block-start", "index": 0, "blockType": "text" },
+      { "type": "text-delta", "index": 0, "text": "RESUME_DONE" },
+      { "type": "block-end", "index": 0, "block": { "type": "text", "text": "RESUME_DONE" } },
+      { "type": "finish", "reason": { "kind": "stop" } }
+    ]
+  }
+]
diff --git a/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/session.expected.jsonl b/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/session.expected.jsonl
new file mode 100644
index 0000000000..8753b9241a
--- /dev/null
+++ b/examples/headless-agent/tests/workspace-context-resume-snapshots/offline-edit/session.expected.jsonl
@@ -0,0 +1,22 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1}}
+{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Remember the workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":2,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nOld workspace instruction.\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".git\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"ba65bdb41810f4d0129129dcbd6cadcd643c069d"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"turn/end","seq":3,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session/end-seed","seq":4,"time":0,"data":{}}
+{"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Acknowledge the current workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}
+{"type":"turn/start","seq":6,"time":0,"data":{"turn":2}}
+{"type":"agent/inbox/spliced","seq":7,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":8,"time":0,"data":{"turn":2,"step":1}}
+{"type":"user/message","seq":9,"time":0,"data":{"content":[{"type":"text","text":"Acknowledge the current workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":10,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nUpdated instructions from: AGENTS.md\n\nThis file changed after it was loaded. Use the following content instead of the previously loaded instructions from this file.\n\nNew workspace instruction after offline edit.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","changes":[{"action":"replace","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"d8375b516f158718bd3463bc8eb7ed42c011b29f"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":11,"time":0,"data":{"title":"Remember the workspace instruction.","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":12,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}"},"reason":"initial"}}
+{"type":"request/context","seq":13,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"text-delta","index":0,"text":"RESUME_DONE"}}}
+{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"RESUME_DONE"}}}}
+{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":18,"time":0,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"RESUME_DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"}},"sourceEventSeqs":[14,15,16,17],"surfaceOp":"append"}
+{"type":"step/end","seq":19,"time":0,"data":{"turn":2,"step":1}}
+{"type":"turn/end","seq":20,"time":0,"data":{"turn":2,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/workspace-context-resume-snapshots/precedence-change/session.expected.jsonl b/examples/headless-agent/tests/workspace-context-resume-snapshots/precedence-change/session.expected.jsonl
new file mode 100644
index 0000000000..b9aabc1cd8
--- /dev/null
+++ b/examples/headless-agent/tests/workspace-context-resume-snapshots/precedence-change/session.expected.jsonl
@@ -0,0 +1,22 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1}}
+{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Remember the workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":2,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nThe following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: CLAUDE.md\n\nOld CLAUDE rule.\n\nInstructions from: AGENTS.md\n\nOld AGENTS rule.\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".git\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"CLAUDE.md\",\"AGENTS.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000CLAUDE.md","path":"CLAUDE.md","digest":"b525eb8a6d3660b732dad4b0aff1b7c63ab32890"},{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"3113bd093ae91976207dcef7390bdc0b2bfcfa10"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"turn/end","seq":3,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session/end-seed","seq":4,"time":0,"data":{}}
+{"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Acknowledge the current workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}
+{"type":"turn/start","seq":6,"time":0,"data":{"turn":2}}
+{"type":"agent/inbox/spliced","seq":7,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"step/start","seq":8,"time":0,"data":{"turn":2,"step":1}}
+{"type":"user/message","seq":9,"time":0,"data":{"content":[{"type":"text","text":"Acknowledge the current workspace instruction."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":10,"time":0,"data":{"content":[{"type":"text","text":"<system-reminder>\nThis complete workspace instruction baseline replaces all earlier workspace instruction baselines. The following workspace instructions may be relevant to your work. Use them as guidance when applicable. More specific instructions take precedence over broader ones. They do not override system, developer, or direct user instructions.\n\nInstructions from: AGENTS.md\n\nCurrent AGENTS rule.\n\n\nInstructions from: CLAUDE.md\n\nCurrent CLAUDE rule.\n\n</system-reminder>"}],"source":{"kind":"workspace-instructions","form":"instructions","baseline":true,"baselineIdentity":"{\"projectRoot\":\"\",\"projectRootMarkers\":[\".git\"],\"maxBytes\":65536,\"maxSourceBytes\":1048576,\"instructionFileCandidates\":[\"AGENTS.md\",\"CLAUDE.md\"],\"localInstructionFileCandidates\":[\"AGENTS.local.md\",\"CLAUDE.local.md\"]}","changes":[{"action":"set","scope":".\u0000AGENTS.md","path":"AGENTS.md","digest":"7f53d2327837129750aef117f9754a001c46cf68"},{"action":"set","scope":".\u0000CLAUDE.md","path":"CLAUDE.md","digest":"5b1e9e3fd759eee6b43ceff899e47fb10c64701a"}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":11,"time":0,"data":{"title":"Remember the workspace instruction.","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":12,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}"},"reason":"initial"}}
+{"type":"request/context","seq":13,"time":0,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
+{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"text-delta","index":0,"text":"RESUME_DONE"}}}
+{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"RESUME_DONE"}}}}
+{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":18,"time":0,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"RESUME_DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{sessionId}}"}},"sourceEventSeqs":[14,15,16,17],"surfaceOp":"append"}
+{"type":"step/end","seq":19,"time":0,"data":{"turn":2,"step":1}}
+{"type":"turn/end","seq":20,"time":0,"data":{"turn":2,"reason":{"kind":"completed"}}}
diff --git a/examples/headless-agent/tests/workspace-context-resume.snapshot.ts b/examples/headless-agent/tests/workspace-context-resume.snapshot.ts
new file mode 100644
index 0000000000..789a859746
--- /dev/null
+++ b/examples/headless-agent/tests/workspace-context-resume.snapshot.ts
@@ -0,0 +1,233 @@
+/**
+ * Assembled-app regression for persisted workspace-instruction resume state.
+ * @module workspace-context-resume-snapshot
+ */
+
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context } from 'cordis'
+import { normalizeSessionLog, scrubRequestHeaders, type NormalizeContext } from '@deepseek-ai/dsh-acp-snapshot'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore, {
+  SESSION_FORMAT_VERSION,
+  SessionId,
+  type SessionEvent,
+  type SessionHeader,
+} from '@deepseek-ai/dsh-session'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { renderWorkspaceContext } from '@deepseek-ai/dsh-workspace-context'
+import { resolveConfig, workspaceBaselineIdentity } from '@deepseek-ai/dsh-workspace-context/src/config.ts'
+import { describe, expect, it } from 'vitest'
+
+const fixtureDir = join(dirname(fileURLToPath(import.meta.url)), 'workspace-context-resume-snapshots/offline-edit')
+const replayFixture = join(fixtureDir, 'replay.jsonl')
+const replayOverride = join(fixtureDir, 'replay.override.json')
+const sessionExpected = join(fixtureDir, 'session.expected.jsonl')
+const precedenceExpected = join(dirname(fixtureDir), 'precedence-change/session.expected.jsonl')
+const configPath = fileURLToPath(new URL('../workspace-context-resume.cordis.snapshot.yml', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const sessionId = SessionId('workspace-context-resume')
+const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
+const oldInstruction = 'Old workspace instruction.'
+const newInstruction = 'New workspace instruction after offline edit.'
+
+interface SeedBaselineOptions {
+  files?: Array<{ name: string; content: string }>
+  instructionFileCandidates?: string[]
+}
+
+async function seedVisibleBaseline(
+  root: string,
+  cwd: string,
+  options: SeedBaselineOptions = {},
+): Promise<string> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
+  const meta: SessionHeader = {
+    version: SESSION_FORMAT_VERSION,
+    id: sessionId,
+    createdAt: 1,
+    cwd,
+    delegationDepth: 0,
+  }
+  const files = options.files ?? [{ name: 'AGENTS.md', content: oldInstruction }]
+  const baseline = renderWorkspaceContext(files.map(file => ({
+    absolutePath: join(cwd, file.name),
+    displayPath: file.name,
+    content: file.content,
+  })), { maxBytes: 65536 })
+  const config = resolveConfig({
+    dshHome: join(cwd, '.dsh'),
+    maxBytes: 65536,
+    ...options.instructionFileCandidates === undefined
+      ? {}
+      : { instructionFileCandidates: options.instructionFileCandidates },
+  })
+  const events: SessionEvent[] = [
+    { type: 'turn/start', seq: 0, time: 10, data: { turn: 1 } },
+    {
+      type: 'user/message',
+      seq: 1,
+      time: 11,
+      data: createUserMessage({ content: [{ type: 'text', text: 'Remember the workspace instruction.' }], source: { kind: 'user' } }),
+      surfaceOp: 'append',
+    },
+    {
+      type: 'user/message',
+      seq: 2,
+      time: 12,
+      data: createUserMessage({
+        content: [{ type: 'text', text: baseline.text }],
+        source: {
+          kind: 'workspace-instructions',
+          form: 'instructions',
+          baseline: true,
+          baselineIdentity: workspaceBaselineIdentity(config, cwd, cwd),
+          changes: files.map(file => ({
+            action: 'set',
+            scope: `.\0${file.name}`,
+            path: file.name,
+            digest: createHash('sha1').update(file.content).digest('hex'),
+          })),
+        },
+      }),
+      surfaceOp: 'append',
+    },
+    { type: 'turn/end', seq: 3, time: 13, data: { turn: 1, reason: { kind: 'completed' } } },
+  ]
+  try {
+    await ctx.sessionPersistence.create(meta)
+    await ctx.sessionPersistence.append(sessionId, events)
+    const location = ctx.sessionPersistence.locate(meta)
+    if (location === undefined) throw new Error('JSONL backend did not locate the seeded session')
+    return location.path
+  } finally {
+    await ctx.fiber.dispose()
+  }
+}
+
+describe('workspace-context resume snapshot', () => {
+  it('appends an offline replacement without duplicating the visible baseline', async () => {
+    let cwd = ''
+    let sessionPath = ''
+    const result = await runLoaderSmoke({
+      label: 'workspace-context resume headless stream-json snapshot',
+      tempDirPrefix: 'dsh-workspace-context-resume-',
+      binScript,
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'Acknowledge the current workspace instruction.'],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT_FILE: replayFixture,
+        DSH_SNAPSHOT_OVERRIDE: replayOverride,
+      },
+      prepare: async (runCwd) => {
+        cwd = runCwd
+        await mkdir(join(runCwd, '.git'), { recursive: true })
+        await writeFile(join(runCwd, 'AGENTS.md'), `${newInstruction}\n`)
+        sessionPath = await seedVisibleBaseline(join(runCwd, '.sessions'), runCwd)
+      },
+      inspect: async () => {
+        const normalization: NormalizeContext = { sessionIds: [sessionId], cwd }
+        const session = scrubRequestHeaders(normalizeSessionLog(await readFile(sessionPath, 'utf8'), normalization))
+        if (refreshing) await writeFile(sessionExpected, session)
+        expect(session).toBe(await readFile(sessionExpected, 'utf8'))
+
+        const records = session.trimEnd().split('\n').map(line => JSON.parse(line) as {
+          type?: string
+          data?: {
+            source?: { kind?: string; baseline?: boolean; changes?: Array<Record<string, unknown>> }
+            content?: Array<{ type?: string; text?: string }>
+          }
+        })
+        const workspaceEvents = records.filter(record => record.type === 'user/message'
+          && record.data?.source?.kind === 'workspace-instructions')
+        expect(workspaceEvents.filter(record => record.data?.source?.baseline === true)).toHaveLength(1)
+        expect(workspaceEvents.filter(record => record.data?.source?.baseline !== true)).toHaveLength(1)
+        expect(workspaceEvents.at(-1)?.data?.source?.changes).toMatchObject([{
+          action: 'replace', scope: '.\0AGENTS.md', path: 'AGENTS.md',
+        }])
+        expect(JSON.stringify(workspaceEvents.at(-1)?.data?.content)).toContain(newInstruction)
+
+        const files = await readdir(join(cwd, '.sessions'), { recursive: true })
+        expect(files.filter(file => file.endsWith('.jsonl'))).toHaveLength(1)
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    const records = result.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    expect(records.at(-1)).toMatchObject({
+      type: 'result',
+      sessionId,
+      output: 'RESUME_DONE',
+    })
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('supersedes an incompatible baseline when precedence changed offline', async () => {
+    let cwd = ''
+    let sessionPath = ''
+    const result = await runLoaderSmoke({
+      label: 'workspace-context precedence-change resume snapshot',
+      tempDirPrefix: 'dsh-workspace-context-precedence-',
+      binScript,
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'Acknowledge the current workspace instruction.'],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT_FILE: replayFixture,
+        DSH_SNAPSHOT_OVERRIDE: replayOverride,
+      },
+      prepare: async (runCwd) => {
+        cwd = runCwd
+        await mkdir(join(runCwd, '.git'), { recursive: true })
+        await writeFile(join(runCwd, 'AGENTS.md'), 'Current AGENTS rule.\n')
+        await writeFile(join(runCwd, 'CLAUDE.md'), 'Current CLAUDE rule.\n')
+        sessionPath = await seedVisibleBaseline(join(runCwd, '.sessions'), runCwd, {
+          files: [
+            { name: 'CLAUDE.md', content: 'Old CLAUDE rule.' },
+            { name: 'AGENTS.md', content: 'Old AGENTS rule.' },
+          ],
+          instructionFileCandidates: ['CLAUDE.md', 'AGENTS.md'],
+        })
+      },
+      inspect: async () => {
+        const normalization: NormalizeContext = { sessionIds: [sessionId], cwd }
+        const session = scrubRequestHeaders(normalizeSessionLog(await readFile(sessionPath, 'utf8'), normalization))
+        if (refreshing) {
+          await mkdir(dirname(precedenceExpected), { recursive: true })
+          await writeFile(precedenceExpected, session)
+        }
+        expect(session).toBe(await readFile(precedenceExpected, 'utf8'))
+
+        const records = session.trimEnd().split('\n').map(line => JSON.parse(line) as {
+          type?: string
+          data?: {
+            source?: { kind?: string; baseline?: boolean }
+            content?: Array<{ type?: string; text?: string }>
+          }
+        })
+        const baselines = records.filter(record => record.type === 'user/message'
+          && record.data?.source?.kind === 'workspace-instructions'
+          && record.data.source.baseline === true)
+        expect(baselines).toHaveLength(2)
+        const replacement = JSON.stringify(baselines.at(-1)?.data?.content)
+        expect(replacement).toContain('replaces all earlier workspace instruction baselines')
+        expect(replacement.indexOf('Instructions from: AGENTS.md'))
+          .toBeLessThan(replacement.indexOf('Instructions from: CLAUDE.md'))
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    expect(result.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>).at(-1))
+      .toMatchObject({
+        type: 'result',
+        sessionId,
+        output: 'RESUME_DONE',
+      })
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
diff --git a/examples/headless-agent/workspace-context-resume.cordis.snapshot.yml b/examples/headless-agent/workspace-context-resume.cordis.snapshot.yml
new file mode 100644
index 0000000000..f5c04d9093
--- /dev/null
+++ b/examples/headless-agent/workspace-context-resume.cordis.snapshot.yml
@@ -0,0 +1,37 @@
+# Keyless real-Loader composition for workspace-instruction resume
+# reconciliation. The test seeds one persisted baseline, changes AGENTS.md
+# while the session is offline, then resumes through the public agent service.
+
+- id: persistence
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: './.sessions'
+    compression: none
+
+- id: replay
+  name: '@deepseek-ai/dsh-llm-replay'
+  config:
+    file: !!js process.env.DSH_SNAPSHOT_FILE
+    overrideFile: !!js process.env.DSH_SNAPSHOT_OVERRIDE
+
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+- id: agent
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    agents: []
+    workspaceContext:
+      maxBytes: 65536
+      dshHome: !!js process.cwd() + '/.dsh'
+    skills:
+      enabled: false
+    toolBash: false
+    toolTasks: false
+    goals: false
+
+# Await the persisted resume before the headless driver inspects root agents.
+- id: resumed-agent
+  name: './tests/fixtures/workspace-context-resume-agent.ts'
diff --git a/examples/jsonrpc-agent/cordis.yml b/examples/jsonrpc-agent/cordis.yml
index 9806413725..2c0890a825 100644
--- a/examples/jsonrpc-agent/cordis.yml
+++ b/examples/jsonrpc-agent/cordis.yml
@@ -65,6 +65,8 @@
 
 - id: tool-todo
   name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
 
 - id: fs-local
   name: '@deepseek-ai/dsh-fs-local'
diff --git a/examples/package.json b/examples/package.json
index 3975d5573b..5379595f23 100644
--- a/examples/package.json
+++ b/examples/package.json
@@ -21,6 +21,7 @@
     "@deepseek-ai/dsh-code-runtime-worker": "workspace:*",
     "@deepseek-ai/dsh-command-goal": "workspace:*",
     "@deepseek-ai/dsh-commands": "workspace:*",
+    "@deepseek-ai/dsh-compact": "workspace:*",
     "@deepseek-ai/dsh-compact-basic": "workspace:*",
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:*",
     "@deepseek-ai/dsh-credentials-local": "workspace:*",
@@ -53,6 +54,7 @@
     "@deepseek-ai/dsh-session": "workspace:*",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:*",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:*",
+    "@deepseek-ai/dsh-session-projection": "workspace:*",
     "@deepseek-ai/dsh-session-query": "workspace:*",
     "@deepseek-ai/dsh-session-query-sqlite": "workspace:*",
     "@deepseek-ai/dsh-session-reference": "workspace:*",
@@ -66,6 +68,8 @@
     "@deepseek-ai/dsh-spill-policy": "workspace:*",
     "@deepseek-ai/dsh-subagent": "workspace:*",
     "@deepseek-ai/dsh-subagent-acp": "workspace:*",
+    "@deepseek-ai/dsh-subagent-claude-code": "workspace:*",
+    "@deepseek-ai/dsh-subagent-codex": "workspace:*",
     "@deepseek-ai/dsh-subagent-dsh-sdk": "workspace:*",
     "@deepseek-ai/dsh-subagent-fork": "workspace:*",
     "@deepseek-ai/dsh-subagent-spawn": "workspace:*",
diff --git a/knip.json b/knip.json
index 1d6a46a01e..6dc4b56dcd 100644
--- a/knip.json
+++ b/knip.json
@@ -36,7 +36,9 @@
       "entry": [
         "headless-agent/tests/fixtures/cli-mock-llm.ts",
         "headless-agent/tests/fixtures/semantic-checkpoint-agent.ts",
+        "headless-agent/tests/fixtures/subagent-diagnostic-agent.ts",
         "headless-agent/tests/fixtures/subagent-inheritance-agent.ts",
+        "headless-agent/tests/fixtures/workspace-context-resume-agent.ts",
         "headless-agent/tests/fixtures/goal-domain/seed-goal.ts",
         "headless-agent/tests/fixtures/time-context-driver.ts",
         "headless-agent/tests/fixtures/time-context-mock-llm.ts",
@@ -46,8 +48,13 @@
         "acp-agent/tests/fixtures/partial-landlock-sandbox.ts",
         "acp-agent/tests/fixtures/subagent-durability-failure.ts",
         "acp-agent/tests/fixtures/subagent-settlement-marker.ts",
+        "acp-agent/tests/fixtures/workspace-context-compaction.ts",
         "acp-agent/tests/fixtures/subagent/subagent-acp/mock-delegating-llm.ts",
         "acp-agent/tests/fixtures/subagent/subagent-acp/driver.ts",
+        "acp-agent/tests/fixtures/subagent/subagent-claude-code/fixture.ts",
+        "acp-agent/tests/fixtures/subagent/subagent-claude-code/driver.ts",
+        "acp-agent/tests/fixtures/subagent/subagent-codex/fixture.ts",
+        "acp-agent/tests/fixtures/subagent/subagent-codex/driver.ts",
         "jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/driver.ts",
         "jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/child-mock-llm.ts",
         "jsonrpc-agent/tests/fixtures/subagent/subagent-dsh-sdk/mock-delegating-llm.ts",
@@ -553,6 +560,29 @@
         "tests/**/*.ts"
       ]
     },
+    "packages/subagent/subagent-codex": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ],
+      "ignoreDependencies": [
+        "@openai/codex"
+      ]
+    },
+    "packages/subagent/subagent-claude-code": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.e2e.ts"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "tests/**/*.ts"
+      ]
+    },
     "packages/fs/tool-fs": {
       "entry": [
         "tests/**/*.spec.ts",
@@ -597,6 +627,22 @@
         "@deepseek-ai/dsh-client-ui-theme"
       ]
     },
+    "packages/client/ui-settings": {
+      "entry": [
+        "tests/**/*.spec.ts",
+        "tests/**/*.spec.tsx"
+      ],
+      "project": [
+        "src/**/*.ts",
+        "src/**/*.tsx",
+        "tests/**/*.ts",
+        "tests/**/*.tsx"
+      ],
+      "ignoreDependencies": [
+        "@types/react-dom",
+        "react-dom"
+      ]
+    },
     "apps/web": {
       "entry": [
         "tests/**/*.e2e.ts",
diff --git a/packages/bash/bash-local/README.i18n.yaml b/packages/bash/bash-local/README.i18n.yaml
index 4d0214386f..a33f59641e 100644
--- a/packages/bash/bash-local/README.i18n.yaml
+++ b/packages/bash/bash-local/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/bash/bash-local/README.md
-README.md: bb87ad6fe021e3144cef4adced3d798bf3d94d67
-README.zh.md: d2f8c9091072bbf3d75909f6826432601001ab88
+README.md: cb40cb8fa40d95d5b4589b7c804f450a2bf38c8e
+README.zh.md: bd4f73babdb47ff92e87e20eb7d60657ed515ec4
diff --git a/packages/bash/bash-local/README.md b/packages/bash/bash-local/README.md
index bb87ad6fe0..cb40cb8fa4 100644
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -23,7 +23,7 @@ The package root exports the default and named `LocalBashExecutor` plugin plus i
 ## Behavior
 
 - **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` with no rc files.
-- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. Process-group kills, post-exit pipe draining, tail retention, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
+- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. The grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so Node can represent it with one timer. Process-group kills, post-exit pipe draining, tail retention, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
 - **Timeout and cancel classification** — `run()` fuses its config-clamped timeout with the caller's signal through one deadline; only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, and a self-signaled command reports neither ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
 - **Model-friendly terminal env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` prevents pagers and ANSI color from garbling results. These values merge as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
 - **Background processes** — `start()` returns a live `BashProcess` handle immediately with no timeout, and `readOutput()` merges offset-based stdout/stderr reads into one consuming delta, placing stderr under a `[stderr]` marker when present. A running process belongs to the subprocess service, survives executor reloads, and is killed and joined on service disposal. Task ids, ownership, polling, and notices belong to the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with.
diff --git a/packages/bash/bash-local/README.zh.md b/packages/bash/bash-local/README.zh.md
index d2f8c90910..bd4f73babd 100644
--- a/packages/bash/bash-local/README.zh.md
+++ b/packages/bash/bash-local/README.zh.md
@@ -23,7 +23,7 @@
 ## 行为
 
 - **每次调用都 spawn，不保留 shell 状态**：每次调用都启动新的非登录 `bash -c`，且不读取 rc 文件。
-- **在受管进程组之上应用配置预算**：`resolve()` 从配置补全 `workdir`／`timeoutMs`／`stdoutMaxBytes`，每次 spawn 都向服务传入显式的字节上限、spill 上限与 `graceMs`。进程组终止、退出后管道排空、尾部保留与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台运行仍使用 `maxOutputBytes`。
+- **在受管进程组之上应用配置预算**：`resolve()` 从配置补全 `workdir`／`timeoutMs`／`stdoutMaxBytes`，每次 spawn 都向服务传入显式的字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程组终止、退出后管道排空、尾部保留与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台运行仍使用 `maxOutputBytes`。
 - **超时与取消分类**：`run()` 通过同一个 deadline 把经配置钳位的超时与调用方的信号融合；只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自身因信号终止的命令两者皆不报告（见[超时库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
 - **适合模型的终端环境**：`NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` 防止分页器与 ANSI 颜色破坏结果。这些值作为普通 env 合并，遵循服务的凭据清除与 `DSH_*` 通道规则；调用方的显式条目依旧优先。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
 - **后台进程**：`start()` 会立即返回活动的 `BashProcess` 句柄且不应用超时；`readOutput()` 把基于偏移量的 stdout/stderr 读取合并为一条消费式增量，并在存在 stderr 时将其置于 `[stderr]` 标记下。运行中的进程属于 subprocess 服务，可在执行器重载后存活，并在服务 dispose 时被终止且等待退出。task id、所有权、轮询和通知属于通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md)，工具层会在其中注册该句柄。
diff --git a/packages/bash/bash-local/src/index.ts b/packages/bash/bash-local/src/index.ts
index 4ed49be02a..ccb5a32aa8 100644
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -14,7 +14,7 @@ import z from 'schemastery'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
 import type { SubprocessCollect, SubprocessHandle, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+import { clampTimeout, deadline, MAX_TIMER_DELAY_MS, timeoutOf } from '@deepseek-ai/dsh-timeout'
 
 /**
  * Model-friendly environment overrides: disable colors, pagers, and
@@ -48,7 +48,7 @@ export interface Config {
   maxOutputBytes?: number
   /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
   maxSpillBytes?: number
-  /** Grace period for kill escalation and for inherited pipes after shell exit. */
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
   graceMs?: number
 }
 
@@ -102,6 +102,9 @@ export class LocalBashExecutor extends BashExecutor {
     assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
     assertPositiveFinite('maxSpillBytes', this.config.maxSpillBytes)
     assertPositiveFinite('graceMs', this.config.graceMs)
+    if (this.config.graceMs > MAX_TIMER_DELAY_MS) {
+      throw new Error(`bash-local: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
+    }
   }
 
   /**
diff --git a/packages/bash/bash-local/tests/executor.spec.ts b/packages/bash/bash-local/tests/executor.spec.ts
index 1395b48958..af5566086f 100644
--- a/packages/bash/bash-local/tests/executor.spec.ts
+++ b/packages/bash/bash-local/tests/executor.spec.ts
@@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { BashProcess } from '@deepseek-ai/dsh-bash'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-exec-spec-'))
@@ -70,6 +71,8 @@ describe('LocalBashExecutor.run', () => {
     await expect(setup({ maxOutputBytes: -1 })).rejects.toThrow(/maxOutputBytes/)
     await expect(setup({ maxSpillBytes: 0 })).rejects.toThrow(/maxSpillBytes/)
     await expect(setup({ graceMs: 0 })).rejects.toThrow(/graceMs/)
+    await expect(setup({ graceMs: MAX_TIMER_DELAY_MS + 1 }))
+      .rejects.toThrow(`graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
 
     const { bash } = await setup()
     expect(() => bash.resolve({ command: 'true', timeoutMs: Number.NaN })).toThrow(/request\.timeoutMs/)
diff --git a/packages/bash/pwsh-local/README.i18n.yaml b/packages/bash/pwsh-local/README.i18n.yaml
index ef6a984d07..9a0690b5c8 100644
--- a/packages/bash/pwsh-local/README.i18n.yaml
+++ b/packages/bash/pwsh-local/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/bash/pwsh-local/README.md
-README.md: 2914c46ab91dd9555dab04551e52321f6eac05bf
-README.zh.md: ce9696b276a2e60acf116d7124cd5cd256d7ebde
+README.md: 3e38ea3830cb651a80eaee744a42f68891767358
+README.zh.md: 8d32ce865d299bac37704e3e8730a7faa63ee108
diff --git a/packages/bash/pwsh-local/README.md b/packages/bash/pwsh-local/README.md
index 2914c46ab9..3e38ea3830 100644
--- a/packages/bash/pwsh-local/README.md
+++ b/packages/bash/pwsh-local/README.md
@@ -30,7 +30,7 @@ The Windows counterpart of `dsh-bash-local`, deliberately mirroring its semantic
 - **Spawn per call, no shell state** — every call is a fresh non-interactive `pwsh -Command` (deterministic; no profile files). The `-NoLogo -NoProfile -NonInteractive` flags disable startup banners, profile loading, and prompts that would garble tool output.
 - **UTF-8 output pinned** — every command runs with `[Console]::OutputEncoding` and `$OutputEncoding` set to UTF-8 first, so the Windows PowerShell 5.1 fallback (or any host whose console code page is not UTF-8) cannot garble non-ASCII output: the subprocess collector decodes bytes as UTF-8. Input encoding is left at the host default; pwsh 7 defaults to UTF-8 and is unaffected.
 - **Executable resolution** — `resolvePwshPath` prefers an explicit `pwshPath`, then on Windows probes PowerShell 7's install location, every PATH entry (Microsoft Store installs; surrounding quotes stripped), and Windows PowerShell 5.1 as a legacy last resort, checking `existsSync` on each; elsewhere it falls back to a bare `pwsh` resolved through PATH. Resolution is a pure function of `(configured, env, platform)` and happens once at construction.
-- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. Tree termination (taskkill on Windows, process-group signals on POSIX), the post-exit pipe-drain grace, tail-keep truncation, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
+- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. The grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so Node can represent it with one timer. Tree termination (taskkill on Windows, process-group signals on POSIX), the post-exit pipe-drain grace, tail-keep truncation, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
 - **Timeout and cancel classification** — `run()` fuses its config-clamped timeout with the caller's signal through one deadline; only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, and a self-terminated command reports neither ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)). Windows reports forced termination as exit 1 without a signal, so signal-stamped facts (`signal`, `killed` status) are POSIX-only there; the timeout/abort classification is platform-independent.
 - **Model-friendly terminal env** — `NO_COLOR=1 PAGER=cat GIT_PAGER=cat` (no `TERM=dumb`: that is a POSIX concept; `NO_COLOR` is honored by modern PowerShell renderers) merged as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins.
 - **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies, and the handle's `readOutput()` merges the service's offset-based stdout/stderr reads into one marked-section delta with a consuming cursor. A still-running process belongs to the subprocess service, so it survives executor reloads and dies (killed and joined) with the service's disposal. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
diff --git a/packages/bash/pwsh-local/README.zh.md b/packages/bash/pwsh-local/README.zh.md
index ce9696b276..8d32ce865d 100644
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -30,7 +30,7 @@
 - **每次调用新建进程，无 shell 状态**——每次调用都是全新的非交互 `pwsh -Command`（确定性；不加载 profile 文件）。`-NoLogo -NoProfile -NonInteractive` 关闭启动横幅、profile 加载与会干扰工具输出的提示符。
 - **UTF-8 输出固定**——每条命令都先以 UTF-8 设置 `[Console]::OutputEncoding` 与 `$OutputEncoding`，因此 Windows PowerShell 5.1 兜底（或任何控制台代码页非 UTF-8 的主机）不会破坏非 ASCII 输出：subprocess collector 以 UTF-8 解码字节。输入编码保持宿主默认；pwsh 7 默认为 UTF-8，不受影响。
 - **可执行文件解析**——`resolvePwshPath` 优先显式 `pwshPath`，然后在 Windows 上依次探测 PowerShell 7 安装位置、每个 PATH 条目（Microsoft Store 安装；剥离两端引号）以及作为遗留兜底的 Windows PowerShell 5.1，逐一检查 `existsSync`；其他平台回退为通过 PATH 解析的裸 `pwsh`。解析是 `(configured, env, platform)` 的纯函数，在构造时执行一次。
-- **受管进程组之上的配置预算**——`resolve()` 从配置填充 `workdir`/`timeoutMs`/`stdoutMaxBytes`，每次 spawn 都向服务提供显式字节上限、spill 上限与 `graceMs`。进程树终止（Windows 用 taskkill，POSIX 用进程组信号）、退出后管道排空宽限、保尾截断与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为单个受信调用方提高 stdout 捕获预算；stderr 与后台运行仍使用 `maxOutputBytes`。
+- **受管进程组之上的配置预算**——`resolve()` 从配置填充 `workdir`/`timeoutMs`/`stdoutMaxBytes`，每次 spawn 都向服务提供显式字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程树终止（Windows 用 taskkill，POSIX 用进程组信号）、退出后管道排空宽限、保尾截断与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为单个受信调用方提高 stdout 捕获预算；stderr 与后台运行仍使用 `maxOutputBytes`。
 - **超时与取消分类**——`run()` 通过一个 deadline 融合配置夹取的超时与调用方信号；只有执行器自身超时报告 `timedOut`，上游取消报告 `aborted`，自我终止的命令两者都不报告（见 [timeout 库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。Windows 将强制终止报告为退出码 1 且无信号，因此基于信号的实情（`signal`、`killed` 状态）在那里仅限 POSIX；超时/取消分类与平台无关。
 - **面向模型的终端环境**——`NO_COLOR=1 PAGER=cat GIT_PAGER=cat`（没有 `TERM=dumb`：那是 POSIX 概念；现代 PowerShell 渲染器遵循 `NO_COLOR`），作为普通 env 在服务的凭据清理与 `DSH_*` 通道规则之下合并；显式调用方条目仍然优先。
 - **后台进程**——`start()` 立即返回存活的 `BashProcess` 句柄，不设超时；句柄的 `readOutput()` 把服务基于偏移的 stdout/stderr 读取合并为带标记分段的增量与消费游标。仍在运行的进程属于 subprocess 服务，因此它跨执行器重载存活，并随服务销毁（被终止并 join）。一切任务形状的职责（id、所有权、轮询、通知）都在通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md) 中，由工具层把句柄注册进去——本执行器从不接触会话或注册表。
diff --git a/packages/bash/pwsh-local/src/index.ts b/packages/bash/pwsh-local/src/index.ts
index 316d2c8651..20ecffd969 100644
--- a/packages/bash/pwsh-local/src/index.ts
+++ b/packages/bash/pwsh-local/src/index.ts
@@ -18,7 +18,7 @@ import z from 'schemastery'
 import { BashExecutor } from '@deepseek-ai/dsh-bash'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashProcessRead, BashRunResult, CollectedOutput } from '@deepseek-ai/dsh-bash'
 import type { SubprocessCollect, SubprocessHandle, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
-import { clampTimeout, deadline, timeoutOf } from '@deepseek-ai/dsh-timeout'
+import { clampTimeout, deadline, MAX_TIMER_DELAY_MS, timeoutOf } from '@deepseek-ai/dsh-timeout'
 import { resolvePwshPath } from './resolve.ts'
 
 /* jscpd:ignore-start -- deliberate call-for-call mirror of dsh-bash-local (Agent Note: pwsh-tool-and-executor). */
@@ -62,7 +62,7 @@ export interface Config {
   maxOutputBytes?: number
   /** Per-stream spill-file cap; larger streams retain only their in-memory tail. */
   maxSpillBytes?: number
-  /** Grace period for kill escalation and for inherited pipes after shell exit. */
+  /** Grace period for kill escalation and inherited pipes; at most `MAX_TIMER_DELAY_MS`. */
   graceMs?: number
   /**
    * Explicit pwsh executable. When omitted, well-known Windows install
@@ -129,6 +129,9 @@ export class PwshLocalExecutor extends BashExecutor {
     assertPositiveFinite('maxOutputBytes', this.config.maxOutputBytes)
     assertPositiveFinite('maxSpillBytes', this.config.maxSpillBytes)
     assertPositiveFinite('graceMs', this.config.graceMs)
+    if (this.config.graceMs > MAX_TIMER_DELAY_MS) {
+      throw new Error(`pwsh-local: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
+    }
     this.pwshPath = resolvePwshPath(this.config.pwshPath)
   }
 
diff --git a/packages/bash/pwsh-local/tests/executor.spec.ts b/packages/bash/pwsh-local/tests/executor.spec.ts
index 4552f2eeec..c7da16c44c 100644
--- a/packages/bash/pwsh-local/tests/executor.spec.ts
+++ b/packages/bash/pwsh-local/tests/executor.spec.ts
@@ -19,6 +19,7 @@ import { PwshLocalExecutor, ENCODING_PREAMBLE, candidatePwshPaths, resolvePwshPa
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import SubprocessService from '@deepseek-ai/dsh-subprocess'
 import type { SubprocessHandle, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type { BashProcess } from '@deepseek-ai/dsh-bash'
 
 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-pwsh-exec-spec-'))
@@ -187,6 +188,8 @@ describe.skipIf(!hasPwsh)('PwshLocalExecutor.run', () => {
     await expect(setup({ maxOutputBytes: -1 })).rejects.toThrow(/maxOutputBytes/)
     await expect(setup({ maxSpillBytes: 0 })).rejects.toThrow(/maxSpillBytes/)
     await expect(setup({ graceMs: 0 })).rejects.toThrow(/graceMs/)
+    await expect(setup({ graceMs: MAX_TIMER_DELAY_MS + 1 }))
+      .rejects.toThrow(`graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
 
     const { bash } = await setup()
     expect(() => bash.resolve({ command: 'Write-Output ok', timeoutMs: Number.NaN })).toThrow(/request\.timeoutMs/)
diff --git a/packages/bundle/base/cordis.patch.yml b/packages/bundle/base/cordis.patch.yml
index c09c7da39c..e284bdca7b 100644
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -100,6 +100,12 @@
         path: ':memory:'
         openAt: first-search
 
+    # Shared projection registry: subagent catalog identity (mode/label) folds
+    # through its registered units, so the `list_agents` surface below fails
+    # loud without it; web layers reuse this same mount for list rows.
+    - id: session-projection
+      name: '@deepseek-ai/dsh-session-projection'
+
     # Session telemetry, on for every dsh mode: mirrors every session-log
     # event (assistant/chunk projected to first-of-step) plus ops markers onto
     # OTLP/HTTP log records, streaming on the batch processor's cadence
@@ -320,6 +326,8 @@
 
     - id: tool-todo
       name: '@deepseek-ai/dsh-tool-todo'
+      config:
+        allowParallelInProgress: true
 
     # Persisted same-session goals reach the model and the slash menu here; the
     # domain, driver, and `/goal` command are above.
diff --git a/packages/bundle/base/package.json b/packages/bundle/base/package.json
index 95e169cabb..14399cd441 100644
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -61,6 +61,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
     "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
     "@deepseek-ai/dsh-session-telemetry-otel": "workspace:^",
     "@deepseek-ai/dsh-session-title": "workspace:^",
diff --git a/packages/bundle/web-app/README.i18n.yaml b/packages/bundle/web-app/README.i18n.yaml
index b48d8c59f3..7662182df0 100644
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/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/bundle/web-app/README.md
-README.md: 95cdbc9694b44539742e5b871157eefa7cb4c290
-README.zh.md: b8d6e9d80bac82a7798cc07d3a34c01d219f2174
+README.md: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
+README.zh.md: 0ffc5cdaf1a98e5df11ef042c7d15a994515c170
diff --git a/packages/bundle/web-app/README.md b/packages/bundle/web-app/README.md
index 95cdbc9694..dc35cb4b59 100644
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection, storage) and the browser plugin roster, and mounts this package's own `web-runtime` glue plugin (config `{mode, printUrl, lanAddresses}`). That plugin owns what used to be launcher code: it resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports (workspace knowledge of this bundle, never user config), mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses`/`printUrl` and the flag family over these rows; [`dsh-headless`](../headless/README.md) layers on top and silences the URL line.
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's own `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin owns what used to be launcher code: it resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports (workspace knowledge of this bundle, never user config), mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows; [`dsh-headless`](../headless/README.md) layers on top, silences the URL line, and disables the surface context.
 
 ## Model Experience
 
@@ -10,7 +10,7 @@ The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides ove
 
 #### What the model sees
 
-The `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the HMR/rebuild update contract for the active mode, and the instruction not to start replacement servers. `DSH_WEB_URL` and `DSH_WEB_MODE` additionally appear in the managed bash environment with their descriptions, resolved per invocation from the live server.
+When `surfaceContext` is true, the `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the HMR/rebuild update contract for the active mode, and the instruction not to start replacement servers. `DSH_WEB_URL` and `DSH_WEB_MODE` additionally appear in the managed bash environment with their descriptions, resolved per invocation from the live server. When it is false, neither the section nor the variables are registered.
 
 #### Token effect
 
diff --git a/packages/bundle/web-app/README.zh.md b/packages/bundle/web-app/README.zh.md
index b8d6e9d80b..0ffc5cdaf1 100644
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影、存储）与浏览器插件名录，并挂载本包自己的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, lanAddresses}`）。该插件接管了原先属于启动器的代码：它通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist（这是本组合包的 workspace 知识，绝不是用户配置），在其上挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses`／`printUrl` 与相应 flag 家族 patch 到这些行上；[`dsh-headless`](../headless/README.md) 再叠加一层并关闭 URL 行。
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包自己的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件接管了原先属于启动器的代码：它通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist（这是本组合包的 workspace 知识，绝不是用户配置），在其上挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上；[`dsh-headless`](../headless/README.md) 再叠加一层，关闭 URL 行并禁用表层上下文。
 
 ## 模型体验
 
@@ -10,7 +10,7 @@ dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 #### 模型看到的内容
 
-全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。
+当 `surfaceContext` 为 true 时，全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，该提示词段和这些变量都不会注册。
 
 #### Token 影响
 
diff --git a/packages/bundle/web-app/cordis.patch.yml b/packages/bundle/web-app/cordis.patch.yml
index 092c295996..624e9e37af 100644
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -45,9 +45,6 @@
 # `dshClient` rows are the browser roster the modules node half scans into
 # window.__DSH_BOOT__; the modules row is simultaneously a host row.
 - insert:
-    - id: session-projection
-      name: '@deepseek-ai/dsh-session-projection'
-
     - id: code-runtime
       name: '@deepseek-ai/dsh-code-runtime-worker'
 
@@ -103,12 +100,15 @@
     # assembly fact of dsh-web-app, never user config), mounts the
     # frontend-static fallback owner, registers the web-surface prompt
     # section and bash runtime variables, and prints the URL line. `dsh web`
-    # patches mode/lanAddresses over these defaults.
+    # patches mode/lanAddresses over these defaults; complete-prompt overlays
+    # set surfaceContext false to suppress every model- and shell-visible Web
+    # runtime contribution.
     - id: web-runtime
       name: '@deepseek-ai/dsh-web-app'
       config:
         mode: production
         printUrl: true
+        surfaceContext: true
 
     # ── browser plugin roster (dshClient rows; node halves are layer-2 hosts) ──
 
diff --git a/packages/bundle/web-app/package.json b/packages/bundle/web-app/package.json
index 1b812b9943..0a406a7bf8 100644
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -63,7 +63,6 @@
     "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^",
     "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
     "@deepseek-ai/dsh-host-webserver": "workspace:^",
-    "@deepseek-ai/dsh-session-projection": "workspace:^",
     "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
     "@deepseek-ai/dsh-storage": "workspace:^",
     "@deepseek-ai/dsh-storage-domain": "workspace:^",
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 20af221f2d..dc2f8c5967 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -474,11 +474,14 @@ function buildAlphaLog(): SessionEvent[] {
     push({ type: 'step/end', data: { turn, step: 0 } })
     push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
   }
-  // Turn 67: todo_write sample — the TodoRow toolview in the flow plus the
-  // todo/write snapshot event feeding the TodoPanel plan strip.
+  // Turn 71: todo_write sample — the TodoRow toolview in the flow plus the
+  // todo/write snapshot event feeding the TodoPanel plan strip. Two items are
+  // in_progress: this fixture chooses the parallel policy, so both surfaces
+  // must render a parallel plan rather than the first active item alone.
   const fixtureTodos = [
     { content: '梳理需求', status: 'completed' },
     { content: '实现 fixture 样本', status: 'in_progress' },
+    { content: '跑后台构建', status: 'in_progress' },
     { content: '浏览器验收', status: 'pending' },
   ]
   // Turn 65: the terminal sample turn 60's two clean prompt rows cannot cover —
@@ -531,7 +534,7 @@ function buildAlphaLog(): SessionEvent[] {
   toolTurn(70, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
 
   const todoArgs = JSON.stringify({ todos: fixtureTodos })
-  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
+  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 2 in progress, 1 completed.')
   // The real tool appends the snapshot mid-execution — between tool/call and
   // tool/result — so the fixture reproduces that exact ordering (the last
   // toolTurn events run ... tool/call, tool/result, step/end, turn/end).
diff --git a/packages/client/connection/tests/fixture.spec.ts b/packages/client/connection/tests/fixture.spec.ts
index 3bdd0a21ea..f608190936 100644
--- a/packages/client/connection/tests/fixture.spec.ts
+++ b/packages/client/connection/tests/fixture.spec.ts
@@ -242,6 +242,10 @@ describe('createFixtureApi', () => {
     const times = events.slice(todoAt - 1, todoAt + 2).map(e => e.time)
     expect(times[0]).toBeLessThanOrEqual(times[1] ?? 0)
     expect(times[1]).toBeLessThanOrEqual(times[2] ?? 0)
+    // The sample is a parallel plan: this fixture chooses the parallel policy,
+    // so the surfaces fed from here face more than one active item.
+    const snapshot = events[todoAt] as { data: { todos: { status: string }[] } }
+    expect(snapshot.data.todos.filter(t => t.status === 'in_progress')).toHaveLength(2)
   })
 
   it('create adds a session and pushes host/session-added to open host streams', async () => {
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 73b3204d61..974f8a65b0 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: e7b57e25208a402a81284f930644bfc4208c9291
-README.zh.md: 1b8543fa24d8e8a62f6b8995619548928ab80ce1
+README.md: 31ae990d2d97757a4d7ea06b323e2131f764b5f7
+README.zh.md: 0f21da2f48dbfd6673fb02d6719390bec872afeb
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index e7b57e2520..31ae990d2d 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -34,7 +34,7 @@ A `grep`/`glob` call declaring the `search` render intent renders its result inl
 
 Tool rows use the keyed, session-scoped `'conversation.chat.toolview'` slot; its render site dispatches via `entryKey: toolName` with `GenericToolCard` as the call-site fallback. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openFile`), and `ToolRowProps` composes it with the session standard kit. A registrant is a plain plugin with only the slot service edge: `ctx.slots.inject('conversation.chat.toolview', () => ctx.slots.register({ name: 'conversation.chat.toolview', key: '<tool>', inject? }, Row))`. The declaration is the activation and reload dependency; `ConversationService` is required only by registrations that call its actions. Trajectory and waterfall toolview slots share this shape and use their own render sites; RendersCheck rejects a declaration nobody renders.
 
-The todo surfaces are two registrations over that shape, both using slot declaration injection without a `ConversationService` edge. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> 已完成 · <active item>` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"<done>/<total> tasks · <n> in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
+The todo surfaces are two registrations over that shape, both using slot declaration injection without a `ConversationService` edge. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`<done>/<total> completed · <active item>` plus a `+<n>` count of the other active ones, parsed from its args through `toolviews/plan-summary.ts` `planSummary`, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). When the deployment permits parallel work, several items may be `in_progress` at once, so `planSummary` names the first and counts the rest, and deliberately returns the two unjoined: the row ellipsizes its summary text, so a count concatenated onto the end of the task name would be the first thing a narrow row clips. The row hands the count to `ToolRow`'s `summarySuffix`, the shared row's non-shrinking slot beside that ellipsized text (an error row drops it, since its collapsed summary is the failure line). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: 0` — before Goal and Queue — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus its own `·`-joined per-status counts (localized, `1 completed · 2 in progress · 1 pending`, zero-count segments omitted; status glyphs are the figma check / progress / dashed-pending set), so it reports the parallel count without needing a name to truncate. The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
 
 `QueueDock` is the terminal input-dock entry at `order: 20`. It hides while empty, renders one pending row directly, and defaults two or more rows to a collapsed `"<n> 条排队消息"` header whose button expands or collapses the complete list. The header exposes `aria-expanded` and `aria-controls`; the expanded list scrolls within a 180px height bound. An active edit or mutation keeps its rows visible, and emptying the queue restores the collapsed default for the next queue. Each visible ordinary-session row remains a single-line preview with its exact-occurrence edit, delete, and strict-steer actions; addressed subagents retain the rows as a read-only projection because their continuation transport does not expose queue mutation. If strict steer loses to a closed window, the original occurrence remains queued for normal delivery; if the driver already claimed it, normal delivery is already underway. Neither converged race displays a failure, while transport and unknown failures do.
 
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index 1b8543fa24..0f21da2f48 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -34,7 +34,7 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时
 
 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。运行时 manager 会将所有审批或问题等待通过 `SessionSummary.pendingInteraction` 投影出来，未实例化的 Session 也不例外；`ui-workspace` 负责其侧边栏呈现。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，其中 kebab-case 预设名渲染为 Title Case 标签；普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
 
-todo 两个面就是在该形状上的两个注册项，都使用 slot 声明注入，不依赖 `ConversationService`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加 `"<已完成>/<总数> tasks · <n> in progress"`（状态图标为 figma 的勾选／进行中／虚线未开始一组）。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
+todo 两个面就是在该形状上的两个注册项，都使用 slot 声明注入，不依赖 `ConversationService`。`TodoRow` 占用 `'conversation.chat.toolview'` 的 `todo_write` key，摘要该次调用「试图写入」的内容（从其 args 经 `toolviews/plan-summary.ts` 的 `planSummary` 解析出 `<已完成>/<总数> 已完成 · <进行中条目>`，以及「其余活跃项的数量」`+<n>`；模型 JSON 残缺或形状不对时回落到通用摘要；非 ok 执行状态保留通用状态点，使被取消的调用绝不读成一次已完成的更新）。部署允许并行工作时，可以有多个条目同时处于 `in_progress`，因此 `planSummary` 给出第一个活跃条目并计数其余，且刻意不把两者拼成一个字符串：行会对摘要文本做省略号截断，把数量接在任务名末尾时，窄行最先裁掉的正是这个数量。该行把数量交给 `ToolRow` 的 `summarySuffix`——共享行在被截断文本旁的不收缩位（出错的行会丢弃它，因为其折叠摘要是失败首行）。`TodoDock` 以 `order: 0` 占用 `'conversation.input.dock'` 列表 slot（位于 Goal 与 Queue 之前），是计划条：它经 `useProjection` 读取 host 计算的 `todos` 投影（站立计划：其后没有更晚 `turn/start` 的最近一次 `todo/write`）并渲染 `TodoPanel`，后者接收纯列表，在列表为空时自我隐藏；列表非空时面板初始折叠，表头显示标题加它自行计算的、以 `·` 连接的各状态计数（本地化，形如 `1 已完成 · 2 进行中 · 1 待处理`，计数为零的段落省略；状态图标为 figma 的勾选／进行中／虚线未开始一组），因此它无需一个可被截断的任务名即可报告并行数量。选取由 dock 适配器负责，因此面板保持为其 props 的纯函数；站立列表放在此处而非行内，行才能保持单行。输入区 composer 链隐藏的一切（例如 ui-question 对 `conversation.composer` 的接管）也会隐藏整个 dock，包括这条计划条。
 
 `QueueDock` 是 `order: 20` 的末端 input-dock 条目。队列为空时隐藏；只有一个待处理项时直接渲染该行；存在两个或更多待处理项时，默认收起为 `"<n> 条排队消息"` 表头，其按钮可展开或收起完整列表。表头暴露 `aria-expanded` 和 `aria-controls`；展开后的列表以 180px 为高度上限，并可滚动。存在进行中的编辑或变更时，列表行会保持可见；队列清空后，下一次出现队列时会恢复默认收起状态。普通会话中的每条可见行仍是单行预览，并提供针对精确单次入队项的编辑、删除和严格 steering 操作；已寻址 subagent 则保留只读行，因为其继续执行传输不提供 Queue 变更。如果严格 steering 输给已关闭的窗口，原单次入队项会留在 Queue 中正常投递；如果驱动器已经认领该项，正常投递就已开始。这两种已收敛的竞态都不显示失败，传输和未知错误仍会显示。
 
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
index 14bfe0e76c..78dfdca877 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
@@ -89,6 +89,20 @@
   text-overflow: clip;
 }
 
+/* Trailing summary fragment kept out of .summary's ellipsis, for a count whose
+   whole value is that it survives a narrow row (the todo row's parallel-active
+   `+n`). Repeats .summary's type because it sits beside that text, and its
+   `nowrap` too: `flex: none` stops the box shrinking but not the text wrapping,
+   which would break the one-line row in the narrow case the slot exists for. */
+.summarySuffix {
+  flex: none;
+  margin-left: 4px;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
 /* File-tool path: same geometry as .summary; hover underline + pointer. */
 .fileLink {
   flex: 1 1 auto;
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
index 71cf69cc5f..b5b0befa50 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
@@ -46,6 +46,14 @@ export interface ToolRowProps {
   icon: ReactNode
   title: string
   summary: string
+  /**
+   * Trailing summary fragment rendered outside the ellipsized summary text, so
+   * a narrow row clips the summary before this. For a fragment whose whole
+   * value is surviving that clip — the todo row's parallel-active count.
+   * null/absent = the summary is the whole collapsed content. Dropped on an
+   * error row, whose collapsed summary is the failure line instead.
+   */
+  summarySuffix?: string | null | undefined
   /** Expanded-body input text; null = no input section. */
   body: string | null
   /** Flattened result text for the expanded Output section; null/absent = no output section. */
@@ -139,6 +147,7 @@ export function ToolRow({
   icon,
   title,
   summary,
+  summarySuffix,
   body,
   output,
   errorSummary,
@@ -173,6 +182,9 @@ export function ToolRow({
   // the error color outranks both the args summary and a terminal description.
   const failureLine = state === 'error' ? errorSummary ?? null : null
   const summaryText = failureLine ?? summary
+  // The failure line replaces the summary wholesale, so a suffix derived from
+  // the call args has nothing left to sit beside.
+  const suffix = failureLine === null ? summarySuffix ?? null : null
   // The failure line is error prose, not the path: no open-file affordance.
   const fileLink = filePath !== undefined && onOpenFile !== undefined && failureLine === null
   const isThink = variant === 'think'
@@ -249,6 +261,7 @@ export function ToolRow({
                 {summaryText}
               </span>
             )}
+            {suffix !== null && <span className={css.summarySuffix}>{suffix}</span>}
           </>
         )}
       >
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
index 4c9d2f8627..ca15f77c4d 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
@@ -191,6 +191,14 @@
   flex-direction: column;
   min-height: 0;
   overflow-y: auto;
+  /* The column scrolls on ONE axis. Stating `hidden` rather than leaving the
+     initial `visible` is what removes the horizontal bar: a box that scrolls in
+     one axis computes `visible` to `auto` in the other, so any bleed becomes
+     user-scrollable. `.heroGlow` bleeds by construction (1051/776 of the hero
+     box), which put a horizontal scrollbar under every center column narrower
+     than the glow. Clipping is unchanged — `overflow-y: auto` already made this
+     a scroll container that clips both axes, so this only takes away the bar. */
+  overflow-x: hidden;
   /* Reserved unconditionally: the composer seat rides this box's content box in
      Chat and its padding box under a view's composer overlay, so an `auto`
      gutter moves the input card sideways by the bar's width whenever the two
diff --git a/packages/client/ui-conversation/src/client/toolviews/plan-summary.ts b/packages/client/ui-conversation/src/client/toolviews/plan-summary.ts
new file mode 100644
index 0000000000..df609e7b3f
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/toolviews/plan-summary.ts
@@ -0,0 +1,60 @@
+/**
+ * Pure plan derivation for the todo_write row's one-line summary. Several items
+ * may be `in_progress` at once — parallel work runs concurrent tasks, so a
+ * summary built from one active item would silently drop the rest. The plan
+ * strip header derives its own counts inline and shares nothing with this, so
+ * this stays inside the toolviews domain rather than in `contract/` (the
+ * inter-domain face).
+ * @module
+ */
+
+/**
+ * One list item as the row sees it: unvalidated model JSON parsed from a call's
+ * args, so any field may be missing or mistyped.
+ */
+export interface PlanItemLike {
+  content?: unknown
+  status?: unknown
+}
+
+/**
+ * Counts plus the two halves of the summary, deliberately NOT pre-joined: the
+ * row ellipsizes its summary text, and a count concatenated onto the end of the
+ * task name is the first thing a narrow row clips — exactly when it carries
+ * information. The row renders `activeExtra` in its own non-shrinking span
+ * beside the truncatable text.
+ */
+export interface PlanSummary {
+  done: number
+  total: number
+  /** First `in_progress` content, or null when that first item is unusable. */
+  activeContent: string | null
+  /** Active items beyond the first; 0 whenever there is no `activeContent` to sit beside. */
+  activeExtra: number
+}
+
+/**
+ * Derive the counts and the active summary from a whole-list snapshot. It names
+ * the first `in_progress` item and counts the remaining active ones, so a
+ * parallel plan reports how many tasks are running rather than naming one and
+ * hiding the others. `activeContent` is null when nothing is in progress, or
+ * when the first active item's content is missing, mistyped, or blank once
+ * trimmed — the tool's own rule for usable content, applied here because a
+ * rejected call keeps its args verbatim. The row then renders the counts alone
+ * rather than falling back to the generic tool summary: the counts are already
+ * known to be good, and the active-item clause is the only part an unusable
+ * name costs.
+ * @param todos - the whole list, in model order.
+ * @returns the done/total counts and the two summary halves.
+ */
+export function planSummary(todos: readonly PlanItemLike[]): PlanSummary {
+  const active = todos.filter(t => t.status === 'in_progress')
+  const first = active[0]?.content
+  const named = typeof first === 'string' && first.trim() !== ''
+  return {
+    done: todos.filter(t => t.status === 'completed').length,
+    total: todos.length,
+    activeContent: named ? first : null,
+    activeExtra: named ? active.length - 1 : 0,
+  }
+}
diff --git a/packages/client/ui-conversation/src/client/toolviews/todo-row.tsx b/packages/client/ui-conversation/src/client/toolviews/todo-row.tsx
index 4a66d9aa4d..d1072e2b4f 100644
--- a/packages/client/ui-conversation/src/client/toolviews/todo-row.tsx
+++ b/packages/client/ui-conversation/src/client/toolviews/todo-row.tsx
@@ -2,9 +2,10 @@
 // "Tool call" card, registered into the keyed 'conversation.chat.toolview'
 // hole like the bash sample (a product registration, not a sample). The row
 // composes ToolRow (chrome, running sweep, whole-row expand) and swaps in a
-// summary of the written list (counts + active item) from the call args; the
-// durable list itself renders in the TodoPanel above the composer, so the
-// row stays one line until expanded.
+// summary of the written list (counts + active items) from the call args, with
+// the parallel-active count riding ToolRow's non-shrinking summary suffix so a
+// narrow row never clips it; the durable list itself renders in the TodoPanel
+// above the composer, so the row stays one line until expanded.
 
 import { IconChecklistOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context } from 'cordis'
@@ -13,18 +14,26 @@ import type { ToolRowProps } from '../contract/slots.ts'
 import { toolRowModel } from '../contract/tool-call-model.ts'
 import { ToolRow } from '../chat/ToolRow.tsx'
 import { NS } from '../locales.ts'
+import { planSummary, type PlanItemLike } from './plan-summary.ts'
 
 /** Todo row props: the toolview runtime share plus the standard locale seat. */
 type TodoRowProps = ToolRowProps & PropsLocale<'conversation'>
 
-/** One parsed args item, shape-checked (model JSON: any field may be missing or mistyped). */
-interface TodoWriteItem { content?: unknown; status?: unknown }
-
-function isItem(value: unknown): value is TodoWriteItem {
+function isItem(value: unknown): value is PlanItemLike {
   return typeof value === 'object' && value !== null
 }
 
-function summarize(argsRaw: string, t: TodoRowProps['t']): string | null {
+/**
+ * The row's summary split at the ellipsis boundary: `text` truncates, `extra`
+ * is the parallel-active count that must not, so a narrow row never clips the
+ * one part that says several tasks are running.
+ */
+interface RowSummary {
+  text: string
+  extra: number
+}
+
+function summarize(argsRaw: string, t: TodoRowProps['t']): RowSummary | null {
   let parsed: unknown
   try {
     parsed = JSON.parse(argsRaw)
@@ -37,12 +46,12 @@ function summarize(argsRaw: string, t: TodoRowProps['t']): string | null {
   if (typeof parsed !== 'object' || parsed === null) return null
   const todos = (parsed as { todos?: unknown }).todos
   if (!Array.isArray(todos) || !todos.every(isItem)) return null
-  const done = todos.filter(item => item.status === 'completed').length
-  const active = todos.find(item => item.status === 'in_progress')
-  const head = t('todo.completed', { done, total: todos.length })
-  return typeof active?.content === 'string' && active.content !== ''
-    ? `${head} · ${active.content}`
-    : head
+  const { done, total, activeContent, activeExtra } = planSummary(todos)
+  const head = t('todo.completed', { done, total })
+  return {
+    text: activeContent === null ? head : `${head} · ${activeContent}`,
+    extra: activeExtra,
+  }
 }
 
 /** One-line plan update row (the whole row toggles the call's Input/Output
@@ -52,7 +61,7 @@ function summarize(argsRaw: string, t: TodoRowProps['t']): string | null {
 export function TodoRow({ toolName, block, inspect, t }: TodoRowProps) {
   const model = toolRowModel(toolName, block)
   const argsRaw = ('kind' in block ? block.call?.argsRaw : block.argsRaw) ?? ''
-  const summary = summarize(argsRaw, t) ?? model.summary
+  const summary = summarize(argsRaw, t) ?? { text: model.summary, extra: 0 }
   return (
     <ToolRow
       t={t}
@@ -60,7 +69,8 @@ export function TodoRow({ toolName, block, inspect, t }: TodoRowProps) {
       toolName={toolName}
       icon={<IconChecklistOutline14 />}
       title={t('todo.rowTitle')}
-      summary={summary}
+      summary={summary.text}
+      summarySuffix={summary.extra > 0 ? `+${summary.extra}` : null}
       body={model.body}
       output={model.output}
       errorSummary={model.errorSummary}
diff --git a/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx b/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
index 810a810fbb..246c79950d 100644
--- a/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-tool-row.spec.tsx
@@ -301,6 +301,20 @@ describe('ToolRow', () => {
     expect(view.getByText('List files')).toBeTruthy()
   })
 
+  it('renders summarySuffix outside the ellipsized summary span, and drops it on a failure line', () => {
+    const view = render(<ToolRow {...rowProps} summarySuffix="+2" />)
+    const summary = view.getByText('List files')
+    const suffix = view.getByText('+2')
+    // Separate spans: .summary truncates, the suffix must not travel inside it.
+    expect(summary.contains(suffix)).toBe(false)
+    view.unmount()
+    // The failure line replaces the summary wholesale, so the suffix goes with it.
+    const failed = render(
+      <ToolRow {...rowProps} state="error" errorSummary="boom" summarySuffix="+2" />,
+    )
+    expect(failed.queryByText('+2')).toBeNull()
+  })
+
   it('an error file row drops the open-file link (the summary is failure prose, not the path)', () => {
     const open = vi.fn()
     const view = render(
diff --git a/packages/client/ui-conversation/tests/todo-panel.spec.tsx b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
index 9cd2075cd7..3ab95168a7 100644
--- a/packages/client/ui-conversation/tests/todo-panel.spec.tsx
+++ b/packages/client/ui-conversation/tests/todo-panel.spec.tsx
@@ -1,10 +1,13 @@
 // @vitest-environment jsdom
 /**
- * Todo display acceptance: the TodoPanel plan strip (empty-hidden, status
- * rows, collapse), its TodoDock adapter (selects the plan off the session
- * snapshot and follows changes), and the todo_write toolview row (progress
- * summary from args, generic fallback on malformed JSON, shared ToolRow
- * state dots and leading expansion).
+ * Todo display acceptance: the TodoPanel plan strip (empty-hidden, status rows
+ * including several `in_progress` at once, collapse), its TodoDock adapter
+ * (selects the plan off the session snapshot and follows changes), the row's
+ * plan summary (counts plus the two halves of the active summary — the named
+ * task and the `+N` count that parallel work adds, kept apart so the row never
+ * ellipsizes the count away), and the todo_write toolview row (progress summary
+ * from args, generic fallback on malformed JSON, shared ToolRow state dots and
+ * leading expansion).
  */
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -17,6 +20,7 @@ import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts
 import { TodoRow, todoToolview } from '../src/client/toolviews/todo-row.tsx'
 import type { TodoDockProps } from '../src/client/skeleton/TodoPanel.tsx'
 import { TodoDock, TodoPanel, todoDockEntry } from '../src/client/skeleton/TodoPanel.tsx'
+import { planSummary } from '../src/client/toolviews/plan-summary.ts'
 import { NS, zh } from '../src/client/locales.ts'
 
 type TodoRowProps = Parameters<typeof TodoRow>[0]
@@ -32,6 +36,49 @@ const LIST: TodoItem[] = [
   { content: '补测试', status: 'pending' },
 ]
 
+/** A parallel plan: three tasks running at once (concurrent subagents). */
+const PARALLEL: TodoItem[] = [
+  { content: '搭骨架', status: 'completed' },
+  { content: '写组件', status: 'in_progress' },
+  { content: '跑后台构建', status: 'in_progress' },
+  { content: '读源码', status: 'in_progress' },
+  { content: '补测试', status: 'pending' },
+]
+
+describe('planSummary', () => {
+  it('counts done/total and names the single active item with no extra count', () => {
+    expect(planSummary(LIST)).toEqual({ done: 1, total: 3, activeContent: '写组件', activeExtra: 0 })
+  })
+
+  it('reports the extra active count separately when several items are in progress', () => {
+    // Parallel work marks several: naming one and hiding the rest would lose
+    // them, and the count stays unjoined so the row cannot ellipsize it.
+    expect(planSummary(PARALLEL)).toEqual({ done: 1, total: 5, activeContent: '写组件', activeExtra: 2 })
+  })
+
+  it('has no hint when nothing is in progress', () => {
+    expect(planSummary([{ content: '都完了', status: 'completed' }]))
+      .toEqual({ done: 1, total: 1, activeContent: null, activeExtra: 0 })
+  })
+
+  it('has no hint when the first active item carries no usable content (model JSON)', () => {
+    // Unvalidated args: a missing, mistyped, empty, or whitespace-only content
+    // yields no hint — and no orphan count, even with a second active item to
+    // count. Whitespace-only is the tool's own rejection rule (trimmed
+    // non-empty), and a rejected call keeps its args verbatim.
+    expect(planSummary([{ status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
+      .toMatchObject({ activeContent: null, activeExtra: 0 })
+    expect(planSummary([{ content: 42, status: 'in_progress' }]).activeContent).toBeNull()
+    expect(planSummary([{ content: '', status: 'in_progress' }]).activeContent).toBeNull()
+    expect(planSummary([{ content: '   ', status: 'in_progress' }, { content: 'x', status: 'in_progress' }]))
+      .toMatchObject({ activeContent: null, activeExtra: 0 })
+  })
+
+  it('is empty-safe', () => {
+    expect(planSummary([])).toEqual({ done: 0, total: 0, activeContent: null, activeExtra: 0 })
+  })
+})
+
 describe('TodoPanel', () => {
   it('renders nothing while the list is empty', () => {
     const { container } = render(<TodoPanel todos={[]} t={t} />)
@@ -80,6 +127,18 @@ describe('TodoPanel', () => {
     expect(screen.getAllByRole('listitem')).toHaveLength(3)
   })
 
+  it('marks every parallel active item, and counts them all in the header', () => {
+    render(<TodoPanel todos={PARALLEL} t={t} />)
+    fireEvent.click(screen.getByRole('button', { expanded: false }))
+    // The old unconditional cap made this list unreachable: three items carry
+    // the in-progress glyph at once, and the header counts all three.
+    const statuses = screen.getAllByRole('listitem').map(li => li.getAttribute('data-status'))
+    expect(statuses.filter(s => s === 'in_progress')).toHaveLength(3)
+    expect(screen.getByText('跑后台构建')).toBeTruthy()
+    expect(screen.getByText('读源码')).toBeTruthy()
+    expect(screen.getByText('1 已完成 · 3 进行中 · 1 待处理')).toBeTruthy()
+  })
+
   it('an all-completed list collapses the summary to the done count alone', () => {
     render(<TodoPanel todos={[{ content: '都完了', status: 'completed' }]} t={t} />)
     expect(screen.getByRole('button', { expanded: false })).toBeTruthy()
@@ -145,12 +204,30 @@ describe('TodoRow', () => {
     expect(screen.getByText('1/3 已完成 · 写组件')).toBeTruthy()
   })
 
+  it('reports the extra active count outside the ellipsized summary text', () => {
+    const { container } = render(<TodoRow {...rowProps(resultNode(JSON.stringify({ todos: PARALLEL })))} />)
+    const text = screen.getByText('1/5 已完成 · 写组件')
+    const extra = screen.getByText('+2')
+    // Separate spans: .summary truncates, the count must not travel inside it.
+    expect(text.contains(extra)).toBe(false)
+    expect(container.textContent).toContain('1/5 已完成 · 写组件+2')
+  })
+
   it('omits the active clause when no item is in progress and reads running-call args', () => {
     const args = JSON.stringify({ todos: [{ content: 'x', status: 'completed' }] })
     render(<TodoRow {...rowProps({ callId: 'c1', name: 'todo_write', argsRaw: args, turn: 1, step: 1, time: 1_000, callView: null })} />)
     expect(screen.getByText('1/1 已完成')).toBeTruthy()
   })
 
+  it('keeps the counts when an active item has unusable content, instead of the generic summary', () => {
+    // planSummary yields activeContent null here, but the counts are known good,
+    // so the row drops only the active clause — `?? model.summary` never runs.
+    const args = JSON.stringify({ todos: [{ content: 'done', status: 'completed' }, { content: 42, status: 'in_progress' }] })
+    const { container } = render(<TodoRow {...rowProps(resultNode(args))} />)
+    expect(screen.getByText('1/2 已完成')).toBeTruthy()
+    expect(container.textContent).not.toContain('+')
+  })
+
   it('keeps the non-ok execution states visible through the shared row states', () => {
     // A running call (no result yet) carries the running state (row sweep).
     const args = JSON.stringify({ todos: LIST })
diff --git a/packages/client/ui-conversation/tests/tool-row-styles.spec.ts b/packages/client/ui-conversation/tests/tool-row-styles.spec.ts
new file mode 100644
index 0000000000..300266a69a
--- /dev/null
+++ b/packages/client/ui-conversation/tests/tool-row-styles.spec.ts
@@ -0,0 +1,45 @@
+/**
+ * The one-line contract of the ToolRow summary line as CSS text. jsdom has no
+ * layout, so the rendering specs (chat-tool-row.spec.tsx) can pin which spans
+ * exist but not whether a narrow row still fits on one line; these read the
+ * declarations the layout depends on.
+ */
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const css = readFileSync(fileURLToPath(new URL('../src/client/chat/ToolRow.module.css', import.meta.url)), 'utf8')
+/** Declarations only: the sheet's prose names the properties it explains. */
+const declarationText = css.replace(/\/\*[\s\S]*?\*\//g, ' ')
+
+function declarations(selector: string): string[] {
+  // Anchored at a rule boundary: an unanchored match would silently read a
+  // compound rule that merely contains the selector (`.root:hover .summarySuffix`)
+  // if one ever lands above the base rule.
+  const rule = new RegExp(`(?:^|\\})\\s*\\${selector}\\s*\\{([^{}]*)\\}`).exec(declarationText)
+  if (rule === null) throw new Error(`ToolRow.module.css has no \`${selector}\` rule`)
+  return (rule[1] ?? '').split(';').map(part => part.trim()).filter(Boolean)
+}
+
+describe('ToolRow.module.css summary line', () => {
+  it('keeps the summary suffix on one line and unshrunk', () => {
+    // `flex: none` stops the box shrinking, not the text wrapping: without
+    // `nowrap`, a row too narrow for title + separator + suffix wraps the `+n`
+    // onto a second line — the exact case the slot exists to survive.
+    expect(declarations('.summarySuffix')).toEqual(expect.arrayContaining([
+      'flex: none',
+      'white-space: nowrap',
+    ]))
+  })
+
+  it('leaves the truncation to the summary text alone', () => {
+    // The suffix must never ellipsize: a clipped count reads as a smaller
+    // number rather than as missing information.
+    expect(declarations('.summary')).toEqual(expect.arrayContaining([
+      'overflow: hidden',
+      'text-overflow: ellipsis',
+      'white-space: nowrap',
+    ]))
+    expect(declarations('.summarySuffix')).not.toEqual(expect.arrayContaining(['text-overflow: ellipsis']))
+  })
+})
diff --git a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
index 7ee67484bc..c8668c3700 100644
--- a/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
+++ b/packages/client/ui-models/src/client/DeepSeekOnboardingDialog.tsx
@@ -7,7 +7,7 @@
 import { useEffect, useRef } from 'react'
 import type { ReactNode } from 'react'
 import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { BrandWordmark, Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import { BrandWordmark, Button, OnboardingSurface } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
 import type { ModelsSettingsState, ModelsSettingsStore } from './store.ts'
 import { deepSeekReadiness } from './store.ts'
@@ -66,6 +66,9 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
     openSection('models')
   }
 
+  // Null covers the still-deciding and nothing-to-do states alike: the
+  // takeover chrome below is part of THIS render, so declining paints and
+  // blocks nothing while the shared join is in flight.
   switch (readiness.kind) {
     case 'loading':
     case 'adapter-absent':
@@ -80,25 +83,27 @@ export function DeepSeekOnboardingDialog(props: DeepSeekOnboardingDialogProps):
   }
 
   return (
-    <section className={styles['page']} role="region" aria-labelledby="deepseek-onboarding-title">
-      <div className={styles['brand']} aria-hidden="true"><BrandWordmark size={24} /></div>
-      <h2
-        ref={titleRef}
-        id="deepseek-onboarding-title"
-        className={styles['title']}
-        tabIndex={-1}
-      >
-        {t('onboardingTitle')}
-      </h2>
-      <p className={styles['description']}>{t('onboardingDescription')}</p>
-      <div className={styles['actions']}>
-        <Button variant="ghost" className={styles['later']} onClick={complete}>
-          {t('onboardingLater')}
-        </Button>
-        <Button variant="primary" className={styles['primary']} onClick={openModels}>
-          {t('onboardingGoToSettings')}
-        </Button>
-      </div>
-    </section>
+    <OnboardingSurface>
+      <section className={styles['page']} role="region" aria-labelledby="deepseek-onboarding-title">
+        <div className={styles['brand']} aria-hidden="true"><BrandWordmark size={24} /></div>
+        <h2
+          ref={titleRef}
+          id="deepseek-onboarding-title"
+          className={styles['title']}
+          tabIndex={-1}
+        >
+          {t('onboardingTitle')}
+        </h2>
+        <p className={styles['description']}>{t('onboardingDescription')}</p>
+        <div className={styles['actions']}>
+          <Button variant="ghost" className={styles['later']} onClick={complete}>
+            {t('onboardingLater')}
+          </Button>
+          <Button variant="primary" className={styles['primary']} onClick={openModels}>
+            {t('onboardingGoToSettings')}
+          </Button>
+        </div>
+      </section>
+    </OnboardingSurface>
   )
 }
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index 7429447091..47cebf796f 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/client/ui-primitives/README.md
-README.md: 385730c94831d2fd4af83f9eca0f55941551c796
-README.zh.md: b8a75dbffc6549f6294dfda5988c67d6569386c9
+README.md: 7571cb48424b650a1aaa5222b33a3ee14faa69b4
+README.zh.md: fa0c3f24023ec8c1eb77553bfe191801b6698687
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 385730c948..7571cb4842 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the OnboardingSurface first-run takeover (body-portaled mask + opaque stage that holds `#root` inert for exactly its own lifetime), the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, DiffBlock, ReadBlock, SearchBlock, and WebBlock. Contract: api-contracts v3 §8.
 
 ## Hover cards
 
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index b8a75dbffc..fa0c3f2402 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、OnboardingSurface 首次使用接管层（portal 到 body 的遮罩加不透明展示层，在自身生命周期内保持 `#root` 为 `inert`）、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、DiffBlock、ReadBlock、SearchBlock，以及 WebBlock。契约：api-contracts v3 §8。
 
 ## 悬浮卡片
 
diff --git a/packages/client/ui-primitives/src/OnboardingSurface.module.css b/packages/client/ui-primitives/src/OnboardingSurface.module.css
new file mode 100644
index 0000000000..e019061c21
--- /dev/null
+++ b/packages/client/ui-primitives/src/OnboardingSurface.module.css
@@ -0,0 +1,29 @@
+/* First-run stage: keep the product top bar visible, then let onboarding own
+   the complete workspace instead of presenting another settings modal. */
+.onboardingOverlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+}
+
+/* Mask */
+.onboardingMask {
+  position: absolute;
+  left: 0px;
+  right: 0px;
+  top: 80px;
+  bottom: 0px;
+  background: rgba(0, 0, 0, 0.24);
+  /* Mask-blur */
+  backdrop-filter: blur(2px);
+}
+
+.onboardingStage {
+  position: absolute;
+  z-index: 1;
+  inset: 0;
+  display: flex;
+  justify-content: center;
+  overflow: hidden;
+  background: var(--dsw-alias-bg-layer-1);
+}
diff --git a/packages/client/ui-primitives/src/OnboardingSurface.tsx b/packages/client/ui-primitives/src/OnboardingSurface.tsx
new file mode 100644
index 0000000000..1bbb6cbc46
--- /dev/null
+++ b/packages/client/ui-primitives/src/OnboardingSurface.tsx
@@ -0,0 +1,34 @@
+// OnboardingSurface: the full-viewport first-run takeover an onboarding step
+// wraps its visible content in. The overlay portals to this document's body
+// (the Modal precedent: ancestor stacking contexts cannot leave sticky page
+// controls above the mask), and the surface holds `#root` inert for exactly
+// its own lifetime — a step that renders null paints nothing and blocks
+// nothing, so "should onboarding show right now" stays a plain render
+// decision inside the step component.
+
+import { useEffect } from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import css from './OnboardingSurface.module.css'
+
+/**
+ * Render the onboarding takeover chrome (mask + opaque stage) around one
+ * step's content and keep the application root inert while mounted.
+ * @param props.children - the step's page content, centered on the stage.
+ * @returns the body-portaled overlay tree.
+ */
+export function OnboardingSurface({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    const appRoot = document.getElementById('root')
+    if (appRoot === null) return
+    appRoot.inert = true
+    return () => { appRoot.inert = false }
+  }, [])
+
+  return createPortal((
+    <div className={css.onboardingOverlay} role="presentation">
+      <div className={css.onboardingMask} aria-hidden="true" />
+      <div className={css.onboardingStage}>{children}</div>
+    </div>
+  ), document.body)
+}
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index feecb95d3e..fe0235c496 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -13,6 +13,7 @@ export type { MenuEntry, MenuItem, MenuSeparator, MenuLabel } from './Menu.tsx'
 export { useAnchoredMaxHeight } from './useAnchoredMaxHeight.ts'
 export { HoverCard } from './HoverCard.tsx'
 export { Modal } from './Modal.tsx'
+export { OnboardingSurface } from './OnboardingSurface.tsx'
 export { RiskConfirmation } from './RiskConfirmation.tsx'
 export type { RiskConfirmationProps } from './RiskConfirmation.tsx'
 export { ConnectionBanner } from './ConnectionBanner.tsx'
diff --git a/packages/client/ui-primitives/tests/onboarding-surface.spec.tsx b/packages/client/ui-primitives/tests/onboarding-surface.spec.tsx
new file mode 100644
index 0000000000..73604c9644
--- /dev/null
+++ b/packages/client/ui-primitives/tests/onboarding-surface.spec.tsx
@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { OnboardingSurface } from '@deepseek-ai/dsh-client-ui-primitives'
+
+let appRoot: HTMLDivElement
+
+beforeEach(() => {
+  appRoot = document.createElement('div')
+  appRoot.id = 'root'
+  document.body.appendChild(appRoot)
+})
+
+afterEach(() => {
+  cleanup()
+  appRoot.remove()
+})
+
+describe('OnboardingSurface', () => {
+  it('portals the overlay chrome to document.body around its content', () => {
+    const view = render(<OnboardingSurface><p>step content</p></OnboardingSurface>)
+    // Portaled: the overlay is a body child, not inside the render container.
+    expect(view.container.querySelector('[class*="onboardingOverlay"]')).toBeNull()
+    const overlay = document.body.querySelector('[class*="onboardingOverlay"]')
+    expect(overlay).not.toBeNull()
+    // The onboarding e2e pins the mask by class substring; the stage carries
+    // the content.
+    expect(overlay!.querySelector('[class*="onboardingMask"]')).not.toBeNull()
+    const stage = overlay!.querySelector('[class*="onboardingStage"]')
+    expect(stage).not.toBeNull()
+    expect(stage!.textContent).toBe('step content')
+  })
+
+  it('holds #root inert for exactly its own lifetime', () => {
+    const view = render(<OnboardingSurface>x</OnboardingSurface>)
+    expect(appRoot.inert).toBe(true)
+    view.unmount()
+    expect(appRoot.inert).toBe(false)
+  })
+
+  it('renders without an #root element (compositions that mount elsewhere)', () => {
+    appRoot.remove()
+    const view = render(<OnboardingSurface>x</OnboardingSurface>)
+    expect(document.body.querySelector('[class*="onboardingStage"]')!.textContent).toBe('x')
+    view.unmount()
+  })
+})
diff --git a/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx
index c25b1bf3aa..34187073a1 100644
--- a/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx
+++ b/packages/client/ui-settings-general/src/client/WelcomeNotice.tsx
@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useRef } from 'react'
 import type { ReactNode } from 'react'
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { BrandWordmark, Button } from '@deepseek-ai/dsh-client-ui-primitives'
+import { BrandWordmark, Button, OnboardingSurface } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SnapshotSelectorHook } from '@deepseek-ai/dsh-client-web-react'
 import type { WelcomeNoticeState, WelcomeNoticeStore } from './welcome-store.ts'
 import css from './WelcomeNotice.module.css'
@@ -55,6 +55,9 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
     if (state.status === 'ready' && !state.acknowledged) titleRef.current?.focus()
   }, [state.acknowledged, state.status])
 
+  // Null while the acknowledgement fact is still loading (or already given):
+  // the takeover chrome below is part of THIS render, so deciding not to
+  // show paints and blocks nothing.
   if (state.status === 'idle' || state.status === 'loading' || state.acknowledged) return null
 
   const acknowledge = async (): Promise<void> => {
@@ -62,25 +65,27 @@ export function WelcomeNotice(props: WelcomeNoticeProps): ReactNode {
   }
 
   return (
-    <section className={css.page} role="region" aria-labelledby="welcome-notice-title">
-      <div className={css.brand} aria-hidden="true"><BrandWordmark size={24} /></div>
-      <h2 ref={titleRef} id="welcome-notice-title" className={css.title} tabIndex={-1}>{t('welcome.title')}</h2>
-      <p className={css.opening}>{t('welcome.paragraph.0')}</p>
-      <blockquote className={css.reflection}>{t('welcome.paragraph.1')}</blockquote>
-      <p className={css.feedback}>
-        {emphasizedFeedback(t('welcome.paragraph.2'), t('welcome.feedbackEmphasis'))}
-      </p>
-      {state.error === null ? null : <p className={css.error} role="alert">{t('welcome.error')}</p>}
-      <div className={css.footer}>
-        <Button
-          variant="primary"
-          className={css.primary}
-          disabled={state.status === 'saving'}
-          onClick={() => { void acknowledge() }}
-        >
-          {t('welcome.continue')}
-        </Button>
-      </div>
-    </section>
+    <OnboardingSurface>
+      <section className={css.page} role="region" aria-labelledby="welcome-notice-title">
+        <div className={css.brand} aria-hidden="true"><BrandWordmark size={24} /></div>
+        <h2 ref={titleRef} id="welcome-notice-title" className={css.title} tabIndex={-1}>{t('welcome.title')}</h2>
+        <p className={css.opening}>{t('welcome.paragraph.0')}</p>
+        <blockquote className={css.reflection}>{t('welcome.paragraph.1')}</blockquote>
+        <p className={css.feedback}>
+          {emphasizedFeedback(t('welcome.paragraph.2'), t('welcome.feedbackEmphasis'))}
+        </p>
+        {state.error === null ? null : <p className={css.error} role="alert">{t('welcome.error')}</p>}
+        <div className={css.footer}>
+          <Button
+            variant="primary"
+            className={css.primary}
+            disabled={state.status === 'saving'}
+            onClick={() => { void acknowledge() }}
+          >
+            {t('welcome.continue')}
+          </Button>
+        </div>
+      </section>
+    </OnboardingSurface>
   )
 }
diff --git a/packages/client/ui-settings/README.i18n.yaml b/packages/client/ui-settings/README.i18n.yaml
index 989fb18e64..5871fb996f 100644
--- a/packages/client/ui-settings/README.i18n.yaml
+++ b/packages/client/ui-settings/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/client/ui-settings/README.md
-README.md: de78d599b7833179339ceeb680fbd665b056bd83
-README.zh.md: 8ae3bdf34f59ca03e4796c354df739aa9fe29bd9
+README.md: 785f0417f00ec8eb1f8c9273b4d81f8ca5ca1810
+README.zh.md: 8e7bd7325b78416345985ee25a56a5eb8b382478
diff --git a/packages/client/ui-settings/README.md b/packages/client/ui-settings/README.md
index de78d599b7..785f0417f0 100644
--- a/packages/client/ui-settings/README.md
+++ b/packages/client/ui-settings/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Settings shell plugin: a pure composition face. It occupies `sidebar.settings` with the trigger chrome and modal settings panel, and declares the slots registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.action` (ordered content-header actions), `settings.section` (one page per feature), and `settings.onboarding` (ordered feature-owned pages in a full-viewport stage). The shell ships no copy of its own — all text arrives from registrants (ui-settings-general owns chrome, General, and the product notice; features own their actions, sections, rows, and conditional onboarding pages). Nav labels may be locale-following thunks, so the nav projection resolves them through `resolveSlotLabel` and re-renders on the section ledger bump or the locale revision (an optional `ctx.get('locale')` read; no hard locale dependency).
 
-The shell projects the onboarding ledger into ascending order and mounts exactly one page at a time in a body-level stage while marking the underlying app root inert. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, and mutations, so independently registered flows cannot stack and the shell does not become a second configuration fact source.
+The shell projects the onboarding ledger into ascending order and mounts exactly one page at a time; the takeover chrome (body-level stage, mask, app-root `inert`) belongs to the step itself through ui-primitives' `OnboardingSurface`, so a mounted step still resolving its private facts renders null and neither paints nor blocks anything — the shell shows no empty stage while a step decides. The active registrant receives its id, `complete()`, and an `openSection(id)` callback; completing or skipping transfers ownership to the next entry. Registrants own durable completion, capability readiness, copy, mutations, and the surface wrap, so independently registered flows cannot stack and the shell does not become a second configuration fact source.
 
 ## Model Experience
 
diff --git a/packages/client/ui-settings/README.zh.md b/packages/client/ui-settings/README.zh.md
index 8ae3bdf34f..8e7bd7325b 100644
--- a/packages/client/ui-settings/README.zh.md
+++ b/packages/client/ui-settings/README.zh.md
@@ -4,7 +4,7 @@
 
 设置外壳插件：一个纯组合表层。它以触发控件和模态设置面板占用 `sidebar.settings`，并声明由注册方填充的 slot：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.action`（内容标题栏中的有序操作）、`settings.section`（每项功能一页）和 `settings.onboarding`（由各功能持有、显示在全视口展示层中的有序页面）。外壳不自带文案：所有文本都来自注册方（ui-settings-general 拥有界面框架、「通用」分区和产品声明；各功能拥有各自的操作、分区、行和条件式首次使用引导页面）。导航 label 可以是跟随语言的 thunk，因此导航投影经 `resolveSlotLabel` 解析，并在分区账本更新或 locale revision 变化时重新渲染（`ctx.get('locale')` 可选读取，无硬 locale 依赖）。
 
-外壳将首次使用引导记录按升序投影，在 body 层级的展示层中每次只挂载一个页面，同时将下层应用根节点标记为 `inert`。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案和变更操作均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
+外壳将首次使用引导记录按升序投影，每次只挂载一个页面；接管界面框架（body 层级的展示层、遮罩、应用根节点 `inert`）经 ui-primitives 的 `OnboardingSurface` 由步骤自身持有，因此已挂载但仍在判定私有事实的步骤渲染 null 时不绘制也不阻塞任何内容——步骤判定期间外壳不会露出空白展示层。当前注册方会收到该条目的 id、`complete()` 和 `openSection(id)` 回调；完成或跳过当前页面后，所有权转交给下一项。持久化完成状态、能力就绪状态、文案、变更操作以及页面的外层包裹均由注册方持有，因此独立注册的流程无法堆叠，外壳也不会成为第二个配置事实来源。
 
 ## 模型体验
 
diff --git a/packages/client/ui-settings/src/client/SettingsRoot.module.css b/packages/client/ui-settings/src/client/SettingsRoot.module.css
index 72c188e019..e70558081a 100644
--- a/packages/client/ui-settings/src/client/SettingsRoot.module.css
+++ b/packages/client/ui-settings/src/client/SettingsRoot.module.css
@@ -219,33 +219,3 @@
   clip: rect(0 0 0 0);
   white-space: nowrap;
 }
-
-/* First-run stage: keep the product top bar visible, then let onboarding own
-   the complete workspace instead of presenting another settings modal. */
-.onboardingOverlay {
-  position: fixed;
-  inset: 0;
-  z-index: 1100;
-}
-
-/* Mask */
-.onboardingMask {
-  position: absolute;
-  left: 0px;
-  right: 0px;
-  top: 80px;
-  bottom: 0px;
-  background: rgba(0, 0, 0, 0.24);
-  /* Mask-blur */
-  backdrop-filter: blur(2px);
-}
-
-.onboardingStage {
-  position: absolute;
-  z-index: 1;
-  inset: 0;
-  display: flex;
-  justify-content: center;
-  overflow: hidden;
-  background: var(--dsw-alias-bg-layer-1);
-}
diff --git a/packages/client/ui-settings/src/client/SettingsRoot.tsx b/packages/client/ui-settings/src/client/SettingsRoot.tsx
index 45055753ac..d6b2e8ef5a 100644
--- a/packages/client/ui-settings/src/client/SettingsRoot.tsx
+++ b/packages/client/ui-settings/src/client/SettingsRoot.tsx
@@ -7,10 +7,11 @@
  * aria-labelledby the title node; close: visually-hidden slot text). Modal
  * open state and the active section id are component-local viewing state;
  * the onboarding coordinator mounts exactly one ordered registrant while the
- * sessions-derived empty-Hero fact is active.
+ * sessions-derived empty-Hero fact is active — the takeover chrome
+ * (OnboardingSurface) belongs to the step, so a mounted-but-deciding step
+ * paints nothing here.
  */
 import { useCallback, useEffect, useId, useRef, useState } from 'react'
-import { createPortal } from 'react-dom'
 import clsx from 'clsx'
 import { IconCloseOutline16, IconDataOutline16, IconSettingsOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SettingsRootComponentProps, SettingsSectionRow } from './contract/slots.ts'
@@ -134,14 +135,6 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
     })
   }, [])
 
-  useEffect(() => {
-    if (onboardingStep === undefined) return
-    const appRoot = document.getElementById('root')
-    if (appRoot === null) return
-    appRoot.inert = true
-    return () => { appRoot.inert = false }
-  }, [onboardingStep])
-
   return (
     <>
       <button
@@ -162,18 +155,15 @@ export function SettingsRoot(props: SettingsRootComponentProps) {
           onClose={close}
         />
       )}
-      {onboardingStep !== undefined && createPortal((
-        <div className={css.onboardingOverlay} role="presentation">
-          <div className={css.onboardingMask} aria-hidden="true" />
-          <div className={css.onboardingStage}>
-            {renderSlot('settings.onboarding', {
-              stepId: onboardingStep.id,
-              complete: () => { completeOnboardingStep(onboardingStep.id) },
-              openSection,
-            }, { only: onboardingStep.id })}
-          </div>
-        </div>
-      ), document.body)}
+      {/* The takeover chrome (OnboardingSurface: mask, opaque stage, `#root`
+          inert) lives inside the step component, wrapped around its visible
+          content — a step still deciding (private facts loading) renders
+          null, so nothing paints or blocks while it decides. */}
+      {onboardingStep !== undefined && renderSlot('settings.onboarding', {
+        stepId: onboardingStep.id,
+        complete: () => { completeOnboardingStep(onboardingStep.id) },
+        openSection,
+      }, { only: onboardingStep.id })}
     </>
   )
 }
diff --git a/packages/client/ui-settings/src/client/contract/slots.ts b/packages/client/ui-settings/src/client/contract/slots.ts
index e585fa5b6f..8516ce8860 100644
--- a/packages/client/ui-settings/src/client/contract/slots.ts
+++ b/packages/client/ui-settings/src/client/contract/slots.ts
@@ -57,7 +57,13 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
      * Root-scoped onboarding steps contributed by settings features. The
      * shell mounts one ordered step at a time; the active registrant either
      * completes itself or keeps ownership until the user completes its sole
-     * path. Registrants own readiness, copy, and dialog behavior.
+     * path. Registrants own readiness, copy, dialog behavior, AND the
+     * takeover chrome: a step wraps its visible content in the
+     * OnboardingSurface primitive (mask, opaque stage, `#root` inert) and
+     * renders null while its private facts are still loading — the shell
+     * paints no chrome of its own, so a mounted-but-deciding step shows and
+     * blocks nothing (the reload white-flash fix; a bare unwrapped step
+     * would render without mask or stage).
      */
     'settings.onboarding': { kind: 'list'; scope: 'root'; owner: SettingsOnboardingOwnerProps }
   }
diff --git a/packages/client/ui-settings/tests/settings-root.spec.tsx b/packages/client/ui-settings/tests/settings-root.spec.tsx
index 900c66d381..40b4dc29c2 100644
--- a/packages/client/ui-settings/tests/settings-root.spec.tsx
+++ b/packages/client/ui-settings/tests/settings-root.spec.tsx
@@ -204,14 +204,19 @@ describe('SettingsPanel navigation', () => {
     expect(inactive).toHaveLength(0)
   })
 
-  it('makes the underlying application inert while onboarding owns the viewport', () => {
+  it('paints no takeover chrome of its own around the mounted step', () => {
+    // The chrome (mask, opaque stage, #root inert) belongs to the step via
+    // the OnboardingSurface primitive — a mounted-but-deciding step that
+    // renders null must show and block nothing (the reload white-flash fix;
+    // onboarding-surface.spec.tsx pins the primitive's half).
     const appRoot = document.createElement('div')
     appRoot.id = 'root'
     document.body.append(appRoot)
     const { view } = mount()
-    expect(appRoot.inert).toBe(true)
+    expect(view.container.querySelector('[class*="onboarding"]')).toBeNull()
+    expect(document.body.querySelector('[class*="onboarding"]')).toBeNull()
+    expect(appRoot.inert).not.toBe(true)
     view.unmount()
-    expect(appRoot.inert).toBe(false)
     appRoot.remove()
   })
 
diff --git a/packages/context/workspace-context/README.i18n.yaml b/packages/context/workspace-context/README.i18n.yaml
index bd8c55d78c..753836e528 100644
--- a/packages/context/workspace-context/README.i18n.yaml
+++ b/packages/context/workspace-context/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/context/workspace-context/README.md
-README.md: 7add269c7a1b38e9624cf6d0368151661bc72a6b
-README.zh.md: 3456c5c36275e8e521b312b1b0b7e1dd102ca23c
+README.md: 82aee27a8fbd6a1ab0f0860226b081e28ba72e6e
+README.zh.md: 9d983f95f4e018cb8fe983d9862cf5f31f83c5f2
diff --git a/packages/context/workspace-context/README.md b/packages/context/workspace-context/README.md
index 7add269c7a..82aee27a8f 100644
--- a/packages/context/workspace-context/README.md
+++ b/packages/context/workspace-context/README.md
@@ -6,7 +6,7 @@ Per-session workspace instruction loading for `AGENTS.md`-compatible files. The
 
 ## Lifecycle
 
-The first eligible `agent/pre-step` of each live session composes the baseline. When the downstream decision enters a nonempty first-step batch, the plugin folds the baseline into that final batch right after the claimed prompt, so the direct prompt and the durable baseline enter step 1 and reach the first request together. A rejected or empty first-step decision leaves the baseline in the agent's `next-step` inbox for a later wakeup. The loader reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. If a previously queued workspace context is still pending, the plugin removes and replaces that exact inbox item instead of accumulating duplicates.
+The first eligible `agent/pre-step` of each live session composes the baseline. When the downstream decision enters a nonempty first-step batch, the plugin folds the baseline into that final batch right after the claimed prompt, so the direct prompt and the durable baseline enter step 1 and reach the first request together. A rejected or empty first-step decision leaves the baseline in the agent's `next-step` inbox for a later wakeup. The loader reads `$DSH_HOME/AGENTS.md` followed by, in each directory from the project root to `agent.session.header.cwd`, every existing base candidate and then every existing local-overlay candidate. Within one directory, candidates whose content is byte-identical after trimming leading and trailing whitespace collapse to the earliest candidate in configured order, so a `CLAUDE.md` that merely duplicates its sibling `AGENTS.md` is rendered once. If a previously queued workspace context is still pending, the plugin removes and replaces that exact inbox item instead of accumulating duplicates. A resumed session retains one compatible visible baseline and appends only current-file transitions; a changed discovery, precedence, project-root, or budget identity instead folds one explicitly superseding complete baseline into the entering batch.
 
 The plugin also listens on `tools/post-execute` for successful first-party `read`, `write`, and `edit` calls. Each touch checks newly reached descendant scopes and every previously loaded scope. Each configured candidate name is an independent scope in its directory: a newly present file is attached through the result's `additionalContexts`; a changed file appends a replacement; a file that disappears or becomes a per-directory duplicate of an earlier candidate appends a removal notice. Native calls and Code Mode sub-dispatches share this path: `run_code` defers each nested context until its outer result, so the loop still appends updates after tool-call/result adjacency is complete. This follows structured filesystem activity rather than shell `cd`, because each local bash call starts a fresh shell and parsing arbitrary shell syntax would be unreliable.
 
@@ -48,11 +48,11 @@ The plugin owns the complete `<system-reminder>` framing, and every injected `us
 
 ## State And Refresh
 
-Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; the complete startup or resume baseline also carries `baseline: true`. A matching durable `user/message` confirms a queued baseline and its candidate versions. An entering pre-step folds newly composed context into its final batch immediately after the claimed messages and removes the pending inbox copy; rejection keeps the current context queued. If a listener rewrites away a claimed workspace message without entering its replacement, a later boundary recomposes the current context. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. If the owning `step/end` arrives before a matching dynamic context reaches the log, the plugin clears that pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
+Model-visible text contains no hidden state markers. Each baseline or dynamic context event instead carries a typed `workspace-instructions` source with a list of `{ action, scope, path, digest? }` changes; a complete baseline also carries `baseline: true` and a `baselineIdentity` derived from normalized discovery, precedence, project-root, and budget configuration. A matching durable `user/message` confirms a queued baseline and its candidate versions. An entering pre-step folds newly composed context into its final batch immediately after the claimed messages and removes the pending inbox copy; rejection keeps the current context queued. If a listener rewrites away a claimed workspace message without entering its replacement, a later boundary recomposes the current context. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. If the owning `step/end` arrives before a matching dynamic context reaches the log, the plugin clears that pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
 
 An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope provider cache stores only `{ path, version, digest, trimmedDigest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. The `trimmedDigest` — SHA-1 over the whitespace-trimmed content — is the per-directory duplicate key, so an unchanged file can still be removed when an earlier candidate converges on its content. Resume works because SHA-1 state is persisted in the typed source, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter the source, pending state, and version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates only the provider cache.
 
-The initial baseline event itself is not rewritten. Its typed changes remain authoritative only while that event is in the visible session surface; the next successful filesystem touch re-adds an unchanged baseline scope after compaction, or appends its replacement or removal. The in-memory scope marker and provider-version cache only select and accelerate probes. A hot plugin remount retains a baseline only when its typed event remains visible, while rebuilding current scope and version tracking; otherwise it queues a current baseline. A resumed loop always recomposes the current baseline and also reconciles still-visible dynamic scopes at its first pre-step; an entering first request records that context in the same step. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, or when a resumed loop prepares its baseline.
+The initial baseline event itself is not rewritten. Its typed changes remain authoritative only while that event is in the visible session surface. When compaction shadows the event, the next entering pre-step composes the current baseline and records it in the same request; a successful filesystem touch can instead re-add an unchanged baseline scope or append its replacement or removal. The in-memory scope marker and provider-version cache only select and accelerate probes. At the first pre-step after resume or hot remount, a compatible visible baseline is retained and compared with the files retained by the current complete rendering. Unchanged and budget-omitted files append nothing; offline additions, edits, removals, and files leaving the retained budget set append `set`, `replace`, or `remove` transitions. An incompatible visible baseline is superseded by one complete current baseline, including an explicit empty baseline when no candidate remains. There is no file watcher, so an on-disk change becomes visible at the next successful `read`, `write`, or `edit` touch, when a resumed session reconciles its baseline, or when an entering pre-step restores a shadowed baseline.
 
 ## Configuration
 
@@ -83,7 +83,7 @@ Instruction content is read through `streamText()` under `maxSourceBytes`, even
 
 #### What the model sees
 
-At the first request of each loop instance, the model receives one durable user-role message containing the bounded user-global and project instruction chain in broad-to-specific order.
+At the first request, derived history contains one durable user-role message with the bounded user-global and project instruction chain in broad-to-specific order. Resume reuses that message when its visible baseline is compatible.
 
 ##### Baseline instruction template
 
@@ -107,7 +107,7 @@ The rendered baseline is appended once and remains in derived history until comp
 
 #### KV Cache effect
 
-Append-only after the existing reusable prefix. A new or resumed instance may append a recomposed baseline, so instruction, precedence, cwd, candidate, or byte-budget changes affect cache reuse from that history position.
+Append-only after the existing reusable prefix. Resume preserves reuse when the visible baseline identity is compatible; an incompatible identity appends a complete replacement, so discovery, precedence, project-root, or budget changes affect reuse only from that history position.
 
 ### Newly discovered scope context
 
@@ -162,7 +162,7 @@ Append-only; newly visible content follows the reusable request prefix and does
 ## Known Limitations and Deferred Work
 
 - **Discovery follows structured fs tools, not shell navigation** — a `bash` command that changes directories does not trigger nested instruction discovery because shell syntax and per-call shell state are not a reliable filesystem seam.
-- **Refresh is touch-driven** — there is no watcher; external edits become visible on the next successful first-party `read`, `write`, or `edit`, or when a resumed loop prepares its baseline.
+- **Refresh is touch-driven** — there is no watcher; external edits become visible on the next successful first-party `read`, `write`, or `edit`, when resume reconciles a visible baseline, or when an entering pre-step restores a shadowed baseline.
 - **Candidate semantics stay intentionally small** — lowercase names, `.claude/rules/`, and `@path` imports are not interpreted; project scopes load `AGENTS.local.md`/`CLAUDE.local.md` overlays by default, but the user-global `$DSH_HOME` scope has no local overlay and other custom names require explicit candidate configuration.
 - **Per-directory dedup is content-based** — sibling candidates collapse only when byte-identical after trimming leading and trailing whitespace; a `CLAUDE.md` that symlinks its sibling `AGENTS.md` resolves to the same content and collapses like any duplicate, while a distinct real copy that has drifted from `AGENTS.md` loads in full alongside it.
 - **Symlinked instruction files are followed across the trust boundary** — a candidate whose final component is a symlink is resolved and its target loaded, so a cloned repository can surface off-tree file content as lower-authority workspace guidance (it never overrides system, developer, or direct user instructions). Confine `ctx.fs` with the filesystem policy gate or an OS sandbox when loading untrusted repositories.
diff --git a/packages/context/workspace-context/README.zh.md b/packages/context/workspace-context/README.zh.md
index 3456c5c362..9d983f95f4 100644
--- a/packages/context/workspace-context/README.zh.md
+++ b/packages/context/workspace-context/README.zh.md
@@ -6,7 +6,7 @@
 
 ## 生命周期
 
-每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使直接提示词与持久基线一同进入步骤 1，并共同抵达第一次请求。reject 或空的第一步决策会将基线留在 agent 的 `next-step` inbox，等待后续唤醒。loader 先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。
+每个实时会话第一次符合条件的 `agent/pre-step` 会组合基线。当下游决策让非空的第一步批次进入时，插件会将基线折入最终批次、紧随已领取的直接提示词之后，使直接提示词与持久基线一同进入步骤 1，并共同抵达第一次请求。reject 或空的第一步决策会将基线留在 agent 的 `next-step` inbox，等待后续唤醒。loader 先读取 `$DSH_HOME/AGENTS.md`，随后针对项目根目录到 `agent.session.header.cwd` 的每个目录，先读取每个现有基础候选文件，再读取每个现有本地 overlay 候选文件。同一目录中，如果候选文件在去除首尾空白后字节完全一致，就会按已配置顺序折叠到最早候选文件，因此 `CLAUDE.md` 若只是复制同级 `AGENTS.md`，只会渲染一次。若之前排队的 workspace 上下文仍在等待，插件会删除并替换该确切 inbox 条目，而不会不断累积副本。恢复后的会话会保留一条兼容的可见基线，并只追加当前文件的转换；如果发现、优先级、项目根目录或预算标识发生变化，则会将一条明确取代旧基线的完整基线折入进入步骤的批次。
 
 该插件还会监听 `tools/post-execute` 中成功的第一方 `read`、`write` 和 `edit` 调用。每次 touch 都会检查新达到的后代 scope 以及之前加载的每个 scope。每个已配置候选名称都是所在目录中的独立 scope：新出现的文件通过结果的 `additionalContexts` 附加；已改变文件追加替换；文件消失或成为同一目录中较早候选文件的重复项时，追加移除通知。原生调用与 Code Mode 子分派共享该路径：`run_code` 将每个嵌套上下文延迟到外层结果，因此 loop 仍会在工具调用／结果相邻关系完成后追加更新。这种发现跟随结构化文件系统活动，而不是 shell `cd`，因为每次本地 bash 调用都启动新 shell，解析任意 shell 语法也不可靠。
 
@@ -48,11 +48,11 @@ These instructions apply to work under `packages/app`. Use them as guidance when
 
 ## 状态与刷新
 
-模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整的启动或恢复基线还会携带 `baseline: true`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；reject 则让当前上下文继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。如果所属 `step/end` 在匹配的动态上下文进入日志之前到达，插件会清除该 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。
+模型可见文本不含隐藏状态标记。每个基线或动态上下文事件改为携带带类型的 `workspace-instructions` 来源，其中包含 `{ action, scope, path, digest? }` 变更列表；完整基线还会携带 `baseline: true`，以及从规范化的发现、优先级、项目根目录和预算配置派生的 `baselineIdentity`。匹配的持久 `user/message` 会确认已排队基线及其候选版本。进入步骤的 pre-step 会把新组合的上下文折入最终批次，位置紧随已领取的消息，并移除 inbox 中仍待处理的副本；reject 则让当前上下文继续排队。若监听器改写掉已领取的 workspace 消息，又没有让替代消息进入，后续边界会重新组合当前上下文。每次相关工具 touch 时，插件会从可见会话事件重建已加载状态，并叠加一个短暂内存 pending 窗口，用于不可变顶层 `tools/result` 上存在但 loop 尚未追加的上下文。如果所属 `step/end` 在匹配的动态上下文进入日志之前到达，插件会清除该 pending 转换及其版本快速路径，使下一次成功 touch 可以重新加载。嵌套 Code Mode 结果会在外层执行 token 下暂存 pending 变更，用于抑制同次运行中的重复项；外层结果会回滚该状态，再只重新提交经过外层策略的上下文。
 
 路径与 SHA-1 内容 digest 都未变时，不会重复注入。每会话、每 scope 提供方 cache 只存储 `{ path, version, digest, trimmedDigest }`：当提供方的不透明 `FsVersion` 与有效可见状态都匹配时，对账会跳过内容读取；版本改变会在任何模型可见更新之前触发有界读取与 SHA-1 确认。`trimmedDigest` 是针对去除空白后内容的 SHA-1，也是每目录重复 key，因此较早候选文件与某个未更改文件的内容收敛后，后者仍可被移除。恢复可行，因为 SHA-1 状态持久化在带类型的来源中，而空的内存版本 cache 只会导致一次确认读取。压缩（compaction）会在 scope 的上下文事件离开可见表层后重新启用它，即使缓存版本未变。移除是 tombstone，因此候选文件之后重新出现时会重新加载。只有在字节预算内实际渲染的模型可见变更才会进入来源、pending 状态和版本 cache；已省略变更仍可在后续 touch 处理，而相同 digest 的版本刷新只更新提供方 cache。
 
-初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态；下一次成功的文件系统 touch 会在压缩后重新添加未变的基线 scope，或追加其替换或移除。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。插件热重挂只有在其带类型的事件仍然可见时才保留基线，同时会重建当前 scope 与版本跟踪状态；否则会排队当前基线。恢复的 loop 始终在第一次 pre-step 重新组合当前基线，并对账仍可见的动态 scope；首次请求若进入步骤，就会在同一步骤记录该上下文。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在恢复 loop 准备基线时可见。
+初始基线事件自身不会被改写。其带类型的变更仅在该事件仍位于可见会话表层时才是权威状态。当压缩遮蔽该事件时，下一次进入步骤的 pre-step 会组合当前基线，并在同一请求中记录它；也可以改由一次成功的文件系统 touch 重新添加未变的基线 scope，或追加其替换或移除。内存中的 scope 标记和提供方版本 cache 只负责选择探测对象并加速探测。恢复或插件热重挂后的第一次 pre-step 会保留兼容的可见基线，并将它与当前完整渲染所保留的文件进行比较。未变化和被预算省略的文件不追加任何内容；agent 离线期间新增、编辑、移除或不再属于预算保留集的文件会追加 `set`、`replace` 或 `remove` 转换。不兼容的可见基线会被一条完整的当前基线取代；如果没有候选文件，这条当前基线会是显式空基线。没有文件 watcher，因此磁盘变更会在下一次成功 `read`、`write` 或 `edit` touch 时可见，也会在恢复后的会话对账其基线时，或进入步骤的 pre-step 恢复被遮蔽的基线时可见。
 
 ## 配置
 
@@ -83,7 +83,7 @@ export interface Config {
 
 #### 模型看到的内容
 
-在每个 loop 实例的第一个请求中，模型会收到一条持久 user 角色消息，其中按从宽泛到具体的顺序包含有界用户全局指令与项目指令链。
+第一次请求的派生历史中包含一条持久 user 角色消息，其中按从宽泛到具体的顺序包含有界用户全局指令与项目指令链。可见基线兼容时，恢复会复用该消息。
 
 ##### 基线指令模板
 
@@ -107,7 +107,7 @@ Instructions from: AGENTS.md
 
 #### KV Cache 影响
 
-仅追加，位于现有可复用前缀之后。新建或恢复的实例可能追加重新组合的基线，因此指令、优先级、cwd、候选文件或字节预算变更会从该历史位置起影响缓存复用。
+仅追加，位于现有可复用前缀之后。可见基线标识兼容时，恢复会保持复用；不兼容的标识会追加一条完整的替代基线，因此发现、优先级、项目根目录或预算变更只会从该历史位置起影响复用。
 
 ### 新发现的 scope 上下文
 
@@ -162,7 +162,7 @@ The previously loaded instructions from this file no longer apply.
 ## 已知限制与暂缓事项
 
 - **发现跟随结构化 fs 工具，而非 shell 导航**：更改目录的 `bash` 命令不会触发嵌套指令发现，因为 shell 语法与每次调用 shell 状态不是可靠的文件系统 seam。
-- **刷新由 touch 驱动**：没有 watcher；外部编辑会在下一次成功的第一方 `read`、`write` 或 `edit` 时可见，也会在恢复 loop 准备基线时可见。
+- **刷新由 touch 驱动**：没有 watcher；外部编辑会在下一次成功的第一方 `read`、`write` 或 `edit` 时、恢复过程对账可见基线时，或进入步骤的 pre-step 恢复被遮蔽的基线时可见。
 - **候选语义有意保持简单**：不解释小写名称、`.claude/rules/` 与 `@path` import；项目 scope 默认加载 `AGENTS.local.md`／`CLAUDE.local.md` overlay，但用户全局 `$DSH_HOME` scope 没有本地 overlay，其他自定义名称需要显式候选配置。
 - **每目录去重基于内容**：只有在去除首尾空白后字节完全一致时，才折叠同级候选文件。`CLAUDE.md` 若 symlink 到同级 `AGENTS.md`，会解析为相同内容，并像任何重复项一样折叠；从 `AGENTS.md` 漂移的独立实体副本则会与它一起完整加载。
 - **Symlink 指令文件会跨越信任边界跟随**：最终组件是 symlink 的候选文件会被解析并加载其目标，因此克隆仓库可以将树外文件内容呈现为较低优先级的工作区指引（它绝不会覆盖 system、developer 或用户直接下达的指令）。加载不受信任仓库时，请用文件系统策略门禁或 OS 沙箱限制 `ctx.fs`。
diff --git a/packages/context/workspace-context/src/config.ts b/packages/context/workspace-context/src/config.ts
index 56c048976c..c1a1fad1e6 100644
--- a/packages/context/workspace-context/src/config.ts
+++ b/packages/context/workspace-context/src/config.ts
@@ -4,6 +4,7 @@
  * @module @deepseek-ai/dsh-workspace-context/config
  */
 
+import { relative } from 'node:path'
 import z from 'schemastery'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 
@@ -58,6 +59,28 @@ export interface ResolvedConfig extends ResolvedDiscoveryConfig {
   maxSourceBytes: number
 }
 
+/**
+ * Identify the discovery, precedence, and budget semantics of one baseline.
+ * @param config - normalized plugin configuration.
+ * @param cwd - absolute session working directory.
+ * @param projectRoot - project root selected for the current baseline.
+ * @returns stable serialized identity for compatibility checks on resume.
+ */
+export function workspaceBaselineIdentity(
+  config: ResolvedConfig,
+  cwd: string,
+  projectRoot: string,
+): string {
+  return JSON.stringify({
+    projectRoot: relative(cwd, projectRoot),
+    projectRootMarkers: config.projectRootMarkers,
+    maxBytes: config.maxBytes,
+    maxSourceBytes: config.maxSourceBytes,
+    instructionFileCandidates: config.instructionFileCandidates,
+    localInstructionFileCandidates: config.localInstructionFileCandidates,
+  })
+}
+
 /**
  * Resolve defaults, the harness home, and valid same-directory candidates.
  * @param config - user-facing plugin configuration.
diff --git a/packages/context/workspace-context/src/files.ts b/packages/context/workspace-context/src/files.ts
index 3e6a3d5de8..6c8bfed533 100644
--- a/packages/context/workspace-context/src/files.ts
+++ b/packages/context/workspace-context/src/files.ts
@@ -46,17 +46,22 @@ interface DiscoverOptions {
   projectRootMarkers?: string[]
   instructionFileCandidates?: string[]
   localInstructionFileCandidates?: string[]
+  projectRoot?: string
   signal?: AbortSignal
 }
 
 interface LoadOptions extends DiscoverOptions {
   maxBytes: number
   maxSourceBytes?: number
+  replacePreviousBaseline?: boolean
 }
 
-/** Rendered baseline plus the files that survived byte budgeting. */
+/** Rendered baseline plus the successfully read and byte-budget-retained files. */
 export interface RenderedInstructionSet {
   rendered: RenderedWorkspaceContext
+  /** Successfully read candidates before content deduplication and byte budgeting. */
+  observed: LoadedInstructionFile[]
+  /** Candidates retained by content deduplication and byte budgeting. */
   included: LoadedInstructionFile[]
 }
 
@@ -286,7 +291,8 @@ async function discoverInstructionFiles(
   }
 
   const cwd = resolve(options.cwd)
-  const projectRoot = await findProjectRoot(cwd, config.projectRootMarkers, fileSystem, options.signal)
+  const projectRoot = options.projectRoot
+    ?? await findProjectRoot(cwd, config.projectRootMarkers, fileSystem, options.signal)
   for (const dir of ancestorChain(projectRoot, cwd)) {
     for (const candidates of [config.instructionFileCandidates, config.localInstructionFileCandidates]) {
       for (const file of await allExistingInstructionFiles(dir, projectRoot, candidates, fileSystem, options.signal)) {
@@ -389,7 +395,7 @@ export async function loadBaselineInstructions(
  * Load a baseline together with the files retained after rendering.
  * @param options - discovery, source-size, byte-budget, and cancellation configuration.
  * @param fileSystem - optional provider used instead of host filesystem reads.
- * @returns rendered context and retained files, or undefined when empty or disabled.
+ * @returns rendered context and retained files, an explicit empty replacement set, or undefined when empty or disabled.
  */
 export async function loadBaselineInstructionSet(
   options: LoadOptions,
@@ -412,10 +418,29 @@ export async function loadBaselineInstructionSet(
     }
   }
   const deduped = dedupInstructionFilesByDirectory(loaded)
-  if (deduped.length === 0) return undefined
-  const rendered = renderWorkspaceContext(deduped, { maxBytes: config.maxBytes })
+  if (deduped.length === 0) {
+    if (options.replacePreviousBaseline !== true) return undefined
+    return {
+      rendered: renderWorkspaceContext([], {
+        maxBytes: config.maxBytes,
+        replacePreviousBaseline: true,
+      }),
+      observed: [],
+      included: [],
+    }
+  }
+  const rendered = renderWorkspaceContext(deduped, {
+    maxBytes: config.maxBytes,
+    ...options.replacePreviousBaseline === undefined
+      ? {}
+      : { replacePreviousBaseline: options.replacePreviousBaseline },
+  })
   const omitted = new Set(rendered.omitted.map(file => file.absolutePath))
-  return { rendered, included: deduped.filter(file => !omitted.has(file.absolutePath)) }
+  return {
+    rendered,
+    observed: loaded,
+    included: deduped.filter(file => !omitted.has(file.absolutePath)),
+  }
 }
 
 /**
diff --git a/packages/context/workspace-context/src/index.ts b/packages/context/workspace-context/src/index.ts
index f07ccf46f8..ac1f2b638e 100644
--- a/packages/context/workspace-context/src/index.ts
+++ b/packages/context/workspace-context/src/index.ts
@@ -13,10 +13,10 @@ import type { Context } from 'cordis'
 import { isDeepStrictEqual } from 'node:util'
 import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
-import type { UserMessage } from '@deepseek-ai/dsh-session'
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
 import type { ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
-import { Config, resolveConfig, type ResolvedConfig } from './config.ts'
-import { loadBaselineInstructionSet } from './files.ts'
+import { Config, resolveConfig, workspaceBaselineIdentity, type ResolvedConfig } from './config.ts'
+import { findProjectRoot, loadBaselineInstructionSet } from './files.ts'
 import {
   applyInstructionVersionUpdates,
   baselineInstructionState,
@@ -24,6 +24,7 @@ import {
   reconcileInstructionContext,
   workspaceContextMessage,
   type InstructionVersionCache,
+  type WorkspaceInstructionSource,
 } from './state.ts'
 import type { WorkspaceInstructionChange } from './render.ts'
 
@@ -39,13 +40,22 @@ export type {
 export { renderWorkspaceContext } from './render.ts'
 export type { RenderedWorkspaceContext, TruncatedInstruction } from './render.ts'
 
-function hasVisibleBaseline(agent: Agent): boolean {
-  return agent.session.surface.nodes.some((seq) => {
+function visibleBaselineSource(
+  agent: Agent,
+  authorityMessages: readonly UserMessage[],
+): WorkspaceInstructionSource | undefined {
+  for (const message of authorityMessages.toReversed()) {
+    if (message.source.kind === 'workspace-instructions' && message.source.baseline === true) {
+      return message.source
+    }
+  }
+  for (const seq of agent.session.surface.nodes.toReversed()) {
     const event = agent.session.events[seq]
-    return event?.type === 'user/message'
+    if (event?.type === 'user/message'
       && event.data.source.kind === 'workspace-instructions'
-      && event.data.source.baseline === true
-  })
+      && event.data.source.baseline === true) return event.data.source
+  }
+  return undefined
 }
 
 function isWorkspaceContext(message: UserMessage): boolean {
@@ -70,6 +80,10 @@ function filePathFromExecution(exec: ToolExecution): string | undefined {
 export function apply(ctx: Context, config: Config): void {
   const resolved: ResolvedConfig = resolveConfig(config)
   const instructionVersions: InstructionVersionCache = new WeakMap()
+  const baselinePreparations = new WeakMap<Session, {
+    identity: string
+    excludedScopes: ReadonlySet<string>
+  }>()
   const projectionLifecycle = new AbortController()
   ctx.effect(
     () => () => {
@@ -99,11 +113,20 @@ export function apply(ctx: Context, config: Config): void {
     const changes: WorkspaceInstructionChange[] = []
     let desiredBaseline = false
     const authorityMessages = [...claimed]
-    const baselinePresent = hasVisibleBaseline(agent) || claimed.some(message =>
-      message.source.kind === 'workspace-instructions' && message.source.baseline === true)
-    if (!baselinePresent) {
-      /* v8 ignore next -- normal agents carry an absolute session cwd. */
-      const cwd = agent.session.header.cwd ?? process.cwd()
+    /* v8 ignore next -- normal agents carry an absolute session cwd. */
+    const cwd = agent.session.header.cwd ?? process.cwd()
+    const projectRoot = await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, signal)
+    const identity = workspaceBaselineIdentity(resolved, cwd, projectRoot)
+    const visibleBaseline = visibleBaselineSource(agent, authorityMessages)
+    const baselinePresent = visibleBaseline !== undefined
+    const keepVisibleBaseline = visibleBaseline?.baselineIdentity === identity
+    const prepared = baselinePreparations.get(agent.session)
+    let excludedBaselineScopes = keepVisibleBaseline && prepared?.identity === identity
+      ? prepared.excludedScopes
+      : undefined
+    let nextPreparation: { identity: string; excludedScopes: ReadonlySet<string> } | undefined
+    if (!baselinePresent || !keepVisibleBaseline || excludedBaselineScopes === undefined) {
+      const replacePreviousBaseline = baselinePresent && !keepVisibleBaseline
       const instructions = await loadBaselineInstructionSet({
         cwd,
         dshHome: resolved.dshHome,
@@ -112,18 +135,45 @@ export function apply(ctx: Context, config: Config): void {
         maxSourceBytes: resolved.maxSourceBytes,
         instructionFileCandidates: resolved.instructionFileCandidates,
         localInstructionFileCandidates: resolved.localInstructionFileCandidates,
+        projectRoot,
+        replacePreviousBaseline,
         signal,
       }, fileSystem)
       const baseline = baselineInstructionState(instructions?.included ?? [])
+      const observedBaseline = baselineInstructionState(instructions?.observed ?? [])
+      const excludedScopes = new Set(observedBaseline.changes.keys())
+      for (const scope of baseline.changes.keys()) excludedScopes.delete(scope)
+      excludedBaselineScopes = excludedScopes
+      nextPreparation = { identity, excludedScopes }
       let versionStates = instructionVersions.get(agent.session)
       if (versionStates === undefined && baseline.versions.size > 0) {
         versionStates = new Map()
         instructionVersions.set(agent.session, versionStates)
       }
       for (const [scope, state] of baseline.versions) versionStates?.set(scope, state)
-      if (instructions !== undefined && instructions.rendered.text.length > 0) {
-        content.push(...workspaceContextMessage(instructions.rendered.text).content)
-        changes.push(...baseline.changes.values())
+      if (!keepVisibleBaseline && instructions !== undefined && instructions.rendered.text.length > 0) {
+        const baselineContent = workspaceContextMessage(instructions.rendered.text).content
+        content.push(...baselineContent)
+        const replacementScopes = new Set(baseline.changes.keys())
+        const replacementRemovals = replacePreviousBaseline
+          ? visibleBaseline.changes.flatMap(change => (
+            change.action === 'remove' || replacementScopes.has(change.scope)
+              ? []
+              : [{ action: 'remove' as const, scope: change.scope, path: change.path }]
+          ))
+          : []
+        const baselineChanges = [...replacementRemovals, ...baseline.changes.values()]
+        changes.push(...baselineChanges)
+        authorityMessages.push(createUserMessage({
+          content: baselineContent,
+          source: {
+            kind: 'workspace-instructions',
+            form: 'instructions',
+            baseline: true,
+            baselineIdentity: identity,
+            changes: baselineChanges,
+          },
+        }))
         desiredBaseline = true
       }
     }
@@ -132,7 +182,15 @@ export function apply(ctx: Context, config: Config): void {
       resolved,
       instructionVersions,
       fileSystem,
-      { authorityMessages, scopeMessages: pending, includeBaselineScopes: baselinePresent, touchedPaths, signal },
+      {
+        authorityMessages,
+        scopeMessages: pending,
+        includeBaselineScopes: keepVisibleBaseline,
+        ...keepVisibleBaseline ? { excludedBaselineScopes } : {},
+        touchedPaths,
+        projectRoot,
+        signal,
+      },
     )
     if (update !== undefined) {
       content.push(...update.context.content)
@@ -142,6 +200,7 @@ export function apply(ctx: Context, config: Config): void {
       }
       applyInstructionVersionUpdates(agent.session, update.versionUpdates, instructionVersions)
     }
+    if (nextPreparation !== undefined) baselinePreparations.set(agent.session, nextPreparation)
     if (content.length === 0) return undefined
     return createUserMessage({
       content,
@@ -149,6 +208,7 @@ export function apply(ctx: Context, config: Config): void {
         kind: 'workspace-instructions',
         form: 'instructions',
         ...desiredBaseline ? { baseline: true } : {},
+        ...desiredBaseline ? { baselineIdentity: identity } : {},
         changes,
       },
     })
diff --git a/packages/context/workspace-context/src/render.ts b/packages/context/workspace-context/src/render.ts
index 9ab311e942..7b61f3b8fd 100644
--- a/packages/context/workspace-context/src/render.ts
+++ b/packages/context/workspace-context/src/render.ts
@@ -12,6 +12,10 @@ const SYSTEM_REMINDER_CLOSE = '</system-reminder>'
 const WORKSPACE_CONTEXT_INTRO = 'The following workspace instructions may be relevant to your work. '
   + 'Use them as guidance when applicable. More specific instructions take precedence over broader ones. '
   + 'They do not override system, developer, or direct user instructions.'
+const REPLACEMENT_WORKSPACE_CONTEXT_INTRO = 'This complete workspace instruction baseline replaces all earlier workspace instruction baselines. '
+  + WORKSPACE_CONTEXT_INTRO
+const EMPTY_REPLACEMENT_WORKSPACE_CONTEXT_INTRO = 'This complete workspace instruction baseline replaces all earlier workspace instruction baselines. '
+  + 'No workspace instructions are currently active.'
 const COMPACT_WORKSPACE_CONTEXT_INTRO = 'Workspace instructions were omitted or truncated to fit the configured byte budget.'
 
 /** Byte-accounting record for one truncated instruction file. */
@@ -294,12 +298,20 @@ function renderInstructionContext(
 /**
  * Render the baseline instruction chain with deterministic precedence budgeting.
  * @param files - loaded files ordered from broadest to most specific.
- * @param options - required rendering byte budget.
+ * @param options - rendering byte budget and whether this baseline supersedes a visible predecessor.
  * @returns bounded baseline prompt text and budget diagnostics.
  */
 export function renderWorkspaceContext(
   files: LoadedInstructionFile[],
-  options: { maxBytes: number },
+  options: { maxBytes: number; replacePreviousBaseline?: boolean },
 ): RenderedWorkspaceContext {
-  return renderInstructionContext(files, options.maxBytes, BASELINE_RENDER_STYLE)
+  const style = options.replacePreviousBaseline === true
+    ? {
+      ...BASELINE_RENDER_STYLE,
+      intro: files.length === 0
+        ? EMPTY_REPLACEMENT_WORKSPACE_CONTEXT_INTRO
+        : REPLACEMENT_WORKSPACE_CONTEXT_INTRO,
+    }
+    : BASELINE_RENDER_STYLE
+  return renderInstructionContext(files, options.maxBytes, style)
 }
diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts
index d0176eef8f..f302e48363 100644
--- a/packages/context/workspace-context/src/state.ts
+++ b/packages/context/workspace-context/src/state.ts
@@ -40,6 +40,8 @@ export interface WorkspaceInstructionSource {
   form: 'instructions'
   /** Marks the complete startup/resume baseline rather than a later delta. */
   baseline?: true
+  /** Discovery, precedence, and budget identity used to validate a resumed baseline. */
+  baselineIdentity?: string
   changes: WorkspaceInstructionChange[]
 }
 
@@ -251,6 +253,8 @@ export async function reconcileInstructionContext(
     scopeMessages: readonly UserMessage[]
     touchedPaths: readonly string[]
     includeBaselineScopes: boolean
+    excludedBaselineScopes?: ReadonlySet<string>
+    projectRoot?: string
     signal?: AbortSignal
   },
 ): Promise<ReconciledInstructionContext | undefined> {
@@ -260,7 +264,8 @@ export async function reconcileInstructionContext(
   const cwd = session.header.cwd ?? process.cwd()
   // TODO(frozen-project-root): retain the baseline root for the loop instance;
   // recomputing it after marker edits reinterprets the existing relative scope keys.
-  const projectRoot = await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, options.signal)
+  const projectRoot = options.projectRoot
+    ?? await findProjectRoot(cwd, resolved.projectRootMarkers, fileSystem, options.signal)
   const scopes = new Set<string>()
   const baselineScopes = new Set<string>()
   const addDirScopes = (target: Set<string>, directory: string): void => {
@@ -324,11 +329,23 @@ export async function reconcileInstructionContext(
     else directoryScopes.push(scope)
   }
   for (const [directory, directoryScopes] of scopesByDirectory) {
+    const probedScopes: string[] = []
+    for (const scope of directoryScopes) {
+      if (options.excludedBaselineScopes !== undefined
+        && baselineScopes.has(scope)
+        && options.excludedBaselineScopes.has(scope)) {
+        const previous = effective.get(scope)
+        if (previous === undefined || previous.action === 'remove') versions.delete(scope)
+        else pushRemoval(scope, previous.path)
+      } else {
+        probedScopes.push(scope)
+      }
+    }
     const itemStart = items.length
     const versionUpdateStart = versionUpdates.length
     const addedAbsolutePaths: string[] = []
-    const priorVersions = new Map(directoryScopes.map(scope => [scope, versions.get(scope)]))
-    for (const scope of directoryScopes) {
+    const priorVersions = new Map(probedScopes.map(scope => [scope, versions.get(scope)]))
+    for (const scope of probedScopes) {
       const previous = effective.get(scope)
       const probe = await probeScopeInstruction(scope, projectRoot, resolved, fileSystem, options.signal)
       if (probe.kind === 'unavailable') {
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index 6157a9fdbf..20bb993447 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -955,6 +955,267 @@ describe('workspace context request injection', () => {
     }
   })
 
+  it('retains one visible baseline across repeated session resumes', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'repo rule')
+      const ctx = new Context()
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(ctx, original)
+
+      const firstResume = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(ctx, firstResume)
+      const secondResume = stubAgent(root, [...firstResume.session.events])
+      await composeBaselinePrefix(ctx, secondResume)
+
+      expect(baselineEvents(firstResume)).toHaveLength(1)
+      expect(baselineEvents(secondResume)).toHaveLength(1)
+      expect(secondResume.session.events.filter(event => event.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions')).toHaveLength(1)
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('preserves a visible baseline when its source is unavailable during resume', async () => {
+    const root = join(await tempRepo(), 'virtual-repo')
+    const home = join(await tempRepo(), 'virtual-home')
+    const ctx = new Context()
+    try {
+      await ctx.plugin(RecordingFileSystem)
+      const fs = ctx.fs as RecordingFileSystem
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'repo rule' })
+      await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(ctx, original)
+
+      fs.throwOnStat.add(join(root, 'AGENTS.md'))
+      const resumed = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(ctx, resumed)
+
+      expect(baselineEvents(resumed)).toHaveLength(1)
+      expect(resumed.session.events.filter(event => event.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions')).toHaveLength(1)
+    } finally {
+      await ctx.fiber.dispose()
+      await rm(dirname(root), { recursive: true, force: true })
+      await rm(dirname(home), { recursive: true, force: true })
+    }
+  })
+
+  it('does not promote an unchanged budget-omitted baseline file during resume', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      const cwd = join(root, 'pkg')
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'root '.repeat(200))
+      await write(join(cwd, 'AGENTS.md'), 'package rule')
+      const ctx = new Context()
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 700 })
+      const original = stubAgent(cwd)
+      await composeBaselinePrefix(ctx, original)
+
+      const firstResume = stubAgent(cwd, [...original.session.events])
+      await composeBaselinePrefix(ctx, firstResume)
+      const secondResume = stubAgent(cwd, [...firstResume.session.events])
+      await composeBaselinePrefix(ctx, secondResume)
+
+      expect(baselineEvents(secondResume)).toHaveLength(1)
+      expect(secondResume.session.events.filter(event => event.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions')).toHaveLength(1)
+      expect(blocksText(secondResume.session.deriveMessages()[0]?.content)).toContain('omitted AGENTS.md')
+      expect(blocksText(secondResume.session.deriveMessages()[0]?.content)).not.toContain('root root')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('removes a previously visible baseline file that leaves the retained budget set', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      const cwd = join(root, 'pkg')
+      await mkdir(join(root, '.git'), { recursive: true })
+      await mkdir(cwd, { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'root '.repeat(200))
+      const ctx = new Context()
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 700 })
+      const original = stubAgent(cwd)
+      await composeBaselinePrefix(ctx, original)
+
+      await write(join(cwd, 'AGENTS.md'), 'package rule')
+      const resumed = stubAgent(cwd, [...original.session.events])
+      await composeBaselinePrefix(ctx, resumed)
+
+      expect(baselineEvents(resumed)).toHaveLength(1)
+      const update = resumed.session.events.findLast(event => event.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions'
+        && event.data.source.baseline !== true)
+      expect(update?.type === 'user/message' && update.data.source.kind === 'workspace-instructions'
+        ? update.data.source.changes
+        : undefined).toMatchObject([
+        { action: 'remove', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+        { action: 'set', scope: sk('pkg', 'AGENTS.md'), path: join('pkg', 'AGENTS.md') },
+      ])
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('recomposes the baseline when candidate precedence changes between resumes', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const originalCtx = new Context()
+    const resumedCtx = new Context()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'agents rule')
+      await write(join(root, 'CLAUDE.md'), 'claude rule')
+      await mountWorkspaceContext(originalCtx, { dshHome: home, maxBytes: 65536 })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(originalCtx, original)
+
+      await mountWorkspaceContext(resumedCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['CLAUDE.md', 'AGENTS.md'],
+      })
+      const resumed = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(resumedCtx, resumed)
+
+      const baselines = baselineEvents(resumed)
+      expect(baselines).toHaveLength(2)
+      const replacement = baselines.at(-1)
+      const replacementText = replacement?.type === 'user/message'
+        ? blocksText(replacement.data.content)
+        : ''
+      expect(replacementText).toContain('replaces all earlier workspace instruction baselines')
+      expect(replacementText.indexOf('Instructions from: CLAUDE.md'))
+        .toBeLessThan(replacementText.indexOf('Instructions from: AGENTS.md'))
+      const baselineIdentities = baselines.flatMap(event => event.type === 'user/message'
+        && event.data.source.kind === 'workspace-instructions'
+        && typeof event.data.source.baselineIdentity === 'string'
+        ? [event.data.source.baselineIdentity]
+        : [])
+      expect(new Set(baselineIdentities).size).toBe(2)
+
+      const repeated = stubAgent(root, [...resumed.session.events])
+      await composeBaselinePrefix(resumedCtx, repeated)
+      expect(baselineEvents(repeated)).toHaveLength(2)
+    } finally {
+      await originalCtx.fiber.dispose()
+      await resumedCtx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('tombstones candidates removed across successive baseline configurations', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const agentsCtx = new Context()
+    const claudeCtx = new Context()
+    const restoredCtx = new Context()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'agents rule')
+      await write(join(root, 'CLAUDE.md'), 'claude rule')
+      await mountWorkspaceContext(agentsCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['AGENTS.md'],
+      })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(agentsCtx, original)
+
+      await mountWorkspaceContext(claudeCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['CLAUDE.md'],
+      })
+      const claudeResume = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(claudeCtx, claudeResume)
+      const claudeBaseline = baselineEvents(claudeResume).at(-1)
+      expect(claudeBaseline?.type === 'user/message' && claudeBaseline.data.source.kind === 'workspace-instructions'
+        ? claudeBaseline.data.source.changes
+        : undefined).toMatchObject([
+        { action: 'remove', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+        { action: 'set', scope: sk('.', 'CLAUDE.md'), path: 'CLAUDE.md' },
+      ])
+
+      await mountWorkspaceContext(restoredCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['AGENTS.md'],
+      })
+      const restored = stubAgent(root, [...claudeResume.session.events])
+      await composeBaselinePrefix(restoredCtx, restored)
+      const restoredBaseline = baselineEvents(restored).at(-1)
+      expect(restoredBaseline?.type === 'user/message' && restoredBaseline.data.source.kind === 'workspace-instructions'
+        ? restoredBaseline.data.source.changes
+        : undefined).toMatchObject([
+        { action: 'remove', scope: sk('.', 'CLAUDE.md'), path: 'CLAUDE.md' },
+        { action: 'set', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+      ])
+    } finally {
+      await agentsCtx.fiber.dispose()
+      await claudeCtx.fiber.dispose()
+      await restoredCtx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('supersedes an incompatible visible baseline when no current candidate exists', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    const originalCtx = new Context()
+    const resumedCtx = new Context()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'agents rule')
+      await mountWorkspaceContext(originalCtx, { dshHome: home, maxBytes: 65536 })
+      const original = stubAgent(root)
+      await composeBaselinePrefix(originalCtx, original)
+
+      await mountWorkspaceContext(resumedCtx, {
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['POLICY.md'],
+      })
+      const resumed = stubAgent(root, [...original.session.events])
+      await composeBaselinePrefix(resumedCtx, resumed)
+
+      const baselines = baselineEvents(resumed)
+      expect(baselines).toHaveLength(2)
+      const replacement = baselines.at(-1)
+      expect(replacement?.type === 'user/message' ? blocksText(replacement.data.content) : '')
+        .toContain('No workspace instructions are currently active.')
+      expect(replacement?.type === 'user/message' && replacement.data.source.kind === 'workspace-instructions'
+        ? replacement.data.source.changes
+        : undefined).toMatchObject([
+        { action: 'remove', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' },
+      ])
+
+      const repeated = stubAgent(root, [...resumed.session.events])
+      await composeBaselinePrefix(resumedCtx, repeated)
+      expect(baselineEvents(repeated)).toHaveLength(2)
+    } finally {
+      await originalCtx.fiber.dispose()
+      await resumedCtx.fiber.dispose()
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
   it('reuses an inserted but unadmitted baseline after session recovery and plugin reload', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
@@ -1323,7 +1584,50 @@ describe('workspace context request injection', () => {
     }
   })
 
-  it('recomposes the baseline from current files when a resumed session edited it offline', async () => {
+  it('folds a compacted baseline into the next entering pre-step before another filesystem touch', async () => {
+    const root = await tempRepo()
+    const home = await tempRepo()
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      await write(join(root, 'AGENTS.md'), 'first post-compaction request rule')
+      const ctx = new Context()
+      await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
+      const agent = stubAgent(root)
+      await composeBaselinePrefix(ctx, agent)
+      const baseline = baselineEvents(agent)[0]
+      expect(baseline).toBeDefined()
+
+      agent.session.append('user/message', createUserMessage({
+        content: [{ type: 'text', text: 'compacted summary' }],
+        source: { kind: 'plugin', plugin: 'compact' },
+      }), {
+        surfaceOp: { op: 'replace', start: baseline!.seq, end: baseline!.seq },
+        sourceEventSeqs: [baseline!.seq],
+      })
+      const prompt = createUserMessage({
+        content: [{ type: 'text', text: 'continue after compaction' }],
+        source: { kind: 'user' },
+      })
+
+      const decision = await agentEvents(ctx, agent).waterfall(
+        'agent/pre-step',
+        { messages: [prompt], turn: 2, step: 1, signal: AbortSignal.timeout(1000) },
+        () => Promise.resolve({ kind: 'enter' as const, messages: [prompt] }),
+      )
+
+      if (decision.kind !== 'enter') throw new Error('post-compaction request was rejected')
+      expect(decision.messages).toHaveLength(2)
+      expect(decision.messages[0]).toBe(prompt)
+      expect(decision.messages[1]?.source).toMatchObject({ kind: 'workspace-instructions', baseline: true })
+      expect(blocksText(decision.messages[1]?.content)).toContain('first post-compaction request rule')
+      expect(agent.inbox.nextStep).toEqual([])
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
+  it('appends a replacement transition when a resumed session edited its baseline offline', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
     try {
@@ -1334,13 +1638,8 @@ describe('workspace context request injection', () => {
       const original = stubAgent(root)
       await composeBaselinePrefix(ctx, original)
 
-      // Offline edit to the baseline file, then resume on a fresh session whose
-      // seeded log already carries the original baseline. A resumed session is
-      // registered after this mount's apply(), so the remount guard never seeds
-      // it: its first step re-composes a fresh baseline from current files,
-      // reflecting the offline edit before the first resumed request. The old
-      // baseline stays in history unmutated (note: resume without mutating an
-      // earlier history event).
+      // The first resumed pre-step retains the compatible visible baseline and
+      // appends only the offline file transition needed to reach current state.
       await write(join(root, 'AGENTS.md'), 'new root rule after offline edit')
       const resumed = stubAgent(root, [...original.session.events])
 
@@ -1352,6 +1651,9 @@ describe('workspace context request injection', () => {
       expect(baselines).toHaveLength(1)
       const latest = resumed.session.events.findLast(event =>
         event.type === 'user/message' && event.data.source.kind === 'workspace-instructions')
+      expect(latest?.type === 'user/message' ? latest.data.source : undefined).toMatchObject({
+        changes: [{ action: 'replace', scope: sk('.', 'AGENTS.md'), path: 'AGENTS.md' }],
+      })
       expect(latest?.type === 'user/message' && blocksText(latest.data.content))
         .toContain('new root rule after offline edit')
       const original0 = baselines[0]
@@ -2756,6 +3058,80 @@ describe('dynamic nested workspace context injection', () => {
     }
   })
 
+  it('ignores an unavailable scope whose visible state is already removed', async () => {
+    const root = join(await tempRepo(), 'virtual-repo')
+    const home = join(await tempRepo(), 'virtual-home')
+    const ctx = new Context()
+    try {
+      await ctx.plugin(RecordingFileSystem)
+      const fs = ctx.fs as RecordingFileSystem
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.throwOnStat.add(join(root, 'pkg/AGENTS.md'))
+      const agent = stubAgent(root)
+      agent.session.append('user/message', createUserMessage({
+        content: [{ type: 'text', text: 'removed nested instructions' }],
+        source: {
+          kind: 'workspace-instructions',
+          form: 'instructions',
+          changes: [{ action: 'remove', scope: sk('pkg', 'AGENTS.md'), path: join('pkg', 'AGENTS.md') }],
+        },
+      }), { surfaceOp: 'append' })
+      const resolved = resolveConfig({
+        dshHome: home,
+        maxBytes: 65536,
+        instructionFileCandidates: ['AGENTS.md'],
+        localInstructionFileCandidates: [],
+      })
+
+      const result = await reconcileInstructionContext(agent, resolved, new WeakMap(), fs, {
+        authorityMessages: [],
+        scopeMessages: [],
+        touchedPaths: [],
+        includeBaselineScopes: false,
+        signal: testToolSignal,
+      })
+
+      expect(result).toBeUndefined()
+    } finally {
+      await ctx.fiber.dispose()
+      await rm(dirname(root), { recursive: true, force: true })
+      await rm(dirname(home), { recursive: true, force: true })
+    }
+  })
+
+  it('loads one transition when user-global and project scopes resolve to the same file', async () => {
+    const root = join(await tempRepo(), 'virtual-repo')
+    const ctx = new Context()
+    try {
+      await ctx.plugin(RecordingFileSystem)
+      const fs = ctx.fs as RecordingFileSystem
+      fs.entries.set(join(root, '.git'), { type: 'directory' })
+      fs.entries.set(join(root, 'AGENTS.md'), { type: 'file', content: 'shared rule' })
+      const agent = stubAgent(root)
+      const resolved = resolveConfig({
+        dshHome: root,
+        maxBytes: 65536,
+        instructionFileCandidates: ['AGENTS.md'],
+        localInstructionFileCandidates: [],
+      })
+
+      const result = await reconcileInstructionContext(agent, resolved, new WeakMap(), fs, {
+        authorityMessages: [],
+        scopeMessages: [],
+        touchedPaths: [],
+        includeBaselineScopes: true,
+        signal: testToolSignal,
+      })
+
+      expect(result?.context.source).toMatchObject({
+        changes: [{ action: 'set', scope: sk(USER_GLOBAL_DIRECTORY, USER_GLOBAL_FILE) }],
+      })
+    } finally {
+      await ctx.fiber.dispose()
+      await rm(dirname(root), { recursive: true, force: true })
+    }
+  })
+
   it('removes a previously rendered sibling once its content becomes a duplicate of an earlier candidate', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 8a75107eea..63c1a491e1 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -938,7 +938,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>',
-        jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents from the\n * live-preferred session corpus without loading or resuming an Agent. Session\n * query supplies lineage, candidate order, event reads, and live state; this\n * service interprets descriptor mode, activity, and per-child diagnostics\n * without consulting Agent registrations, Activations, or providers.\n *\n * The trace and exact descriptor read receive `signal`; the full event-list\n * read has no signal parameter, so the scan rechecks cancellation around\n * every await and between candidates. Query rejections that settle after an\n * abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded where supported and\n *   observed around every query await.\n * @returns children and per-child diagnostics in stable trace order.\n * @throws {@link SubagentError} when session query is unavailable or the\n *   caller cancels the scan.\n */',
+        jsDoc: '/**\n * Enumerate the parent\'s direct session-backed subagents without loading or\n * resuming an Agent and without any query seam: the listing merges the live\n * session store with optional session persistence (live-preferred) and\n * serves each child\'s durable mode/label from the registered `subagent`\n * projection unit down a three-rung ladder — the registry\'s watermark\n * snapshot for a live child; for a cold one, a durable projection-cache\n * row when the optional cache serves an own-suffix identity (its `seq`\n * gate proves the value postdates the fork seed, where a child\'s own\n * descriptor is immutable once appended), else one persistence inspection\n * folded through the registry. The\n * projection fold is the single classification authority; per-child\n * diagnostics relay a fold that served no identity or a failed inspection,\n * never a list-time descriptor parse. Absent persistence, enumeration is\n * live-only (a cold child cannot be resumed then either, so its absence is\n * capability absence, not an error). This service consults no Agent\n * registrations, Activations, or providers.\n *\n * Every persistence read receives `signal`, and the listing rechecks\n * cancellation around each of those awaits. Read rejections that settle\n * after an abort become a stable `SubagentError` with code `CANCELLED`.\n * @param parentSessionId - parent session whose direct children are listed.\n * @param signal - caller-owned cancellation forwarded to persistence reads\n *   and observed around every read await.\n * @returns children and per-child diagnostics ordered by `createdAt`, then id.\n * @throws {@link SubagentError} when the projection registry or the session\n *   store is not mounted, or the caller cancels the listing.\n */',
       },
       {
         signature: 'registerProvider(provider: SubagentProvider): () => void',
@@ -2819,7 +2819,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
   },
   {
     name: 'SubprocessSpawnSpec',
-    declaration: 'export interface SubprocessSpawnSpec {\n    argv: readonly string[];\n    cwd: string;\n    stdio: SubprocessStdio;\n    graceMs: number;\n    signal?: AbortSignal | undefined;\n    env?: Record<string, string> | undefined;\n}',
+    declaration: 'export interface SubprocessSpawnSpec {\n    argv: readonly string[];\n    cwd: string;\n    stdio: SubprocessStdio;\n    graceMs: number;\n    signal?: AbortSignal | undefined;\n    env?: NodeJS.ProcessEnv | undefined;\n}',
   },
   {
     name: 'SubprocessStdinMode',
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index 854e28d2e7..d655c2488e 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -161,7 +161,7 @@ export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap]
 export interface TodoItem {
   /** What this task is — a short imperative line shown in the UI. */
   content: string
-  /** Lifecycle state. `in_progress` marks the single task being worked now. */
+  /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
   status: 'pending' | 'in_progress' | 'completed'
 }
 
diff --git a/packages/fs/tool-fs-search/README.i18n.yaml b/packages/fs/tool-fs-search/README.i18n.yaml
index 276db5f47c..fbe6453292 100644
--- a/packages/fs/tool-fs-search/README.i18n.yaml
+++ b/packages/fs/tool-fs-search/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/fs/tool-fs-search/README.md
-README.md: 78ffa069e56da5fc987913acf761eb5c6ae15b1a
-README.zh.md: b7bb08f94682b0c85baf33ad9045320e3306bbb2
+README.md: 32fa61e3bb09b2166499003953a5631a93baf73b
+README.zh.md: bf2eac320bf3dc0811ec8e3747487b4f3ce634b7
diff --git a/packages/fs/tool-fs-search/README.md b/packages/fs/tool-fs-search/README.md
index 78ffa069e5..32fa61e3bb 100644
--- a/packages/fs/tool-fs-search/README.md
+++ b/packages/fs/tool-fs-search/README.md
@@ -30,7 +30,7 @@ The binary ships with the package on every supported platform (macOS/Linux/Windo
 | `grepMaxLineBytes` | `2000` | Byte cap per matched-line preview; the cut preserves UTF-8 boundaries and is marked `(line truncated)`. |
 | `rawOutputMaxBytes` | `20000000` | Max complete raw `rg` stdout a search will parse (matches Claude Code's ripgrep raw buffer); larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. |
 | `timeoutMs` | `30000` | Cooperative tool-call budget attached to both tool definitions, enforced by `@deepseek-ai/dsh-timeout-policy` through `exec.signal`; the subprocess seam's terminate escalation is the hard kill. |
-| `graceMs` | `3000` | Terminate-escalation grace period the subprocess seam grants past `timeoutMs` before the search fails as `SEARCH_ABORTED`. |
+| `graceMs` | `3000` | Positive terminate-escalation grace the subprocess seam grants past `timeoutMs` before the search fails as `SEARCH_ABORTED`; it cannot exceed [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md). |
 | `stderrMaxBytes` | `65536` | Diagnostic-tail budget for `rg` stderr, captured through the subprocess seam's collect disposition; a lossy read keeps only the tail (marked `[stderr truncated]`). |
 
 ## Tools
diff --git a/packages/fs/tool-fs-search/README.zh.md b/packages/fs/tool-fs-search/README.zh.md
index b7bb08f946..bf2eac320b 100644
--- a/packages/fs/tool-fs-search/README.zh.md
+++ b/packages/fs/tool-fs-search/README.zh.md
@@ -30,7 +30,7 @@ await ctx.plugin(LocalSpillStore)                           // @deepseek-ai/dsh-
 | `grepMaxLineBytes` | `2000` | 每条匹配行预览的字节上限；截断会保留 UTF-8 边界，并标记为 `(line truncated)`。 |
 | `rawOutputMaxBytes` | `20000000` | 搜索将解析的完整原始 `rg` stdout 上限（与 Claude Code 的 ripgrep 原始 buffer 相同）；更大的原始输出以 `SEARCH_RAW_OUTPUT_OVERFLOW` 失败。 |
 | `timeoutMs` | `30000` | 附加到两个工具定义上的协作式工具调用预算，由 `@deepseek-ai/dsh-timeout-policy` 通过 `exec.signal` 强制执行；subprocess seam 的终止升级提供硬终止。 |
-| `graceMs` | `3000` | subprocess seam 在 `timeoutMs` 之外授予的终止升级宽限期；超过后搜索以 `SEARCH_ABORTED` 失败。 |
+| `graceMs` | `3000` | subprocess seam 在 `timeoutMs` 之外授予的终止升级宽限期须为正值；超过后搜索以 `SEARCH_ABORTED` 失败；该宽限期不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)。 |
 | `stderrMaxBytes` | `65536` | `rg` stderr 的诊断尾部预算，经 subprocess seam 的 collect 形态捕获；lossy 读取只保留尾部（标记 `[stderr truncated]`）。 |
 
 ## 工具
diff --git a/packages/fs/tool-fs-search/package.json b/packages/fs/tool-fs-search/package.json
index 9e5b8c0374..c0fb5d49d3 100644
--- a/packages/fs/tool-fs-search/package.json
+++ b/packages/fs/tool-fs-search/package.json
@@ -36,6 +36,7 @@
     "@deepseek-ai/dsh-spill": "^0.0.1",
     "@deepseek-ai/dsh-subprocess": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
@@ -49,6 +50,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-spill": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
diff --git a/packages/fs/tool-fs-search/src/index.ts b/packages/fs/tool-fs-search/src/index.ts
index 7f8e43cb73..cf0a8db066 100644
--- a/packages/fs/tool-fs-search/src/index.ts
+++ b/packages/fs/tool-fs-search/src/index.ts
@@ -28,6 +28,7 @@
 
 import type { Context } from 'cordis'
 import z from 'schemastery'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { GLOB_MAX_RESULTS, applyGlobTool } from './glob.ts'
 import { GREP_MAX_LINE_BYTES, GREP_MAX_MATCHES, applyGrepTool } from './grep.ts'
 import { RAW_OUTPUT_MAX_BYTES, SEARCH_GRACE_MS, SEARCH_META_MAX_BYTES, SEARCH_STDERR_MAX_BYTES, SEARCH_TIMEOUT_MS } from './search-core.ts'
@@ -82,7 +83,7 @@ export interface Config {
   searchMetaMaxBytes?: number
   /** Max complete raw `rg` stdout bytes a search will parse; larger raw output fails with `SEARCH_RAW_OUTPUT_OVERFLOW`. */
   rawOutputMaxBytes?: number
-  /** Terminate-escalation grace period (ms) for one search process, handed to the subprocess seam. */
+  /** Terminate-escalation grace (ms), handed to the subprocess seam and bounded by `MAX_TIMER_DELAY_MS`. */
   graceMs?: number
   /** Max bytes retained for one search's stderr tail; the excerpt is embedded in `SEARCH_*` error messages, never shown on success. */
   stderrMaxBytes?: number
@@ -130,6 +131,9 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
   assertPositiveInteger('searchMetaMaxBytes', resolved.searchMetaMaxBytes)
   assertPositiveInteger('rawOutputMaxBytes', resolved.rawOutputMaxBytes)
   assertPositiveInteger('graceMs', resolved.graceMs)
+  if (resolved.graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`tool-fs-search: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
   assertPositiveInteger('stderrMaxBytes', resolved.stderrMaxBytes)
   assertPositiveInteger('timeoutMs', resolved.timeoutMs)
   applyGlobTool(ctx, {
diff --git a/packages/fs/tool-fs-search/tests/tools.spec.ts b/packages/fs/tool-fs-search/tests/tools.spec.ts
index 9a8fa991ff..e9ae5588ee 100644
--- a/packages/fs/tool-fs-search/tests/tools.spec.ts
+++ b/packages/fs/tool-fs-search/tests/tools.spec.ts
@@ -18,6 +18,7 @@ import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { TOOL_ABORTED_BEFORE_DISPATCH, type ToolExecution, type ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import { SubprocessService } from '@deepseek-ai/dsh-subprocess'
 import type { SubprocessCollectedOutputs, SubprocessHandle, SubprocessOutcome, SubprocessOutputRead, SubprocessOutputReader, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { rgPath } from '@vscode/ripgrep'
 import { SpillLocator, SpillStore } from '@deepseek-ai/dsh-spill'
 import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill'
@@ -309,6 +310,17 @@ describe('config validation', () => {
     await ctx.plugin(FakeSubprocess)
     await expect(ctx.plugin(ToolFsSearch, { ...DEFAULT_CONFIG, ...config })).rejects.toThrow(new RegExp(`tool-fs-search: ${name} must be a positive integer`))
   })
+
+  it('rejects a grace beyond the Node timer range at load', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(FakeSubprocess)
+    await expect(ctx.plugin(ToolFsSearch, {
+      ...DEFAULT_CONFIG,
+      graceMs: MAX_TIMER_DELAY_MS + 1,
+    })).rejects.toThrow(`tool-fs-search: graceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
+  })
 })
 
 describe('command construction (plain argv)', () => {
diff --git a/packages/fs/tool-fs-search/tsconfig.json b/packages/fs/tool-fs-search/tsconfig.json
index ad0c703117..76644e4523 100644
--- a/packages/fs/tool-fs-search/tsconfig.json
+++ b/packages/fs/tool-fs-search/tsconfig.json
@@ -36,6 +36,9 @@
     {
       "path": "../../spill/spill"
     },
+    {
+      "path": "../../util/timeout"
+    },
     {
       "path": "../../support/invariants"
     }
diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index f528b2297e..19fb0fe8a2 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -527,6 +527,28 @@ function detachedProjectionsFor(
   return registry.restore({}, events, 0).snapshot
 }
 
+/**
+ * Best-effort projections for one subagent history page, fail-soft like
+ * {@link listProjectionsFor}: a registered unit throwing on a corrupt payload
+ * never blocks transcript reading — the page is served without the block.
+ * @param ctx - context carrying the logger for the degradation warning.
+ * @param childSessionId - the child whose page is being decorated.
+ * @param compute - the arm-specific fold (live watermark or detached restore).
+ * @returns the projections block, or undefined when the fold failed.
+ */
+function subagentHistoryProjections(
+  ctx: Context,
+  childSessionId: SessionId,
+  compute: () => SessionProjectionsBlock | undefined,
+): SessionProjectionsBlock | undefined {
+  try {
+    return compute()
+  } catch (error) {
+    ctx.logger.warn(`subagent.history: projections for "${childSessionId}" failed (serving the page without them): ${String(error)}`)
+    return undefined
+  }
+}
+
 /** Map continuation admission failures without exposing provider details. */
 function subagentPromptError(
   request: RpcRequest<{ childSessionId: SessionId }>,
@@ -567,6 +589,15 @@ function subagentPromptError(
   return err(request, { code: 'internal', message: 'subagent prompt failed', details: {} })
 }
 
+/** Stable RPC face of the missing projections capability, shared by every catalog read path. */
+function projectionsUnavailableError(): RpcError {
+  return {
+    code: 'internal',
+    message: 'subagent catalog is unavailable: this deployment does not mount the sessionProjections registry (load @deepseek-ai/dsh-session-projection)',
+    details: {},
+  }
+}
+
 /** Verify one address and mode against the complete direct-child catalog. */
 async function catalogChild(
   ctx: Context,
@@ -600,19 +631,11 @@ async function catalogChild(
     }
     return { entry }
   } catch (error: unknown) {
-    if (signal?.aborted
-      || (error instanceof SubagentError && error.code === 'CANCELLED')
-      || (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED')) {
+    if (signal?.aborted || (error instanceof SubagentError && error.code === 'CANCELLED')) {
       return { error: { code: 'cancelled', message: 'subagent catalog read was cancelled', details: {} } }
     }
-    if (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
-      return {
-        error: {
-          code: 'subagent-not-found',
-          message: `parent session "${parentSessionId}" was not found`,
-          details: { parentSessionId, childSessionId },
-        },
-      }
+    if (error instanceof SubagentError && error.code === 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE') {
+      return { error: projectionsUnavailableError() }
     }
     return { error: { code: 'internal', message: 'subagent catalog read failed', details: {} } }
   }
@@ -925,28 +948,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     })
   }
 
-  /** Whether the session's own suffix carries the durable subagent discriminator. */
-  function hasSubagentDescriptor(session: Pick<Session, 'events' | 'header'>): boolean {
-    const events = session.events
-    // Indexed scan from the own-suffix start: slicing copies the whole suffix
-    // on every Agent-bound RPC, including each `session.prompt` on long
-    // transcripts.
-    for (let index = session.header.seedLength ?? 0; index < events.length; index += 1) {
-      if (events[index]?.type === 'subagent/descriptor') return true
-    }
-    return false
-  }
-
   /**
-   * Generic Host interaction cannot claim a durably classified subagent or an
-   * Agent created through its live parent. The runtime-owner arm also covers
-   * descriptor-less child publication windows and older stored headers.
+   * Generic Host interaction cannot claim a durably classified subagent
+   * (`origin: 'subagent'` in the header) or an Agent runtime-owned by its
+   * live parent.
    */
   function hasSubagentOwner(
-    session: Pick<Session, 'events' | 'header'>,
+    session: Pick<Session, 'header'>,
     agent: Agent | undefined,
   ): boolean {
-    if (session.header.origin === 'subagent' || hasSubagentDescriptor(session)) return true
+    if (session.header.origin === 'subagent') return true
     const parentId = session.header.parentSession
     if (parentId === undefined || agent === undefined) return false
     const parent = ctx.agents.get(parentId)
@@ -1002,7 +1013,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
       resume = (async () => {
         try {
           const inspected = await inspectServable(sessionId)
-          if (hasSubagentOwner({ header: inspected.meta, events: inspected.events }, undefined)) {
+          if (hasSubagentOwner({ header: inspected.meta }, undefined)) {
             throw new SubagentSessionOwnership(sessionId)
           }
           const publishedSession = ctx.sessions.get(sessionId)
@@ -1121,7 +1132,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           // Ownership first: explicit-id adoption of a session-backed
           // subagent must answer `agent-busy` regardless of the requested
           // cwd (the api/commands.ts contract), not a cwd conflict.
-          if (hasSubagentOwner({ header: inspected.meta, events: inspected.events }, undefined)) {
+          if (hasSubagentOwner({ header: inspected.meta }, undefined)) {
             throw new SubagentSessionOwnership(sessionId)
           }
           if (inspected.meta.cwd !== cwd) {
@@ -1903,15 +1914,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             parentAvailable: ctx.agents.get(request.payload.parentSessionId) !== undefined,
           })
         } catch (error: unknown) {
-          if (signal?.aborted
-            || (error instanceof SubagentError && error.code === 'CANCELLED')
-            || (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED')) {
+          if (signal?.aborted || (error instanceof SubagentError && error.code === 'CANCELLED')) {
             return err(request, {
               code: 'cancelled',
               message: 'subagent catalog read was cancelled',
               details: {},
             })
           }
+          if (error instanceof SubagentError && error.code === 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE') {
+            return err(request, projectionsUnavailableError())
+          }
           return err(request, {
             code: 'internal',
             message: 'subagent catalog read failed',
@@ -1928,44 +1940,65 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           parentSessionId, childSessionId, mode,
         }, signal)
         if (verified.error !== undefined) return err(request, verified.error)
-        try {
-          const snapshot = await ctx.sessionQuery.readSession(childSessionId)
-          signal?.throwIfAborted()
-          if (snapshot.session.parentSession !== parentSessionId) {
-            return err(request, {
-              code: 'subagent-unauthorized',
-              message: 'subagent parent changed during history read',
-              details: { childSessionId },
-            })
-          }
-          const page = historyPage(ctx, snapshot.events, beforeSeq, maxMessages)
-          const projections = beforeSeq === undefined
-            ? detachedProjectionsFor(ctx, snapshot.events)
+        // The generic-history data plane: an attached child serves its
+        // in-memory snapshot and the registry's live watermark projections; a
+        // cold child is one persistence inspection plus a detached fold.
+        let header: SessionHeader
+        let events: SessionEvent[]
+        let projections: SessionProjectionsBlock | undefined
+        const attached = ctx.sessions.get(childSessionId)
+        if (attached !== undefined) {
+          header = attached.header
+          events = [...attached.events]
+          projections = beforeSeq === undefined
+            ? subagentHistoryProjections(ctx, childSessionId, () => projectionsFor(ctx, attached))
             : undefined
-          return ok(request, { ...page, ...projections === undefined ? {} : { projections } })
-        } catch (error: unknown) {
-          if (signal?.aborted
-            || (error instanceof SessionQueryError && error.code === 'SESSION_QUERY_ABORTED')) {
+        } else {
+          try {
+            const inspected = await inspectServable(childSessionId)
+            header = inspected.meta
+            events = inspected.events
+            projections = beforeSeq === undefined
+              ? subagentHistoryProjections(ctx, childSessionId, () => detachedProjectionsFor(ctx, inspected.events))
+              : undefined
+          } catch (error: unknown) {
+            if (signal?.aborted) {
+              return err(request, {
+                code: 'cancelled',
+                message: 'subagent history read was cancelled',
+                details: {},
+              })
+            }
+            if (error instanceof SessionNotFound) {
+              return err(request, {
+                code: 'subagent-not-found',
+                message: 'subagent disappeared during history read',
+                details: { parentSessionId, childSessionId },
+              })
+            }
             return err(request, {
-              code: 'cancelled',
-              message: 'subagent history read was cancelled',
+              code: 'internal',
+              message: 'subagent history read failed',
               details: {},
             })
           }
-          if (error instanceof SessionQueryError
-            && error.code === 'SESSION_QUERY_SESSION_NOT_FOUND') {
-            return err(request, {
-              code: 'subagent-not-found',
-              message: 'subagent disappeared during history read',
-              details: { parentSessionId, childSessionId },
-            })
-          }
+        }
+        if (signal?.aborted) {
           return err(request, {
-            code: 'internal',
-            message: 'subagent history read failed',
+            code: 'cancelled',
+            message: 'subagent history read was cancelled',
             details: {},
           })
         }
+        if (header.parentSession !== parentSessionId) {
+          return err(request, {
+            code: 'subagent-unauthorized',
+            message: 'subagent parent changed during history read',
+            details: { childSessionId },
+          })
+        }
+        const page = historyPage(ctx, events, beforeSeq, maxMessages)
+        return ok(request, { ...page, ...projections === undefined ? {} : { projections } })
       },
 
       async prompt(request, signal) {
diff --git a/packages/host/apiproxy/src/api/subagents.ts b/packages/host/apiproxy/src/api/subagents.ts
index d1e0392eb1..4c251dca7c 100644
--- a/packages/host/apiproxy/src/api/subagents.ts
+++ b/packages/host/apiproxy/src/api/subagents.ts
@@ -70,7 +70,8 @@ export interface SubagentsApi {
   ): Promise<RpcResponse<SubagentCatalog>>
 
   /**
-   * Reads one healthy catalog child's persisted raw log with ordinary
+   * Reads one healthy catalog child's transcript — the in-memory snapshot of
+   * a live child, the persisted log of a cold one — with ordinary
    * message-aligned pagination and render intents, without Agent activation.
    */
   history(
diff --git a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
index 8b01e9005a..78a67ef642 100644
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -190,6 +190,7 @@ describe('subagent ownership fence', () => {
     const meta = header('session-child', 1000, {
       parentSession: sid('session-parent'),
       seedLength: 0,
+      origin: 'subagent',
     })
     const events = [
       { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
@@ -245,6 +246,47 @@ describe('subagent ownership fence', () => {
     expect(inspect).toHaveBeenCalledTimes(3)
   })
 
+  it('no longer treats a descriptor-only cold child without origin as subagent-owned', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const sessionId = sid('session-legacy-child')
+    const meta = header('session-legacy-child', 1000, {
+      parentSession: sid('session-parent'),
+      seedLength: 0,
+    })
+    const events = [
+      {
+        type: 'subagent/descriptor',
+        seq: 0,
+        time: 1,
+        data: { version: 2, mode: 'continuable', provider: 'spawn', label: 'child' },
+      },
+    ] as SessionEvent[]
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve([meta]),
+      inspect: () => Promise.resolve({ meta, events }),
+      locate: () => undefined,
+    } as never)
+    // Pre-#1569 stores classify a child only through the descriptor event and
+    // carry no header `origin`; the pre-release decision stops recognizing
+    // them, so the ownership fence lets generic resume reach the registry
+    // instead of answering `agent-busy`.
+    const resume = vi.spyOn(ctx.agents, 'resume')
+      .mockRejectedValue(new Error('registry unavailable in this bench'))
+    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+
+    const prompt = await api.sessions.prompt(request({
+      sessionId,
+      mode: 'queue',
+      content: [{ type: 'text', text: 'follow up' }],
+    }))
+    expect(resume).toHaveBeenCalledTimes(1)
+    expect(prompt.result.ok).toBe(false)
+    if (!prompt.result.ok) expect(prompt.result.error.code).toBe('internal')
+  })
+
   it('rejects origin-marked and runtime-owned live children from generic controls', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
diff --git a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
index faa1c39e9f..c761484da5 100644
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -1,7 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
-import { SessionQueryError } from '@deepseek-ai/dsh-session-query'
 import { SubagentError } from '@deepseek-ai/dsh-subagent'
 import { RpcId } from '../src/api/rpc.ts'
 import type { RpcRequest } from '../src/api/rpc.ts'
@@ -21,7 +20,12 @@ function bench(options: {
   entries?: object[]
   followupError?: Error
   listError?: Error
-  readError?: Error
+  /** Persistence forgets the child entirely (the vanished-mid-read race). */
+  storedChild?: false
+  /** Attach the child to the live session store instead of persistence only. */
+  liveChild?: true
+  /** Every registered projection unit throws on this child's payloads. */
+  projectionsThrow?: true
   historyParent?: SessionId
 } = {}) {
   const parent = { id: PARENT }
@@ -49,25 +53,44 @@ function bench(options: {
   ) => options.followupError === undefined
     ? Promise.resolve('message-1')
     : Promise.reject(options.followupError))
-  const readSession = vi.fn(() => options.readError === undefined
-    ? Promise.resolve({
-      session: {
-        version: 0, id: CHILD, createdAt: 1, parentSession: options.historyParent ?? PARENT,
-      } satisfies SessionHeader,
-      events: [
-        { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'work' }], source: { kind: 'user' } } },
-      ] as unknown as SessionEvent[],
-    })
-    : Promise.reject(options.readError))
+  const childHeader = {
+    version: 0, id: CHILD, createdAt: 1, cwd: '/proj', parentSession: options.historyParent ?? PARENT,
+  } satisfies SessionHeader
+  const childEvents = [
+    { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'work' }], source: { kind: 'user' } } },
+  ] as unknown as SessionEvent[]
+  const inspect = vi.fn(() => Promise.resolve({ meta: childHeader, events: childEvents }))
+  const liveBlock = { values: {}, asOfSeq: 3 }
+  const coldBlock = { values: {}, asOfSeq: 0 }
+  const snapshot = vi.fn(() => {
+    if (options.projectionsThrow === true) throw new Error('hostile unit')
+    return liveBlock
+  })
+  const restore = vi.fn(() => {
+    if (options.projectionsThrow === true) throw new Error('hostile unit')
+    return { snapshot: coldBlock }
+  })
   const ctx = new Context()
   ctx.provide('agents', { get: getAgent })
   ctx.provide('subagents', { listChildren, followup })
-  ctx.provide('sessionQuery', { readSession })
+  ctx.provide('sessions', {
+    get: (id: SessionId) => options.liveChild === true && id === CHILD
+      ? { id: CHILD, header: childHeader, events: childEvents }
+      : undefined,
+  })
+  ctx.provide('sessionPersistence', {
+    list: () => Promise.resolve(options.storedChild === false ? [] : [childHeader]),
+    inspect,
+    locate: () => undefined,
+  })
+  // The gateway's own projection push feed subscribes at construction; the
+  // no-op disposer keeps that seam quiet while these tests pin history reads.
+  ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
   ctx.provide('userInteraction', { registerProvider: () => () => {} })
   const api = createApiProxy(ctx, {
     provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp',
   })
-  return { api, getAgent, listChildren, readSession, followup, parent }
+  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, parent }
 }
 
 describe('subagent gateway', () => {
@@ -113,7 +136,7 @@ describe('subagent gateway', () => {
   })
 
   it('reads a healthy direct child without looking up or activating any Agent', async () => {
-    const { api, getAgent, readSession } = bench()
+    const { api, getAgent, inspect, restore } = bench()
     const response = await api.subagents.history(request({
       parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable', maxMessages: 10,
     }))
@@ -121,27 +144,65 @@ describe('subagent gateway', () => {
       ok: true,
       value: { hasMore: false, events: [{ event: { type: 'user/message', seq: 0 } }] },
     })
-    expect(readSession).toHaveBeenCalledWith(CHILD)
+    expect(inspect).toHaveBeenCalledWith(CHILD)
+    expect(restore).toHaveBeenCalledTimes(1)
     expect(getAgent).not.toHaveBeenCalled()
   })
 
+  it('serves a live child from the in-memory snapshot and the watermark projections', async () => {
+    const { api, inspect, snapshot, restore } = bench({ liveChild: true })
+    const response = await api.subagents.history(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable',
+    }))
+    expect(response.result).toMatchObject({
+      ok: true,
+      value: { hasMore: false, projections: { asOfSeq: 3 } },
+    })
+    expect(snapshot).toHaveBeenCalledTimes(1)
+    expect(restore).not.toHaveBeenCalled()
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('serves the page without projections when a hostile unit breaks the fold', async () => {
+    const cold = bench({ projectionsThrow: true })
+    const coldResponse = await cold.api.subagents.history(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable',
+    }))
+    expect(coldResponse.result).toMatchObject({
+      ok: true,
+      value: { hasMore: false, events: [{ event: { type: 'user/message', seq: 0 } }] },
+    })
+    if (coldResponse.result.ok) expect('projections' in coldResponse.result.value).toBe(false)
+
+    const live = bench({ projectionsThrow: true, liveChild: true })
+    const liveResponse = await live.api.subagents.history(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable',
+    }))
+    expect(liveResponse.result).toMatchObject({
+      ok: true,
+      value: { hasMore: false, events: [{ event: { type: 'user/message', seq: 0 } }] },
+    })
+    if (liveResponse.result.ok) expect('projections' in liveResponse.result.value).toBe(false)
+    expect(live.snapshot).toHaveBeenCalledTimes(1)
+  })
+
   it('reads one-shot history and rejects an address with the wrong mode', async () => {
     const oneShot = {
       kind: 'child', id: CHILD, mode: 'one-shot', label: 'batch',
       activity: 'inactive', hasChildren: false,
     }
-    const { api, readSession } = bench({ entries: [oneShot] })
+    const { api, inspect } = bench({ entries: [oneShot] })
     expect((await api.subagents.history(request({
       parentSessionId: PARENT, childSessionId: CHILD, mode: 'one-shot',
     }))).result).toMatchObject({ ok: true })
     expect((await api.subagents.history(request({
       parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable',
     }))).result).toMatchObject({ ok: false, error: { code: 'subagent-not-found' } })
-    expect(readSession).toHaveBeenCalledTimes(1)
+    expect(inspect).toHaveBeenCalledTimes(1)
   })
 
   it('rejects a diagnostic address before reading history', async () => {
-    const { api, readSession } = bench({ entries: [
+    const { api, inspect } = bench({ entries: [
       { kind: 'diagnostic', id: CHILD, reason: 'unsupported' },
     ] })
     const response = await api.subagents.history(request({
@@ -154,7 +215,34 @@ describe('subagent gateway', () => {
         details: { parentSessionId: PARENT, childSessionId: CHILD, reason: 'unsupported' },
       },
     })
-    expect(readSession).not.toHaveBeenCalled()
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('maps the missing projections capability to one wire face on list, history, and prompt', async () => {
+    const listError = () => new SubagentError(
+      'listing subagents requires the sessionProjections registry (load @deepseek-ai/dsh-session-projection)',
+      'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE',
+    )
+    const expected = {
+      code: 'internal',
+      message: 'subagent catalog is unavailable: this deployment does not mount the sessionProjections registry (load @deepseek-ai/dsh-session-projection)',
+    }
+
+    const list = bench({ listError: listError() })
+    expect((await list.api.subagents.list(request({ parentSessionId: PARENT }))).result)
+      .toMatchObject({ ok: false, error: expected })
+
+    const history = bench({ listError: listError() })
+    expect((await history.api.subagents.history(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable',
+    }))).result).toMatchObject({ ok: false, error: expected })
+    expect(history.inspect).not.toHaveBeenCalled()
+
+    const prompt = bench({ listError: listError() })
+    expect((await prompt.api.subagents.prompt(request({
+      parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable', content: [],
+    }), new AbortController().signal)).result).toMatchObject({ ok: false, error: expected })
+    expect(prompt.followup).not.toHaveBeenCalled()
   })
 
   it('routes human content through the exact live parent with rpc attribution', async () => {
@@ -193,9 +281,7 @@ describe('subagent gateway', () => {
   })
 
   it('maps history disappearance and hides unexpected backend details', async () => {
-    const disappeared = bench({
-      readError: new SessionQueryError('secret path', 'SESSION_QUERY_SESSION_NOT_FOUND'),
-    })
+    const disappeared = bench({ storedChild: false })
     expect((await disappeared.api.subagents.history(request({
       parentSessionId: PARENT, childSessionId: CHILD, mode: 'continuable',
     }))).result).toMatchObject({
diff --git a/packages/sdk/helper/package.json b/packages/sdk/helper/package.json
index bf9eacb813..bed70dbbda 100644
--- a/packages/sdk/helper/package.json
+++ b/packages/sdk/helper/package.json
@@ -45,6 +45,7 @@
     "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
     "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-todo": "workspace:^",
     "@deepseek-ai/dsh-tool-web": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
diff --git a/packages/sdk/helper/src/features/builtin/index.ts b/packages/sdk/helper/src/features/builtin/index.ts
index b23325445d..abdcc35dd5 100644
--- a/packages/sdk/helper/src/features/builtin/index.ts
+++ b/packages/sdk/helper/src/features/builtin/index.ts
@@ -10,6 +10,7 @@ import type { Config as CodexHooksConfig } from '@deepseek-ai/dsh-hooks-codex'
 import type { Config as JsonlConfig } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import type { Config as SqliteConfig } from '@deepseek-ai/dsh-session-persistence-sqlite'
 import type { Config as ToolSubagentConfig } from '@deepseek-ai/dsh-tool-subagent'
+import type { Config as ToolTodoConfig } from '@deepseek-ai/dsh-tool-todo'
 import type { Config as ToolWebConfig } from '@deepseek-ai/dsh-tool-web'
 import type { ProjectProfile } from '../../project/types.ts'
 import { defineFeatures } from '../define-feature.ts'
@@ -126,7 +127,12 @@ config:
         id: 'default',
         label: 'todo_write tool',
         default: true,
-        resources: [{ kind: 'npm-cordis-config-entry', id: 'tool-todo', package: '@deepseek-ai/dsh-tool-todo' }],
+        resources: [{
+          kind: 'npm-cordis-config-entry',
+          id: 'tool-todo',
+          package: '@deepseek-ai/dsh-tool-todo',
+          config: { allowParallelInProgress: true } satisfies ToolTodoConfig,
+        }],
       }],
     },
     {
diff --git a/packages/sdk/helper/tsconfig.json b/packages/sdk/helper/tsconfig.json
index b1a3b7a61a..528b370a5c 100644
--- a/packages/sdk/helper/tsconfig.json
+++ b/packages/sdk/helper/tsconfig.json
@@ -27,6 +27,9 @@
     {
       "path": "../../subagent/tool-subagent"
     },
+    {
+      "path": "../../todo/tool-todo"
+    },
     {
       "path": "../../web/tool-web"
     },
diff --git a/packages/session-query/session-query/tests/session-query.spec.ts b/packages/session-query/session-query/tests/session-query.spec.ts
index ebcad51bd7..acc993d2b3 100644
--- a/packages/session-query/session-query/tests/session-query.spec.ts
+++ b/packages/session-query/session-query/tests/session-query.spec.ts
@@ -3,7 +3,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context, type Fiber } from 'cordis'
 import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader, SessionId as SessionIdType } from '@deepseek-ai/dsh-session'
-import SessionPersistence, { SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
+import SessionPersistence, { SessionPersistenceCorruptionError, SessionPersistenceRevision } from '@deepseek-ai/dsh-session-persistence'
 import SessionQueryService, {
   SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
   type SessionEventSurface,
@@ -1114,6 +1114,24 @@ describe('session-query exact reads', () => {
     await expect(ctx.sessionQuery.listEvents(SessionId('durable'))).rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
   })
 
+  it('wraps persisted corruption as SESSION_QUERY_CORRUPT_SESSION with its cause preserved', async () => {
+    const durable = header('durable-corrupt')
+    TestPersistence.reset([{ meta: durable, events: eventLog() }])
+    const ctx = await liveContext()
+    await ctx.plugin(TestPersistence)
+    const corruption = new SessionPersistenceCorruptionError(
+      'stored prefix failed validation',
+      { cause: new Error('torn final record') },
+    )
+    TestPersistence.inspectFailure = corruption
+
+    await expect(ctx.sessionQuery.readSession(durable.id)).rejects.toMatchObject({
+      code: 'SESSION_QUERY_CORRUPT_SESSION',
+      message: `stored session "${durable.id}" is corrupt: stored prefix failed validation`,
+      cause: corruption,
+    })
+  })
+
   it('reports absent sessions, persisted load failures, and persisted header conflicts', async () => {
     const durable = header('durable')
     TestPersistence.reset([{ meta: durable, events: eventLog() }])
diff --git a/packages/subagent/README.i18n.yaml b/packages/subagent/README.i18n.yaml
index 9cde7517ab..11357c76d2 100644
--- a/packages/subagent/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 6aeb7fb1eaa9341dd72df614ca11d114f321fb83
-README.zh.md: a78cb365a8e96ad44c0c930c072372f88930906c
+README.md: 0a342569e66539e4987710b2e56f2946c97b1ac1
+README.zh.md: 5d2f7beef478b8bfd27b4772c7a951ea62cb10ef
diff --git a/packages/subagent/README.md b/packages/subagent/README.md
index 6aeb7fb1ea..0a342569e6 100644
--- a/packages/subagent/README.md
+++ b/packages/subagent/README.md
@@ -11,6 +11,8 @@ This family lets an agent delegate work to child agents. Multiple named provider
 | [`subagent-spawn/`](subagent-spawn/README.md) | Starts a fresh in-process child | registers on `ctx.subagents` |
 | [`subagent-fork/`](subagent-fork/README.md) | Starts an in-process child from the parent's completed history | registers on `ctx.subagents` |
 | [`subagent-acp/`](subagent-acp/README.md) | Starts an out-of-process child over ACP | registers on `ctx.subagents` |
+| [`subagent-codex/`](subagent-codex/README.md) | Starts a real Codex app-server child | registers on `ctx.subagents` |
+| [`subagent-claude-code/`](subagent-claude-code/README.md) | Starts a real Claude Code child through the official Claude Agent SDK | registers on `ctx.subagents` |
 | [`subagent-dsh-sdk/`](subagent-dsh-sdk/README.md) | Starts an out-of-process Harness child through the TypeScript SDK | registers on `ctx.subagents` |
 | [`tool-subagent/`](tool-subagent/README.md) | Exposes delegation to the model | registers on `ctx.tools` |
 | [`tool-subagent-control/`](tool-subagent-control/README.md) | Exposes child messaging and listing to the model | registers on `ctx.tools` |
diff --git a/packages/subagent/README.zh.md b/packages/subagent/README.zh.md
index a78cb365a8..5d2f7beef4 100644
--- a/packages/subagent/README.zh.md
+++ b/packages/subagent/README.zh.md
@@ -11,6 +11,8 @@
 | [`subagent-spawn/`](subagent-spawn/README.md) | 启动全新的进程内子 agent | 注册到 `ctx.subagents` |
 | [`subagent-fork/`](subagent-fork/README.md) | 从父 agent 已完成的历史记录启动进程内子 agent | 注册到 `ctx.subagents` |
 | [`subagent-acp/`](subagent-acp/README.md) | 通过 ACP（Agent Client Protocol）启动进程外子 agent | 注册到 `ctx.subagents` |
+| [`subagent-codex/`](subagent-codex/README.md) | 启动真实的 Codex app-server 子 agent | 注册到 `ctx.subagents` |
+| [`subagent-claude-code/`](subagent-claude-code/README.md) | 通过官方 Claude Agent SDK 启动真实的 Claude Code 子 agent | 注册到 `ctx.subagents` |
 | [`subagent-dsh-sdk/`](subagent-dsh-sdk/README.md) | 通过 TypeScript SDK 启动进程外 Harness 子 agent | 注册到 `ctx.subagents` |
 | [`tool-subagent/`](tool-subagent/README.md) | 向模型公开委派操作 | 注册到 `ctx.tools` |
 | [`tool-subagent-control/`](tool-subagent-control/README.md) | 向模型公开子级消息发送和列举操作 | 注册到 `ctx.tools` |
diff --git a/packages/subagent/subagent-acp/README.i18n.yaml b/packages/subagent/subagent-acp/README.i18n.yaml
index 2f5532e9f4..f44ae87197 100644
--- a/packages/subagent/subagent-acp/README.i18n.yaml
+++ b/packages/subagent/subagent-acp/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-acp/README.md
-README.md: 83a5f60414528bdb768ffccd29f3091793f44b6b
-README.zh.md: 4ea8daef9341897463f3dbedca86fd2c83b45514
+README.md: 4fdd3a09e128d4dc7ec7395d9578803c64a33bc6
+README.zh.md: 7cb1e3d18602ef839e4af316962fc2d10bc67640
diff --git a/packages/subagent/subagent-acp/README.md b/packages/subagent/subagent-acp/README.md
index 83a5f60414..4fdd3a09e1 100644
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -14,7 +14,7 @@ The returned run id is minted in the parent namespace. The child server's sessio
 
 After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation.
 
-`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, then runs this backend's own teardown ladder (`disposeAcpChild`) over the seam's verbs: close stdin and wait `disposeEofGraceMs` for cooperative quiescence, then the handle's `terminate()` escalation (SIGTERM, the spawn grace, SIGKILL — Windows force-terminates directly), then a bounded whole-tree exit wait that rejects if survivors remain. Every run uses a fresh process; process pooling is not implemented.
+`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, then runs this backend's own teardown ladder (`disposeAcpChild`) over the seam's verbs: close stdin and wait `disposeEofGraceMs` for cooperative quiescence, then invoke the handle's `terminate()` escalation (SIGTERM, the spawn grace, SIGKILL — Windows force-terminates directly) and await the subprocess owner's whole-tree exit proof. Every run uses a fresh process; process pooling is not implemented.
 
 ## Capabilities and context
 
@@ -30,8 +30,8 @@ ACP advertises no start-time capabilities because this process cannot enforce th
 | `cwd` | parent session cwd | Working-directory override for the child process and its ACP session; must be non-empty, a relative value resolves against the harness launch directory at load, and the result must name a directory the harness can enter. |
 | `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first allow-shaped option. |
 | `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. |
-| `disposeEofGraceMs` | `6000` | Grace after stdin EOF before platform termination. |
-| `disposeGraceMs` | `3000` | Exit-confirmation grace after termination; POSIX also waits this long after SIGTERM before SIGKILL. |
+| `disposeEofGraceMs` | `6000` | Positive grace after stdin EOF before platform termination; it cannot exceed [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md). |
+| `disposeGraceMs` | `3000` | Positive POSIX grace after SIGTERM before SIGKILL (Windows force-terminates directly); it cannot exceed [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md). |
 
 ```yaml
 - id: subagent-acp
@@ -57,7 +57,7 @@ ACP advertises no start-time capabilities because this process cannot enforce th
 
 ## Process boundary
 
-The child spawns through the [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam: credential-shaped ambient variables and ambient `DSH_*` names are removed by the shared scrub, then explicit `config.env` values merge after it (an intended `DEEPSEEK_API_KEY` survives, and a `DSH_*` deployment fact such as `DSH_PERMISSION_MODE` reaches the child the same way — the scrub drops only its stale ambient namesake), stderr is inherited to the parent's own stream, and disposal runs the seam's cooperative stdin-EOF→SIGTERM→SIGKILL ladder with this plugin's configured graces. The ACP wire is the real serialization boundary; same-process subagent values are not defensively cloned.
+The child spawns through the [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam: credential-shaped ambient variables and ambient `DSH_*` names are removed by the shared scrub, then explicit `config.env` values merge after it (an intended `DEEPSEEK_API_KEY` survives, and a `DSH_*` deployment fact such as `DSH_PERMISSION_MODE` reaches the child the same way — the scrub drops only its stale ambient namesake), stderr is inherited to the parent's own stream, and disposal applies this plugin's EOF window before the subprocess-owned SIGTERM→SIGKILL escalation and whole-tree join. The ACP wire is the real serialization boundary; same-process subagent values are not defensively cloned.
 
 The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
 
diff --git a/packages/subagent/subagent-acp/README.zh.md b/packages/subagent/subagent-acp/README.zh.md
index 4ea8daef93..7cb1e3d186 100644
--- a/packages/subagent/subagent-acp/README.zh.md
+++ b/packages/subagent/subagent-acp/README.zh.md
@@ -14,7 +14,7 @@ ACP（Agent Client Protocol）提供方会在全新的子进程中运行每个 s
 
 发布后，提供方发送提示词，并把流式 `agent_message_chunk` 文本收集到 `SubagentResult.output`。提示词/传输失败会以 `stopReason: 'error'` 兑现；如果必需的请求信号或 dispose（资源释放）请求了取消，则以 `aborted` 兑现。
 
-`dispose()` 是幂等的。它会移除信号监听器，在可行时请求 ACP 取消，然后经由该 seam 的动词运行本后端自有的拆卸阶梯（`disposeAcpChild`）：先关闭 stdin 并等待 `disposeEofGraceMs` 让子进程协作式完全停稳，再触发句柄的 `terminate()` 升级（SIGTERM、spawn 宽限期、SIGKILL——Windows 直接强制终止），最后进行有界的整树退出等待；若仍有存活进程，则拒绝。每次运行都使用全新进程；尚未实现进程池。
+`dispose()` 是幂等的。它会移除信号监听器，在可行时请求 ACP 取消，然后经由该 seam 的动词运行本后端自有的拆卸阶梯（`disposeAcpChild`）：先关闭 stdin 并等待 `disposeEofGraceMs` 让子进程协作式完全停稳，再触发句柄的 `terminate()` 升级（SIGTERM、spawn 宽限期、SIGKILL——Windows 直接强制终止），并等待子进程责任方给出整棵进程树的退出证明。每次运行都使用全新进程；尚未实现进程池。
 
 ## 能力与上下文
 
@@ -30,8 +30,8 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
 | `cwd` | 父会话 cwd | 子进程及其 ACP 会话的工作目录覆盖值；不得为空。相对值会在加载时以 harness 启动目录为基准解析，结果必须指向 harness 可以进入的目录。 |
 | `permission` | `reject` | 自动回答权限请求：拒绝，或选择第一个允许形态的选项。 |
 | `env` | `{}` | 显式子进程环境，叠加到已清理凭据的父进程环境之上。 |
-| `disposeEofGraceMs` | `6000` | stdin EOF 之后、平台终止之前的宽限时间。 |
-| `disposeGraceMs` | `3000` | 终止后的退出确认宽限时间；POSIX 在 SIGTERM 后、SIGKILL 前也会等待同样时长。 |
+| `disposeEofGraceMs` | `6000` | stdin EOF 之后、平台终止之前的宽限时间须为正值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)。 |
+| `disposeGraceMs` | `3000` | POSIX 在 SIGTERM 后、SIGKILL 前的宽限时间（Windows 直接强制终止），须为正值且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)。 |
 
 ```yaml
 - id: subagent-acp
@@ -57,7 +57,7 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
 
 ## 进程边界
 
-子进程经由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam spawn：共享的凭据清除先移除疑似凭据的环境变量和环境中已有的 `DSH_*` 名称，显式 `config.env` 值在清除之后合并（有意转发的 `DEEPSEEK_API_KEY` 会保留下来，`DSH_PERMISSION_MODE` 这类 `DSH_*` 部署事实也以同样的方式到达子进程——清除只丢弃其陈旧的同名环境值），stderr 会继承到父进程自身的流，dispose 则以本插件配置的宽限期运行该 seam 的协作式 stdin EOF→SIGTERM→SIGKILL 阶梯。ACP 协议格式（wire format）是真正的序列化边界；同进程 subagent 值不会为防御目的而克隆。
+子进程经由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam spawn：共享的凭据清除先移除疑似凭据的环境变量和环境中已有的 `DSH_*` 名称，显式 `config.env` 值在清除之后合并（有意转发的 `DEEPSEEK_API_KEY` 会保留下来，`DSH_PERMISSION_MODE` 这类 `DSH_*` 部署事实也以同样的方式到达子进程——清除只丢弃其陈旧的同名环境值），stderr 会继承到父进程自身的流，dispose 则先应用本插件的 EOF 时间窗，再由子进程责任方执行 SIGTERM→SIGKILL 升级并等待整棵进程树退出。ACP 协议格式（wire format）是真正的序列化边界；同进程 subagent 值不会为防御目的而克隆。
 
 本包没有默认导出。否则 Cordis loader 的解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)。
 
diff --git a/packages/subagent/subagent-acp/package.json b/packages/subagent/subagent-acp/package.json
index 382d2e219a..424cb9cb5c 100644
--- a/packages/subagent/subagent-acp/package.json
+++ b/packages/subagent/subagent-acp/package.json
@@ -31,6 +31,7 @@
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-subagent": "^0.0.1",
     "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
@@ -47,6 +48,7 @@
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
     "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/subagent/subagent-acp/src/index.ts b/packages/subagent/subagent-acp/src/index.ts
index 8616f7ae94..fa7c031760 100644
--- a/packages/subagent/subagent-acp/src/index.ts
+++ b/packages/subagent/subagent-acp/src/index.ts
@@ -17,6 +17,7 @@ import type {
   SubagentProvider,
   SubagentStartRequest,
 } from '@deepseek-ai/dsh-subagent'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import { type AcpRunSpec, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, type PermissionPolicy, startAcpRun } from './run.ts'
 
 export const name = 'subagent-acp'
@@ -54,10 +55,11 @@ export interface Config {
   /**
    * Grace period (ms) for the child's EOF-driven quiesce on dispose — its
    * window to flush persistence and tear down its own nested subprocesses
-   * before the parent escalates to a signal.
+   * before the parent escalates to a signal. Must not exceed
+   * `MAX_TIMER_DELAY_MS`.
    */
   disposeEofGraceMs?: number
-  /** Termination confirmation window (ms), including forced exit on every platform. */
+  /** Termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */
   disposeGraceMs?: number
 }
 
@@ -72,10 +74,10 @@ export const Config: z<Config> = z.object({
   disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS),
 })
 
-/** A dispose grace must be a positive finite number (it bounds the teardown wait). */
+/** A dispose grace must fit the single Node timer that owns its teardown tier. */
 function assertPositiveFinite(name: string, value: number): void {
-  if (!Number.isFinite(value) || value <= 0) {
-    throw new Error(`subagent-acp: ${name} must be a positive finite number`)
+  if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subagent-acp: ${name} must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
   }
 }
 
diff --git a/packages/subagent/subagent-acp/src/run.ts b/packages/subagent/subagent-acp/src/run.ts
index fba0403739..f3e155e649 100644
--- a/packages/subagent/subagent-acp/src/run.ts
+++ b/packages/subagent/subagent-acp/src/run.ts
@@ -62,9 +62,9 @@ export interface AcpRunSpec {
    */
   disposeEofGraceMs: number
   /**
-   * Termination confirmation window (ms) in {@link SubagentRun.dispose}; POSIX applies it after
-   * `SIGTERM` and `SIGKILL`, while Windows applies it after direct forced termination. The plugin
-   * fills this from its `disposeGraceMs` config.
+   * Termination-escalation grace (ms) in {@link SubagentRun.dispose}; POSIX
+   * waits this long after `SIGTERM` before `SIGKILL`, while Windows
+   * force-terminates directly. The plugin fills it from `disposeGraceMs`.
    */
   disposeGraceMs: number
   /**
@@ -105,14 +105,12 @@ async function treeExitsWithin(child: SubprocessHandle, ms: number): Promise<boo
  * Cooperative teardown ladder for an out-of-process agent, over the seam's
  * public verbs; resolves only at whole-tree quiescence: stdin EOF (the child's
  * window to flush persistence and reap its own descendants), then the
- * terminate() escalation (SIGTERM → spec grace → SIGKILL), then a bounded
- * confirmation wait.
+ * terminate() escalation (SIGTERM → spec grace → SIGKILL) and its
+ * whole-tree exit proof.
  * @param child - the spawned ACP child's handle.
  * @param eofGraceMs - tier-1 window after stdin EOF.
- * @param graceMs - confirmation window after the escalation's SIGKILL.
- * @throws when the tree still has not exited `graceMs` after forced termination.
  */
-export async function disposeAcpChild(child: SubprocessHandle, eofGraceMs: number, graceMs: number): Promise<void> {
+export async function disposeAcpChild(child: SubprocessHandle, eofGraceMs: number): Promise<void> {
   // A spawn failure has no process to tear down; observe the rejection so
   // disposal in a finally block cannot surface it as unhandled.
   if (child.pid <= 0) {
@@ -121,13 +119,10 @@ export async function disposeAcpChild(child: SubprocessHandle, eofGraceMs: numbe
   }
   child.stdin?.end()
   if (await treeExitsWithin(child, eofGraceMs)) return
-  // terminate() sends SIGTERM now and SIGKILL after the spawn spec's grace
-  // (this plugin passes disposeGraceMs there), so the bound covers both the
-  // escalation window and an equal confirmation window after the SIGKILL.
+  // terminate() owns the bounded SIGTERM→SIGKILL timer. Its unbounded wait is
+  // the process owner's exit proof, not a second derived grace that can overflow.
   child.terminate()
-  if (!(await treeExitsWithin(child, graceMs * 2))) {
-    throw new Error('ACP child process tree did not exit within its dispose windows')
-  }
+  await child.waitForExit()
 }
 
 /**
@@ -235,7 +230,7 @@ export async function startAcpRun(request: SubagentStartRequest, spec: AcpRunSpe
 
   // Startup rollback and the published handle share one process teardown.
   let processDisposal: Promise<void> | undefined
-  const disposeProcess = (): Promise<void> => (processDisposal ??= disposeAcpChild(child, spec.disposeEofGraceMs, spec.disposeGraceMs))
+  const disposeProcess = (): Promise<void> => (processDisposal ??= disposeAcpChild(child, spec.disposeEofGraceMs))
 
   // Accumulate the child's streamed assistant text — the SubagentResult output.
   const output: string[] = []
diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
index f2cbeda27b..6c6c238e74 100644
--- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts
@@ -7,6 +7,7 @@ import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import * as acp from '../src/index.ts'
 import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DISPOSE_GRACE_MS, disposeAcpChild, startAcpRun, toAcpPrompt, type AcpRunSpec } from '../src/run.ts'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
@@ -147,7 +148,7 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)',
 
   it('tier 1: a cooperative child exits on stdin EOF without any signal', async () => {
     const child = bash('read -r line; exit 0')
-    await disposeAcpChild(child, 5_000, 200)
+    await disposeAcpChild(child, 5_000)
     const outcome = await child.done
     expect(outcome.exitCode).toBe(0)
     expect(outcome.signal).toBeNull()
@@ -155,7 +156,7 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)',
 
   it('tier 2: an EOF-deaf child dies by the terminate escalation (SIGTERM)', async () => {
     const child = bash('sleep 60')
-    await disposeAcpChild(child, 100, 5_000)
+    await disposeAcpChild(child, 100)
     const outcome = await child.done
     expect(outcome.signal).toBe('SIGTERM')
   })
@@ -166,30 +167,11 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)',
     while (!child.collected.stdout!.readFrom(0).text.includes('armed')) {
       await new Promise(resolve => setTimeout(resolve, 10))
     }
-    await disposeAcpChild(child, 50, 2_000)
+    await disposeAcpChild(child, 50)
     const outcome = await child.done
     expect(outcome.signal).toBe('SIGKILL')
   })
 
-  it('throws when the tree survives even the escalation window', async () => {
-    // A handle whose tree never exits (waitForExit only ever aborts): the
-    // ladder must fail loud instead of resolving over survivors. Built as a
-    // stub because the ladder composes only public verbs.
-    const never: Parameters<typeof disposeAcpChild>[0] = {
-      pid: 1,
-      stdin: undefined,
-      stdout: undefined,
-      stderr: undefined,
-      collected: {},
-      done: new Promise(() => {}),
-      terminate: () => {},
-      waitForExit: (signal?: AbortSignal) => new Promise((resolve) => {
-        signal?.addEventListener('abort', () => { resolve(false) }, { once: true })
-      }),
-    }
-    await expect(disposeAcpChild(never, 20, 20)).rejects.toThrow(/did not exit within its dispose windows/)
-  })
-
   it('observes a spawn-level rejection and returns without a process to reap', async () => {
     const child = spawnSubprocess({
       argv: ['bash', '-c', 'true'],
@@ -197,7 +179,7 @@ describe('disposeAcpChild (the backend-owned teardown ladder over seam verbs)',
       stdio: { stdin: 'ignore', stdout: { maxBytes: 1000 }, stderr: { maxBytes: 1000 } },
       graceMs: 200,
     })
-    await expect(disposeAcpChild(child, 1_000, 1_000)).resolves.toBeUndefined()
+    await expect(disposeAcpChild(child, 1_000)).resolves.toBeUndefined()
     await expect(child.done).rejects.toThrow()
   })
 })
@@ -721,13 +703,20 @@ describe('dsh-subagent-acp', () => {
     }
   })
 
-  it('rejects a non-positive dispose grace at load', async () => {
-    for (const bad of [{ disposeEofGraceMs: 0 }, { disposeGraceMs: -1 }, { disposeEofGraceMs: Number.NaN }]) {
+  it('rejects a dispose grace outside the Node timer range at load', async () => {
+    for (const bad of [
+      { disposeEofGraceMs: 0 },
+      { disposeGraceMs: -1 },
+      { disposeEofGraceMs: Number.NaN },
+      { disposeGraceMs: Number.POSITIVE_INFINITY },
+      { disposeEofGraceMs: MAX_TIMER_DELAY_MS + 1 },
+      { disposeGraceMs: MAX_TIMER_DELAY_MS + 1 },
+    ]) {
       const ctx = new Context()
       await ctx.plugin(SubagentService)
       await ctx.plugin(LocalSubprocessService)
       await expect(ctx.plugin(acp, { providerName: 'acp', command: 'true', args: [], permission: 'reject', env: {}, ...bad }))
-        .rejects.toThrow(/subagent-acp: dispose(?:Eof)?GraceMs must be a positive finite number/)
+        .rejects.toThrow(new RegExp(`subagent-acp: dispose(?:Eof)?GraceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`))
       await ctx.fiber.dispose()
     }
   })
diff --git a/packages/subagent/subagent-acp/tsconfig.json b/packages/subagent/subagent-acp/tsconfig.json
index 2d60858d4a..c7966ddc6f 100644
--- a/packages/subagent/subagent-acp/tsconfig.json
+++ b/packages/subagent/subagent-acp/tsconfig.json
@@ -29,6 +29,9 @@
     {
       "path": "../../subprocess/subprocess"
     },
+    {
+      "path": "../../util/timeout"
+    },
     {
       "path": "../../support/loader-smoke"
     },
diff --git a/packages/subagent/subagent-claude-code/README.i18n.yaml b/packages/subagent/subagent-claude-code/README.i18n.yaml
new file mode 100644
index 0000000000..6bc638bdc4
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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-claude-code/README.md
+README.md: e62f60fceea16749296a91377785b81d94d751ca
+README.zh.md: e171524157b2b1696df31753816210d41637a911
diff --git a/packages/subagent/subagent-claude-code/README.md b/packages/subagent/subagent-claude-code/README.md
new file mode 100644
index 0000000000..e62f60fcee
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/README.md
@@ -0,0 +1,96 @@
+# @deepseek-ai/dsh-subagent-claude-code
+
+English | [中文](README.zh.md)
+
+This package registers the fixed `claude-code` subagent provider. Each accepted run invokes the official Claude Agent SDK in the delegating Session's workspace, starts the SDK-distributed Claude Code CLI through the shared subprocess service, submits one self-contained text task, and returns only the final answer through the shared [`dsh-subagent`](../subagent/README.md) result contract.
+
+## Start and ownership
+
+`start(request)` accepts only a non-empty sequence of text blocks and derives the child cwd from the parent Session. It creates one private `AbortController`, calls the official SDK `query()`, and publishes the run only after the SDK's `spawnClaudeCodeProcess` hook has supplied a live CLI handle owned by [`dsh-subprocess`](../../subprocess/subprocess/README.md). A failure or cancellation before publication closes the query, terminates any acquired process tree, waits for it to exit, and rejects `start()`.
+
+The SDK receives the exact concatenated text task. The provider iterates the complete SDK message stream and accepts only a `result` message with `subtype: "success"`, `is_error: false`, and a nonblank `result`, followed by normal iterator completion. Every SDK error subtype, an error-marked success, a missing answer, iterator failure, protocol failure, or process failure maps to `error`; this version produces neither `max-tokens` nor `refusal`.
+
+Local cancellation wins the result race and maps to `aborted`. `dispose()` is idempotent: it aborts the run, asks the SDK query to close, invokes the shared process-tree termination escalation, and waits for whole-tree exit. SDK graceful close expresses protocol intent; the subprocess handle remains the authority for process quiescence. Result failure and independent teardown failure remain separate.
+
+## Native settings and interaction
+
+The provider deliberately omits the SDK `settingSources` option. The official SDK therefore reads the host's normal user, project, and local Claude settings relative to the parent Session cwd, including native account state and product configuration. The provider neither copies nor filters those files and does not create or modify login state.
+
+Each query sets `persistSession: false` and disables `AskUserQuestion`. It supplies no `canUseTool`, elicitation, or dialog callback, so unattended interactions fail through the SDK instead of waiting for a user interface this provider does not own.
+
+## Capabilities and context
+
+The provider advertises no optional start-time capabilities and reports `inheritsParentContext: false`. Claude Code receives the standalone text task and the parent Session cwd, but not the parent conversation, persona, tool filter, depth policy, or structured-output contract. Every run has an independent SDK query, cancellation controller, CLI process, and non-persisted product session.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `env` | `{}` | Explicit SDK/CLI environment layered over the shared credential-scrubbed parent environment. |
+| `disposeGraceMs` | `3000` | Positive finite grace in milliseconds, no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), between the shared process-tree owner's termination tiers; disposal then waits for whole-tree exit. |
+
+Production uses the Claude Code CLI supplied by `@anthropic-ai/claude-agent-sdk` and the host's native settings and authentication. The plugin does not install another CLI, select a model, create a product home, log in, or probe an account. Credential-shaped ambient variables are removed before the explicit `env` overlay is applied, so an API key or token intended for the child must be supplied there. Non-credential endpoint variables such as `ANTHROPIC_BASE_URL`, along with ordinary ambient values such as `PATH` and `HOME`, remain inherited unless overridden.
+
+Install this package and add the following rows to your own `cordis.yml`. Shipped CLI configurations do not load this provider or expose `subagent_claude_code` by default.
+
+```yaml
+- id: subagent-claude-code
+  name: '@deepseek-ai/dsh-subagent-claude-code'
+  config:
+    env:
+      ANTHROPIC_API_KEY: !!js process.env.ANTHROPIC_API_KEY
+
+- id: tool-subagent-claude-code
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: claude-code
+    toolName: subagent_claude_code
+    enableRunInBackground: false
+    maxDepth: provider-managed
+```
+
+## Product compatibility and evidence
+
+The runtime dependency is pinned to `@anthropic-ai/claude-agent-sdk@0.3.220`, whose platform optional dependency supplies Claude Code 2.1.220. Required evidence exercises that official distribution through a keyless loopback product path and a credentialed DeepSeek path, while Loader composition proves that both opt-in product packages coexist without starting either product.
+
+The project owner's identity-scoped distribution authorization covers the official SDK and the official CLI/platform payloads declared by each SDK version. [`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) discloses the current optional payload closure without classifying its declared terms as permissive; unrelated non-permissive runtime dependencies continue to fail the notices gate.
+
+## Model Experience
+
+### Child request
+
+#### What the model sees
+
+The Claude Code child receives the standalone text task as one fresh SDK query. Its workspace is the parent Session cwd, while its model, system instructions, tools, permissions, and authentication come from the host's native Claude settings and product installation.
+
+#### Token effect
+
+The child pays for an independent Claude Code context and query. Child tokens do not enter the parent's context.
+
+#### KV Cache effect
+
+Independent of the parent request cache. Reuse depends only on Claude Code's own model, instructions, tools, native settings, and fresh query.
+
+### Parent tool result, indirectly
+
+#### What the model sees
+
+Through `dsh-tool-subagent`, the parent sees only the strict final Claude Code answer or the consumer's exact error for a non-completed result. Claude Code reasoning, tool activity, intermediate messages, stderr, workspace diffs, usage, and product ids are not copied into the parent Session.
+
+#### Token effect
+
+Parent input grows only by the final answer or error retained in the tool result. This provider adds no parent tool schema by itself.
+
+#### KV Cache effect
+
+Append-only: the new tool result follows the reusable parent request prefix.
+
+## Known Limitations and Deferred Work
+
+- **One fresh query and process per run** — there is no continuation, resume, pooling, progress stream, or product-session persistence.
+- **Host settings are intentionally authoritative** — project and user settings can change model, tools, and behavior; the provider does not provide a filtered or hermetic production mode.
+- **Product installation and account state remain native** — an incompatible SDK payload, configuration error, or authentication failure is surfaced as a startup or run error; the plugin provides no installer or login flow.
+- **No human interaction path** — `AskUserQuestion` is disabled and other interactive callbacks are absent, so tasks requiring new approval or input fail instead of suspending.
+- **Final text only** — reasoning, intermediate messages, tool traffic, usage, stderr, and workspace diffs remain product-local.
+- **No optional shared capabilities** — output schemas, child personas, tool filtering, and harness depth enforcement are rejected by the shared service for this provider.
+- **No wall-clock timeout or side-effect rollback** — the caller cancels long work, and files or external systems changed before cancellation are not restored.
diff --git a/packages/subagent/subagent-claude-code/README.zh.md b/packages/subagent/subagent-claude-code/README.zh.md
new file mode 100644
index 0000000000..e171524157
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/README.zh.md
@@ -0,0 +1,96 @@
+# @deepseek-ai/dsh-subagent-claude-code
+
+[English](README.md) | 中文
+
+本包（package）注册固定的 `claude-code` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中调用官方 Claude Agent SDK，通过共享子进程服务启动 SDK 分发的 Claude Code CLI，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+
+## 启动与所有权
+
+`start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。它会创建一个私有 `AbortController`，调用官方 SDK 的 `query()`，并仅在 SDK 的 `spawnClaudeCodeProcess` 钩子已经提供由 [`dsh-subprocess`](../../subprocess/subprocess/README.md) 管理的活动 CLI 句柄后发布此次运行。若在发布前发生失败或取消，它会关闭 query、终止所有已取得的进程树并等待其退出，然后拒绝 `start()` 调用。
+
+SDK 接收由文本块原样拼接成的任务。提供方会完整迭代 SDK 消息流，而且只接受满足以下条件的 `result` 消息：其 `subtype: "success"`、`is_error: false` 且 `result` 非空白，之后迭代器还须正常结束。所有 SDK 错误子类型、标记为错误的成功消息、缺失答案、迭代器失败、协议失败或进程失败都映射为 `error`；本版本不会产生 `max-tokens` 或 `refusal`。
+
+本地取消会在结果竞态中胜出并映射为 `aborted`。`dispose()` 具有幂等性：它会中止此次运行、请求 SDK query 关闭、调用共享的进程树逐级终止机制，并等待整棵进程树退出。SDK 的优雅关闭只表达协议意图；进程是否完全停稳仍以子进程句柄为准。结果失败与独立的清理失败仍彼此分离。
+
+## 原生设置与交互
+
+提供方故意省略 SDK 的 `settingSources` 选项。因此，官方 SDK 会相对于父会话 cwd 读取宿主机常规的用户、项目和本地 Claude 设置，包括原生账户状态与产品配置。提供方既不复制也不过滤这些文件，也不会创建或修改登录状态。
+
+每次 query 都设置 `persistSession: false` 并禁用 `AskUserQuestion`。提供方不设置 `canUseTool`、elicitation 或对话回调，因此无人值守交互会经 SDK 失败，而不会等待本提供方不负责的用户界面。
+
+## 能力与上下文
+
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Claude Code 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。每次运行都拥有独立的 SDK query、取消控制器、CLI 进程和不持久化的产品会话。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `env` | `{}` | 显式指定的 SDK/CLI 环境，叠加在由共享机制清除凭证后的父环境之上。 |
+| `disposeGraceMs` | `3000` | 共享进程树责任方各终止层级之间的宽限期，单位为毫秒且须为正有限值，并不得大于仓库共享的 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)；随后资源释放会等待整棵进程树退出。 |
+
+生产环境使用 `@anthropic-ai/claude-agent-sdk` 提供的 Claude Code CLI，以及宿主机原生设置与身份验证。本插件不安装另一份 CLI、不选择模型、不创建产品主目录、不执行登录，也不探测账户。具有凭证特征的环境变量会在显式 `env` 覆盖生效前被清除，因此供子进程使用的 API 密钥或 token 必须在该配置中显式提供。除非被覆盖，`ANTHROPIC_BASE_URL` 等非凭证端点变量以及 `PATH` 和 `HOME` 等普通环境变量仍会被继承。
+
+请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。正式 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_claude_code`。
+
+```yaml
+- id: subagent-claude-code
+  name: '@deepseek-ai/dsh-subagent-claude-code'
+  config:
+    env:
+      ANTHROPIC_API_KEY: !!js process.env.ANTHROPIC_API_KEY
+
+- id: tool-subagent-claude-code
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: claude-code
+    toolName: subagent_claude_code
+    enableRunInBackground: false
+    maxDepth: provider-managed
+```
+
+## 产品兼容性与证据
+
+运行时依赖精确锁定为 `@anthropic-ai/claude-agent-sdk@0.3.220`，其平台可选依赖提供 Claude Code 2.1.220。强制证据会通过无密钥回环产品路径与带密钥 DeepSeek 路径运行该官方发行版，而 Loader 组合则证明两个选择启用的产品包能够共存，且不会启动任一产品。
+
+项目所有者按身份范围授权分发官方 SDK 及每个 SDK 版本声明的官方 CLI／平台载荷。[`THIRD_PARTY_NOTICES.md`](../../../THIRD_PARTY_NOTICES.md) 会披露当前可选载荷闭包，但不会把其声明条款归类为宽松许可证；其他无关的非宽松运行时依赖仍会使第三方声明门禁失败。
+
+## 模型体验
+
+### 子任务请求
+
+#### 模型看到的内容
+
+Claude Code 子任务会在一个全新的 SDK query 中接收独立文本任务。它的工作区是父会话 cwd；其模型、系统指令、工具、权限和身份验证来自宿主机原生 Claude 设置与产品安装。
+
+#### 对 token 的影响
+
+子任务需为独立的 Claude Code 上下文和 query 承担 token 开销。子任务 token 不会进入父级上下文。
+
+#### 对 KV Cache 的影响
+
+这与父请求缓存相互独立。能否复用只取决于 Claude Code 自身的模型、指令、工具、原生设置和全新 query。
+
+### 父级工具结果（间接）
+
+#### 模型看到的内容
+
+通过 `dsh-tool-subagent`，父级模型只会看到符合严格成功条件的 Claude Code 最终答案，或者在结果未完成时看到消费方给出的原样错误。Claude Code 的推理、工具活动、中间消息、stderr、工作区差异、用量信息和产品标识符均不会复制到父会话。
+
+#### 对 token 的影响
+
+父级输入只会增加工具结果中保留的最终答案或错误内容。本提供方自身不添加父级工具 schema。
+
+#### 对 KV Cache 的影响
+
+仅追加：新的工具结果接在可复用的父请求前缀之后。
+
+## 已知限制与后续工作
+
+- **每次运行均新建一个 query 和一个进程**：不支持续接、恢复、池化、进度流或产品会话持久化。
+- **宿主设置有意保持权威**：项目和用户设置可以改变模型、工具与行为；本提供方不提供经过筛选或与宿主环境隔离的生产模式。
+- **产品安装与账户状态仍由原生机制管理**：不兼容的 SDK 载荷、配置错误或身份验证失败都会呈现为启动错误或运行错误；本插件不提供安装程序或登录流程。
+- **没有人工交互路径**：`AskUserQuestion` 被禁用，其他交互回调也不存在，因此需要新审批或输入的任务会失败而不会挂起。
+- **仅返回最终文本**：推理、中间消息、工具通信、用量信息、stderr 和工作区差异仍只保留在产品内部。
+- **没有可选的共享能力**：对于本提供方，共享服务会拒绝输出 schema、子任务角色设定、工具筛选和 harness 深度强制约束。
+- **没有按实际经过时间触发的超时或副作用回滚**：长时间运行的工作由调用方取消，且取消前已更改的文件或外部系统不会恢复原状。
diff --git a/packages/subagent/subagent-claude-code/package.json b/packages/subagent/subagent-claude-code/package.json
new file mode 100644
index 0000000000..8b25c6919c
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/package.json
@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-claude-code",
+  "description": "One-shot Claude Code subagent provider over the official Agent SDK",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "0.93.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.220",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/subagent/subagent-claude-code/src/index.ts b/packages/subagent/subagent-claude-code/src/index.ts
new file mode 100644
index 0000000000..e4d6fbac5f
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/src/index.ts
@@ -0,0 +1,107 @@
+/**
+ * Fixed Claude Code one-shot subagent provider. Every accepted run invokes
+ * the official Agent SDK in the delegating Session's workspace and places
+ * the SDK-spawned real CLI under the shared subprocess owner.
+ *
+ * @module @deepseek-ai/dsh-subagent-claude-code
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import {
+  assertPositiveFinite,
+  NO_START_CAPABILITIES,
+  resolveChildCwd,
+  type ResolvedSubagentStartRequest,
+  type SubagentCapabilities,
+  type SubagentProvider,
+} from '@deepseek-ai/dsh-subagent'
+import {
+  DEFAULT_DISPOSE_GRACE_MS,
+  startClaudeCodeRun,
+  type ClaudeCodeRunSpec,
+} from './run.ts'
+
+export const name = 'subagent-claude-code'
+export const inject = ['subagents', 'subprocess']
+
+/* jscpd:ignore-start -- sibling product providers intentionally expose the
+ * same two deployment-owned fields without adding a shared config owner. */
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for Claude Code process-tree termination. */
+  disposeGraceMs?: number
+}
+
+export const Config: z<Config> = z.object({
+  env: z.dict(z.string()).default({}),
+  disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS),
+})
+
+type ResolvedConfig = Required<Config>
+/* jscpd:ignore-end */
+
+/* jscpd:ignore-start -- Cordis registration and shared-seam plumbing mirror
+ * the Codex sibling; each product's lifecycle remains package-private. */
+class ClaudeCodeProvider implements SubagentProvider {
+  readonly name = 'claude-code'
+  readonly capabilities: SubagentCapabilities = NO_START_CAPABILITIES
+  readonly inheritsParentContext = false
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly config: ResolvedConfig,
+  ) {}
+
+  start(request: ResolvedSubagentStartRequest) {
+    const parentCwd = request.parent.session.header.cwd
+    if (parentCwd === undefined) {
+      throw new Error(
+        'subagent-claude-code: no working directory for the child — delegate from a parent session that has one',
+      )
+    }
+    const spec: ClaudeCodeRunSpec = {
+      cwd: resolveChildCwd(
+        'subagent-claude-code',
+        undefined,
+        parentCwd,
+      ),
+      env: this.config.env,
+      disposeGraceMs: this.config.disposeGraceMs,
+      spawn: spawnSpec => this.ctx.subprocess.spawn(spawnSpec),
+      onError: (error, stopReason) => {
+        this.ctx.logger.warn(
+          `subagent-claude-code: child run failed (${stopReason}): ${error.message}`,
+        )
+      },
+    }
+    return startClaudeCodeRun(request, spec)
+  }
+}
+
+/**
+ * Register the fixed `claude-code` provider.
+ * @param ctx - context carrying shared subagent and subprocess services.
+ * @param config - explicit child environment and disposal grace.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const resolved = config as ResolvedConfig
+  assertPositiveFinite(
+    'subagent-claude-code',
+    'disposeGraceMs',
+    resolved.disposeGraceMs,
+  )
+  if (resolved.disposeGraceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(
+      `subagent-claude-code: disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`,
+    )
+  }
+  ctx.subagents.registerProvider(new ClaudeCodeProvider(ctx, resolved))
+}
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-claude-code/src/invariant.ts b/packages/subagent/subagent-claude-code/src/invariant.ts
new file mode 100644
index 0000000000..462692590f
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/src/invariant.ts
@@ -0,0 +1,31 @@
+/**
+ * Package-owned invariant companion for
+ * `@deepseek-ai/dsh-subagent-claude-code`.
+ * @module @deepseek-ai/dsh-subagent-claude-code/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-claude-code'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-claude-code-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: lifecycle pairing belongs to the shared subagent
+ * service and process-tree ownership belongs to the subprocess service.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - plugin context carrying the invariant registry.
+ * @returns the installed registration's disposer.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-claude-code/src/process.ts b/packages/subagent/subagent-claude-code/src/process.ts
new file mode 100644
index 0000000000..32a545bf08
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/src/process.ts
@@ -0,0 +1,156 @@
+/**
+ * Projection from the shared managed-process handle to the official Claude
+ * Agent SDK's custom-spawn process interface.
+ *
+ * @module @deepseek-ai/dsh-subagent-claude-code/process
+ */
+
+import { EventEmitter } from 'node:events'
+import type {
+  SpawnedProcess,
+  SpawnOptions,
+} from '@anthropic-ai/claude-agent-sdk'
+import {
+  scrubbedParentEnv,
+  type SubprocessHandle,
+  type SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+
+function thrown(value: unknown): Error {
+  /* v8 ignore next -- the subprocess seam rejects with Error. */
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+/**
+ * Encode the SDK's complete child environment as a subprocess overlay.
+ * @param env - SDK-composed child environment after its removals and replacements.
+ * @returns explicit values plus tombstones for surviving ambient names the SDK removed.
+ */
+export function sdkEnvironmentOverlay(
+  env: SpawnOptions['env'],
+): NodeJS.ProcessEnv {
+  const overlay: NodeJS.ProcessEnv = { ...env }
+  for (const name of Object.keys(scrubbedParentEnv())) {
+    if (!(name in env)) overlay[name] = undefined
+  }
+  return overlay
+}
+
+/**
+ * Translate one official SDK spawn request to the shared process owner.
+ * @param options - command, arguments, workspace, environment, and forwarded signal from the SDK.
+ * @param graceMs - process-tree termination grace.
+ * @returns the fully explicit shared subprocess request.
+ */
+export function claudeSpawnSpec(
+  options: SpawnOptions,
+  graceMs: number,
+): SubprocessSpawnSpec {
+  if (options.cwd === undefined || options.cwd.length === 0) {
+    throw new Error('subagent-claude-code: SDK spawn request omitted its workspace')
+  }
+  return {
+    argv: [options.command, ...options.args],
+    cwd: options.cwd,
+    stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' },
+    graceMs,
+    signal: options.signal,
+    env: sdkEnvironmentOverlay(options.env),
+  }
+}
+
+/**
+ * SDK-facing view of one shared managed process. Protocol transport remains
+ * in the official SDK; this adapter only projects streams and exit events.
+ */
+export class ManagedClaudeCodeProcess implements SpawnedProcess {
+  readonly stdin
+  readonly stdout
+  private readonly events = new EventEmitter()
+  private exitCodeValue: number | null = null
+  private signalCodeValue: NodeJS.Signals | null = null
+  private killRequested = false
+
+  /**
+   * Project a managed process with piped stdin and stdout.
+   * @param child - shared handle that remains the process-tree authority.
+   */
+  constructor(private readonly child: SubprocessHandle) {
+    this.stdin = child.stdin as NonNullable<SubprocessHandle['stdin']>
+    this.stdout = child.stdout as NonNullable<SubprocessHandle['stdout']>
+    // EventEmitter gives `error` special throw semantics without a listener.
+    // The SDK attaches its listener synchronously after custom spawn returns,
+    // while this no-op also contains an already-rejected spawn handle.
+    this.events.on('error', () => {})
+    void child.done.then(
+      (outcome) => {
+        this.exitCodeValue = outcome.exitCode
+        this.signalCodeValue = outcome.signal
+        this.events.emit('exit', outcome.exitCode, outcome.signal)
+      },
+      (error: unknown) => {
+        this.events.emit('error', thrown(error))
+      },
+    )
+  }
+
+  /** Whether the SDK has requested managed tree termination. */
+  get killed(): boolean {
+    return this.killRequested
+  }
+
+  /** Direct-child exit code, or null while running or after signal exit. */
+  get exitCode(): number | null {
+    return this.exitCodeValue
+  }
+
+  /** Direct-child terminating signal, if any. */
+  get signalCode(): NodeJS.Signals | null {
+    return this.signalCodeValue
+  }
+
+  /**
+   * Route the SDK's termination request to the tree-scoped process owner.
+   * @param _signal - SDK-selected signal; the shared seam owns its escalation ladder.
+   * @returns false only after exit or a previous termination request.
+   */
+  kill(_signal: NodeJS.Signals): boolean {
+    if (
+      this.killRequested
+      || this.exitCodeValue !== null
+      || this.signalCodeValue !== null
+    ) {
+      return false
+    }
+    this.killRequested = true
+    this.child.terminate()
+    return true
+  }
+
+  /** Register a persistent process lifecycle listener. */
+  on(
+    event: 'exit' | 'error',
+    listener: ((code: number | null, signal: NodeJS.Signals | null) => void)
+      | ((error: Error) => void),
+  ): void {
+    this.events.on(event, listener)
+  }
+
+  /** Register a one-shot process lifecycle listener. */
+  once(
+    event: 'exit' | 'error',
+    listener: ((code: number | null, signal: NodeJS.Signals | null) => void)
+      | ((error: Error) => void),
+  ): void {
+    this.events.once(event, listener)
+  }
+
+  /** Remove a process lifecycle listener. */
+  off(
+    event: 'exit' | 'error',
+    listener: ((code: number | null, signal: NodeJS.Signals | null) => void)
+      | ((error: Error) => void),
+  ): void {
+    this.events.off(event, listener)
+  }
+}
diff --git a/packages/subagent/subagent-claude-code/src/run.ts b/packages/subagent/subagent-claude-code/src/run.ts
new file mode 100644
index 0000000000..d5f222b6c4
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/src/run.ts
@@ -0,0 +1,287 @@
+/**
+ * One-shot Claude Code lifecycle: invoke the official Agent SDK, place its
+ * real CLI process under the shared subprocess owner, map only strict SDK
+ * success to completion, and dispose to whole-tree quiescence.
+ *
+ * @module @deepseek-ai/dsh-subagent-claude-code/run
+ */
+
+import { randomUUID } from 'node:crypto'
+import {
+  query as officialQuery,
+  type Options,
+  type Query,
+  type SDKMessage,
+  type SDKResultMessage,
+  type SpawnOptions,
+} from '@anthropic-ai/claude-agent-sdk'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import {
+  settleRunResult,
+  subprocessRunHandle,
+  type SubagentResult,
+  type SubagentRun,
+  type SubagentStartRequest,
+  type SubagentStopReason,
+} from '@deepseek-ai/dsh-subagent'
+import {
+  scrubbedParentEnv,
+  type SubprocessHandle,
+  type SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import {
+  claudeSpawnSpec,
+  ManagedClaudeCodeProcess,
+} from './process.ts'
+
+/** Default POSIX grace between subprocess termination tiers. */
+export const DEFAULT_DISPOSE_GRACE_MS = 3_000
+
+/* jscpd:ignore-start -- sibling providers intentionally keep product-private
+ * run inputs and error normalization instead of adding a shared lifecycle owner. */
+/** Fully resolved inputs for one official Claude Agent SDK query. */
+export interface ClaudeCodeRunSpec {
+  /** Parent Session workspace supplied to the SDK and real CLI. */
+  readonly cwd: string
+  /** Explicit deployment/test environment layered after shared scrubbing. */
+  readonly env: Record<string, string>
+  /** Subprocess termination grace passed to the shared process-tree owner. */
+  readonly disposeGraceMs: number
+  /** Shared subprocess service spawn operation. */
+  readonly spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle
+  /** Diagnostic sink for a post-publication error flattened into a result. */
+  readonly onError?: (error: Error, stopReason: SubagentStopReason) => void
+}
+
+function thrown(value: unknown): Error {
+  /* v8 ignore next -- typed SDK and subprocess failures reject with Error. */
+  return value instanceof Error ? value : new Error(String(value))
+}
+/* jscpd:ignore-end */
+
+/**
+ * Validate and preserve the one-shot task before crossing the SDK boundary.
+ * @param prompt - task content accepted from the shared subagent service.
+ * @returns the exact text sequence as one SDK prompt.
+ */
+export function textTask(prompt: readonly ContentBlock[]): string {
+  if (prompt.length === 0) {
+    throw new Error('subagent-claude-code: the one-shot task must contain only text blocks')
+  }
+  const texts: string[] = []
+  for (const block of prompt) {
+    if (block.type !== 'text') {
+      throw new Error('subagent-claude-code: the one-shot task must contain only text blocks')
+    }
+    texts.push(block.text)
+  }
+  if (texts.every(text => text.trim().length === 0)) {
+    throw new Error('subagent-claude-code: the one-shot task must not be empty')
+  }
+  return texts.join('')
+}
+
+/**
+ * Strictly derive the only SDK result that can complete a shared run.
+ * @param message - an official discriminated result union.
+ * @returns exact final text for a successful, non-error result.
+ */
+export function successfulResult(message: SDKResultMessage): string {
+  if (
+    message.subtype !== 'success'
+    || message.is_error
+    || message.result.trim().length === 0
+  ) {
+    const detail = message.subtype === 'success'
+      ? 'success result was marked as an error or contained no answer'
+      : message.errors.join('; ') || message.subtype
+    throw new Error(`subagent-claude-code: Claude Code failed: ${detail}`)
+  }
+  return message.result
+}
+
+/**
+ * Consume the complete SDK stream and require one strict success plus normal
+ * iterator completion.
+ * @param query - published official SDK query.
+ * @returns the completed shared result.
+ */
+export async function consumeClaudeQuery(
+  query: AsyncIterable<SDKMessage>,
+): Promise<SubagentResult> {
+  let answer: string | undefined
+  for await (const message of query) {
+    if (message.type !== 'result') continue
+    answer = successfulResult(message)
+  }
+  if (answer === undefined) {
+    throw new Error('subagent-claude-code: Claude Code ended without a result')
+  }
+  return {
+    output: [{ type: 'text', text: answer }],
+    stopReason: 'completed',
+  }
+}
+
+/**
+ * Close the official query, terminate the managed process tree, and wait for
+ * the subprocess owner to prove it is gone.
+ * @param query - official SDK query, when creation reached that point.
+ * @param child - shared-service handle that owns the CLI process tree.
+ */
+export async function disposeClaudeCodeChild(
+  query: Pick<Query, 'close'> | undefined,
+  child: SubprocessHandle,
+): Promise<void> {
+  const failures: Error[] = []
+  try {
+    query?.close()
+  } catch (error: unknown) {
+    failures.push(thrown(error))
+  }
+
+  if (child.pid > 0) {
+    child.terminate()
+    try {
+      await child.waitForExit()
+    } catch (error: unknown) {
+      failures.push(thrown(error))
+    }
+  }
+  try {
+    await child.done
+  } catch (error: unknown) {
+    failures.push(thrown(error))
+  }
+
+  const firstFailure = failures[0]
+  if (failures.length === 1 && firstFailure !== undefined) throw firstFailure
+  if (failures.length > 1) {
+    throw new AggregateError(
+      failures,
+      'subagent-claude-code: query and process cleanup failed',
+    )
+  }
+}
+
+/**
+ * Build the fixed official SDK options for one one-shot provider run.
+ * @param spec - workspace, environment, process seam, and disposal policy.
+ * @param controller - per-run cancellation owner.
+ * @param capture - receives the real managed child synchronously from the SDK hook.
+ * @returns options that inherit native settings while disabling persistence and user questions.
+ */
+export function claudeQueryOptions(
+  spec: ClaudeCodeRunSpec,
+  controller: AbortController,
+  capture: (child: SubprocessHandle) => void,
+): Options {
+  return {
+    abortController: controller,
+    cwd: spec.cwd,
+    env: { ...scrubbedParentEnv(), ...spec.env },
+    persistSession: false,
+    disallowedTools: ['AskUserQuestion'],
+    spawnClaudeCodeProcess: (options: SpawnOptions) => {
+      const child = spec.spawn(claudeSpawnSpec(options, spec.disposeGraceMs))
+      capture(child)
+      return new ManagedClaudeCodeProcess(child)
+    },
+  }
+}
+
+/**
+ * Start one official Claude Agent SDK query and publish its one-shot run.
+ * @param request - resolved shared subagent request.
+ * @param spec - workspace, environment, process seam, and diagnostic policy.
+ * @returns the published run after both Query and real CLI handle exist.
+ */
+export async function startClaudeCodeRun(
+  request: SubagentStartRequest,
+  spec: ClaudeCodeRunSpec,
+): Promise<SubagentRun> {
+  const prompt = textTask(request.prompt)
+  if (request.signal.aborted) {
+    throw new Error('subagent-claude-code: request was aborted before SDK startup')
+  }
+
+  const controller = new AbortController()
+  const requestCancel = (): void => {
+    if (!controller.signal.aborted) {
+      controller.abort(new Error('subagent-claude-code: run cancelled locally'))
+    }
+  }
+  const onAbort = (): void => { requestCancel() }
+  request.signal.addEventListener('abort', onAbort, { once: true })
+
+  let child: SubprocessHandle | undefined
+  let query: Query | undefined
+  try {
+    query = officialQuery({
+      prompt,
+      options: claudeQueryOptions(spec, controller, (captured) => {
+        child = captured
+      }),
+    })
+    if (child === undefined || child.pid <= 0) {
+      throw new Error(
+        'subagent-claude-code: official SDK did not publish a controllable Claude Code process',
+      )
+    }
+    if (controller.signal.aborted) {
+      throw new Error('subagent-claude-code: request was aborted before SDK startup')
+    }
+  } catch (error: unknown) {
+    request.signal.removeEventListener('abort', onAbort)
+    const cancelledBeforeCleanup = controller.signal.aborted
+    requestCancel()
+    if (child !== undefined) {
+      try {
+        await disposeClaudeCodeChild(query, child)
+      } catch (disposeError: unknown) {
+        throw new AggregateError(
+          [thrown(error), thrown(disposeError)],
+          'subagent-claude-code: startup failed and CLI cleanup also failed',
+        )
+      }
+    } else if (query !== undefined) {
+      try {
+        query.close()
+      } catch (disposeError: unknown) {
+        throw new AggregateError(
+          [thrown(error), thrown(disposeError)],
+          'subagent-claude-code: startup failed and query cleanup also failed',
+        )
+      }
+    }
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- the request can abort while process cleanup is awaited.
+    if (cancelledBeforeCleanup || request.signal.aborted) {
+      throw new Error('subagent-claude-code: request was aborted before SDK startup')
+    }
+    throw thrown(error)
+  }
+
+  const publishedQuery = query
+  const publishedChild = child
+  const result = settleRunResult({
+    attempt: () => consumeClaudeQuery(publishedQuery),
+    collectOutput: () => [],
+    cancelled: () => controller.signal.aborted,
+    onError: spec.onError,
+    signal: request.signal,
+    onAbort,
+  })
+
+  return subprocessRunHandle({
+    id: SessionId(randomUUID()),
+    result,
+    signal: request.signal,
+    onAbort,
+    requestCancel,
+    teardown: () => disposeClaudeCodeChild(
+      publishedQuery,
+      publishedChild,
+    ),
+  })
+}
diff --git a/packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts b/packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts
new file mode 100644
index 0000000000..51a2ea0025
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts
@@ -0,0 +1,72 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  LOADER_SMOKE_TEST_TIMEOUT_MS,
+  runLoaderSmoke,
+} from '@deepseek-ai/dsh-loader-smoke'
+
+const fixtureDir = fileURLToPath(new URL(
+  '../../../../examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/',
+  import.meta.url,
+))
+const driver = join(fixtureDir, 'driver.ts')
+const configPath = join(fixtureDir, 'cordis.yml')
+const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+describe('product-provider public Loader composition', () => {
+  it('loads both opt-in packages and foreground tools without starting either product', async () => {
+    const { stdout, stderr } = await runLoaderSmoke({
+      label: 'product-provider Loader composition',
+      tempDirPrefix: 'dsh-product-provider-loader-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      env: {
+        // Loading either optional package must not probe or start its binary.
+        PATH: '',
+      },
+    })
+
+    expect(stderr).toBe('')
+    expect(JSON.parse(stdout)).toEqual({
+      registeredProviders: ['codex', 'claude-code'],
+      providers: [
+        {
+          name: 'codex',
+          capabilities: {
+            outputSchema: false,
+            depthLimit: false,
+            toolFilter: false,
+            persona: false,
+          },
+          inheritsParentContext: false,
+        },
+        {
+          name: 'claude-code',
+          capabilities: {
+            outputSchema: false,
+            depthLimit: false,
+            toolFilter: false,
+            persona: false,
+          },
+          inheritsParentContext: false,
+        },
+      ],
+      tools: [
+        {
+          name: 'subagent_codex',
+          parameterNames: ['description', 'prompt'],
+          required: ['description', 'prompt'],
+        },
+        {
+          name: 'subagent_claude_code',
+          parameterNames: ['description', 'prompt'],
+          required: ['description', 'prompt'],
+        },
+      ],
+      starts: 0,
+    })
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
diff --git a/packages/subagent/subagent-claude-code/tests/messages-fixture.ts b/packages/subagent/subagent-claude-code/tests/messages-fixture.ts
new file mode 100644
index 0000000000..d8a04cf953
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/tests/messages-fixture.ts
@@ -0,0 +1,150 @@
+import { createServer, type IncomingHttpHeaders, type ServerResponse } from 'node:http'
+
+/** One deterministic response emitted by the package-private Messages server. */
+export type MessagesBehavior =
+  | { readonly kind: 'complete'; readonly text: string }
+  | { readonly kind: 'hold' }
+
+/** One recorded Anthropic Messages request. */
+interface RecordedMessagesRequest {
+  readonly method: string
+  readonly path: string
+  readonly headers: IncomingHttpHeaders
+  readonly body: Record<string, unknown>
+}
+
+/** Running package-private Anthropic Messages fixture. */
+export interface MessagesFixture {
+  readonly baseUrl: string
+  readonly requests: RecordedMessagesRequest[]
+  readonly requestStarted: Promise<void>
+  close(): Promise<void>
+}
+
+function event(
+  response: ServerResponse,
+  type: string,
+  payload: Record<string, unknown>,
+): void {
+  response.write(`event: ${type}\ndata: ${JSON.stringify(payload)}\n\n`)
+}
+
+function complete(
+  response: ServerResponse,
+  body: Record<string, unknown>,
+  text: string,
+): void {
+  const model = typeof body.model === 'string' ? body.model : 'fixture-model'
+  response.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache',
+    connection: 'keep-alive',
+  })
+  event(response, 'message_start', {
+    type: 'message_start',
+    message: {
+      id: 'msg_dsh_fixture',
+      type: 'message',
+      role: 'assistant',
+      model,
+      content: [],
+      stop_reason: null,
+      stop_sequence: null,
+      usage: {
+        input_tokens: 7,
+        output_tokens: 0,
+        cache_creation_input_tokens: 0,
+        cache_read_input_tokens: 0,
+      },
+    },
+  })
+  event(response, 'content_block_start', {
+    type: 'content_block_start',
+    index: 0,
+    content_block: { type: 'text', text: '' },
+  })
+  event(response, 'content_block_delta', {
+    type: 'content_block_delta',
+    index: 0,
+    delta: { type: 'text_delta', text },
+  })
+  event(response, 'content_block_stop', {
+    type: 'content_block_stop',
+    index: 0,
+  })
+  event(response, 'message_delta', {
+    type: 'message_delta',
+    delta: { stop_reason: 'end_turn', stop_sequence: null },
+    usage: { output_tokens: 1 },
+  })
+  event(response, 'message_stop', { type: 'message_stop' })
+  response.end()
+}
+
+/**
+ * Start a loopback-only Anthropic Messages SSE fixture.
+ * @param behavior - the single response behavior for this fixture.
+ * @returns the bound server and its recorded requests.
+ */
+export async function startMessagesFixture(
+  behavior: MessagesBehavior,
+): Promise<MessagesFixture> {
+  const requests: RecordedMessagesRequest[] = []
+  let requestStartedResolve!: () => void
+  const requestStarted = new Promise<void>((resolve) => {
+    requestStartedResolve = resolve
+  })
+  const server = createServer((request, response) => {
+    const chunks: Buffer[] = []
+    request.on('data', (chunk: Buffer) => { chunks.push(chunk) })
+    request.on('end', () => {
+      const path = request.url ?? ''
+      if (path !== '/v1/messages' && !path.startsWith('/v1/messages?')) {
+        response.writeHead(404, { 'content-type': 'application/json' })
+        response.end(JSON.stringify({
+          type: 'error',
+          error: { type: 'not_found_error', message: `unexpected path ${path}` },
+        }))
+        return
+      }
+      const text = Buffer.concat(chunks).toString('utf8')
+      const body = JSON.parse(text) as Record<string, unknown>
+      requests.push({
+        method: request.method ?? '',
+        path,
+        headers: request.headers,
+        body,
+      })
+      requestStartedResolve()
+      if (behavior.kind === 'complete') {
+        complete(response, body, behavior.text)
+      }
+      // A hold deliberately leaves the response pending until client abort.
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject)
+      resolve()
+    })
+  })
+  const address = server.address()
+  if (address === null || typeof address === 'string') {
+    throw new Error('Messages fixture did not bind a TCP port')
+  }
+  return {
+    baseUrl: `http://127.0.0.1:${address.port}`,
+    requests,
+    requestStarted,
+    async close(): Promise<void> {
+      server.closeAllConnections()
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error !== undefined) reject(error)
+          else resolve()
+        })
+      })
+    },
+  }
+}
diff --git a/packages/subagent/subagent-claude-code/tests/real-deepseek.e2e.ts b/packages/subagent/subagent-claude-code/tests/real-deepseek.e2e.ts
new file mode 100644
index 0000000000..806181ad13
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/tests/real-deepseek.e2e.ts
@@ -0,0 +1,160 @@
+import { execFile } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import * as claudeCode from '../src/index.ts'
+
+const execFileAsync = promisify(execFile)
+const OFFICIAL_DEEPSEEK_BASE_URL = 'https://api.deepseek.com'
+const sdkRoot = dirname(fileURLToPath(
+  import.meta.resolve('@anthropic-ai/claude-agent-sdk'),
+))
+const sdkPackage = JSON.parse(readFileSync(
+  join(sdkRoot, 'package.json'),
+  'utf8',
+)) as {
+  version: string
+  claudeCodeVersion: string
+  optionalDependencies: Record<string, string>
+}
+const platformPackage = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}`
+const platformRoot = resolve(sdkRoot, '..', platformPackage.split('/')[1]!)
+const claudeBin = join(
+  platformRoot,
+  process.platform === 'win32' ? 'claude.exe' : 'claude',
+)
+
+const roots: string[] = []
+const contexts: Context[] = []
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function deepSeekBaseUrl(): string {
+  const configured = (process.env.DEEPSEEK_BASE_URL ?? OFFICIAL_DEEPSEEK_BASE_URL)
+    .replace(/\/+$/, '')
+  if (configured !== OFFICIAL_DEEPSEEK_BASE_URL) {
+    throw new Error('Claude Code DeepSeek e2e requires the official DeepSeek base URL')
+  }
+  return configured
+}
+
+async function expectQuiescent(handles: readonly SubprocessHandle[]): Promise<void> {
+  expect(handles.length).toBeGreaterThan(0)
+  for (const handle of handles) {
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toHaveProperty('exitCode')
+  }
+}
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)(
+  'Claude Code provider with real DeepSeek API',
+  () => {
+    it('returns one unique nonce through the production provider and real SDK/CLI', async () => {
+      const apiKey = process.env.DEEPSEEK_API_KEY
+      if (apiKey === undefined) throw new Error('e2e ran without DEEPSEEK_API_KEY')
+      const root = mkdtempSync(join(tmpdir(), 'dsh-claude-deepseek-e2e-'))
+      roots.push(root)
+      const workspace = join(root, 'workspace')
+      const claudeConfig = join(root, 'claude-config')
+      const xdgConfig = join(root, 'xdg-config')
+      const xdgCache = join(root, 'xdg-cache')
+      const xdgData = join(root, 'xdg-data')
+      const xdgState = join(root, 'xdg-state')
+      for (const directory of [
+        workspace,
+        claudeConfig,
+        xdgConfig,
+        xdgCache,
+        xdgData,
+        xdgState,
+      ]) mkdirSync(directory)
+
+      const env = {
+        ANTHROPIC_AUTH_TOKEN: apiKey,
+        ANTHROPIC_BASE_URL: `${deepSeekBaseUrl()}/anthropic`,
+        ANTHROPIC_MODEL: 'deepseek-v4-pro[1m]',
+        ANTHROPIC_DEFAULT_OPUS_MODEL: 'deepseek-v4-pro[1m]',
+        ANTHROPIC_DEFAULT_SONNET_MODEL: 'deepseek-v4-pro[1m]',
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: 'deepseek-v4-flash',
+        CLAUDE_CODE_SUBAGENT_MODEL: 'deepseek-v4-flash',
+        CLAUDE_CODE_EFFORT_LEVEL: 'max',
+        CLAUDE_CONFIG_DIR: claudeConfig,
+        HOME: root,
+        XDG_CONFIG_HOME: xdgConfig,
+        XDG_CACHE_HOME: xdgCache,
+        XDG_DATA_HOME: xdgData,
+        XDG_STATE_HOME: xdgState,
+        CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+        CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: '1',
+        DISABLE_TELEMETRY: '1',
+        DISABLE_ERROR_REPORTING: '1',
+        HTTP_PROXY: '',
+        HTTPS_PROXY: '',
+        ALL_PROXY: '',
+        NO_PROXY: '127.0.0.1,localhost',
+      }
+      const ctx = new Context()
+      contexts.push(ctx)
+      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
+      const handles: SubprocessHandle[] = []
+      const spawn = ctx.subprocess.spawn.bind(ctx.subprocess)
+      vi.spyOn(ctx.subprocess, 'spawn').mockImplementation((spec) => {
+        const handle = spawn(spec)
+        handles.push(handle)
+        return handle
+      })
+      await ctx.plugin(claudeCode, { env, disposeGraceMs: 3_000 })
+
+      expect(sdkPackage.version).toBe('0.3.220')
+      expect(sdkPackage.claudeCodeVersion).toBe('2.1.220')
+      expect(sdkPackage.optionalDependencies[platformPackage]).toBe('0.3.220')
+      const version = await execFileAsync(claudeBin, ['--version'], {
+        env: { ...process.env, ...env },
+      })
+      expect(version.stdout.trim()).toBe('2.1.220 (Claude Code)')
+
+      const nonce = `DSH_CLAUDE_DEEPSEEK_${randomUUID()}`
+      const parent = {
+        id: 'deepseek-e2e-parent',
+        session: { header: { cwd: workspace } },
+      } as unknown as Agent
+      const run = await ctx.subagents.start('claude-code', {
+        prompt: [{
+          type: 'text',
+          text: `Reply with exactly ${nonce} and nothing else. Do not use tools.`,
+        }],
+        parent,
+        signal: new AbortController().signal,
+      })
+      const result = await run.result
+      await run.dispose()
+
+      expect(result.stopReason).toBe('completed')
+      const text = result.output
+        .filter(block => block.type === 'text')
+        .map(block => block.text)
+        .join('')
+        .trim()
+      expect(text).toBe(nonce)
+      await expectQuiescent(handles)
+    }, 180_000)
+  },
+)
diff --git a/packages/subagent/subagent-claude-code/tests/real-product.spec.ts b/packages/subagent/subagent-claude-code/tests/real-product.spec.ts
new file mode 100644
index 0000000000..f76b4038f6
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/tests/real-product.spec.ts
@@ -0,0 +1,272 @@
+import { execFile } from 'node:child_process'
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import type {
+  Query,
+  SDKMessage,
+  SDKSystemMessage,
+} from '@anthropic-ai/claude-agent-sdk'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import * as claudeCode from '../src/index.ts'
+import {
+  startMessagesFixture,
+  type MessagesBehavior,
+  type MessagesFixture,
+} from './messages-fixture.ts'
+
+const observedSdkMessages = vi.hoisted((): SDKMessage[] => [])
+
+vi.mock('@anthropic-ai/claude-agent-sdk', async (importOriginal) => {
+  const actual = await importOriginal<
+    typeof import('@anthropic-ai/claude-agent-sdk')
+  >()
+  return {
+    ...actual,
+    query(options: Parameters<typeof actual.query>[0]): Query {
+      const query = actual.query(options)
+      // Observe the real SDK stream without replacing its protocol or CLI.
+      return new Proxy(query, {
+        get(target, property) {
+          if (property === Symbol.asyncIterator) {
+            return async function* (): AsyncGenerator<SDKMessage, void> {
+              for await (const message of target) {
+                observedSdkMessages.push(message)
+                yield message
+              }
+            }
+          }
+          const value: unknown = Reflect.get(target, property, target)
+          if (typeof value === 'function') {
+            const method = value as (...args: unknown[]) => unknown
+            return method.bind(target)
+          }
+          return value
+        },
+      })
+    },
+  }
+})
+
+const execFileAsync = promisify(execFile)
+const sdkRoot = dirname(fileURLToPath(
+  import.meta.resolve('@anthropic-ai/claude-agent-sdk'),
+))
+const sdkPackage = JSON.parse(readFileSync(
+  join(sdkRoot, 'package.json'),
+  'utf8',
+)) as {
+  version: string
+  claudeCodeVersion: string
+  optionalDependencies: Record<string, string>
+}
+const platformPackage = `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}`
+const platformRoot = resolve(sdkRoot, '..', platformPackage.split('/')[1]!)
+const claudeBin = join(
+  platformRoot,
+  process.platform === 'win32' ? 'claude.exe' : 'claude',
+)
+const settingsModel = 'dsh-settings-inheritance-marker'
+const fakeKey = 'dsh-fake-anthropic-key'
+
+const roots: string[] = []
+const fixtures: MessagesFixture[] = []
+const contexts: Context[] = []
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+  await Promise.all(fixtures.splice(0).map(fixture => fixture.close()))
+  for (const root of roots.splice(0)) {
+    rmSync(root, { recursive: true, force: true })
+  }
+  observedSdkMessages.length = 0
+})
+
+interface RealHarness {
+  readonly ctx: Context
+  readonly handles: SubprocessHandle[]
+  readonly parent: Agent
+  readonly workspace: string
+  readonly env: Record<string, string>
+}
+
+async function realHarness(behavior: MessagesBehavior): Promise<{
+  readonly harness: RealHarness
+  readonly fixture: MessagesFixture
+}> {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-claude-code-real-'))
+  roots.push(root)
+  const workspace = join(root, 'workspace')
+  const claudeConfig = join(root, 'claude-config')
+  const xdgConfig = join(root, 'xdg')
+  mkdirSync(workspace)
+  mkdirSync(claudeConfig)
+  mkdirSync(xdgConfig)
+  writeFileSync(
+    join(claudeConfig, 'settings.json'),
+    `${JSON.stringify({ model: settingsModel }, null, 2)}\n`,
+  )
+  const fixture = await startMessagesFixture(behavior)
+  fixtures.push(fixture)
+  const env = {
+    ANTHROPIC_API_KEY: fakeKey,
+    ANTHROPIC_BASE_URL: fixture.baseUrl,
+    CLAUDE_CONFIG_DIR: claudeConfig,
+    HOME: root,
+    XDG_CONFIG_HOME: xdgConfig,
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+    CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: '1',
+    DISABLE_TELEMETRY: '1',
+    DISABLE_ERROR_REPORTING: '1',
+    HTTP_PROXY: '',
+    HTTPS_PROXY: '',
+    ALL_PROXY: '',
+    NO_PROXY: '127.0.0.1,localhost',
+  }
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(LocalSubprocessService)
+  const handles: SubprocessHandle[] = []
+  const spawn = ctx.subprocess.spawn.bind(ctx.subprocess)
+  vi.spyOn(ctx.subprocess, 'spawn').mockImplementation((spec) => {
+    const handle = spawn(spec)
+    handles.push(handle)
+    return handle
+  })
+  await ctx.plugin(claudeCode, { env, disposeGraceMs: 3_000 })
+  const parent = {
+    id: 'real-parent',
+    session: { header: { cwd: workspace } },
+  } as unknown as Agent
+  return {
+    harness: { ctx, handles, parent, workspace, env },
+    fixture,
+  }
+}
+
+async function expectQuiescent(
+  handles: readonly SubprocessHandle[],
+): Promise<void> {
+  expect(handles.length).toBeGreaterThan(0)
+  for (const handle of handles) {
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    const outcome = await handle.done
+    expect(outcome).toHaveProperty('exitCode')
+    expect(outcome).toHaveProperty('signal')
+  }
+}
+
+function startRequest(
+  harness: RealHarness,
+  prompt: string,
+  signal = new AbortController().signal,
+) {
+  return harness.ctx.subagents.start('claude-code', {
+    prompt: [{ type: 'text', text: prompt }],
+    parent: harness.parent,
+    signal,
+  })
+}
+
+describe('real Claude Agent SDK 0.3.220 and Claude Code 2.1.220', {
+  timeout: 60_000,
+}, () => {
+  it('inherits host settings and sends the exact task and fake key to local Messages', async () => {
+    const sentinel = 'REAL_CLAUDE_CODE_SENTINEL_2_1_220'
+    const task = 'Return the fixture sentinel exactly.'
+    const { harness, fixture } = await realHarness({
+      kind: 'complete',
+      text: sentinel,
+    })
+    expect(sdkPackage.version).toBe('0.3.220')
+    expect(sdkPackage.claudeCodeVersion).toBe('2.1.220')
+    expect(sdkPackage.optionalDependencies[platformPackage]).toBe('0.3.220')
+    const version = await execFileAsync(claudeBin, ['--version'], {
+      env: { ...process.env, ...harness.env },
+    })
+    expect(version.stdout.trim()).toBe('2.1.220 (Claude Code)')
+
+    const run = await startRequest(harness, task)
+    await expect(run.result).resolves.toEqual({
+      output: [{ type: 'text', text: sentinel }],
+      stopReason: 'completed',
+    })
+    await run.dispose()
+
+    const initMessage = observedSdkMessages.find(
+      (message): message is SDKSystemMessage =>
+        message.type === 'system' && message.subtype === 'init',
+    )
+    expect(initMessage?.claude_code_version).toBe('2.1.220')
+
+    expect(fixture.requests).toHaveLength(1)
+    const recorded = fixture.requests[0]!
+    expect(recorded.method).toBe('POST')
+    expect(recorded.path).toMatch(/^\/v1\/messages(?:\?.*)?$/)
+    expect(recorded.headers['x-api-key']).toBe(fakeKey)
+    expect(recorded.body.model).toBe(settingsModel)
+    expect(Array.isArray(recorded.body.messages)).toBe(true)
+    const messageTexts = (
+      recorded.body.messages as Array<{ content?: unknown }>
+    ).flatMap((message): unknown[] =>
+      Array.isArray(message.content) ? message.content as unknown[] : [])
+      .filter((block): block is { type: string; text: string } =>
+        typeof block === 'object'
+        && block !== null
+        && 'type' in block
+        && block.type === 'text'
+        && 'text' in block
+        && typeof block.text === 'string')
+      .map(block => block.text)
+    expect(messageTexts.filter(text => text.includes(task))).toEqual([task])
+    await expectQuiescent(harness.handles)
+  })
+
+  it('maps a real CLI process failure to error', async () => {
+    const { harness, fixture } = await realHarness({ kind: 'hold' })
+    const run = await startRequest(harness, 'Exercise the failure path.')
+    await fixture.requestStarted
+    expect(harness.handles).toHaveLength(1)
+    harness.handles[0]!.terminate()
+    await expect(run.result).resolves.toEqual({
+      output: [],
+      stopReason: 'error',
+    })
+    await run.dispose()
+    expect(fixture.requests).toHaveLength(1)
+    expect(fixture.requests[0]!.headers['x-api-key']).toBe(fakeKey)
+    await expectQuiescent(harness.handles)
+  })
+
+  it('settles cancellation and leaves the real SDK-spawned CLI tree quiescent', async () => {
+    const { harness, fixture } = await realHarness({ kind: 'hold' })
+    const controller = new AbortController()
+    const run = await startRequest(
+      harness,
+      'Wait for cancellation.',
+      controller.signal,
+    )
+    await fixture.requestStarted
+    controller.abort(new Error('real product cancellation'))
+    await expect(run.result).resolves.toEqual({
+      output: [],
+      stopReason: 'aborted',
+    })
+    await run.dispose()
+    await expectQuiescent(harness.handles)
+  })
+})
diff --git a/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts b/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts
new file mode 100644
index 0000000000..8c4ac1708d
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/tests/subagent-claude-code.spec.ts
@@ -0,0 +1,881 @@
+import { PassThrough } from 'node:stream'
+import type {
+  Options,
+  Query,
+  SDKMessage,
+  SDKResultMessage,
+  SpawnOptions,
+} from '@anthropic-ai/claude-agent-sdk'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type Mock,
+  vi,
+} from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import type {
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessSpawnSpec,
+} from '@deepseek-ai/dsh-subprocess'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import * as claudeCode from '../src/index.ts'
+import * as invariant from '../src/invariant.ts'
+import {
+  claudeSpawnSpec,
+  ManagedClaudeCodeProcess,
+  sdkEnvironmentOverlay,
+} from '../src/process.ts'
+import {
+  claudeQueryOptions,
+  consumeClaudeQuery,
+  disposeClaudeCodeChild,
+  startClaudeCodeRun,
+  successfulResult,
+  textTask,
+  type ClaudeCodeRunSpec,
+} from '../src/run.ts'
+
+type QueryFactory = (params: {
+  prompt: string
+  options: Options
+}) => Query
+
+const queryMock = vi.hoisted(() => vi.fn<QueryFactory>())
+
+vi.mock('@anthropic-ai/claude-agent-sdk', async importOriginal => ({
+  ...await importOriginal<typeof import('@anthropic-ai/claude-agent-sdk')>(),
+  query: queryMock,
+}))
+
+const fakeParent = {
+  id: 'parent',
+  session: { header: { cwd: process.cwd() } },
+} as unknown as Agent
+
+function request(
+  prompt: ContentBlock[] = [{ type: 'text', text: 'do the task' }],
+  signal = new AbortController().signal,
+) {
+  return { prompt, parent: fakeParent, signal }
+}
+
+async function nextTask(): Promise<void> {
+  await new Promise<void>((resolve) => { setImmediate(resolve) })
+}
+
+interface FakeChildOptions {
+  readonly pid?: number
+  readonly exitOnTerminate?: boolean
+  readonly waitForExitError?: Error
+  readonly doneError?: Error
+}
+
+interface FakeChild {
+  readonly handle: SubprocessHandle
+  readonly stdin: PassThrough
+  readonly stdout: PassThrough
+  readonly settle: (outcome?: SubprocessOutcome) => void
+  readonly fail: (error: Error) => void
+  readonly terminate: Mock<SubprocessHandle['terminate']>
+  readonly waitForExit: Mock<SubprocessHandle['waitForExit']>
+}
+
+function fakeChild(options: FakeChildOptions = {}): FakeChild {
+  const stdin = new PassThrough()
+  const stdout = new PassThrough()
+  let exited = false
+  let resolveDone!: (outcome: SubprocessOutcome) => void
+  let rejectDone!: (error: Error) => void
+  const done = new Promise<SubprocessOutcome>((resolve, reject) => {
+    resolveDone = resolve
+    rejectDone = reject
+  })
+  // Individual tests deliberately exercise rejected and still-pending handles.
+  void done.catch(() => {})
+  const settle = (
+    outcome: SubprocessOutcome = { exitCode: 0, signal: null },
+  ): void => {
+    if (exited) return
+    exited = true
+    resolveDone(outcome)
+  }
+  const fail = (error: Error): void => {
+    if (exited) return
+    exited = true
+    rejectDone(error)
+  }
+  if (options.doneError !== undefined) fail(options.doneError)
+  const terminate = vi.fn<SubprocessHandle['terminate']>(() => {
+    if (options.exitOnTerminate !== false) settle()
+  })
+  const waitForExit = vi.fn<SubprocessHandle['waitForExit']>(async (signal?: AbortSignal): Promise<boolean> => {
+    if (options.waitForExitError !== undefined) {
+      throw options.waitForExitError
+    }
+    if (exited) return true
+    if (signal === undefined) {
+      await done.catch(() => {})
+      return true
+    }
+    return await new Promise<boolean>((resolve) => {
+      const onAbort = (): void => { resolve(false) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void done.then(
+        () => {
+          signal.removeEventListener('abort', onAbort)
+          resolve(true)
+        },
+        () => {
+          signal.removeEventListener('abort', onAbort)
+          resolve(true)
+        },
+      )
+    })
+  })
+  const handle: SubprocessHandle = {
+    pid: options.pid ?? 1234,
+    stdin,
+    stdout,
+    stderr: undefined,
+    collected: {},
+    done,
+    terminate,
+    waitForExit,
+  }
+  return {
+    handle,
+    stdin,
+    stdout,
+    settle,
+    fail,
+    terminate,
+    waitForExit,
+  }
+}
+
+function success(
+  result = 'answer',
+  isError = false,
+): SDKResultMessage {
+  return {
+    type: 'result',
+    subtype: 'success',
+    is_error: isError,
+    result,
+  } as SDKResultMessage
+}
+
+type ErrorSubtype = Exclude<SDKResultMessage['subtype'], 'success'>
+
+function failure(
+  subtype: ErrorSubtype,
+  errors: string[] = ['fixture failure'],
+): SDKResultMessage {
+  return {
+    type: 'result',
+    subtype,
+    is_error: true,
+    errors,
+  } as SDKResultMessage
+}
+
+function queryFrom(
+  messages: readonly SDKMessage[],
+  after?: Error,
+  close = vi.fn(),
+): Query {
+  async function* stream(): AsyncGenerator<SDKMessage, void> {
+    for (const message of messages) yield message
+    if (after !== undefined) throw after
+  }
+  return Object.assign(stream(), { close }) as unknown as Query
+}
+
+function waitingQuery(signal: AbortSignal, close = vi.fn()): Query {
+  async function* stream(): AsyncGenerator<SDKMessage, void> {
+    await new Promise<never>((_resolve, reject) => {
+      const fail = (): void => {
+        reject(signal.reason instanceof Error
+          ? signal.reason
+          : new Error(String(signal.reason)))
+      }
+      if (signal.aborted) fail()
+      else signal.addEventListener('abort', fail, { once: true })
+    })
+  }
+  return Object.assign(stream(), { close }) as unknown as Query
+}
+
+function sdkSpawnOptions(
+  overrides: Partial<SpawnOptions> = {},
+): SpawnOptions {
+  return {
+    command: '/sdk/claude',
+    args: ['--output-format', 'stream-json'],
+    cwd: '/workspace',
+    env: { PATH: '/bin', OMITTED: undefined },
+    signal: new AbortController().signal,
+    ...overrides,
+  }
+}
+
+interface FakeRun {
+  readonly child: FakeChild
+  readonly close: ReturnType<typeof vi.fn>
+  readonly spawnSpecs: SubprocessSpawnSpec[]
+  readonly options: Options[]
+  readonly spec: ClaudeCodeRunSpec
+}
+
+function fakeRun(
+  messages: readonly SDKMessage[] = [success()],
+  after?: Error,
+  child = fakeChild(),
+): FakeRun {
+  const close = vi.fn()
+  const query = queryFrom(messages, after, close)
+  const spawnSpecs: SubprocessSpawnSpec[] = []
+  const options: FakeRun['options'] = []
+  const spec: ClaudeCodeRunSpec = {
+    cwd: '/workspace',
+    env: { ANTHROPIC_API_KEY: 'fake-key' },
+    disposeGraceMs: 5,
+    spawn: (spawnSpec) => {
+      spawnSpecs.push(spawnSpec)
+      return child.handle
+    },
+  }
+  queryMock.mockImplementation((params) => {
+    options.push(params.options)
+    params.options.spawnClaudeCodeProcess!(sdkSpawnOptions())
+    return query
+  })
+  return { child, close, spawnSpecs, options, spec }
+}
+
+beforeEach(() => {
+  queryMock.mockImplementation(({ options }) => {
+    options.spawnClaudeCodeProcess!(sdkSpawnOptions({
+      cwd: options.cwd!,
+      env: options.env!,
+      signal: options.abortController!.signal,
+    }))
+    return queryFrom([])
+  })
+})
+
+afterEach(() => {
+  queryMock.mockReset()
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+})
+
+describe('task admission and package contracts', () => {
+  it('preserves text sequences and rejects empty, blank, and non-text tasks', () => {
+    expect(textTask([
+      { type: 'text', text: 'one' },
+      { type: 'text', text: 'two' },
+    ])).toBe('onetwo')
+    expect(() => textTask([])).toThrow('only text blocks')
+    expect(() => textTask([{ type: 'reasoning', text: 'hidden' }]))
+      .toThrow('only text blocks')
+    expect(() => textTask([{ type: 'text', text: ' \n ' }]))
+      .toThrow('must not be empty')
+  })
+
+  it('registers one fixed descriptor, validates config, and unregisters on HMR', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
+    const fiber = await ctx.plugin(claudeCode, {})
+    expect(ctx.subagents.getProvider('claude-code')).toMatchObject({
+      name: 'claude-code',
+      capabilities: {
+        outputSchema: false,
+        depthLimit: false,
+        toolFilter: false,
+        persona: false,
+      },
+      inheritsParentContext: false,
+    })
+    expect(ctx.subagents.list()).toEqual(['claude-code'])
+    await fiber.dispose()
+    expect(ctx.subagents.list()).toEqual([])
+
+    for (const disposeGraceMs of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      await expect(ctx.plugin(claudeCode, { disposeGraceMs }))
+        .rejects.toThrow('disposeGraceMs must be a positive finite number')
+    }
+    await expect(ctx.plugin(claudeCode, {
+      disposeGraceMs: MAX_TIMER_DELAY_MS + 1,
+    })).rejects.toThrow(
+      `disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`,
+    )
+    await ctx.fiber.dispose()
+  })
+
+  it('starts through the registered provider with its resolved config and diagnostics', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
+    const child = fakeChild()
+    const spawn = vi.spyOn(ctx.subprocess, 'spawn')
+      .mockImplementation(() => child.handle)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => {})
+    await ctx.plugin(claudeCode, {
+      env: {
+        ANTHROPIC_API_KEY: 'provider-fake-key',
+        CLAUDE_CONFIG_DIR: '/private/tmp/dsh-claude-code-unit-config',
+        HOME: '/private/tmp/dsh-claude-code-unit-home',
+      },
+      disposeGraceMs: 29,
+    })
+
+    await expect(ctx.subagents.start('claude-code', {
+      ...request(),
+      parent: {
+        id: 'parent-without-cwd',
+        session: { header: {} },
+      } as unknown as Agent,
+    })).rejects.toThrow(
+      'subagent-claude-code: no working directory for the child — delegate from a parent session that has one',
+    )
+    expect(queryMock).not.toHaveBeenCalled()
+
+    const run = await ctx.subagents.start('claude-code', request())
+    child.settle({ exitCode: 9, signal: null })
+    child.stdout.end()
+    await expect(run.result).resolves.toEqual({
+      output: [],
+      stopReason: 'error',
+    })
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining(
+      'subagent-claude-code: child run failed (error):',
+    ))
+    expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
+      cwd: process.cwd(),
+      graceMs: 29,
+    }))
+    expect(spawn.mock.calls[0]?.[0].env).toMatchObject({
+      ANTHROPIC_API_KEY: 'provider-fake-key',
+    })
+    await run.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps the Loader namespace shape and package-owned empty invariant', async () => {
+    expect('default' in claudeCode).toBe(false)
+    expect(claudeCode.name).toBe('subagent-claude-code')
+    expect(claudeCode.inject).toEqual(['subagents', 'subprocess'])
+    const loader = Object.create(Loader.prototype) as Loader
+    expect(loader.unwrapExports(claudeCode)).toBe(claudeCode)
+
+    const dispose = vi.fn()
+    const register = vi.fn((
+      _packageName: string,
+      _installer: InvariantInstaller,
+    ) => dispose)
+    const ctx = { invariants: { register } } as unknown as Context
+    await expect(invariant.apply(ctx)).resolves.toBe(dispose)
+    expect(register).toHaveBeenCalledWith(
+      '@deepseek-ai/dsh-subagent-claude-code',
+      expect.any(Function),
+    )
+    const install = register.mock.calls[0]![1]
+    await install(new Context(), (message) => { throw new Error(message) })
+    expect(invariant.name).toBe('subagent-claude-code-invariant')
+    expect(invariant.inject).toEqual(['invariants'])
+  })
+})
+
+describe('official spawn projection', () => {
+  it('forwards command, arguments, cwd, environment, and signal exactly', () => {
+    vi.stubEnv('SDK_REMOVED_AMBIENT', 'ambient-value')
+    const signal = new AbortController().signal
+    const options = sdkSpawnOptions({
+      command: '/official/claude',
+      args: ['--one', 'two'],
+      cwd: '/parent/workspace',
+      env: { A: 'one', B: undefined, C: 'three' },
+      signal,
+    })
+    expect(sdkEnvironmentOverlay(options.env)).toEqual(expect.objectContaining({
+      A: 'one',
+      B: undefined,
+      C: 'three',
+      SDK_REMOVED_AMBIENT: undefined,
+    }))
+    const spawnSpec = claudeSpawnSpec(options, 321)
+    expect(spawnSpec).toMatchObject({
+      argv: ['/official/claude', '--one', 'two'],
+      cwd: '/parent/workspace',
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' },
+      graceMs: 321,
+      signal,
+    })
+    expect(spawnSpec.env).toEqual(expect.objectContaining({
+      A: 'one',
+      B: undefined,
+      C: 'three',
+      SDK_REMOVED_AMBIENT: undefined,
+    }))
+    const missingCwd = sdkSpawnOptions()
+    delete missingCwd.cwd
+    expect(() => claudeSpawnSpec(
+      missingCwd,
+      321,
+    )).toThrow('SDK spawn request omitted its workspace')
+    expect(() => claudeSpawnSpec(
+      sdkSpawnOptions({ cwd: '' }),
+      321,
+    )).toThrow('SDK spawn request omitted its workspace')
+  })
+
+  it('projects streams, exit facts, listeners, and idempotent tree termination', async () => {
+    const child = fakeChild({ exitOnTerminate: false })
+    const process = new ManagedClaudeCodeProcess(child.handle)
+    expect(process.stdin).toBe(child.stdin)
+    expect(process.stdout).toBe(child.stdout)
+    expect(process.killed).toBe(false)
+    expect(process.exitCode).toBeNull()
+    expect(process.signalCode).toBeNull()
+
+    const exit = vi.fn()
+    const once = vi.fn()
+    const removed = vi.fn()
+    process.on('exit', exit)
+    process.once('exit', once)
+    process.on('exit', removed)
+    process.off('exit', removed)
+    expect(process.kill('SIGTERM')).toBe(true)
+    expect(process.killed).toBe(true)
+    expect(process.kill('SIGKILL')).toBe(false)
+    expect(child.terminate).toHaveBeenCalledOnce()
+
+    child.settle({ exitCode: null, signal: 'SIGTERM' })
+    await nextTask()
+    expect(exit).toHaveBeenCalledWith(null, 'SIGTERM')
+    expect(once).toHaveBeenCalledOnce()
+    expect(removed).not.toHaveBeenCalled()
+    expect(process.signalCode).toBe('SIGTERM')
+    expect(process.kill('SIGTERM')).toBe(false)
+  })
+
+  it('emits spawn errors', async () => {
+    const child = fakeChild()
+    const process = new ManagedClaudeCodeProcess(child.handle)
+    const errorListener = vi.fn()
+    const removed = vi.fn()
+    process.once('error', errorListener)
+    process.on('error', removed)
+    process.off('error', removed)
+    child.fail(new Error('spawn boom'))
+    await nextTask()
+    expect(errorListener).toHaveBeenCalledWith(expect.objectContaining({
+      message: 'spawn boom',
+    }))
+    expect(removed).not.toHaveBeenCalled()
+  })
+
+  it('exposes a settled direct-child exit code', async () => {
+    const child = fakeChild()
+    const process = new ManagedClaudeCodeProcess(child.handle)
+    child.settle({ exitCode: 7, signal: null })
+    await nextTask()
+    expect(process.exitCode).toBe(7)
+    expect(process.signalCode).toBeNull()
+    expect(process.kill('SIGTERM')).toBe(false)
+  })
+})
+
+describe('query options and result mapping', () => {
+  it('builds the fixed unattended options over the scrubbed environment', () => {
+    vi.stubEnv('HOST_VISIBLE', 'visible')
+    vi.stubEnv('HOST_SECRET_TOKEN', 'must-not-leak')
+    vi.stubEnv('DSH_INTERNAL', 'must-not-leak')
+    const child = fakeChild()
+    const spawn = vi.fn(() => child.handle)
+    const captured: SubprocessHandle[] = []
+    const spec: ClaudeCodeRunSpec = {
+      cwd: '/workspace',
+      env: {
+        HOST_VISIBLE: 'overridden',
+        ANTHROPIC_API_KEY: 'explicit-fake-key',
+      },
+      disposeGraceMs: 17,
+      spawn,
+    }
+    const controller = new AbortController()
+    const options = claudeQueryOptions(spec, controller, (value) => {
+      captured.push(value)
+    })
+
+    expect(options).toMatchObject({
+      abortController: controller,
+      cwd: '/workspace',
+      persistSession: false,
+      disallowedTools: ['AskUserQuestion'],
+    })
+    expect(options.env).toMatchObject({
+      HOST_VISIBLE: 'overridden',
+      ANTHROPIC_API_KEY: 'explicit-fake-key',
+    })
+    expect(options.env).not.toHaveProperty('HOST_SECRET_TOKEN')
+    expect(options.env).not.toHaveProperty('DSH_INTERNAL')
+    for (const omitted of [
+      'settingSources',
+      'canUseTool',
+      'onElicitation',
+      'onUserDialog',
+      'supportedDialogKinds',
+    ]) {
+      expect(options).not.toHaveProperty(omitted)
+    }
+
+    const spawned = options.spawnClaudeCodeProcess!(sdkSpawnOptions())
+    expect(spawned).toBeInstanceOf(ManagedClaudeCodeProcess)
+    expect(captured).toEqual([child.handle])
+    expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
+      argv: ['/sdk/claude', '--output-format', 'stream-json'],
+      cwd: '/workspace',
+      graceMs: 17,
+    }))
+  })
+
+  it('accepts only a non-error success with a non-blank final result', () => {
+    expect(successfulResult(success('exact final'))).toBe('exact final')
+    expect(() => successfulResult(success('answer', true)))
+      .toThrow('marked as an error')
+    expect(() => successfulResult(success(' \n ')))
+      .toThrow('contained no answer')
+    expect(() => successfulResult(failure(
+      'error_during_execution',
+      ['first', 'second'],
+    ))).toThrow('first; second')
+    expect(() => successfulResult(failure(
+      'error_max_turns',
+      [],
+    ))).toThrow('error_max_turns')
+  })
+
+  it('consumes the complete stream and keeps the latest strict success', async () => {
+    const query = queryFrom([
+      { type: 'system', subtype: 'init' } as SDKMessage,
+      success('first'),
+      success('last'),
+    ])
+    await expect(consumeClaudeQuery(query)).resolves.toEqual({
+      output: [{ type: 'text', text: 'last' }],
+      stopReason: 'completed',
+    })
+    await expect(consumeClaudeQuery(
+      queryFrom([{ type: 'system', subtype: 'init' } as SDKMessage]),
+    )).rejects.toThrow('ended without a result')
+  })
+})
+
+describe('run publication, cancellation, and settlement', () => {
+  it('publishes only after Query and managed child exist, then disposes once', async () => {
+    const fixture = fakeRun([success('exact answer')])
+    const run = await startClaudeCodeRun(
+      request([
+        { type: 'text', text: 'first' },
+        { type: 'text', text: 'second' },
+      ]),
+      fixture.spec,
+    )
+    expect(fixture.options).toHaveLength(1)
+    expect(fixture.spawnSpecs).toHaveLength(1)
+    await expect(run.result).resolves.toEqual({
+      output: [{ type: 'text', text: 'exact answer' }],
+      stopReason: 'completed',
+    })
+    const first = run.dispose()
+    const second = run.dispose()
+    expect(second).toBe(first)
+    await first
+    expect(fixture.close).toHaveBeenCalledOnce()
+    expect(fixture.child.terminate).toHaveBeenCalledOnce()
+  })
+
+  it('flattens every SDK error result without inventing shared stop reasons', async () => {
+    const subtypes: ErrorSubtype[] = [
+      'error_during_execution',
+      'error_max_turns',
+      'error_max_budget_usd',
+      'error_max_structured_output_retries',
+    ]
+    for (const subtype of subtypes) {
+      const fixture = fakeRun([failure(subtype)])
+      const onError = vi.fn()
+      const run = await startClaudeCodeRun(
+        request(),
+        { ...fixture.spec, onError },
+      )
+      await expect(run.result).resolves.toEqual({
+        output: [],
+        stopReason: 'error',
+      })
+      expect(onError).toHaveBeenCalledWith(
+        expect.any(Error),
+        'error',
+      )
+      await run.dispose()
+    }
+  })
+
+  it('fails closed when iteration rejects after a result', async () => {
+    const fixture = fakeRun(
+      [success('partial final')],
+      new Error('iterator boom'),
+    )
+    const run = await startClaudeCodeRun(request(), fixture.spec)
+    await expect(run.result).resolves.toEqual({
+      output: [],
+      stopReason: 'error',
+    })
+    await run.dispose()
+  })
+
+  it('maps invalid success and missing result to error', async () => {
+    for (const messages of [
+      [success('answer', true)],
+      [success('')],
+      [{ type: 'system', subtype: 'init' } as SDKMessage],
+    ]) {
+      const fixture = fakeRun(messages)
+      const run = await startClaudeCodeRun(request(), fixture.spec)
+      await expect(run.result).resolves.toMatchObject({
+        stopReason: 'error',
+      })
+      await run.dispose()
+    }
+  })
+
+  it('gives local cancellation precedence and isolates overlapping controllers', async () => {
+    const firstChild = fakeChild()
+    const secondChild = fakeChild()
+    const children = [firstChild, secondChild]
+    const controllers: AbortController[] = []
+    let index = 0
+    const spec: ClaudeCodeRunSpec = {
+      cwd: '/workspace',
+      env: {},
+      disposeGraceMs: 5,
+      spawn: () => children[index++]!.handle,
+    }
+    queryMock.mockImplementation(({ prompt, options }) => {
+      controllers.push(options.abortController!)
+      options.spawnClaudeCodeProcess!(sdkSpawnOptions())
+      return prompt === 'wait'
+        ? waitingQuery(options.abortController!.signal)
+        : queryFrom([success('second answer')])
+    })
+    const firstAbort = new AbortController()
+    const first = await startClaudeCodeRun(
+      request([{ type: 'text', text: 'wait' }], firstAbort.signal),
+      spec,
+    )
+    const second = await startClaudeCodeRun(
+      request([{ type: 'text', text: 'finish' }]),
+      spec,
+    )
+    expect(controllers).toHaveLength(2)
+    expect(controllers[0]).not.toBe(controllers[1])
+    firstAbort.abort(new Error('parent cancelled'))
+    await expect(first.result).resolves.toEqual({
+      output: [],
+      stopReason: 'aborted',
+    })
+    await expect(second.result).resolves.toEqual({
+      output: [{ type: 'text', text: 'second answer' }],
+      stopReason: 'completed',
+    })
+    expect(controllers[1]!.signal.aborted).toBe(false)
+    await Promise.all([first.dispose(), second.dispose()])
+  })
+
+  it('keeps local cancellation authoritative when the SDK iterator ends normally', async () => {
+    const parentAbort = new AbortController()
+    const child = fakeChild()
+    async function* stream(): AsyncGenerator<SDKMessage, void> {
+      yield success('candidate answer')
+      parentAbort.abort(new Error('parent cancelled at iterator completion'))
+    }
+    queryMock.mockImplementation(({ options }) => {
+      options.spawnClaudeCodeProcess!(sdkSpawnOptions())
+      return Object.assign(stream(), { close: vi.fn() }) as unknown as Query
+    })
+    const run = await startClaudeCodeRun(
+      request(undefined, parentAbort.signal),
+      {
+        cwd: '/workspace',
+        env: {},
+        disposeGraceMs: 5,
+        spawn: () => child.handle,
+      },
+    )
+    await expect(run.result).resolves.toEqual({
+      output: [],
+      stopReason: 'aborted',
+    })
+    await run.dispose()
+  })
+
+  it('rejects pre-abort and every incomplete startup transaction', async () => {
+    const preAborted = new AbortController()
+    preAborted.abort()
+    const unused = fakeRun()
+    await expect(startClaudeCodeRun(
+      request(undefined, preAborted.signal),
+      unused.spec,
+    )).rejects.toThrow('aborted before SDK startup')
+    expect(unused.options).toEqual([])
+
+    const noChildClose = vi.fn()
+    queryMock.mockImplementationOnce(
+      () => queryFrom([], undefined, noChildClose),
+    )
+    await expect(startClaudeCodeRun(request(), {
+      ...unused.spec,
+    })).rejects.toThrow('did not publish a controllable')
+    expect(noChildClose).toHaveBeenCalledOnce()
+
+    const closeFailure = vi.fn(() => { throw new Error('close boom') })
+    queryMock.mockImplementationOnce(
+      () => queryFrom([], undefined, closeFailure),
+    )
+    const noChild = startClaudeCodeRun(request(), {
+      ...unused.spec,
+    })
+    await expect(noChild).rejects.toBeInstanceOf(AggregateError)
+
+    const startupAbort = new AbortController()
+    const abortedChild = fakeChild()
+    const abortedClose = vi.fn()
+    queryMock.mockImplementationOnce(({ options }) => {
+      options.spawnClaudeCodeProcess!(sdkSpawnOptions())
+      startupAbort.abort(new Error('startup cancelled'))
+      return queryFrom([], undefined, abortedClose)
+    })
+    const abortedDuringStartup = startClaudeCodeRun(
+      request(undefined, startupAbort.signal),
+      {
+        ...unused.spec,
+        spawn: () => abortedChild.handle,
+      },
+    )
+    await expect(abortedDuringStartup)
+      .rejects.toThrow('aborted before SDK startup')
+    expect(abortedClose).toHaveBeenCalledOnce()
+    expect(abortedChild.terminate).toHaveBeenCalledOnce()
+
+    queryMock.mockImplementationOnce(() => {
+      throw new Error('query failed before resource creation')
+    })
+    await expect(startClaudeCodeRun(request(), {
+      ...unused.spec,
+    })).rejects.toThrow('query failed before resource creation')
+
+    const spawned = fakeChild()
+    const spawnSpecs: SubprocessSpawnSpec[] = []
+    let factoryController: AbortController | undefined
+    queryMock.mockImplementationOnce(({ options }) => {
+      factoryController = options.abortController
+      options.spawnClaudeCodeProcess!(sdkSpawnOptions())
+      throw new Error('query construction failed')
+    })
+    const factoryFailure = startClaudeCodeRun(request(), {
+      ...unused.spec,
+      spawn: (spawnSpec) => {
+        spawnSpecs.push(spawnSpec)
+        return spawned.handle
+      },
+    })
+    await expect(factoryFailure).rejects.toThrow('query construction failed')
+    expect(spawnSpecs).toHaveLength(1)
+    expect(factoryController?.signal.aborted).toBe(true)
+    expect(spawned.terminate).toHaveBeenCalledOnce()
+
+    const failedSpawn = fakeChild({
+      pid: -1,
+      doneError: new Error('spawn failed'),
+    })
+    const failed = fakeRun([], undefined, failedSpawn)
+    await expect(startClaudeCodeRun(request(), failed.spec))
+      .rejects.toBeInstanceOf(AggregateError)
+    expect(failed.close).toHaveBeenCalledOnce()
+  })
+})
+
+describe('query and process disposal', () => {
+  it('closes the query, terminates the tree, and waits for direct-child outcome', async () => {
+    const child = fakeChild()
+    const close = vi.fn()
+    await disposeClaudeCodeChild({ close }, child.handle)
+    expect(close).toHaveBeenCalledOnce()
+    expect(child.terminate).toHaveBeenCalledOnce()
+    expect(child.waitForExit).toHaveBeenCalledOnce()
+    expect(child.waitForExit).toHaveBeenCalledWith()
+    await expect(child.handle.done).resolves.toEqual({
+      exitCode: 0,
+      signal: null,
+    })
+  })
+
+  it('does not finish disposal before the managed tree exits', async () => {
+    const child = fakeChild({ exitOnTerminate: false })
+    let disposed = false
+    const disposal = disposeClaudeCodeChild(
+      { close: vi.fn() },
+      child.handle,
+    ).then(() => {
+      disposed = true
+    })
+    await nextTask()
+    expect(disposed).toBe(false)
+    child.settle()
+    await disposal
+    expect(disposed).toBe(true)
+  })
+
+  it('reports wait, close, and direct-child failures without skipping cleanup', async () => {
+    const waitFailure = fakeChild({
+      waitForExitError: new Error('wait boom'),
+    })
+    const closeFailure = vi.fn(() => { throw new Error('close boom') })
+    await expect(disposeClaudeCodeChild(
+      { close: closeFailure },
+      waitFailure.handle,
+    )).rejects.toBeInstanceOf(AggregateError)
+    expect(waitFailure.terminate).toHaveBeenCalledOnce()
+
+    const doneFailure = fakeChild({
+      pid: -1,
+      doneError: new Error('spawn boom'),
+    })
+    await expect(disposeClaudeCodeChild(
+      { close: vi.fn() },
+      doneFailure.handle,
+    )).rejects.toThrow('spawn boom')
+
+    const both = fakeChild({
+      pid: -1,
+      doneError: new Error('spawn boom'),
+    })
+    await expect(disposeClaudeCodeChild(
+      { close: () => { throw new Error('close boom') } },
+      both.handle,
+    )).rejects.toBeInstanceOf(AggregateError)
+  })
+})
diff --git a/packages/subagent/subagent-claude-code/tsconfig.json b/packages/subagent/subagent-claude-code/tsconfig.json
new file mode 100644
index 0000000000..751aa08a9e
--- /dev/null
+++ b/packages/subagent/subagent-claude-code/tsconfig.json
@@ -0,0 +1,37 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "lib/types/.tsbuildinfo"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../subagent"
+    },
+    {
+      "path": "../../subprocess/subprocess"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/subagent/subagent-codex/README.i18n.yaml b/packages/subagent/subagent-codex/README.i18n.yaml
new file mode 100644
index 0000000000..97c2b9f705
--- /dev/null
+++ b/packages/subagent/subagent-codex/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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-codex/README.md
+README.md: c25ee90edf8972da66448fe84cb659b0aec79e6f
+README.zh.md: 10c8fcc47a9ab04bca983857bd44ede265c23435
diff --git a/packages/subagent/subagent-codex/README.md b/packages/subagent/subagent-codex/README.md
new file mode 100644
index 0000000000..c25ee90edf
--- /dev/null
+++ b/packages/subagent/subagent-codex/README.md
@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-subagent-codex
+
+English | [中文](README.zh.md)
+
+This package registers the fixed `codex` subagent provider. Each accepted run starts the official `codex app-server --stdio` command in the delegating Session's workspace, creates one ephemeral Codex thread, submits one self-contained text task, and returns only the final answer through the shared [`dsh-subagent`](../subagent/README.md) result contract.
+
+## Start and ownership
+
+`start(request)` accepts only a non-empty sequence of text blocks and derives the child cwd from the parent Session. It then spawns the fixed command through [`dsh-subprocess`](../../subprocess/subprocess/README.md), performs `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`, and publishes the run only after Codex returns a valid ephemeral thread. A failure or cancellation before publication closes the wire, terminates the managed process tree, waits for it to exit, and rejects `start()`.
+
+The published `run.result` starts exactly one turn. It accepts only notifications for that run's thread and turn, then waits for the authoritative `turn/completed` terminal notification. The latest `agentMessage` with `phase: "final_answer"` wins; when Codex emits no explicit final phase, the latest message with `phase: null` is the compatibility fallback. Commentary never replaces either answer, and a successful turn with no nonblank answer settles as an error.
+
+For command and file approvals, the unattended provider selects a non-approval decision offered by the request, preferring `cancel`; the stable 0.146.0 request shape without an offered-decision list falls back to `decline`. It answers permission requests with an empty turn-scoped permission set, answers user-input requests with no answers, and declines MCP elicitation. A request with no legal unattended response, or any unknown server request, fails the run.
+
+Local cancellation wins the result race and maps to `aborted`. A failed turn whose `codexErrorInfo` is `contextWindowExceeded` maps to `max-tokens`; every other remote interrupted or failed turn maps to `error`, and this version produces no `refusal`. `dispose()` is idempotent: it requests a best-effort `turn/interrupt` with both current ids when they are known, closes the JSON-RPC wire, ends stdin, invokes the shared process-tree termination escalation, and waits for whole-tree exit. Result failure and independent teardown failure remain separate.
+
+## Capabilities and context
+
+The provider advertises no optional start-time capabilities and reports `inheritsParentContext: false`. Codex receives the standalone text task and the parent Session cwd, but not the parent conversation, persona, tool filter, depth policy, or structured-output contract. The ephemeral Codex thread id and turn id stay private to this run and are never persisted in the parent Session.
+
+## Configuration
+
+| Key | Default | Meaning |
+|---|---|---|
+| `env` | `{}` | Explicit child environment layered over the subprocess seam's credential-scrubbed parent environment. |
+| `disposeGraceMs` | `3000` | Positive finite grace in milliseconds, no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), between the shared process-tree owner's termination tiers; disposal then waits for whole-tree exit. |
+
+Production resolves `codex` from `PATH` and uses the host's native Codex configuration and authentication. The plugin does not install Codex, select a model, create `CODEX_HOME`, log in, or probe a version. Credential-shaped ambient variables are removed by the subprocess seam, so an API key intended for the child must be supplied explicitly in `env`; ordinary ambient values such as `PATH` and `HOME` remain available unless overridden.
+
+Install this package and add the following rows to your own `cordis.yml`. Shipped CLI configurations do not load this provider or expose `subagent_codex` by default.
+
+```yaml
+- id: subagent-codex
+  name: '@deepseek-ai/dsh-subagent-codex'
+  config:
+    env:
+      OPENAI_API_KEY: !!js process.env.OPENAI_API_KEY
+
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: codex
+    toolName: subagent_codex
+    enableRunInBackground: false
+    maxDepth: provider-managed
+```
+
+## Product compatibility and evidence
+
+The production wire intentionally implements only the app-server methods required by this one-shot contract. Development evidence is pinned to `@openai/codex@0.146.0` / `codex-cli 0.146.0`: the keyless real-product spec drives the official binary against a loopback Responses service with a non-empty fake key and proves the task, authentication, exact answer, cancellation, approvals, and process-tree exit. A separate Loader composition e2e boots the README-shaped user configuration with no `codex` command available, verifies the fixed provider and foreground-only tool schema, and records zero child starts. A credentialed e2e starts the production provider and real Codex, then obtains a unique answer from the fixed official DeepSeek service through a loopback-only test bridge from Responses to Chat Completions; that bridge is not production functionality or native Codex support for DeepSeek's Chat Completions API. The npm package is a test-only dependency; deployments still supply `codex` on `PATH`.
+
+## Model Experience
+
+### Child request
+
+#### What the model sees
+
+The Codex child receives the standalone text blocks as one turn in a fresh ephemeral thread. Its workspace is the parent Session cwd, and its model, system instructions, tools, sandbox, and authentication come from the native Codex installation and configuration.
+
+#### Token effect
+
+The child pays for an independent Codex context and turn. Child tokens do not enter the parent's context.
+
+#### KV Cache effect
+
+Independent of the parent request cache. Reuse depends only on Codex's own provider, model, instructions, tools, and ephemeral-thread request.
+
+### Parent tool result, indirectly
+
+#### What the model sees
+
+Through `dsh-tool-subagent`, the parent sees only the selected final Codex answer or the consumer's exact error for a non-completed result. Codex commentary, reasoning, tool activity, stderr, workspace diffs, and product ids are not copied into the parent Session.
+
+#### Token effect
+
+Parent input grows only by the final answer or error retained in the tool result. This provider adds no parent tool schema by itself.
+
+#### KV Cache effect
+
+Append-only: the new tool result follows the reusable parent request prefix.
+
+## Known Limitations and Deferred Work
+
+- **One fresh process, thread, and turn per run** — there is no continuation, resume, pooling, progress stream, or product-session persistence.
+- **Host-managed product installation and account state** — a missing or incompatible `codex`, configuration error, or authentication failure is surfaced as a startup or run error; the plugin provides no installer, login flow, or runtime version gate.
+- **Compatibility is pinned by development evidence** — upgrading from the verified 0.146.0 protocol baseline requires regenerating upstream schema evidence and rerunning handshake, answer-selection, approval, cancellation, keyless real-product, and credentialed DeepSeek nonce tests.
+- **No human approval path** — known unattended approval requests are denied and unknown server requests fail closed; deployments cannot configure an allow policy through this package.
+- **Final text only** — reasoning, commentary, intermediate messages, tool traffic, usage, stderr, and workspace diffs remain product-local.
+- **No optional shared capabilities** — output schemas, child personas, tool filtering, and harness depth enforcement are rejected by the shared service for this provider.
+- **No wall-clock timeout or side-effect rollback** — the caller cancels long work, and files or external systems changed before cancellation are not restored.
diff --git a/packages/subagent/subagent-codex/README.zh.md b/packages/subagent/subagent-codex/README.zh.md
new file mode 100644
index 0000000000..10c8fcc47a
--- /dev/null
+++ b/packages/subagent/subagent-codex/README.zh.md
@@ -0,0 +1,90 @@
+# @deepseek-ai/dsh-subagent-codex
+
+[English](README.md) | 中文
+
+本包（package）注册固定的 `codex` subagent 提供方。每次接受运行请求后，它都会在发起委托的会话工作区中启动官方 `codex app-server --stdio` 命令，创建一个临时 Codex 线程，提交一个自包含的文本任务，并通过共享的 [`dsh-subagent`](../subagent/README.md) 结果契约仅返回最终答案。
+
+## 启动与所有权
+
+`start(request)` 只接受非空的文本块序列，并根据父会话确定子级 cwd。随后，它通过 [`dsh-subprocess`](../../subprocess/subprocess/README.md) spawn 固定命令，依次执行 `initialize` → `initialized` → `thread/start { cwd, ephemeral: true }`，且仅在 Codex 返回有效的临时线程后才发布此次运行。若在发布前发生失败或取消，它会关闭通信链路、终止受管进程树并等待其退出，然后拒绝 `start()` 调用。
+
+已发布的 `run.result` 恰好启动一个轮次。它只接受与此次运行的线程和轮次匹配的通知，随后等待权威的终止通知 `turn/completed`。以最后一条 `phase: "final_answer"` 的 `agentMessage` 为准；若 Codex 没有发出明确的最终阶段，则以最后一条 `phase: null` 的消息作为兼容性回退。过程说明绝不会取代上述任一答案；成功完成的轮次若没有非空白答案，结果也会判为错误。
+
+对于命令与文件审批，无人值守的提供方会从请求给出的决策选项中选择一项不予批准的决策，并优先选择 `cancel`；稳定的 0.146.0 请求形态没有决策选项列表，因此回退到 `decline`。它对权限请求返回作用域限于当前轮次的空权限集，不向用户输入请求提供任何答案，并拒绝 MCP elicitation。若请求在无人值守模式下没有合法响应，或是未知服务器请求，此次运行就会失败。
+
+本地取消会在结果竞态中胜出并映射为 `aborted`。失败轮次的 `codexErrorInfo` 若为 `contextWindowExceeded`，则映射为 `max-tokens`；其他任何远端中断或失败轮次都映射为 `error`，且本版本不会产生 `refusal`。`dispose()` 具有幂等性：如果当前的两个标识符均已知，它会尽力请求 `turn/interrupt`，关闭 JSON-RPC 通信链路，结束标准输入，调用共享的进程树逐级终止机制，并等待整棵进程树退出。结果失败与独立的清理失败仍彼此分离。
+
+## 能力与上下文
+
+本提供方不声明任何可选的启动时能力，并报告 `inheritsParentContext: false`。Codex 会接收独立文本任务和父会话 cwd，但不会接收父会话的对话、角色设定、工具筛选器、深度策略或结构化输出契约。临时 Codex 线程 ID 与轮次 ID 仅在此次运行内部可见，绝不会持久化到父会话。
+
+## 配置
+
+| 配置键 | 默认值 | 含义 |
+|---|---|---|
+| `env` | `{}` | 显式指定的子进程环境，叠加在由子进程 seam 清除凭证后的父环境之上。 |
+| `disposeGraceMs` | `3000` | 共享进程树责任方各终止层级之间的宽限期，单位为毫秒且须为正有限值，并不得大于仓库共享的 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)；随后资源释放会等待整棵进程树退出。 |
+
+生产环境会从 `PATH` 中解析 `codex`，并使用宿主机原生的 Codex 配置与身份验证。本插件不安装 Codex、不选择模型、不创建 `CODEX_HOME`、不执行登录，也不探测版本。子进程 seam 会移除具有凭证特征的环境变量，因此供子进程使用的 API 密钥必须在 `env` 中显式提供；除非被覆盖，`PATH` 和 `HOME` 等普通环境变量值仍然可用。
+
+请安装此包，并将以下配置项添加到你自己的 `cordis.yml`。正式 CLI 配置默认不会加载此提供方，也不会暴露 `subagent_codex`。
+
+```yaml
+- id: subagent-codex
+  name: '@deepseek-ai/dsh-subagent-codex'
+  config:
+    env:
+      OPENAI_API_KEY: !!js process.env.OPENAI_API_KEY
+
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: codex
+    toolName: subagent_codex
+    enableRunInBackground: false
+    maxDepth: provider-managed
+```
+
+## 产品兼容性与证据
+
+生产环境的协议层有意只实现这一单次执行契约所需的 app-server 方法。开发证据锁定在 `@openai/codex@0.146.0` / `codex-cli 0.146.0`：无密钥真实产品测试使用非空的伪密钥，驱动官方二进制程序连接回环 Responses 服务，并证明任务、身份验证、精确回答、取消、审批与进程树退出。独立的 Loader 装配 e2e 会在没有可用 `codex` 命令时启动与 README 同形的用户配置，验证固定提供方与只支持前台执行的工具 schema，并记录零次子级启动。带密钥 e2e 会启动生产提供方和真实 Codex，再通过一个仅限回环、将 Responses 转为 Chat Completions 的测试桥接层，从固定的 DeepSeek 官方服务获得唯一答案；该桥接层既不属于生产功能，也不代表 Codex 原生支持 DeepSeek 的 Chat Completions API。该 NPM 包仅作为测试依赖；部署环境仍需通过 `PATH` 提供 `codex`。
+
+## 模型体验
+
+### 子任务请求
+
+#### 模型看到的内容
+
+Codex 子任务会在一个全新的临时线程中，以单个轮次接收这些独立文本块。它的工作区是父会话 cwd；其模型、系统指令、工具、沙箱和身份验证来自原生 Codex 安装与配置。
+
+#### 对 token 的影响
+
+子任务需为独立的 Codex 上下文和轮次承担 token 开销。子任务 token 不会进入父级上下文。
+
+#### 对 KV Cache 的影响
+
+这与父请求缓存相互独立。能否复用只取决于 Codex 自身的提供方、模型、指令、工具和临时线程请求。
+
+### 父级工具结果（间接）
+
+#### 模型看到的内容
+
+通过 `dsh-tool-subagent`，父级模型只会看到选定的 Codex 最终答案，或者在结果未完成时看到消费方给出的原样错误。Codex 的过程说明、推理（reasoning）、工具活动、stderr、工作区差异和产品标识符均不会复制到父会话。
+
+#### 对 token 的影响
+
+父级输入只会增加工具结果中保留的最终答案或错误内容。本提供方自身不添加父级工具 schema。
+
+#### 对 KV Cache 的影响
+
+仅追加：新的工具结果接在可复用的父请求前缀之后。
+
+## 已知限制与后续工作
+
+- **每次运行均新建一个进程、一个线程和一个轮次**：不支持续接、恢复、池化、进度流或产品会话持久化。
+- **产品安装和账户状态由宿主管理**：`codex` 缺失或不兼容、配置错误或身份验证失败，都会呈现为启动错误或运行错误；本插件不提供安装程序、登录流程或运行时版本门禁。
+- **兼容性由开发证据锁定**：若要从已验证的 0.146.0 协议基线升级，必须重新生成上游 schema 证据，并重新运行握手、答案选择、审批、取消、无密钥真实产品以及带密钥的 DeepSeek 随机数测试。
+- **没有人工审批路径**：已知的无人值守审批请求会被拒绝，未知服务器请求会以默认拒绝方式使运行失败；部署方无法通过本包配置允许策略。
+- **仅返回最终文本**：推理、过程说明、中间消息、工具通信、用量信息、stderr 和工作区差异仍只保留在产品内部。
+- **没有可选的共享能力**：对于本提供方，共享服务会拒绝输出 schema、子任务角色设定、工具筛选和 harness 深度强制约束。
+- **没有按实际经过时间触发的超时或副作用回滚**：长时间运行的工作由调用方取消，且取消前已更改的文件或外部系统不会恢复原状。
diff --git a/packages/subagent/subagent-codex/package.json b/packages/subagent/subagent-codex/package.json
new file mode 100644
index 0000000000..873cf1d77c
--- /dev/null
+++ b/packages/subagent/subagent-codex/package.json
@@ -0,0 +1,55 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-codex",
+  "description": "One-shot Codex subagent provider over the official app-server protocol",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-sdk-protocol": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1",
+    "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-sdk-protocol": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "@openai/codex": "0.146.0",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
diff --git a/packages/subagent/subagent-codex/src/index.ts b/packages/subagent/subagent-codex/src/index.ts
new file mode 100644
index 0000000000..23077e3b54
--- /dev/null
+++ b/packages/subagent/subagent-codex/src/index.ts
@@ -0,0 +1,101 @@
+/**
+ * Fixed Codex one-shot subagent provider. Every accepted run starts a fresh
+ * official `codex app-server --stdio` process in the delegating Session's
+ * workspace and publishes only after an ephemeral thread exists.
+ *
+ * @module @deepseek-ai/dsh-subagent-codex
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import {
+  assertPositiveFinite,
+  NO_START_CAPABILITIES,
+  resolveChildCwd,
+  type ResolvedSubagentStartRequest,
+  type SubagentCapabilities,
+  type SubagentProvider,
+} from '@deepseek-ai/dsh-subagent'
+import {
+  DEFAULT_DISPOSE_GRACE_MS,
+  startCodexRun,
+  type CodexRunSpec,
+} from './run.ts'
+
+export const name = 'subagent-codex'
+export const inject = ['subagents', 'subprocess']
+
+/** Deployment-owned environment and process-release bound. */
+export interface Config {
+  /**
+   * Explicit environment entries layered over the subprocess seam's
+   * credential-scrubbed parent environment.
+   */
+  env?: Record<string, string>
+  /** Grace in milliseconds for app-server process-tree termination. */
+  disposeGraceMs?: number
+}
+
+export const Config: z<Config> = z.object({
+  env: z.dict(z.string()).default({}),
+  disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS),
+})
+
+type ResolvedConfig = Required<Config>
+
+class CodexProvider implements SubagentProvider {
+  readonly name = 'codex'
+  readonly capabilities: SubagentCapabilities = NO_START_CAPABILITIES
+  readonly inheritsParentContext = false
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly config: ResolvedConfig,
+  ) {}
+
+  start(request: ResolvedSubagentStartRequest) {
+    const parentCwd = request.parent.session.header.cwd
+    if (parentCwd === undefined) {
+      throw new Error(
+        'subagent-codex: no working directory for the child — delegate from a parent session that has one',
+      )
+    }
+    const spec: CodexRunSpec = {
+      cwd: resolveChildCwd(
+        'subagent-codex',
+        undefined,
+        parentCwd,
+      ),
+      env: this.config.env,
+      disposeGraceMs: this.config.disposeGraceMs,
+      spawn: spawnSpec => this.ctx.subprocess.spawn(spawnSpec),
+      onError: (error, stopReason) => {
+        this.ctx.logger.warn(
+          `subagent-codex: child run failed (${stopReason}): ${error.message}`,
+        )
+      },
+    }
+    return startCodexRun(request, spec)
+  }
+}
+
+/**
+ * Register the fixed `codex` provider.
+ * @param ctx - context carrying shared subagent and subprocess services.
+ * @param config - explicit child environment and disposal grace.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const resolved = config as ResolvedConfig
+  assertPositiveFinite(
+    'subagent-codex',
+    'disposeGraceMs',
+    resolved.disposeGraceMs,
+  )
+  if (resolved.disposeGraceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(
+      `subagent-codex: disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`,
+    )
+  }
+  ctx.subagents.registerProvider(new CodexProvider(ctx, resolved))
+}
diff --git a/packages/subagent/subagent-codex/src/invariant.ts b/packages/subagent/subagent-codex/src/invariant.ts
new file mode 100644
index 0000000000..a0c094af9c
--- /dev/null
+++ b/packages/subagent/subagent-codex/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-codex`.
+ * @module @deepseek-ai/dsh-subagent-codex/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-codex'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-codex-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: lifecycle pairing belongs to the shared subagent
+ * service and process-tree ownership belongs to the subprocess service.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - plugin context carrying the invariant registry.
+ * @returns the installed registration's disposer.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-codex/src/run.ts b/packages/subagent/subagent-codex/src/run.ts
new file mode 100644
index 0000000000..c3ebf4ba19
--- /dev/null
+++ b/packages/subagent/subagent-codex/src/run.ts
@@ -0,0 +1,200 @@
+/**
+ * One-shot Codex child lifecycle: spawn the real app-server through the
+ * subprocess seam, publish only after initialization and ephemeral thread
+ * creation, flatten post-publication failures, and dispose to whole-tree
+ * quiescence.
+ *
+ * @module @deepseek-ai/dsh-subagent-codex/run
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import {
+  settleRunResult,
+  subprocessRunHandle,
+  type SubagentResult,
+  type SubagentRun,
+  type SubagentStartRequest,
+  type SubagentStopReason,
+} from '@deepseek-ai/dsh-subagent'
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
+import { CodexAppServerWire } from './wire.ts'
+
+/** Default POSIX grace between subprocess termination tiers. */
+export const DEFAULT_DISPOSE_GRACE_MS = 3_000
+
+/**
+ * Resolve the fixed app-server command for a platform.
+ *
+ * Windows npm and pnpm installs expose `codex.cmd`, which requires `cmd.exe`;
+ * the argv is constant so no task or configuration text enters the
+ * shell boundary.
+ * @param platform - host platform used to select the executable boundary.
+ * @returns argv for the fixed Codex app-server command.
+ */
+export function codexAppServerArgv(
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  return platform === 'win32'
+    ? ['cmd.exe', '/d', '/s', '/c', 'codex', 'app-server', '--stdio']
+    : ['codex', 'app-server', '--stdio']
+}
+
+/** Fully resolved inputs for one Codex app-server run. */
+export interface CodexRunSpec {
+  /** Parent Session workspace, also supplied to `thread/start`. */
+  readonly cwd: string
+  /** Explicit deployment/test environment layered after the shared scrub. */
+  readonly env: Record<string, string>
+  /** Subprocess termination grace passed to the shared process-tree owner. */
+  readonly disposeGraceMs: number
+  /** Shared subprocess service spawn operation. */
+  readonly spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle
+  /** Diagnostic sink for a post-publication error flattened into a result. */
+  readonly onError?: (error: Error, stopReason: SubagentStopReason) => void
+}
+
+function thrown(value: unknown): Error {
+  /* v8 ignore next -- typed subprocess/wire failures reject with Error. */
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+/**
+ * Validate and preserve the one-shot task before crossing the process seam.
+ * @param prompt - task content accepted from the shared subagent service.
+ * @returns the exact non-empty text block sequence.
+ */
+export function textTask(prompt: readonly ContentBlock[]): string[] {
+  if (prompt.length === 0) {
+    throw new Error('subagent-codex: the one-shot task must contain only text blocks')
+  }
+  const texts: string[] = []
+  for (const block of prompt) {
+    if (block.type !== 'text') {
+      throw new Error('subagent-codex: the one-shot task must contain only text blocks')
+    }
+    texts.push(block.text)
+  }
+  if (texts.every(text => text.trim().length === 0)) {
+    throw new Error('subagent-codex: the one-shot task must not be empty')
+  }
+  return texts
+}
+
+/**
+ * Close the private wire, terminate the managed process tree, and wait for the
+ * subprocess owner to prove it is gone.
+ * @param wire - private app-server protocol connection.
+ * @param child - shared-service handle that owns the process tree.
+ */
+export async function disposeCodexChild(
+  wire: CodexAppServerWire,
+  child: SubprocessHandle,
+): Promise<void> {
+  wire.close()
+  if (child.pid <= 0) {
+    await child.done.catch(() => {})
+    return
+  }
+  try {
+    child.stdin?.end()
+  } catch {
+    // A concurrently closed stdin does not change tree ownership below.
+  }
+  child.terminate()
+  await child.waitForExit()
+  await child.done
+}
+
+/**
+ * Start the real `codex app-server --stdio` child and publish its one-shot run.
+ * @param request - resolved shared subagent request.
+ * @param spec - workspace, environment, process seam, and diagnostic policy.
+ * @returns the published run after initialization and ephemeral thread creation.
+ */
+export async function startCodexRun(
+  request: SubagentStartRequest,
+  spec: CodexRunSpec,
+): Promise<SubagentRun> {
+  const texts = textTask(request.prompt)
+  if (request.signal.aborted) {
+    throw new Error('subagent-codex: request was aborted before app-server startup')
+  }
+
+  const child = spec.spawn({
+    argv: codexAppServerArgv(),
+    cwd: spec.cwd,
+    stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' },
+    graceMs: spec.disposeGraceMs,
+    env: spec.env,
+  })
+
+  const wire = new CodexAppServerWire(
+    child.stdout as NonNullable<SubprocessHandle['stdout']>,
+    child.stdin as NonNullable<SubprocessHandle['stdin']>,
+  )
+  const disposeProcess = (): Promise<void> => disposeCodexChild(wire, child)
+
+  const processFailure: Promise<never> = child.done.then(
+    outcome => Promise.reject(new Error(
+      'subagent-codex: app-server exited before the run settled '
+      + `(code ${String(outcome.exitCode)}, signal ${String(outcome.signal)})`,
+    )),
+    (error: unknown) => Promise.reject(thrown(error)),
+  )
+  // A normal post-result dispose also closes the process. Keep that expected
+  // late rejection observed after the result race has already settled.
+  processFailure.catch(() => {})
+
+  const runAbort = new AbortController()
+  const requestCancel = (): void => {
+    if (runAbort.signal.aborted) return
+    runAbort.abort(new Error('subagent-codex: run cancelled locally'))
+    wire.interrupt()
+  }
+  const onAbort = (): void => { requestCancel() }
+  request.signal.addEventListener('abort', onAbort, { once: true })
+
+  try {
+    wire.start()
+    await Promise.race([wire.initialize(request.signal), processFailure])
+    await Promise.race([wire.startThread(spec.cwd, request.signal), processFailure])
+  } catch (error: unknown) {
+    request.signal.removeEventListener('abort', onAbort)
+    try {
+      await disposeProcess()
+    } catch (disposeError: unknown) {
+      throw new AggregateError(
+        [thrown(error), thrown(disposeError)],
+        'subagent-codex: startup failed and app-server cleanup also failed',
+      )
+    }
+    if (runAbort.signal.aborted) {
+      throw new Error('subagent-codex: request was aborted before run publication')
+    }
+    throw thrown(error)
+  }
+
+  const collectOutput = (): ContentBlock[] => wire.collectOutput()
+  const result: Promise<SubagentResult> = settleRunResult({
+    attempt: () => Promise.race([
+      wire.runTurn(texts, runAbort.signal),
+      processFailure,
+    ]),
+    collectOutput,
+    cancelled: () => runAbort.signal.aborted,
+    onError: spec.onError,
+    signal: request.signal,
+    onAbort,
+  })
+
+  return subprocessRunHandle({
+    id: SessionId(randomUUID()),
+    result,
+    signal: request.signal,
+    onAbort,
+    requestCancel,
+    teardown: disposeProcess,
+  })
+}
diff --git a/packages/subagent/subagent-codex/src/wire.ts b/packages/subagent/subagent-codex/src/wire.ts
new file mode 100644
index 0000000000..51be212841
--- /dev/null
+++ b/packages/subagent/subagent-codex/src/wire.ts
@@ -0,0 +1,374 @@
+/**
+ * Minimal Codex app-server 0.146.0 protocol adapter. The shared JSON-RPC
+ * transport owns framing and request correlation; this module owns only the
+ * product methods, current thread/turn association, unattended approval
+ * responses, and terminal-answer selection.
+ *
+ * @module @deepseek-ai/dsh-subagent-codex/wire
+ */
+
+import type { Readable, Writable } from 'node:stream'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SubagentResult } from '@deepseek-ai/dsh-subagent'
+import { JsonRpcLineTransport } from '@deepseek-ai/dsh-sdk-protocol'
+
+type JsonObject = Record<string, unknown>
+
+function object(value: unknown, label: string): JsonObject {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`subagent-codex: app-server returned invalid ${label}`)
+  }
+  return value as JsonObject
+}
+
+function string(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`subagent-codex: app-server returned invalid ${label}`)
+  }
+  return value
+}
+
+function unattendedDecision(params: JsonObject): 'cancel' | 'decline' {
+  const available = params.availableDecisions
+  if (available === undefined || available === null) return 'decline'
+  if (Array.isArray(available)) {
+    if (available.includes('cancel')) return 'cancel'
+    if (available.includes('decline')) return 'decline'
+  }
+  throw new Error('subagent-codex: app-server offered no unattended approval decision')
+}
+
+function isContextWindowExceeded(turn: JsonObject): boolean {
+  if (turn.status !== 'failed') return false
+  const error = turn.error
+  return error !== null
+    && typeof error === 'object'
+    && !Array.isArray(error)
+    && (error as JsonObject).codexErrorInfo === 'contextWindowExceeded'
+}
+
+function thrown(value: unknown): Error {
+  /* v8 ignore next -- typed protocol and stream failures reject with Error. */
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+function abortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error(`subagent-codex: app-server request aborted: ${String(signal.reason)}`)
+}
+
+async function raceAbort<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) {
+    void pending.catch(() => {})
+    throw abortError(signal)
+  }
+  let rejectAbort!: (error: Error) => void
+  const aborted = new Promise<never>((_resolve, reject) => { rejectAbort = reject })
+  const onAbort = (): void => { rejectAbort(abortError(signal)) }
+  signal.addEventListener('abort', onAbort, { once: true })
+  try {
+    return await Promise.race([pending, aborted])
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
+}
+
+/**
+ * One app-server connection and its single ephemeral thread/turn.
+ *
+ * The class deliberately exposes no generic request surface. Supporting
+ * another product method must first become part of the provider contract.
+ */
+export class CodexAppServerWire {
+  private readonly transport: JsonRpcLineTransport
+  private readonly fatal = Promise.withResolvers<never>()
+  private threadId: string | undefined
+  private turnId: string | undefined
+  private pendingTurnId: string | undefined
+  private turnCompleted: PromiseWithResolvers<JsonObject> | undefined
+  private readonly earlyTurnNotifications: Array<{
+    readonly method: string
+    readonly params: JsonObject
+  }> = []
+  private lastFinalAnswer: string | undefined
+  private lastUnphasedAnswer: string | undefined
+  private closed = false
+
+  constructor(
+    private readonly input: Readable,
+    output: Writable,
+  ) {
+    this.transport = new JsonRpcLineTransport(input, output)
+    // Fatal protocol state can arrive after the current guarded operation has
+    // already settled. Keep the shared rejection observed without inserting
+    // another promise-adoption hop into active races.
+    void this.fatal.promise.catch(() => {})
+    this.transport.onRequest((method, params) => this.handleServerRequest(method, params))
+    this.transport.onNotification((method, params) => {
+      try {
+        this.handleNotification(method, params)
+      } catch (error: unknown) {
+        this.fail(thrown(error))
+      }
+    })
+    this.input.on('error', this.onInputError)
+    this.input.on('end', this.onInputEnd)
+    // Pipe errors can race protocol closure and process teardown. Retain both
+    // error listeners for the lifetime of their per-run streams so no late
+    // EPIPE or read failure becomes an unhandled EventEmitter error.
+    output.on('error', this.onOutputError)
+  }
+
+  /** Start reading app-server frames. */
+  start(): void {
+    this.transport.start()
+  }
+
+  /**
+   * Perform the required app-server initialize/initialized handshake.
+   * @param signal - unpublished-start cancellation.
+   */
+  async initialize(signal: AbortSignal): Promise<void> {
+    object(await this.guarded(this.transport.request('initialize', {
+      clientInfo: {
+        name: 'deepseek-harness',
+        title: 'DeepSeek Harness',
+        version: '0.0.1',
+      },
+      capabilities: {
+        experimentalApi: false,
+        requestAttestation: false,
+      },
+    }, signal), signal), 'initialize response')
+    this.transport.notify('initialized')
+    await this.guarded(this.transport.flush(), signal)
+  }
+
+  /**
+   * Create the run's private ephemeral thread and retain its identity.
+   * @param cwd - parent Session workspace.
+   * @param signal - unpublished-start cancellation.
+   */
+  async startThread(cwd: string, signal: AbortSignal): Promise<void> {
+    const response = object(await this.guarded(this.transport.request('thread/start', {
+      cwd,
+      ephemeral: true,
+    }, signal), signal), 'thread/start response')
+    const thread = object(response.thread, 'thread/start thread')
+    const id = string(thread.id, 'thread/start thread id')
+    if (thread.ephemeral !== true) {
+      throw new Error('subagent-codex: app-server did not create an ephemeral thread')
+    }
+    this.threadId = id
+  }
+
+  /**
+   * Submit the one text-only task and wait for this thread/turn's authoritative
+   * terminal notification.
+   * @param texts - already validated task text blocks.
+   * @param signal - local cancellation for the published run.
+   * @returns the shared subagent result.
+   */
+  async runTurn(
+    texts: readonly string[],
+    signal: AbortSignal,
+  ): Promise<SubagentResult> {
+    const completion = Promise.withResolvers<JsonObject>()
+    this.turnCompleted = completion
+    const threadId = this.threadId as string
+    const response = object(await this.guarded(this.transport.request('turn/start', {
+      threadId,
+      input: texts.map(text => ({ type: 'text', text, text_elements: [] })),
+    }, signal), signal), 'turn/start response')
+    const turn = object(response.turn, 'turn/start turn')
+    this.commitTurnId(string(turn.id, 'turn/start turn id'))
+
+    const completed = await this.guarded(completion.promise, signal)
+    const terminal = object(completed.turn, 'turn/completed turn')
+    const status = terminal.status
+    if (isContextWindowExceeded(terminal)) {
+      return { output: this.collectOutput(), stopReason: 'max-tokens' }
+    }
+    if (status !== 'completed') {
+      const detail = status === 'failed'
+        ? `: ${JSON.stringify(terminal.error)}`
+        : ''
+      throw new Error(`subagent-codex: Codex turn ended with status ${String(status)}${detail}`)
+    }
+    const output = this.collectOutput()
+    if (output.length === 0) {
+      throw new Error('subagent-codex: Codex completed without a final answer')
+    }
+    return { output, stopReason: 'completed' }
+  }
+
+  /**
+   * Best-effort remote cancellation. Local settlement and process teardown
+   * remain authoritative when the child no longer accepts protocol requests.
+   */
+  interrupt(): void {
+    if (this.threadId === undefined || this.turnId === undefined || this.closed) return
+    void this.transport.request('turn/interrupt', {
+      threadId: this.threadId,
+      turnId: this.turnId,
+    }).catch(() => {})
+  }
+
+  /**
+   * The best non-commentary answer observed so far, preserving exact bytes.
+   * @returns the selected final or nullable-phase text block, if any.
+   */
+  collectOutput(): ContentBlock[] {
+    const selected = this.lastFinalAnswer ?? this.lastUnphasedAnswer
+    return selected !== undefined && selected.trim().length > 0
+      ? [{ type: 'text', text: selected }]
+      : []
+  }
+
+  /** Detach JSON-RPC listeners and reject outstanding requests. Idempotent. */
+  close(): void {
+    if (this.closed) return
+    this.closed = true
+    this.input.off('end', this.onInputEnd)
+    this.transport.close()
+  }
+
+  private async guarded<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+    const withFatal = Promise.race([this.fatal.promise, pending])
+    return raceAbort(withFatal, signal)
+  }
+
+  private fail(error: Error): void {
+    this.fatal.reject(error)
+  }
+
+  private readonly onInputError = (error: Error): void => {
+    this.fail(error)
+  }
+
+  private readonly onOutputError = (error: Error): void => {
+    this.fail(error)
+  }
+
+  private readonly onInputEnd = (): void => {
+    this.fail(new Error('subagent-codex: app-server protocol stream closed'))
+  }
+
+  private observePendingTurnId(id: string): void {
+    if (this.turnCompleted === undefined) {
+      throw new Error('subagent-codex: app-server referenced a turn before turn/start')
+    }
+    if (this.pendingTurnId !== undefined && this.pendingTurnId !== id) {
+      throw new Error('subagent-codex: app-server referenced conflicting turns')
+    }
+    this.pendingTurnId = id
+  }
+
+  private commitTurnId(id: string): void {
+    if (this.pendingTurnId !== undefined && this.pendingTurnId !== id) {
+      throw new Error('subagent-codex: turn/start response did not match the active turn')
+    }
+    this.turnId = id
+    const notifications = this.earlyTurnNotifications.splice(0)
+    for (const notification of notifications) {
+      this.handleNotification(notification.method, notification.params)
+    }
+  }
+
+  private validateRunIds(params: JsonObject, nullableTurn = false): void {
+    if (params.threadId !== this.threadId) {
+      throw new Error('subagent-codex: app-server request referenced another thread')
+    }
+    if (nullableTurn && params.turnId === null) return
+    const id = string(params.turnId, 'server request turn id')
+    if (this.turnId === undefined) {
+      this.observePendingTurnId(id)
+      return
+    }
+    if (id !== this.turnId) {
+      throw new Error('subagent-codex: app-server request referenced another turn')
+    }
+  }
+
+  private handleServerRequest(method: string, params: JsonObject): Promise<unknown> {
+    try {
+      switch (method) {
+        case 'item/commandExecution/requestApproval':
+        case 'item/fileChange/requestApproval':
+          this.validateRunIds(params)
+          return Promise.resolve({ decision: unattendedDecision(params) })
+        case 'item/permissions/requestApproval':
+          this.validateRunIds(params)
+          return Promise.resolve({ permissions: {}, scope: 'turn' })
+        case 'item/tool/requestUserInput':
+          this.validateRunIds(params)
+          return Promise.resolve({ answers: {} })
+        case 'mcpServer/elicitation/request':
+          this.validateRunIds(params, true)
+          return Promise.resolve({ action: 'decline', content: null, _meta: null })
+        default:
+          throw new Error(`subagent-codex: unsupported app-server request ${JSON.stringify(method)}`)
+      }
+    } catch (error: unknown) {
+      const normalized = thrown(error)
+      this.fail(normalized)
+      return Promise.reject(normalized)
+    }
+  }
+
+  private handleNotification(method: string, params: JsonObject): void {
+    if (method === 'turn/started') {
+      const threadId = string(params.threadId, 'turn/started thread id')
+      if (threadId !== this.threadId) return
+      const turn = object(params.turn, 'turn/started turn')
+      if (this.turnCompleted !== undefined && this.turnId === undefined) {
+        this.observePendingTurnId(string(turn.id, 'turn/started turn id'))
+      }
+      return
+    }
+    if (method === 'item/completed') {
+      const threadId = string(params.threadId, 'item/completed thread id')
+      if (threadId !== this.threadId) return
+      const id = string(params.turnId, 'item/completed turn id')
+      if (this.turnId === undefined) {
+        if (this.turnCompleted !== undefined) {
+          this.observePendingTurnId(id)
+          this.earlyTurnNotifications.push({ method, params })
+        }
+        return
+      }
+      if (id !== this.turnId) return
+      const item = object(params.item, 'item/completed item')
+      if (item.type !== 'agentMessage') return
+      const text = typeof item.text === 'string'
+        ? item.text
+        : (() => { throw new Error('subagent-codex: app-server returned an invalid agent message') })()
+      if (item.phase === 'final_answer') {
+        this.lastFinalAnswer = text
+      } else if (item.phase === null) {
+        this.lastUnphasedAnswer = text
+      } else if (item.phase !== 'commentary') {
+        throw new Error(`subagent-codex: app-server returned an unknown agent message phase ${JSON.stringify(item.phase)}`)
+      }
+      return
+    }
+    if (method !== 'turn/completed') return
+    const threadId = string(params.threadId, 'turn/completed thread id')
+    if (threadId !== this.threadId) return
+    const turn = object(params.turn, 'turn/completed turn')
+    const id = string(turn.id, 'turn/completed turn id')
+    const turnCompleted = this.turnCompleted
+    if (turnCompleted === undefined) return
+    if (this.turnId === undefined) {
+      this.observePendingTurnId(id)
+      this.earlyTurnNotifications.push({ method, params })
+      return
+    }
+    if (id !== this.turnId) return
+    if (!['completed', 'interrupted', 'failed'].includes(String(turn.status))) {
+      throw new Error(`subagent-codex: app-server returned invalid terminal turn status ${String(turn.status)}`)
+    }
+    turnCompleted.resolve(params)
+  }
+}
diff --git a/packages/subagent/subagent-codex/tests/deepseek-responses-bridge.ts b/packages/subagent/subagent-codex/tests/deepseek-responses-bridge.ts
new file mode 100644
index 0000000000..b59738031e
--- /dev/null
+++ b/packages/subagent/subagent-codex/tests/deepseek-responses-bridge.ts
@@ -0,0 +1,190 @@
+import { createServer } from 'node:http'
+import type {
+  IncomingMessage,
+  Server,
+  ServerResponse,
+} from 'node:http'
+import { completeResponsesEvents } from './responses-fixture.ts'
+
+const OFFICIAL_DEEPSEEK_BASE_URL = 'https://api.deepseek.com'
+const MAX_REQUEST_BYTES = 1_048_576
+
+/** One running test-only Responses-to-DeepSeek bridge. */
+export interface DeepSeekResponsesBridge {
+  readonly baseUrl: string
+  readonly completedRequests: number
+  close(): Promise<void>
+}
+
+function readRequest(request: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    request.setEncoding('utf8')
+    request.on('data', (chunk: string) => {
+      body += chunk
+      if (Buffer.byteLength(body) > MAX_REQUEST_BYTES) {
+        request.destroy(new Error('DeepSeek bridge request exceeded its byte limit'))
+      }
+    })
+    request.on('end', () => { resolve(body) })
+    request.on('error', reject)
+  })
+}
+
+function responseInputTexts(body: Record<string, unknown>): string[] {
+  if (!Array.isArray(body.input)) return []
+  return body.input.flatMap((item): string[] => {
+    if (item === null || typeof item !== 'object') return []
+    const content = (item as Record<string, unknown>).content
+    if (!Array.isArray(content)) return []
+    return content.flatMap((part): string[] => (
+      part !== null
+      && typeof part === 'object'
+      && typeof (part as Record<string, unknown>).text === 'string'
+        ? [(part as Record<string, unknown>).text as string]
+        : []
+    ))
+  })
+}
+
+function taskText(body: Record<string, unknown>): string {
+  const input = responseInputTexts(body).join('\n')
+  if (input.trim().length > 0) return input
+  return typeof body.instructions === 'string' ? body.instructions : ''
+}
+
+function deepSeekBaseUrl(): string {
+  const configured = (process.env.DEEPSEEK_BASE_URL ?? OFFICIAL_DEEPSEEK_BASE_URL)
+    .replace(/\/+$/, '')
+  if (configured !== OFFICIAL_DEEPSEEK_BASE_URL) {
+    throw new Error('Codex DeepSeek e2e requires the official DeepSeek base URL')
+  }
+  return configured
+}
+
+async function completeWithDeepSeek(
+  authorization: string,
+  task: string,
+): Promise<string> {
+  const response = await fetch(`${deepSeekBaseUrl()}/chat/completions`, {
+    method: 'POST',
+    headers: {
+      authorization,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: 'deepseek-v4-flash',
+      messages: [
+        {
+          role: 'system',
+          content: 'Follow the user instruction and return only the requested nonce.',
+        },
+        { role: 'user', content: task },
+      ],
+      temperature: 0,
+      max_tokens: 64,
+      stream: false,
+    }),
+  })
+  if (!response.ok) {
+    void response.body?.cancel()
+    throw new Error(`DeepSeek bridge upstream returned HTTP ${response.status}`)
+  }
+  const payload = await response.json() as {
+    choices?: Array<{ message?: { content?: unknown } }>
+  }
+  const content = payload.choices?.[0]?.message?.content
+  if (typeof content !== 'string' || content.trim().length === 0) {
+    throw new Error('DeepSeek bridge upstream returned no text')
+  }
+  return content
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error !== undefined) reject(error)
+      else resolve()
+    })
+    server.closeAllConnections()
+  })
+}
+
+/**
+ * Start the single-purpose loopback bridge used by the Codex credentialed e2e.
+ * @param nonce - unique answer the incoming Responses task must request.
+ * @returns loopback endpoint, completion count, and close operation.
+ */
+export async function startDeepSeekResponsesBridge(
+  nonce: string,
+): Promise<DeepSeekResponsesBridge> {
+  let seenRequests = 0
+  let completedRequests = 0
+  const openResponses = new Set<ServerResponse>()
+  const server = createServer((request, response) => {
+    openResponses.add(response)
+    response.on('close', () => { openResponses.delete(response) })
+    void (async () => {
+      if (request.method !== 'POST' || request.url !== '/v1/responses') {
+        response.writeHead(404)
+        response.end()
+        return
+      }
+      if (seenRequests !== 0) {
+        response.writeHead(409)
+        response.end()
+        return
+      }
+      seenRequests += 1
+      const authorization = request.headers.authorization
+      if (
+        typeof authorization !== 'string'
+        || !authorization.startsWith('Bearer ')
+        || authorization.length === 'Bearer '.length
+      ) {
+        throw new Error('Codex DeepSeek bridge received no bearer credential')
+      }
+      const body = JSON.parse(await readRequest(request)) as Record<string, unknown>
+      const task = taskText(body)
+      if (!task.includes(nonce)) {
+        throw new Error('Codex DeepSeek bridge request omitted the expected nonce')
+      }
+      const text = await completeWithDeepSeek(authorization, task)
+      completedRequests += 1
+      response.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+        'x-request-id': 'req_deepseek_e2e',
+      })
+      for (const event of completeResponsesEvents(text)) {
+        response.write(`data: ${JSON.stringify(event)}\n\n`)
+      }
+      response.end('data: [DONE]\n\n')
+    })().catch(() => {
+      if (!response.headersSent) {
+        response.writeHead(502, { 'content-type': 'application/json' })
+      }
+      response.end(JSON.stringify({ error: { message: 'DeepSeek bridge request failed' } }))
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject)
+      resolve()
+    })
+  })
+  const address = server.address()
+  if (address === null || typeof address === 'string') {
+    throw new Error('DeepSeek bridge did not acquire a TCP port')
+  }
+  return {
+    baseUrl: `http://127.0.0.1:${address.port}/v1`,
+    get completedRequests(): number { return completedRequests },
+    async close(): Promise<void> {
+      for (const response of openResponses) response.destroy()
+      await closeServer(server)
+    },
+  }
+}
diff --git a/packages/subagent/subagent-codex/tests/loader-composition.e2e.ts b/packages/subagent/subagent-codex/tests/loader-composition.e2e.ts
new file mode 100644
index 0000000000..6c4019f8c8
--- /dev/null
+++ b/packages/subagent/subagent-codex/tests/loader-composition.e2e.ts
@@ -0,0 +1,53 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import {
+  LOADER_SMOKE_TEST_TIMEOUT_MS,
+  runLoaderSmoke,
+} from '@deepseek-ai/dsh-loader-smoke'
+
+const fixtureDir = fileURLToPath(new URL(
+  '../../../../examples/acp-agent/tests/fixtures/subagent/subagent-codex/',
+  import.meta.url,
+))
+const driver = join(fixtureDir, 'driver.ts')
+const configPath = join(fixtureDir, 'cordis.yml')
+const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+describe('Codex provider public Loader composition', () => {
+  it('loads the opt-in package and foreground tool without starting Codex', async () => {
+    const { stdout, stderr } = await runLoaderSmoke({
+      label: 'subagent-codex Loader composition',
+      tempDirPrefix: 'dsh-subagent-codex-loader-',
+      binScript: driver,
+      libBinScript: driver,
+      configPath,
+      tsconfigPath: repoTsconfig,
+      env: {
+        // Loading the optional package must not probe or start a Codex binary.
+        PATH: '',
+      },
+    })
+
+    expect(stderr).toBe('')
+    expect(JSON.parse(stdout)).toEqual({
+      providers: ['codex'],
+      provider: {
+        name: 'codex',
+        capabilities: {
+          outputSchema: false,
+          depthLimit: false,
+          toolFilter: false,
+          persona: false,
+        },
+        inheritsParentContext: false,
+      },
+      tool: {
+        name: 'subagent_codex',
+        parameterNames: ['description', 'prompt'],
+        required: ['description', 'prompt'],
+      },
+      starts: 0,
+    })
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
diff --git a/packages/subagent/subagent-codex/tests/real-deepseek.e2e.ts b/packages/subagent/subagent-codex/tests/real-deepseek.e2e.ts
new file mode 100644
index 0000000000..29c5536bc0
--- /dev/null
+++ b/packages/subagent/subagent-codex/tests/real-deepseek.e2e.ts
@@ -0,0 +1,141 @@
+import { execFile } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { delimiter, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import * as codex from '../src/index.ts'
+import {
+  startDeepSeekResponsesBridge,
+  type DeepSeekResponsesBridge,
+} from './deepseek-responses-bridge.ts'
+
+const execFileAsync = promisify(execFile)
+const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))
+const codexBinDir = join(packageRoot, 'node_modules', '.bin')
+const codexPackage = JSON.parse(readFileSync(
+  join(packageRoot, 'node_modules', '@openai', 'codex', 'package.json'),
+  'utf8',
+)) as { version: string }
+
+const roots: string[] = []
+const contexts: Context[] = []
+const bridges: DeepSeekResponsesBridge[] = []
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+  await Promise.all(bridges.splice(0).map(bridge => bridge.close()))
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+async function expectQuiescent(handles: readonly SubprocessHandle[]): Promise<void> {
+  expect(handles.length).toBeGreaterThan(0)
+  for (const handle of handles) {
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    await expect(handle.done).resolves.toHaveProperty('exitCode')
+  }
+}
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)(
+  'Codex provider with real DeepSeek API',
+  () => {
+    it('returns one unique nonce through the production provider and real Codex', async () => {
+      const apiKey = process.env.DEEPSEEK_API_KEY
+      if (apiKey === undefined) throw new Error('e2e ran without DEEPSEEK_API_KEY')
+      const root = mkdtempSync(join(tmpdir(), 'dsh-codex-deepseek-e2e-'))
+      roots.push(root)
+      const workspace = join(root, 'workspace')
+      const codexHome = join(root, 'codex-home')
+      mkdirSync(workspace)
+      mkdirSync(codexHome)
+      const nonce = `DSH_CODEX_DEEPSEEK_${randomUUID()}`
+      const bridge = await startDeepSeekResponsesBridge(nonce)
+      bridges.push(bridge)
+      writeFileSync(join(codexHome, 'config.toml'), [
+        'model = "deepseek-v4-flash"',
+        'model_provider = "deepseek-e2e"',
+        'approval_policy = "never"',
+        'sandbox_mode = "read-only"',
+        'disable_response_storage = true',
+        'check_for_update_on_startup = false',
+        '',
+        '[model_providers.deepseek-e2e]',
+        'name = "DeepSeek E2E bridge"',
+        `base_url = "${bridge.baseUrl}"`,
+        'env_key = "DEEPSEEK_API_KEY"',
+        'wire_api = "responses"',
+        'requires_openai_auth = false',
+        '',
+        '[analytics]',
+        'enabled = false',
+        '',
+      ].join('\n'))
+      const env = {
+        DEEPSEEK_API_KEY: apiKey,
+        CODEX_HOME: codexHome,
+        HOME: root,
+        XDG_CONFIG_HOME: join(root, 'xdg-config'),
+        PATH: `${codexBinDir}${delimiter}${process.env.PATH ?? ''}`,
+        HTTP_PROXY: '',
+        HTTPS_PROXY: '',
+        ALL_PROXY: '',
+        NO_PROXY: '127.0.0.1,localhost',
+      }
+      const ctx = new Context()
+      contexts.push(ctx)
+      await ctx.plugin(SubagentService)
+      await ctx.plugin(LocalSubprocessService)
+      const handles: SubprocessHandle[] = []
+      const spawn = ctx.subprocess.spawn.bind(ctx.subprocess)
+      vi.spyOn(ctx.subprocess, 'spawn').mockImplementation((spec) => {
+        const handle = spawn(spec)
+        handles.push(handle)
+        return handle
+      })
+      await ctx.plugin(codex, { env, disposeGraceMs: 2_000 })
+      const version = await execFileAsync(join(codexBinDir, 'codex'), ['--version'], {
+        env: { ...process.env, ...env },
+      })
+      expect(codexPackage.version).toBe('0.146.0')
+      expect(version.stdout.trim()).toBe('codex-cli 0.146.0')
+
+      const parent = {
+        id: 'deepseek-e2e-parent',
+        session: { header: { cwd: workspace } },
+      } as unknown as Agent
+      const run = await ctx.subagents.start('codex', {
+        prompt: [{
+          type: 'text',
+          text: `Reply with exactly ${nonce} and nothing else. Do not use tools.`,
+        }],
+        parent,
+        signal: new AbortController().signal,
+      })
+      const result = await run.result
+      await run.dispose()
+
+      expect(result.stopReason).toBe('completed')
+      const text = result.output
+        .filter(block => block.type === 'text')
+        .map(block => block.text)
+        .join('')
+        .trim()
+      expect(text).toBe(nonce)
+      expect(bridge.completedRequests).toBe(1)
+      await expectQuiescent(handles)
+    }, 180_000)
+  },
+)
diff --git a/packages/subagent/subagent-codex/tests/real-product.spec.ts b/packages/subagent/subagent-codex/tests/real-product.spec.ts
new file mode 100644
index 0000000000..5f73adaf7e
--- /dev/null
+++ b/packages/subagent/subagent-codex/tests/real-product.spec.ts
@@ -0,0 +1,225 @@
+import { execFile } from 'node:child_process'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import { delimiter, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import { Context } from 'cordis'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import * as codex from '../src/index.ts'
+import {
+  startResponsesFixture,
+  type ResponsesBehavior,
+  type ResponsesFixture,
+} from './responses-fixture.ts'
+
+const execFileAsync = promisify(execFile)
+const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)))
+const codexBinDir = join(packageRoot, 'node_modules', '.bin')
+const codexPackage = JSON.parse(readFileSync(
+  join(packageRoot, 'node_modules', '@openai', 'codex', 'package.json'),
+  'utf8',
+)) as { version: string }
+
+const roots: string[] = []
+const fixtures: ResponsesFixture[] = []
+const contexts: Context[] = []
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+  await Promise.all(fixtures.splice(0).map(fixture => fixture.close()))
+  for (const root of roots.splice(0)) {
+    rmSync(root, { recursive: true, force: true })
+  }
+})
+
+interface RealHarness {
+  readonly ctx: Context
+  readonly handles: SubprocessHandle[]
+  readonly parent: Agent
+  readonly env: Record<string, string>
+  readonly workspace: string
+}
+
+async function realHarness(script: readonly ResponsesBehavior[]): Promise<{
+  readonly harness: RealHarness
+  readonly fixture: ResponsesFixture
+}> {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-codex-real-'))
+  roots.push(root)
+  const workspace = join(root, 'workspace')
+  const codexHome = join(root, 'codex-home')
+  const fixture = await startResponsesFixture(script)
+  fixtures.push(fixture)
+  mkdirSync(workspace)
+  mkdirSync(codexHome)
+  writeFileSync(join(codexHome, 'config.toml'), [
+    'model = "fixture-model"',
+    'model_provider = "fixture"',
+    'approval_policy = "on-request"',
+    'sandbox_mode = "read-only"',
+    'disable_response_storage = true',
+    'check_for_update_on_startup = false',
+    '',
+    '[model_providers.fixture]',
+    'name = "Fixture Responses"',
+    `base_url = "${fixture.baseUrl}"`,
+    'env_key = "OPENAI_API_KEY"',
+    'wire_api = "responses"',
+    'requires_openai_auth = false',
+    '',
+    '[analytics]',
+    'enabled = false',
+    '',
+  ].join('\n'))
+  const env = {
+    OPENAI_API_KEY: 'dsh-fake-openai-key',
+    CODEX_HOME: codexHome,
+    HOME: root,
+    XDG_CONFIG_HOME: join(root, 'xdg'),
+    PATH: `${codexBinDir}${delimiter}${process.env.PATH ?? ''}`,
+    HTTP_PROXY: '',
+    HTTPS_PROXY: '',
+    ALL_PROXY: '',
+    NO_PROXY: '127.0.0.1,localhost',
+  }
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(SubagentService)
+  await ctx.plugin(LocalSubprocessService)
+  const handles: SubprocessHandle[] = []
+  const spawn = ctx.subprocess.spawn.bind(ctx.subprocess)
+  vi.spyOn(ctx.subprocess, 'spawn').mockImplementation((spec) => {
+    const handle = spawn(spec)
+    handles.push(handle)
+    return handle
+  })
+  await ctx.plugin(codex, { env, disposeGraceMs: 2_000 })
+  const parent = {
+    id: 'real-parent',
+    session: { header: { cwd: workspace } },
+  } as unknown as Agent
+  return { harness: { ctx, handles, parent, env, workspace }, fixture }
+}
+
+async function expectQuiescent(handles: readonly SubprocessHandle[]): Promise<void> {
+  expect(handles.length).toBeGreaterThan(0)
+  for (const handle of handles) {
+    await expect(handle.waitForExit()).resolves.toBe(true)
+    const outcome = await handle.done
+    expect(outcome).toHaveProperty('exitCode')
+    expect(outcome).toHaveProperty('signal')
+  }
+}
+
+function responseInputTexts(body: Record<string, unknown>): string[] {
+  if (!Array.isArray(body.input)) return []
+  return body.input.flatMap((item): string[] => {
+    if (item === null || typeof item !== 'object') return []
+    const content = (item as Record<string, unknown>).content
+    if (!Array.isArray(content)) return []
+    return content.flatMap((part): string[] => (
+      part !== null
+      && typeof part === 'object'
+      && typeof (part as Record<string, unknown>).text === 'string'
+        ? [(part as Record<string, unknown>).text as string]
+        : []
+    ))
+  })
+}
+
+describe('real @openai/codex 0.146.0 product', () => {
+  it('passes the exact task and fake authentication to local Responses and returns exact text', async () => {
+    const sentinel = 'REAL_CODEX_SENTINEL_0_146_0'
+    const task = 'Return the fixture sentinel exactly.'
+    const { harness, fixture } = await realHarness([
+      { kind: 'complete', text: sentinel },
+    ])
+    expect(codexPackage.version).toBe('0.146.0')
+    const version = await execFileAsync(join(codexBinDir, 'codex'), ['--version'], {
+      env: { ...process.env, ...harness.env },
+    })
+    expect(version.stdout.trim()).toBe('codex-cli 0.146.0')
+
+    const run = await harness.ctx.subagents.start('codex', {
+      prompt: [{ type: 'text', text: task }],
+      parent: harness.parent,
+      signal: new AbortController().signal,
+    })
+    await expect(run.result).resolves.toEqual({
+      output: [{ type: 'text', text: sentinel }],
+      stopReason: 'completed',
+    })
+    await run.dispose()
+
+    expect(fixture.requests).toHaveLength(1)
+    const recorded = fixture.requests[0]!
+    expect(recorded.method).toBe('POST')
+    expect(recorded.path).toBe('/v1/responses')
+    expect(recorded.headers.authorization).toBe('Bearer dsh-fake-openai-key')
+    expect(responseInputTexts(recorded.body)).toContain(task)
+    await expectQuiescent(harness.handles)
+  }, 60_000)
+
+  it('cancels a real app-server command approval without executing the command', async () => {
+    const { harness, fixture } = await realHarness([
+      {
+        kind: 'functionCall',
+        name: 'exec_command',
+        arguments: {
+          cmd: 'touch approval-side-effect',
+          sandbox_permissions: 'require_escalated',
+          justification: 'exercise the unattended approval boundary',
+        },
+      },
+    ])
+    const sideEffect = join(harness.workspace, 'approval-side-effect')
+    const run = await harness.ctx.subagents.start('codex', {
+      prompt: [{ type: 'text', text: 'Attempt the fixture command.' }],
+      parent: harness.parent,
+      signal: new AbortController().signal,
+    })
+    await expect(run.result).resolves.toEqual({
+      output: [],
+      stopReason: 'error',
+    })
+    await run.dispose()
+
+    expect(existsSync(sideEffect)).toBe(false)
+    expect(fixture.requests).toHaveLength(1)
+    const tools = fixture.requests[0]!.body.tools as Array<Record<string, unknown>>
+    expect(tools).toEqual(expect.arrayContaining([
+      expect.objectContaining({ type: 'function', name: 'exec_command' }),
+    ]))
+    expect(fixture.requests.every(requestEntry =>
+      requestEntry.headers.authorization === 'Bearer dsh-fake-openai-key',
+    )).toBe(true)
+    await expectQuiescent(harness.handles)
+  }, 60_000)
+
+  it('settles cancellation locally and leaves the real app-server tree quiescent', async () => {
+    const { harness, fixture } = await realHarness([{ kind: 'hold' }])
+    const controller = new AbortController()
+    const run = await harness.ctx.subagents.start('codex', {
+      prompt: [{ type: 'text', text: 'Wait for cancellation.' }],
+      parent: harness.parent,
+      signal: controller.signal,
+    })
+    await fixture.requestStarted
+    controller.abort(new Error('real product cancellation'))
+    await expect(run.result).resolves.toMatchObject({ stopReason: 'aborted' })
+    await run.dispose()
+    await expectQuiescent(harness.handles)
+  }, 60_000)
+})
diff --git a/packages/subagent/subagent-codex/tests/responses-fixture.ts b/packages/subagent/subagent-codex/tests/responses-fixture.ts
new file mode 100644
index 0000000000..cac49b9158
--- /dev/null
+++ b/packages/subagent/subagent-codex/tests/responses-fixture.ts
@@ -0,0 +1,288 @@
+import { createServer } from 'node:http'
+import type {
+  IncomingHttpHeaders,
+  IncomingMessage,
+  Server,
+  ServerResponse,
+} from 'node:http'
+
+/** One request observed by the package-private Responses fixture. */
+interface RecordedResponsesRequest {
+  readonly method: string | undefined
+  readonly path: string | undefined
+  readonly headers: IncomingHttpHeaders
+  readonly body: Record<string, unknown>
+}
+
+/** Behavior consumed by one Responses request. */
+export type ResponsesBehavior =
+  | { readonly kind: 'complete'; readonly text: string }
+  | {
+    readonly kind: 'functionCall'
+    readonly name: string
+    readonly arguments: Record<string, unknown>
+  }
+  | { readonly kind: 'hold' }
+
+/** Running package-private Responses fixture. */
+export interface ResponsesFixture {
+  readonly baseUrl: string
+  readonly requests: RecordedResponsesRequest[]
+  readonly requestStarted: Promise<void>
+  close(): Promise<void>
+}
+
+function responseObject(text: string): Record<string, unknown> {
+  const message = {
+    id: 'msg_fixture',
+    type: 'message',
+    status: 'completed',
+    role: 'assistant',
+    content: [{
+      type: 'output_text',
+      annotations: [],
+      logprobs: [],
+      text,
+    }],
+  }
+  return {
+    id: 'resp_fixture',
+    object: 'response',
+    created_at: 1,
+    status: 'completed',
+    background: false,
+    error: null,
+    incomplete_details: null,
+    instructions: null,
+    max_output_tokens: null,
+    max_tool_calls: null,
+    model: 'fixture-model',
+    output: [message],
+    parallel_tool_calls: true,
+    previous_response_id: null,
+    prompt_cache_key: null,
+    prompt_cache_retention: null,
+    reasoning: { effort: null, summary: null },
+    safety_identifier: null,
+    service_tier: 'default',
+    store: false,
+    temperature: null,
+    text: { format: { type: 'text' }, verbosity: 'medium' },
+    tool_choice: 'auto',
+    tools: [],
+    top_logprobs: 0,
+    top_p: null,
+    truncation: 'disabled',
+    usage: {
+      input_tokens: 10,
+      input_tokens_details: { cached_tokens: 0 },
+      output_tokens: 1,
+      output_tokens_details: { reasoning_tokens: 0 },
+      total_tokens: 11,
+    },
+    user: null,
+    metadata: {},
+  }
+}
+
+/**
+ * Build the minimal Responses SSE event sequence consumed by Codex 0.146.0.
+ * @param text - exact assistant answer.
+ * @returns ordered response lifecycle events.
+ */
+export function completeResponsesEvents(text: string): Record<string, unknown>[] {
+  const completed = responseObject(text)
+  const message = (completed.output as Record<string, unknown>[])[0]!
+  const part = (message.content as Record<string, unknown>[])[0]!
+  return [
+    {
+      type: 'response.created',
+      response: { ...completed, status: 'in_progress', output: [] },
+    },
+    {
+      type: 'response.output_item.added',
+      output_index: 0,
+      item: { ...message, status: 'in_progress', content: [] },
+    },
+    {
+      type: 'response.content_part.added',
+      item_id: message.id,
+      output_index: 0,
+      content_index: 0,
+      part: { ...part, text: '' },
+    },
+    {
+      type: 'response.output_text.delta',
+      item_id: message.id,
+      output_index: 0,
+      content_index: 0,
+      delta: text,
+      logprobs: [],
+    },
+    {
+      type: 'response.output_text.done',
+      item_id: message.id,
+      output_index: 0,
+      content_index: 0,
+      text,
+      logprobs: [],
+    },
+    {
+      type: 'response.content_part.done',
+      item_id: message.id,
+      output_index: 0,
+      content_index: 0,
+      part,
+    },
+    {
+      type: 'response.output_item.done',
+      output_index: 0,
+      item: message,
+    },
+    { type: 'response.completed', response: completed },
+  ]
+}
+
+function functionCallEvents(
+  name: string,
+  argumentsValue: Record<string, unknown>,
+): Record<string, unknown>[] {
+  const argumentsText = JSON.stringify(argumentsValue)
+  const item = {
+    id: 'fc_fixture',
+    type: 'function_call',
+    status: 'completed',
+    name,
+    arguments: argumentsText,
+    call_id: 'call_fixture',
+  }
+  const completed = {
+    ...responseObject(''),
+    output: [item],
+    usage: {
+      input_tokens: 10,
+      input_tokens_details: { cached_tokens: 0 },
+      output_tokens: 5,
+      output_tokens_details: { reasoning_tokens: 0 },
+      total_tokens: 15,
+    },
+  }
+  return [
+    {
+      type: 'response.created',
+      response: { ...completed, status: 'in_progress', output: [] },
+    },
+    {
+      type: 'response.output_item.added',
+      output_index: 0,
+      item: { ...item, status: 'in_progress', arguments: '' },
+    },
+    {
+      type: 'response.function_call_arguments.delta',
+      item_id: item.id,
+      output_index: 0,
+      delta: argumentsText,
+    },
+    {
+      type: 'response.function_call_arguments.done',
+      item_id: item.id,
+      output_index: 0,
+      arguments: argumentsText,
+    },
+    {
+      type: 'response.output_item.done',
+      output_index: 0,
+      item,
+    },
+    { type: 'response.completed', response: completed },
+  ]
+}
+
+function readRequest(request: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    request.setEncoding('utf8')
+    request.on('data', (chunk: string) => { body += chunk })
+    request.on('end', () => { resolve(body) })
+    request.on('error', reject)
+  })
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error !== undefined) reject(error)
+      else resolve()
+    })
+    server.closeAllConnections()
+  })
+}
+
+/**
+ * Start a loopback-only Responses SSE fixture.
+ * @param script - one behavior per expected Responses request.
+ * @returns the running fixture and its observed requests.
+ */
+export async function startResponsesFixture(
+  script: readonly ResponsesBehavior[],
+): Promise<ResponsesFixture> {
+  const behaviors = [...script]
+  const requests: RecordedResponsesRequest[] = []
+  const started = Promise.withResolvers<undefined>()
+  const openResponses = new Set<ServerResponse>()
+  const server = createServer((request, response) => {
+    openResponses.add(response)
+    response.on('close', () => { openResponses.delete(response) })
+    void readRequest(request).then((body) => {
+      requests.push({
+        method: request.method,
+        path: request.url,
+        headers: request.headers,
+        body: JSON.parse(body) as Record<string, unknown>,
+      })
+      started.resolve(undefined)
+      const behavior = behaviors.shift()
+      if (behavior === undefined) {
+        response.writeHead(500, { 'content-type': 'application/json' })
+        response.end(JSON.stringify({ error: { message: 'fixture script exhausted' } }))
+        return
+      }
+      response.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+        'x-request-id': 'req_fixture',
+      })
+      if (behavior.kind === 'hold') return
+      const events = behavior.kind === 'complete'
+        ? completeResponsesEvents(behavior.text)
+        : functionCallEvents(behavior.name, behavior.arguments)
+      for (const event of events) {
+        response.write(`data: ${JSON.stringify(event)}\n\n`)
+      }
+      response.end('data: [DONE]\n\n')
+    }).catch((error: unknown) => {
+      response.destroy(error instanceof Error ? error : new Error(String(error)))
+    })
+  })
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject)
+      resolve()
+    })
+  })
+  const address = server.address()
+  if (address === null || typeof address === 'string') {
+    throw new Error('responses fixture did not acquire a TCP port')
+  }
+  return {
+    baseUrl: `http://127.0.0.1:${address.port}/v1`,
+    requests,
+    requestStarted: started.promise,
+    async close(): Promise<void> {
+      for (const response of openResponses) response.destroy()
+      await closeServer(server)
+    },
+  }
+}
diff --git a/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts b/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts
new file mode 100644
index 0000000000..de89aa4854
--- /dev/null
+++ b/packages/subagent/subagent-codex/tests/subagent-codex.spec.ts
@@ -0,0 +1,1120 @@
+import { PassThrough } from 'node:stream'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { describe, expect, it, vi } from 'vitest'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import SubagentService from '@deepseek-ai/dsh-subagent'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import type {
+  SubprocessHandle,
+  SubprocessOutcome,
+} from '@deepseek-ai/dsh-subprocess'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+import * as codex from '../src/index.ts'
+import * as invariant from '../src/invariant.ts'
+import {
+  codexAppServerArgv,
+  DEFAULT_DISPOSE_GRACE_MS,
+  disposeCodexChild,
+  startCodexRun,
+  textTask,
+  type CodexRunSpec,
+} from '../src/run.ts'
+import { CodexAppServerWire } from '../src/wire.ts'
+
+type JsonObject = Record<string, unknown>
+
+const fakeParent = {
+  id: 'parent',
+  session: { header: { cwd: process.cwd() } },
+} as unknown as Agent
+
+function request(
+  prompt: ContentBlock[] = [{ type: 'text', text: 'do the task' }],
+  signal = new AbortController().signal,
+) {
+  return { prompt, parent: fakeParent, signal }
+}
+
+async function nextTask(): Promise<void> {
+  await new Promise<void>((resolve) => { setImmediate(resolve) })
+}
+
+class ProtocolPeer {
+  private buffer = ''
+  private readonly frames: JsonObject[] = []
+  private readonly wakeups = new Set<() => void>()
+
+  constructor(
+    input: PassThrough,
+    private readonly output: PassThrough,
+  ) {
+    input.on('data', (chunk: Buffer | string) => {
+      this.buffer += chunk.toString()
+      for (;;) {
+        const newline = this.buffer.indexOf('\n')
+        if (newline < 0) break
+        const line = this.buffer.slice(0, newline)
+        this.buffer = this.buffer.slice(newline + 1)
+        if (line.trim().length > 0) this.frames.push(JSON.parse(line) as JsonObject)
+      }
+      for (const wake of this.wakeups) wake()
+      this.wakeups.clear()
+    })
+  }
+
+  async next(predicate: (frame: JsonObject) => boolean): Promise<JsonObject> {
+    for (;;) {
+      const index = this.frames.findIndex(predicate)
+      if (index >= 0) return this.frames.splice(index, 1)[0]!
+      await new Promise<void>((resolve) => { this.wakeups.add(resolve) })
+    }
+  }
+
+  nextMethod(method: string): Promise<JsonObject> {
+    return this.next(frame => frame.method === method)
+  }
+
+  nextResponse(id: unknown): Promise<JsonObject> {
+    return this.next(frame => frame.id === id && frame.method === undefined)
+  }
+
+  send(...frames: readonly JsonObject[]): void {
+    this.output.write(`${frames.map(frame => JSON.stringify(frame)).join('\n')}\n`)
+  }
+
+  respond(requestFrame: JsonObject, result: unknown): void {
+    this.send({ id: requestFrame.id, result })
+  }
+}
+
+interface FakeChildOptions {
+  readonly pid?: number
+  readonly exitOnTerminate?: boolean
+  readonly doneError?: Error
+}
+
+interface FakeChild {
+  readonly handle: SubprocessHandle
+  readonly peer: ProtocolPeer
+  readonly fromChild: PassThrough
+  readonly toChild: PassThrough
+  readonly settle: (outcome?: SubprocessOutcome) => void
+  readonly fail: (error: Error) => void
+  readonly terminate: () => void
+  readonly waitForExit: (signal?: AbortSignal) => Promise<boolean>
+}
+
+function fakeChild(options: FakeChildOptions = {}): FakeChild {
+  const fromChild = new PassThrough()
+  const toChild = new PassThrough()
+  const peer = new ProtocolPeer(toChild, fromChild)
+  let exited = false
+  let resolveDone!: (outcome: SubprocessOutcome) => void
+  let rejectDone!: (error: Error) => void
+  const done = new Promise<SubprocessOutcome>((resolve, reject) => {
+    resolveDone = resolve
+    rejectDone = reject
+  })
+  const settle = (
+    outcome: SubprocessOutcome = { exitCode: 0, signal: null },
+  ): void => {
+    if (exited) return
+    exited = true
+    resolveDone(outcome)
+  }
+  const fail = (error: Error): void => {
+    if (exited) return
+    exited = true
+    rejectDone(error)
+  }
+  if (options.doneError !== undefined) fail(options.doneError)
+  const terminate = vi.fn(() => {
+    if (options.exitOnTerminate !== false) settle()
+  })
+  const waitForExit = vi.fn(async (signal?: AbortSignal) => {
+    if (exited) return true
+    if (signal === undefined) {
+      await done.catch(() => {})
+      return true
+    }
+    return await new Promise<boolean>((resolve) => {
+      const onAbort = (): void => { resolve(false) }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void done.then(
+        () => {
+          signal.removeEventListener('abort', onAbort)
+          resolve(true)
+        },
+        () => {
+          signal.removeEventListener('abort', onAbort)
+          resolve(true)
+        },
+      )
+    })
+  })
+  const handle: SubprocessHandle = {
+    pid: options.pid ?? 1234,
+    stdin: toChild,
+    stdout: fromChild,
+    stderr: undefined,
+    collected: {},
+    done,
+    terminate,
+    waitForExit,
+  }
+  return {
+    handle,
+    peer,
+    fromChild,
+    toChild,
+    settle,
+    fail,
+    terminate,
+    waitForExit,
+  }
+}
+
+function runSpec(
+  child: FakeChild,
+  overrides: Partial<CodexRunSpec> = {},
+): CodexRunSpec {
+  return {
+    cwd: process.cwd(),
+    env: {},
+    disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
+    spawn: () => child.handle,
+    ...overrides,
+  }
+}
+
+async function initializeWire(): Promise<{
+  readonly child: FakeChild
+  readonly wire: CodexAppServerWire
+}> {
+  const child = fakeChild()
+  const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+  wire.start()
+  const initializing = wire.initialize(new AbortController().signal)
+  const initialize = await child.peer.nextMethod('initialize')
+  child.peer.respond(initialize, { userAgent: 'codex-cli 0.146.0' })
+  await initializing
+  expect(await child.peer.nextMethod('initialized')).toEqual({
+    jsonrpc: '2.0',
+    method: 'initialized',
+  })
+  const starting = wire.startThread(process.cwd(), new AbortController().signal)
+  const threadStart = await child.peer.nextMethod('thread/start')
+  child.peer.respond(threadStart, { thread: { id: 'thread-1', ephemeral: true } })
+  await starting
+  return { child, wire }
+}
+
+async function publishRun(
+  child = fakeChild(),
+  signal = new AbortController().signal,
+  specOverrides: Partial<CodexRunSpec> = {},
+) {
+  const starting = startCodexRun(request(undefined, signal), runSpec(child, specOverrides))
+  const initialize = await child.peer.nextMethod('initialize')
+  child.peer.respond(initialize, { userAgent: 'codex-cli 0.146.0' })
+  await child.peer.nextMethod('initialized')
+  const threadStart = await child.peer.nextMethod('thread/start')
+  child.peer.respond(threadStart, { thread: { id: 'thread-1', ephemeral: true } })
+  const run = await starting
+  const turnStart = await child.peer.nextMethod('turn/start')
+  return { child, run, turnStart }
+}
+
+function agentMessage(
+  text: unknown,
+  phase: unknown,
+  turnId = 'turn-1',
+  threadId = 'thread-1',
+): JsonObject {
+  return {
+    method: 'item/completed',
+    params: {
+      threadId,
+      turnId,
+      item: { type: 'agentMessage', text, phase },
+    },
+  }
+}
+
+function turnCompleted(
+  status: unknown,
+  turnId = 'turn-1',
+  threadId = 'thread-1',
+  error: unknown = null,
+): JsonObject {
+  return {
+    method: 'turn/completed',
+    params: {
+      threadId,
+      turn: { id: turnId, status, error },
+    },
+  }
+}
+
+describe('task admission and package contracts', () => {
+  it('resolves the fixed app-server command through the Windows npm shim boundary', () => {
+    expect(codexAppServerArgv('win32')).toEqual([
+      'cmd.exe',
+      '/d',
+      '/s',
+      '/c',
+      'codex',
+      'app-server',
+      '--stdio',
+    ])
+    expect(codexAppServerArgv('linux')).toEqual(['codex', 'app-server', '--stdio'])
+  })
+
+  it('accepts one or more text blocks and rejects empty or non-text tasks', () => {
+    expect(textTask([
+      { type: 'text', text: 'one' },
+      { type: 'text', text: 'two' },
+    ])).toEqual(['one', 'two'])
+    expect(() => textTask([])).toThrow('only text blocks')
+    expect(() => textTask([{ type: 'reasoning', text: 'hidden' }]))
+      .toThrow('only text blocks')
+    expect(() => textTask([{ type: 'text', text: ' \n ' }]))
+      .toThrow('must not be empty')
+  })
+
+  it('registers one fixed descriptor, validates config, and unregisters on HMR', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
+    const fiber = await ctx.plugin(codex, {})
+    const provider = ctx.subagents.getProvider('codex')!
+    expect(provider).toMatchObject({
+      name: 'codex',
+      capabilities: {
+        outputSchema: false,
+        depthLimit: false,
+        toolFilter: false,
+        persona: false,
+      },
+      inheritsParentContext: false,
+    })
+    expect(ctx.subagents.list()).toEqual(['codex'])
+    await fiber.dispose()
+    expect(ctx.subagents.list()).toEqual([])
+
+    for (const disposeGraceMs of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      await expect(ctx.plugin(codex, { disposeGraceMs }))
+        .rejects.toThrow('disposeGraceMs must be a positive finite number')
+    }
+    await expect(ctx.plugin(codex, { disposeGraceMs: MAX_TIMER_DELAY_MS + 1 }))
+      .rejects.toThrow(`disposeGraceMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
+    await ctx.fiber.dispose()
+  })
+
+  it('requires a parent session cwd without suggesting unsupported config', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
+    const spawn = vi.spyOn(ctx.subprocess, 'spawn')
+    await ctx.plugin(codex, {})
+
+    await expect(ctx.subagents.start('codex', {
+      prompt: [{ type: 'text', text: 'task' }],
+      parent: {
+        id: 'parent-without-cwd',
+        session: { header: {} },
+      } as unknown as Agent,
+      signal: new AbortController().signal,
+    })).rejects.toThrow(
+      'subagent-codex: no working directory for the child — delegate from a parent session that has one',
+    )
+    expect(spawn).not.toHaveBeenCalled()
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps the namespace export shape and package-owned empty invariant', async () => {
+    expect('default' in codex).toBe(false)
+    expect(codex.name).toBe('subagent-codex')
+    expect(codex.inject).toEqual(['subagents', 'subprocess'])
+    const loader = Object.create(Loader.prototype) as Loader
+    expect(loader.unwrapExports(codex)).toBe(codex)
+
+    const dispose = vi.fn()
+    const register = vi.fn((
+      _packageName: string,
+      _installer: InvariantInstaller,
+    ) => dispose)
+    const ctx = { invariants: { register } } as unknown as Context
+    await expect(invariant.apply(ctx)).resolves.toBe(dispose)
+    expect(register).toHaveBeenCalledWith(
+      '@deepseek-ai/dsh-subagent-codex',
+      expect.any(Function),
+    )
+    const install = register.mock.calls[0]![1]
+    await install(new Context(), (message) => { throw new Error(message) })
+    expect(invariant.name).toBe('subagent-codex-invariant')
+    expect(invariant.inject).toEqual(['invariants'])
+  })
+})
+
+describe('CodexAppServerWire', () => {
+  it('sends the fixed handshake, thread, and turn payloads and keeps final_answer', async () => {
+    const child = fakeChild()
+    const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+    expect(wire.collectOutput()).toEqual([])
+    wire.start()
+
+    const initializing = wire.initialize(new AbortController().signal)
+    const initialize = await child.peer.nextMethod('initialize')
+    expect(initialize.params).toEqual({
+      clientInfo: {
+        name: 'deepseek-harness',
+        title: 'DeepSeek Harness',
+        version: '0.0.1',
+      },
+      capabilities: {
+        experimentalApi: false,
+        requestAttestation: false,
+      },
+    })
+    child.peer.respond(initialize, { userAgent: 'codex-cli 0.146.0' })
+    await initializing
+    await child.peer.nextMethod('initialized')
+
+    const starting = wire.startThread('/workspace', new AbortController().signal)
+    const threadStart = await child.peer.nextMethod('thread/start')
+    expect(threadStart.params).toEqual({ cwd: '/workspace', ephemeral: true })
+    child.peer.respond(threadStart, { thread: { id: 'thread-1', ephemeral: true } })
+    await starting
+
+    const result = wire.runTurn(
+      ['first', 'second'],
+      new AbortController().signal,
+    )
+    const turnStart = await child.peer.nextMethod('turn/start')
+    expect(turnStart.params).toEqual({
+      threadId: 'thread-1',
+      input: [
+        { type: 'text', text: 'first', text_elements: [] },
+        { type: 'text', text: 'second', text_elements: [] },
+      ],
+    })
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    await nextTask()
+    child.peer.send(
+      {
+        method: 'turn/started',
+        params: { threadId: 'thread-1', turn: { id: 'turn-1' } },
+      },
+      agentMessage('other thread', 'final_answer', 'turn-1', 'thread-2'),
+      agentMessage('other turn', 'final_answer', 'turn-2'),
+      {
+        method: 'item/completed',
+        params: {
+          threadId: 'thread-1',
+          turnId: 'turn-1',
+          item: { type: 'reasoning', text: 'not output' },
+        },
+      },
+      agentMessage('commentary', 'commentary'),
+      agentMessage('unphased', null),
+      agentMessage('first final', 'final_answer'),
+      agentMessage('last final', 'final_answer'),
+      turnCompleted('completed'),
+    )
+    await expect(result).resolves.toEqual({
+      output: [{ type: 'text', text: 'last final' }],
+      stopReason: 'completed',
+    })
+    expect(wire.collectOutput()).toEqual([{ type: 'text', text: 'last final' }])
+    wire.close()
+    wire.close()
+  })
+
+  it('uses the last nullable-phase answer when no explicit final exists', async () => {
+    const { child, wire } = await initializeWire()
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    child.peer.send(
+      agentMessage('first', null),
+      agentMessage('fallback', null),
+      turnCompleted('completed'),
+    )
+    await expect(result).resolves.toEqual({
+      output: [{ type: 'text', text: 'fallback' }],
+      stopReason: 'completed',
+    })
+    wire.close()
+  })
+
+  it('maps only an explicit context-window failure to max-tokens', async () => {
+    const { child, wire } = await initializeWire()
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    child.peer.send(
+      agentMessage('partial answer', null),
+      turnCompleted('failed', 'turn-1', 'thread-1', {
+        message: 'too much context',
+        codexErrorInfo: 'contextWindowExceeded',
+      }),
+    )
+    await expect(result).resolves.toEqual({
+      output: [{ type: 'text', text: 'partial answer' }],
+      stopReason: 'max-tokens',
+    })
+    wire.close()
+  })
+
+  it('rejects invalid handshake, thread, and turn response shapes', async () => {
+    {
+      const child = fakeChild()
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      wire.start()
+      const pending = wire.initialize(new AbortController().signal)
+      const frame = await child.peer.nextMethod('initialize')
+      child.peer.respond(frame, null)
+      await expect(pending).rejects.toThrow('invalid initialize response')
+      wire.close()
+    }
+    {
+      const child = fakeChild()
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      wire.start()
+      const pending = wire.startThread('/workspace', new AbortController().signal)
+      const frame = await child.peer.nextMethod('thread/start')
+      child.peer.respond(frame, { thread: { id: 'thread-1', ephemeral: false } })
+      await expect(pending).rejects.toThrow('did not create an ephemeral thread')
+      wire.close()
+    }
+    {
+      const { child, wire } = await initializeWire()
+      const pending = wire.runTurn(['task'], new AbortController().signal)
+      const frame = await child.peer.nextMethod('turn/start')
+      child.peer.respond(frame, { turn: { id: '' } })
+      await expect(pending).rejects.toThrow('turn/start turn id')
+      wire.close()
+    }
+  })
+
+  it('fails closed for empty output, malformed messages, phases, and terminal status', async () => {
+    const scenarios: Array<{
+      readonly frames: JsonObject[]
+      readonly message: string
+    }> = [
+      {
+        frames: [turnCompleted('completed')],
+        message: 'without a final answer',
+      },
+      {
+        frames: [
+          agentMessage('fallback', null),
+          agentMessage(' \n ', 'final_answer'),
+          turnCompleted('completed'),
+        ],
+        message: 'without a final answer',
+      },
+      {
+        frames: [agentMessage(42, 'final_answer')],
+        message: 'invalid agent message',
+      },
+      {
+        frames: [agentMessage('answer', 'future_phase')],
+        message: 'unknown agent message phase',
+      },
+      {
+        frames: [turnCompleted('failed', 'turn-1', 'thread-1', { message: 'no' })],
+        message: 'status failed',
+      },
+      {
+        frames: [turnCompleted('interrupted')],
+        message: 'status interrupted',
+      },
+      {
+        frames: [turnCompleted('inProgress')],
+        message: 'invalid terminal turn status',
+      },
+    ]
+    for (const scenario of scenarios) {
+      const { child, wire } = await initializeWire()
+      const result = wire.runTurn(['task'], new AbortController().signal)
+      const turnStart = await child.peer.nextMethod('turn/start')
+      child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+      child.peer.send(...scenario.frames)
+      await expect(result).rejects.toThrow(scenario.message)
+      wire.close()
+    }
+  })
+
+  it('fails closed when terminal notification params are not an object', async () => {
+    const { child, wire } = await initializeWire()
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    child.peer.send({ method: 'turn/completed', params: null })
+    await expect(result).rejects.toThrow('invalid turn/completed thread id')
+    wire.close()
+  })
+
+  it('keeps an unsupported request authoritative over an early terminal in the same chunk', async () => {
+    const { child, wire } = await initializeWire()
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.send(
+      { id: turnStart.id, result: { turn: { id: 'turn-1' } } },
+      { id: 'future-request', method: 'future/request', params: {} },
+      agentMessage('early answer', 'final_answer'),
+      turnCompleted('completed'),
+    )
+    await expect(result).rejects.toThrow('unsupported app-server request')
+    wire.close()
+  })
+
+  it('answers all five unattended request classes without granting authority', async () => {
+    const { child, wire } = await initializeWire()
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+
+    child.peer.send({
+      id: 'command',
+      method: 'item/commandExecution/requestApproval',
+      params: {
+        threadId: 'thread-1',
+        turnId: 'turn-1',
+        availableDecisions: ['decline', 'cancel'],
+      },
+    })
+    expect(await child.peer.nextResponse('command')).toMatchObject({
+      result: { decision: 'cancel' },
+    })
+
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    await nextTask()
+    const requests = [
+      {
+        id: 'file',
+        method: 'item/fileChange/requestApproval',
+        params: {
+          threadId: 'thread-1',
+          turnId: 'turn-1',
+          availableDecisions: ['decline'],
+        },
+        result: { decision: 'decline' },
+      },
+      {
+        id: 'file-default',
+        method: 'item/fileChange/requestApproval',
+        params: { threadId: 'thread-1', turnId: 'turn-1' },
+        result: { decision: 'decline' },
+      },
+      {
+        id: 'permissions',
+        method: 'item/permissions/requestApproval',
+        params: { threadId: 'thread-1', turnId: 'turn-1' },
+        result: { permissions: {}, scope: 'turn' },
+      },
+      {
+        id: 'user-input',
+        method: 'item/tool/requestUserInput',
+        params: { threadId: 'thread-1', turnId: 'turn-1', questions: [] },
+        result: { answers: {} },
+      },
+      {
+        id: 'mcp',
+        method: 'mcpServer/elicitation/request',
+        params: { threadId: 'thread-1', turnId: null },
+        result: { action: 'decline', content: null, _meta: null },
+      },
+    ] as const
+    for (const serverRequest of requests) {
+      child.peer.send(serverRequest)
+      expect(await child.peer.nextResponse(serverRequest.id)).toMatchObject({
+        result: serverRequest.result,
+      })
+    }
+
+    child.peer.send(agentMessage('answer', 'final_answer'), turnCompleted('completed'))
+    await expect(result).resolves.toMatchObject({ stopReason: 'completed' })
+    wire.close()
+  })
+
+  it('fails the run on unknown requests or wrong request association', async () => {
+    for (const serverRequest of [
+      {
+        id: 'unknown',
+        method: 'future/request',
+        params: { threadId: 'thread-1', turnId: 'turn-1' },
+      },
+      {
+        id: 'approval',
+        method: 'item/commandExecution/requestApproval',
+        params: {
+          threadId: 'thread-1',
+          turnId: 'turn-1',
+          availableDecisions: ['accept'],
+        },
+      },
+      {
+        id: 'malformed-approval',
+        method: 'item/fileChange/requestApproval',
+        params: {
+          threadId: 'thread-1',
+          turnId: 'turn-1',
+          availableDecisions: 'decline',
+        },
+      },
+      {
+        id: 'thread',
+        method: 'item/fileChange/requestApproval',
+        params: { threadId: 'thread-2', turnId: 'turn-1' },
+      },
+      {
+        id: 'turn',
+        method: 'item/fileChange/requestApproval',
+        params: { threadId: 'thread-1', turnId: 'turn-2' },
+      },
+    ]) {
+      const { child, wire } = await initializeWire()
+      const result = wire.runTurn(['task'], new AbortController().signal)
+      const turnStart = await child.peer.nextMethod('turn/start')
+      child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+      await nextTask()
+      child.peer.send(serverRequest)
+      const response = await child.peer.nextResponse(serverRequest.id)
+      expect(response.error).toMatchObject({ code: -32603 })
+      await expect(result).rejects.toThrow()
+      wire.close()
+    }
+  })
+
+  it('rejects conflicting early turn identities before accepting output', async () => {
+    const { child, wire } = await initializeWire()
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.send({
+      method: 'turn/started',
+      params: { threadId: 'thread-1', turn: { id: 'turn-early' } },
+    })
+    child.peer.respond(turnStart, { turn: { id: 'turn-response' } })
+    await expect(result).rejects.toThrow('did not match the active turn')
+    wire.close()
+  })
+
+  it('rejects conflicting early notifications and requests before turn/start', async () => {
+    {
+      const { child, wire } = await initializeWire()
+      child.peer.send({
+        id: 'too-early',
+        method: 'item/fileChange/requestApproval',
+        params: { threadId: 'thread-1', turnId: 'turn-1' },
+      })
+      const response = await child.peer.nextResponse('too-early')
+      expect(response.error).toMatchObject({ code: -32603 })
+      wire.close()
+    }
+    {
+      const { child, wire } = await initializeWire()
+      const result = wire.runTurn(['task'], new AbortController().signal)
+      await child.peer.nextMethod('turn/start')
+      child.peer.send(
+        {
+          method: 'turn/started',
+          params: { threadId: 'thread-1', turn: { id: 'turn-1' } },
+        },
+        agentMessage('wrong', 'final_answer', 'turn-2'),
+      )
+      await expect(result).rejects.toThrow('conflicting turns')
+      wire.close()
+    }
+  })
+
+  it('interrupts only an active open turn and contains remote interrupt failure', async () => {
+    const { child, wire } = await initializeWire()
+    wire.interrupt()
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    await nextTask()
+    wire.interrupt()
+    const interrupt = await child.peer.nextMethod('turn/interrupt')
+    expect(interrupt.params).toEqual({ threadId: 'thread-1', turnId: 'turn-1' })
+    child.peer.send({
+      id: interrupt.id,
+      error: { code: -32000, message: 'already done' },
+    })
+    child.peer.send(agentMessage('answer', 'final_answer'), turnCompleted('completed'))
+    await expect(result).resolves.toMatchObject({ stopReason: 'completed' })
+    wire.close()
+    wire.interrupt()
+  })
+
+  it('ignores unrelated and out-of-window notifications', async () => {
+    const { child, wire } = await initializeWire()
+    child.peer.send(
+      {
+        method: 'turn/started',
+        params: { threadId: 'thread-2', turn: { id: 'turn-other' } },
+      },
+      {
+        method: 'turn/started',
+        params: { threadId: 'thread-1', turn: { id: 'turn-before' } },
+      },
+      agentMessage('before', 'final_answer'),
+      { method: 'future/notification', params: {} },
+      turnCompleted('completed'),
+      turnCompleted('completed', 'turn-other', 'thread-2'),
+    )
+    await nextTask()
+
+    const result = wire.runTurn(['task'], new AbortController().signal)
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    await nextTask()
+    child.peer.send(
+      agentMessage('wrong turn', 'final_answer', 'turn-2'),
+      turnCompleted('completed', 'turn-2'),
+      agentMessage('answer', 'final_answer'),
+      turnCompleted('completed'),
+    )
+    await expect(result).resolves.toEqual({
+      output: [{ type: 'text', text: 'answer' }],
+      stopReason: 'completed',
+    })
+    wire.close()
+  })
+
+  it('rejects pending work on abort, EOF, and stream error', async () => {
+    {
+      const child = fakeChild()
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      wire.start()
+      const controller = new AbortController()
+      controller.abort('pre-aborted')
+      await expect(wire.initialize(controller.signal))
+        .rejects.toThrow('app-server request aborted: pre-aborted')
+      wire.close()
+    }
+    {
+      const child = fakeChild()
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      wire.start()
+      const controller = new AbortController()
+      const pending = wire.initialize(controller.signal)
+      await child.peer.nextMethod('initialize')
+      controller.abort(new Error('cancel initialize'))
+      await expect(pending).rejects.toThrow('cancel initialize')
+      wire.close()
+    }
+    {
+      const child = fakeChild()
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      wire.start()
+      const pending = wire.initialize(new AbortController().signal)
+      await child.peer.nextMethod('initialize')
+      child.fromChild.end()
+      await expect(pending).rejects.toThrow(/(?:protocol stream|JSON-RPC input) closed/)
+      wire.close()
+    }
+    {
+      const child = fakeChild()
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      wire.start()
+      const pending = wire.initialize(new AbortController().signal)
+      await child.peer.nextMethod('initialize')
+      child.fromChild.emit('error', new Error('stdout broke'))
+      await expect(pending).rejects.toThrow('stdout broke')
+      wire.close()
+    }
+    {
+      const child = fakeChild()
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      wire.start()
+      const pending = wire.initialize(new AbortController().signal)
+      await child.peer.nextMethod('initialize')
+      child.toChild.emit('error', new Error('stdin broke'))
+      await expect(pending).rejects.toThrow('stdin broke')
+      wire.close()
+      child.toChild.emit('error', new Error('late stdin close'))
+    }
+  })
+})
+
+describe('run lifecycle and quiescence', () => {
+  it('spawns the fixed app-server, publishes after thread creation, and disposes once', async () => {
+    const child = fakeChild()
+    const spawn = vi.fn(() => child.handle)
+    const starting = startCodexRun(
+      request([{ type: 'text', text: 'task' }]),
+      runSpec(child, { env: { OPENAI_API_KEY: 'fake' }, spawn }),
+    )
+    let published = false
+    void starting.then(() => { published = true })
+    const initialize = await child.peer.nextMethod('initialize')
+    expect(published).toBe(false)
+    child.peer.respond(initialize, { userAgent: 'codex-cli 0.146.0' })
+    await child.peer.nextMethod('initialized')
+    const threadStart = await child.peer.nextMethod('thread/start')
+    expect(published).toBe(false)
+    child.peer.respond(threadStart, { thread: { id: 'thread-1', ephemeral: true } })
+    const run = await starting
+    expect(spawn).toHaveBeenCalledWith({
+      argv: codexAppServerArgv(),
+      cwd: process.cwd(),
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'inherit' },
+      graceMs: DEFAULT_DISPOSE_GRACE_MS,
+      env: { OPENAI_API_KEY: 'fake' },
+    })
+    expect(run.localAgent).toBeUndefined()
+
+    const turnStart = await child.peer.nextMethod('turn/start')
+    child.peer.send(
+      { id: turnStart.id, result: { turn: { id: 'turn-1' } } },
+      agentMessage('answer', 'final_answer'),
+      turnCompleted('completed'),
+    )
+    await expect(run.result).resolves.toEqual({
+      output: [{ type: 'text', text: 'answer' }],
+      stopReason: 'completed',
+    })
+    const disposal = run.dispose()
+    expect(run.dispose()).toBe(disposal)
+    await disposal
+    await nextTask()
+    expect(child.terminate).toHaveBeenCalledTimes(1)
+    expect(child.waitForExit).toHaveBeenCalledTimes(1)
+  })
+
+  it('settles local cancellation immediately and sends best-effort interrupt', async () => {
+    const controller = new AbortController()
+    const { child, run, turnStart } = await publishRun(
+      fakeChild(),
+      controller.signal,
+    )
+    child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+    await nextTask()
+    controller.abort(new Error('stop'))
+    await expect(run.result).resolves.toEqual({
+      output: [],
+      stopReason: 'aborted',
+    })
+    expect(await child.peer.nextMethod('turn/interrupt')).toMatchObject({
+      params: { threadId: 'thread-1', turnId: 'turn-1' },
+    })
+    await run.dispose()
+  })
+
+  it('flattens child exit and protocol failures after publication', async () => {
+    const errors: string[] = []
+    {
+      const child = fakeChild({ exitOnTerminate: false })
+      const { run } = await publishRun(child, undefined, {
+        onError: (error) => { errors.push(error.message) },
+      })
+      child.settle({ exitCode: 9, signal: null })
+      await expect(run.result).resolves.toEqual({ output: [], stopReason: 'error' })
+      expect(errors.at(-1)).toContain('code 9')
+      await run.dispose().catch(() => {})
+    }
+    {
+      const child = fakeChild()
+      const { run, turnStart } = await publishRun(child, undefined, {
+        onError: () => { throw new Error('diagnostic sink') },
+      })
+      child.peer.respond(turnStart, { turn: { id: 'turn-1' } })
+      child.fromChild.end()
+      await expect(run.result).resolves.toEqual({ output: [], stopReason: 'error' })
+      await run.dispose()
+    }
+  })
+
+  it('rejects before spawn when pre-aborted and rolls back startup failures', async () => {
+    const controller = new AbortController()
+    controller.abort()
+    const spawn = vi.fn()
+    await expect(startCodexRun(
+      request(undefined, controller.signal),
+      {
+        cwd: process.cwd(),
+        env: {},
+        disposeGraceMs: 10,
+        spawn,
+      },
+    )).rejects.toThrow('aborted before app-server startup')
+    expect(spawn).not.toHaveBeenCalled()
+
+    const child = fakeChild()
+    const starting = startCodexRun(request(), runSpec(child))
+    const initialize = await child.peer.nextMethod('initialize')
+    child.peer.respond(initialize, null)
+    await expect(starting).rejects.toThrow('invalid initialize response')
+    expect(child.terminate).toHaveBeenCalledTimes(1)
+  })
+
+  it('rolls back an abort that wins immediately after thread creation', async () => {
+    const controller = new AbortController()
+    const child = fakeChild()
+    const starting = startCodexRun(
+      request(undefined, controller.signal),
+      runSpec(child),
+    )
+    const initialize = await child.peer.nextMethod('initialize')
+    child.peer.respond(initialize, { userAgent: 'codex-cli 0.146.0' })
+    await child.peer.nextMethod('initialized')
+    const threadStart = await child.peer.nextMethod('thread/start')
+    child.peer.respond(threadStart, { thread: { id: 'thread-1', ephemeral: true } })
+    controller.abort('startup race')
+    await expect(starting).rejects.toThrow('aborted before run publication')
+    expect(child.terminate).toHaveBeenCalledTimes(1)
+  })
+
+  it('rolls back a subprocess done rejection during startup', async () => {
+    const child = fakeChild({ doneError: new Error('spawn observer failed') })
+    const error: unknown = await startCodexRun(request(), runSpec(child)).then(
+      () => undefined,
+      (failure: unknown) => failure,
+    )
+    expect(error).toBeInstanceOf(AggregateError)
+    if (!(error instanceof AggregateError)) {
+      throw new Error('expected startup and rollback failures')
+    }
+    expect(error.errors).toEqual([
+      expect.objectContaining({ message: 'spawn observer failed' }),
+      expect.objectContaining({ message: 'spawn observer failed' }),
+    ])
+    expect(child.terminate).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps overlapping runs isolated', async () => {
+    const first = fakeChild()
+    const second = fakeChild()
+    const runs = await Promise.all([
+      publishRun(first),
+      publishRun(second),
+    ])
+    for (const [index, entry] of runs.entries()) {
+      const id = `turn-${index + 1}`
+      entry.child.peer.send(
+        { id: entry.turnStart.id, result: { turn: { id } } },
+        agentMessage(`answer-${index + 1}`, 'final_answer', id),
+        turnCompleted('completed', id),
+      )
+    }
+    const results = await Promise.all(runs.map(entry => entry.run.result))
+    expect(results.map(result => result.output)).toEqual([
+      [{ type: 'text', text: 'answer-1' }],
+      [{ type: 'text', text: 'answer-2' }],
+    ])
+    expect(runs[0].run.id).not.toBe(runs[1].run.id)
+    await Promise.all(runs.map(entry => entry.run.dispose()))
+  })
+
+  it('uses the registered provider config and logs flattened errors', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SubagentService)
+    await ctx.plugin(LocalSubprocessService)
+    const child = fakeChild()
+    const spawn = vi.spyOn(ctx.subprocess, 'spawn').mockReturnValue(child.handle)
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: unknown) => {
+      warnings.push(String(message))
+    }) as typeof ctx.logger.warn
+    await ctx.plugin(codex, {
+      env: { OPENAI_API_KEY: 'fake' },
+      disposeGraceMs: 25,
+    })
+    const starting = ctx.subagents.start('codex', {
+      prompt: [{ type: 'text', text: 'task' }],
+      parent: fakeParent,
+      signal: new AbortController().signal,
+    })
+    const initialize = await child.peer.nextMethod('initialize')
+    child.peer.respond(initialize, { userAgent: 'codex-cli 0.146.0' })
+    await child.peer.nextMethod('initialized')
+    const threadStart = await child.peer.nextMethod('thread/start')
+    child.peer.respond(threadStart, { thread: { id: 'thread-1', ephemeral: true } })
+    const run = await starting
+    await child.peer.nextMethod('turn/start')
+    child.settle({ exitCode: 1, signal: null })
+    await expect(run.result).resolves.toMatchObject({ stopReason: 'error' })
+    expect(spawn).toHaveBeenCalledWith(expect.objectContaining({
+      env: { OPENAI_API_KEY: 'fake' },
+      graceMs: 25,
+      cwd: process.cwd(),
+    }))
+    expect(warnings).toEqual([
+      expect.stringContaining('subagent-codex: child run failed (error):'),
+    ])
+    await run.dispose().catch(() => {})
+    await ctx.fiber.dispose()
+  })
+})
+
+describe('disposeCodexChild', () => {
+  it('closes stdin, terminates, and waits for the managed tree', async () => {
+    const child = fakeChild()
+    const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+    const end = vi.spyOn(child.toChild, 'end')
+    await disposeCodexChild(wire, child.handle)
+    expect(end).toHaveBeenCalled()
+    expect(child.terminate).toHaveBeenCalledTimes(1)
+    expect(child.waitForExit).toHaveBeenCalledTimes(1)
+    expect(child.waitForExit).toHaveBeenCalledWith()
+  })
+
+  it('does not finish disposal before the managed tree exits', async () => {
+    const child = fakeChild({ exitOnTerminate: false })
+    const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+    let disposed = false
+    const disposal = disposeCodexChild(wire, child.handle).then(() => {
+      disposed = true
+    })
+    await new Promise<void>((resolve) => { setImmediate(resolve) })
+    expect(disposed).toBe(false)
+    child.settle()
+    await disposal
+    expect(disposed).toBe(true)
+  })
+
+  it('contains a concurrently closed stdin error', async () => {
+    const child = fakeChild()
+    const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+    vi.spyOn(child.toChild, 'end').mockImplementation(() => {
+      throw new Error('already closed')
+    })
+    await expect(disposeCodexChild(wire, child.handle))
+      .resolves.toBeUndefined()
+  })
+
+  it('handles a spawn-level failure with no process tree', async () => {
+    const child = fakeChild({
+      pid: -1,
+      doneError: new Error('spawn failed'),
+    })
+    const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+    await expect(disposeCodexChild(wire, child.handle))
+      .resolves.toBeUndefined()
+    expect(child.terminate).not.toHaveBeenCalled()
+    expect(child.waitForExit).not.toHaveBeenCalled()
+  })
+
+  it('reports direct-child observer failure and accepts absent stdin', async () => {
+    {
+      const child = fakeChild({
+        doneError: new Error('close observer failed'),
+      })
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      await expect(disposeCodexChild(wire, child.handle))
+        .rejects.toThrow('close observer failed')
+    }
+    {
+      const child = fakeChild()
+      const handle = { ...child.handle, stdin: undefined }
+      const wire = new CodexAppServerWire(child.handle.stdout!, child.handle.stdin!)
+      await expect(disposeCodexChild(wire, handle)).resolves.toBeUndefined()
+    }
+  })
+})
diff --git a/packages/subagent/subagent-codex/tsconfig.json b/packages/subagent/subagent-codex/tsconfig.json
new file mode 100644
index 0000000000..b9f33967ba
--- /dev/null
+++ b/packages/subagent/subagent-codex/tsconfig.json
@@ -0,0 +1,45 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../sdk/sdk-protocol"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../subagent"
+    },
+    {
+      "path": "../../subprocess/subprocess"
+    },
+    {
+      "path": "../../util/timeout"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml
index c8aefc7533..f5ceedc743 100644
--- 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: a21aa6ae2822d68d513fd9409d77b3f3bf74a7a3
-README.zh.md: 3caa612aefcdac4f1dcdbcf4a3c1b81adc52c3d3
+README.md: 9d2e38c8730f7b7f26e690aa878a4466fa7c2829
+README.zh.md: 341c18617af4d040ec44814fac1ec4502d9b8902
diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md
index a21aa6ae28..9d2e38c873 100644
--- a/packages/subagent/subagent/README.md
+++ b/packages/subagent/subagent/README.md
@@ -21,7 +21,7 @@ The [subagent family overview](../README.md) maps implementations and model-faci
 | `reportFrom(child, content, { delivery, signal })` | Deliver one selected message from the exact live continuable child to its exact live direct parent and return the accepted stable `MessageId`. Quiet delivery injects context; waking delivery submits one later parent turn. |
 | `registerContinuableSetup(contribution)` | Compose an optional deployment capability into each continuable child's unpublished scope, with immediate revocation from resident children. |
 | `drainContinuableDescendants(parents)` | Close admission below exact live host-owned parent Agents, stop only their visible continuable descendants, await materializations admitted below those roots through publication or rollback, then release the selected forests child-first. The cutoff lasts until each exact parent leaves the registry; unrelated parent forests and manager-wide admission remain live. |
-| `listChildren(parentSessionId, signal?)` | List direct session-backed subagents with their `one-shot`/`continuable` mode, `running`/`inactive` activity, origin-classified one-level `hasChildren` hint, and per-child diagnostics, in stable trace order without loading or resuming them. Requires session query; it does not require `ctx.agents` or the continuation manager. |
+| `listChildren(parentSessionId, signal?)` | List direct session-backed subagents with their `one-shot`/`continuable` mode, `running`/`inactive` activity, origin-classified one-level `hasChildren` hint, and per-child diagnostics, ordered by `createdAt` then id, without loading or resuming them. Reads the live session store and optional session persistence directly (live-only enumeration when persistence is absent) and requires the mounted `sessionProjections` registry; it does not require `ctx.agents`, the continuation manager, or any query service. |
 
 `SubagentStartRequest.label` is an optional short durable display label for a session-backed one-shot child. Model-facing delegation supplies its existing `description`; lower-level callers need not invent presentation metadata. Continuable starts always carry their own required label. `signal` is required and is the canonical cancellation channel for a one-shot `start`. An abort before publication makes `start()` reject after rollback; an abort after publication cancels the returned run's remaining turn work without hiding its id. The request may also select a model, require structured output, cap delegation depth, restrict child tools, or set a child persona. For a continuable start or follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance; afterward the manager owns the Activation independently, so later caller cancellation neither cancels the accepted turn nor disposes the child.
 
@@ -48,7 +48,7 @@ The seam owns the versioned `subagent/descriptor` session event vocabulary (`src
 
 The seam owns the depth vocabulary shared by implementations and consumers: the `AgentOptions.subagentDepth` declaration, `assertSubagentMaxDepth`, and `delegationDepthOf(agent)`. The persisted `SessionHeader.delegationDepth` is authoritative and monotone — runtime options may deepen the count but never lower it, so a resumed child cannot be re-counted as top-level.
 
-`inheritsParentContext` is descriptive rather than enforceable. It says only whether the child sees completed parent conversation history (`fork` does; `spawn` and ACP do not), not whether it inherits tools, services, or authority.
+`inheritsParentContext` is descriptive rather than enforceable. It says only whether the child sees completed parent conversation history (`fork` does; `spawn` and the out-of-process one-shot providers do not), not whether it inherits tools, services, or authority.
 
 ## One-shot ownership and lifecycle
 
@@ -78,13 +78,13 @@ Provider additions and removals also emit `subagent/provider-added` and `subagen
 
 Continuable children do not create `SubagentRun` or Tasks. The continuation manager directly owns one process-local Activation and retained `AgentHandle` per resident child Session, uses the Agent inbox as the only FIFO, and cold-resumes from the durable descriptor. Exact live direct-parent identity authorizes parent-to-child delivery. Exact live child identity authorizes reports; the manager derives the recipient from durable `parentSession`, and `MessageSource` remains provenance rather than authority.
 
-When `ctx.sessionProjections` is available, the service registers `subagentTiming`. The projection resets at each descriptor so a fork seed's ancestor work cannot enter the child's total, then accumulates `turn/start` → `turn/end` active time and retains same-cut `active.since` and `active.through` bounds for an open turn. While that turn remains open, `active.through` follows the latest folded event, giving an inactive consumer a conservative crash bound without mixing in newer session metadata.
+When `ctx.sessionProjections` is available, the service registers two projection units. `subagentTiming` resets at each descriptor so a fork seed's ancestor work cannot enter the child's total, then accumulates `turn/start` → `turn/end` active time and retains same-cut `active.since` and `active.through` bounds for an open turn; while that turn remains open, `active.through` follows the latest folded event, giving an inactive consumer a conservative crash bound without mixing in newer session metadata. `subagent` folds the durable identity — mode plus creation label — from `subagent/descriptor` events with the same last-wins reset discipline, so a fork seed's ancestor descriptor stands only until the child's own overrides it; a malformed or unrecognized-version payload folds to the serializable `null` sentinel — indistinguishable from a log with no descriptor, and surviving every JSON push frame so a consumer replaces a stale identity instead of keeping it — and never throws.
 
 `registerContinuableSetup()` lets optional packages add child-scoped capabilities without teaching the continuation manager their names. Contributions install synchronously before Activation publication, roll back with failed setup, and are released with the child scope. New grants wait for the next Activation, while contribution removal revokes every resident installation immediately.
 
 ## Collection model
 
-The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task, no result promise, and no public subagent cancellation — a caller sends later work with the `send_message` follow-up tool, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` resolves session query and dynamically imports its optional runtime only when called, then interprets a read-only live-preferred scan of all descriptor-bearing direct children without consulting the continuation manager, Agent registrations, Activations, or providers. Each healthy row derives its read-time `hasChildren` hint from traced direct-descendant headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The scan forwards the caller's signal to cancellable trace and exact-read operations, checks cancellation around the remaining event-list read, and reports every observed abort as `SubagentError` code `CANCELLED`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
+The model-facing tool collects synchronously by default: it awaits the child result and disposes the run before returning. One-shot background delegation registers a plain Task in the tool, whose generic status, collection, and cancellation tools own later interaction, and persists its model-supplied `description` as the optional display label. Continuable background delegation calls `ctx.subagents.startContinuable()` and returns only the durable child id; the child owns its own turns from inbox acceptance, so there is no Task, no result promise, and no public subagent cancellation — a caller sends later work with the `send_message` follow-up tool, and the durable child Session remains the source of the child's detailed output. The continuation manager exists only while `ctx.agents` is available, and session persistence is resolved per continuation operation. Independently, `listChildren()` enumerates the live-preferred merge of the live session store and optional session persistence — live-only when persistence is absent, since a cold child cannot be resumed then either — and serves each child's durable mode/label from the registered `subagent` projection unit: the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when it serves an own-suffix identity — its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended — else one bounded-concurrency persistence inspection folded through the registry, whose result must still name the enumerated lifecycle (a re-published id degrades to a `corrupt` diagnostic). A throwing cache read renders no verdict — the cache is derived data — and silently falls through to that authoritative re-fold. The projection fold is the single classification authority; listing parses no descriptor itself. A served identity produces a child row; a settled candidate whose fold served no identity is a `corrupt` diagnostic, a failed inspection is a transient `unavailable` retried on the next listing, and a running candidate without an identity yet is omitted (the creation window before its descriptor is appended). It never consults the continuation manager, Agent registrations, Activations, or providers. Each child row derives its read-time `hasChildren` hint from merged headers carrying durable `origin: 'subagent'`; it does not read descendant event logs, and the descriptor-backed child catalog remains authoritative when expanded. Service consumers such as a UI can retain both modes and choose a fallback for an unlabeled one-shot child; the model-facing `list_agents` tool projects only `continuable` entries and maps service activity to its existing `running`/`complete` vocabulary. The listing forwards the caller's signal to every persistence read, checks cancellation around each of those awaits, and reports every observed abort as `SubagentError` code `CANCELLED`; an unmounted projection registry fails loud with `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE`, and a missing session store with `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE`. See the [background subagent tasks Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md), the [continuable background subagents Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md), the [durable catalog Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md), the [merged-service Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md), the [capability-seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md), and `src/types.ts` for the complete contracts.
 
 Continuable Activations await a best-effort final session flush without treating listener participation as durability confirmation. One-shot runs retain best-effort session checkpointing, so a completed one-shot child is discoverable after disposal only when its session actually reached persistence; the service does not invent a catalog entry from Task history when that checkpoint is absent.
 
diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md
index 3caa612aef..341c18617a 100644
--- a/packages/subagent/subagent/README.zh.md
+++ b/packages/subagent/subagent/README.zh.md
@@ -21,7 +21,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 | `reportFrom(child, content, { delivery, signal })` | 从确切在线可继续 child 向其确切在线直接 parent 投递一条选中消息，并返回已接受的稳定 `MessageId`。静默投递会注入上下文；唤醒投递会提交一个后续 parent 轮次。 |
 | `registerContinuableSetup(contribution)` | 把一项可选部署能力组合到每个可继续 child 尚未发布的作用域中，并支持从驻留 child 立即撤销。 |
 | `drainContinuableDescendants(parents)` | 在由 host 确切拥有的在线 parent Agent 之下关闭准入，只停止其可见的可继续后代，等待在这些根之下已获准的物化过程完成发布或回滚，再按 child-first 顺序释放所选森林。该截止状态会持续到每个确切 parent 离开注册表；无关的 parent 森林和管理器全局准入保持在线。 |
-| `listChildren(parentSessionId, signal?)` | 按稳定的追踪顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。要求会话查询；不要求 `ctx.agents` 或继续执行管理器。 |
+| `listChildren(parentSessionId, signal?)` | 按 `createdAt` 再按 id 的顺序列出由会话支撑的直接 subagent，包括其 `one-shot`／`continuable` 模式、`running`／`inactive` 活动状态、基于 origin 分类的一层 `hasChildren` 提示与逐 child diagnostic，且不会加载或恢复它们。直接读取在线会话存储与可选的会话持久化（持久化缺席时仅枚举在线 child），并要求已挂载 `sessionProjections` 注册表；不要求 `ctx.agents`、继续执行管理器或任何查询服务。 |
 
 `SubagentStartRequest.label` 是由会话支撑的一次性 child 所使用的可选简短持久化显示标签。面向模型的委派会提供其已有的 `description`；底层调用方无需凭空构造展示元数据。可继续启动始终携带自身的必填标签。`signal` 是必填项，也是一次性 `start` 的规范取消通道。发布前中止会使 `start()` 在回滚后拒绝；发布后中止会取消已返回 run 的剩余轮次工作，但不会隐藏其 id。请求还可以选择模型、要求结构化输出、限制委派深度、约束子 agent 工具或设置子 agent persona。对于可继续启动或后续操作，调用方信号只在 inbox 接受之前掌管查找、物化和准入；此后由管理器独立拥有 Activation，因此调用方后续取消既不会取消已接受的轮次，也不会 dispose（资源释放）子 agent。
 
@@ -48,7 +48,7 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 该 seam 拥有实现和消费方共享的深度词汇：`AgentOptions.subagentDepth` 声明、`assertSubagentMaxDepth` 和 `delegationDepthOf(agent)`。持久化的 `SessionHeader.delegationDepth` 具有权威性且单调：运行时选项可以加深计数，但绝不能降低它，因此恢复后的子 agent 不会被重新计为顶层。
 
-`inheritsParentContext` 只用于描述，不能强制执行。它仅说明子 agent 是否能看到父级已完成的对话历史（`fork` 可以；`spawn` 和 ACP（Agent Client Protocol）不可以），不表示是否继承工具、服务或权限。
+`inheritsParentContext` 只用于描述，不能强制执行。它仅说明子 agent 是否能看到父级已完成的对话历史（`fork` 可以；`spawn` 和各进程外一次性提供方不可以），不表示是否继承工具、服务或权限。
 
 ## 一次性所有权与生命周期
 
@@ -78,13 +78,13 @@ subagent seam 允许一个 agent（智能体）通过具名提供方把工作委
 
 可继续子级不会创建 `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 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。
+当 `ctx.sessionProjections` 可用时，服务会注册两个投影单元。`subagentTiming` 会在每个描述符处重置，使 fork 种子中的祖先工作不会计入 child 总量，随后累加 `turn/start` → `turn/end` 活跃时间，并为未结束的轮次保留同一切面的 `active.since` 和 `active.through` 边界；在该轮次保持未结束期间，`active.through` 会跟随最近折叠的事件，从而为 inactive 消费方提供保守的崩溃上界，又不会混入更新的会话元数据。`subagent` 以同样的 last-wins 重置纪律从 `subagent/descriptor` 事件折叠持久化身份——模式与创建标签——因此 fork 种子中的祖先描述符只在 child 自身的描述符覆盖之前有效；畸形或版本不识别的载荷折叠为可序列化的 `null` 哨兵——与没有描述符的日志不可区分，且能完好通过每个 JSON 推送帧，让消费方以之替换掉手中过时的身份而非永久滞留——绝不抛错。
 
 `registerContinuableSetup()` 允许可选包添加子级作用域能力，而无需让继续执行管理器知道这些能力的名称。贡献会在 Activation 发布前同步安装，在设置失败时一并回滚，并随子级作用域释放。新授权须等到下一个 Activation，移除贡献则会立即撤销每个驻留安装项。
 
 ## 收集模型
 
-面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、没有结果 promise，也没有公开的子 agent 取消操作——调用方通过 `send_message` 后续操作工具发送后续工作，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 只在被调用时解析会话查询并动态导入其可选运行时，然后解释对所有带描述符的直接 child 所作的只读、实时优先扫描，且不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个健康条目都会根据追踪结果中携带持久化 `origin: 'subagent'` 的直接后代 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。扫描会把调用方的取消信号转发到可取消的追踪与精确读取操作，在其余事件列表读取的前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
+面向模型的工具默认同步收集：先等待子 agent 结果，再 dispose 运行，然后才返回。一次性后台委派会在工具中注册普通 Task，其通用状态、收集和取消工具负责后续交互，并将模型提供的 `description` 持久化为可选显示标签。可继续后台委派会调用 `ctx.subagents.startContinuable()`，只返回持久化子 agent id；子 agent 自 inbox 接受起就拥有自己的轮次，因此没有 Task、没有结果 promise，也没有公开的子 agent 取消操作——调用方通过 `send_message` 后续操作工具发送后续工作，而持久化子 agent Session 仍是子 agent 详细输出的来源。只有 `ctx.agents` 可用时，继续执行管理器才会存在，而会话持久化按每项继续执行操作解析。与此独立，`listChildren()` 枚举在线会话存储与可选会话持久化的在线优先合并——持久化缺席时仅枚举在线 child，因为那时冷 child 本就无法恢复——并由已注册的 `subagent` 投影单元供给每个 child 的持久化模式与标签：在线 child 取注册表的水位快照；冷 child 先取可选投影缓存的持久化行，且仅当其 `seq` 门证明该值折叠自 child 自身后缀（fork 种子之后——自有描述符一经追加即不可变）才直接采用，否则经一次有界并发的持久化 inspect 再经注册表折叠，且 inspect 结果必须仍指向枚举时的生命周期（同 id 被重新发布的会话降级为 `corrupt` diagnostic）。缓存读取抛错不产生判决——缓存是派生数据——静默落到该权威重折。投影折叠是唯一的分类权威；列表自身不解析任何描述符。取得身份值即产出 child 行；已定局而折叠未产出身份的候选是 `corrupt` diagnostic，inspect 失败是瞬时的 `unavailable`（下次列表重试），运行中而暂无身份值的候选整行省略（描述符尚未追加的创建窗口）。它不查询继续执行管理器、Agent 注册信息、Activation 或提供方。每个 child 行都会根据合并结果中携带持久化 `origin: 'subagent'` 的 header 派生读取时的 `hasChildren` 提示；它不会读取后代事件日志，展开后仍以描述符支撑的 child 目录为权威依据。UI 等服务消费方可以保留两种模式，并为无标签的一次性 child 选择回退展示；面向模型的 `list_agents` 工具只投影 `continuable` 条目，并将服务活动状态映射到现有的 `running`／`complete` 词汇。列表操作会把调用方的取消信号转发到每次持久化读取，在这些 await 前后检查取消，并将每次检测到的中止报告为 `SubagentError` 错误码 `CANCELLED`；投影注册表未挂载则以 `SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE` 响亮失败，会话存储缺失则以 `SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE` 响亮失败。完整契约见[后台 subagent 任务 Agent Note](../../../.agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.md)、[可继续后台 subagent Agent Note](../../../.agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.md)、[持久化目录 Agent Note](../../../.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md)、[服务合并 Agent Note](../../../.agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.md)、[能力 seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)和 `src/types.ts`。
 
 可继续 Activation 会等待 best-effort 的最终会话 flush，但不会把 listener 参与视为持久性确认。一次性运行保留尽力执行的会话检查点，因此已完成的一次性 child 只有在其会话确实进入持久化存储时，才可在 dispose 后继续被发现；如果该检查点缺失，服务不会根据 Task 历史虚构目录条目。
 
diff --git a/packages/subagent/subagent/package.json b/packages/subagent/subagent/package.json
index c00caf7fb9..ba1dd0fbc4 100644
--- a/packages/subagent/subagent/package.json
+++ b/packages/subagent/subagent/package.json
@@ -40,8 +40,8 @@
     "@deepseek-ai/dsh-scope": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence": "^0.0.1",
-    "@deepseek-ai/dsh-session-query": "^0.0.1",
     "@deepseek-ai/dsh-session-projection": "^0.0.1",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.0.1",
     "@deepseek-ai/dsh-tasks": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
@@ -50,10 +50,10 @@
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
-    "@deepseek-ai/dsh-session-query": {
+    "@deepseek-ai/dsh-session-projection": {
       "optional": true
     },
-    "@deepseek-ai/dsh-session-projection": {
+    "@deepseek-ai/dsh-session-projection-cache": {
       "optional": true
     },
     "@deepseek-ai/dsh-tasks": {
@@ -68,8 +68,10 @@
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
-    "@deepseek-ai/dsh-session-query": "workspace:^",
     "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "@deepseek-ai/dsh-storage-domain": "workspace:^",
     "@deepseek-ai/dsh-tasks": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.7"
diff --git a/packages/subagent/subagent/src/client.ts b/packages/subagent/subagent/src/client.ts
index 928637dc7a..602dcd8793 100644
--- a/packages/subagent/subagent/src/client.ts
+++ b/packages/subagent/subagent/src/client.ts
@@ -4,4 +4,4 @@
  * @module @deepseek-ai/dsh-subagent/client
  */
 
-export type { SubagentTimingProjection } from './projection-types.ts'
+export type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts'
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 975d07ce4c..5bcd53d6a5 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -20,8 +20,8 @@
  * continuation manager holds their `AgentHandle` directly and orders every turn
  * through the child's own inbox, so providers contribute only the detached
  * creation spec and see no handle, turn, or teardown. Direct-child discovery
- * independently interprets the optional session-query corpus and does not
- * require that continuation runtime.
+ * reads the live session store and optional session persistence directly and
+ * does not require that continuation runtime.
  *
  * Same-process providers are trusted typed collaborators. Requests, provider
  * descriptors, results, and lifecycle payloads are borrowed immutable values;
@@ -65,7 +65,7 @@ import type { ContinuableSetupContribution } from './activation-setup-registry.t
 import { listChildren as listSubagentChildren } from './list-children.ts'
 import type { SubagentListEntry } from './list-children.ts'
 import { snapshotSubagentDescriptor } from './descriptor.ts'
-import { subagentTimingProjectionDefinition } from './projection.ts'
+import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from './projection.ts'
 
 export * from './out-of-process.ts'
 export { SubagentRunId } from './types.ts'
@@ -118,7 +118,7 @@ export type {
 export type { ContinuableSetupContribution } from './activation-setup-registry.ts'
 export type { SubagentListEntry } from './list-children.ts'
 export type { SubagentRunEndInfo, SubagentRunInfo } from './types.ts'
-export type { SubagentTimingProjection } from './projection-types.ts'
+export type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -190,6 +190,7 @@ export class SubagentService extends Service {
     })
     ctx.inject(['sessionProjections'], (projectionCtx) => {
       projectionCtx.sessionProjections.register(subagentTimingProjectionDefinition)
+      projectionCtx.sessionProjections.register(subagentIdentityProjectionDefinition)
     })
   }
 
@@ -283,22 +284,32 @@ export class SubagentService extends Service {
   }
 
   /**
-   * Enumerate the parent's direct session-backed subagents from the
-   * live-preferred session corpus without loading or resuming an Agent. Session
-   * query supplies lineage, candidate order, event reads, and live state; this
-   * service interprets descriptor mode, activity, and per-child diagnostics
-   * without consulting Agent registrations, Activations, or providers.
+   * Enumerate the parent's direct session-backed subagents without loading or
+   * resuming an Agent and without any query seam: the listing merges the live
+   * session store with optional session persistence (live-preferred) and
+   * serves each child's durable mode/label from the registered `subagent`
+   * projection unit down a three-rung ladder — the registry's watermark
+   * snapshot for a live child; for a cold one, a durable projection-cache
+   * row when the optional cache serves an own-suffix identity (its `seq`
+   * gate proves the value postdates the fork seed, where a child's own
+   * descriptor is immutable once appended), else one persistence inspection
+   * folded through the registry. The
+   * projection fold is the single classification authority; per-child
+   * diagnostics relay a fold that served no identity or a failed inspection,
+   * never a list-time descriptor parse. Absent persistence, enumeration is
+   * live-only (a cold child cannot be resumed then either, so its absence is
+   * capability absence, not an error). This service consults no Agent
+   * registrations, Activations, or providers.
    *
-   * The trace and exact descriptor read receive `signal`; the full event-list
-   * read has no signal parameter, so the scan rechecks cancellation around
-   * every await and between candidates. Query rejections that settle after an
-   * abort become a stable `SubagentError` with code `CANCELLED`.
+   * Every persistence read receives `signal`, and the listing rechecks
+   * cancellation around each of those awaits. Read rejections that settle
+   * after an abort become a stable `SubagentError` with code `CANCELLED`.
    * @param parentSessionId - parent session whose direct children are listed.
-   * @param signal - caller-owned cancellation forwarded where supported and
-   *   observed around every query await.
-   * @returns children and per-child diagnostics in stable trace order.
-   * @throws {@link SubagentError} when session query is unavailable or the
-   *   caller cancels the scan.
+   * @param signal - caller-owned cancellation forwarded to persistence reads
+   *   and observed around every read await.
+   * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+   * @throws {@link SubagentError} when the projection registry or the session
+   *   store is not mounted, or the caller cancels the listing.
    */
   listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]> {
     return listSubagentChildren(this.ctx, parentSessionId, signal)
diff --git a/packages/subagent/subagent/src/list-children.ts b/packages/subagent/subagent/src/list-children.ts
index cabbec121d..fef098f90f 100644
--- a/packages/subagent/subagent/src/list-children.ts
+++ b/packages/subagent/subagent/src/list-children.ts
@@ -1,33 +1,47 @@
 /**
- * Read-only interpretation of session-query lineage as durable subagent
- * 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.
+ * Read-only enumeration of one parent's durable subagent children straight
+ * from the live session store and optional session persistence — no query
+ * seam. Candidates are the live-preferred merge of both listings filtered to
+ * durable `origin: 'subagent'` under the parent; each child's mode/label is
+ * the registered `subagent` projection unit's value, resolved down a
+ * three-rung ladder: the registry's watermark cache for a live child, a
+ * durable projection-cache row when it serves an own-suffix identity (the
+ * seq gate), and one persistence inspection folded through the registry
+ * otherwise, validated against the enumerated lifecycle. The projection
+ * fold is the single
+ * classification authority — this module parses no descriptor itself. Absent
+ * persistence, enumeration is live-only: a cold child is unreachable for
+ * resume anyway, so its absence is capability absence, not an error. The
+ * module owns no catalog state and does not consult Activation,
+ * Agent-registry, continuation-manager, or provider state.
  *
  * @module @deepseek-ai/dsh-subagent
  */
 
 import type { Context } from 'cordis'
-import type { SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionQueryService, SessionRecord } from '@deepseek-ai/dsh-session-query'
-import type SubagentService from './index.ts'
+import type { Session, SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
+import type { SessionProjectionRegistry } from '@deepseek-ai/dsh-session-projection'
+import type { SessionProjectionCache } from '@deepseek-ai/dsh-session-projection-cache'
 import { SubagentError } from './error.ts'
-import { foldSubagentDescriptor } from './descriptor.ts'
-
-type SessionQueryRuntime = Pick<
-  typeof import('@deepseek-ai/dsh-session-query'),
-  'assertSessionHeadersCompatible' | 'SessionQueryError'
->
+import type { SubagentIdentityProjection } from './projection-types.ts'
 
 /**
- * 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.
+ * Concurrent cold inspections per listing; a constant because it bounds one
+ * read-only scan of local media, not deployment behavior. Should a networked
+ * persistence backend appear, promote it to a validated `Config` field.
+ */
+const COLD_READ_CONCURRENCY = 4
+
+/**
+ * One entry of a {@link listChildren} result, ordered by header `createdAt`
+ * with ties broken on id. Only a candidate whose durable header has
+ * `origin: 'subagent'` is interpreted. A served `subagent` projection value
+ * produces a `child`; a settled candidate whose fold served no identity
+ * produces a `diagnostic`; a running candidate without one is omitted — its
+ * descriptor may not be appended yet (the creation window). Diagnostics
+ * relay the projection fold's outcome or a failed read, never a per-child
+ * event scan, and never expose model-hidden descriptor content.
  */
 export type SubagentListEntry =
   | {
@@ -35,7 +49,7 @@ export type SubagentListEntry =
     /** The durable child session id, stable across Activations. */
     readonly id: SessionId
     /**
-     * Corpus snapshot activity: `running` means the logical record is live in
+     * Store snapshot activity: `running` means the logical record is live in
      * `ctx.sessions`; `inactive` means it exists only in persistence. Neither
      * encodes a durable outcome, and a continuable child may still reject
      * delivery as an ownership conflict.
@@ -59,179 +73,263 @@ export type SubagentListEntry =
   )
   | {
     readonly kind: 'diagnostic'
-    /** The traced candidate's session id. */
+    /** The candidate's session id. */
     readonly id: SessionId
     /**
-     * Why the candidate was omitted: `corrupt` for invalid surfaces, header
-     * conflicts, or malformed/duplicated descriptors; `unsupported` for an
-     * unknown descriptor version; `unavailable` when the child disappeared or
-     * its per-child read hit a persistence failure.
+     * Why the candidate has no `child` row: `corrupt` for a settled candidate
+     * whose projection fold served no identity (a missing, malformed, or
+     * unrecognized-version descriptor — deliberately undistinguished), and
+     * for any candidate whose log makes a registered unit's fold or schema
+     * throw (deterministic data damage, contained per child); `unavailable`
+     * when the candidate's persistence inspection failed (retried on the
+     * next listing). `unsupported` is kept for consumers already routing on
+     * it but is no longer produced.
      */
     readonly reason: 'corrupt' | 'unsupported' | 'unavailable'
   }
 
 /**
- * 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.
+ * Enumerate one parent's origin-classified direct children from the
+ * live-preferred merge of `ctx.sessions` and optional session persistence,
+ * serving each identity from the `subagent` projection unit: the registry's
+ * watermark snapshot for a live child; for a cold one, a durable
+ * projection-cache row when it serves an own-suffix identity (the seq gate),
+ * else one bounded-concurrency persistence inspection folded through the
+ * registry.
+ * @see SubagentService.listChildren for the public cancellation and failure contract.
+ * @param ctx - context carrying the session store, the projection registry,
+ *   optional persistence, and the optional projection cache.
  * @param parentSessionId - parent session whose direct children are listed.
- * @param signal - caller-owned cancellation.
- * @returns children and per-child diagnostics in stable trace order.
- * @throws {@link SubagentError} when session query is unavailable or
- *   the caller cancels the scan.
+ * @param signal - caller-owned cancellation observed around every persistence read.
+ * @returns children and per-child diagnostics ordered by `createdAt`, then id.
+ * @throws {@link SubagentError} when the projection registry or the session
+ *   store is not mounted, or the caller cancels the listing.
  */
 export async function listChildren(
   ctx: Context,
   parentSessionId: SessionId,
   signal?: AbortSignal,
-): ReturnType<SubagentService['listChildren']> {
-  const query = ctx.get('sessionQuery')
-  if (query === undefined) {
+): Promise<SubagentListEntry[]> {
+  const projections = ctx.get('sessionProjections')
+  // Checked before any read, even with zero candidates: mode/label are the
+  // row's strong contract, so a missing fold capability is a deterministic
+  // deployment configuration error, never an empty success.
+  if (projections === undefined) {
     throw new SubagentError(
-      'listing subagents requires session query (load a dsh-session-query backend)',
-      'SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE',
+      'listing subagents requires the sessionProjections registry (load @deepseek-ai/dsh-session-projection)',
+      'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE',
+    )
+  }
+  // Strict global read, never the `ctx.sessions` property proxy: the proxy is
+  // caller-scope bound, so a consumer plugin without its own `sessions`
+  // injection (the model-facing tool, the API proxy) would throw on access.
+  const sessions = ctx.get('sessions')
+  if (sessions === undefined) {
+    throw new SubagentError(
+      'listing subagents requires the session store (load @deepseek-ai/dsh-session)',
+      'SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE',
     )
   }
   assertListingNotCancelled(signal)
-  // Keep runtime values behind the listing-only boundary so ordinary
-  // subagent imports and control operations do not evaluate the optional peer.
-  const queryRuntime: SessionQueryRuntime = await import('@deepseek-ai/dsh-session-query')
-  assertListingNotCancelled(signal)
-  const trace = await runListingQuery(
-    () => query.traceSession(parentSessionId, signal),
-    signal,
-  )
-  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',
-    )
-    const entry = await inspectChild(
-      query, queryRuntime, parentSessionId, node.session, hasChildren, signal,
-    )
-    // Cancellation can race the inspection's last checkpoint or diagnostic
-    // mapping; do not return success or begin another candidate afterward.
-    assertListingNotCancelled(signal)
-    if (entry !== undefined) entries.push(entry)
-  }
-  return entries
-}
-
-/** Interpret one traced direct-child record as a child, diagnostic, or exclusion. */
-async function inspectChild(
-  query: SessionQueryService,
-  queryRuntime: SessionQueryRuntime,
-  parentSessionId: SessionId,
-  candidate: SessionRecord,
-  hasChildren: boolean,
-  signal?: AbortSignal,
-): Promise<SubagentListEntry | undefined> {
-  const childId = candidate.header.id
-  try {
-    const records = await runListingQuery(() => query.listEvents(childId), signal)
-    // Only the child's own suffix: a fork seed may replay an ancestor's
-    // descriptor without making the fork itself a subagent.
-    const seedLength = candidate.header.seedLength ?? 0
-    const descriptorSeqs = records
-      .filter(record => record.seq >= seedLength && record.type === 'subagent/descriptor')
-      .map(record => record.seq)
-    if (descriptorSeqs.length === 0) return undefined
-    if (descriptorSeqs.length > 1) {
-      return { kind: 'diagnostic', id: childId, reason: 'corrupt' }
-    }
-    // The length-one branch proves this exact-read sequence exists.
-    // oxlint-disable-next-line typescript/no-non-null-assertion
-    const seq = descriptorSeqs[0]!
-    const window = await runListingQuery(
-      () => query.readEvent({ sessionId: childId, seq }, signal),
-      signal,
-    )
-    queryRuntime.assertSessionHeadersCompatible(window.session, candidate.header)
-    if (window.session.parentSession !== parentSessionId || window.target.type !== 'subagent/descriptor') {
-      return { kind: 'diagnostic', id: childId, reason: 'corrupt' }
-    }
-    let descriptor: ReturnType<typeof foldSubagentDescriptor>
+  const persistence = ctx.get('sessionPersistence')
+  // Optional acceleration only: an absent cache service just means every
+  // cold candidate takes the authoritative preparation rung, so it carries
+  // no error code and no configuration check.
+  const cache = ctx.get('sessionProjectionCache')
+  let persistedHeaders: readonly SessionHeader[] = []
+  if (persistence !== undefined) {
     try {
-      descriptor = foldSubagentDescriptor([window.target])
-    } catch {
-      return { kind: 'diagnostic', id: childId, reason: 'corrupt' }
+      persistedHeaders = await persistence.list(signal)
+    } catch (error: unknown) {
+      // The backend may reject with its own abort failure after observing the
+      // forwarded signal; cancellation stays a stable subagent failure.
+      assertListingNotCancelled(signal)
+      throw error
     }
-    if (descriptor === undefined) {
-      return { kind: 'diagnostic', id: childId, reason: 'unsupported' }
-    }
-    const activity = candidate.live ? 'running' : 'inactive'
-    if (descriptor.mode === 'one-shot') {
-      return {
-        kind: 'child',
-        id: childId,
-        mode: descriptor.mode,
-        ...descriptor.label !== undefined ? { label: descriptor.label } : {},
-        activity,
-        hasChildren,
-      }
-    }
-    return {
-      kind: 'child', id: childId, mode: descriptor.mode, label: descriptor.label,
-      activity, hasChildren,
-    }
-  } catch (error: unknown) {
-    const reason = perChildDiagnosticReason(error, queryRuntime.SessionQueryError)
-    if (reason === undefined) throw error
-    return { kind: 'diagnostic', id: childId, reason }
+    assertListingNotCancelled(signal)
   }
+  // Live-preferred merge without header reconciliation: a live record wins
+  // its id wholesale, exactly as a live-preferred corpus would serve it.
+  const corpus = new Map<SessionId, { header: SessionHeader; live: Session | undefined }>()
+  for (const header of persistedHeaders) corpus.set(header.id, { header, live: undefined })
+  for (const session of sessions.list()) {
+    corpus.set(session.header.id, { header: session.header, live: session })
+  }
+  const subagentParents = new Set<SessionId>()
+  for (const record of corpus.values()) {
+    if (record.header.origin === 'subagent' && record.header.parentSession !== undefined) {
+      subagentParents.add(record.header.parentSession)
+    }
+  }
+  const candidates = [...corpus.values()]
+    .filter(record => record.header.parentSession === parentSessionId
+      && record.header.origin === 'subagent')
+    .sort((a, b) => a.header.createdAt - b.header.createdAt
+      || a.header.id.localeCompare(b.header.id))
+
+  const rows: (SubagentListEntry | undefined)[] = Array.from({ length: candidates.length })
+  const coldReads: { index: number; header: SessionHeader }[] = []
+  candidates.forEach((candidate, index) => {
+    const childId = candidate.header.id
+    if (candidate.live === undefined) {
+      coldReads.push({ index, header: candidate.header })
+      return
+    }
+    // The registry's watermark cache serves the live value with zero log
+    // reads; a live child without an identity yet is the creation window
+    // before the establishing provider appends its descriptor.
+    let identity: SubagentIdentityProjection | null | undefined
+    try {
+      identity = projections.snapshot(candidate.live).values.subagent
+    } catch {
+      // The snapshot folds EVERY registered unit over this child's log, so
+      // any unit's fold or schema can reject damaged payloads. That is
+      // deterministic data damage in this one child; it degrades to one
+      // corrupt diagnostic instead of failing the whole listing.
+      rows[index] = { kind: 'diagnostic', id: childId, reason: 'corrupt' }
+      return
+    }
+    // The unit's serializable no-value sentinel is `null`; `undefined` can
+    // only mean the key was dropped at a JSON boundary. Both are no value.
+    if (identity === undefined || identity === null) return
+    rows[index] = childRow(childId, identity, 'running', subagentParents.has(childId))
+  })
+
+  // Cold candidates exist only when persistence listed them, so the narrow
+  // re-check is about types, not reachability.
+  if (persistence !== undefined && coldReads.length > 0) {
+    const queue = [...coldReads]
+    await Promise.all(Array.from(
+      { length: Math.min(COLD_READ_CONCURRENCY, queue.length) },
+      async () => {
+        for (let job = queue.shift(); job !== undefined; job = queue.shift()) {
+          rows[job.index] = await resolveColdIdentity(
+            persistence, projections, cache, job.header,
+            subagentParents.has(job.header.id), signal,
+          )
+        }
+      },
+    ))
+  }
+  assertListingNotCancelled(signal)
+  return rows.filter((row): row is SubagentListEntry => row !== undefined)
 }
 
-/** Stop a listing scan at its next cancellation checkpoint. */
+/**
+ * Resolve one cold candidate down the remaining ladder: a durable
+ * projection-cache row when it serves an own-suffix identity (the seq gate),
+ * otherwise one persistence inspection folded through the projection
+ * registry (the same detached recipe the API proxy uses for detached session
+ * projections). A failed inspection is one transient `unavailable` row
+ * retried on the next listing; an inspection naming another lifecycle, and a
+ * settled log the fold cannot identify — or that makes any registered unit
+ * throw — are final, so they report `corrupt`.
+ */
+async function resolveColdIdentity(
+  persistence: SessionPersistence,
+  projections: SessionProjectionRegistry,
+  cache: SessionProjectionCache | undefined,
+  header: SessionHeader,
+  hasChildren: boolean,
+  signal: AbortSignal | undefined,
+): Promise<SubagentListEntry> {
+  const childId = header.id
+  if (cache !== undefined) {
+    let cached: SubagentIdentityProjection | null | undefined
+    try {
+      cached = cache.cachedSnapshot(header)?.values.subagent
+    } catch {
+      // Unlike the preparation fold below, a throwing cache read renders no
+      // verdict: the cache is derived data, so its damage (a poisoned stored
+      // row of ANY unit) silently falls through to the authoritative re-fold.
+      cached = undefined
+    }
+    // A child's OWN descriptor is immutable once appended, so a cached
+    // identity is final only when the seq gate proves it was folded from the
+    // own suffix: a creation-window checkpoint may instead carry a fork
+    // seed's replayed ANCESTOR descriptor (seq below `seedLength`), which
+    // must not outrank the re-fold. Everything else also falls through to
+    // preparation: an absent key (a cut before any descriptor) and the
+    // `null` sentinel, whose verdict belongs to the authoritative re-fold,
+    // not to a derived row.
+    if (cached !== undefined && cached !== null && cached.seq >= (header.seedLength ?? 0)) {
+      return childRow(childId, cached, 'inactive', hasChildren)
+    }
+  }
+  assertListingNotCancelled(signal)
+  let inspected: { meta: SessionHeader; events: readonly SessionEvent[] }
+  try {
+    inspected = await persistence.inspect(childId, signal)
+  } catch {
+    // Per-child isolation: the child vanished or its backend read failed —
+    // one diagnostic row, and the listing itself still succeeds.
+    assertListingNotCancelled(signal)
+    return { kind: 'diagnostic', id: childId, reason: 'unavailable' }
+  }
+  assertListingNotCancelled(signal)
+  // A session id names a slot, not a lifecycle: a child deleted and
+  // re-published under another owner between the enumeration and this read
+  // must not leak into the old parent's listing.
+  if (!sameLifecycle(inspected.meta, header)) {
+    return { kind: 'diagnostic', id: childId, reason: 'corrupt' }
+  }
+  let identity: SubagentIdentityProjection | null | undefined
+  try {
+    identity = projections.restore({}, inspected.events, 0).snapshot.values.subagent
+  } catch {
+    // The restore folds EVERY registered unit over this child's log, so any
+    // unit's fold or schema can reject damaged payloads — deterministic data
+    // damage in this one child, contained as its own corrupt diagnostic.
+    return { kind: 'diagnostic', id: childId, reason: 'corrupt' }
+  }
+  if (identity === undefined || identity === null) {
+    return { kind: 'diagnostic', id: childId, reason: 'corrupt' }
+  }
+  return childRow(childId, identity, 'inactive', hasChildren)
+}
+
+/** Materialize one served identity as its child row. */
+function childRow(
+  id: SessionId,
+  identity: SubagentIdentityProjection,
+  activity: 'running' | 'inactive',
+  hasChildren: boolean,
+): SubagentListEntry {
+  return identity.mode === 'one-shot'
+    ? {
+      kind: 'child',
+      id,
+      mode: 'one-shot',
+      ...identity.label !== undefined ? { label: identity.label } : {},
+      activity,
+      hasChildren,
+    }
+    : {
+      kind: 'child',
+      id,
+      mode: 'continuable',
+      label: identity.label,
+      activity,
+      hasChildren,
+    }
+}
+
+/** Immutable header fields that distinguish one session lifecycle from another under the same id. */
+const LIFECYCLE_WITNESS_KEYS = [
+  'version', 'id', 'createdAt', 'cwd', 'parentSession', 'seedLength', 'delegationDepth',
+] as const
+
+/**
+ * Whether an inspected log still belongs to the enumerated lifecycle,
+ * mirroring the retired query-source compatibility check's field set.
+ */
+function sameLifecycle(meta: SessionHeader, expected: SessionHeader): boolean {
+  return LIFECYCLE_WITNESS_KEYS.every(key => meta[key] === expected[key])
+}
+
+/** Stop a listing at its next cancellation checkpoint. */
 function assertListingNotCancelled(signal: AbortSignal | undefined): void {
   if (signal?.aborted) {
     throw new SubagentError('subagent listing was cancelled', 'CANCELLED')
   }
 }
-
-/**
- * Run one session-query operation between cancellation checkpoints. Query
- * implementations may reject with their own abort error after observing the
- * forwarded signal; cancellation remains a stable subagent failure.
- */
-async function runListingQuery<T>(
-  operation: () => Promise<T>,
-  signal: AbortSignal | undefined,
-): Promise<T> {
-  assertListingNotCancelled(signal)
-  try {
-    const result = await operation()
-    assertListingNotCancelled(signal)
-    return result
-  } catch (error: unknown) {
-    assertListingNotCancelled(signal)
-    throw error
-  }
-}
-
-/**
- * Map a per-child query failure to a fixed diagnostic. Configuration errors
- * and unrecognized failures remain operation failures.
- */
-function perChildDiagnosticReason(
-  error: unknown,
-  SessionQueryError: SessionQueryRuntime['SessionQueryError'],
-): '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':
-      return 'unavailable'
-    case 'SESSION_QUERY_INVALID_SURFACE':
-    case 'SESSION_QUERY_SOURCE_CONFLICT':
-      return 'corrupt'
-    default:
-      return undefined
-  }
-}
diff --git a/packages/subagent/subagent/src/out-of-process.ts b/packages/subagent/subagent/src/out-of-process.ts
index fc78fb28fa..d049dba2be 100644
--- a/packages/subagent/subagent/src/out-of-process.ts
+++ b/packages/subagent/subagent/src/out-of-process.ts
@@ -132,9 +132,9 @@ function toError(value: unknown): Error {
 export interface RunResultSettlement {
   /** The turn attempt (typically racing local cancellation); returns the terminal result. */
   attempt: () => Promise<SubagentResult>
-  /** Snapshot of the child output streamed so far (a partial answer survives failure). */
+  /** Snapshot the provider exposes when cancellation or failure wins settlement. */
   collectOutput: () => ContentBlock[]
-  /** Whether local cancellation settled (an in-flight rejection then reads as `aborted`). */
+  /** Whether local cancellation settled before the attempt's outcome is observed. */
   cancelled: () => boolean
   /** Diagnostic sink for a failure flattened to a stop reason; a throw from it is contained. */
   onError?: ((error: Error, stopReason: SubagentStopReason) => void) | undefined
@@ -146,16 +146,19 @@ export interface RunResultSettlement {
 
 /**
  * Settle an out-of-process run result under the seam contract: `result` never
- * rejects after publication. A rejection from the attempt resolves as
- * `aborted` when cancellation already settled locally, else it is flattened
- * to `stopReason: 'error'` through the contained diagnostic sink; the abort
- * listener is removed on every path.
+ * rejects after publication. A normally completed or rejected attempt resolves
+ * as `aborted` when cancellation already settled locally; another rejection is
+ * flattened to `stopReason: 'error'` through the contained diagnostic sink.
+ * The abort listener is removed on every path.
  * @param parts - the attempt, output snapshot, cancellation state, sink, and signal wiring.
  * @returns the terminal result (never a rejection).
  */
 export async function settleRunResult(parts: RunResultSettlement): Promise<SubagentResult> {
   try {
-    return await parts.attempt()
+    const result = await parts.attempt()
+    return parts.cancelled()
+      ? { output: parts.collectOutput(), stopReason: 'aborted' }
+      : result
   } catch (error: unknown) {
     // Cover a rejection already queued when cancellation arrives.
     if (parts.cancelled()) return { output: parts.collectOutput(), stopReason: 'aborted' }
diff --git a/packages/subagent/subagent/src/projection-types.ts b/packages/subagent/subagent/src/projection-types.ts
index c5a23b03b8..046c32e91d 100644
--- a/packages/subagent/subagent/src/projection-types.ts
+++ b/packages/subagent/subagent/src/projection-types.ts
@@ -17,9 +17,48 @@ export interface SubagentTimingProjection {
   }
 }
 
+/**
+ * Durable identity of one descriptor-backed subagent session: lifecycle mode
+ * plus creation label, folded last-wins from `subagent/descriptor` events.
+ * Label strength follows the descriptor schema: a continuable child always
+ * carries one, a one-shot child may omit it.
+ */
+export type SubagentIdentityProjection =
+  | {
+    /** A terminal one-shot child. */
+    mode: 'one-shot'
+    /** Optional durable creation label from the child's descriptor. */
+    label?: string
+    /**
+     * Seq of the `subagent/descriptor` event this identity was folded from.
+     * `seq >= header.seedLength` proves the identity comes from the child's
+     * OWN log suffix — where a descriptor is immutable once appended — and
+     * not from a fork seed's replayed ancestor descriptor.
+     */
+    seq: number
+  }
+  | {
+    /** A resumable conversation. */
+    mode: 'continuable'
+    /** Durable creation label from the child's descriptor. */
+    label: string
+    /** Seq of the folded descriptor event; see the one-shot arm for the own-suffix proof. */
+    seq: number
+  }
+
 declare module '@deepseek-ai/dsh-session-projection/types' {
   interface SessionProjectionMap {
     /** Active-turn duration for a descriptor-backed subagent session. */
     subagentTiming: SubagentTimingProjection
+    /**
+     * Identity of a descriptor-backed subagent session. `null` ⟺ no valid
+     * descriptor (missing, malformed, or unrecognized-version — deliberately
+     * undistinguished). The sentinel is deliberately serializable: a
+     * value pushed over JSON transports must survive `JSON.stringify`
+     * losslessly, where an `undefined` field would be dropped and a stale
+     * identity would survive on the receiving side. The entry itself stays
+     * non-optional.
+     */
+    subagent: SubagentIdentityProjection | null
   }
 }
diff --git a/packages/subagent/subagent/src/projection.ts b/packages/subagent/subagent/src/projection.ts
index ffdcb4fd09..9473f3b003 100644
--- a/packages/subagent/subagent/src/projection.ts
+++ b/packages/subagent/subagent/src/projection.ts
@@ -1,12 +1,16 @@
 /**
- * Pure session projection for subagent active-turn duration.
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
  *
  * @module @deepseek-ai/dsh-subagent/projection
  */
 
 import { z } from 'zod'
 import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
-import type { SubagentTimingProjection } from './projection-types.ts'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { foldSubagentDescriptor } from './descriptor.ts'
+import type { SubagentDescriptorData } from './descriptor.ts'
+import type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts'
 
 interface TimingState {
   /** Milliseconds accumulated across completed post-descriptor turns. */
@@ -80,3 +84,73 @@ ProjectionDefinition<'subagentTiming', TimingState> = {
   }),
   stateVersion: 2,
 }
+
+interface IdentityState {
+  /** Identity from the last valid descriptor; absent before one, and after an invalid one. */
+  identity?: SubagentIdentityProjection
+}
+
+// The cast bridges only the optional-label arm: Zod's optional output
+// includes explicit `undefined`, which exactOptionalPropertyTypes excludes
+// from the public interface. The no-value state itself is the serializable
+// `null` arm — never `undefined` — so every registry read and push frame
+// survives JSON.stringify losslessly.
+const identitySchema = z.discriminatedUnion('mode', [
+  z.object({
+    mode: z.literal('one-shot'),
+    label: z.string().optional(),
+    seq: z.number().int().nonnegative(),
+  }).strict(),
+  z.object({
+    mode: z.literal('continuable'),
+    label: z.string(),
+    seq: z.number().int().nonnegative(),
+  }).strict(),
+]).nullable() as unknown as z.ZodType<SubagentIdentityProjection | null>
+
+/** Interpret one `subagent/descriptor` event's identity; no value when the payload cannot be trusted. */
+function descriptorIdentity(event: SessionEvent): SubagentIdentityProjection | undefined {
+  let descriptor: SubagentDescriptorData | undefined
+  try {
+    descriptor = foldSubagentDescriptor([event])
+  } catch {
+    // Only a malformed current-version payload throws in descriptor parsing;
+    // a projection fold must never throw, so damage folds to no value.
+    descriptor = undefined
+  }
+  if (descriptor === undefined) return undefined
+  return descriptor.mode === 'one-shot'
+    ? {
+      mode: 'one-shot',
+      ...descriptor.label !== undefined ? { label: descriptor.label } : {},
+      seq: event.seq,
+    }
+    : { mode: 'continuable', label: descriptor.label, seq: event.seq }
+}
+
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export const subagentIdentityProjectionDefinition:
+ProjectionDefinition<'subagent', IdentityState> = {
+  key: 'subagent',
+  schema: identitySchema,
+  init: () => ({}),
+  apply: (state, event) => {
+    if (event.type !== 'subagent/descriptor') return state
+    const identity = descriptorIdentity(event)
+    return identity === undefined ? {} : { identity }
+  },
+  view: state => state.identity ?? null,
+  // Bumped when the identity gained its `seq` field: an older checkpoint row
+  // would replay into a value the schema rejects, so it must refold instead.
+  stateVersion: 2,
+}
diff --git a/packages/subagent/subagent/tests/list-children.spec.ts b/packages/subagent/subagent/tests/list-children.spec.ts
index f8ceab50a8..ef52883db2 100644
--- a/packages/subagent/subagent/tests/list-children.spec.ts
+++ b/packages/subagent/subagent/tests/list-children.spec.ts
@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
+import { z } from 'zod'
 import { Context } from 'cordis'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
@@ -9,7 +10,12 @@ import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-test
 import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
-import { SessionQueryError } from '@deepseek-ai/dsh-session-query'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection'
+import SessionProjectionCache from '@deepseek-ai/dsh-session-projection-cache'
+import Storage from '@deepseek-ai/dsh-storage'
+import { DomainFacility } from '@deepseek-ai/dsh-storage-domain'
+import { MemoryMediaPool, MemoryStorageBackend } from '../../../storage/storage-domain/tests/helpers/memory-backend.ts'
 import SubagentService, {
   SUBAGENT_DESCRIPTOR_VERSION,
   SubagentError,
@@ -17,7 +23,6 @@ import SubagentService, {
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
 import * as SubagentFork from '@deepseek-ai/dsh-subagent-fork'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
-import { TestSessionQueryService } from '../../../session-query/session-query/tests/test-service.ts'
 
 type Script = ConstructorParameters<typeof MockAdapter>[0]
 
@@ -26,18 +31,29 @@ afterEach(() => {
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
 
-/** Boot the continuable stack plus a concrete session-query service. */
-async function setup(script: Script, options: { sessionQuery?: boolean } = {}) {
+/** Boot the continuable stack with real JSONL session persistence. */
+async function setup(
+  script: Script,
+  options: { sessionProjections?: boolean; projectionCache?: boolean } = {},
+) {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   const root = mkdtempSync(join(tmpdir(), 'dsh-subagent-list-'))
   roots.push(root)
   await ctx.plugin(JsonlSessionPersistence, { root })
   await ctx.plugin(AgentLoop, { agents: [] })
+  if (options.sessionProjections !== false) await ctx.plugin(SessionProjectionRegistry)
+  if (options.projectionCache === true) {
+    await ctx.plugin(Storage)
+    ctx.storage.backend.register('memory', new MemoryStorageBackend(new MemoryMediaPool()))
+    const facility = new DomainFacility(ctx, { backend: 'memory', routes: {} })
+    ctx.storage.mount('domain', facility)
+    ctx.provide('storageDomain', facility)
+    await ctx.plugin(SessionProjectionCache, { writeEveryEvents: 100, writeIntervalMs: 60_000 })
+  }
   await ctx.plugin(SubagentService)
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(SubagentFork, { providerName: 'fork' })
-  if (options.sessionQuery !== false) await ctx.plugin(TestSessionQueryService)
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
   const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
   return { ctx, parent }
@@ -101,38 +117,76 @@ function descriptorPayload(label: string, version = SUBAGENT_DESCRIPTOR_VERSION)
   return { version, mode: 'continuable' as const, provider: 'spawn', label }
 }
 
+declare module '@deepseek-ai/dsh-session-projection/types' {
+  interface SessionProjectionMap {
+    /** Test-only hostile probe proving per-child isolation of foreign unit failures. */
+    subagentListHostileProbe: null
+  }
+}
+
+/**
+ * A foreign registered unit that rejects one specific child's log at view
+ * time: `apply` never throws (the eager drive passes every committed event
+ * through it), while the poisoned state detonates only when a listing read
+ * folds or serves this child through the registry.
+ */
+const hostileProjectionDefinition: ProjectionDefinition<'subagentListHostileProbe', { poisoned?: boolean }> = {
+  key: 'subagentListHostileProbe',
+  schema: z.null(),
+  init: () => ({}),
+  apply: (state, event) =>
+    event.type === 'subagent/descriptor' && (event.data as { label?: string }).label === 'poison me'
+      ? { poisoned: true }
+      : state,
+  view: (state) => {
+    if (state.poisoned === true) throw new Error('hostile unit rejects the poisoned log')
+    return null
+  },
+  stateVersion: 1,
+}
+
 describe('SubagentService.listChildren', () => {
-  it('lists through session query without the Activation continuation runtime', async () => {
+  it('lists live children without persistence, query services, or the continuation runtime', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionProjectionRegistry)
     await ctx.plugin(SubagentService)
-    await ctx.plugin(TestSessionQueryService)
     expect(ctx.get('tasks')).toBeUndefined()
     expect(ctx.get('agents')).toBeUndefined()
+    expect(ctx.get('sessionPersistence')).toBeUndefined()
 
-    const parentId = SessionId('query-only-parent')
+    const parentId = SessionId('live-only-parent')
     ctx.sessions.create(parentId)
-    const childId = SessionId('query-only-child')
+    const childId = SessionId('live-only-child')
     const child = ctx.sessions.create(childId, {
       meta: { parentSession: parentId, origin: 'subagent' },
     })
     child.append('turn/start', {
       turn: 1,
     })
-    child.append('subagent/descriptor', descriptorPayload('query-only child'))
+    child.append('subagent/descriptor', descriptorPayload('live-only child'))
 
     await expect(ctx.subagents.listChildren(parentId)).resolves.toEqual([
       {
-        kind: 'child', id: childId, label: 'query-only child', mode: 'continuable',
+        kind: 'child', id: childId, label: 'live-only child', mode: 'continuable',
         activity: 'running', hasChildren: false,
       },
     ])
   })
 
-  it('fails loud before any work when session query is not loaded', async () => {
-    const { ctx, parent } = await setup([], { sessionQuery: false })
+  it('fails loud when the projection registry is not mounted, even with no children', async () => {
+    const { ctx, parent } = await setup([], { sessionProjections: false })
     await expect(ctx.subagents.listChildren(parent.id)).rejects.toThrow(
-      expect.objectContaining({ code: 'SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE' }) as Error,
+      expect.objectContaining({ code: 'SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE' }) as Error,
+    )
+  })
+
+  it('fails loud when the session store is not mounted', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionProjectionRegistry)
+    await ctx.plugin(SubagentService)
+    await expect(ctx.subagents.listChildren(SessionId('no-store-parent'))).rejects.toThrow(
+      expect.objectContaining({ code: 'SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE' }) as Error,
     )
   })
 
@@ -148,7 +202,7 @@ describe('SubagentService.listChildren', () => {
     ])
   })
 
-  it('lists one-shot and continuable children from the same trace', async () => {
+  it('lists one-shot and continuable children under the same parent', async () => {
     const { ctx, parent } = await setup([textResponse('once'), textResponse('again')])
     const oneShot = await ctx.subagents.start('spawn', {
       prompt: [{ type: 'text', text: 'finish once' }],
@@ -205,33 +259,59 @@ describe('SubagentService.listChildren', () => {
     ])
   })
 
-  it('orders children by createdAt then id without inspecting ordinary forks', async () => {
+  it('orders children by createdAt then id without listing 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')))
+    /** Publish one live child with a pinned header ordering key. */
+    const liveChild = (parentId: SessionId, id: string, createdAt: number, label: string): SessionId => {
+      const session = ctx.sessions.create(SessionId(id), {
+        meta: { parentSession: parentId, origin: 'subagent', createdAt },
+      })
+      session.append('turn/start', { turn: 1 })
+      session.append('subagent/descriptor', descriptorPayload(label))
+      return session.header.id
+    }
+    // Live creation order is deliberately shuffled against the expected
+    // result: same-createdAt ties break on id, different createdAt orders
+    // ascending.
+    const late = liveChild(parent.id, '00000000-0000-4000-8000-000000000009', 9, 'late child')
+    const tieB = liveChild(parent.id, '00000000-0000-4000-8000-000000000002', 5, 'tie b')
+    const tieA = liveChild(parent.id, '00000000-0000-4000-8000-000000000001', 5, 'tie a')
     // 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('omits a live child that has not appended its descriptor yet', async () => {
+    const { ctx, parent } = await setup([])
+    const pending = ctx.sessions.create(SessionId('creation-window-child'), {
+      meta: { parentSession: parent.id, origin: 'subagent' },
+    })
+    pending.append('turn/start', { turn: 1 })
+    // The creation window: the establishing provider has not appended the
+    // descriptor yet, so the row is omitted rather than diagnosed.
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([])
+  })
+
+  it('lists a one-shot child with its durable creation label', async () => {
+    const { ctx, parent } = await setup([])
+    const labeled = await authorChild(ctx, '00000000-0000-4000-8000-00000000ab02', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents({
+      version: SUBAGENT_DESCRIPTOR_VERSION,
+      mode: 'one-shot',
+      provider: 'spawn',
+      label: 'labeled one-shot',
+    }))
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([
+      {
+        kind: 'child', id: labeled, mode: 'one-shot', label: 'labeled one-shot',
+        activity: 'inactive', hasChildren: false,
+      },
+    ])
   })
 
   it('reports a live child as running while keeping settled siblings complete', async () => {
@@ -256,7 +336,7 @@ describe('SubagentService.listChildren', () => {
     })
   })
 
-  it('diagnoses duplicate descriptors as corrupt without hiding healthy siblings', async () => {
+  it('lists the last descriptor when a log carries more than one', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     const healthy = await startChild(ctx, parent, 'healthy sibling')
     const events = childEvents(descriptorPayload('twice'))
@@ -267,22 +347,169 @@ describe('SubagentService.listChildren', () => {
       data: descriptorPayload('twice again'),
     } as SessionEvent)
     events[4] = { ...events[4]!, seq: 4 }
-    const corrupt = await authorChild(ctx, '00000000-0000-4000-8000-00000000dupe', {
+    const doubled = await authorChild(ctx, '00000000-0000-4000-8000-00000000dupe', {
       parentSession: parent.id,
       origin: 'subagent',
     }, events)
+    // The last-wins projection fold serves the final descriptor's identity; a
+    // repeated descriptor is not a per-child corruption diagnostic.
     const entries = await ctx.subagents.listChildren(parent.id)
-    expect(entries).toContainEqual({ kind: 'diagnostic', id: corrupt, reason: 'corrupt' })
+    expect(entries).toContainEqual({
+      kind: 'child', id: doubled, label: 'twice again', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    })
     expect(entries).toContainEqual({
       kind: 'child', id: healthy, label: 'healthy sibling', mode: 'continuable',
       activity: 'inactive', hasChildren: false,
     })
   })
 
-  it('diagnoses a child rejected by persisted Session preparation as corrupt', async () => {
+  it('serves the serializable null sentinel when a later descriptor invalidates the identity', async () => {
     const { ctx, parent } = await setup([])
-    // The surface-eligible user/message lacks its required surfaceOp. The
-    // first-party persistence inspection rejects before session-query can fold it.
+    const liveId = SessionId('invalidated-live-child')
+    const live = ctx.sessions.create(liveId, {
+      meta: { parentSession: parent.id, origin: 'subagent' },
+    })
+    live.append('turn/start', { turn: 1 })
+    live.append('subagent/descriptor', descriptorPayload('was valid'))
+    expect(ctx.sessionProjections.snapshot(live).values.subagent)
+      .toEqual({ mode: 'continuable', label: 'was valid', seq: 1 })
+    // Last-wins: the malformed follow-up resets the identity to the sentinel.
+    live.append(
+      'subagent/descriptor',
+      { version: SUBAGENT_DESCRIPTOR_VERSION, mode: 'continuable', provider: 7 } as never,
+    )
+    const values = ctx.sessionProjections.snapshot(live).values
+    expect(values.subagent).toBeNull()
+    // The sentinel survives a JSON push frame; an undefined field would be
+    // dropped there and a consumer would keep the stale identity forever.
+    const wired = JSON.parse(JSON.stringify(values)) as Record<string, unknown>
+    expect('subagent' in wired).toBe(true)
+    expect(wired['subagent']).toBeNull()
+    // The listing reads the same null as no value: running → omitted.
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([])
+  })
+
+  it('diagnoses a settled child whose later descriptor invalidated the identity as corrupt', async () => {
+    const { ctx, parent } = await setup([])
+    const events = childEvents(descriptorPayload('was valid'))
+    events.splice(3, 0, {
+      type: 'subagent/descriptor',
+      seq: 3,
+      time: 3,
+      data: { version: SUBAGENT_DESCRIPTOR_VERSION, mode: 'continuable', provider: 7 },
+    } as SessionEvent)
+    events[4] = { ...events[4]!, seq: 4 }
+    const invalidated = await authorChild(ctx, '00000000-0000-4000-8000-00000000ad01', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, events)
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([
+      { kind: 'diagnostic', id: invalidated, reason: 'corrupt' },
+    ])
+  })
+
+  it('serves a cached own-suffix identity directly without inspection', async () => {
+    const { ctx, parent } = await setup([], { projectionCache: true })
+    const child = await authorChild(ctx, '00000000-0000-4000-8000-00000000ae01', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('disk label')))
+    // seq 2 >= seedLength 0: the cached identity provably comes from the
+    // child's own suffix, so it is final and the log is never re-read — the
+    // divergent label proves the row, not the log, produced the entry.
+    ctx.sessionProjectionCache.cachedSnapshot = () => ({
+      asOfSeq: 2,
+      values: { subagent: { mode: 'continuable', label: 'cached own', seq: 2 } },
+    })
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect')
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
+      kind: 'child', id: child, label: 'cached own', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    }])
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('refuses a cached ancestor identity from the fork seed and lets preparation rule', async () => {
+    const { ctx, parent } = await setup([], { projectionCache: true })
+    // A fork child: the seed replays the ancestor's descriptor (seq 2), and
+    // the child's own descriptor arrives in its first own turn (seq 5).
+    const seed = childEvents(descriptorPayload('ancestor label'))
+    const events = [
+      ...seed,
+      { type: 'turn/start', seq: 4, time: 5, data: { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'subagent/descriptor', seq: 5, time: 6, data: descriptorPayload('own label') },
+      { type: 'turn/end', seq: 6, time: 7, data: { turn: 2, reason: { kind: 'completed' } } },
+    ] as SessionEvent[]
+    const forkChild = await authorChild(ctx, '00000000-0000-4000-8000-00000000ae02', {
+      parentSession: parent.id,
+      seedLength: seed.length,
+      origin: 'subagent',
+    }, events)
+    // A creation-window checkpoint carried the ANCESTOR identity: its seq 2
+    // fails the own-suffix gate (< seedLength 4), so preparation rules.
+    ctx.sessionProjectionCache.cachedSnapshot = () => ({
+      asOfSeq: 2,
+      values: { subagent: { mode: 'continuable', label: 'ancestor label', seq: 2 } },
+    })
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect')
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
+      kind: 'child', id: forkChild, label: 'own label', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    }])
+    expect(inspect).toHaveBeenCalledTimes(1)
+  })
+
+  it.each([
+    ['version', (meta: SessionHeader): SessionHeader => ({ ...meta, version: meta.version + 1 })],
+    ['id', (meta: SessionHeader): SessionHeader => ({ ...meta, id: SessionId('another-lifecycle') })],
+    ['createdAt', (meta: SessionHeader): SessionHeader => ({ ...meta, createdAt: meta.createdAt + 1 })],
+    ['cwd', (meta: SessionHeader): SessionHeader => ({ ...meta, cwd: '/elsewhere' })],
+    ['parentSession', (meta: SessionHeader): SessionHeader => ({ ...meta, parentSession: SessionId('another-parent') })],
+    ['seedLength', (meta: SessionHeader): SessionHeader => ({ ...meta, seedLength: (meta.seedLength ?? 0) + 1 })],
+    ['delegationDepth', (meta: SessionHeader): SessionHeader => ({ ...meta, delegationDepth: (meta.delegationDepth ?? 0) + 1 })],
+  ] as const)('diagnoses an inspection returning another lifecycle (%s) as corrupt', async (_field, mutate) => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    const healthy = await startChild(ctx, parent, 'healthy sibling')
+    const reborn = await authorChild(ctx, '00000000-0000-4000-8000-00000000ae03', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('reborn child')))
+    const original = ctx.sessionPersistence.inspect.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.inspect = async (sessionId, signal) => {
+      const result = await original(sessionId, signal)
+      if (sessionId !== reborn) return result
+      // The id was re-published as a different lifecycle after enumeration.
+      return { ...result, meta: mutate(result.meta) }
+    }
+    const entries = await ctx.subagents.listChildren(parent.id)
+    expect(entries).toContainEqual({ kind: 'diagnostic', id: reborn, reason: 'corrupt' })
+    expect(entries).toContainEqual({
+      kind: 'child', id: healthy, label: 'healthy sibling', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    })
+  })
+
+  it('lets preparation rule when the cache serves the null sentinel', async () => {
+    const { ctx, parent } = await setup([], { projectionCache: true })
+    const healthy = await authorChild(ctx, '00000000-0000-4000-8000-00000000ad02', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('actually valid')))
+    // A stale cached sentinel must not out-rank the authoritative re-fold.
+    ctx.sessionProjectionCache.cachedSnapshot = () => ({ asOfSeq: 0, values: { subagent: null } })
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect')
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
+      kind: 'child', id: healthy, label: 'actually valid', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    }])
+    expect(inspect).toHaveBeenCalledTimes(1)
+  })
+
+  it('maps a child rejected by persistence inspection to unavailable', async () => {
+    const { ctx, parent } = await setup([])
+    // The surface-eligible user/message lacks its required surfaceOp, so the
+    // first-party inspection rejects before any projection fold can run.
     const invalid = await authorChild(ctx, '00000000-0000-4000-8000-0000000000ee', {
       parentSession: parent.id,
       origin: 'subagent',
@@ -297,7 +524,7 @@ describe('SubagentService.listChildren', () => {
       { type: 'subagent/descriptor', seq: 2, time: 3, data: descriptorPayload('broken surface') },
     ] as SessionEvent[])
     const entries = await ctx.subagents.listChildren(parent.id)
-    expect(entries).toEqual([{ kind: 'diagnostic', id: invalid, reason: 'corrupt' }])
+    expect(entries).toEqual([{ kind: 'diagnostic', id: invalid, reason: 'unavailable' }])
   })
 
   it('diagnoses a malformed descriptor payload as corrupt', async () => {
@@ -310,28 +537,36 @@ describe('SubagentService.listChildren', () => {
     expect(entries).toEqual([{ kind: 'diagnostic', id: malformed, reason: 'corrupt' }])
   })
 
-  it('diagnoses an unknown descriptor version as unsupported', async () => {
+  it('diagnoses an unknown descriptor version as corrupt', async () => {
     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)))
+    // The projection fold does not distinguish an unrecognized version from
+    // other invalid descriptors: both serve no identity, and a settled
+    // no-value candidate is corrupt.
     const entries = await ctx.subagents.listChildren(parent.id)
-    expect(entries).toEqual([{ kind: 'diagnostic', id: future, reason: 'unsupported' }])
+    expect(entries).toEqual([{ kind: 'diagnostic', id: future, reason: 'corrupt' }])
   })
 
-  it('ignores an ancestor descriptor replayed inside a fork seed', async () => {
+  it('lists a fork whose seed replays an ancestor descriptor under that identity', async () => {
     const { ctx, parent } = await setup([])
-    // A fork child whose seed replays a parent log containing a descriptor:
-    // the seed's descriptor is the ANCESTOR's, not this child's.
+    // The last-wins fold serves a seed-replayed ancestor descriptor until the
+    // child's own descriptor overrides it (known deviation #1 in the design).
     const seed = childEvents(descriptorPayload('ancestor label'))
-    await authorChild(ctx, '00000000-0000-4000-8000-0000000000f0', {
+    const forkChild = 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([])
+    expect(entries).toEqual([
+      {
+        kind: 'child', id: forkChild, label: 'ancestor label', mode: 'continuable',
+        activity: 'inactive', hasChildren: false,
+      },
+    ])
   })
 
   it('does not filter by provider availability: children of unmounted providers stay listed', async () => {
@@ -354,103 +589,85 @@ describe('SubagentService.listChildren', () => {
     ])
   })
 
-  it('maps a per-child read failure to one unavailable diagnostic after a successful trace', async () => {
+  it('contains a foreign unit failure during a cold fold to that child as corrupt', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
-    const childId = await startChild(ctx, parent, 'flaky storage')
-    const query = ctx.get('sessionQuery')!
-    const originalListEvents = query.listEvents.bind(query)
-    query.listEvents = (sessionId) => {
-      if (sessionId === childId) {
-        return Promise.reject(new SessionQueryError('backend read failed', 'SESSION_QUERY_PERSISTENCE_FAILED'))
-      }
-      return originalListEvents(sessionId)
-    }
+    ctx.sessionProjections.register(hostileProjectionDefinition)
+    const healthy = await startChild(ctx, parent, 'healthy sibling')
+    const poisoned = await authorChild(ctx, '00000000-0000-4000-8000-00000000d00d', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('poison me')))
+    // The subagent unit itself folds this child cleanly; the FOREIGN unit's
+    // view throws, and that damage stays contained to the one child.
     const entries = await ctx.subagents.listChildren(parent.id)
-    expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'unavailable' }])
+    expect(entries).toContainEqual({ kind: 'diagnostic', id: poisoned, reason: 'corrupt' })
+    expect(entries).toContainEqual({
+      kind: 'child', id: healthy, label: 'healthy sibling', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    })
   })
 
-  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', code))
+  it('contains a foreign unit failure during a live snapshot to that child as corrupt', async () => {
+    const { ctx, parent } = await setup([])
+    ctx.sessionProjections.register(hostileProjectionDefinition)
+    const poisonedId = SessionId('live-poisoned-child')
+    const poisoned = ctx.sessions.create(poisonedId, {
+      meta: { parentSession: parent.id, origin: 'subagent' },
+    })
+    poisoned.append('turn/start', { turn: 1 })
+    poisoned.append('subagent/descriptor', descriptorPayload('poison me'))
+    const healthyId = SessionId('live-healthy-child')
+    const healthy = ctx.sessions.create(healthyId, {
+      meta: { parentSession: parent.id, origin: 'subagent' },
+    })
+    healthy.append('turn/start', { turn: 1 })
+    healthy.append('subagent/descriptor', descriptorPayload('live healthy'))
     const entries = await ctx.subagents.listChildren(parent.id)
-    expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'unavailable' }])
+    expect(entries).toContainEqual({ kind: 'diagnostic', id: poisonedId, reason: 'corrupt' })
+    expect(entries).toContainEqual({
+      kind: 'child', id: healthyId, label: 'live healthy', mode: 'continuable',
+      activity: 'running', hasChildren: false,
+    })
   })
 
-  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')
-    const query = ctx.get('sessionQuery')!
-    const originalReadEvent = query.readEvent.bind(query)
-    query.readEvent = async (request) => {
-      const window = await originalReadEvent(request)
-      return {
-        ...window,
-        session: { ...window.session, parentSession: SessionId('someone-else') },
-      }
-    }
-    const entries = await ctx.subagents.listChildren(parent.id)
-    // The exact read's conflicting immutable header is per-child corruption.
-    expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'corrupt' }])
-  })
-
-  it('diagnoses a read whose target is no longer the descriptor event as corrupt', async () => {
-    const { ctx, parent } = await setup([textResponse('done')])
-    const childId = await startChild(ctx, parent, 'shifted log')
-    const query = ctx.get('sessionQuery')!
-    const originalReadEvent = query.readEvent.bind(query)
-    query.readEvent = async (request) => {
-      const window = await originalReadEvent(request)
-      return { ...window, target: { ...window.target, type: 'turn/start' } as typeof window.target }
-    }
-    const entries = await ctx.subagents.listChildren(parent.id)
-    expect(entries).toEqual([{ kind: 'diagnostic', id: childId, reason: 'corrupt' }])
-  })
-
-  it('fails the whole call when the initial trace fails', async () => {
+  it('fails the whole enumeration when the persisted listing itself fails', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     await startChild(ctx, parent, 'never listed')
-    const query = ctx.get('sessionQuery')!
-    query.traceSession = () =>
-      Promise.reject(new SessionQueryError('listing failed', 'SESSION_QUERY_PERSISTENCE_FAILED'))
-    await expect(ctx.subagents.listChildren(parent.id)).rejects.toThrow(
-      expect.objectContaining({ code: 'SESSION_QUERY_PERSISTENCE_FAILED' }) as Error,
-    )
+    ctx.sessionPersistence.list = () => Promise.reject(new Error('backend listing failed'))
+    // Without any abort in flight, the original backend failure propagates
+    // as the operation failure — no cancellation mapping, no diagnostic rows.
+    await expect(ctx.subagents.listChildren(parent.id)).rejects.toThrow('backend listing failed')
   })
 
-  it('propagates an unrecognized per-child failure as an operation failure', async () => {
+  it('maps a failed cold inspection to one unavailable diagnostic and retries it next listing', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
-    await startChild(ctx, parent, 'strange failure')
-    const query = ctx.get('sessionQuery')!
-    query.listEvents = () => Promise.reject(new Error('not a query failure'))
-    await expect(ctx.subagents.listChildren(parent.id)).rejects.toThrow('not a query failure')
-  })
-
-  it('propagates a configuration/window query failure instead of diagnosing the child', async () => {
-    const { ctx, parent } = await setup([textResponse('done')])
-    await startChild(ctx, parent, 'misconfigured query')
-    const query = ctx.get('sessionQuery')!
-    query.listEvents = () =>
-      Promise.reject(new SessionQueryError('bad window', 'SESSION_QUERY_INVALID_WINDOW'))
-    await expect(ctx.subagents.listChildren(parent.id)).rejects.toThrow(
-      expect.objectContaining({ code: 'SESSION_QUERY_INVALID_WINDOW' }) as Error,
-    )
+    const healthy = await startChild(ctx, parent, 'healthy sibling')
+    const flaky = await authorChild(ctx, '00000000-0000-4000-8000-00000000f1a7', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('flaky storage')))
+    const original = ctx.sessionPersistence.inspect.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.inspect = (sessionId, signal) => {
+      if (sessionId === flaky) {
+        return Promise.reject(new Error('backend read failed'))
+      }
+      return original(sessionId, signal)
+    }
+    // Per-child isolation: the failed child degrades to one diagnostic while
+    // the healthy sibling stays complete.
+    const degraded = await ctx.subagents.listChildren(parent.id)
+    expect(degraded).toContainEqual({ kind: 'diagnostic', id: flaky, reason: 'unavailable' })
+    expect(degraded).toContainEqual({
+      kind: 'child', id: healthy, label: 'healthy sibling', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    })
+    // Nothing is memoized: with the backend healthy again, the next listing
+    // folds the same child to its identity.
+    ctx.sessionPersistence.inspect = original
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toContainEqual({
+      kind: 'child', id: flaky, label: 'flaky storage', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    })
   })
 
   it('lists compacted and uncompacted children identically', async () => {
@@ -492,19 +709,18 @@ describe('SubagentService.listChildren', () => {
     ])
   })
 
-  it('reports an origin-classified grandchild without reading its events', async () => {
+  it('reports an origin-classified grandchild without inspecting it', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     const childId = await startChild(ctx, parent, 'direct child')
     const grandchildId = await authorChild(ctx, '00000000-0000-4000-8000-0000000000cc', {
       parentSession: childId,
       origin: 'subagent',
     }, childEvents(descriptorPayload('grandchild')))
-    const query = ctx.get('sessionQuery')!
-    const originalListEvents = query.listEvents.bind(query)
     const inspected: SessionId[] = []
-    query.listEvents = (sessionId) => {
+    const original = ctx.sessionPersistence.inspect.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.inspect = (sessionId, signal) => {
       inspected.push(sessionId)
-      return originalListEvents(sessionId)
+      return original(sessionId, signal)
     }
     const entries = await ctx.subagents.listChildren(parent.id)
     expect(entries).toEqual([
@@ -513,10 +729,112 @@ describe('SubagentService.listChildren', () => {
         activity: 'inactive', hasChildren: true,
       },
     ])
+    // The grandchild contributes only its header to the hasChildren hint.
     expect(inspected).toContain(childId)
     expect(inspected).not.toContain(grandchildId)
   })
 
+  it('inspects each cold child exactly once and a live child never', async () => {
+    const { ctx, parent } = await setup([textResponse('done')])
+    const coldStarted = await startChild(ctx, parent, 'cold started child')
+    const coldAuthored = await authorChild(ctx, '00000000-0000-4000-8000-00000000ab01', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('cold authored child')))
+    const liveId = SessionId('live-mixed-child')
+    const live = ctx.sessions.create(liveId, {
+      meta: { parentSession: parent.id, origin: 'subagent' },
+    })
+    live.append('turn/start', { turn: 1 })
+    live.append('subagent/descriptor', descriptorPayload('live mixed child'))
+
+    const inspected: SessionId[] = []
+    const original = ctx.sessionPersistence.inspect.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.inspect = (sessionId, signal) => {
+      inspected.push(sessionId)
+      return original(sessionId, signal)
+    }
+    const entries = await ctx.subagents.listChildren(parent.id)
+    expect(entries).toHaveLength(3)
+    // The cost model: one inspection per cold child, none for a live child,
+    // whose identity is served from the registry's watermark cache.
+    expect(inspected.filter(id => id === coldStarted)).toHaveLength(1)
+    expect(inspected.filter(id => id === coldAuthored)).toHaveLength(1)
+    expect(inspected).not.toContain(liveId)
+  })
+
+  it('serves a cold child from the projection cache without any inspection', async () => {
+    const { ctx, parent } = await setup([textResponse('done')], { projectionCache: true })
+    const childId = await startChild(ctx, parent, 'cached child')
+    // The child's turn/end and disposal are the cache's mandatory checkpoint
+    // points; both writes are fail-soft asynchronous, so wait for the row.
+    const header = (await ctx.sessionPersistence.list()).find(meta => meta.id === childId)
+    await vi.waitFor(() => {
+      expect(ctx.sessionProjectionCache.cachedSnapshot(header!)?.values.subagent).toBeDefined()
+    }, { timeout: 5_000 })
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect')
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
+      kind: 'child', id: childId, label: 'cached child', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    }])
+    expect(inspect).not.toHaveBeenCalled()
+  })
+
+  it('falls back to inspection when the cache serves no identity for the child', async () => {
+    const { ctx, parent } = await setup([], { projectionCache: true })
+    const foreign = await authorChild(ctx, '00000000-0000-4000-8000-00000000ac01', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('uncached child')))
+    const expected = [{
+      kind: 'child', id: foreign, label: 'uncached child', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    }]
+    // No stored row at all for a foreign child this process never ran.
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect')
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual(expected)
+    expect(inspect).toHaveBeenCalledTimes(1)
+    // A stored row whose cut predates the descriptor: the subagent key is
+    // absent from the served values, and preparation still rules.
+    ctx.sessionProjectionCache.cachedSnapshot = () => ({ asOfSeq: 0, values: {} })
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual(expected)
+    expect(inspect).toHaveBeenCalledTimes(2)
+  })
+
+  it('takes the preparation rung directly when no projection cache is mounted', async () => {
+    const { ctx, parent } = await setup([])
+    expect(ctx.get('sessionProjectionCache')).toBeUndefined()
+    const foreign = await authorChild(ctx, '00000000-0000-4000-8000-00000000ac02', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('uncacheable child')))
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect')
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
+      kind: 'child', id: foreign, label: 'uncacheable child', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    }])
+    expect(inspect).toHaveBeenCalledTimes(1)
+  })
+
+  it('silently falls through to preparation when the cache read throws', async () => {
+    const { ctx, parent } = await setup([], { projectionCache: true })
+    const recovered = await authorChild(ctx, '00000000-0000-4000-8000-00000000ac03', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('recovered child')))
+    ctx.sessionProjectionCache.cachedSnapshot = () => {
+      // A poisoned stored row (any unit's) detonates at view time; the cache
+      // is derived data, so its failure must not become a verdict.
+      throw new Error('poisoned cache row')
+    }
+    const inspect = vi.spyOn(ctx.sessionPersistence, 'inspect')
+    await expect(ctx.subagents.listChildren(parent.id)).resolves.toEqual([{
+      kind: 'child', id: recovered, label: 'recovered child', mode: 'continuable',
+      activity: 'inactive', hasChildren: false,
+    }])
+    expect(inspect).toHaveBeenCalledTimes(1)
+  })
+
   it('does not count an ordinary grandchild without subagent origin', async () => {
     const { ctx, parent } = await setup([textResponse('done')])
     const childId = await startChild(ctx, parent, 'direct child')
@@ -550,115 +868,92 @@ describe('SubagentService.listChildren', () => {
     }])
   })
 
-  it('stops the scan at the between-candidates checkpoint when the signal aborts', async () => {
-    const { ctx, parent } = await setup([textResponse('one'), textResponse('two')])
-    await startChild(ctx, parent, 'first child')
-    await startChild(ctx, parent, 'second child')
-    const controller = new AbortController()
-    const query = ctx.get('sessionQuery')!
-    const originalListEvents = query.listEvents.bind(query)
-    let inspected = 0
-    query.listEvents = (sessionId) => {
-      inspected += 1
-      // Cancel while the first candidate's read is in flight: the loop's next
-      // between-candidates checkpoint must stop before the second read.
-      controller.abort()
-      return originalListEvents(sessionId)
-    }
-    await expect(ctx.subagents.listChildren(parent.id, controller.signal)).rejects.toThrow(
-      expect.objectContaining({ code: 'CANCELLED' }) as Error,
-    )
-    expect(inspected).toBe(1)
-  })
-
-  it('forwards cancellation to the initial trace and reports the stable subagent error', async () => {
+  it('a pre-aborted signal stops before any persistence read', async () => {
     const { ctx, parent } = await setup([])
     const controller = new AbortController()
-    const query = ctx.get('sessionQuery')!
-    const entered = Promise.withResolvers<undefined>()
-    query.traceSession = (_sessionId, signal) => {
-      entered.resolve(undefined)
-      return new Promise((_resolve, reject) => {
-        signal?.addEventListener('abort', () => {
-          reject(new Error('query trace aborted'))
-        }, { once: true })
-      })
-    }
-    const listing = ctx.subagents.listChildren(parent.id, controller.signal)
-    await entered.promise
     controller.abort()
-    await expect(listing).rejects.toThrow(
-      expect.objectContaining({ code: 'CANCELLED' }) as Error,
-    )
-  })
-
-  it('forwards cancellation to the exact descriptor read and reports the stable subagent error', async () => {
-    const { ctx, parent } = await setup([textResponse('done')])
-    await startChild(ctx, parent, 'cancelled exact read')
-    const controller = new AbortController()
-    const query = ctx.get('sessionQuery')!
-    const entered = Promise.withResolvers<undefined>()
-    query.readEvent = (_request, signal) => {
-      entered.resolve(undefined)
-      return new Promise((_resolve, reject) => {
-        signal?.addEventListener('abort', () => {
-          reject(new Error('query read aborted'))
-        }, { once: true })
-      })
-    }
-    const listing = ctx.subagents.listChildren(parent.id, controller.signal)
-    await entered.promise
-    controller.abort()
-    await expect(listing).rejects.toThrow(
-      expect.objectContaining({ code: 'CANCELLED' }) as Error,
-    )
-  })
-
-  it('stops after a per-child read when the signal aborts mid-inspection', async () => {
-    const { ctx, parent } = await setup([textResponse('done')])
-    await startChild(ctx, parent, 'cancelled mid-read')
-    const controller = new AbortController()
-    const query = ctx.get('sessionQuery')!
-    const originalReadEvent = query.readEvent.bind(query)
-    let exactReads = 0
-    query.readEvent = async (request) => {
-      exactReads += 1
-      const window = await originalReadEvent(request)
-      controller.abort()
-      return window
-    }
-    // The post-read checkpoint throws a subagent error, which is not a
-    // session-query failure and therefore propagates instead of becoming a
-    // per-child diagnostic.
-    await expect(ctx.subagents.listChildren(parent.id, controller.signal))
-      .rejects.toThrow(expect.objectContaining({ code: 'CANCELLED' }) as Error)
-    expect(exactReads).toBe(1)
-  })
-
-  it('a mapped per-child failure during an abort cannot become a successful result', async () => {
-    const { ctx, parent } = await setup([textResponse('done')])
-    await startChild(ctx, parent, 'aborted behind a diagnostic')
-    const controller = new AbortController()
-    const query = ctx.get('sessionQuery')!
-    query.listEvents = () => {
-      // The read fails with a diagnostic-mapped code while the caller aborts:
-      // cancellation normalization must fail the scan rather than return a
-      // one-diagnostic success.
-      controller.abort()
-      return Promise.reject(new SessionQueryError('backend read failed', 'SESSION_QUERY_PERSISTENCE_FAILED'))
-    }
+    ctx.sessionPersistence.list = () => Promise.reject(new Error('must not be called'))
     await expect(ctx.subagents.listChildren(parent.id, controller.signal)).rejects.toThrow(
       expect.objectContaining({ code: 'CANCELLED' }) as Error,
     )
   })
 
-  it('a pre-aborted signal stops before any candidate read', async () => {
-    const { ctx, parent } = await setup([textResponse('done')])
-    await startChild(ctx, parent, 'never read')
+  it('forwards cancellation to the persisted listing and reports the stable subagent error', async () => {
+    const { ctx, parent } = await setup([])
     const controller = new AbortController()
+    const entered = Promise.withResolvers<undefined>()
+    ctx.sessionPersistence.list = (signal) => {
+      entered.resolve(undefined)
+      return new Promise((_resolve, reject) => {
+        signal?.addEventListener('abort', () => {
+          reject(new Error('backend listing aborted'))
+        }, { once: true })
+      })
+    }
+    const listing = ctx.subagents.listChildren(parent.id, controller.signal)
+    await entered.promise
     controller.abort()
-    const query = ctx.get('sessionQuery')!
-    query.listEvents = () => Promise.reject(new Error('must not be called'))
+    await expect(listing).rejects.toThrow(
+      expect.objectContaining({ code: 'CANCELLED' }) as Error,
+    )
+  })
+
+  it('forwards cancellation to a cold inspection and reports the stable subagent error', async () => {
+    const { ctx, parent } = await setup([])
+    await authorChild(ctx, '00000000-0000-4000-8000-00000000ce11', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('cancelled cold read')))
+    const controller = new AbortController()
+    const entered = Promise.withResolvers<undefined>()
+    ctx.sessionPersistence.inspect = (_sessionId, signal) => {
+      entered.resolve(undefined)
+      return new Promise((_resolve, reject) => {
+        signal?.addEventListener('abort', () => {
+          reject(new Error('backend read aborted'))
+        }, { once: true })
+      })
+    }
+    const listing = ctx.subagents.listChildren(parent.id, controller.signal)
+    await entered.promise
+    controller.abort()
+    await expect(listing).rejects.toThrow(
+      expect.objectContaining({ code: 'CANCELLED' }) as Error,
+    )
+  })
+
+  it('an abort observed after a cold inspection resolves cannot become a successful result', async () => {
+    const { ctx, parent } = await setup([])
+    await authorChild(ctx, '00000000-0000-4000-8000-00000000ce12', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('cancelled mid-listing')))
+    const controller = new AbortController()
+    const original = ctx.sessionPersistence.inspect.bind(ctx.sessionPersistence)
+    ctx.sessionPersistence.inspect = async (sessionId, signal) => {
+      const result = await original(sessionId, signal)
+      controller.abort()
+      return result
+    }
+    // The post-read checkpoint throws the stable subagent error instead of
+    // interpreting the fully-read log as a successful listing.
+    await expect(ctx.subagents.listChildren(parent.id, controller.signal))
+      .rejects.toThrow(expect.objectContaining({ code: 'CANCELLED' }) as Error)
+  })
+
+  it('a cold inspection failure during an abort cannot become an unavailable diagnostic', async () => {
+    const { ctx, parent } = await setup([])
+    await authorChild(ctx, '00000000-0000-4000-8000-00000000ce13', {
+      parentSession: parent.id,
+      origin: 'subagent',
+    }, childEvents(descriptorPayload('aborted behind a failure')))
+    const controller = new AbortController()
+    ctx.sessionPersistence.inspect = () => {
+      // The read fails while the caller aborts: cancellation normalization
+      // must fail the listing rather than return a one-diagnostic success.
+      controller.abort()
+      return Promise.reject(new Error('backend read failed'))
+    }
     await expect(ctx.subagents.listChildren(parent.id, controller.signal)).rejects.toThrow(
       expect.objectContaining({ code: 'CANCELLED' }) as Error,
     )
@@ -671,9 +966,9 @@ describe('SubagentService.listChildren', () => {
   })
 
   it('SubagentError from listChildren is typed with its stable code', async () => {
-    const { ctx, parent } = await setup([], { sessionQuery: false })
+    const { ctx, parent } = await setup([], { sessionProjections: false })
     const caught: unknown = await ctx.subagents.listChildren(parent.id).catch((error: unknown) => error)
     expect(caught).toBeInstanceOf(SubagentError)
-    expect((caught as SubagentError).code).toBe('SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE')
+    expect((caught as SubagentError).code).toBe('SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE')
   })
 })
diff --git a/packages/subagent/subagent/tests/optional-session-query.spec.ts b/packages/subagent/subagent/tests/optional-session-query.spec.ts
deleted file mode 100644
index 469087e576..0000000000
--- a/packages/subagent/subagent/tests/optional-session-query.spec.ts
+++ /dev/null
@@ -1,13 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-
-describe('@deepseek-ai/dsh-subagent optional session-query peer', () => {
-  it('loads ordinary subagent operations without evaluating the optional query package', async () => {
-    vi.doMock('@deepseek-ai/dsh-session-query', () => {
-      throw new Error('optional session-query runtime was loaded eagerly')
-    })
-
-    const subagent = await import('../src/index.ts')
-
-    expect(subagent.SubagentService).toBeTypeOf('function')
-  })
-})
diff --git a/packages/subagent/subagent/tests/timing-projection.spec.ts b/packages/subagent/subagent/tests/timing-projection.spec.ts
index e9a3be43ea..0165f73714 100644
--- a/packages/subagent/subagent/tests/timing-projection.spec.ts
+++ b/packages/subagent/subagent/tests/timing-projection.spec.ts
@@ -23,11 +23,15 @@ describe('subagent timing projection', () => {
     await ctx.plugin(SessionProjectionRegistry)
     const serviceFiber = await ctx.plugin(SubagentService)
 
-    expect(ctx.sessionProjections.snapshot(ctx.sessions.create()).values.subagentTiming)
-      .toEqual({ settledMs: 0 })
+    const before = ctx.sessionProjections.snapshot(ctx.sessions.create()).values
+    expect(before.subagentTiming).toEqual({ settledMs: 0 })
+    // The identity unit registers alongside timing; an empty log serves its
+    // serializable null sentinel.
+    expect(before.subagent).toBeNull()
     await serviceFiber.dispose()
-    expect(ctx.sessionProjections.snapshot(ctx.sessions.create()).values.subagentTiming)
-      .toBeUndefined()
+    const after = ctx.sessionProjections.snapshot(ctx.sessions.create()).values
+    expect(after.subagentTiming).toBeUndefined()
+    expect(after.subagent).toBeUndefined()
   })
 
   it('resets inherited seed timing at the child descriptor and sums later completed turns', () => {
diff --git a/packages/subagent/subagent/tsconfig.json b/packages/subagent/subagent/tsconfig.json
index 612330c646..de2fff3d84 100644
--- a/packages/subagent/subagent/tsconfig.json
+++ b/packages/subagent/subagent/tsconfig.json
@@ -30,10 +30,10 @@
       "path": "../../session-persistence/session-persistence"
     },
     {
-      "path": "../../session-query/session-query"
+      "path": "../../session-projection/session-projection"
     },
     {
-      "path": "../../session-projection/session-projection"
+      "path": "../../session-projection/session-projection-cache"
     },
     {
       "path": "../../tasks/tasks"
diff --git a/packages/subagent/tool-subagent-control/README.i18n.yaml b/packages/subagent/tool-subagent-control/README.i18n.yaml
index d6bd2d78b9..f26a290f5e 100644
--- a/packages/subagent/tool-subagent-control/README.i18n.yaml
+++ b/packages/subagent/tool-subagent-control/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/tool-subagent-control/README.md
-README.md: 5d775a524c38750953c6389b9ebdea67a33df7ca
-README.zh.md: 3b989fca8b79cea3e3b10bb2e65805e0cee79c69
+README.md: ea95a45b85e01d1f5f1c478a35c80c65151724ac
+README.zh.md: 2cc876c8b39caa19fdf30eae7c8def0ba81fe7b1
diff --git a/packages/subagent/tool-subagent-control/README.md b/packages/subagent/tool-subagent-control/README.md
index 5d775a524c..ea95a45b85 100644
--- a/packages/subagent/tool-subagent-control/README.md
+++ b/packages/subagent/tool-subagent-control/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The optional, globally named `send_message` and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and requires only `subagents`; the separately loadable `./list-agents` plugin registers `list_agents`, declares `sessionQuery` as a load-time dependency, and remains inactive until that service is available. A deployment without session query keeps `send_message` and omits the list tool. Neither tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
+The optional, globally named `send_message` and `list_agents` tools are thin adapters over `ctx.subagents`. Provider-bound `@deepseek-ai/dsh-tool-subagent` instances register distinct delegation tools per transport; this separately loaded package registers shared control tools once, so multiple delegation tools never register duplicate global controls. The root plugin registers `send_message` and the separately loadable `./list-agents` plugin registers `list_agents`; both require only `subagents`, so a deployment can keep `send_message` while omitting the list tool. Neither tool's presence determines whether a delegation tool starts continuable work. These tools own only the parent-to-child direction; the independently installed [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) owns the child-to-parent direction.
 
 The tool performs no lifecycle routing — residency and cold resume belong to the subagent service. It passes `exec.agent` as the exact live parent that authorizes delivery and attributes every message as durable provenance `{ kind: 'coordinator', senderSessionId: parent.id }`, which the service retains but never treats as authority. Every message becomes the subagent's next FIFO turn through `Agent.followup()`: if the child is still working, the message waits until its current turn finishes, so it cannot redirect work already underway. The tool forwards its execution signal, which owns admission only until inbox acceptance; once the child accepts the message the accepted turn cannot be cancelled through this tool. This call returns no child reply — its transcript by that id is the source of what it did — and a child with `report` sends content on its own initiative as a separate parent message. A delivery failure becomes an errored tool result stating the message was not delivered.
 
diff --git a/packages/subagent/tool-subagent-control/README.zh.md b/packages/subagent/tool-subagent-control/README.zh.md
index 3b989fca8b..2cc876c8b3 100644
--- a/packages/subagent/tool-subagent-control/README.zh.md
+++ b/packages/subagent/tool-subagent-control/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-可选的全局具名 `send_message` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message`，且只要求 `subagents`；可单独加载的 `./list-agents` 插件注册 `list_agents`，将 `sessionQuery` 声明为加载时依赖，并在该服务可用前保持未激活状态。没有会话查询服务的部署可保留 `send_message` 并省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
+可选的全局具名 `send_message` 与 `list_agents` 工具是 `ctx.subagents` 之上的轻量适配器。绑定提供方的 `@deepseek-ai/dsh-tool-subagent` 实例会为每种传输注册不同的委派工具；这个单独加载的包只注册一次共享控制工具，因此多个委派工具绝不会重复注册全局控制工具。根插件注册 `send_message`，可单独加载的 `./list-agents` 插件注册 `list_agents`；两者都只要求 `subagents`，部署可保留 `send_message` 而省略列表工具。是否加载这些工具不会决定委派工具是否启动可继续工作。这些工具只负责父到子的方向；单独安装的 [`@deepseek-ai/dsh-tool-subagent-report`](../tool-subagent-report/README.md) 负责子到父的方向。
 
 本工具不执行生命周期路由：驻留与冷恢复归 subagent 服务所有。它将 `exec.agent` 作为授权投递的确切在线父级传入，并把每条消息的来源标记为持久化来源 `{ kind: 'coordinator', senderSessionId: parent.id }`；服务会保留该来源，但绝不将其视为权限。每条消息都会通过 `Agent.followup()` 成为子 agent（智能体）的下一个 FIFO 轮次：如果子 agent 仍在工作，该消息会等待其当前轮次结束，因此无法重定向已经在进行的工作。本工具会转发其执行信号，该信号只在 inbox 接受之前掌管准入；一旦子 agent 接受消息，已接受的轮次便无法再通过本工具取消。本次调用不会返回子 agent 的回复；通过该 id 查看其 transcript（文本记录），才是了解它完成了哪些工作的真源。拥有 `report` 的子 agent 会自行把内容作为一条单独的父级消息发回。投递失败会变为出错的工具结果，并明确说明消息未送达。
 
diff --git a/packages/subagent/tool-subagent-control/package.json b/packages/subagent/tool-subagent-control/package.json
index f0d57c52aa..8c7841ef63 100644
--- a/packages/subagent/tool-subagent-control/package.json
+++ b/packages/subagent/tool-subagent-control/package.json
@@ -33,16 +33,10 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-session-query": "^0.0.1",
     "@deepseek-ai/dsh-subagent": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
-  "peerDependenciesMeta": {
-    "@deepseek-ai/dsh-session-query": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
@@ -52,7 +46,7 @@
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-session-persistence": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
-    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-subagent-spawn": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
diff --git a/packages/subagent/tool-subagent-control/src/list-agents.ts b/packages/subagent/tool-subagent-control/src/list-agents.ts
index 75f9cbe450..bab3fb6f40 100644
--- a/packages/subagent/tool-subagent-control/src/list-agents.ts
+++ b/packages/subagent/tool-subagent-control/src/list-agents.ts
@@ -1,20 +1,17 @@
 /**
  * The globally named `list_agents` tool: a thin model-facing adapter over
- * the continuable projection of `ctx.subagents.listChildren()`. It is
- * separately loadable from the
- * root `send_message` plugin because it additionally requires the session
- * query service — a deployment may use `send_message` without loading session
- * query, and this plugin remains inactive until that service is available.
+ * the continuable projection of `ctx.subagents.listChildren()`. It stays
+ * separately loadable from the root `send_message` plugin so a deployment
+ * can register `send_message` without exposing the list tool.
  * @module @deepseek-ai/dsh-tool-subagent-control/list-agents
  */
 
 import type { Context } from 'cordis'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-session-query'
 import type {} from '@deepseek-ai/dsh-subagent'
 
 export const name = 'tool-subagent-list-agents'
-export const inject = ['tools', 'subagents', 'sessionQuery']
+export const inject = ['tools', 'subagents']
 
 type ListAgentsEntry =
   | {
@@ -31,7 +28,7 @@ type ListAgentsEntry =
 
 /**
  * Register the `list_agents` tool.
- * @param ctx - context carrying the tool registry, subagent service, and session query.
+ * @param ctx - context carrying the tool registry and subagent service.
  */
 export function apply(ctx: Context): void {
   ctx.tools.register(defineTool({
diff --git a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
index 9872f73456..e734ae8222 100644
--- a/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/list-agents.spec.ts
@@ -8,11 +8,11 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import type { SubagentListEntry } from '@deepseek-ai/dsh-subagent'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
-import { TestSessionQueryService } from '../../../session-query/session-query/tests/test-service.ts'
 import * as tool from '../src/list-agents.ts'
 
 const testToolSignal = new AbortController().signal
@@ -29,9 +29,9 @@ async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
   roots.push(root)
   await ctx.plugin(JsonlSessionPersistence, { root })
   await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(SessionProjectionRegistry)
   await ctx.plugin(SubagentService)
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
-  await ctx.plugin(TestSessionQueryService)
   await ctx.plugin(tool)
   ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
   const parent = ctx.agentLoop.create(SessionId('parent'), { provider: 'mock', model: 'mock' })
@@ -177,17 +177,16 @@ describe('dsh-tool-subagent-control/list-agents', () => {
     await mountAgentLoopTestDependencies(ctx)
     await ctx.plugin(AgentLoop, { agents: [] })
     await ctx.plugin(SubagentService)
-    await ctx.plugin(TestSessionQueryService)
     const fiber = await ctx.plugin(tool)
     expect(ctx.tools.schemas().some(schema => schema.name === 'list_agents')).toBe(true)
     await fiber.dispose()
     expect(ctx.tools.schemas().some(schema => schema.name === 'list_agents')).toBe(false)
   })
 
-  it('has the namespace-plugin export shape and requires sessionQuery at load', () => {
+  it('has the namespace-plugin export shape', () => {
     expect('default' in tool).toBe(false)
     expect(tool.name).toBe('tool-subagent-list-agents')
-    expect(tool.inject).toEqual(['tools', 'subagents', 'sessionQuery'])
+    expect(tool.inject).toEqual(['tools', 'subagents'])
     expect(typeof tool.apply).toBe('function')
   })
 })
diff --git a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
index 302e053abe..db674b0599 100644
--- a/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
+++ b/packages/subagent/tool-subagent-control/tests/tool-subagent-control.spec.ts
@@ -8,6 +8,7 @@ import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import JsonlSessionPersistence from '@deepseek-ai/dsh-session-persistence-jsonl'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SubagentService from '@deepseek-ai/dsh-subagent'
 import * as SubagentSpawn from '@deepseek-ai/dsh-subagent-spawn'
 import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
@@ -27,6 +28,7 @@ async function setup(script: ConstructorParameters<typeof MockAdapter>[0]) {
   roots.push(root)
   await ctx.plugin(JsonlSessionPersistence, { root })
   await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(SessionProjectionRegistry)
   await ctx.plugin(SubagentService)
   await ctx.plugin(SubagentSpawn, { providerName: 'spawn' })
   await ctx.plugin(tool)
diff --git a/packages/subagent/tool-subagent-control/tsconfig.json b/packages/subagent/tool-subagent-control/tsconfig.json
index 91eeb707b0..3a57a0437e 100644
--- a/packages/subagent/tool-subagent-control/tsconfig.json
+++ b/packages/subagent/tool-subagent-control/tsconfig.json
@@ -26,9 +26,6 @@
     {
       "path": "../subagent"
     },
-    {
-      "path": "../../session-query/session-query"
-    },
     {
       "path": "../../support/invariants"
     }
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index f95c5ad09d..67894c32cb 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -67,8 +67,8 @@ export interface Config {
    * requires the provider's `depthLimit` capability (mount fails loud
    * otherwise). The provider checks the calling agent's current depth at every
    * start; the tool remains model-visible so runtime policy owns rejection.
-   * `'provider-managed'` is for an out-of-process provider (ACP) whose
-   * recursion budget belongs to the child harness's own deployment.
+   * `'provider-managed'` is for an out-of-process provider whose recursion
+   * budget belongs to the child runtime or its own deployment.
    */
   maxDepth?: number | 'provider-managed'
 }
diff --git a/packages/subprocess/subprocess-local/package.json b/packages/subprocess/subprocess-local/package.json
index 2aa69b82e1..e1429bffd0 100644
--- a/packages/subprocess/subprocess-local/package.json
+++ b/packages/subprocess/subprocess-local/package.json
@@ -27,11 +27,13 @@
   "peerDependencies": {
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-subprocess": "^0.0.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }
 }
diff --git a/packages/subprocess/subprocess-local/src/spawn.ts b/packages/subprocess/subprocess-local/src/spawn.ts
index 90d460c2c5..462da41382 100644
--- a/packages/subprocess/subprocess-local/src/spawn.ts
+++ b/packages/subprocess/subprocess-local/src/spawn.ts
@@ -15,6 +15,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { setTimeout as sleepMs } from 'node:timers/promises'
 import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 import type {
   CollectedOutput,
   SubprocessCollect,
@@ -26,12 +27,12 @@ import type {
 
 /**
  * Build a child environment: explicit caller entries merge after the scrubbed
- * parent base, so a deliberately supplied credential or current `DSH_*` fact
- * wins over the scrub that dropped its ambient namesake.
- * @param extra - explicit caller entries, merged verbatim after the scrub.
+ * parent base. A string deliberately restores or overrides an entry; an
+ * explicit `undefined` tombstone removes an ordinary ambient entry.
+ * @param extra - explicit caller entries and tombstones, merged after the scrub.
  * @returns the environment to hand to `spawn` for the child process.
  */
-export function childEnv(extra?: Readonly<Record<string, string>>): NodeJS.ProcessEnv {
+export function childEnv(extra?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
   return { ...scrubbedParentEnv(), ...extra }
 }
 
@@ -298,8 +299,12 @@ function signalTree(
  * @param spec - fully resolved argv, cwd, stdio, grace, cancellation, environment.
  * @param internals - test-only spill-directory, platform, and taskkill overrides.
  * @returns live subprocess handle.
+ * @throws when `graceMs` cannot be represented by one Node timer.
  */
 export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInternals = {}): SubprocessHandle {
+  if (!Number.isFinite(spec.graceMs) || spec.graceMs <= 0 || spec.graceMs > MAX_TIMER_DELAY_MS) {
+    throw new Error(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+  }
   const spillDir = internals.spillDir ?? privateSpillDir()
   const platform = internals.platform ?? process.platform
   const taskkill = internals.taskkill ?? taskkillProcessTree
@@ -341,7 +346,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   const stdoutCollector = collectStream(outMode, child.stdout, 'stdout')
   const stderrCollector = collectStream(errMode, child.stderr, 'stderr')
 
-  let graceTimer: NodeJS.Timeout | undefined
+  let graceTimer: ReturnType<typeof setTimeout> | undefined
+  let treeExitObserved = false
+  let treeExitObservation: Promise<void> | undefined
   let settled = false
 
   // Failed spawns use pid -1 so signalling remains a no-op.
@@ -349,6 +356,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
 
   /** Whether the detached tree's root (or POSIX group) is still alive. */
   const treeAlive = (): boolean => {
+    /* v8 ignore next -- only a timer callback already queued when the observer settles can enter here;
+       the guard is the final defense against probing an id after its tree was confirmed absent. */
+    if (treeExitObserved) return false
     if (pid <= 0) return false
     if (platform === 'win32') {
       // Windows has no group-liveness probe; the direct child's exit is the
@@ -371,19 +381,40 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
     }
   }
 
+  /**
+   * Start or reuse the handle's single whole-tree exit observer. The first
+   * confirmed absence is a permanent no-more-signals boundary: it cancels a
+   * pending escalation before this process-group id can be reused.
+   */
+  const observeTreeExit = (): Promise<void> => {
+    treeExitObservation ??= (async () => {
+      while (treeAlive()) await sleepTick()
+      treeExitObserved = true
+      if (graceTimer !== undefined) clearTimeout(graceTimer)
+      graceTimer = undefined
+    })()
+    return treeExitObservation
+  }
+
   // The escalation's tier primitive (not on the handle — terminate() is the
   // only consumer-facing termination verb). Guards on TREE liveness, not
   // outcome settlement: a TERM-trapping helper can outlive the settled direct
   // child and must stay signalable, while a fully-dead tree (possible pid
   // reuse) must not be re-signalled by a later tier.
   const kill = (sig: NodeJS.Signals): void => {
+    /* v8 ignore next -- the shared exit observer cancels the ordinary dead-tree timer;
+       this remains the timer/death race guard and cannot be staged deterministically. */
     if (!treeAlive()) return
     signalTree(platform, pid, sig, child, taskkill)
   }
 
   const terminate = (): void => {
-    if (graceTimer !== undefined) return // escalation already in flight
-    if (!treeAlive()) return
+    if (treeExitObserved || graceTimer !== undefined) return
+    // Observe from the first termination tier onward, even when inherited
+    // pipes delay `done` and no consumer has begun its own teardown wait.
+    void observeTreeExit()
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- observer can record absence before its first await.
+    if (treeExitObserved) return
     kill('SIGTERM')
     // The escalation must survive direct-child settlement — the leader dying
     // does not mean the tree died — so settle does not clear this timer, and
@@ -405,7 +436,7 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   }
 
   const done = new Promise<SubprocessOutcome>((resolve, reject) => {
-    let pipeDrainTimer: NodeJS.Timeout | undefined
+    let pipeDrainTimer: ReturnType<typeof setTimeout> | undefined
     const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
       if (settled) return
       settled = true
@@ -428,7 +459,9 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
       // A surviving descendant that inherited a pipe must not hold the
       // outcome open indefinitely: after exit, the same bounded grace that
       // governs kills also bounds the close wait.
-      pipeDrainTimer = setTimeout(() => { settle(exitCode, signal) }, spec.graceMs)
+      pipeDrainTimer = setTimeout(() => {
+        settle(exitCode, signal)
+      }, spec.graceMs)
     })
     child.on('close', settle)
     function cleanup(): void {
@@ -440,11 +473,23 @@ export function spawnSubprocess(spec: SubprocessSpawnSpec, internals: SpawnInter
   })
 
   const waitForExit = async (signal?: AbortSignal): Promise<boolean> => {
-    while (treeAlive()) {
-      if (signal?.aborted) return false
-      await sleepTick()
+    const observed = observeTreeExit()
+    if (treeExitObserved) return true
+    if (signal?.aborted) return false
+    if (signal === undefined) {
+      await observed
+      return true
+    }
+    const aborted = Promise.withResolvers<boolean>()
+    const onAbort = (): void => { aborted.resolve(false) }
+    signal.addEventListener('abort', onAbort, { once: true })
+    /* v8 ignore next -- closes the event-loop race between the preceding aborted check and listener registration. */
+    if (signal.aborted) onAbort()
+    try {
+      return await Promise.race([observed.then(() => true), aborted.promise])
+    } finally {
+      signal.removeEventListener('abort', onAbort)
     }
-    return true
   }
 
   return {
diff --git a/packages/subprocess/subprocess-local/tests/spawn.spec.ts b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
index 491756f01f..08b6b1dbf8 100644
--- a/packages/subprocess/subprocess-local/tests/spawn.spec.ts
+++ b/packages/subprocess/subprocess-local/tests/spawn.spec.ts
@@ -2,8 +2,14 @@ import { mkdtempSync, readFileSync, statSync, unlinkSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
-import { killGroup, OutputCollector, spawnSubprocess, taskkillProcessTree } from '../src/spawn.ts'
+import {
+  killGroup,
+  OutputCollector,
+  spawnSubprocess,
+  taskkillProcessTree,
+} from '../src/spawn.ts'
 import type { SubprocessHandle, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
 
 const { failNextClose, failNextUnlink } = vi.hoisted(() => ({
   failNextClose: { value: false },
@@ -102,6 +108,14 @@ async function waitForPidFile(path: string, timeoutMs = 5_000): Promise<number>
 }
 
 describe('spawnSubprocess', () => {
+  it.each([0, -1, Number.NaN, Number.POSITIVE_INFINITY, MAX_TIMER_DELAY_MS + 1])(
+    'rejects an invalid grace before spawning: %s',
+    (graceMs) => {
+      expect(() => spawnSubprocess(spec('true', { graceMs })))
+        .toThrow(`subprocess graceMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`)
+    },
+  )
+
   it('captures stdout on success', async () => {
     const result = await finish(spawnSubprocess(spec('echo hello')))
     expect(result.exitCode).toBe(0)
@@ -164,6 +178,54 @@ describe('spawnSubprocess', () => {
     expect(result.signal).toBe('SIGKILL')
   })
 
+  it('cancels escalation when the terminated group vanishes before collected pipes drain', async () => {
+    const pidFile = join(spillDir, `escaped-pipe-holder-${Date.now()}.pid`)
+    const graceMs = 160
+    const childScript = `
+      const { spawn } = require('node:child_process')
+      const { writeFileSync } = require('node:fs')
+      const helper = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
+        detached: true,
+        stdio: ['ignore', 1, 2],
+      })
+      writeFileSync(${JSON.stringify(pidFile)}, String(helper.pid))
+      helper.unref()
+      setInterval(() => {}, 1000)
+    `
+    const running = spawnSubprocess({
+      ...spec('unused', { graceMs }),
+      argv: [process.execPath, '-e', childScript],
+    })
+    const helper = await waitForPidFile(pidFile)
+    const realKill: typeof process.kill = process.kill.bind(process)
+    let termAt = 0
+    let forceSignals = 0
+    const killSpy = vi.spyOn(process, 'kill').mockImplementation((target, signal) => {
+      if (target !== -running.pid) return realKill(target, signal)
+      if (signal === 'SIGTERM') {
+        termAt = Date.now()
+        return realKill(target, signal)
+      }
+      if (signal === 'SIGKILL') {
+        forceSignals += 1
+        return true
+      }
+      if (signal === 0 && termAt !== 0 && Date.now() - termAt < graceMs / 2) {
+        throw Object.assign(new Error('simulated vanished process group'), { code: 'ESRCH' })
+      }
+      return true // Before TERM the original group is live; later its pgid is reused.
+    })
+    try {
+      running.terminate()
+      await running.done
+      expect(forceSignals).toBe(0)
+    } finally {
+      killSpy.mockRestore()
+      process.kill(helper, 'SIGKILL')
+      await waitGone(helper)
+    }
+  })
+
   it('terminates the whole process group (grandchildren die too)', async () => {
     // The subshell writes the sleep's pid then waits on it; terminating the
     // group must take the sleep down with bash.
@@ -254,6 +316,19 @@ describe('stdin and extra env (set by in-process plugins)', () => {
     expect(result.stdout.text).toBe('alpha/beta\n')
   })
 
+  it('lets an explicit tombstone remove an ordinary ambient env entry', async () => {
+    process.env.SUBPROCESS_TOMBSTONE_PROBE = 'ambient-value'
+    try {
+      const result = await finish(spawnSubprocess(spec(
+        'echo "${SUBPROCESS_TOMBSTONE_PROBE:-absent}"',
+        { env: { SUBPROCESS_TOMBSTONE_PROBE: undefined } },
+      )))
+      expect(result.stdout.text).toBe('absent\n')
+    } finally {
+      delete process.env.SUBPROCESS_TOMBSTONE_PROBE
+    }
+  })
+
   it('an explicit extra env entry overrides the credential scrub', async () => {
     // EXPLICIT_OVERRIDE_PASSWORD matches the credential scrub pattern, yet an explicit
     // entry is still honored — the scrub only drops AMBIENT process.env creds.
@@ -627,7 +702,6 @@ describe('coverage seams', () => {
   it('terminate() after the tree died delivers no termination signal', async () => {
     const running = spawnSubprocess(spec('true'))
     await running.done
-    await running.waitForExit()
     const spy = vi.spyOn(process, 'kill')
     try {
       running.terminate()
@@ -636,6 +710,21 @@ describe('coverage seams', () => {
     } finally {
       spy.mockRestore()
     }
+    await running.waitForExit()
+  })
+
+  it('repeated terminate after exit never probes or signals a reused process group', async () => {
+    const running = spawnSubprocess(spec('sleep 60'))
+    running.terminate()
+    await running.done
+    await running.waitForExit()
+    const spy = vi.spyOn(process, 'kill').mockImplementation(() => true)
+    try {
+      running.terminate()
+      expect(spy).not.toHaveBeenCalled()
+    } finally {
+      spy.mockRestore()
+    }
   })
 
   it('waitForExit on a failed spawn reports exited immediately', async () => {
diff --git a/packages/subprocess/subprocess-local/tsconfig.json b/packages/subprocess/subprocess-local/tsconfig.json
index 5a8dea211b..5272a4f78d 100644
--- a/packages/subprocess/subprocess-local/tsconfig.json
+++ b/packages/subprocess/subprocess-local/tsconfig.json
@@ -17,6 +17,9 @@
     {
       "path": "../subprocess"
     },
+    {
+      "path": "../../util/timeout"
+    },
     {
       "path": "../../support/invariants"
     }
diff --git a/packages/subprocess/subprocess/README.i18n.yaml b/packages/subprocess/subprocess/README.i18n.yaml
index 88567e6317..b178daafb2 100644
--- a/packages/subprocess/subprocess/README.i18n.yaml
+++ b/packages/subprocess/subprocess/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/subprocess/subprocess/README.md
-README.md: c360437bf2b2b95734f55f6aec46b0cecffb9260
-README.zh.md: 914ab16b40c688867eb20afc3de60a38fd88d42b
+README.md: e59dd96df036826f36bd0286c977438d2d87d1cf
+README.zh.md: e8fb89dfd1f8c41a0caefc96469c13d9ae7d415d
diff --git a/packages/subprocess/subprocess/README.md b/packages/subprocess/subprocess/README.md
index c360437bf2..e59dd96df0 100644
--- a/packages/subprocess/subprocess/README.md
+++ b/packages/subprocess/subprocess/README.md
@@ -7,10 +7,10 @@ The subprocess seam (`ctx.subprocess`). The abstract `SubprocessService` exposes
 ## Contract
 
 - `spawn(spec)` returns immediately with a live handle; `done` resolves at process close with exit facts (`SubprocessOutcome` carries no output and no cause classification) and rejects only for spawn-level failures.
-- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
+- The spec is fully explicit — argv, cwd, per-stream stdio dispositions, grace — because deployment-varying defaults belong to the calling seam's config, not to a hidden subprocess-service default (the `dsh-bash` request/spec split is the owning template). Grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so the implementation can represent it with one Node timer instead of accepting a value that Node collapses to one millisecond. `argv` is never shell-interpreted; a consumer that wants a shell passes `['bash', '-c', command]` itself.
 - Stdio is Node-shaped per stream: `'pipe'` hands the caller the raw stream for its own protocol framing (LSP JSON-RPC, ACP ndjson), `'inherit'` passes the parent descriptor through for diagnostics, and collect mode (`{ maxBytes, spill? }`) buffers a bounded tail with an optional full-stream spill file. Collect readers take whole-stream byte offsets and never consume, so independent readers cannot steal one another's deltas; a read whose offset slid out of the in-memory tail is `lossy` and points at the spill file when one exists. Collected output stays readable after settlement.
 - Termination is tree-scoped on every platform (POSIX detached groups with direct-child fallback; Windows `taskkill /T`): `terminate()` — the only termination verb — escalates SIGTERM→grace→SIGKILL (idempotent, driven by the spec's abort signal too, a no-op once the tree is gone), and `waitForExit(signal?)` observes whole-tree liveness so a consumer-owned teardown ladder holds each tier on real quiescence — the manager reacts but never classifies why (callers own deadlines, teardown ladders, and cause classification).
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and the spec's explicit `env` merges after the scrub with no namespace validation — a deliberately forwarded credential or a current `DSH_*` fact survives precisely because it is an explicit caller opt-in, while the stale ambient namesake never reaches the child. Spawners that cannot route through the service (node-pty backends, SDK-managed transports) import the scrub.
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` are the one shared scrub definition: ambient credential-shaped and `DSH_*` names are dropped, and the spec's explicit `env` merges after the scrub with no namespace validation — a string deliberately forwards or overrides a value, while an `undefined` tombstone removes an ordinary ambient entry. Spawners that cannot route through the service (node-pty backends, SDK-managed transports) import the scrub.
 - Disposal of the service terminates all still-running managed processes and awaits their exit.
 
 See the [subprocess data-structure catalog](../../../docs/core-data-structures/subprocess.md) and the [seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md).
diff --git a/packages/subprocess/subprocess/README.zh.md b/packages/subprocess/subprocess/README.zh.md
index 914ab16b40..e8fb89dfd1 100644
--- a/packages/subprocess/subprocess/README.zh.md
+++ b/packages/subprocess/subprocess/README.zh.md
@@ -7,10 +7,10 @@
 ## 契约
 
 - `spawn(spec)` 立即返回一个活动句柄；`done` 在进程关闭时以退出事实 resolve（`SubprocessOutcome` 不携带输出，也不携带原因分类），仅在 spawn 层面失败时 reject。
-- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
+- spec 完全显式（argv、cwd、按流划分的 stdio 处置方式（disposition）、宽限期），因为随部署变化的默认值属于调用方 seam 的配置，而不属于某个隐藏的子进程默认值（`dsh-bash` 的 request/spec 拆分是这条规则的所属模板）。宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样实现便可用一个 Node 定时器表示它，而不会接受会被 Node 折叠为 1 毫秒的值。`argv` 绝不经过 shell 解释；需要 shell 的消费方自行传入 `['bash', '-c', command]`。
 - stdio 按流采用 Node 风格：`'pipe'` 把原始流交给调用方做自己的协议分帧（LSP 的 JSON-RPC、ACP（Agent Client Protocol）的 ndjson），`'inherit'` 直通父进程描述符以承载诊断输出，收集模式（collect）`{ maxBytes, spill? }` 则缓冲一段有界尾部，外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费，因此独立的读取器不会抢走彼此的增量；偏移量滑出内存尾部窗口的读取标记为 `lossy`，并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
 - 终止在每个平台上都以进程树为范围（POSIX 用 detached 进程组并以直接子进程回退；Windows 用 `taskkill /T`）：`terminate()`（唯一的终止动词）执行 SIGTERM→宽限期→SIGKILL 升级（幂等，也由 spec 的 abort 信号驱动，进程树消亡后为空操作）；`waitForExit(signal?)` 观察整棵进程树的存活状态，使消费方自有的拆卸阶梯能在真正完全停稳后才进入下一层。管理器只响应中止，但绝不判定原因（deadline、拆卸阶梯与原因分类归调用方所有）。
-- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，spec 的显式 `env` 在清除之后合并且不做命名空间校验——有意转发的凭据或当前 `DSH_*` 事实之所以能保留下来，正因为它是调用方的显式选择，而陈旧的同名环境值永远到不了子进程。无法把 spawn 路由到该服务的进程启动方（node-pty 后端、由 SDK 管理的传输层）改为导入环境清理函数。
+- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的环境清理定义：环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃，spec 的显式 `env` 在清理后合并且不做命名空间校验——字符串会有意转发或覆盖某个值，而 `undefined` tombstone 则会删除普通的环境条目。无法把 spawn 路由到该服务的进程启动方（node-pty 后端、由 SDK 管理的传输层）会导入该环境清理定义。
 - 服务自身的 dispose（资源释放）会终止所有仍在运行的受管进程并等待其退出。
 
 参见[子进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与[seam Agent Note](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
diff --git a/packages/subprocess/subprocess/src/types.ts b/packages/subprocess/subprocess/src/types.ts
index fdfc44b3c2..6084cc8c8e 100644
--- a/packages/subprocess/subprocess/src/types.ts
+++ b/packages/subprocess/subprocess/src/types.ts
@@ -80,10 +80,11 @@ export interface SubprocessSpawnSpec {
   /** Per-stream stdio dispositions. */
   stdio: SubprocessStdio
   /**
-   * Grace period in milliseconds for the {@link SubprocessHandle.terminate}
-   * escalation and for draining still-open collected pipes after the process
-   * exits (an inherited descriptor held by a surviving descendant cannot hold
-   * the outcome open indefinitely).
+   * Positive finite grace period in milliseconds, no greater than
+   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
+   * and for draining still-open collected pipes after the process exits (an
+   * inherited descriptor held by a surviving descendant cannot hold the
+   * outcome open indefinitely).
    */
   graceMs: number
   /**
@@ -94,13 +95,12 @@ export interface SubprocessSpawnSpec {
   signal?: AbortSignal | undefined
   /**
    * Explicit environment entries merged onto the implementation's scrubbed
-   * parent base (see `scrubbedParentEnv`), with no namespace validation:
-   * every entry is a deliberate caller opt-in, so a forwarded
-   * credential-shaped entry or a current `DSH_*` fact survives precisely
-   * because this layer merges after the scrub that drops its ambient
-   * namesake.
+   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+   * string is a deliberate caller opt-in, so a forwarded credential-shaped
+   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
+   * tombstone that removes an ordinary ambient entry from the child.
    */
-  env?: Record<string, string> | undefined
+  env?: NodeJS.ProcessEnv | undefined
 }
 
 /**
diff --git a/packages/todo/tool-todo/README.i18n.yaml b/packages/todo/tool-todo/README.i18n.yaml
index e0a1a5ea25..20b8dffbbf 100644
--- a/packages/todo/tool-todo/README.i18n.yaml
+++ b/packages/todo/tool-todo/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/todo/tool-todo/README.md
-README.md: 456d4a08d88b145d574362ffa0874faef9167b22
-README.zh.md: ec37682773e50c3f153525f6c2b6b6cce583144f
+README.md: 914e89a000e4bb87ebd7844f05db3809c6726528
+README.zh.md: c88dbf976fa5110028fcc964ab9aa8efcc3244d3
diff --git a/packages/todo/tool-todo/README.md b/packages/todo/tool-todo/README.md
index 456d4a08d8..914e89a000 100644
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -14,9 +14,15 @@ Registers one tool, `todo_write(todos: [{ content, status }])`, on `ctx.tools`.
 
 The list belongs to the ONE agent session that called the tool. There is no subagent/shared/swarm scope: a non-agent caller (no `exec.agent`) has nowhere to write the list and is rejected. This is a deliberate scope limit — see the Agent Note.
 
+## Configuration
+
+`allowParallelInProgress` is required: every composition must choose whether several todos may be `in_progress` at once. It is a deployment choice, not a fixed rule: whether concurrent active tasks are legitimate depends on runtime concurrency the tool cannot observe. Use `true` for agents that may fan out work and `false` to enforce the single-active discipline.
+
+The flag moves the model-facing instruction and the accepted input together — `true` asks the model to mark every actively worked task and accepts any number, `false` asks for exactly one and rejects a call marking more with `Error: invalid todos: at most one task may be in_progress (got <n>)`. The durable-log invariant does NOT follow it: a log written while parallel work was allowed must still replay after a deployment tightens the policy, so the invariant stays silent on the active count.
+
 ## Validation
 
-Beyond the schema's type/required/enum checks, `execute` rejects an empty or duplicate `content`, more than one `in_progress` task (a coherent plan has at most one task active), and any item key beyond `content`/`status` — an extended item shape (ids, nesting) fails loud instead of silently flattening, keeping the logged snapshot equal to what the model believes it wrote. Ordering and the discipline of keeping the list current are left to the model via the tool description.
+Beyond the schema's type/required/enum checks, `execute` rejects an empty or duplicate `content`, and any item key beyond `content`/`status` — an extended item shape (ids, nesting) fails loud instead of silently flattening, keeping the logged snapshot equal to what the model believes it wrote. How many tasks may be `in_progress` at once is the deployment's call (§ Configuration): a composition that chooses `true` permits parallel work (concurrent subagents, background commands) to mark several tasks simultaneously. Ordering and the discipline of keeping the list current are left to the model via the tool description.
 
 ## Rendering
 
@@ -50,7 +56,7 @@ Prefix-stable while the definition and visibility are unchanged. Plugin lifecycl
 
 #### What the model sees
 
-Each assistant tool call retains the entire replacement list in its arguments. Success returns exactly `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.` Stable failures are ``Error: invalid todo: `content` must be a non-empty string``, `Error: invalid todos: duplicate content "<content>"`, `Error: invalid todos: at most one task may be in_progress, got <count>`, and `Error: todo_write requires an owning agent session`. The full `todo/write` session event is UI and replay state, not a second model message.
+Each assistant tool call retains the entire replacement list in its arguments. Success returns exactly `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.` Stable failures are ``Error: invalid todo: `content` must be a non-empty string``, `Error: invalid todos: duplicate content "<content>"`, `Error: todo_write requires an owning agent session`, and — only where the deployment set `allowParallelInProgress: false` — `Error: invalid todos: at most one task may be in_progress (got <n>)`. The full `todo/write` session event is UI and replay state, not a second model message.
 
 #### Token effect
 
diff --git a/packages/todo/tool-todo/README.zh.md b/packages/todo/tool-todo/README.zh.md
index ec37682773..c88dbf976f 100644
--- a/packages/todo/tool-todo/README.zh.md
+++ b/packages/todo/tool-todo/README.zh.md
@@ -14,9 +14,15 @@
 
 该列表属于调用工具的唯一 agent 会话。不存在 subagent／共享／swarm scope：非 agent 调用方（没有 `exec.agent`）无处写入列表，因此会被拒绝。这是有意设置的 scope 限制，详见 Agent Note（agent 决策记录）。
 
+## 配置
+
+`allowParallelInProgress` 是必填项：每个组合都必须选择是否允许多个 todo 同时处于 `in_progress`。这是部署层的选择而非固定规则：并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况。可能并行展开工作的 agent 使用 `true`，`false` 则强制执行单活跃项纪律。
+
+该开关会同时改变面向模型的指令与接受的输入——`true` 要求模型标记每个正在推进的任务并接受任意数量；`false` 要求恰好一个，并以 `Error: invalid todos: at most one task may be in_progress (got <n>)` 拒绝标记更多的调用。持久日志不变式**不**跟随它：在允许并行时写下的日志，在部署收紧策略之后仍必须可回放，因此不变式对活跃数量保持沉默。
+
 ## 验证
 
-除 schema 的类型／必填／枚举检查外，`execute` 还会拒绝空或重复的 `content`、同时存在多个 `in_progress` 任务的情况（连贯计划最多只有一个活跃任务），以及 `content`/`status` 之外的任何条目键——扩展条目形状（id、嵌套）会明确报错而不是被静默压平，保证落日志的快照与模型自认为写入的内容一致。列表的顺序及及时更新由模型依照工具描述负责。
+除 schema 的类型／必填／枚举检查外，`execute` 还会拒绝空或重复的 `content`，以及 `content`/`status` 之外的任何条目键——扩展条目形状（id、嵌套）会明确报错而不是被静默压平，保证落日志的快照与模型自认为写入的内容一致。同时可以有多少任务处于 `in_progress` 由部署决定（见 § 配置）：选择 `true` 的组合允许并行工作（并发 subagent、后台命令）同时将多个任务标记为 `in_progress`。列表的顺序及及时更新由模型依照工具描述负责。
 
 ## 渲染
 
@@ -50,7 +56,7 @@
 
 #### 模型看到的内容
 
-每个 assistant 工具调用都会在参数中保留整个替换列表。成功时原样返回 `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.`。稳定失败文本为 ``Error: invalid todo: `content` must be a non-empty string``、`Error: invalid todos: duplicate content "<content>"`、`Error: invalid todos: at most one task may be in_progress, got <count>` 和 `Error: todo_write requires an owning agent session`。完整 `todo/write` 会话事件是 UI 与回放状态，而非第二条模型消息。
+每个 assistant 工具调用都会在参数中保留整个替换列表。成功时原样返回 `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.`。稳定失败文本为 ``Error: invalid todo: `content` must be a non-empty string``、`Error: invalid todos: duplicate content "<content>"`、`Error: todo_write requires an owning agent session`，以及——仅在部署设置了 `allowParallelInProgress: false` 时——`Error: invalid todos: at most one task may be in_progress (got <n>)`。完整 `todo/write` 会话事件是 UI 与回放状态，而非第二条模型消息。
 
 #### Token 影响
 
diff --git a/packages/todo/tool-todo/package.json b/packages/todo/tool-todo/package.json
index 0fa3eb0c4f..2c4490589f 100644
--- a/packages/todo/tool-todo/package.json
+++ b/packages/todo/tool-todo/package.json
@@ -30,6 +30,7 @@
   ],
   "license": "BSD-3-Clause",
   "dependencies": {
+    "schemastery": "^3.18.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -41,6 +42,8 @@
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
diff --git a/packages/todo/tool-todo/src/index.ts b/packages/todo/tool-todo/src/index.ts
index 3bce915ee3..0e403c5510 100644
--- a/packages/todo/tool-todo/src/index.ts
+++ b/packages/todo/tool-todo/src/index.ts
@@ -6,7 +6,8 @@
  */
 
 import type { Context } from 'cordis'
-import { z } from 'zod'
+import z from 'schemastery'
+import { z as zod } from 'zod'
 import type { ZodType } from 'zod'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { TodoItem } from '@deepseek-ai/dsh-session'
@@ -24,29 +25,73 @@ export const inject = ['tools']
 /** The valid {@link TodoItem} statuses, as a runtime set for input narrowing. */
 const STATUSES = ['pending', 'in_progress', 'completed'] as const
 
-const DESCRIPTION =
+/** Model-facing todo tool configuration. */
+export interface Config {
+  /**
+   * Required deployment choice for whether several todos may be `in_progress` at once. True suits
+   * agents that run work concurrently — subagents, background commands, workflow fan-out — and the
+   * description then instructs the model to mark every actively worked task. False restores the
+   * single-active discipline: the description asks for exactly one, and a call marking more is
+   * rejected.
+   */
+  allowParallelInProgress: boolean
+}
+
+/** Schemastery configuration for the todo tool consumer. */
+export const Config: z<Config> = z.object({
+  allowParallelInProgress: z.boolean().required(),
+})
+
+const DESCRIPTION_HEAD =
   'Record and update a structured task list for the current work. Send the ENTIRE '
   + 'list every call — it REPLACES the previous list (there are no partial updates, '
   + 'no per-item edits). Use it to plan multi-step work and show progress: add one '
-  + 'todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` '
-  + 'at a time; while work remains, exactly one active task should be '
-  + '`in_progress`. Mark a todo `completed` the moment it is done (do not batch '
-  + 'completions), and allow no `in_progress` item only once all work is complete. '
-  + 'Skip the list for trivial single-step tasks. Statuses: `pending` '
-  + '(not started), `in_progress` (being worked on now), `completed` (finished).'
+  + 'todo per concrete step before you start. '
+
+const DESCRIPTION_PARALLEL =
+  'Mark every todo being actively worked '
+  + 'on `in_progress` — several at once when work genuinely runs in parallel (e.g. '
+  + 'concurrent subagents or background commands), one for sequential work; while '
+  + 'work remains, at least one task should be `in_progress`. '
+
+const DESCRIPTION_SINGLE =
+  'Keep AT MOST ONE todo `in_progress` at a '
+  + 'time; while work remains, exactly one active task should be `in_progress`. '
+
+const DESCRIPTION_TAIL =
+  'Mark a todo '
+  + '`completed` the moment it is done (do not batch completions), and allow no '
+  + '`in_progress` item only once all work is complete. Skip the list for trivial '
+  + 'single-step tasks. Statuses: `pending` (not started), `in_progress` (being '
+  + 'worked on now), `completed` (finished).'
+
+/**
+ * The model-facing description for one activation. The active-status clause is the only part that
+ * varies, because it is the only instruction the parallel policy changes.
+ * @param allowParallel - whether several todos may be `in_progress` at once.
+ * @returns the composed tool description.
+ */
+function describe(allowParallel: boolean): string {
+  return DESCRIPTION_HEAD
+    + (allowParallel ? DESCRIPTION_PARALLEL : DESCRIPTION_SINGLE)
+    + DESCRIPTION_TAIL
+}
 
 /**
  * Validate the value constraints the ParameterSchemaSpec can't express and build the canonical {@link
- * TodoItem}[]: trimmed non-empty unique content and at most one in-progress item. The registry
- * has already enforced the status enum and rejected unknown item keys (`additionalProperties:
- * false` — the logged snapshot must equal what the model believes it wrote, so a nested/extended
- * item shape fails loud at the schema boundary instead of silently flattening); the cast below
- * records that guarantee.
+ * TodoItem}[]: trimmed non-empty unique content, and at most one `in_progress` item unless the
+ * deployment allows parallel work. The registry has already enforced the status enum and rejected
+ * unknown item keys (`additionalProperties: false` — the logged snapshot must equal what the model
+ * believes it wrote, so a nested/extended item shape fails loud at the schema boundary instead of
+ * silently flattening); the cast below records that guarantee.
+ * @param raw - the model-supplied list, already schema-checked.
+ * @param allowParallel - whether several items may be `in_progress` at once.
+ * @returns the canonical list.
  */
-function toTodoList(raw: { content: string; status: string }[]): TodoItem[] {
+function toTodoList(raw: { content: string; status: string }[], allowParallel: boolean): TodoItem[] {
   const todos: TodoItem[] = []
   const seen = new Set<string>()
-  let inProgress = 0
+  let active = 0
   for (const item of raw) {
     const content = item.content.trim()
     if (content.length === 0) {
@@ -56,27 +101,32 @@ function toTodoList(raw: { content: string; status: string }[]): TodoItem[] {
       throw new Error(`invalid todos: duplicate content ${JSON.stringify(content)}`)
     }
     seen.add(content)
-    const status = item.status as TodoItem['status']
-    if (status === 'in_progress') inProgress++
-    todos.push({ content, status })
+    if (item.status === 'in_progress') active++
+    todos.push({ content, status: item.status as TodoItem['status'] })
   }
-  if (inProgress > 1) {
-    throw new Error(`invalid todos: at most one task may be in_progress, got ${inProgress}`)
+  if (!allowParallel && active > 1) {
+    throw new Error(`invalid todos: at most one task may be in_progress (got ${active})`)
   }
   return todos
 }
 
 /** Wire payload schema of the `todos` projection (whole list or pre-first-write null). */
-const todosProjectionSchema: ZodType<TodoItem[] | null> = z.union([
-  z.array(z.object({
-    content: z.string(),
-    status: z.union([z.literal('pending'), z.literal('in_progress'), z.literal('completed')]),
+const todosProjectionSchema: ZodType<TodoItem[] | null> = zod.union([
+  zod.array(zod.object({
+    content: zod.string(),
+    status: zod.union([zod.literal('pending'), zod.literal('in_progress'), zod.literal('completed')]),
   })),
-  z.null(),
+  zod.null(),
 ])
 
-/** Register the `todo_write` tool on `ctx.tools` and, when the session-projection seam is composed, the `todos` unit. */
-export function apply(ctx: Context): void {
+/**
+ * Register the `todo_write` tool on `ctx.tools` and, when the session-projection seam is composed,
+ * the `todos` unit.
+ * @param ctx - registrant context carrying the tool registry.
+ * @param config - deployment's explicit todo policy.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const allowParallel = config.allowParallelInProgress
   // The unit child activates only when a projection registry is composed
   // (headless assemblies without the seam stay unaffected). Standing-plan fold:
   // latest whole todo/write list, cleared by the next turn/start (turn/end keeps
@@ -99,7 +149,7 @@ export function apply(ctx: Context): void {
   })
   ctx.tools.register(defineTool({
     name: 'todo_write',
-    description: DESCRIPTION,
+    description: describe(allowParallel),
     parameters: {
       todos: {
         type: 'array',
@@ -155,7 +205,7 @@ export function apply(ctx: Context): void {
       }],
     },
     execute(args, exec) {
-      const todos = toTodoList(args.todos)
+      const todos = toTodoList(args.todos, allowParallel)
       if (!exec.agent) {
         // The list is per-agent-session state; a non-agent caller (no owning
         // session) has nowhere to write it. Reject rather than silently no-op.
diff --git a/packages/todo/tool-todo/src/invariant.ts b/packages/todo/tool-todo/src/invariant.ts
index d353c80f77..0cfe48a6f2 100644
--- a/packages/todo/tool-todo/src/invariant.ts
+++ b/packages/todo/tool-todo/src/invariant.ts
@@ -12,11 +12,18 @@ export const name = 'tool-todo-invariant'
 /** Service required before the companion can reserve package ownership. */
 export const inject = ['invariants']
 
-/** Validate one whole-list todo snapshot before it reaches the durable log. */
+/**
+ * Validate one whole-list todo snapshot before it reaches the durable log.
+ *
+ * Deliberately silent on how many items are `in_progress`. That is the tool's
+ * per-deployment policy (`Config.allowParallelInProgress`), not a durable-shape
+ * rule: a log written while parallel work was allowed must still replay after a
+ * deployment tightens the policy, so tying the invariant to the current config
+ * would reject history that was valid when it was written.
+ */
 function validateTodos(value: unknown, fail: InvariantFailure): void {
   if (!Array.isArray(value)) fail('todo/write todos must be an array')
   const seen = new Set<string>()
-  let active = 0
   for (const item of value) {
     if (typeof item !== 'object' || item === null) fail('todo/write entries must be objects')
     const { content, status } = item as Record<string, unknown>
@@ -28,9 +35,7 @@ function validateTodos(value: unknown, fail: InvariantFailure): void {
     if (typeof status !== 'string' || !TODO_STATUSES.has(status)) {
       fail(`todo/write carries unknown status ${JSON.stringify(status)}`)
     }
-    if (status === 'in_progress') active += 1
   }
-  if (active > 1) fail(`todo/write contains ${active} in-progress entries; at most one is allowed`)
 }
 
 /* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
diff --git a/packages/todo/tool-todo/tests/integration.spec.ts b/packages/todo/tool-todo/tests/integration.spec.ts
index f8be1ec27f..f10f2c49e2 100644
--- a/packages/todo/tool-todo/tests/integration.spec.ts
+++ b/packages/todo/tool-todo/tests/integration.spec.ts
@@ -18,7 +18,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
   const ctx = new Context()
   await mountAgentLoopTestDependencies(ctx)
   await ctx.plugin(AgentLoop, { agents: [] })
-  await ctx.plugin(ToolTodo)
+  await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
   ctx.llm.registerAdapter(['mock'], adapter)
   return ctx
 }
diff --git a/packages/todo/tool-todo/tests/invariant.spec.ts b/packages/todo/tool-todo/tests/invariant.spec.ts
index f186711845..ac3c76bf71 100644
--- a/packages/todo/tool-todo/tests/invariant.spec.ts
+++ b/packages/todo/tool-todo/tests/invariant.spec.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore, { type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as TodoInvariant from '@deepseek-ai/dsh-tool-todo/invariant'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 
@@ -17,13 +19,22 @@ function event(todos: unknown): SessionEvent {
 }
 
 describe('todo snapshot invariants', () => {
-  it('accepts a unique whole-list snapshot with one active item', async () => {
-    const ctx = await setup()
-    expect(() => { ctx.emit('session/event', {} as Session, event([
+  it('accepts historical and live parallel snapshots under the single-active tool policy', async () => {
+    const todos = [
       { content: 'Inspect state', status: 'completed' },
       { content: 'Apply fix', status: 'in_progress' },
+      { content: 'Watch background build', status: 'in_progress' },
       { content: 'Run checks', status: 'pending' },
-    ])) }).not.toThrow()
+    ] as const
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(ToolTodo, { allowParallelInProgress: false })
+    ctx.sessions.create().append('todo/write', { todos: [...todos] })
+    await ctx.plugin(InvariantService, { enabled: true })
+
+    await expect(ctx.plugin(TodoInvariant).then(() => undefined)).resolves.toBeUndefined()
+    expect(() => { ctx.emit('session/event', {} as Session, event(todos)) }).not.toThrow()
   })
 
   it.each([
@@ -36,7 +47,6 @@ describe('todo snapshot invariants', () => {
     [[{ content: 'same', status: 'pending' }, { content: 'same', status: 'completed' }], /repeats content/],
     [[{ content: 'task', status: 42 }], /unknown status/],
     [[{ content: 'task', status: 'paused' }], /unknown status/],
-    [[{ content: 'one', status: 'in_progress' }, { content: 'two', status: 'in_progress' }], /at most one/],
   ])('rejects an incoherent durable todo snapshot', async (todos, message) => {
     const ctx = await setup()
     expect(() => { ctx.emit('session/event', {} as Session, event(todos)) }).toThrow(message)
diff --git a/packages/todo/tool-todo/tests/loader-composition.spec.ts b/packages/todo/tool-todo/tests/loader-composition.spec.ts
new file mode 100644
index 0000000000..572254e348
--- /dev/null
+++ b/packages/todo/tool-todo/tests/loader-composition.spec.ts
@@ -0,0 +1,139 @@
+// Proves `allowParallelInProgress` is real configurability and not a constant:
+// the flag is set in a cordis.yml booted through the real Loader, and both faces
+// it controls — the model-facing description and the accepted input — follow it.
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
+
+let root: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+function agent(ctx: Context): Agent {
+  const scope = ctx.plugin(() => {})
+  const id = SessionId('todo-loader-agent')
+  const session = Session.create(id)
+  const value: Agent = {
+    id, options: {}, session, inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    status: 'idle', ctx: scope.ctx,
+    followup: () => {}, steer: () => {}, inject: () => {}, send: () => {}, cancel() {},
+    runMaintenance: task => task(new AbortController().signal),
+    whenIdle: () => Promise.resolve(),
+  }
+  ctx.agents.register(value)
+  return value
+}
+
+function resultText(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+/**
+ * Boot a cordis.yml carrying the given tool-todo config block.
+ * @param configLines - YAML lines nested under the tool's `config:` key.
+ * @returns the booted context.
+ */
+async function boot(configLines: readonly string[]): Promise<Context> {
+  root = await mkdtemp(join(tmpdir(), 'dsh-todo-loader-'))
+  const configPath = join(root, 'cordis.yml')
+  await writeFile(configPath, [
+    "- name: '@deepseek-ai/dsh-agent'",
+    "- name: '@deepseek-ai/dsh-system-prompt'",
+    "- name: '@deepseek-ai/dsh-tools'",
+    "- name: '@deepseek-ai/dsh-tool-todo'",
+    ...configLines.length > 0 ? ['  config:', ...configLines] : [],
+    '',
+  ].join('\n'))
+
+  const ctx = new Context()
+  context = ctx
+  ctx.baseUrl = pathToFileURL(root).href + '/'
+  await ctx.plugin(Loader)
+  ctx.loader.builtins.include = Include
+  const modules = new Map<string, unknown>([
+    ['@deepseek-ai/dsh-agent', AgentRegistry],
+    ['@deepseek-ai/dsh-system-prompt', SystemPrompt],
+    ['@deepseek-ai/dsh-tools', ToolRegistry],
+    ['@deepseek-ai/dsh-tool-todo', ToolTodo],
+  ])
+  ctx.loader.internal = {
+    version: 'v2',
+    async import(specifier: string) {
+      if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+      return modules.get(specifier)
+    },
+  } as unknown as NonNullable<typeof ctx.loader.internal>
+  await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(configPath).href } })
+  await ctx.loader.await()
+  return ctx
+}
+
+const PARALLEL_TODOS = [
+  { content: 'run subagent a', status: 'in_progress' },
+  { content: 'run subagent b', status: 'in_progress' },
+]
+
+describe('tool-todo real Loader composition through cordis.yml', () => {
+  it('allowParallelInProgress: false narrows the description and rejects a parallel write', async () => {
+    const ctx = await boot(['    allowParallelInProgress: false'])
+    const description = ctx.tools.schemas().find(s => s.name === 'todo_write')?.description ?? ''
+    expect(description).toContain('Keep AT MOST ONE todo `in_progress`')
+    expect(description).not.toContain('several at once')
+
+    const owner = agent(ctx)
+    const result = await ctx.tools.execute({
+      signal: new AbortController().signal,
+      callId: CallId('parallel'),
+      name: 'todo_write',
+      arguments: { todos: PARALLEL_TODOS },
+      agent: owner,
+    })
+    expect(result.isError).toBe(true)
+    expect(resultText(result)).toContain('at most one task may be in_progress')
+    expect(owner.session.events.some(e => e.type === 'todo/write')).toBe(false)
+  }, 30_000)
+
+  it('allowParallelInProgress: true permits a parallel write end to end', async () => {
+    const ctx = await boot(['    allowParallelInProgress: true'])
+    const description = ctx.tools.schemas().find(s => s.name === 'todo_write')?.description ?? ''
+    expect(description).toContain('several at once when work genuinely runs in parallel')
+
+    const owner = agent(ctx)
+    const result = await ctx.tools.execute({
+      signal: new AbortController().signal,
+      callId: CallId('parallel-enabled'),
+      name: 'todo_write',
+      arguments: { todos: PARALLEL_TODOS },
+      agent: owner,
+    })
+    expect(result.isError).toBe(false)
+    expect(owner.session.events.findLast(e => e.type === 'todo/write')?.data.todos).toEqual(PARALLEL_TODOS)
+  }, 30_000)
+
+  it.each([
+    { label: 'is omitted', configLines: [], failure: '$.allowParallelInProgress missing required value' },
+    { label: 'is not boolean', configLines: ['    allowParallelInProgress: "no"'], failure: '$.allowParallelInProgress expected boolean' },
+  ])('fails loading when allowParallelInProgress $label', async ({ configLines, failure }) => {
+    // The policy is self-contained, so misconfiguration fails at load: the
+    // entry's apply rejects and boot never reaches a running tool.
+    await expect(boot(configLines)).rejects.toThrow(failure)
+  }, 30_000)
+})
diff --git a/packages/todo/tool-todo/tests/projection.spec.ts b/packages/todo/tool-todo/tests/projection.spec.ts
index d751d2a949..f1932b9955 100644
--- a/packages/todo/tool-todo/tests/projection.spec.ts
+++ b/packages/todo/tool-todo/tests/projection.spec.ts
@@ -42,7 +42,7 @@ async function harness(withTodoTool: boolean): Promise<Bench> {
   await ctx.plugin(UserInteractionService)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(SessionProjectionRegistry)
-  if (withTodoTool) await ctx.plugin(ToolTodo)
+  if (withTodoTool) await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
   const session = ctx.sessions.create()
   ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
   const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
@@ -116,7 +116,7 @@ describe('todos projection provider', () => {
   it('drops the key when the tool-todo fiber unloads (HMR safety)', async () => {
     const bench = await harness(false)
     seedMessage(bench.session)
-    const fiber = await bench.ctx.plugin(ToolTodo)
+    const fiber = await bench.ctx.plugin(ToolTodo, { allowParallelInProgress: true })
     expect((await bench.tailProjections())?.values).toEqual({ todos: null })
     await fiber.dispose()
     expect('todos' in ((await bench.tailProjections())?.values ?? {})).toBe(false)
diff --git a/packages/todo/tool-todo/tests/tool-todo.spec.ts b/packages/todo/tool-todo/tests/tool-todo.spec.ts
index 154fde4857..12d1f5f665 100644
--- a/packages/todo/tool-todo/tests/tool-todo.spec.ts
+++ b/packages/todo/tool-todo/tests/tool-todo.spec.ts
@@ -26,11 +26,11 @@ function agentWithSession(id = 'parent-1'): Agent & { session: Session } {
   return { id: SessionId(id), session } as unknown as Agent & { session: Session }
 }
 
-async function setup(): Promise<Context> {
+async function setup(allowParallelInProgress: boolean): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(SystemPrompt)
   await ctx.plugin(ToolRegistry)
-  await ctx.plugin(tool)
+  await ctx.plugin(tool, { allowParallelInProgress })
   return ctx
 }
 
@@ -52,7 +52,7 @@ function text(result: { content: { type: string; text?: string }[] }): string {
 
 describe('dsh-tool-todo', () => {
   it('registers a `todo_write` tool whose schema is an array of {content,status}', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const schema = ctx.tools.schemas().find(s => s.name === 'todo_write')
     expect(schema).toBeDefined()
     const props = (schema!.parameters as { properties?: Record<string, unknown> }).properties ?? {}
@@ -65,7 +65,7 @@ describe('dsh-tool-todo', () => {
   })
 
   it('appends a todo/write event carrying the whole list to the calling session', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const agent = agentWithSession('writer')
     const todos: TodoItem[] = [
       { content: 'plan', status: 'in_progress' },
@@ -85,7 +85,7 @@ describe('dsh-tool-todo', () => {
   })
 
   it('stores the trimmed content (the dedupe/length key), not the raw input', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const agent = agentWithSession('trim')
     const result = await callTodo(ctx, { todos: [{ content: '  plan the work  ', status: 'pending' }] }, { agent })
     expect(result.isError).toBe(false)
@@ -95,7 +95,7 @@ describe('dsh-tool-todo', () => {
   })
 
   it('replaces the list on a second call (last-write-wins on the log)', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const agent = agentWithSession('writer-2')
     await callTodo(ctx, { todos: [{ content: 'a', status: 'pending' }] }, { agent })
     await callTodo(ctx, { todos: [
@@ -111,38 +111,99 @@ describe('dsh-tool-todo', () => {
   })
 
   it('rejects a malformed status before execute runs (registry arg-validation)', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const result = await callTodo(ctx, { todos: [{ content: 'x', status: 'doing' }] })
     expect(result.isError).toBe(true)
   })
 
   it('rejects a non-array todos argument', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const result = await callTodo(ctx, { todos: 'nope' })
     expect(result.isError).toBe(true)
   })
 
+  it('accepts several in_progress items at once (parallel work)', async () => {
+    const ctx = await setup(true)
+    const agent = agentWithSession('parallel')
+    const todos: TodoItem[] = [
+      { content: 'run subagent a', status: 'in_progress' },
+      { content: 'run subagent b', status: 'in_progress' },
+      { content: 'merge results', status: 'pending' },
+    ]
+    const result = await callTodo(ctx, { todos }, { agent })
+    expect(result.isError).toBe(false)
+    if (result.isError) throw new Error('expected todo_write success')
+    expect(result.value).toEqual({
+      todos,
+      counts: { pending: 1, inProgress: 2, completed: 0 },
+    })
+    expect(agent.session.events.findLast(e => e.type === 'todo/write')!.data.todos).toEqual(todos)
+  })
+
+  describe('allowParallelInProgress', () => {
+    const parallel = [
+      { content: 'run subagent a', status: 'in_progress' },
+      { content: 'run subagent b', status: 'in_progress' },
+    ]
+
+    it('false rejects a call marking several items in_progress', async () => {
+      const ctx = await setup(false)
+      const agent = agentWithSession('single-active')
+      const result = await callTodo(ctx, { todos: parallel }, { agent })
+      expect(result.isError).toBe(true)
+      expect(text(result)).toContain('at most one task may be in_progress')
+      // A rejected call must not reach the durable log.
+      expect(agent.session.events.some(e => e.type === 'todo/write')).toBe(false)
+    })
+
+    it('false still accepts one active item', async () => {
+      const ctx = await setup(false)
+      const todos: TodoItem[] = [
+        { content: 'run subagent a', status: 'in_progress' },
+        { content: 'run subagent b', status: 'pending' },
+      ]
+      const result = await callTodo(ctx, { todos })
+      expect(result.isError).toBe(false)
+    })
+
+    it('true accepts the very list false rejects', async () => {
+      const ctx = await setup(true)
+      const result = await callTodo(ctx, { todos: parallel })
+      expect(result.isError).toBe(false)
+    })
+
+    it('instructs the model to keep at most one active, while true instructs parallel', async () => {
+      const single = await setup(false)
+      const singleDesc = single.tools.schemas().find(s => s.name === 'todo_write')!.description
+      expect(singleDesc).toContain('Keep AT MOST ONE todo `in_progress`')
+      expect(singleDesc).not.toContain('several at once')
+
+      const parallelDesc = (await setup(true)).tools.schemas().find(s => s.name === 'todo_write')!.description
+      expect(parallelDesc).toContain('several at once when work genuinely runs in parallel')
+      expect(parallelDesc).not.toContain('AT MOST ONE')
+    })
+  })
+
   it.each([
     { label: 'empty content', todos: [{ content: '   ', status: 'pending' }], fragment: 'non-empty' },
     { label: 'duplicate content', todos: [{ content: 'dup', status: 'pending' }, { content: 'dup', status: 'completed' }], fragment: 'duplicate' },
-    { label: 'two in_progress', todos: [{ content: 'a', status: 'in_progress' }, { content: 'b', status: 'in_progress' }], fragment: 'in_progress' },
     { label: 'unknown item keys', todos: [{ content: 'a', status: 'pending', children: [] }], fragment: 'not a declared property' },
   ])('rejects $label as an isError result', async ({ todos, fragment }) => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const result = await callTodo(ctx, { todos })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain(fragment)
   })
 
   it('rejects a non-agent caller (the list has no owning session)', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const result = await callTodo(ctx, { todos: [{ content: 'a', status: 'pending' }] }, { agent: undefined })
     expect(result.isError).toBe(true)
     expect(text(result)).toContain('owning agent session')
   })
 
   it('presents the call with a stable title and the list as raw input', async () => {
-    const ctx = await setup()
+    const ctx = await setup(true)
     const def = ctx.tools.get('todo_write')!
     const todos = [{ content: 'a', status: 'pending' }]
     expect(def.presentCall?.({ todos })).toEqual({ card: 'generic', title: 'Update todo list', kind: 'other', rawInput: todos })
@@ -152,7 +213,7 @@ describe('dsh-tool-todo', () => {
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)
-    const fiber = await ctx.plugin(tool)
+    const fiber = await ctx.plugin(tool, { allowParallelInProgress: true })
     expect(ctx.tools.schemas().some(s => s.name === 'todo_write')).toBe(true)
     await fiber.dispose()
     expect(ctx.tools.schemas().some(s => s.name === 'todo_write')).toBe(false)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index aaaed3c423..8f34b3587b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -319,6 +319,9 @@ importers:
       '@deepseek-ai/dsh-commands':
         specifier: workspace:*
         version: link:../packages/ui/commands
+      '@deepseek-ai/dsh-compact':
+        specifier: workspace:*
+        version: link:../packages/compact/compact
       '@deepseek-ai/dsh-compact-basic':
         specifier: workspace:*
         version: link:../packages/compact/compact-basic
@@ -415,6 +418,9 @@ importers:
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:*
         version: link:../packages/session-persistence/session-persistence-jsonl
+      '@deepseek-ai/dsh-session-projection':
+        specifier: workspace:*
+        version: link:../packages/session-projection/session-projection
       '@deepseek-ai/dsh-session-query':
         specifier: workspace:*
         version: link:../packages/session-query/session-query
@@ -454,6 +460,12 @@ importers:
       '@deepseek-ai/dsh-subagent-acp':
         specifier: workspace:*
         version: link:../packages/subagent/subagent-acp
+      '@deepseek-ai/dsh-subagent-claude-code':
+        specifier: workspace:*
+        version: link:../packages/subagent/subagent-claude-code
+      '@deepseek-ai/dsh-subagent-codex':
+        specifier: workspace:*
+        version: link:../packages/subagent/subagent-codex
       '@deepseek-ai/dsh-subagent-dsh-sdk':
         specifier: workspace:*
         version: link:../packages/subagent/subagent-dsh-sdk
@@ -934,6 +946,9 @@ importers:
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
         version: link:../../session-persistence/session-persistence-jsonl
+      '@deepseek-ai/dsh-session-projection':
+        specifier: workspace:^
+        version: link:../../session-projection/session-projection
       '@deepseek-ai/dsh-session-query-sqlite':
         specifier: workspace:^
         version: link:../../session-query/session-query-sqlite
@@ -1179,9 +1194,6 @@ importers:
       '@deepseek-ai/dsh-host-webserver':
         specifier: workspace:^
         version: link:../../host/webserver
-      '@deepseek-ai/dsh-session-projection':
-        specifier: workspace:^
-        version: link:../../session-projection/session-projection
       '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
         version: link:../../session-projection/session-projection-cache
@@ -3266,6 +3278,9 @@ importers:
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
@@ -4436,6 +4451,9 @@ importers:
       '@deepseek-ai/dsh-tool-subagent':
         specifier: workspace:^
         version: link:../../subagent/tool-subagent
+      '@deepseek-ai/dsh-tool-todo':
+        specifier: workspace:^
+        version: link:../../todo/tool-todo
       '@deepseek-ai/dsh-tool-web':
         specifier: workspace:^
         version: link:../../web/tool-web
@@ -5178,9 +5196,15 @@ importers:
       '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
         version: link:../../session-projection/session-projection
-      '@deepseek-ai/dsh-session-query':
+      '@deepseek-ai/dsh-session-projection-cache':
         specifier: workspace:^
-        version: link:../../session-query/session-query
+        version: link:../../session-projection/session-projection-cache
+      '@deepseek-ai/dsh-storage':
+        specifier: workspace:^
+        version: link:../../storage/storage
+      '@deepseek-ai/dsh-storage-domain':
+        specifier: workspace:^
+        version: link:../../storage/storage-domain
       '@deepseek-ai/dsh-tasks':
         specifier: workspace:^
         version: link:../../tasks/tasks
@@ -5227,6 +5251,98 @@ importers:
       '@deepseek-ai/dsh-subprocess-local':
         specifier: workspace:^
         version: link:../../subprocess/subprocess-local
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/subagent/subagent-claude-code:
+    dependencies:
+      '@anthropic-ai/claude-agent-sdk':
+        specifier: 0.3.220
+        version: 0.3.220(@anthropic-ai/sdk@0.93.0(zod@4.4.3))(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(zod@4.4.3)
+      '@anthropic-ai/sdk':
+        specifier: 0.93.0
+        version: 0.93.0(zod@4.4.3)
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-loader-smoke':
+        specifier: workspace:^
+        version: link:../../support/loader-smoke
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-subagent':
+        specifier: workspace:^
+        version: link:../subagent
+      '@deepseek-ai/dsh-subprocess':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: link:../../../vendor/cordis
+
+  packages/subagent/subagent-codex:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
+    devDependencies:
+      '@cordisjs/plugin-loader':
+        specifier: ^1.0.0-rc.5
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-loader-smoke':
+        specifier: workspace:^
+        version: link:../../support/loader-smoke
+      '@deepseek-ai/dsh-sdk-protocol':
+        specifier: workspace:^
+        version: link:../../sdk/sdk-protocol
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-subagent':
+        specifier: workspace:^
+        version: link:../subagent
+      '@deepseek-ai/dsh-subprocess':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess
+      '@deepseek-ai/dsh-subprocess-local':
+        specifier: workspace:^
+        version: link:../../subprocess/subprocess-local
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
+      '@openai/codex':
+        specifier: 0.146.0
+        version: 0.146.0
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -5486,9 +5602,9 @@ importers:
       '@deepseek-ai/dsh-session-persistence-jsonl':
         specifier: workspace:^
         version: link:../../session-persistence/session-persistence-jsonl
-      '@deepseek-ai/dsh-session-query':
+      '@deepseek-ai/dsh-session-projection':
         specifier: workspace:^
-        version: link:../../session-query/session-query
+        version: link:../../session-projection/session-projection
       '@deepseek-ai/dsh-subagent':
         specifier: workspace:^
         version: link:../subagent
@@ -5565,6 +5681,9 @@ importers:
       '@deepseek-ai/dsh-subprocess':
         specifier: workspace:^
         version: link:../subprocess
+      '@deepseek-ai/dsh-timeout':
+        specifier: workspace:^
+        version: link:../../util/timeout
       cordis:
         specifier: ^4.0.0-rc.7
         version: link:../../../vendor/cordis
@@ -5828,10 +5947,19 @@ importers:
 
   packages/todo/tool-todo:
     dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: link:../../../vendor/schemastery
       zod:
         specifier: ^4.4.3
         version: 4.4.3
     devDependencies:
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
@@ -7067,6 +7195,58 @@ packages:
   '@antfu/install-pkg@1.1.0':
     resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
 
+  '@anthropic-ai/claude-agent-sdk-darwin-arm64@0.3.220':
+    resolution: {integrity: sha512-7VxlbEosK7DODiOnsjoVd0DSJzbnaPrM2jelMHI0y8zx1UnLS3WC6EFUXbvy74F2sXqEznh2tzn7EKWInaRN6Q==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@anthropic-ai/claude-agent-sdk-darwin-x64@0.3.220':
+    resolution: {integrity: sha512-X9RwDsSmbF6ultKZroaip+DL8WRgC64gHbrAwrRlAFSPNZV7zmJyP2ur8rW7KrxqmtuehdMMkw8+SAC/6hD2PA==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@anthropic-ai/claude-agent-sdk-linux-arm64-musl@0.3.220':
+    resolution: {integrity: sha512-OHoZOZ8Cf2TBr6oXIXPwyvUxj9jrq2w8E4poA8dMpacXszcPSPiCQCMuuOh4aWJzfeJE1+TtWxhKMVb2csXyZQ==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@anthropic-ai/claude-agent-sdk-linux-arm64@0.3.220':
+    resolution: {integrity: sha512-WkROPwWskqhKR9XgnmseHQ6rLi9zM9qt57IWoToIjL/eXOqDWipp7JXZ1L5ud+LrA42dunHPZfBwD/vXZ+A7LA==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@anthropic-ai/claude-agent-sdk-linux-x64-musl@0.3.220':
+    resolution: {integrity: sha512-K+FWj+LcGhC1Z7wqeWoLxm1iemcba5xKpLLFVwYm4V6HyMx3ruYd/2r2TiQtjT+JWeNFWIys0ScHiItR6vWAiA==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@anthropic-ai/claude-agent-sdk-linux-x64@0.3.220':
+    resolution: {integrity: sha512-tkTJFnpR9VifvWX2fmkCAPkT6+8Wk/gVu8B5jsVekKZPiZoWRHmMXO30BnZn+f0TZhgYP+82PSX3S8crH1kn+w==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@anthropic-ai/claude-agent-sdk-win32-arm64@0.3.220':
+    resolution: {integrity: sha512-rIwgq0UwQExWl6KrHUyC4w5KwpL9l6nd95aUTx6RitexaAuEw//xtfTVLnuE4hDDQZFkzEwpdKc3nxDWoGcUbA==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@anthropic-ai/claude-agent-sdk-win32-x64@0.3.220':
+    resolution: {integrity: sha512-MuOuXhbr66HlGaWXD2f3w0k2PsvmnbkwcUZ0dAe2poFLdl72GC2dapwwOBefxm9QmoNqk9+jmv/dSKGOVWyvLw==}
+    cpu: [x64]
+    os: [win32]
+
+  '@anthropic-ai/claude-agent-sdk@0.3.220':
+    resolution: {integrity: sha512-glc7SdwPkOkLw8oxwLo9PKTdLJGqW/PIR4urWXFoRtX9YllwozsEVc5Tc1+EvLSkfrsxPJqQWqOgpjUOQXf1oA==}
+    engines: {node: '>=18.0.0'}
+    peerDependencies:
+      '@anthropic-ai/sdk': '>=0.93.0'
+      '@modelcontextprotocol/sdk': ^1.29.0
+      zod: ^4.0.0
+
   '@anthropic-ai/sdk@0.91.1':
     resolution: {integrity: sha512-LAmu761tSN9r66ixvmciswUj/ZC+1Q4iAfpedTfSVLeswRwnY3n2Nb6Tsk+cLPP28aLOPWeMgIuTuCcMC6W/iw==}
     hasBin: true
@@ -7076,6 +7256,15 @@ packages:
       zod:
         optional: true
 
+  '@anthropic-ai/sdk@0.93.0':
+    resolution: {integrity: sha512-q9vaSZQVFx6B/gPxetGYfLXSJD5v0sOmh0OpZDq7yCrTSA+Rscvrtyol7JJTW40wEpQB4U1B4JXzxQitbQ3CAA==}
+    hasBin: true
+    peerDependencies:
+      zod: ^3.25.0 || ^4.0.0
+    peerDependenciesMeta:
+      zod:
+        optional: true
+
   '@asamuzakjp/css-color@5.1.11':
     resolution: {integrity: sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==}
     engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
@@ -8082,6 +8271,47 @@ packages:
   '@nodable/entities@2.2.0':
     resolution: {integrity: sha512-9uGyhaQavEUMC8AIddIjau4NsnsXhou+j5sBAGojCM1oxmQpVKTWR/9JxABD6UAv12vpIms55fPZKFQEhG6uBg==}
 
+  '@openai/codex@0.146.0':
+    resolution: {integrity: sha512-yG3sPWNda/2YAIQIDq9MrrjoCTIQ7rxYM5IasrG3VBcuhCLTkgeg/JzqmJq1V98RE4MJ5jCxDXXQlOjrditFRw==}
+    engines: {node: '>=16'}
+    hasBin: true
+
+  '@openai/codex@0.146.0-darwin-arm64':
+    resolution: {integrity: sha512-nb61yX4r5L6Z0dlC4o3u0GAK1YCd4TUvjaB382bajDoh84V+uv2hTBIVZ++fgXWV9yoeuNrNnNcn7GoTGOe2Tg==}
+    engines: {node: '>=16'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@openai/codex@0.146.0-darwin-x64':
+    resolution: {integrity: sha512-hTQR5jy/ObfTf1MDnuJCZJAe+SljKE8DDwQWN6lDFgjsPhMQz852U2tILt8Ei+G5GkQSzemHYKl2AYPwW0Y5xw==}
+    engines: {node: '>=16'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@openai/codex@0.146.0-linux-arm64':
+    resolution: {integrity: sha512-qiYDxkkEFnXG7joadJW6Q+XcgyDXCpGdpa9nk/c+i0gEomur1j7bHvx12NfWWCF/y8Tqri6ay+FLuC2MjdehtA==}
+    engines: {node: '>=16'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@openai/codex@0.146.0-linux-x64':
+    resolution: {integrity: sha512-fswvyGprAPCMiOEue/7MKMk7pCjh9kZIJfJX5i9atmfnmGYbYCcUhZsEH9LEP0+0t5xyPqDbfNXY7NSxIVuXxA==}
+    engines: {node: '>=16'}
+    cpu: [x64]
+    os: [linux]
+
+  '@openai/codex@0.146.0-win32-arm64':
+    resolution: {integrity: sha512-EW6zdjDe+SLX2Iw+xymJ5+Pz2+DGexdstfFHXh4Ub+TfJsQPiMjGfZfNaoWgdJ2FsqSIzVKu2+G0KCMGYz2W8g==}
+    engines: {node: '>=16'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@openai/codex@0.146.0-win32-x64':
+    resolution: {integrity: sha512-b3lxMYeR0+IhstNo4JjX1P9cPc1xwVcCVkPd1lD1wpWPJ0SBhpIkPczwbu3ZRkJcdyl342+rgyf4DUrbZLdrGA==}
+    engines: {node: '>=16'}
+    cpu: [x64]
+    os: [win32]
+
   '@opentelemetry/api-logs@0.220.0':
     resolution: {integrity: sha512-CmVa4ImJ+ynfrPMNaAXHET6Bhb44SwzmfyVJFq9ni2jgXJR/l7C6gfVFddNmHP+ZOkP9cf4f9DBe68qVLTHc9w==}
     engines: {node: '>=8.0.0'}
@@ -12324,12 +12554,57 @@ snapshots:
       package-manager-detector: 1.6.0
       tinyexec: 1.2.4
 
+  '@anthropic-ai/claude-agent-sdk-darwin-arm64@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk-darwin-x64@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk-linux-arm64-musl@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk-linux-arm64@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk-linux-x64-musl@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk-linux-x64@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk-win32-arm64@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk-win32-x64@0.3.220':
+    optional: true
+
+  '@anthropic-ai/claude-agent-sdk@0.3.220(@anthropic-ai/sdk@0.93.0(zod@4.4.3))(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(zod@4.4.3)':
+    dependencies:
+      '@anthropic-ai/sdk': 0.93.0(zod@4.4.3)
+      '@modelcontextprotocol/sdk': 1.29.0(zod@4.4.3)
+      zod: 4.4.3
+    optionalDependencies:
+      '@anthropic-ai/claude-agent-sdk-darwin-arm64': 0.3.220
+      '@anthropic-ai/claude-agent-sdk-darwin-x64': 0.3.220
+      '@anthropic-ai/claude-agent-sdk-linux-arm64': 0.3.220
+      '@anthropic-ai/claude-agent-sdk-linux-arm64-musl': 0.3.220
+      '@anthropic-ai/claude-agent-sdk-linux-x64': 0.3.220
+      '@anthropic-ai/claude-agent-sdk-linux-x64-musl': 0.3.220
+      '@anthropic-ai/claude-agent-sdk-win32-arm64': 0.3.220
+      '@anthropic-ai/claude-agent-sdk-win32-x64': 0.3.220
+
   '@anthropic-ai/sdk@0.91.1(zod@4.4.3)':
     dependencies:
       json-schema-to-ts: 3.1.1
     optionalDependencies:
       zod: 4.4.3
 
+  '@anthropic-ai/sdk@0.93.0(zod@4.4.3)':
+    dependencies:
+      json-schema-to-ts: 3.1.1
+    optionalDependencies:
+      zod: 4.4.3
+
   '@asamuzakjp/css-color@5.1.11':
     dependencies:
       '@asamuzakjp/generational-cache': 1.0.1
@@ -13305,6 +13580,33 @@ snapshots:
 
   '@nodable/entities@2.2.0': {}
 
+  '@openai/codex@0.146.0':
+    optionalDependencies:
+      '@openai/codex-darwin-arm64': '@openai/codex@0.146.0-darwin-arm64'
+      '@openai/codex-darwin-x64': '@openai/codex@0.146.0-darwin-x64'
+      '@openai/codex-linux-arm64': '@openai/codex@0.146.0-linux-arm64'
+      '@openai/codex-linux-x64': '@openai/codex@0.146.0-linux-x64'
+      '@openai/codex-win32-arm64': '@openai/codex@0.146.0-win32-arm64'
+      '@openai/codex-win32-x64': '@openai/codex@0.146.0-win32-x64'
+
+  '@openai/codex@0.146.0-darwin-arm64':
+    optional: true
+
+  '@openai/codex@0.146.0-darwin-x64':
+    optional: true
+
+  '@openai/codex@0.146.0-linux-arm64':
+    optional: true
+
+  '@openai/codex@0.146.0-linux-x64':
+    optional: true
+
+  '@openai/codex@0.146.0-win32-arm64':
+    optional: true
+
+  '@openai/codex@0.146.0-win32-x64':
+    optional: true
+
   '@opentelemetry/api-logs@0.220.0':
     dependencies:
       '@opentelemetry/api': 1.9.0
diff --git a/python/sdk/tests/test_bundled_runtime.py b/python/sdk/tests/test_bundled_runtime.py
index 1ac4487582..90b885957e 100644
--- a/python/sdk/tests/test_bundled_runtime.py
+++ b/python/sdk/tests/test_bundled_runtime.py
@@ -38,6 +38,8 @@ _CORDIS_YML = """\
     cwd: '.'
 - id: todo
   name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
 """
 
 
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index dd00068fe4..1c7e2c3a0c 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -320,8 +320,8 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Subprocess seam',
     mode: 'seam',
     implementations: ['subprocess-local'],
-    consumers: ['bash-local', 'bash-sandbox', 'lsp-local', 'subagent-acp'],
-    note: 'The bash executors, the LSP host, and the ACP subagent backend spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation.',
+    consumers: ['bash-local', 'bash-sandbox', 'lsp-local', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
+    note: 'The bash executors, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation.',
   },
   {
     key: 'bash',
@@ -417,7 +417,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'subagent',
     title: 'Subagent provider and continuation service',
     mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-codex', 'subagent-claude-code', 'subagent-dsh-sdk'],
     consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
     note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
   },
diff --git a/scripts/gen-third-party-notices.spec.ts b/scripts/gen-third-party-notices.spec.ts
index f31cca6879..d0c427c8f6 100644
--- a/scripts/gen-third-party-notices.spec.ts
+++ b/scripts/gen-third-party-notices.spec.ts
@@ -2,7 +2,20 @@ import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSyn
 import { join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { describe, expect, it } from 'vitest'
-import { collectPythonDependencies, isPermissive, type Manifest, manifestPatterns, parsePyprojectRequirements, parseVendoredRows, render, tierExternalDeps, virtualManifest } from './gen-third-party-notices.ts'
+import {
+  CLAUDE_AGENT_SDK_PACKAGE,
+  claudeDistributionFromManifest,
+  collectPythonDependencies,
+  isOwnerAuthorizedRuntime,
+  isPermissive,
+  type Manifest,
+  manifestPatterns,
+  parsePyprojectRequirements,
+  parseVendoredRows,
+  render,
+  tierExternalDeps,
+  virtualManifest,
+} from './gen-third-party-notices.ts'
 
 const root = resolve(import.meta.dirname, '..')
 
@@ -12,7 +25,9 @@ describe('THIRD_PARTY_NOTICES.md', () => {
   // Pre-commit regenerates the file whenever a manifest is staged, so reaching
   // this assertion means the notices were committed without that hook.
   it('matches what the generator produces from the current manifests', () => {
-    expect(readFileSync(resolve(root, 'THIRD_PARTY_NOTICES.md'), 'utf8'), 'stale notices — run `pnpm run gen-third-party-notices`').toBe(render())
+    const generated = render()
+    expect(generated).toContain('It depends on the third-party software listed below.')
+    expect(readFileSync(resolve(root, 'THIRD_PARTY_NOTICES.md'), 'utf8'), 'stale notices — run `pnpm run gen-third-party-notices`').toBe(generated)
   })
 })
 
@@ -223,7 +238,14 @@ describe('collectPythonDependencies', () => {
 describe('isPermissive', () => {
   it('accepts the licenses this project ships and rejects copyleft or unknown ones', () => {
     expect(['MIT', 'ISC', 'BSD-3-Clause', 'Apache-2.0', 'MIT / Apache-2.0', '(MIT OR CC0-1.0)'].every(isPermissive)).toBe(true)
-    expect(['LGPL-3.0-only', 'MPL-2.0', 'GPL-3.0-or-later', 'SEE LICENSE IN LICENSE'].some(isPermissive)).toBe(false)
+    expect([
+      'LGPL-3.0-only',
+      'MPL-2.0',
+      'GPL-3.0-or-later',
+      'SEE LICENSE IN LICENSE',
+      'SEE LICENSE IN README.md',
+      'SEE LICENSE IN LICENSE.md',
+    ].some(isPermissive)).toBe(false)
   })
 
   it('requires every operand of an AND, so a copyleft conjunct cannot ride along', () => {
@@ -245,6 +267,66 @@ describe('isPermissive', () => {
   })
 })
 
+describe('official Claude distribution authorization', () => {
+  it('authorizes only the direct SDK identity without relabeling its license', () => {
+    expect(isOwnerAuthorizedRuntime(CLAUDE_AGENT_SDK_PACKAGE)).toBe(true)
+    expect(isOwnerAuthorizedRuntime(`${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`))
+      .toBe(false)
+    expect(isOwnerAuthorizedRuntime('@anthropic-ai/unrelated')).toBe(false)
+    expect(isPermissive('SEE LICENSE IN README.md')).toBe(false)
+  })
+
+  it('derives version-independent platform payloads from the official SDK manifest', () => {
+    expect(claudeDistributionFromManifest({
+      name: CLAUDE_AGENT_SDK_PACKAGE,
+      version: '9.8.7',
+      license: 'future declared terms',
+      claudeCodeVersion: '6.5.4',
+      optionalDependencies: {
+        [`${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`]: '9.8.7',
+        [`${CLAUDE_AGENT_SDK_PACKAGE}-darwin-arm64`]: '9.8.7',
+      },
+    })).toEqual({
+      sdkVersion: '9.8.7',
+      claudeCodeVersion: '6.5.4',
+      payloads: [
+        {
+          name: `${CLAUDE_AGENT_SDK_PACKAGE}-darwin-arm64`,
+          version: '9.8.7',
+        },
+        {
+          name: `${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`,
+          version: '9.8.7',
+        },
+      ],
+    })
+  })
+
+  it('rejects a wrong SDK identity, missing payloads, and unrelated optionals', () => {
+    expect(() => claudeDistributionFromManifest({
+      name: '@anthropic-ai/unrelated',
+      version: '1.0.0',
+      claudeCodeVersion: '1.0.0',
+      optionalDependencies: {
+        [`${CLAUDE_AGENT_SDK_PACKAGE}-linux-x64`]: '1.0.0',
+      },
+    })).toThrow(`expected ${CLAUDE_AGENT_SDK_PACKAGE} manifest`)
+    expect(() => claudeDistributionFromManifest({
+      name: CLAUDE_AGENT_SDK_PACKAGE,
+      version: '1.0.0',
+      claudeCodeVersion: '1.0.0',
+    })).toThrow('declares no optional platform payloads')
+    expect(() => claudeDistributionFromManifest({
+      name: CLAUDE_AGENT_SDK_PACKAGE,
+      version: '1.0.0',
+      claudeCodeVersion: '1.0.0',
+      optionalDependencies: {
+        '@anthropic-ai/unrelated': '1.0.0',
+      },
+    })).toThrow('outside its authorized platform-payload identity')
+  })
+})
+
 describe('manifestPatterns', () => {
   it('derives globs from the declared members, so a new member area is read', () => {
     expect(manifestPatterns(['packages/*/*', 'tools/*'], ['packages/*'])).toEqual([
diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts
index 0d41953e4b..ec88d32a61 100644
--- a/scripts/gen-third-party-notices.ts
+++ b/scripts/gen-third-party-notices.ts
@@ -49,6 +49,21 @@ const FIRST_PARTY = new Set([
   'node-addon-landlock-run-linux-x64',
 ])
 
+/** Official SDK identity covered by the project's narrow owner authorization. */
+export const CLAUDE_AGENT_SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk'
+const CLAUDE_PLATFORM_PACKAGE_PREFIX = `${CLAUDE_AGENT_SDK_PACKAGE}-`
+const CLAUDE_PLATFORM_DECLARED_LICENSE = 'SEE LICENSE IN LICENSE.md'
+
+/**
+ * Whether a non-permissive runtime declaration has an identity-scoped owner
+ * authorization. This does not reclassify its terms as permissive.
+ * @param name - exact npm package identity.
+ * @returns true only for the official Claude Agent SDK package.
+ */
+export function isOwnerAuthorizedRuntime(name: string): boolean {
+  return name === CLAUDE_AGENT_SDK_PACKAGE
+}
+
 /**
  * Metadata overrides where the installed manifest is wrong or unreachable.
  * Each entry documents why the store cannot answer.
@@ -92,6 +107,7 @@ const BUILD_TIME_TOOLS = [
 /** The `package.json` fields this generator reads. */
 export interface Manifest {
   name?: string
+  version?: string
   private?: boolean
   license?: string
   dependencies?: Record<string, string>
@@ -164,7 +180,74 @@ function loadWorkspaceManifests(): { manifests: Map<string, Manifest>; names: Se
   return { manifests, names }
 }
 
-type VirtualManifest = Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }
+type VirtualManifest = Manifest & {
+  claudeCodeVersion?: string
+  license?: string
+  repository?: string | { url?: string }
+  homepage?: string
+}
+
+/** One platform payload declared by the official Claude Agent SDK. */
+export interface ClaudePlatformPayload {
+  readonly name: string
+  readonly version: string
+}
+
+/** Current SDK and CLI distribution facts derived from the installed SDK manifest. */
+export interface ClaudeDistribution {
+  readonly sdkVersion: string
+  readonly claudeCodeVersion: string
+  readonly payloads: ClaudePlatformPayload[]
+}
+
+function requiredManifestString(
+  value: string | undefined,
+  field: string,
+): string {
+  if (value === undefined || value.length === 0) {
+    throw new Error(`gen-third-party-notices: ${CLAUDE_AGENT_SDK_PACKAGE} has no ${field}.`)
+  }
+  return value
+}
+
+/**
+ * Derive the official platform payload set without a version or platform
+ * allowlist. Only identities in the SDK's own package namespace are covered.
+ * @param manifest - installed official SDK manifest.
+ * @returns current SDK, CLI, and optional platform payload facts.
+ */
+export function claudeDistributionFromManifest(
+  manifest: VirtualManifest,
+): ClaudeDistribution {
+  if (manifest.name !== CLAUDE_AGENT_SDK_PACKAGE) {
+    throw new Error(
+      `gen-third-party-notices: expected ${CLAUDE_AGENT_SDK_PACKAGE} manifest, got ${JSON.stringify(manifest.name)}.`,
+    )
+  }
+  const sdkVersion = requiredManifestString(manifest.version, 'version')
+  const claudeCodeVersion = requiredManifestString(
+    manifest.claudeCodeVersion,
+    'claudeCodeVersion',
+  )
+  const entries = Object.entries(manifest.optionalDependencies ?? {})
+  if (entries.length === 0) {
+    throw new Error(
+      `gen-third-party-notices: ${CLAUDE_AGENT_SDK_PACKAGE} declares no optional platform payloads.`,
+    )
+  }
+  const payloads = entries.map(([name, version]) => {
+    if (!name.startsWith(CLAUDE_PLATFORM_PACKAGE_PREFIX)) {
+      throw new Error(
+        `gen-third-party-notices: ${CLAUDE_AGENT_SDK_PACKAGE} optional dependency ${name} is outside its authorized platform-payload identity.`,
+      )
+    }
+    return {
+      name,
+      version: requiredManifestString(version, `${name} optional dependency version`),
+    }
+  }).sort((left, right) => left.name.localeCompare(right.name))
+  return { sdkVersion, claudeCodeVersion, payloads }
+}
 
 /**
  * Resolve one package's manifest inside a pnpm virtual store. The prefix scan
@@ -193,9 +276,8 @@ export function virtualManifest(virtual: string, name: string): VirtualManifest
   return undefined
 }
 
-/** License and repository URL for an installed external package, from the pnpm store. */
-function installedMetadata(name: string): { license: string; repo: string } {
-  const override = OVERRIDES[name]
+/** Resolve one installed external package manifest from either pnpm store. */
+function installedManifest(name: string): VirtualManifest | undefined {
   let manifest: (Manifest & { license?: string; repository?: string | { url?: string }; homepage?: string }) | undefined
   // The nested Landlock workspace installs into its own store, so a package
   // only that workspace depends on is unreachable from the root one.
@@ -210,6 +292,13 @@ function installedMetadata(name: string): { license: string; repo: string } {
     manifest = virtualManifest(virtual, name)
     if (manifest !== undefined) break
   }
+  return manifest
+}
+
+/** License and repository URL for an installed external package, from the pnpm store. */
+function installedMetadata(name: string): { license: string; repo: string } {
+  const override = OVERRIDES[name]
+  const manifest = installedManifest(name)
   const license = override?.license ?? manifest?.license
   const rawRepo = typeof manifest?.repository === 'string' ? manifest.repository : manifest?.repository?.url ?? manifest?.homepage
   const repo = override?.repo ?? normalizeRepo(rawRepo)
@@ -219,6 +308,37 @@ function installedMetadata(name: string): { license: string; repo: string } {
   return { license, repo }
 }
 
+function collectClaudeDistribution(): ClaudeDistribution {
+  const manifest = installedManifest(CLAUDE_AGENT_SDK_PACKAGE)
+  if (manifest === undefined) {
+    throw new Error(
+      `gen-third-party-notices: cannot resolve ${CLAUDE_AGENT_SDK_PACKAGE}; run \`pnpm install\`.`,
+    )
+  }
+  const distribution = claudeDistributionFromManifest(manifest)
+  let installedPayloads = 0
+  for (const payload of distribution.payloads) {
+    const installed = installedManifest(payload.name)
+    if (installed === undefined) continue
+    installedPayloads += 1
+    if (
+      installed.name !== payload.name
+      || installed.version !== payload.version
+      || installed.license !== CLAUDE_PLATFORM_DECLARED_LICENSE
+    ) {
+      throw new Error(
+        `gen-third-party-notices: installed ${payload.name} does not match its SDK-declared version and ${CLAUDE_PLATFORM_DECLARED_LICENSE} license field.`,
+      )
+    }
+  }
+  if (installedPayloads === 0) {
+    throw new Error(
+      'gen-third-party-notices: no SDK-declared Claude platform payload is installed; install optional dependencies before regenerating.',
+    )
+  }
+  return distribution
+}
+
 /** Normalize a manifest repository/homepage value to a browsable https URL. */
 function normalizeRepo(raw: string | undefined): string | undefined {
   if (raw === undefined || raw === '') return undefined
@@ -519,6 +639,26 @@ function renderNpmTable(deps: ExternalDep[]): string {
   return lines.join('\n')
 }
 
+function renderClaudeDistribution(
+  distribution: ClaudeDistribution | undefined,
+): string {
+  if (distribution === undefined) return ''
+  const rows = distribution.payloads.map(payload =>
+    `| [\`${payload.name}\`](https://www.npmjs.com/package/${payload.name}) | ${payload.version} | ${CLAUDE_PLATFORM_DECLARED_LICENSE} |`,
+  )
+  return `
+## Official Claude Code platform payloads
+
+The project owner authorizes distribution of every version of the official \`${CLAUDE_AGENT_SDK_PACKAGE}\` package and the official Claude Code CLI/platform payloads that each version declares through \`optionalDependencies\`. This identity-scoped authorization does not classify their declared terms as permissive and does not cover any unrelated runtime package; version, declared-license, and payload-set changes still require the ordinary dependency, lockfile, compatibility, terms, and notices review.
+
+The installed SDK ${distribution.sdkVersion} declares the following optional platform packages. Each carries the official Claude Code ${distribution.claudeCodeVersion} executable; the package identities and versions come from the SDK manifest, while the declared license field is verified against the platform payload installed for the current host.
+
+| Optional platform package | Version | Declared license |
+| --- | --- | --- |
+${rows.join('\n')}
+`
+}
+
 /**
  * Render the complete notices document.
  * @returns the exact bytes `THIRD_PARTY_NOTICES.md` must hold.
@@ -531,11 +671,19 @@ export function render(): string {
   const vendored = collectVendored()
   const python = collectPython()
   const patched = collectPatched()
+  const claudeDistribution = runtimeDeps.some(
+    dep => dep.name === CLAUDE_AGENT_SDK_PACKAGE,
+  )
+    ? collectClaudeDistribution()
+    : undefined
 
   const nonPermissiveDev = devDeps.filter(dep => !isPermissive(dep.license))
   // A copyleft license reaching a shipped surface is a distribution decision,
   // not a rendering detail; the notices cannot quietly absorb it.
-  const nonPermissiveRuntime = runtimeDeps.filter(dep => !isPermissive(dep.license))
+  const nonPermissiveRuntime = runtimeDeps.filter(dep =>
+    !isPermissive(dep.license)
+    && !isOwnerAuthorizedRuntime(dep.name),
+  )
   if (nonPermissiveRuntime.length > 0) {
     throw new Error(`gen-third-party-notices: runtime ${nonPermissiveRuntime.map(dep => `${dep.name} (${dep.license})`).join(', ')} is not a permissive license; review the distribution terms and record the decision before regenerating.`)
   }
@@ -546,9 +694,9 @@ export function render(): string {
 
 # Third-Party Notices
 
-DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party open-source software listed below. Each project remains under its own license; nothing in this file changes those terms.
+DeepSeek Harness is licensed under [BSD 3-Clause](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
 
-This file lists **direct** dependencies declared by the workspace. It is generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
+This file lists **direct** dependencies declared by the workspace and the explicitly disclosed official Claude platform payload closure. It is generated from the workspace manifests by \`scripts/gen-third-party-notices.ts\`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and \`scripts/gen-third-party-notices.spec.ts\` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run \`pnpm run verify-third-party-notices\` for the standalone check.
 
 The complete npm transitive closure, with exact pinned versions, is recorded in [\`pnpm-lock.yaml\`](pnpm-lock.yaml) — inspect it with \`pnpm licenses list\`. The Python closure is recorded in [\`python/sdk/uv.lock\`](python/sdk/uv.lock), and the Landlock launcher workspace keeps its own in [\`native/landlock-run/pnpm-lock.yaml\`](native/landlock-run/pnpm-lock.yaml).
 
@@ -569,6 +717,7 @@ ${renderNpmTable(runtimeDeps)}
 pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification:
 
 ${patchedLines.join('\n')}
+${renderClaudeDistribution(claudeDistribution)}
 
 ## Development-only npm dependencies
 
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index f0eb64548e..38d2f406ff 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -14,6 +14,7 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createScope } from '@deepseek-ai/dsh-scope'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import GoalService from '@deepseek-ai/dsh-goal'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -401,19 +402,19 @@ const TOOL_PACKAGES: ToolPackage[] = [
       list_agents: 'packages/subagent/tool-subagent-control/src/list-agents.ts',
       send_message: 'packages/subagent/tool-subagent-control/src/index.ts',
     },
-    requires: ['ctx.tools', 'ctx.subagents', 'ctx.sessionQuery (list_agents only)'],
+    requires: ['ctx.tools', 'ctx.subagents', 'ctx.sessionProjections (list_agents catalog rows)'],
     writes: ['tool/call', 'tool/result', 'child session events through ctx.subagents'],
     async mount(ctx) {
       await ctx.plugin(SubagentService)
       await ctx.plugin(LocalTaskService)
       await ctx.plugin(AgentRegistry)
       await ctx.plugin(SessionStore)
-      await ctx.plugin(SessionQuerySqlite, { path: ':memory:' })
+      await ctx.plugin(SessionProjectionRegistry)
       await ctx.plugin(ToolSubagentControl)
       await ctx.plugin(ToolSubagentListAgents)
     },
     note:
-      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (which additionally requires session query).',
+      'The globally named control tools over continuable background subagents: provider-bound `tool-subagent` instances register distinct delegation tools, while this package registers `send_message` once, plus `list_agents` from its separately loaded `/list-agents` plugin (whose catalog rows are served through the sessionProjections registry).',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-subagent-report',
@@ -454,10 +455,10 @@ const TOOL_PACKAGES: ToolPackage[] = [
     requires: ['ctx.tools', 'owning Agent session'],
     writes: ['tool/call', 'todo/write', 'tool/result'],
     async mount(ctx) {
-      await ctx.plugin(ToolTodo)
+      await ctx.plugin(ToolTodo, { allowParallelInProgress: true })
     },
     note:
-      'todo_write is session-owned state; UIs render the latest todo/write event as a checklist.',
+      'todo_write is session-owned state; UIs render the latest todo/write event as a checklist. `allowParallelInProgress` is required with no default, so the catalog states its choice: `true`, whose description invites several `in_progress` items. A deployment choosing `false` receives the same tool with a description asking for exactly one active task.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-workflow',
@@ -610,7 +611,7 @@ export function render(catalog: ToolCatalog): string {
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
-    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
+    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
     '',
     '## Tool Package Map',
     '',
diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts
index d7fb7e1b13..84eeeb10bb 100644
--- a/scripts/run-gates.spec.ts
+++ b/scripts/run-gates.spec.ts
@@ -189,6 +189,12 @@ describe('Node 24 lane ownership', () => {
     expect(subject.find(item => item.id === 'doc-typecheck')?.env).toEqual({
       DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1',
     })
+    expect(subject.find(item => item.id === 'built-bin-smoke')?.args).toEqual(
+      expect.arrayContaining([
+        'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
+        'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
+      ]),
+    )
     expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({
       displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built',
       env: { DSH_SNAPSHOT: 'replay' },
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 238c513433..f7669eac7e 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -599,6 +599,8 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
     'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
     'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
+    'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
+    'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     // The worker-entry packages' built bundles: the only automated proof
     // that lib/index.js resolves its sibling lib/worker.cjs under plain node
     // (the e2e lane runs unbuilt, so these files self-skip there).
diff --git a/tsconfig.host.json b/tsconfig.host.json
index 38e909fe63..4eed9078af 100644
--- a/tsconfig.host.json
+++ b/tsconfig.host.json
@@ -31,6 +31,7 @@
     "apps/web/tests/hmr-live.e2e.ts",
     "apps/web/tests/seeded-history.e2e.ts",
     "apps/web/tests/sidebar-scrollbar.e2e.ts",
+    "apps/web/tests/conversation-column-overflow.e2e.ts",
     "apps/web/tests/code-mode-round.e2e.ts",
     "apps/web/tests/composer-draft-scroll.e2e.ts",
     "apps/web/tests/cordis-tool-round.e2e.ts",
@@ -207,6 +208,8 @@
     { "path": "./packages/subagent/subagent-spawn" },
     { "path": "./packages/subagent/subagent-fork" },
     { "path": "./packages/subagent/subagent-acp" },
+    { "path": "./packages/subagent/subagent-claude-code" },
+    { "path": "./packages/subagent/subagent-codex" },
     { "path": "./packages/subagent/subagent-dsh-sdk" },
     { "path": "./packages/tasks/tasks" },
     { "path": "./packages/tasks/tasks-local" },