@deepseek-ai/dsh-subagent 0.1.3-alpha.2 → 0.1.5-alpha.2

package/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: 60aea7d446acf2e01f46132ab03354bf17f74213
-README.zh.md: e46ee53436256afa5f0c8dd1c635cbd0f9585927
+README.md: 5f9668fd7a14cdfca33ab72a217c07372a24502f
+README.zh.md: 563ed06237088c4bc250ca3c4f5a863b6ffe8239

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-subagent` is the service behind child-agent delegation: an agent hands a task to a named child, collects the finished result, and — for continuable children — keeps sending follow-up work across turns. Multiple providers coexist under one contract, so a single composition can offer in-process children, out-of-process ACP or SDK children, and real Codex or Claude Code children side by side. Children come in two shapes: one-shot runs that settle with a single result, and continuable children whose durable session accepts later messages and can be interrupted. The same service answers discovery questions — which children exist, their mode, activity, and lineage — without loading or resuming them. Mount it with at least one provider backend and a delegation tool; the backends and the model-facing tools live in sibling packages.
+Use `dsh-subagent` to delegate work to named child agents, collect their results, and continue supported child conversations across turns. A composition can offer in-process, ACP, SDK, Codex, or Claude Code children side by side. Choose one-shot children for a single result or continuable children for later messages and interruption. You can also inspect available children, their mode, activity, and lineage without loading or resuming them. Enable at least one supported child backend and a delegation tool.
 
 ## Table of Contents
 
@@ -96,6 +96,8 @@ A request is validated against the provider's advertised capabilities, a durable
 
 The manager reserves a child identity, resolves the durable descriptor, creates (or cold-resumes) the child Agent, installs it in an Activation, and submits the prompt. Model-authored messages cross one parent/child edge through fixed Steer scheduling; browser human prompts choose Queue or best-effort Steer through an internal adapter, while other host protocols may retain Queue for distinct turns. A Session queue command admits a live subagent-owned Agent only from its own continuable descriptor. Settlement waits for Agent activity to finish, an empty Inbox, and no owned children, then flushes final Session state with admission open. Under the child lock, the manager revalidates the wake generation, Session sequence, Inbox, and owned children; the synchronous task entry of `Agent.runMaintenance()` claims the idle phase and closes the private subagent Inbox in the same JavaScript turn before handle disposal. An absent direct-child Activation cold-resumes from the persisted session. When a resident Activation settles, the manager tells the child's direct parent in the parent's own turn stream.
 
+Successful local child creation appends a `subagent/catalog` fact to the parent Session. One-shot creation records it after the provider returns; continuable creation records it after initial inbox admission and before returning the child id. Failure releases the child without publishing a compensating catalog event. A one-shot catalog append failure handles the run’s result rejection and preserves the catalog error; disposal failures are logged separately. The `subagentCatalog` projection excludes fork-inherited facts and exposes a direct-child list through `projections.values.subagentCatalog` in Session observations and client snapshots. Invalid own catalog payloads, including unsupported versions, reject projection restoration. Its immutable storage and checkpoint validation use [`dsh-chunked-list`](../../util/chunked-list/README.md). Its view preserves parent catalog event order in O(D) time for D facts. [The parent-catalog decision](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.md) owns ordering, persistence costs, and alternatives.
+
 ### Ownership and invariants
 
 - **Publication is the boundary** — before it the provider owns the setup and must roll back on failure; after it the caller owns the run and must dispose it.

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-subagent` 是子 agent 委派背后的服务：agent（智能体）把任务交给具名子 agent，收集完成的结果，并且——对可继续子 agent 而言——跨轮次持续发送后续工作。多个提供方在同一约定下共存，因此单个组合可以并排提供进程内子 agent、进程外 ACP 或 SDK 子 agent，以及真实 Codex 或 Claude Code 子 agent。子 agent 有两种形态：一次性运行以单个结果结算，可继续子 agent 的持久会话则接受后续消息并可被中断。同一服务还回答发现类问题——存在哪些子级、它们的模式、活动状态与血缘——而不加载或恢复它们。把它与至少一个提供方后端和一个委派工具一起挂载；后端与面向模型的工具位于兄弟包中。
+使用 `dsh-subagent` 把工作委派给具名子 agent、收集结果，并跨轮次继续受支持的子级对话。一个组合可以并排提供进程内、ACP、SDK、Codex 或 Claude Code 子级。需要单个结果时选择一次性子级；需要后续消息与中断能力时选择可继续子级。你还可以检查可用子级及其模式、活动状态与血缘，而无需加载或恢复它们。启用时需要至少一个受支持的子级后端和一个委派工具。
 
 ## 目录
 
@@ -96,6 +96,8 @@ kind: "package-reference"
 
 管理器预留 child 身份、解析持久化描述符、创建（或冷恢复）child、把它安装进 Activation 并提交提示词。模型编写的消息通过固定 Steer 调度跨一条 parent/child 边；浏览器人类 prompt 通过内部适配器选择 Queue 或 best-effort Steer，其他 host 协议仍可保留 Queue 以创建独立轮次。Session queue command 仅根据 child 自身的 continuable descriptor 准入在线 subagent-owned Agent。Settlement 会等待 Agent 活动结束、Inbox 为空且没有所拥有子级，再在准入开放时 flush 最终 Session 状态。管理器随后在 child lock 内重新验证 wake generation、Session 序号、Inbox 与所拥有子级；`Agent.runMaintenance()` 的同步 task 入口会占用 idle 阶段，并在同一个 JavaScript turn 内关闭私有 subagent Inbox，然后才 dispose handle。直接 child 不存在 Activation 时会从持久化会话冷恢复。当驻留 Activation 结算时，管理器会在 parent 自身的轮次流中告知该 child 的直接 parent。
 
