fix: address codex review round 2

- listChildren() checks its cancellation signal before starting the corpus
  trace and immediately after it resolves, so a pre-aborted or trace-time
  abort fails CANCELLED instead of returning a successful empty result.
- Corrected the persistence-repair claims: session query resolves persisted
  candidates through the non-mutating inspect() read, so listing is
  storage-read-only and a torn child tail is surfaced (shorter valid prefix)
  rather than repaired; the Agent Note, README, and JSDoc now state that,
  and the zh pair is re-recorded.

.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: 634cb8708f951dfd62e1345f96420cba0d7baed9
-2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: a3d282d3de63ca3bc081c071e66c2713422ebcc2
+2026-07-22-durable-subagent-catalog-and-list-agents.md: 8d228c1b9af57c0d0054c216dc6ca63cdd4718f2
+2026-07-22-durable-subagent-catalog-and-list-agents.zh.md: b508d9cde3ba4e0f8451477f1a4e5bbff2df6205

.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.md

@@ -35,7 +35,7 @@ The published logical record is also the status source: `SessionRecord.live` mea
 
 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 when called and throws `SubagentError` with stable code `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE` before doing any work when it 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 loading session query; the list tool catches misconfiguration at plugin load, while another direct service consumer receives the same explicit call-time contract.
 
-This descriptor-read path is the correctness baseline, not a claim that work is linear only in the number of direct children. Let D be the number of direct-child candidates, C be the number of persisted sessions scanned by each persistence listing, and L_i be the size of candidate i's full log. One corpus trace is followed by `sessionQuery.listEvents(childId)` for every candidate. A candidate with no descriptor is omitted, and one with multiple descriptors is diagnosed without another read; only a candidate with exactly one descriptor is loaded again through `sessionQuery.readEvent({ sessionId: childId, seq })`. The read must return the same immutable session header observed by the trace, including the direct-parent relationship, and its target must still be the located descriptor event; a mismatch is per-child corruption. In the persisted-only worst case, each exact read repeats `persistence.list()`, loads the full child log, and clones its events, for O(D × C + Σ L_i) work up to constant factors; a candidate with exactly one descriptor pays those costs twice, while other candidates pay them once. A live candidate similarly takes one detached in-memory snapshot of its full log, or two when its descriptor is read. The persisted path may durably repair an interrupted child log by appending synthetic closing events. The first version accepts these repeated reads as the no-index correctness baseline, but deployments must treat total corpus and child-log size—not only direct-child count—as the capacity constraint. Listing creates no Agent and appends no catalog or descriptor event itself, but it is not a storage-read-only operation. The model-hidden descriptor remains outside the conversation surface and survives compaction, so compacted and uncompacted children must enumerate identically.
+This descriptor-read path is the correctness baseline, not a claim that work is linear only in the number of direct children. Let D be the number of direct-child candidates, C be the number of persisted sessions scanned by each persistence listing, and L_i be the size of candidate i's full log. One corpus trace is followed by `sessionQuery.listEvents(childId)` for every candidate. A candidate with no descriptor is omitted, and one with multiple descriptors is diagnosed without another read; only a candidate with exactly one descriptor is loaded again through `sessionQuery.readEvent({ sessionId: childId, seq })`. The read must return the same immutable session header observed by the trace, including the direct-parent relationship, and its target must still be the located descriptor event; a mismatch is per-child corruption. In the persisted-only worst case, each exact read repeats `persistence.list()`, loads the full child log, and clones its events, for O(D × C + Σ L_i) work up to constant factors; a candidate with exactly one descriptor pays those costs twice, while other candidates pay them once. A live candidate similarly takes one detached in-memory snapshot of its full log, or two when its descriptor is read. Session query resolves persisted candidates through the persistence seam's non-mutating `inspect()` read, which returns the valid stored prefix without repairing a torn tail or closing an interrupted turn, so listing is storage-read-only; repair remains the resume path's concern. The first version accepts these repeated reads as the no-index correctness baseline, but deployments must treat total corpus and child-log size—not only direct-child count—as the capacity constraint. Listing creates no Agent and appends no catalog, descriptor, or repair event. The model-hidden descriptor remains outside the conversation surface and survives compaction, so compacted and uncompacted children must enumerate identically.
 
 If measured scale later requires an index, that index is derived state: session headers and child descriptors remain authoritative, and rebuilding or corruption fallback must reproduce the same results. An index cannot become a second authorization source or make an unpublished child visible.
 
@@ -78,7 +78,7 @@ The first version has no child deletion operation. If later product behavior del
 
 **Return separate child and diagnostic arrays.** Separate arrays introduce two ordering domains or require exposing another sort key to reconstruct candidate order. One discriminated entry array preserves the trace order while keeping child and diagnostic fields type-safe.
 
-**Add a repair-free descriptor inspection API.** This would make discovery strictly storage-read-only, but expands the persistence seam solely to avoid the interrupted-tail repair that normal session load and eventual resume already require. The first version accepts `load()` semantics and documents the side effect.
+**Read candidates through the repairing `load()` path.** Reusing resume's `load()` semantics would let discovery durably close an interrupted tail early, but turns a listing query into a mutating operation and couples its failure modes to write coordination. Session query's corpus reads already use the non-mutating `inspect()` contract, so listing stays storage-read-only and leaves tail repair to the resume path that needs it.
 
 **Paginate or cap the query now (deferred).** This bounds one result, but makes model discovery stateful and can hide older children unless the model follows a cursor. The first version has no cursor, page arguments, or candidate-limit configuration and returns the complete stably ordered set; a service-level bound remains a later decision if measured scale requires it.
 
@@ -92,7 +92,7 @@ The first version has no child deletion operation. If later product behavior del
 
 - Session tracing observes the complete logical corpus, then descriptor validation reads every direct-child log once and candidates with exactly one descriptor twice. In the persisted-only worst case, work is O(D × C + Σ L_i), not merely O(D), because each exact read rescans persistence and loads and clones the full candidate log. A later derived index must preserve the same authorization, per-child diagnostic, and fallback behavior.
 - Corpus construction is an all-or-nothing trust boundary: one live/persisted header conflict fails the initial trace and hides otherwise healthy siblings. Per-child isolation begins only after that trace succeeds.
-- Session-query reads may repair interrupted child logs and persist synthetic closing events even though listing creates no Agent. This is the existing persistence-load contract, not a hidden catalog write.
+- A torn child tail is surfaced, not repaired: the non-mutating `inspect()` read returns the valid stored prefix, so a child interrupted mid-write may list from a shorter log until the resume path's repairing load closes it.
 - The first version has no deletion operation, so persisted children remain listed for as long as their sessions remain in persistence even though live Agent resources remain bounded by resident Activations.
 - The query returns every direct continuable child and diagnostic without a service cursor or candidate cap. Stable ordering makes the result deterministic but does not bound model-context growth; service pagination or deletion remains a later product decision.
 - `running` and `complete` are process-local corpus snapshots, not delivery promises. Another process may activate a persisted child while this process reports it as `complete`; cross-process accuracy requires a shared lease.

.agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md

@@ -35,7 +35,7 @@ parent 到 child 的枚举及 `list_agents` 是一个基于持久化 child Sessi
 
 subagent 服务将 `sessionQuery` 保持为可选依赖，因此没有该服务时仍可执行 start 和 follow-up。其公开的 `listChildren(parentSessionId: SessionId)` 方法在调用时解析这个可选服务；如果服务缺失，该方法会在执行任何工作前抛出 `SubagentError`，并携带稳定错误码 `SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE`。`@deepseek-ai/dsh-tool-subagent-control` 导出可分别加载的工具插件：`send_message` 适配器只要求 `subagents`，而 `list_agents` 适配器在加载时同时要求 `subagents` 和 `sessionQuery`。因此，部署可以在不加载会话查询的情况下使用 `send_message`；列表工具会在插件加载时捕获配置错误，而其他直接服务消费方会收到同一项明确的调用时契约。
 