+本地子级创建成功时，父 Session 追加一条 `subagent/catalog` 事实。一次性创建在 provider 返回后记录；可继续创建在初始 inbox 准入后、返回子级 id 前记录。失败会释放子级，不发布补偿性目录事件。一次性目录追加失败时会处理 run 的结果拒绝，并保留目录错误；资源释放失败会单独记录。`subagentCatalog` projection 排除 fork 继承的事实，通过 Session 观察和客户端快照中的 `projections.values.subagentCatalog` 暴露直接子级列表。无效的自身 catalog payload（包括不支持的版本）会使 projection 恢复失败。其不可变存储和检查点校验使用 [`dsh-chunked-list`](../../util/chunked-list/README.zh.md)。其视图对 D 条事实以 O(D) 时间保留父目录事件顺序。[父目录决策](../../../.agents/notes/implemented/architecture/2026-09-01-parent-owned-subagent-catalog.zh.md) 说明排序、持久化成本和替代方案。
+
 ### 所有权与不变式
 
 - **发布即边界**——发布前提供方拥有设置并须在失败时回滚；发布后调用方拥有运行并须 dispose（资源释放）它。

package/lib/index.js

@@ -10,6 +10,7 @@ import { foldConsumedWork } from "@deepseek-ai/dsh-agent";
 import { SessionLogOffset, SessionSeq } from "@deepseek-ai/dsh-session";
 import { brandString } from "@deepseek-ai/dsh-brand";
 import { snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
+import { appendChunkedList, chunkedListSchema, iterateChunkedList } from "@deepseek-ai/dsh-chunked-list";
 import { accessSync, constants, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
 //#region lib/types/error.js
@@ -708,7 +709,7 @@ var SubagentInbox = class {
 	* @returns whether either Agent inbox destination is non-empty.
 	*/
 	get hasPending() {
-		return this.agent.inbox.hasPending;
+		return this.agent.inbox.nextTurn.length > 0 || this.agent.inbox.nextStep.length > 0;
 	}
 	/**
 	* Submit through the Agent only while its Activation remains resident.
@@ -1004,7 +1005,6 @@ var ContinuableActivationRegistry = class {
 		} finally {
 			this.wake(activation);
 		}
-		activation.announced = true;
 		return message.id;
 	}
 	/**
@@ -1060,8 +1060,7 @@ var ContinuableActivationRegistry = class {
 	async materializeTracked(inputs, parentLineage) {
 		const { childId, provider, parent, create } = inputs;
 		inputs.signal.throwIfAborted();
-		const setup = (childCtx) => {
-			const child = childCtx.agent;
+		const setup = (childCtx, child) => {
 			if (create !== void 0) {
 				child.session.append("subagent/descriptor", create.descriptor);
 				appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies);
@@ -1071,11 +1070,13 @@ var ContinuableActivationRegistry = class {
 		const observer = this.observeActivation(provider, childId, parent);
 		const handle = create === void 0 ? await this.ownerCtx.agents.resume({
 			resumeSessionId: childId,
+			parentAgent: parent,
 			agentOptions: inputs.agentOptions,
 			signal: inputs.signal,
 			setup
 		}) : await this.ownerCtx.agents.create({
 			sessionId: childId,
+			parentAgent: parent,
 			meta: create.meta,
 			...create.seed === void 0 ? {} : { seed: create.seed },
 			inheritedEventCount: create.inheritedEventCount,
@@ -1426,6 +1427,100 @@ function foldSubagentDescriptor(events) {
 	if (event === void 0) return void 0;
 	return parseSubagentDescriptor(event.data);
 }
+const sessionIdSchema = z.string();
+const oneShotCatalogSchema = z.object({
+	version: z.literal(0),
+	childId: sessionIdSchema,
+	childCreatedAt: z.number().int().nonnegative(),
+	mode: z.literal("one-shot"),
+	label: z.string().optional()
+}).strict();
+const continuableCatalogSchema = z.object({
+	version: z.literal(0),
+	childId: sessionIdSchema,
+	childCreatedAt: z.number().int().nonnegative(),
+	mode: z.literal("continuable"),
+	label: z.string()
+}).strict();
+const eventDataSchema = z.union([oneShotCatalogSchema, continuableCatalogSchema]);
+const viewSchema = z.array(z.union([oneShotCatalogSchema.omit({
+	version: true,
+	childId: true,
+	childCreatedAt: true
+}).extend({
+	id: sessionIdSchema,
+	createdAt: oneShotCatalogSchema.shape.childCreatedAt
+}), continuableCatalogSchema.omit({
+	version: true,
+	childId: true,
+	childCreatedAt: true
+}).extend({
+	id: sessionIdSchema,
+	createdAt: continuableCatalogSchema.shape.childCreatedAt
+})]));
+const stateSchema = z.object({
+	inheritedEventCount: z.number().int().nonnegative(),
+	head: chunkedListSchema(eventDataSchema).optional()
+}).strict();
+/**
+* Materialize direct children from their parent's successful creation facts.
+* @param state - parent catalog fold state.
+* @returns current direct-child rows in parent catalog event order.
+*/
+function subagentCatalogEntries(state) {
+	const entries = [];
+	for (const data of iterateChunkedList(state.head)) entries.push(data.mode === "one-shot" ? {
+		id: data.childId,
+		createdAt: data.childCreatedAt,
+		mode: data.mode,
+		...data.label === void 0 ? {} : { label: data.label }
+	} : {
+		id: data.childId,
+		createdAt: data.childCreatedAt,
+		mode: data.mode,
+		label: data.label
+	});
+	return entries;
+}
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+const subagentCatalogProjectionDefinition = {
+	key: "subagentCatalog",
+	stateSchema,
+	init: (_header, inheritedEventCount) => ({ inheritedEventCount }),
+	apply: (state, event) => {
+		if (event.type !== "subagent/catalog" || event.seq < state.inheritedEventCount) return state;
+		return {
+			...state,
+			head: appendChunkedList(state.head, eventDataSchema.parse(event.data))
+		};
+	},
+	stateVersion: 2,
+	wire: {
+		viewSchema,
+		view: subagentCatalogEntries
+	}
+};
+/**
+* Append a complete direct-child discovery fact to its parent Session.
+* @param parent - durable direct parent receiving the discovery fact.
+* @param child - established child's immutable Session metadata.
+* @param descriptor - mode-discriminated creation label frozen with the child.
+*/
+function establishCatalogChild(parent, child, descriptor) {
+	parent.append("subagent/catalog", descriptor.mode === "one-shot" ? {
+		version: 0,
+		childId: child.id,
+		childCreatedAt: child.createdAt,
+		mode: descriptor.mode,
+		...descriptor.label === void 0 ? {} : { label: descriptor.label }
+	} : {
+		version: 0,
+		childId: child.id,
+		childCreatedAt: child.createdAt,
+		mode: descriptor.mode,
+		label: descriptor.label
+	});
+}
 //#endregion
 //#region lib/types/internal.js
 /**
@@ -1611,11 +1706,14 @@ var SubagentContinuationManager = class {
 						},
 						signal: spec.signal
 					});
-					return this.submitMaterialized(activation, isAdjacentAgentSendMessageTool(this.ctx.get("tools")?.get("send_message", activation.handle.agent)) ? withContinuableReturnGuidance(parent.id, request.prompt) : request.prompt, {
+					const childHeader = activation.handle.agent.session.header;
+					return await this.submitMaterialized(activation, isAdjacentAgentSendMessageTool(this.ctx.get("tools")?.get("send_message", activation.handle.agent)) ? withContinuableReturnGuidance(parent.id, request.prompt) : request.prompt, {
 						source: { kind: "user" },
 						signal: spec.signal,
 						delivery: "queue"
-					}, parent);
+					}, parent, () => {
+						establishCatalogChild(parent.session, childHeader, descriptor);
+					});
 				})
 			};
 		} catch (error) {
@@ -1707,7 +1805,9 @@ var SubagentContinuationManager = class {
 						return;
 					}
 				}
-				return this.submitAdmitted(activation, content, options, parent);
+				const messageId = this.submitAdmitted(activation, content, options, parent);
+				activation.announced = true;
+				return messageId;
 			});
 			/* v8 ignore start -- only a delivery that lost the disposal cutoff retries. */
 			if (live !== void 0) return live;
@@ -1817,18 +1917,23 @@ var SubagentContinuationManager = class {
 			__disposeResources$1(env_1);
 		}
 	}
-	/** Submit to a freshly materialized Activation or roll it back completely. */
-	async submitMaterialized(activation, content, options, parent) {
+	/** Admit a materialized child, commit its creation fact, and release it on failure. */
+	async submitMaterialized(activation, content, options, parent, commit) {
 		try {
 			if (contentHasImage(content)) {
 				await this.assertImageCapable(activation.handle.agent, options.signal);
 				if (activation.inbox.closing !== void 0) throw new SubagentError(`subagent "${activation.childId}" is closing`, "ACTIVATION_CLOSING");
 			}
-			return this.submitAdmitted(activation, content, options, parent);
+			const messageId = this.submitAdmitted(activation, content, options, parent);
+			commit?.();
+			activation.announced = true;
+			return messageId;
 		} catch (error) {
-			/* v8 ignore next -- rollback disposal failures must not mask the
-			* pre-acceptance signal, drain, or lifecycle failure. */
-			await this.activations.dispose(activation).catch(() => void 0);
+			try {
+				await this.activations.dispose(activation);
+			} catch (cleanupError) {
+				this.ctx.logger.warn(`subagent continuation: disposal after admission or catalog append failure also failed: ${String(cleanupError)}`);
+			}
 			throw error;
 		}
 	}
@@ -2759,6 +2864,7 @@ let SubagentRuntime = (() => {
 				}, "subagents.continuationBinding()");
 			});
 			ctx.inject(["sessionProjections"], (projectionCtx) => {
+				projectionCtx.sessionProjections.register(subagentCatalogProjectionDefinition);
 				projectionCtx.sessionProjections.register(subagentTimingProjectionDefinition);
 				projectionCtx.sessionProjections.register(subagentIdentityProjectionDefinition);
 			});
@@ -3030,6 +3136,8 @@ let SubagentRuntime = (() => {
 		* fulfills; a rejection therefore has no run for the caller to dispose and
 		* emits no run lifecycle events. Post-publication turn and infrastructure
 		* failures settle through the returned run.
+		* A catalog append failure disposes the run and handles its result rejection;
+		* the caller receives the catalog error even if disposal also fails.
 		* @param name - the provider to use.
 		* @param request - child label, prompt, parent, signal, and optional capabilities.
 		* @returns the published holder-owned run.
@@ -3048,7 +3156,20 @@ let SubagentRuntime = (() => {
 				...request,
 				descriptor
 			};
-			return observeRun(this.emitLifecycle, name, request.parent, await provider.start(resolved));
+			const run = await provider.start(resolved);
+			const child = run.localAgent?.session;
+			if (child !== void 0) try {
+				establishCatalogChild(request.parent.session, child.header, descriptor);
+			} catch (error) {
+				run.result.catch(() => void 0);
+				try {
+					await run.dispose();
+				} catch (cleanupError) {
+					this.ctx.logger.warn(`subagent: disposal after catalog append failure also failed: ${String(cleanupError)}`);
+				}
+				throw error;
+			}
+			return observeRun(this.emitLifecycle, name, request.parent, run);
 		}
 		/**
 		* Resolve one provider's detached continuable-creation contribution. Method

package/lib/typert.host.js

@@ -102,7 +102,7 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentInterruptReceipt',
         schema: _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":477,"column":3},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":480,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-subagent#subagents/list',
@@ -129,7 +129,7 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentCatalog',
         schema: _deepseek_ai_dsh_subagent_subagents_list_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":383,"column":9},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":386,"column":9},
     },
     {
       id: '@deepseek-ai/dsh-subagent#subagents/prompt',
@@ -155,7 +155,7 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptReceipt',
         schema: _deepseek_ai_dsh_subagent_subagents_prompt_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":410,"column":9},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":413,"column":9},
     },
   ],
   model: {
@@ -264,7 +264,7 @@ export const TYPERT = {
             "name": "start",
             "signature": "async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>",
             "summary": "Establish a published child on the named provider.",
-            "jsDoc": "/**\n * Establish a published child on the named provider. Capability and semantic\n * checks run before delegation. Provider ownership lasts until its promise\n * fulfills; a rejection therefore has no run for the caller to dispose and\n * emits no run lifecycle events. Post-publication turn and infrastructure\n * failures settle through the returned run.\n * @param name - the provider to use.\n * @param request - child label, prompt, parent, signal, and optional capabilities.\n * @returns the published holder-owned run.\n */"
+            "jsDoc": "/**\n * Establish a published child on the named provider. Capability and semantic\n * checks run before delegation. Provider ownership lasts until its promise\n * fulfills; a rejection therefore has no run for the caller to dispose and\n * emits no run lifecycle events. Post-publication turn and infrastructure\n * failures settle through the returned run.\n * A catalog append failure disposes the run and handles its result rejection;\n * the caller receives the catalog error even if disposal also fails.\n * @param name - the provider to use.\n * @param request - child label, prompt, parent, signal, and optional capabilities.\n * @returns the published holder-owned run.\n */"
           }
         ],
         "types": [
@@ -386,7 +386,15 @@ export const TYPERT = {
           },
           {
             "name": "EpochHeader",
-            "declaration": "export interface EpochHeader {\n    config: LlmCallConfig;\n    adapterDefaults?: LlmCallConfigAdapterDefaults;\n    system?: string;\n    tools?: ToolSchema[];\n}"
+            "declaration": "export interface EpochHeader {\n    config: LlmCallConfig;\n    adapterDefaults?: LlmCallConfigAdapterDefaults;\n    tools?: ToolSchema[];\n}"
+          },
+          {
+            "name": "FeedbackCategory",
+            "declaration": "export type FeedbackCategory = 'task-result' | 'instruction-following' | 'product-interaction' | 'service-stability' | 'resource-cost' | 'security-privacy-permission' | 'other';"
+          },
+          {
+            "name": "FeedbackRecord",
+            "declaration": "export interface FeedbackRecord {\n    readonly text?: string;\n    readonly category?: FeedbackCategory;\n}"
           },
           {
             "name": "FileAttachmentRef",
@@ -458,7 +466,7 @@ export const TYPERT = {
           },
           {
             "name": "Inbox",
-            "declaration": "export class Inbox {\n    get nextTurn(): readonly UserMessage[];\n    get nextStep(): readonly UserMessage[];\n    get hasPending(): boolean;\n    clear(): void;\n    claim(target: InboxTarget, turn: number): UserMessage[];\n    append(target: InboxTarget, message: UserMessage): void;\n    prepend(target: InboxTarget, message: UserMessage): void;\n    replace(messageId: MessageId, newMessage: UserMessage): boolean;\n    remove(messageId: MessageId): boolean;\n    splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n}"
+            "declaration": "export interface Inbox {\n    readonly nextTurn: readonly UserMessage[];\n    readonly nextStep: readonly UserMessage[];\n    clear(): void;\n    append(target: InboxTarget, message: UserMessage): void;\n    prepend(target: InboxTarget, message: UserMessage): void;\n    replace(messageId: MessageId, newMessage: UserMessage): boolean;\n    remove(messageId: MessageId): boolean;\n    splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];\n}"
           },
           {
             "name": "InboxTarget",
@@ -502,7 +510,7 @@ export const TYPERT = {
           },
           {
             "name": "MessageFeedbackItem",
-            "declaration": "export interface MessageFeedbackItem {\n    readonly messageId: MessageId;\n    readonly rating: MessageFeedbackRating;\n    readonly note?: string;\n    readonly version: MessageFeedbackVersion;\n    readonly createdAt: number;\n    readonly updatedAt: number;\n}"
+            "declaration": "export interface MessageFeedbackItem {\n    readonly messageId: MessageId;\n    readonly rating: MessageFeedbackRating;\n    readonly note?: string;\n    readonly category?: FeedbackCategory;\n    readonly version: MessageFeedbackVersion;\n    readonly createdAt: number;\n    readonly updatedAt: number;\n}"
           },
           {
             "name": "MessageFeedbackPut",
@@ -578,7 +586,7 @@ export const TYPERT = {
           },
           {
             "name": "RequestContext",
-            "declaration": "export interface RequestContext {\n    provider: string;\n    model: string;\n    contextWindow?: number;\n}"
+            "declaration": "export interface RequestContext {\n    provider: string;\n    model: string;\n    contextWindow?: number;\n    systemPromptUpdate?: SystemPromptUpdate;\n}"
           },
           {
             "name": "RequestHeaderReason",
@@ -598,11 +606,11 @@ export const TYPERT = {
           },
           {
             "name": "SessionEvent",
-            "declaration": "export type SessionEvent<T extends SessionEventType = SessionEventType> = { [K in SessionEventType]: { type: K; seq: SessionSeq; time: number; data: SessionEventMap[K]; ignorable?: true; } & (K extends SurfaceEventType ? { sourceEventSeqs?: SessionSeq[]; surfaceOp?: SurfaceOp; } : object) }[T];"
+            "declaration": "export type SessionEvent<T extends SessionEventType = SessionEventType> = { [K in SessionEventType]: { type: K; seq: SessionSeq; time: number; data: SessionEventMap[K]; ignorable?: true; } & (K extends SurfaceEventType ? SurfaceIntent<K> : { surfaceOp?: never; sourceEventSeqs?: never; }) }[T];"
           },
           {
             "name": "SessionEventMap",
-            "declaration": "export interface SessionEventMap {\n    'turn/start': { turn: number; };\n    'turn/end': { turn: number; reason: TurnEndReason; };\n    'step/start': { turn: number; step: number; };\n    'step/end': { turn: number; step: number; };\n    'user/message': UserMessage;\n    'assistant/message': { turn: number; step: number; message: AssistantMessage; stream: AssistantStreamRecord[]; usage?: TokenUsage; interrupted?: true; };\n    'assistant/attempt': { turn: number; step: number; stream: AssistantStreamRecord[]; };\n    'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string; };\n    'tool/result': { turn: number; step: number; message: ToolResultMessage; error?: { name: string; code: string; }; meta?: JsonValue; };\n    'request/header': { header: EpochHeader; reason: RequestHeaderReason; startsSeries?: true; };\n    'request/context': RequestContext;\n    'session/end-seed': { inherited?: true; };\n    'agent/inbox/spliced': { target: InboxTarget; start: number; removedCount?: number; inserted: UserMessage[]; outcome?: 'canceled'; };\n    'approval/asked': { id: ApprovalRequestId; toolName: string; callId?: ToolCallId; reason?: string; };\n    'approval/decided': { id: ApprovalRequestId; outcome: ApprovalOutcome; };\n    'approval/policy': { policy: ApprovalPolicy; source?: 'delegation'; };\n    'tool/code-dispatch-start': PtcDispatchStartEventData;\n    'tool/code-dispatch': PtcDispatchEventData;\n    'agent-preset/selected': { agentPreset: string; };\n    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource; };\n    'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string; sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq; };\n    'session/title': SessionTitleEventData;\n    'todo/write': { todos: TodoItem[]; };\n    'model/selection': ModelSelection;\n    'subagent/descriptor': SubagentDescriptorData;\n    'sandbox/mode': { mode: SandboxMode; source?: 'delegation'; };\n    'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot; };\n    'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot; };\n    'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot; };\n    'team/message/delivered': { version: 2; teamId: TeamId; messageId: TeamMessageId; targetId: SessionId; };\n    'goal/change': GoalChangeMeta;\n    'feedback/message-put': MessageFeedbackPut;\n    'feedback/message-delete': MessageFeedbackDelete;\n    'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; };\n    'compaction/summary': { compactionId: CompactionId; sourceCommandId?: CommandId; summary: ContentBlock[]; shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; provider: string; model: string; maxTokens?: number; usage?: TokenUsage; } & ({ rawOutput: ContentBlock[]; llmStreamCall: true; } | { rawOutput?: ContentBlock[]; llmStreamCall?: never; });\n    'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string; };\n    'compaction/prune': { shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; };\n}"
+            "declaration": "export interface SessionEventMap {\n    'turn/start': { turn: number; };\n    'turn/end': { turn: number; reason: TurnEndReason; };\n    'step/start': { turn: number; step: number; };\n    'step/end': { turn: number; step: number; };\n    'user/message': UserMessage;\n    'system/message': { turn: number; step: number; message: SystemMessage; };\n    'assistant/message': { turn: number; step: number; message: AssistantMessage; stream: AssistantStreamRecord[]; usage?: TokenUsage; interrupted?: true; };\n    'assistant/attempt': { turn: number; step: number; stream: AssistantStreamRecord[]; };\n    'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string; };\n    'tool/result': { turn: number; step: number; message: ToolResultMessage; error?: { name: string; code: string; }; meta?: JsonValue; };\n    'request/header': { header: EpochHeader; reason: RequestHeaderReason; startsSeries?: true; };\n    'request/context': RequestContext;\n    'session/end-seed': { inherited?: true; };\n    'agent/inbox/spliced': { target: InboxTarget; start: number; removedCount?: number; inserted: UserMessage[]; outcome?: 'canceled'; };\n    'approval/asked': { id: ApprovalRequestId; toolName: string; callId?: ToolCallId; reason?: string; };\n    'approval/decided': { id: ApprovalRequestId; outcome: ApprovalOutcome; };\n    'approval/policy': { policy: ApprovalPolicy; source?: 'delegation'; };\n    'tool/ptc-dispatch-start': PtcDispatchStartEventData;\n    'tool/ptc-dispatch': PtcDispatchEventData;\n    'agent-preset/selected': { agentPreset: string; };\n    'command/run': { commandId: CommandId; name: string; args?: string; source: CommandSource; };\n    'command/done': { commandId: CommandId; kind: 'success' | 'error'; text?: string; sourceEventSeq?: import('@deepseek-ai/dsh-session/types').SessionSeq; };\n    'session/title': SessionTitleEventData;\n    'todo/write': { todos: TodoItem[]; };\n    'model/selection': ModelSelection;\n    'subagent/descriptor': SubagentDescriptorData;\n    'sandbox/mode': { mode: SandboxMode; source?: 'delegation'; };\n    'subagent/catalog': SubagentCatalogEvent;\n    'feedback/record': FeedbackRecord;\n    'team/member': { version: 2; teamId: TeamId; member: TeamMemberSnapshot; };\n    'team/task': { version: 2; teamId: TeamId; task: TeamTaskSnapshot; };\n    'team/message/queued': { version: 2; teamId: TeamId; message: TeamMessageSnapshot; };\n    'team/message/delivered': { version: 2; teamId: TeamId; messageId: TeamMessageId; targetId: SessionId; };\n    'goal/change': GoalChangeMeta;\n    'feedback/message-put': MessageFeedbackPut;\n    'feedback/message-delete': MessageFeedbackDelete;\n    'compaction/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; };\n    'compaction/summary': { compactionId: CompactionId; sourceCommandId?: CommandId; summary: ContentBlock[]; shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; provider: string; model: string; maxTokens?: number; usage?: TokenUsage; } & ({ rawOutput: ContentBlock[]; llmStreamCall: true; } | { rawOutput?: ContentBlock[]; llmStreamCall?: never; });\n    'compaction/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string; };\n    'compaction/prune': { shadowedRange: { start: SessionSeq; end: SessionSeq; }; shadowedSeqs: SessionSeq[]; shadowedTokenCount: number; };\n}"
           },
           {
             "name": "SessionEventType",
@@ -668,6 +676,10 @@ export const TYPERT = {
             "name": "SubagentCatalog",
             "declaration": "export interface SubagentCatalog {\n    readonly entries: readonly SubagentListEntry[];\n    readonly parentAvailable: boolean;\n}"
           },
+          {
+            "name": "SubagentCatalogEvent",
+            "declaration": "export type SubagentCatalogEvent = { readonly version: 0; readonly childId: SessionId; readonly childCreatedAt: number; } & ({ readonly mode: 'one-shot'; readonly label?: string; } | { readonly mode: 'continuable'; readonly label: string; });"
+          },
           {
             "name": "SubagentDescendantListEntry",
             "declaration": "export type SubagentDescendantListEntry = SubagentListEntry & { readonly parentId: SessionId; readonly depth: number; };"
@@ -738,7 +750,7 @@ export const TYPERT = {
           },
           {
             "name": "SurfaceEventType",
-            "declaration": "export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';"
+            "declaration": "export type SurfaceEventType = 'system/message' | 'user/message' | 'assistant/message' | 'tool/result';"
           },
           {
             "name": "SurfaceIntent",
@@ -746,7 +758,15 @@ export const TYPERT = {
           },
           {
             "name": "SurfaceOp",
-            "declaration": "export type SurfaceOp = 'append' | { op: 'replace'; start: SessionSeq; end: SessionSeq; };"
+            "declaration": "export type SurfaceOp = 'append' | { op: 'replace'; startSeq: SessionSeq; endSeq: SessionSeq; };"
+          },
+          {
+            "name": "SystemMessage",
+            "declaration": "export interface SystemMessage extends Message {\n    readonly role: 'system';\n    readonly source: MessageSourceMap['plugin'];\n}"
+          },
+          {
+            "name": "SystemPromptUpdate",
+            "declaration": "export type SystemPromptUpdate = 'in-history';"
           },
           {
             "name": "TeamId",

package/lib/typert.remote-client.js

@@ -99,7 +99,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentInterruptReceipt',
         schema: _deepseek_ai_dsh_subagent_subagents_interruptByParent_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":477,"column":3},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":480,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-subagent#subagents/list',
@@ -126,7 +126,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentCatalog',
         schema: _deepseek_ai_dsh_subagent_subagents_list_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":383,"column":9},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":386,"column":9},
     },
     {
       id: '@deepseek-ai/dsh-subagent#subagents/prompt',
@@ -152,7 +152,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-subagent/client#SubagentPromptReceipt',
         schema: _deepseek_ai_dsh_subagent_subagents_prompt_result$schema,
       },
-      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":410,"column":9},
+      sourceLocation: {"file":"packages/subagent/subagent/src/index.ts","line":413,"column":9},
     },
   ],
 }

package/lib/types/catalog.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Parent-owned durable subagent catalog events and their chunked projection.
+ *
+ * @module @deepseek-ai/dsh-subagent/catalog
+ */
+import { z } from 'zod';
+import type { ChunkedList } from '@deepseek-ai/dsh-chunked-list';
+import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
+import type { SubagentCatalogEntry } from './projection-types.ts';
+/** Current payload version for `subagent/catalog` events. */
+export declare const SUBAGENT_CATALOG_VERSION = 0;
+/** One complete parent-owned catalog fact. */
+export type SubagentCatalogEvent = {
+    readonly version: 0;
+    readonly childId: SessionId;
+    readonly childCreatedAt: number;
+} & ({
+    readonly mode: 'one-shot';
+    readonly label?: string;
+} | {
+    readonly mode: 'continuable';
+    readonly label: string;
+});
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * A direct child's complete discovery fact.
+         * @param data - versioned parent-owned catalog entry.
+         */
+        'subagent/catalog': SubagentCatalogEvent;
+    }
+}
+/** Host fold state for one parent catalog. */
+export interface SubagentCatalogState {
+    readonly inheritedEventCount: SessionLogOffset;
+    readonly head?: ChunkedList<SubagentCatalogEvent> | undefined;
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        subagentCatalog: SubagentCatalogState;
+    }
+}
+/**
+ * Materialize direct children from their parent's successful creation facts.
+ * @param state - parent catalog fold state.
+ * @returns current direct-child rows in parent catalog event order.
+ */
+declare function subagentCatalogEntries(state: SubagentCatalogState): SubagentCatalogEntry[];
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+export declare const subagentCatalogProjectionDefinition: {
+    key: "subagentCatalog";
+    stateSchema: z.ZodType<SubagentCatalogState, unknown, z.core.$ZodTypeInternals<SubagentCatalogState, unknown>>;
+    init: (_header: SessionHeader, inheritedEventCount: SessionLogOffset) => {
+        inheritedEventCount: SessionLogOffset;
+    };
+    apply: (state: NoInfer<SubagentCatalogState>, event: SessionEvent) => SubagentCatalogState;
+    stateVersion: number;
+    wire: {
+        viewSchema: z.ZodType<SubagentCatalogEntry[], unknown, z.core.$ZodTypeInternals<SubagentCatalogEntry[], unknown>>;
+        view: typeof subagentCatalogEntries;
+    };
+};
+/**
+ * Append a complete direct-child discovery fact to its parent Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param child - established child's immutable Session metadata.
+ * @param descriptor - mode-discriminated creation label frozen with the child.
+ */
+export declare function establishCatalogChild(parent: Session, child: SessionHeader, descriptor: {
+    readonly mode: 'one-shot';
+    readonly label?: string;
+} | {
+    readonly mode: 'continuable';
+    readonly label: string;
+}): void;
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/catalog.js

@@ -0,0 +1,103 @@
+/**
+ * Parent-owned durable subagent catalog events and their chunked projection.
+ *
+ * @module @deepseek-ai/dsh-subagent/catalog
+ */
+import { z } from 'zod';
+import { appendChunkedList, chunkedListSchema, iterateChunkedList } from '@deepseek-ai/dsh-chunked-list';
+/** Current payload version for `subagent/catalog` events. */
+export const SUBAGENT_CATALOG_VERSION = 0;
+const sessionIdSchema = z.string();
+const oneShotCatalogSchema = z.object({
+    version: z.literal(SUBAGENT_CATALOG_VERSION),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal('one-shot'),
+    label: z.string().optional(),
+}).strict();
+const continuableCatalogSchema = z.object({
+    version: z.literal(SUBAGENT_CATALOG_VERSION),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal('continuable'),
+    label: z.string(),
+}).strict();
+const eventDataSchema = z.union([
+    oneShotCatalogSchema,
+    continuableCatalogSchema,
+]);
+const viewSchema = z.array(z.union([
+    oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: oneShotCatalogSchema.shape.childCreatedAt,
+    }),
+    continuableCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: continuableCatalogSchema.shape.childCreatedAt,
+    }),
+]));
+const stateSchema = z.object({
+    inheritedEventCount: z.number().int().nonnegative(),
+    head: chunkedListSchema(eventDataSchema).optional(),
+}).strict();
+/**
+ * Materialize direct children from their parent's successful creation facts.
+ * @param state - parent catalog fold state.
+ * @returns current direct-child rows in parent catalog event order.
+ */
+function subagentCatalogEntries(state) {
+    const entries = [];
+    for (const data of iterateChunkedList(state.head)) {
+        entries.push(data.mode === 'one-shot'
+            ? {
+                id: data.childId,
+                createdAt: data.childCreatedAt,
+                mode: data.mode,
+                ...data.label === undefined ? {} : { label: data.label },
+            }
+            : {
+                id: data.childId,
+                createdAt: data.childCreatedAt,
+                mode: data.mode,
+                label: data.label,
+            });
+    }
+    return entries;
+}
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+export const subagentCatalogProjectionDefinition = {
+    key: 'subagentCatalog',
+    stateSchema,
+    init: (_header, inheritedEventCount) => ({ inheritedEventCount }),
+    apply: (state, event) => {
+        if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount)
+            return state;
+        return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) };
+    },
+    stateVersion: 2,
+    wire: { viewSchema, view: subagentCatalogEntries },
+};
+/**
+ * Append a complete direct-child discovery fact to its parent Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param child - established child's immutable Session metadata.
+ * @param descriptor - mode-discriminated creation label frozen with the child.
+ */
+export function establishCatalogChild(parent, child, descriptor) {
+    parent.append('subagent/catalog', descriptor.mode === 'one-shot'
+        ? {
+            version: SUBAGENT_CATALOG_VERSION,
+            childId: child.id,
+            childCreatedAt: child.createdAt,
+            mode: descriptor.mode,
+            ...descriptor.label === undefined ? {} : { label: descriptor.label },
+        }
+        : {
+            version: SUBAGENT_CATALOG_VERSION,
+            childId: child.id,
+            childCreatedAt: child.createdAt,
+            mode: descriptor.mode,
+            label: descriptor.label,
+        });
+}
+//# sourceMappingURL=catalog.js.map