-这条描述符读取路径是正确性基线，并不声称工作量只与直接 child 数量呈线性关系。令 D 为直接 child 候选数量，C 为每次持久化列表查询所扫描的持久化会话数量，L_i 为候选 i 的完整日志大小。一次语料追踪后，每个候选都会执行 `sessionQuery.listEvents(childId)`。没有描述符的候选会被排除；含有多个描述符的候选会直接产生 diagnostic，无需再次读取；只有恰好含有一个描述符的候选才会通过 `sessionQuery.readEvent({ sessionId: childId, seq })` 再次加载。此次读取返回的不可变会话 header 必须与追踪时观测到的相同，包括直接 parent 关系，并且读取目标仍必须是先前定位的描述符事件；任何不一致均视为该 child 损坏。对于只存在于持久化存储中的最坏情况，每次精确读取都会重复执行 `persistence.list()`、加载完整 child 日志并克隆其中的事件，因此忽略常数因子后的工作量为 O(D × C + Σ L_i)；恰好含有一个描述符的候选承担两次这类成本，其他候选只承担一次。存活候选同样会对其完整日志取得一份分离的内存快照；读取其描述符时则会取得两份。持久化路径可能通过追加合成的结束事件，持久修复中断的 child 日志。第一版接受这些重复读取，将其作为无索引的正确性基线，但部署必须将语料总量和 child 日志大小，而不仅是直接 child 数量，视为容量约束。列表查询不会创建 Agent，也不会自行追加目录或描述符事件，但它并非严格的存储只读操作。对模型隐藏的描述符始终位于对话 surface 之外，并且会在压缩后保留，因此经过压缩和未经压缩的 child 必须枚举出相同结果。
+这条描述符读取路径是正确性基线，并不声称工作量只与直接 child 数量呈线性关系。令 D 为直接 child 候选数量，C 为每次持久化列表查询所扫描的持久化会话数量，L_i 为候选 i 的完整日志大小。一次语料追踪后，每个候选都会执行 `sessionQuery.listEvents(childId)`。没有描述符的候选会被排除；含有多个描述符的候选会直接产生 diagnostic，无需再次读取；只有恰好含有一个描述符的候选才会通过 `sessionQuery.readEvent({ sessionId: childId, seq })` 再次加载。此次读取返回的不可变会话 header 必须与追踪时观测到的相同，包括直接 parent 关系，并且读取目标仍必须是先前定位的描述符事件；任何不一致均视为该 child 损坏。对于只存在于持久化存储中的最坏情况，每次精确读取都会重复执行 `persistence.list()`、加载完整 child 日志并克隆其中的事件，因此忽略常数因子后的工作量为 O(D × C + Σ L_i)；恰好含有一个描述符的候选承担两次这类成本，其他候选只承担一次。存活候选同样会对其完整日志取得一份分离的内存快照；读取其描述符时则会取得两份。会话查询通过持久化 seam 的非变更 `inspect()` 读取解析持久化候选：它返回有效的已存储前缀，既不修复撕裂的尾部，也不关闭中断的 turn，因此列表查询是存储只读操作；修复仍是恢复路径的职责。第一版接受这些重复读取，将其作为无索引的正确性基线，但部署必须将语料总量和 child 日志大小，而不仅是直接 child 数量，视为容量约束。列表查询不会创建 Agent，也不会追加任何目录、描述符或修复事件。对模型隐藏的描述符始终位于对话 surface 之外，并且会在压缩后保留，因此经过压缩和未经压缩的 child 必须枚举出相同结果。
 
 如果实测规模日后需要索引，该索引属于派生状态：会话 header 和 child 描述符仍是权威信息，重建或损坏回退必须复现相同结果。索引不能成为第二个鉴权来源，也不能让尚未发布的 child 变得可见。
 
@@ -78,7 +78,7 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 **分别返回 child 和 diagnostic 数组。** 分离的数组会引入两个排序域，或者要求公开另一个排序键才能重建候选顺序。一个带判别字段的条目数组既能保留追踪顺序，也能保证 child 与 diagnostic 字段的类型安全。
 
-**添加不会触发修复的描述符检查 API。** 这能使发现严格保持存储只读，但仅为避免中断尾部修复就扩展持久化 seam，而普通会话加载和最终恢复原本就需要执行该修复。第一版接受 `load()` 的语义，并记录这项副作用。
+**通过会触发修复的 `load()` 路径读取候选。** 复用恢复路径的 `load()` 语义可以让发现提前持久化地关闭中断尾部，但会把列表查询变成变更操作，并使其失败模式与写协调耦合。会话查询的语料读取本就使用非变更的 `inspect()` 契约，因此列表查询保持存储只读，尾部修复留给真正需要它的恢复路径。
 
 **立即为查询分页或设置上限（暂缓）。** 这可以限制一次结果的大小，但会使模型发现成为有状态操作，而且除非模型继续跟随 cursor，否则可能隐藏更早的 child。第一版没有 cursor、分页参数或候选数量上限配置，而是返回经稳定排序的完整集合；如果实测规模需要限制，服务级限制仍留待后续决策。
 
@@ -92,7 +92,7 @@ diagnostic 是瞬时查询结果，不属于会话事件或目录状态。推导
 
 - 会话追踪会观察完整的逻辑语料，随后描述符校验会读取每个直接 child 的日志一次，并对恰好含有一个描述符的候选读取两次。对于只存在于持久化存储中的最坏情况，工作量为 O(D × C + Σ L_i)，而不只是 O(D)，因为每次精确读取都会重新扫描持久化存储，并加载和克隆候选的完整日志。后续的派生索引必须保持相同的鉴权、逐 child diagnostic 和回退行为。
 - 语料构建是一个全有或全无的信任边界：一处存活／持久化 header 冲突就会导致初始追踪失败，并隐藏原本健康的 sibling。只有初始追踪成功后，逐 child 隔离才会生效。
-- 会话查询读取可能修复中断的 child 日志并持久化合成的结束事件，即使列表查询不创建 Agent。这是现有的持久化加载契约，而非隐藏的目录写入。
+- 撕裂的 child 尾部会被呈现而非修复：非变更的 `inspect()` 读取返回有效的已存储前缀，因此写入中途被打断的 child 在恢复路径的修复加载将其关闭之前，可能以较短的日志形式出现在列表中。
 - 第一版没有删除操作，因此只要 child 会话仍保留在持久化存储中，它们就会继续出现在列表里，但存活 Agent 资源仍由驻留 Activation 数量限制。
 - 查询会返回每个直接可继续 child 和 diagnostic，不设服务 cursor 或候选数量上限。稳定排序可使结果确定，但不会限制模型上下文的增长；服务分页或删除仍是后续的产品决策。
 - `running` 和 `complete` 是进程内语料快照，而非消息送达承诺。另一个进程可能在当前进程将某个持久化 child 报告为 `complete` 时激活它；跨进程准确性需要共享租约。

docs/cordis-catalog/services.md

@@ -1997,10 +1997,12 @@ async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
  * live-preferred corpus without loading or resuming an Agent. The lineage
  * trace supplies stable candidate order and live status; each candidate is
  * then inspected independently for exactly one supported descriptor in its