package/lib/types/client.d.ts

@@ -4,5 +4,5 @@
  * @module @deepseek-ai/dsh-subagent/client
  */
 export type * from './control-types.ts';
-export type { SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
+export type { SubagentCatalogEntry, SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
 //# sourceMappingURL=client.d.ts.map

package/lib/types/continuation-activation.js

@@ -337,7 +337,6 @@ export class ContinuableActivationRegistry {
         finally {
             this.wake(activation);
         }
-        activation.announced = true;
         return message.id;
     }
     /**
@@ -405,8 +404,7 @@ export class ContinuableActivationRegistry {
     async materializeTracked(inputs, parentLineage) {
         const { childId, provider, parent, create } = inputs;
         inputs.signal.throwIfAborted();
-        const setup = (childCtx) => {
-            const child = childCtx.agent;
+        const setup = (childCtx, child) => {
             // Only fresh creation appends the descriptor and delegated policy after
             // the inherited marker; a cold resume replays those persisted events.
             if (create !== undefined) {
@@ -419,12 +417,14 @@ export class ContinuableActivationRegistry {
         const handle = create === undefined
             ? await this.ownerCtx.agents.resume({
                 resumeSessionId: childId,
+                parentAgent: parent,
                 agentOptions: inputs.agentOptions,
                 signal: inputs.signal,
                 setup,
             })
             : await this.ownerCtx.agents.create({
                 sessionId: childId,
+                parentAgent: parent,
                 meta: create.meta,
                 ...(create.seed === undefined ? {} : { seed: create.seed }),
                 inheritedEventCount: create.inheritedEventCount,

package/lib/types/continuation.d.ts

@@ -109,7 +109,7 @@ export declare class SubagentContinuationManager {
      * supplies every reconstruction input; no subagent provider is dispatched.
      */
     private coldResume;
-    /** Submit to a freshly materialized Activation or roll it back completely. */
+    /** Admit a materialized child, commit its creation fact, and release it on failure. */
     private submitMaterialized;
     /** Build and submit one message across the final synchronous admission cutoff. */
     private submitAdmitted;

package/lib/types/continuation.js

@@ -73,6 +73,7 @@ import { ContinuableActivationRegistry, } from "./continuation-activation.js";
 import { createAgentMessage, withContinuableReturnGuidance, } from "./continuation-messages.js";
 import { assertSubagentMaxDepth } from "./depth.js";
 import { foldSubagentDescriptor, snapshotSubagentDescriptor } from "./descriptor.js";
+import { establishCatalogChild } from "./catalog.js";
 import { SubagentError } from "./error.js";
 import { isAdjacentAgentSendMessageTool } from "./internal.js";
 /**
@@ -167,9 +168,10 @@ export class SubagentContinuationManager {
                     composition: { persona: request.persona, toolFilter: request.toolFilter },
                     signal: spec.signal,
                 });
-                return this.submitMaterialized(activation, isAdjacentAgentSendMessageTool(this.ctx.get('tools')?.get('send_message', activation.handle.agent))
+                const childHeader = activation.handle.agent.session.header;
+                return await this.submitMaterialized(activation, isAdjacentAgentSendMessageTool(this.ctx.get('tools')?.get('send_message', activation.handle.agent))
                     ? withContinuableReturnGuidance(parent.id, request.prompt)
-                    : request.prompt, { source: { kind: 'user' }, signal: spec.signal, delivery: 'queue' }, parent);
+                    : request.prompt, { source: { kind: 'user' }, signal: spec.signal, delivery: 'queue' }, parent, () => { establishCatalogChild(parent.session, childHeader, descriptor); });
             });
             return { childId, messageId };
         }
@@ -264,7 +266,9 @@ export class SubagentContinuationManager {
                         return undefined;
                     }
                 }
-                return this.submitAdmitted(activation, content, options, parent);
+                const messageId = this.submitAdmitted(activation, content, options, parent);
+                activation.announced = true;
+                return messageId;
             });
             /* v8 ignore start -- only a delivery that lost the disposal cutoff retries. */
             if (live !== undefined)
@@ -385,8 +389,8 @@ export class SubagentContinuationManager {
             __disposeResources(env_1);
         }
     }
-    /** Submit to a freshly materialized Activation or roll it back completely. */
-    async submitMaterialized(activation, content, options, parent) {
+    /** Admit a materialized child, commit its creation fact, and release it on failure. */
+    async submitMaterialized(activation, content, options, parent, commit) {
         try {
             if (contentHasImage(content)) {
                 await this.assertImageCapable(activation.handle.agent, options.signal);
@@ -394,12 +398,18 @@ export class SubagentContinuationManager {
                     throw new SubagentError(`subagent "${activation.childId}" is closing`, 'ACTIVATION_CLOSING');
                 }
             }
-            return this.submitAdmitted(activation, content, options, parent);
+            const messageId = this.submitAdmitted(activation, content, options, parent);
+            commit?.();
+            activation.announced = true;
+            return messageId;
         }
         catch (error) {
-            /* v8 ignore next -- rollback disposal failures must not mask the
-             * pre-acceptance signal, drain, or lifecycle failure. */
-            await this.activations.dispose(activation).catch(() => undefined);
+            try {
+                await this.activations.dispose(activation);
+            }
+            catch (cleanupError) {
+                this.ctx.logger.warn(`subagent continuation: disposal after admission or catalog append failure also failed: ${String(cleanupError)}`);
+            }
             throw error;
         }
     }

package/lib/types/inbox.js

@@ -27,7 +27,7 @@ export class SubagentInbox {
      * @returns whether either Agent inbox destination is non-empty.
      */
     get hasPending() {
-        return this.agent.inbox.hasPending;
+        return this.agent.inbox.nextTurn.length > 0 || this.agent.inbox.nextStep.length > 0;
     }
     /**
      * Submit through the Agent only while its Activation remains resident.

package/lib/types/index.d.ts

@@ -38,6 +38,7 @@ import type { SubagentCatalog, SubagentInterruptReceipt, SubagentPromptReceipt,
 import type { ContinuableStart, ContinuableStartSpec, SubagentInterruptAuthority, SubagentProvider, SubagentRun, SubagentRunEndInfo, SubagentRunInfo, SubagentSendMessageOptions, SubagentStartRequest } from './types.ts';
 import type { SubagentDescendantListEntry, SubagentListEntry } from './list-children.ts';
 import { deliverSubagentPrompt } from './internal.ts';
+export type {} from './catalog.ts';
 export * from './out-of-process.ts';
 export { AssistantOutputFold, finalAssistantOutput } from './assistant-output.ts';
 export { SubagentRunId } from './types.ts';
@@ -286,6 +287,8 @@ export declare class SubagentRuntime extends TypertRemoteService {
      * fulfills; a rejection therefore has no run for the caller to dispose and
      * emits no run lifecycle events. Post-publication turn and infrastructure
      * failures settle through the returned run.
+     * A catalog append failure disposes the run and handles its result rejection;
+     * the caller receives the catalog error even if disposal also fails.
      * @param name - the provider to use.
      * @param request - child label, prompt, parent, signal, and optional capabilities.
      * @returns the published holder-owned run.

package/lib/types/index.js

@@ -74,6 +74,7 @@ import SubagentContinuationManager from "./continuation.js";
 import { listChildren as listSubagentChildren, listDescendants as listSubagentDescendants } from "./list-children.js";
 import { snapshotSubagentDescriptor } from "./descriptor.js";
 import { subagentIdentityProjectionDefinition, subagentTimingProjectionDefinition } from "./projection.js";
+import { establishCatalogChild, subagentCatalogProjectionDefinition } from "./catalog.js";
 import { deliverSubagentPrompt } from "./internal.js";
 export * from "./out-of-process.js";
 export { AssistantOutputFold, finalAssistantOutput } from "./assistant-output.js";
@@ -125,6 +126,7 @@ let SubagentRuntime = (() => {
                 }, 'subagents.continuationBinding()');
             });
             ctx.inject(['sessionProjections'], (projectionCtx) => {
+                projectionCtx.sessionProjections.register(subagentCatalogProjectionDefinition);
                 projectionCtx.sessionProjections.register(subagentTimingProjectionDefinition);
                 projectionCtx.sessionProjections.register(subagentIdentityProjectionDefinition);
             });
@@ -414,6 +416,8 @@ let SubagentRuntime = (() => {
          * fulfills; a rejection therefore has no run for the caller to dispose and
          * emits no run lifecycle events. Post-publication turn and infrastructure
          * failures settle through the returned run.
+         * A catalog append failure disposes the run and handles its result rejection;
+         * the caller receives the catalog error even if disposal also fails.
          * @param name - the provider to use.
          * @param request - child label, prompt, parent, signal, and optional capabilities.
          * @returns the published holder-owned run.
@@ -430,7 +434,25 @@ let SubagentRuntime = (() => {
                 ...request.label !== undefined ? { label: request.label } : {},
             });
             const resolved = { ...request, descriptor };
-            return observeRun(this.emitLifecycle, name, request.parent, await provider.start(resolved));
+            const run = await provider.start(resolved);
+            const child = run.localAgent?.session;
+            if (child !== undefined) {
+                try {
+                    establishCatalogChild(request.parent.session, child.header, descriptor);
+                }
+                catch (error) {
+                    // No caller receives this run; the catalog error owns the failed start.
+                    void run.result.catch(() => undefined);
+                    try {
+                        await run.dispose();
+                    }
+                    catch (cleanupError) {
+                        this.ctx.logger.warn(`subagent: disposal after catalog append failure also failed: ${String(cleanupError)}`);
+                    }
+                    throw error;
+                }
+            }
+            return observeRun(this.emitLifecycle, name, request.parent, run);
         }
         /**
          * Resolve one provider's detached continuable-creation contribution. Method

package/lib/types/projection-types.d.ts

@@ -3,7 +3,18 @@
  *
  * @module @deepseek-ai/dsh-subagent/projection-types
  */
-import type { SessionSeq } from '@deepseek-ai/dsh-session/types';
+import type { SessionId, SessionSeq } from '@deepseek-ai/dsh-session/types';
+/** One current direct-child discovery row materialized from parent facts. */
+export type SubagentCatalogEntry = {
+    readonly id: SessionId;
+    readonly createdAt: number;
+} & ({
+    readonly mode: 'one-shot';
+    readonly label?: string;
+} | {
+    readonly mode: 'continuable';
+    readonly label: string;
+});
 /** Durable active-turn timing for one descriptor-backed child session. */
 export interface SubagentTimingProjection {
     /** Milliseconds accumulated across completed turns after the child's own descriptor. */
@@ -44,6 +55,8 @@ export type SubagentIdentityProjection = {
 };
 declare module '@deepseek-ai/dsh-session-projection/types' {
     interface SessionProjectionMap {
+        /** Direct children in parent catalog event order, excluding fork-inherited facts. */
+        subagentCatalog: SubagentCatalogEntry[];
         /** Active-turn duration for a descriptor-backed subagent session. */
         subagentTiming: SubagentTimingProjection;
         /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent",
   "description": "Abstract subagent seam (ctx.subagents): named-provider registry for delegating to child agents",
-  "version": "0.1.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -54,30 +54,31 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-brand": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-chunked-list": "^0.1.5-alpha.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-projection-cache": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-query": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-util-time": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-agent-presets": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-util-time": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-agent-presets": {
@@ -110,27 +111,28 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-agent-presets": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-jobs": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-scope": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-query": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-storage": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session-projection-cache": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-storage-json": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-user-approval": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-util-time": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-schedule": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-storage": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-storage-json": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-util-time": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.5-alpha.2"
   }
 }