- * own suffix. Session-query reads take no signal, so cancellation is
- * cooperative: the scan rechecks `signal` after every un-signalled await and
- * stops between candidates instead of draining a slow or large catalog after
- * the caller has gone.
+ * own suffix. Listing is storage-read-only: session query resolves persisted
+ * candidates through the non-mutating `inspect()` read, so no catalog,
+ * descriptor, or repair event is written. Session-query reads take no signal,
+ * so cancellation is cooperative: the scan rechecks `signal` before and
+ * after the initial trace and after every other un-signalled await instead of
+ * draining a slow or large catalog after the caller has gone.
  * @param parentSessionId - parent whose direct children are listed.
  * @param signal - caller-owned cancellation observed between query awaits.
  * @returns child and diagnostic entries in lineage-trace order.

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -898,7 +898,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
       {
         signature: 'async listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>',
-        jsDoc: '/**\n * Enumerate one session\'s direct continuable children from the durable,\n * live-preferred corpus without loading or resuming an Agent. The lineage\n * trace supplies stable candidate order and live status; each candidate is\n * then inspected independently for exactly one supported descriptor in its\n * own suffix. Session-query reads take no signal, so cancellation is\n * cooperative: the scan rechecks `signal` after every un-signalled await and\n * stops between candidates instead of draining a slow or large catalog after\n * the caller has gone.\n * @param parentSessionId - parent whose direct children are listed.\n * @param signal - caller-owned cancellation observed between query awaits.\n * @returns child and diagnostic entries in lineage-trace order.\n */',
+        jsDoc: '/**\n * Enumerate one session\'s direct continuable children from the durable,\n * live-preferred corpus without loading or resuming an Agent. The lineage\n * trace supplies stable candidate order and live status; each candidate is\n * then inspected independently for exactly one supported descriptor in its\n * own suffix. Listing is storage-read-only: session query resolves persisted\n * candidates through the non-mutating `inspect()` read, so no catalog,\n * descriptor, or repair event is written. Session-query reads take no signal,\n * so cancellation is cooperative: the scan rechecks `signal` before and\n * after the initial trace and after every other un-signalled await instead of\n * draining a slow or large catalog after the caller has gone.\n * @param parentSessionId - parent whose direct children are listed.\n * @param signal - caller-owned cancellation observed between query awaits.\n * @returns child and diagnostic entries in lineage-trace order.\n */',
       },
       {
         signature: 'registerProvider(provider: SubagentProvider): () => void',

packages/subagent/subagent/src/index.ts

@@ -251,10 +251,12 @@ export class SubagentService extends Service {
    * live-preferred corpus without loading or resuming an Agent. The lineage
    * trace supplies stable candidate order and live status; each candidate is
    * then inspected independently for exactly one supported descriptor in its
-   * own suffix. Session-query reads take no signal, so cancellation is
-   * cooperative: the scan rechecks `signal` after every un-signalled await and
-   * stops between candidates instead of draining a slow or large catalog after
-   * the caller has gone.
+   * own suffix. Listing is storage-read-only: session query resolves persisted
+   * candidates through the non-mutating `inspect()` read, so no catalog,
+   * descriptor, or repair event is written. Session-query reads take no signal,
+   * so cancellation is cooperative: the scan rechecks `signal` before and
+   * after the initial trace and after every other un-signalled await instead of
+   * draining a slow or large catalog after the caller has gone.
    * @param parentSessionId - parent whose direct children are listed.
    * @param signal - caller-owned cancellation observed between query awaits.
    * @returns child and diagnostic entries in lineage-trace order.
@@ -267,10 +269,11 @@ export class SubagentService extends Service {
         'SUBAGENT_CONTROL_SESSION_QUERY_UNAVAILABLE',
       )
     }
+    assertListingNotCancelled(signal)
     const trace = await query.traceSession(parentSessionId)
+    assertListingNotCancelled(signal)
     const entries: SubagentListEntry[] = []
     for (const node of trace.descendants) {
-      assertListingNotCancelled(signal)
       const entry = await this.inspectChild(query, parentSessionId, node.session, signal)
       if (entry !== undefined) entries.push(entry)
     }