@oai404iao/pi-subagent 0.3.0 → 0.4.0

package/src/coordinator.ts

@@ -20,23 +20,60 @@ import {
 	ModelRuntime,
 	SessionManager,
 } from "@earendil-works/pi-coding-agent";
+import { syncBundledAgents, type AgentSyncResult } from "./agent-sync.ts";
 import {
-	syncBundledAgents,
-	type AgentSyncResult,
-	unmodifiedManagedAgentNames,
-} from "./agent-sync.ts";
+	catalogStatus,
+	closeAgent,
+	createAgentControlState,
+	currentAgentTurnId,
+	delegationStatus,
+	finishAgentTurn,
+	interruptAgentTurn,
+	queueAgentTurn,
+	setAgentResidency,
+	startAgentTurn,
+	type AgentControlState,
+} from "./agent-state.ts";
 import {
 	discoverAgents,
 	formatAgentCatalog,
 	type AgentDiscoveryResult,
 } from "./agents.ts";
 import { readPersistedCatalog } from "./catalog.ts";
-import { DESCRIPTOR_CUSTOM_TYPE, foldDescriptor } from "./descriptor.ts";
 import {
+	MAX_COMPLETIONS_PER_DELIVERY,
+	appendCompletionUpdate,
+	appendUndeliveredCompletion,
+	foldCompletionMailbox,
+	readCompletionMailbox,
+	releaseCompletionDeliveries,
+	reserveCompletionDelivery,
+	unreadCompletionCounts,
+	type CompletionUpdate,
+} from "./completion-mailbox.ts";
+import {
+	DESCRIPTOR_CUSTOM_TYPE,
+	DESCRIPTOR_VERSION,
+	descriptorContext,
+	foldDescriptor,
+} from "./descriptor.ts";
+import {
+	claimMailboxMessages,
+	commitMailboxClaim,
+	enqueueMailboxMessage,
+	foldOwnedMailbox,
+	formatMailboxBatch,
+	readMailbox,
+} from "./mailbox.ts";
+import {
+	FollowupTaskParameters,
 	InterruptParameters,
 	ListAgentsParameters,
 	ReportParameters,
 	SendMessageParameters,
+	WaitAgentParameters,
+	DEFAULT_WAIT_AGENT_TIMEOUT_MS,
+	MAX_WAIT_AGENT_TIMEOUT_MS,
 	delegationParameters,
 	forkDelegationParameters,
 } from "./schemas.ts";
@@ -55,13 +92,30 @@ import {
 	ProviderRegistry,
 	SpawnProvider,
 } from "./providers.ts";
+import {
+	AgentOperationQueue,
+	BackgroundRunLimiter,
+	type BackgroundRunPermit,
+} from "./scheduler.ts";
 import { buildToolCeiling, resolveToolPolicy } from "./tool-policy.ts";
+import {
+	ROOT_TASK_PATH,
+	descriptorTaskPath,
+	isAgentId,
+	numberedTaskName,
+	resolveTaskPath,
+	slugTaskName,
+	taskPath,
+	validateTaskName,
+} from "./task-path.ts";
 import {
 	snapshotAgent,
 	type AgentDefinition,
 	type CatalogChild,
+	type CatalogDiagnostic,
 	type CatalogEntry,
 	type ControlDetails,
+	type ContextInheritance,
 	type DelegationDetails,
 	type ParentMessageDetails,
 	type SubagentDescriptor,
@@ -69,20 +123,23 @@ import {
 	type SubagentProviderName,
 	type SubagentRunResult,
 	type SubagentSettings,
+	type RuntimeMode,
 	type SubagentStopReason,
 	type TraceItem,
 } from "./types.ts";
 
 const REPORT_CUSTOM_TYPE = "pi-subagent/report";
-const SETTLED_CUSTOM_TYPE = "pi-subagent/settled";
 const AGENT_CUSTOM_TYPE = "pi-subagent/agent";
 const LINEAGE_CUSTOM_TYPE = "pi-subagent/lineage";
 const AGENT_ID_PATTERN =
 	/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const MAX_TRACE_ITEMS = 100;
 const MAX_TRACE_TEXT = 4000;
+const MAX_WAIT_AGENT_RESULT_BYTES = 256 * 1024;
 const BACKGROUND_CONTROL_TOOLS = new Set([
 	"send_message",
+	"followup_task",
+	"wait_agent",
 	"interrupt_agent",
 	"list_agents",
 ]);
@@ -96,22 +153,57 @@ const DELEGATION_SCOPE_PROMPT = [
 const REPORT_PROMPT = [
 	"You have a `report` tool that sends a selected update to the agent that started you.",
 	"Call it with a self-contained answer before finishing, and earlier when a finding changes what the parent should do.",
-	"Reporting does not end this turn and does not prevent later follow-up messages.",
+	"A report is recorded for the parent without waking it; it does not end this turn and does not prevent later follow-up messages.",
+	"Your final answer is delivered separately as a completion update.",
 ].join(" ");
 
 export interface DelegationInput {
 	agent: string;
+	task_name?: string;
 	description: string;
 	prompt: string;
-	run_in_background?: boolean;
+	context?: {
+		mode: ContextInheritance["mode"];
+		completed_turns?: number;
+	};
 }
 
 export type DelegationOutcome =
 	| { kind: "continuable"; details: DelegationDetails }
 	| { kind: "foreground"; details: DelegationDetails; result: SubagentRunResult };
 
+export interface SendMessageOutcome {
+	kind: "mailbox";
+	agentId: string;
+	taskPath: string;
+	messageId: string;
+	pendingMessages: number;
+}
+
+export interface FollowupTaskOutcome {
+	agentId: string;
+	taskPath: string;
+	turnId: string;
+	claimedMessages: number;
+}
+
+export interface InterruptOutcome {
+	agentId: string;
+	taskPath: string;
+	active: boolean;
+}
+
+export interface WaitAgentOutcome {
+	timedOut: boolean;
+	timeoutMs: number;
+	updates: CompletionUpdate[];
+	unreadUpdates: number;
+	taskPaths: Record<string, string>;
+}
+
 interface ParentRef {
 	agentId: string;
+	taskPath: string;
 	depth: number;
 	cwd: string;
 	sessionManager: SessionView;
@@ -124,7 +216,6 @@ interface ParentRef {
 		customType: string,
 		content: string,
 		details: ParentMessageDetails,
-		delivery: "wakeup" | "quiet",
 	): Promise<void>;
 }
 
@@ -136,21 +227,52 @@ interface Activation {
 	runtime: AgentSessionRuntime;
 	seedMessageCount: number;
 	epochMessageStart: number;
-	status: DelegationDetails["status"];
+	controlState: AgentControlState;
 	trace: TraceItem[];
 	streamedText: string;
 	usage: ReturnType<typeof emptyUsage>;
+	startedTurnIds: Set<string>;
+	silentSettlementTurnIds: Set<string>;
+	pendingMailboxClaims: Set<string>;
+	userMessageGates: Map<string, UserMessageGate>;
 	ownedChildren: Set<string>;
 	currentRun?: Promise<SubagentRunResult>;
 	pendingSettlement?: SubagentRunResult;
 	unsubscribe?: () => void;
 	onUpdate?: (details: DelegationDetails) => void;
 	published: boolean;
+	everPublished: boolean;
 	suppressSettlement: boolean;
 	finalizing: boolean;
-	finalizePromise?: Promise<void>;
+	finalizePromise?: Promise<boolean>;
+	holdsBackgroundSlot: boolean;
+	turnAbortController?: AbortController;
+	persistenceGate: PersistenceGate;
 	disposed: boolean;
 	lastError?: string;
+	ownerActivation?: Activation;
+	lastUsedSequence: number;
+}
+
+interface UserMessageGate {
+	prepare(): void;
+	accept(): void;
+	reject(error: Error): void;
+}
+
+interface PersistenceGate {
+	promise: Promise<void>;
+	resolve(): void;
+	reject(error: Error): void;
+	readonly settled: boolean;
+	readonly state: "pending" | "fulfilled" | "rejected";
+}
+
+interface CompletionWaiter {
+	promise: Promise<"activity" | "timeout">;
+	wake(): void;
+	reject(error: Error): void;
+	dispose(): void;
 }
 
 interface CreateActivationOptions {
@@ -161,16 +283,53 @@ interface CreateActivationOptions {
 	onUpdate?: (details: DelegationDetails) => void;
 }
 
+interface StartPromptOptions {
+	detachAtAcceptance: boolean;
+	waitForCapacity: boolean;
+	preparePrompt?: (turnId: string) => string;
+	onPromptAccepted?: (turnId: string) => void;
+	acceptAfterUserMessage?: boolean;
+}
+
+interface PendingPromptStart {
+	activation: Activation;
+	accepted: Promise<void>;
+	coldPrepared?: PreparedChildSession;
+}
+
+type SerializedSendMessageOutcome = SendMessageOutcome;
+
+interface PendingFollowupStart extends PendingPromptStart {
+	outcome: FollowupTaskOutcome;
+}
+
 interface CatalogRecord {
 	agentId: string;
+	piSessionId: string;
+	taskPath: string;
 	descriptor: SubagentDescriptor;
 	sessionFile?: string;
 	active?: Activation;
+	pendingMessages: number;
+	unreadUpdatesByChild: Map<string, number>;
+}
+
+interface ResolvedTarget {
+	agentId: string;
+	taskPath: string;
+	record?: CatalogRecord;
+}
+
+interface ReservedTask {
+	name: string;
+	path: string;
+	release(): void;
 }
 
 interface CoordinatorCatalog {
 	records: CatalogRecord[];
 	diagnostics: CatalogEntry[];
+	rootUnreadUpdatesByChild: Map<string, number>;
 }
 
 function runtimeFromRegistry(registry: ModelRegistry): ModelRuntime {
@@ -195,6 +354,79 @@ function errorText(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+function abortReason(signal: AbortSignal): Error {
+	return signal.reason instanceof Error
+		? signal.reason
+		: new Error(signal.reason ? String(signal.reason) : "operation aborted");
+}
+
+function waitForPromise<T>(
+	promise: Promise<T>,
+	signal?: AbortSignal,
+): Promise<T> {
+	if (!signal) return promise;
+	if (signal.aborted) return Promise.reject(abortReason(signal));
+	return new Promise<T>((resolvePromise, rejectPromise) => {
+		const abort = () => {
+			rejectPromise(abortReason(signal));
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then(
+			(value) => {
+				signal.removeEventListener("abort", abort);
+				resolvePromise(value);
+			},
+			(error) => {
+				signal.removeEventListener("abort", abort);
+				rejectPromise(error);
+			},
+		);
+	});
+}
+
+function createPersistenceGate(
+	session: Pick<SessionView, "getEntries">,
+	requireNewAssistant: boolean,
+): PersistenceGate {
+	const alreadyDurable = !requireNewAssistant && session
+		.getEntries()
+		.some(
+			(entry) =>
+				entry.type === "message"
+				&& entry.message.role === "assistant",
+		);
+	let state: PersistenceGate["state"] =
+		alreadyDurable ? "fulfilled" : "pending";
+	let resolvePromise!: () => void;
+	let rejectPromise!: (error: Error) => void;
+	const promise = alreadyDurable
+		? Promise.resolve()
+		: new Promise<void>((resolve, reject) => {
+				resolvePromise = resolve;
+				rejectPromise = reject;
+			});
+	void promise.catch(() => {});
+	return {
+		promise,
+		resolve: () => {
+			if (state !== "pending") return;
+			state = "fulfilled";
+			resolvePromise();
+		},
+		reject: (error) => {
+			if (state !== "pending") return;
+			state = "rejected";
+			rejectPromise(error);
+		},
+		get settled() {
+			return state !== "pending";
+		},
+		get state() {
+			return state;
+		},
+	};
+}
+
 /**
  * Read the durable pi-subagent control id recorded for a session, if any.
  *
@@ -246,17 +478,88 @@ function stopReasonHeadline(reason: SubagentStopReason): string {
 function makeRuntimeSettings(descriptor: SubagentDescriptor): SubagentSettings {
 	return {
 		agentScope: descriptor.runtime.agentScope,
-		syncBundledAgents: descriptor.runtime.syncBundledAgents,
 		maxDepth: descriptor.runtime.maxDepth,
-		enableRunInBackground: descriptor.runtime.enableRunInBackground,
-		defaultBackground: descriptor.runtime.defaultBackground,
-		reportDelivery: descriptor.runtime.reportDelivery,
+		runtimeMode: descriptor.runtime.runtimeMode,
+		maxConcurrentBackgroundRuns: descriptor.runtime.maxConcurrentBackgroundRuns,
+		maxIdleRuntimes: descriptor.runtime.maxIdleRuntimes,
 		inheritExtensions: descriptor.runtime.inheritExtensions,
 		openAIIdentity: descriptor.runtime.openAIIdentity,
 		maxOutputBytes: descriptor.runtime.maxOutputBytes,
 	};
 }
 
+function delegationContext(
+	providerName: SubagentProviderName,
+	input: DelegationInput,
+): ContextInheritance {
+	if (providerName === "fork") {
+		if (input.context !== undefined) {
+			throw new Error(
+				"subagent_fork always uses all_completed context; use subagent for another context policy",
+			);
+		}
+		return { mode: "all_completed" };
+	}
+	const context = input.context;
+	if (!context) return { mode: "fresh" };
+	if (context.mode === "last_n_completed") {
+		if (
+			!Number.isSafeInteger(context.completed_turns)
+			|| context.completed_turns === undefined
+			|| context.completed_turns < 1
+			|| context.completed_turns > 100
+		) {
+			throw new Error(
+				"context.completed_turns must be an integer between 1 and 100 for last_n_completed",
+			);
+		}
+		return {
+			mode: context.mode,
+			completedTurns: context.completed_turns,
+		};
+	}
+	if (
+		context.mode !== "fresh"
+		&& context.mode !== "all_completed"
+	) {
+		throw new Error(`unsupported context mode: ${String(context.mode)}`);
+	}
+	if (context.completed_turns !== undefined) {
+		throw new Error(
+			"context.completed_turns is available only for last_n_completed",
+		);
+	}
+	return { mode: context.mode };
+}
+
+function mailboxOwner(descriptor: SubagentDescriptor): {
+	parentAgentId: string;
+	agentId: string;
+} {
+	return {
+		parentAgentId: descriptor.parentAgentId,
+		agentId: descriptor.agentId,
+	};
+}
+
+function completionWaiterKey(parent: ParentRef): string {
+	return `${parent.agentId}:${parent.sessionManager.getSessionId()}`;
+}
+
+function waitTimeout(value: number | undefined): number {
+	const timeoutMs = value ?? DEFAULT_WAIT_AGENT_TIMEOUT_MS;
+	if (
+		!Number.isSafeInteger(timeoutMs)
+		|| timeoutMs < 0
+		|| timeoutMs > MAX_WAIT_AGENT_TIMEOUT_MS
+	) {
+		throw new Error(
+			`timeout_ms must be a safe integer between 0 and ${MAX_WAIT_AGENT_TIMEOUT_MS}`,
+		);
+	}
+	return timeoutMs;
+}
+
 function isPathInside(parent: string, child: string): boolean {
 	const rel = relative(resolve(parent), resolve(child));
 	return rel === "" || (!rel.startsWith("..") && !rel.startsWith("/"));
@@ -288,8 +591,19 @@ async function loadCodexIdentityInlineExtension(
 export class SubagentCoordinator {
 	private readonly providers = new ProviderRegistry();
 	private readonly active = new Map<string, Activation>();
+	private readonly agentOperations = new AgentOperationQueue();
+	private readonly completionOperations = new AgentOperationQueue();
+	private readonly idleRuntimeOperations = new AgentOperationQueue();
+	private readonly backgroundRuns = new BackgroundRunLimiter();
+	private readonly admittedOperations = new Set<Promise<unknown>>();
+	private readonly completionWaiters = new Map<string, CompletionWaiter>();
+	private readonly reservedTaskPaths = new Set<string>();
+	private readonly runtimeId = uuidv7();
+	private idleRuntimeLimit = 0;
+	private activationSequence = 0;
 	private agentSyncResult: AgentSyncResult | undefined;
 	private draining = false;
+	private shutdownPromise: Promise<void> | undefined;
 
 	constructor(
 		private readonly pi: ExtensionAPI,
@@ -314,26 +628,39 @@ export class SubagentCoordinator {
 		return join(this.agentDir, "agents");
 	}
 
+	configureBackgroundRuns(limit: number): void {
+		this.backgroundRuns.configure(limit);
+	}
+
+	async configureIdleRuntimes(limit: number): Promise<void> {
+		if (!Number.isSafeInteger(limit) || limit < 0) {
+			throw new Error("maxIdleRuntimes must be a non-negative safe integer");
+		}
+		this.idleRuntimeLimit = limit;
+		await this.trimIdleRuntimes();
+	}
+
 	discoverAvailableAgents(
 		cwd: string,
 		settings: SubagentSettings,
 		projectTrusted: boolean,
 	): AgentDiscoveryResult {
-		if (settings.syncBundledAgents && !this.agentSyncResult) {
+		if (!this.agentSyncResult) {
 			this.synchronizeBundledAgents();
 		}
-		const excludeUserAgentNames = settings.syncBundledAgents
-			? undefined
-			: unmodifiedManagedAgentNames(this.agentDir);
-		return discoverAgents({
+		const discovery = discoverAgents({
 			cwd,
 			scope: settings.agentScope,
 			projectTrusted,
-			bundledDir: this.bundledAgentsDir,
 			agentDir: this.agentDir,
-			includeBundled: !settings.syncBundledAgents && settings.agentScope !== "project",
-			excludeUserAgentNames,
 		});
+		return {
+			...discovery,
+			diagnostics: [
+				...(this.agentSyncResult?.diagnostics ?? []),
+				...discovery.diagnostics,
+			],
+		};
 	}
 
 	async parentFromContext(ctx: ExtensionContext): Promise<ParentRef> {
@@ -344,6 +671,9 @@ export class SubagentCoordinator {
 			agentId: readAgentId(ctx.sessionManager) ?? ensureAgentId(
 				ctx.sessionManager as unknown as SessionView,
 			),
+			taskPath: descriptor
+				? descriptorTaskPath(descriptor)
+				: ROOT_TASK_PATH,
 			depth: descriptor?.depth ?? 0,
 			cwd: ctx.cwd,
 			// ExtensionContext narrows the live SessionManager to a read-only
@@ -354,13 +684,13 @@ export class SubagentCoordinator {
 			model: ctx.model,
 			thinkingLevel: ctx.thinkingLevel ?? "off",
 			projectTrusted: ctx.isProjectTrusted(),
-			deliver: async (customType, content, details, delivery) => {
-				const options =
-					delivery === "wakeup"
-						? { triggerTurn: true, deliverAs: "followUp" as const }
-						: ctx.isIdle()
-							? { triggerTurn: false }
-							: { triggerTurn: false, deliverAs: "nextTurn" as const };
+			// Reports never start a parent turn. The entry becomes part of the
+			// parent session (and therefore its next model context) while the
+			// parent keeps working; durable completions are read with wait_agent.
+			deliver: async (customType, content, details) => {
+				const options = ctx.isIdle()
+					? { triggerTurn: false }
+					: { triggerTurn: false, deliverAs: "nextTurn" as const };
 				this.pi.sendMessage({ customType, content, display: true, details }, options);
 			},
 		};
@@ -374,34 +704,47 @@ export class SubagentCoordinator {
 		signal?: AbortSignal,
 		onUpdate?: (details: DelegationDetails) => void,
 		agentDiscovery?: AgentDiscoveryResult,
+	): Promise<DelegationOutcome> {
+		return this.runAdmittedOperation(() =>
+			this.delegateAdmitted(
+				parent,
+				providerName,
+				input,
+				settings,
+				signal,
+				onUpdate,
+				agentDiscovery,
+			),
+		);
+	}
+
+	private async delegateAdmitted(
+		parent: ParentRef,
+		providerName: SubagentProviderName,
+		input: DelegationInput,
+		settings: SubagentSettings,
+		signal?: AbortSignal,
+		onUpdate?: (details: DelegationDetails) => void,
+		agentDiscovery?: AgentDiscoveryResult,
 	): Promise<DelegationOutcome> {
 		if (this.draining) throw new Error("pi-subagent is shutting down; no new delegation was accepted");
-		const provider = this.providers.get(providerName);
-		if (
-			providerName === "spawn" &&
-			!settings.enableRunInBackground &&
-			input.run_in_background === true
-		) {
-			throw new Error(
-				"run_in_background is disabled by pi-subagent foreground-only mode (enableRunInBackground: false)",
-			);
-		}
-		const runInBackground =
-			providerName === "spawn" && settings.enableRunInBackground
-				? (input.run_in_background ?? settings.defaultBackground)
-				: false;
-		const mode: SubagentMode = runInBackground ? "continuable" : "one-shot";
+		const context = delegationContext(providerName, input);
+		const resolvedProviderName: SubagentProviderName =
+			context.mode === "fresh" ? "spawn" : "fork";
+		const provider = this.providers.get(resolvedProviderName);
+		const mode: SubagentMode =
+			settings.runtimeMode === "background" ? "continuable" : "one-shot";
 		if (mode === "continuable" && !provider.supportsContinuable) {
 			throw new Error(`subagent provider "${provider.name}" does not support continuable children`);
 		}
 		if (mode === "continuable" && !parent.sessionManager.getSessionFile()) {
 			throw new Error(
-				"continuable subagents require a persisted parent session; set run_in_background to false",
+				'continuable subagents require a persisted parent session; set runtimeMode to "foreground" to delegate from an ephemeral session',
 			);
 		}
 		if (mode === "continuable" && parent.activation?.descriptor.mode === "one-shot") {
 			throw new Error(
-				"a one-shot child cannot leave a continuable descendant behind; set run_in_background to false",
+				"a foreground child cannot leave a continuable descendant behind; its runtime mode is fixed at creation",
 			);
 		}
 
@@ -429,57 +772,71 @@ export class SubagentCoordinator {
 
 		const model = this.resolveModel(parent, agent);
 		const thinkingLevel = agent.thinking ?? parent.thinkingLevel;
-		const prepared = await provider.prepare(parent, mode);
 		parent.agentId = ensureAgentId(parent.sessionManager);
-		const openAIIdentityEnabled =
-			settings.openAIIdentity && isOpenAIResponsesModel(model);
-		const descriptor: SubagentDescriptor = {
-			version: 2,
-			mode,
-			provider: providerName,
-			label: input.description.trim(),
-			agentId: uuidv7(),
-			parentAgentId: parent.agentId,
-			parentPiSessionId: parent.sessionManager.getSessionId(),
-			...(parent.sessionManager.getSessionFile()
-				? { parentSessionFile: parent.sessionManager.getSessionFile() }
-				: {}),
-			depth,
-			cwd: parent.cwd,
-			createdAt: new Date().toISOString(),
-			agent: snapshotAgent(agent),
-			model: { provider: model.provider, id: model.id },
-			thinkingLevel,
-			runtime: {
-				agentScope: settings.agentScope,
-				syncBundledAgents: settings.syncBundledAgents,
-				maxDepth: settings.maxDepth,
-				enableRunInBackground: settings.enableRunInBackground,
-				defaultBackground: settings.defaultBackground,
-				reportDelivery: settings.reportDelivery,
-				inheritExtensions: settings.inheritExtensions,
-				openAIIdentity: openAIIdentityEnabled,
-				maxOutputBytes: settings.maxOutputBytes,
-			},
-		};
-		prepared.sessionManager.appendCustomEntry(AGENT_CUSTOM_TYPE, {
-			agentId: descriptor.agentId,
-		});
-		prepared.sessionManager.appendCustomEntry(LINEAGE_CUSTOM_TYPE, {
-			version: 1,
-			agentId: descriptor.agentId,
-			parentAgentId: descriptor.parentAgentId,
-			parentPiSessionId: descriptor.parentPiSessionId,
-			relation: descriptor.provider,
-			agentName: descriptor.agent.name,
-			openAIIdentity: openAIIdentityEnabled,
-			...(descriptor.parentSessionFile
-				? { parentSessionFile: descriptor.parentSessionFile }
-				: {}),
-		});
-
+		const reservedTask = await this.reserveTask(
+			parent,
+			input.task_name,
+			input.description,
+		);
+		let prepared: PreparedChildSession | undefined;
 		let activation: Activation | undefined;
+		let keepTaskReservation = false;
 		try {
+			prepared = await provider.prepare(parent, mode, context);
+			if (this.draining) {
+				throw new Error("pi-subagent is shutting down; no new delegation was accepted");
+			}
+			const openAIIdentityEnabled =
+				settings.openAIIdentity && isOpenAIResponsesModel(model);
+			const descriptor: SubagentDescriptor = {
+				version: DESCRIPTOR_VERSION,
+				mode,
+				provider: resolvedProviderName,
+				label: input.description.trim(),
+				agentId: uuidv7(),
+				parentAgentId: parent.agentId,
+				parentPiSessionId: parent.sessionManager.getSessionId(),
+				...(parent.sessionManager.getSessionFile()
+					? { parentSessionFile: parent.sessionManager.getSessionFile() }
+					: {}),
+				depth,
+				cwd: parent.cwd,
+				createdAt: new Date().toISOString(),
+				agent: snapshotAgent(agent),
+				model: { provider: model.provider, id: model.id },
+				thinkingLevel,
+				task: {
+					name: reservedTask.name,
+					path: reservedTask.path,
+				},
+				context,
+				runtime: {
+					agentScope: settings.agentScope,
+					maxDepth: settings.maxDepth,
+					runtimeMode: settings.runtimeMode,
+					maxConcurrentBackgroundRuns: settings.maxConcurrentBackgroundRuns,
+					maxIdleRuntimes: settings.maxIdleRuntimes,
+					inheritExtensions: settings.inheritExtensions,
+					openAIIdentity: openAIIdentityEnabled,
+					maxOutputBytes: settings.maxOutputBytes,
+				},
+			};
+			prepared.sessionManager.appendCustomEntry(AGENT_CUSTOM_TYPE, {
+				agentId: descriptor.agentId,
+			});
+			prepared.sessionManager.appendCustomEntry(LINEAGE_CUSTOM_TYPE, {
+				version: 1,
+				agentId: descriptor.agentId,
+				parentAgentId: descriptor.parentAgentId,
+				parentPiSessionId: descriptor.parentPiSessionId,
+				relation: descriptor.provider,
+				agentName: descriptor.agent.name,
+				taskPath: descriptor.task.path,
+				openAIIdentity: openAIIdentityEnabled,
+				...(descriptor.parentSessionFile
+					? { parentSessionFile: descriptor.parentSessionFile }
+					: {}),
+			});
 			activation = await this.createActivation({
 				parent,
 				descriptor,
@@ -487,11 +844,18 @@ export class SubagentCoordinator {
 				isNew: true,
 				onUpdate,
 			});
+			if (this.draining) {
+				throw new Error("pi-subagent is shutting down; no new delegation was accepted");
+			}
 			if (mode === "continuable" && parent.activation) {
-				parent.activation.ownedChildren.add(activation.agentId);
+				this.acquireParentOwnership(activation, parent);
 			}
-			const started = this.startPrompt(activation, input.prompt, signal, mode === "continuable");
+			const started = this.startPrompt(activation, input.prompt, signal, {
+				detachAtAcceptance: mode === "continuable",
+				waitForCapacity: !parent.activation?.holdsBackgroundSlot,
+			});
 			await started.accepted;
+			keepTaskReservation = true;
 			if (mode === "continuable") {
 				activation.onUpdate = undefined;
 				return { kind: "continuable", details: this.detailsOf(activation) };
@@ -503,37 +867,197 @@ export class SubagentCoordinator {
 			await this.disposeActivation(activation);
 			return { kind: "foreground", details, result };
 		} catch (error) {
-			if (activation && !activation.published) {
+			if (activation && prepared && !activation.published) {
 				activation.suppressSettlement = true;
 				await this.rollbackActivation(activation, prepared);
-			} else if (!activation) {
+			} else if (!activation && prepared) {
 				await prepared.rollback();
 			}
 			throw error;
+		} finally {
+			if (!keepTaskReservation) reservedTask.release();
 		}
 	}
 
-	async sendMessage(parent: ParentRef, childId: string, message: string, signal?: AbortSignal): Promise<void> {
+	async sendMessage(
+		parent: ParentRef,
+		childId: string,
+		message: string,
+		signal?: AbortSignal,
+	): Promise<void> {
+		await this.sendMessageWithOutcome(parent, childId, message, signal);
+	}
+
+	async sendMessageWithOutcome(
+		parent: ParentRef,
+		childId: string,
+		message: string,
+		signal?: AbortSignal,
+	): Promise<SendMessageOutcome> {
+		return this.runAdmittedOperation(() =>
+			this.sendMessageAdmitted(parent, childId, message, signal),
+		);
+	}
+
+	private async sendMessageAdmitted(
+		parent: ParentRef,
+		childId: string,
+		message: string,
+		signal?: AbortSignal,
+	): Promise<SendMessageOutcome> {
 		if (this.draining) throw new Error("pi-subagent is shutting down; message was not delivered");
+		const target = await this.resolveTarget(parent, childId);
+		return this.agentOperations.run(target.agentId, () =>
+			this.sendMessageSerialized(parent, target.agentId, message, signal),
+		);
+	}
+
+	private async sendMessageSerialized(
+		parent: ParentRef,
+		childId: string,
+		message: string,
+		signal?: AbortSignal,
+	): Promise<SerializedSendMessageOutcome> {
+		if (this.draining) {
+			throw new Error("pi-subagent is shutting down; message was not delivered");
+		}
 		let activation = this.active.get(childId);
-		let coldPrepared: PreparedChildSession | undefined;
-		if (activation?.finalizing && activation.finalizePromise) {
-			await activation.finalizePromise;
-			activation = undefined;
+		if (activation?.disposed) activation = undefined;
+		if (activation) {
+			this.touchActivation(activation);
+			this.assertContinuableDirectChild(parent, activation.descriptor);
+			if (signal?.aborted) throw abortReason(signal);
+			await waitForPromise(activation.persistenceGate.promise, signal);
+			if (this.draining || activation.disposed) {
+				throw new Error(
+					`subagent ${childId} became unavailable before its mailbox could be persisted`,
+				);
+			}
+			const enqueued = enqueueMailboxMessage(
+				activation.runtime.session.sessionManager,
+				{
+					senderAgentId: parent.agentId,
+					recipientAgentId: childId,
+					content: message,
+				},
+			);
+			return {
+				kind: "mailbox",
+				agentId: childId,
+				taskPath: descriptorTaskPath(activation.descriptor),
+				messageId: enqueued.message.messageId,
+				pendingMessages: enqueued.pendingMessages,
+			};
 		}
+		const located = await this.findPersistedChild(parent, childId);
+		if (!located) throw new Error(`unknown subagent: ${childId}; message was not delivered`);
+		this.assertContinuableDirectChild(parent, located.descriptor);
+		const manager = SessionManager.open(
+			located.sessionFile,
+			parent.sessionManager.getSessionDir(),
+			parent.cwd,
+		);
+		if (signal?.aborted) throw abortReason(signal);
+		const enqueued = enqueueMailboxMessage(manager, {
+			senderAgentId: parent.agentId,
+			recipientAgentId: childId,
+			content: message,
+		});
+		return {
+			kind: "mailbox",
+			agentId: childId,
+			taskPath: descriptorTaskPath(located.descriptor),
+			messageId: enqueued.message.messageId,
+			pendingMessages: enqueued.pendingMessages,
+		};
+	}
 
-		if (!activation) {
+	async followupTask(
+		parent: ParentRef,
+		childId: string,
+		signal?: AbortSignal,
+	): Promise<FollowupTaskOutcome> {
+		return this.runAdmittedOperation(() =>
+			this.followupTaskAdmitted(parent, childId, signal),
+		);
+	}
+
+	private async followupTaskAdmitted(
+		parent: ParentRef,
+		childId: string,
+		signal?: AbortSignal,
+	): Promise<FollowupTaskOutcome> {
+		if (this.draining) {
+			throw new Error("pi-subagent is shutting down; follow-up task was not started");
+		}
+		const target = await this.resolveTarget(parent, childId);
+		const pending = await this.agentOperations.run(target.agentId, () =>
+			this.followupTaskSerialized(parent, target.agentId, signal),
+		);
+		try {
+			await pending.accepted;
+		} catch (error) {
+			if (pending.coldPrepared && !pending.activation.published) {
+				await this.agentOperations.run(target.agentId, async () => {
+					if (this.active.get(target.agentId) !== pending.activation) return;
+					pending.activation.suppressSettlement = true;
+					await this.rollbackActivation(
+						pending.activation,
+						pending.coldPrepared!,
+					);
+				});
+			}
+			throw error;
+		}
+		return pending.outcome;
+	}
+
+	private async followupTaskSerialized(
+		parent: ParentRef,
+		childId: string,
+		signal?: AbortSignal,
+	): Promise<PendingFollowupStart> {
+		if (this.draining) {
+			throw new Error("pi-subagent is shutting down; follow-up task was not started");
+		}
+		if (signal?.aborted) throw abortReason(signal);
+		let activation = this.active.get(childId);
+		if (activation?.disposed) activation = undefined;
+		let descriptor: SubagentDescriptor;
+		let manager: SessionManager;
+		let coldPrepared: PreparedChildSession | undefined;
+
+		if (activation) {
+			this.touchActivation(activation);
+			descriptor = activation.descriptor;
+			this.assertContinuableDirectChild(parent, descriptor);
+			manager = activation.runtime.session.sessionManager;
+			if (activation.currentRun || activation.runtime.session.isStreaming) {
+				throw new Error(
+					`subagent ${childId} already has a scheduled or running turn; mailbox messages were not consumed`,
+				);
+			}
+		} else {
 			const located = await this.findPersistedChild(parent, childId);
-			if (!located) throw new Error(`unknown subagent: ${childId}; message was not delivered`);
-			if (located.descriptor.mode !== "continuable") {
-				throw new Error(`subagent ${childId} is one-shot and cannot accept follow-up messages`);
+			if (!located) {
+				throw new Error(`unknown subagent: ${childId}; follow-up task was not started`);
 			}
-			this.assertDirectParent(parent, located.descriptor);
-			const manager = SessionManager.open(
+			descriptor = located.descriptor;
+			this.assertContinuableDirectChild(parent, descriptor);
+			manager = SessionManager.open(
 				located.sessionFile,
 				parent.sessionManager.getSessionDir(),
 				parent.cwd,
 			);
+		}
+		const owner = mailboxOwner(descriptor);
+		const batch = readMailbox(manager.getEntries(), owner).pending;
+		if (batch.length === 0) {
+			throw new Error(`subagent ${childId} has no pending mailbox messages`);
+		}
+		const messageIds = batch.map((message) => message.messageId);
+
+		if (!activation) {
 			coldPrepared = {
 				sessionManager: manager,
 				seedMessageCount: manager.buildSessionContext().messages.length,
@@ -541,25 +1065,42 @@ export class SubagentCoordinator {
 			};
 			activation = await this.createActivation({
 				parent,
-				descriptor: located.descriptor,
+				descriptor,
 				prepared: coldPrepared,
 				isNew: false,
 			});
-			if (parent.activation) parent.activation.ownedChildren.add(activation.agentId);
-		} else {
-			this.assertDirectParent(parent, activation.descriptor);
-		}
-
-		const session = activation.runtime.session;
-		if (activation.currentRun || session.isStreaming) {
-			if (signal?.aborted) throw signal.reason ?? new Error("message delivery aborted");
-			await session.followUp(message);
-			return;
+			this.acquireParentOwnership(activation, parent);
 		}
 
 		try {
-			const started = this.startPrompt(activation, message, signal, true);
-			await started.accepted;
+			this.acquireParentOwnership(activation, parent);
+			const started = this.startPrompt(activation, "", signal, {
+				detachAtAcceptance: true,
+				waitForCapacity: !parent.activation?.holdsBackgroundSlot,
+				preparePrompt: (turnId) =>
+					formatMailboxBatch(batch, turnId),
+				onPromptAccepted: (turnId) => {
+					claimMailboxMessages(
+						manager,
+						messageIds,
+						turnId,
+						owner,
+					);
+					activation.pendingMailboxClaims.add(turnId);
+				},
+				acceptAfterUserMessage: true,
+			});
+			return {
+				activation,
+				accepted: started.accepted,
+				...(coldPrepared ? { coldPrepared } : {}),
+				outcome: {
+					agentId: childId,
+					taskPath: descriptorTaskPath(descriptor),
+					turnId: started.turnId,
+					claimedMessages: batch.length,
+				},
+			};
 		} catch (error) {
 			if (coldPrepared && !activation.published) {
 				activation.suppressSettlement = true;
@@ -569,49 +1110,449 @@ export class SubagentCoordinator {
 		}
 	}
 
-	async interrupt(parent: ParentRef, targetId: string): Promise<void> {
-		const target = this.active.get(targetId);
-		if (!target) return;
-		if (!(await this.isDescendantOf(parent, target.descriptor))) {
-			throw new Error(`subagent ${targetId} is not a live descendant of ${parent.agentId}`);
-		}
-		target.status = "failed";
-		void target.runtime.session.abort().catch((error) => {
-			target.lastError = errorText(error);
+	async waitAgent(
+		parent: ParentRef,
+		toolCallId: string,
+		timeoutMs?: number,
+		signal?: AbortSignal,
+	): Promise<WaitAgentOutcome> {
+		return this.runAdmittedOperation(async () => {
+			const outcome = await this.waitAgentAdmitted(
+				parent,
+				toolCallId,
+				waitTimeout(timeoutMs),
+				signal,
+			);
+			if (outcome.updates.length === 0) {
+				return { ...outcome, taskPaths: {} };
+			}
+			let paths = new Map<string, string>();
+			try {
+				const catalog = await this.catalogRecords(parent);
+				paths = new Map(
+					catalog.records.map((record) => [
+						record.agentId,
+						record.taskPath,
+					]),
+				);
+			} catch {
+				// Completion delivery is already durably reserved. Readable
+				// path enrichment is cosmetic and must not turn that delivery
+				// into a failed tool call.
+			}
+			return {
+				...outcome,
+				taskPaths: Object.fromEntries(
+					outcome.updates.map((update) => [
+						update.childAgentId,
+						paths.get(update.childAgentId)
+							?? update.childAgentId,
+					]),
+				),
+			};
 		});
 	}
 
-	async list(parent: ParentRef, scope: "children" | "descendants"): Promise<CatalogEntry[]> {
-		const catalog = await this.catalogRecords(parent);
-		const records = catalog.records;
-		const byId = new Map(records.map((record) => [record.agentId, record]));
-		const children: CatalogChild[] = [];
-		for (const record of records) {
-			if (record.descriptor.mode !== "continuable") continue;
-			const distance = this.distanceFrom(parent.agentId, record.descriptor, byId);
-			if (distance === undefined || (scope === "children" && distance !== 1)) continue;
-			children.push({
-				kind: "child",
-				agentId: record.agentId,
-				parentAgentId: record.descriptor.parentAgentId,
-				depth: distance,
-				descriptor: record.descriptor,
-				...(record.sessionFile ? { sessionFile: record.sessionFile } : {}),
-				status: record.active
-					? record.active.currentRun || record.active.runtime.session.isStreaming
-						? "running"
-						: "idle"
-					: "ready",
-			});
+	private async waitAgentAdmitted(
+		parent: ParentRef,
+		toolCallId: string,
+		timeoutMs: number,
+		signal?: AbortSignal,
+	): Promise<WaitAgentOutcome> {
+		if (this.draining) {
+			throw new Error("pi-subagent is shutting down; wait_agent was not accepted");
 		}
-		children.sort(
-			(left, right) =>
-				left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) ||
-				left.agentId.localeCompare(right.agentId),
-		);
-		const parentFile = parent.sessionManager.getSessionFile();
-		const diagnostics = parentFile
-			? catalog.diagnostics.filter(
+		if (signal?.aborted) throw abortReason(signal);
+		if (!toolCallId.trim() || toolCallId.length > 512) {
+			throw new Error("wait_agent requires a non-empty tool call id of at most 512 characters");
+		}
+		const key = completionWaiterKey(parent);
+		const deadline = Date.now() + timeoutMs;
+		while (true) {
+			let waiter: CompletionWaiter | undefined;
+			const immediate = await this.completionOperations.run(
+				key,
+				async (): Promise<WaitAgentOutcome | undefined> => {
+					if (this.draining) {
+						throw new Error("pi-subagent is shutting down; wait_agent was interrupted");
+					}
+					if (signal?.aborted) throw abortReason(signal);
+					if (this.completionWaiters.has(key)) {
+						throw new Error(
+							`wait_agent is already waiting for direct-child activity on ${parent.agentId}`,
+						);
+					}
+					const snapshot = readCompletionMailbox(
+						parent.sessionManager.getEntries(),
+						{
+							parentAgentId: parent.agentId,
+							activeRuntimeId: this.runtimeId,
+						},
+					);
+					if (snapshot.currentRuntimeReservations.length > 0) {
+						throw new Error(
+							"a previous wait_agent delivery is awaiting its durable tool result",
+						);
+					}
+					if (snapshot.available.length > 0) {
+						return this.reserveWaitAgentOutcome(
+							parent,
+							toolCallId,
+							timeoutMs,
+							snapshot,
+						);
+					}
+					const remaining = Math.max(0, deadline - Date.now());
+					if (remaining === 0) {
+						return {
+							timedOut: true,
+							timeoutMs,
+							updates: [],
+							unreadUpdates: snapshot.unread.length,
+							taskPaths: {},
+						};
+					}
+					waiter = this.createCompletionWaiter(remaining, signal);
+					this.completionWaiters.set(key, waiter);
+
+					// Append happens before notify, but fold once more after
+					// subscription so no completion can land in the check/register gap.
+					const rechecked = readCompletionMailbox(
+						parent.sessionManager.getEntries(),
+						{
+							parentAgentId: parent.agentId,
+							activeRuntimeId: this.runtimeId,
+						},
+					);
+					if (rechecked.available.length > 0) {
+						try {
+							return this.reserveWaitAgentOutcome(
+								parent,
+								toolCallId,
+								timeoutMs,
+								rechecked,
+							);
+						} finally {
+							this.removeCompletionWaiter(key, waiter);
+							waiter = undefined;
+						}
+					}
+					return undefined;
+				},
+			);
+			if (immediate) return immediate;
+			if (!waiter) {
+				throw new Error("wait_agent failed to establish an activity subscription");
+			}
+			let activity: "activity" | "timeout";
+			try {
+				activity = await waiter.promise;
+			} catch (error) {
+				this.removeCompletionWaiter(key, waiter);
+				throw error;
+			}
+			const afterWake = await this.completionOperations.run(
+				key,
+				async (): Promise<WaitAgentOutcome | undefined> => {
+					try {
+						if (this.draining) {
+							throw new Error(
+								"pi-subagent is shutting down; wait_agent was interrupted",
+							);
+						}
+						if (signal?.aborted) throw abortReason(signal);
+						if (this.completionWaiters.get(key) !== waiter) {
+							throw new Error(
+								"wait_agent lost ownership of its activity subscription",
+							);
+						}
+						const snapshot = readCompletionMailbox(
+							parent.sessionManager.getEntries(),
+							{
+								parentAgentId: parent.agentId,
+								activeRuntimeId: this.runtimeId,
+							},
+						);
+						if (snapshot.currentRuntimeReservations.length > 0) {
+							throw new Error(
+								"a previous wait_agent delivery is awaiting its durable tool result",
+							);
+						}
+						if (snapshot.available.length > 0) {
+							return this.reserveWaitAgentOutcome(
+								parent,
+								toolCallId,
+								timeoutMs,
+								snapshot,
+							);
+						}
+						if (activity === "timeout" || Date.now() >= deadline) {
+							return {
+								timedOut: true,
+								timeoutMs,
+								updates: [],
+								unreadUpdates: snapshot.unread.length,
+								taskPaths: {},
+							};
+						}
+						return undefined;
+					} finally {
+						this.removeCompletionWaiter(key, waiter!);
+					}
+				},
+			);
+			if (afterWake) return afterWake;
+		}
+	}
+
+	private reserveWaitAgentOutcome(
+		parent: ParentRef,
+		toolCallId: string,
+		timeoutMs: number,
+		snapshot: ReturnType<typeof readCompletionMailbox>,
+	): WaitAgentOutcome {
+		const updates = this.boundedWaitAgentUpdates(snapshot.available);
+		reserveCompletionDelivery(parent.sessionManager, {
+			parentAgentId: parent.agentId,
+			runtimeId: this.runtimeId,
+			toolCallId,
+			completionIds: updates.map((update) => update.completionId),
+		});
+		return {
+			timedOut: false,
+			timeoutMs,
+			updates,
+			unreadUpdates: Math.max(
+				0,
+				snapshot.unread.length - updates.length,
+			),
+			taskPaths: {},
+		};
+	}
+
+	private boundedWaitAgentUpdates(
+		available: readonly CompletionUpdate[],
+	): CompletionUpdate[] {
+		const updates: CompletionUpdate[] = [];
+		let remainingBytes = MAX_WAIT_AGENT_RESULT_BYTES;
+		for (const update of available) {
+			if (updates.length >= MAX_COMPLETIONS_PER_DELIVERY) break;
+			const metadataBytes = Buffer.byteLength(
+				`completion ${update.completionId}\nchild=${update.childAgentId} turn=${update.turnId} stop=${update.stopReason}\n`,
+				"utf8",
+			) + 256;
+			const fullBytes =
+				metadataBytes + Buffer.byteLength(update.output, "utf8");
+			if (updates.length > 0 && fullBytes > remainingBytes) break;
+			const outputBudget = Math.max(0, remainingBytes - metadataBytes);
+			const truncated = truncateUtf8(update.output, outputBudget);
+			updates.push({
+				...update,
+				output: truncated.text,
+				...(truncated.truncated || update.outputTruncated
+					? {
+							outputTruncated: true,
+							omittedBytes:
+								(update.omittedBytes ?? 0)
+								+ truncated.omittedBytes,
+						}
+					: {}),
+			});
+			remainingBytes = Math.max(
+				0,
+				remainingBytes
+					- metadataBytes
+					- Buffer.byteLength(truncated.text, "utf8"),
+			);
+			if (truncated.truncated) break;
+		}
+		return updates;
+	}
+
+	async releaseWaitAgentDeliveries(
+		parent: ParentRef,
+		reason: string,
+	): Promise<number> {
+		const key = completionWaiterKey(parent);
+		return this.completionOperations.run(key, async () =>
+			releaseCompletionDeliveries(parent.sessionManager, {
+				parentAgentId: parent.agentId,
+				runtimeId: this.runtimeId,
+				reason,
+			}),
+		);
+	}
+
+	private createCompletionWaiter(
+		timeoutMs: number,
+		signal?: AbortSignal,
+	): CompletionWaiter {
+		let settled = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let resolvePromise!: (activity: "activity" | "timeout") => void;
+		let rejectPromise!: (error: Error) => void;
+		const promise = new Promise<"activity" | "timeout">(
+			(resolve, reject) => {
+				resolvePromise = resolve;
+				rejectPromise = reject;
+			},
+		);
+		const onAbort = () => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			rejectPromise(abortReason(signal!));
+		};
+		if (signal) signal.addEventListener("abort", onAbort, { once: true });
+		timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolvePromise("timeout");
+		}, timeoutMs);
+		// An awaited tool deadline must keep headless SDK processes alive.
+		// Wake, abort and shutdown clear it rather than leaving a background timer.
+		const dispose = () => {
+			if (timer) clearTimeout(timer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+		};
+		return {
+			promise,
+			wake: () => {
+				if (settled) return;
+				settled = true;
+				dispose();
+				resolvePromise("activity");
+			},
+			reject: (error) => {
+				if (settled) return;
+				settled = true;
+				dispose();
+				rejectPromise(error);
+			},
+			dispose,
+		};
+	}
+
+	private removeCompletionWaiter(
+		key: string,
+		waiter: CompletionWaiter,
+	): void {
+		if (this.completionWaiters.get(key) === waiter) {
+			this.completionWaiters.delete(key);
+		}
+		waiter.dispose();
+	}
+
+	async interrupt(parent: ParentRef, targetId: string): Promise<void> {
+		await this.interruptWithOutcome(parent, targetId);
+	}
+
+	async interruptWithOutcome(
+		parent: ParentRef,
+		targetId: string,
+	): Promise<InterruptOutcome> {
+		return this.runAdmittedOperation(() =>
+			this.interruptAdmitted(parent, targetId),
+		);
+	}
+
+	private async interruptAdmitted(
+		parent: ParentRef,
+		targetId: string,
+	): Promise<InterruptOutcome> {
+		const resolved = await this.resolveTarget(parent, targetId, {
+			allowUnknownId: true,
+		});
+		return this.agentOperations.run(resolved.agentId, async () => {
+			if (
+				resolved.record
+				&& !(await this.isDescendantOf(
+					parent,
+					resolved.record.descriptor,
+				))
+			) {
+				throw new Error(
+					`subagent ${resolved.taskPath} is not a descendant of ${parent.taskPath}`,
+				);
+			}
+			const target = this.active.get(resolved.agentId);
+			if (!target) {
+				return {
+					agentId: resolved.agentId,
+					taskPath: resolved.taskPath,
+					active: false,
+				};
+			}
+			if (!(await this.isDescendantOf(parent, target.descriptor))) {
+				throw new Error(
+					`subagent ${resolved.taskPath} is not a live descendant of ${parent.taskPath}`,
+				);
+			}
+			this.touchActivation(target);
+			interruptAgentTurn(target.controlState);
+			this.emitUpdate(target);
+			target.turnAbortController?.abort(
+				new Error(`subagent ${resolved.taskPath} was interrupted`),
+			);
+			void target.runtime.session.abort().catch((error) => {
+				target.lastError = errorText(error);
+			});
+			return {
+				agentId: resolved.agentId,
+				taskPath: descriptorTaskPath(target.descriptor),
+				active: true,
+			};
+		});
+	}
+
+	async list(parent: ParentRef, scope: "children" | "descendants"): Promise<CatalogEntry[]> {
+		return this.runAdmittedOperation(() => this.listAdmitted(parent, scope));
+	}
+
+	private async listAdmitted(
+		parent: ParentRef,
+		scope: "children" | "descendants",
+	): Promise<CatalogEntry[]> {
+		const catalog = await this.catalogRecords(parent);
+		const records = catalog.records;
+		const byId = new Map(records.map((record) => [record.agentId, record]));
+		const children: CatalogChild[] = [];
+		for (const record of records) {
+			if (record.descriptor.mode !== "continuable") continue;
+			const distance = this.distanceFrom(parent.agentId, record.descriptor, byId);
+			if (distance === undefined || (scope === "children" && distance !== 1)) continue;
+			children.push({
+				kind: "child",
+				agentId: record.agentId,
+				parentAgentId: record.descriptor.parentAgentId,
+				taskPath: record.taskPath,
+				parentTaskPath:
+					record.descriptor.parentAgentId === parent.agentId
+						? parent.taskPath
+						: (byId.get(record.descriptor.parentAgentId)?.taskPath
+							?? record.descriptor.parentAgentId),
+				depth: distance,
+				descriptor: record.descriptor,
+				...(record.sessionFile ? { sessionFile: record.sessionFile } : {}),
+				status: record.active ? catalogStatus(record.active.controlState) : "ready",
+				pendingMessages: record.pendingMessages,
+				unreadUpdates:
+					record.descriptor.parentAgentId === parent.agentId
+						? (catalog.rootUnreadUpdatesByChild.get(record.agentId) ?? 0)
+						: (byId
+								.get(record.descriptor.parentAgentId)
+								?.unreadUpdatesByChild.get(record.agentId) ?? 0),
+			});
+		}
+		children.sort(
+			(left, right) =>
+				left.descriptor.createdAt.localeCompare(right.descriptor.createdAt) ||
+				left.agentId.localeCompare(right.agentId),
+		);
+		const parentFile = parent.sessionManager.getSessionFile();
+		const diagnostics = parentFile
+			? catalog.diagnostics.filter(
 					(entry) => entry.kind === "diagnostic" && entry.parentSessionFile === parentFile,
 				)
 			: [];
@@ -619,50 +1560,115 @@ export class SubagentCoordinator {
 	}
 
 	async report(child: Activation, output: string): Promise<void> {
+		return this.runAdmittedOperation(() => this.reportAdmitted(child, output));
+	}
+
+	private async reportAdmitted(child: Activation, output: string): Promise<void> {
 		if (child.descriptor.mode !== "continuable") {
 			throw new Error("report is available only to continuable subagents");
 		}
 		const truncated = truncateUtf8(output, child.descriptor.runtime.maxOutputBytes);
-		const content = `Background subagent ${child.agentId} reported:\n\n${truncated.text}${
+		const readablePath = descriptorTaskPath(child.descriptor);
+		const content = `Background subagent ${readablePath} (${child.agentId}) reported:\n\n${truncated.text}${
 			truncated.truncated ? `\n\n[Report truncated; ${truncated.omittedBytes} bytes omitted.]` : ""
 		}`;
-		await child.parent.deliver(
-			REPORT_CUSTOM_TYPE,
-			content,
-			{
-				kind: "report",
-				childAgentId: child.agentId,
-				label: child.descriptor.label,
-				...(truncated.truncated ? { truncated: true } : {}),
-			},
-			child.descriptor.runtime.reportDelivery,
-		);
+		await child.parent.deliver(REPORT_CUSTOM_TYPE, content, {
+			kind: "report",
+			childAgentId: child.agentId,
+			taskPath: readablePath,
+			label: child.descriptor.label,
+			...(truncated.truncated ? { truncated: true } : {}),
+		});
+	}
+
+	private runAdmittedOperation<T>(operation: () => Promise<T>): Promise<T> {
+		if (this.draining) {
+			return Promise.reject(new Error("pi-subagent is shutting down"));
+		}
+		const promise = operation();
+		this.admittedOperations.add(promise);
+		const remove = () => {
+			this.admittedOperations.delete(promise);
+		};
+		void promise.then(remove, remove);
+		return promise;
+	}
+
+	private async waitForAdmittedOperations(): Promise<void> {
+		while (this.admittedOperations.size > 0) {
+			await Promise.allSettled([...this.admittedOperations]);
+		}
 	}
 
 	async shutdown(): Promise<void> {
-		if (this.draining) return;
+		if (this.shutdownPromise) return this.shutdownPromise;
 		this.draining = true;
+		this.rejectCompletionWaiters(
+			new Error("pi-subagent is shutting down"),
+		);
+		this.shutdownPromise = this.performShutdown();
+		return this.shutdownPromise;
+	}
+
+	private async performShutdown(): Promise<void> {
+		this.backgroundRuns.close();
+		await this.abortActiveRuns();
+		await this.agentOperations.waitForIdle();
+		await this.idleRuntimeOperations.waitForIdle();
+		await this.completionOperations.waitForIdle();
+		await this.abortActiveRuns();
+		await this.waitForAdmittedOperations();
+		await this.agentOperations.waitForIdle();
+		await this.abortActiveRuns();
 		const activations = [...this.active.values()];
-		for (const activation of activations) activation.suppressSettlement = true;
 		await Promise.allSettled(
-			activations.map(async (activation) => {
-				if (!activation.runtime.session.isIdle) await activation.runtime.session.abort();
-			}),
+			activations
+				.map((activation) => activation.currentRun)
+				.filter(
+					(run): run is Promise<SubagentRunResult> => run !== undefined,
+				),
 		);
 		for (const activation of activations.sort((left, right) => right.descriptor.depth - left.descriptor.depth)) {
 			await this.disposeActivation(activation).catch(() => {});
 		}
+		await this.agentOperations.waitForIdle();
+		await this.idleRuntimeOperations.waitForIdle();
+		await this.completionOperations.waitForIdle();
+	}
+
+	private rejectCompletionWaiters(error: Error): void {
+		for (const [key, waiter] of this.completionWaiters) {
+			this.completionWaiters.delete(key);
+			waiter.reject(error);
+			waiter.dispose();
+		}
+	}
+
+	private async abortActiveRuns(): Promise<void> {
+		const activations = [...this.active.values()];
+		for (const activation of activations) {
+			activation.suppressSettlement = true;
+			activation.turnAbortController?.abort(
+				new Error("pi-subagent is shutting down"),
+			);
+		}
+		await Promise.allSettled(
+			activations.map(async (activation) => {
+				if (!activation.runtime.session.isIdle) {
+					await activation.runtime.session.abort();
+				}
+			}),
+		);
 	}
 
 	createChildToolDefinitions(
 		getActivation: () => Activation,
-		enableRunInBackground = true,
-		defaultBackground = true,
+		runtimeMode: RuntimeMode = "background",
 		agentDiscovery?: AgentDiscoveryResult,
 	): ToolDefinition[] {
 		const agentNames = agentDiscovery?.agents.map((agent) => agent.name);
 		const assertBackgroundControlEnabled = (toolName: string): void => {
-			if (!enableRunInBackground) {
+			if (runtimeMode === "foreground") {
 				throw new Error(`tool "${toolName}" is unavailable in foreground-only mode`);
 			}
 		};
@@ -678,13 +1684,11 @@ export class SubagentCoordinator {
 			name: "subagent",
 			label: "Subagent",
 			description:
-				"Delegate a standalone task to a fresh child in an isolated session. " +
-				(!enableRunInBackground
+				"Delegate a standalone task to a named child path, with optional completed-turn context inheritance. " +
+				(runtimeMode === "foreground"
 					? "This foreground-only instance always waits for the result."
-					: defaultBackground
-						? "It runs in the background by default and returns a durable id."
-						: "It waits for the result by default; background mode returns a durable id."),
-			parameters: delegationParameters(enableRunInBackground, agentNames),
+					: "It returns a readable path plus durable id; use send_message, followup_task, and wait_agent to continue it."),
+			parameters: delegationParameters(agentNames),
 			execute: async (_id, params, signal, onUpdate) => {
 				const activation = getActivation();
 				const outcome = await this.delegate(
@@ -704,7 +1708,10 @@ export class SubagentCoordinator {
 			name: "subagent_fork",
 			label: "Subagent Fork",
 			description:
-				"Delegate a one-shot task to a child seeded with completed turns from this conversation.",
+				"Delegate a task to a child seeded with all completed turns from this conversation. " +
+				(runtimeMode === "foreground"
+					? "This foreground-only instance always waits for the result."
+					: "It returns a readable path plus durable id and can be continued through its mailbox."),
 			parameters: forkDelegationParameters(agentNames),
 			execute: async (_id, params, signal, onUpdate) => {
 				const activation = getActivation();
@@ -725,12 +1732,12 @@ export class SubagentCoordinator {
 			name: "send_message",
 			label: "Send Message",
 			description:
-				"Queue a message as a direct continuable child's next FIFO turn. This returns acceptance, not the child's answer.",
+				"Durably append a message to a direct continuable child's FIFO mailbox without starting or resuming it. Use followup_task to start the queued batch. This returns acceptance, not the child's answer.",
 			parameters: SendMessageParameters,
 			execute: async (_id, params, signal) => {
 				assertBackgroundControlEnabled("send_message");
 				const activation = getActivation();
-				await this.sendMessage(
+				const delivery = await this.sendMessageWithOutcome(
 					this.parentForActivation(activation),
 					params.subagent_id,
 					params.message,
@@ -740,10 +1747,92 @@ export class SubagentCoordinator {
 					content: [
 						{
 							type: "text",
-							text: `message queued as the next turn for subagent ${params.subagent_id}`,
+							text:
+								delivery.kind === "mailbox"
+									? `message ${delivery.messageId} durably enqueued for ${delivery.taskPath}; ${delivery.pendingMessages} pending`
+									: `message queued as the next turn for ${delivery.taskPath}`,
 						},
 					],
-					details: { kind: "control", action: "send", agentId: params.subagent_id } satisfies ControlDetails,
+					details: {
+						kind: "control",
+						action: "send",
+						agentId: delivery.agentId,
+						taskPath: delivery.taskPath,
+						...(delivery.kind === "mailbox"
+							? {
+									messageId: delivery.messageId,
+									pendingMessages: delivery.pendingMessages,
+								}
+							: {}),
+					} satisfies ControlDetails,
+				};
+			},
+		});
+
+		const followup = defineTool({
+			name: "followup_task",
+			label: "Follow-up Task",
+			description:
+				"Start exactly one scheduled turn for a direct child, atomically claiming its current pending FIFO mailbox batch.",
+			parameters: FollowupTaskParameters,
+			execute: async (_id, params, signal) => {
+				assertBackgroundControlEnabled("followup_task");
+				const activation = getActivation();
+				const outcome = await this.followupTask(
+					this.parentForActivation(activation),
+					params.subagent_id,
+					signal,
+				);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `started turn ${outcome.turnId} for ${outcome.taskPath}, claiming ${outcome.claimedMessages} mailbox message${outcome.claimedMessages === 1 ? "" : "s"}`,
+						},
+					],
+					details: {
+						kind: "control",
+						action: "followup",
+						agentId: outcome.agentId,
+						taskPath: outcome.taskPath,
+						turnId: outcome.turnId,
+						claimedMessages: outcome.claimedMessages,
+					} satisfies ControlDetails,
+				};
+			},
+		});
+
+		const wait = defineTool({
+			name: "wait_agent",
+			label: "Wait Agent",
+			description:
+				"Wait event-driven for unread completion updates from direct children. This does not start a child or occupy a background scheduler slot.",
+			parameters: WaitAgentParameters,
+			execute: async (id, params, signal) => {
+				assertBackgroundControlEnabled("wait_agent");
+				const activation = getActivation();
+				const outcome = await this.waitAgent(
+					this.parentForActivation(activation),
+					id,
+					params.timeout_ms,
+					signal,
+				);
+				return {
+					content: [
+						{
+							type: "text",
+							text: this.formatWaitAgentOutcome(outcome),
+						},
+					],
+					details: {
+						kind: "control",
+						action: "wait",
+						timedOut: outcome.timedOut,
+						completionIds: outcome.updates.map(
+							(update) => update.completionId,
+						),
+						unreadUpdates: outcome.unreadUpdates,
+					} satisfies ControlDetails,
 				};
 			},
 		});
@@ -757,10 +1846,18 @@ export class SubagentCoordinator {
 			execute: async (_id, params) => {
 				assertBackgroundControlEnabled("interrupt_agent");
 				const activation = getActivation();
-				await this.interrupt(this.parentForActivation(activation), params.agent_id);
+				const outcome = await this.interruptWithOutcome(
+					this.parentForActivation(activation),
+					params.agent_id,
+				);
 				return {
-					content: [{ type: "text", text: `interrupt requested for agent ${params.agent_id}` }],
-					details: { kind: "control", action: "interrupt", agentId: params.agent_id } satisfies ControlDetails,
+					content: [{ type: "text", text: `interrupt requested for ${outcome.taskPath}` }],
+					details: {
+						kind: "control",
+						action: "interrupt",
+						agentId: outcome.agentId,
+						taskPath: outcome.taskPath,
+					} satisfies ControlDetails,
 				};
 			},
 		});
@@ -769,7 +1866,7 @@ export class SubagentCoordinator {
 			name: "list_agents",
 			label: "List Agents",
 			description:
-				"List direct continuable children or all descendants as running, idle, or ready (persisted and resumable).",
+				"List direct continuable children or all descendants as running, idle, or ready, with separate mailbox task and completion counts.",
 			parameters: ListAgentsParameters,
 			execute: async (_id, params) => {
 				assertBackgroundControlEnabled("list_agents");
@@ -796,18 +1893,28 @@ export class SubagentCoordinator {
 				await this.report(activation, params.output);
 				return {
 					content: [{ type: "text", text: `report accepted by the agent that started you` }],
-					details: { kind: "control", action: "report", agentId: activation.agentId } satisfies ControlDetails,
+				details: {
+					kind: "control",
+					action: "report",
+					agentId: activation.agentId,
+					taskPath: descriptorTaskPath(activation.descriptor),
+				} satisfies ControlDetails,
 				};
 			},
 		});
 
-		return [spawn, fork, send, interrupt, list, report];
+		return [spawn, fork, send, followup, wait, interrupt, list, report];
 	}
 
 	outcomeToolResult(outcome: DelegationOutcome): AgentToolResult<DelegationDetails> {
 		if (outcome.kind === "continuable") {
 			return {
-				content: [{ type: "text", text: `started subagent ${outcome.details.agentId}` }],
+				content: [
+					{
+						type: "text",
+						text: `started subagent ${outcome.details.taskPath} (${outcome.details.agentId})`,
+					},
+				],
 				details: outcome.details,
 			};
 		}
@@ -834,12 +1941,49 @@ export class SubagentCoordinator {
 					return `${entry.piSessionId} [diagnostic: ${entry.reason}]`;
 				}
 				const location =
-					scope === "descendants" ? ` parent=${entry.parentAgentId} depth=${entry.depth}` : "";
-				return `${entry.agentId} [${entry.status}]${location} — ${entry.descriptor.label} (${entry.descriptor.agent.name})`;
+					scope === "descendants"
+						? ` parent=${entry.parentTaskPath} depth=${entry.depth}`
+						: "";
+				const mailbox = ` pending=${entry.pendingMessages} updates=${entry.unreadUpdates}`;
+				return `${entry.taskPath} [${entry.status}]${mailbox}${location} — ${entry.descriptor.label} (${entry.descriptor.agent.name}) id=${entry.agentId}`;
 			})
 			.join("\n");
 	}
 
+	formatWaitAgentOutcome(outcome: WaitAgentOutcome): string {
+		if (outcome.timedOut) {
+			return `wait_agent timed out after ${outcome.timeoutMs}ms with no completion updates`;
+		}
+		const updates = outcome.updates.map((update) => {
+			const output = update.output.trim() || "(no output)";
+			const fullPath =
+				outcome.taskPaths[update.childAgentId]
+				?? update.childAgentId;
+			const readablePath =
+				fullPath.length > 200
+					? `${fullPath.slice(0, 199)}…`
+					: fullPath;
+			const truncation = update.outputTruncated
+				? `\n[Completion output truncated${
+						update.omittedBytes !== undefined
+							? `; ${update.omittedBytes} bytes omitted`
+							: ""
+					}.]`
+				: "";
+			return [
+				`completion ${update.completionId}`,
+				`child=${readablePath} id=${update.childAgentId} turn=${update.turnId} stop=${update.stopReason}`,
+				`${output}${truncation}`,
+			].join("\n");
+		});
+		if (outcome.unreadUpdates > 0) {
+			updates.push(
+				`${outcome.unreadUpdates} additional completion update${outcome.unreadUpdates === 1 ? "" : "s"} remain unread`,
+			);
+		}
+		return updates.join("\n\n");
+	}
+
 	private resolveModel(parent: ParentRef, agent: AgentDefinition): Model<any> {
 		if (!agent.model) {
 			if (!parent.model) throw new Error("no parent model is selected for the subagent");
@@ -878,8 +2022,7 @@ export class SubagentCoordinator {
 				if (!activation) throw new Error("subagent activation is not published yet");
 				return activation;
 			},
-			descriptor.runtime.enableRunInBackground,
-			descriptor.runtime.defaultBackground,
+			descriptor.runtime.runtimeMode,
 			agentDiscovery,
 		);
 		const model =
@@ -996,8 +2139,8 @@ export class SubagentCoordinator {
 						return false;
 					}
 					if (
-						!descriptor.runtime.enableRunInBackground &&
-						BACKGROUND_CONTROL_TOOLS.has(tool)
+						descriptor.runtime.runtimeMode === "foreground"
+						&& BACKGROUND_CONTROL_TOOLS.has(tool)
 					) {
 						return false;
 					}
@@ -1045,17 +2188,32 @@ export class SubagentCoordinator {
 				runtime,
 				seedMessageCount: options.prepared.seedMessageCount,
 				epochMessageStart: runtime.session.messages.length,
-				status: "starting",
+				controlState: createAgentControlState(),
 				trace: [],
 				streamedText: "",
 				usage: emptyUsage(),
+				startedTurnIds: new Set(),
+				silentSettlementTurnIds: new Set(),
+				pendingMailboxClaims: new Set(),
+				userMessageGates: new Map(),
 				ownedChildren: new Set(),
 				onUpdate: options.onUpdate,
 				published: false,
+				everPublished: false,
 				suppressSettlement: false,
 				finalizing: false,
+				holdsBackgroundSlot: false,
+				persistenceGate: createPersistenceGate(
+					runtime.session.sessionManager,
+					options.isNew,
+				),
+				lastUsedSequence: ++this.activationSequence,
 				disposed: false,
 			};
+			const existing = this.active.get(activation.agentId);
+			if (existing && !existing.disposed) {
+				throw new Error(`subagent ${activation.agentId} already has a resident runtime`);
+			}
 			activation.unsubscribe = runtime.session.subscribe((event) => this.observe(activation!, event));
 			this.active.set(activation.agentId, activation);
 			return activation;
@@ -1065,16 +2223,33 @@ export class SubagentCoordinator {
 		}
 	}
 
+	private async acquireBackgroundRun(
+		activation: Activation,
+		signal: AbortSignal | undefined,
+		waitForCapacity: boolean,
+	): Promise<BackgroundRunPermit | undefined> {
+		if (activation.descriptor.mode !== "continuable") return undefined;
+		const permit = await this.backgroundRuns.acquire({
+			...(signal ? { signal } : {}),
+			waitForCapacity,
+		});
+		activation.holdsBackgroundSlot = true;
+		return permit;
+	}
+
 	private startPrompt(
 		activation: Activation,
 		prompt: string,
 		signal: AbortSignal | undefined,
-		detachAtAcceptance: boolean,
-	): { accepted: Promise<void>; result: Promise<SubagentRunResult> } {
+		options: StartPromptOptions,
+	): { turnId: string; accepted: Promise<void>; result: Promise<SubagentRunResult> } {
 		if (activation.currentRun) throw new Error(`subagent ${activation.agentId} is already running`);
 		if (signal?.aborted) throw signal.reason ?? new Error("subagent start aborted");
+		this.touchActivation(activation);
 		activation.pendingSettlement = undefined;
-		activation.status = "running";
+		this.resetTurnCapture(activation);
+		const turnId = uuidv7();
+		queueAgentTurn(activation.controlState, turnId);
 		this.emitUpdate(activation);
 
 		let resolveAccepted!: () => void;
@@ -1084,47 +2259,127 @@ export class SubagentCoordinator {
 			resolveAccepted = resolvePromise;
 			rejectAccepted = rejectPromise;
 		});
+		const turnAbortController = new AbortController();
+		activation.turnAbortController = turnAbortController;
 		const abort = () => {
+			turnAbortController.abort(
+				signal?.reason ?? new Error(`subagent turn ${turnId} was aborted`),
+			);
 			void activation.runtime.session.abort().catch(() => {});
 		};
 		if (signal) signal.addEventListener("abort", abort, { once: true });
+		let preflightSucceeded = false;
+		const acceptPrompt = () => {
+			if (acceptedSettled) return;
+			if (turnAbortController.signal.aborted) {
+				throw abortReason(turnAbortController.signal);
+			}
+			acceptedSettled = true;
+			activation.userMessageGates.delete(turnId);
+			this.publish(activation);
+			if (options.detachAtAcceptance && signal) {
+				signal.removeEventListener("abort", abort);
+			}
+			resolveAccepted();
+		};
+		const rejectPrompt = (error: Error) => {
+			if (acceptedSettled) return;
+			acceptedSettled = true;
+			activation.userMessageGates.delete(turnId);
+			activation.silentSettlementTurnIds.add(turnId);
+			if (!activation.published && !activation.everPublished) {
+				activation.suppressSettlement = true;
+			}
+			rejectAccepted(error);
+		};
+		if (options.acceptAfterUserMessage) {
+			activation.userMessageGates.set(turnId, {
+				prepare: () => {
+					if (turnAbortController.signal.aborted) {
+						throw abortReason(turnAbortController.signal);
+					}
+					options.onPromptAccepted?.(turnId);
+				},
+				accept: acceptPrompt,
+				reject: rejectPrompt,
+			});
+		}
 
 		const core = (async (): Promise<SubagentRunResult> => {
+			let permit: BackgroundRunPermit | undefined;
 			try {
-				await activation.runtime.session.prompt(prompt, {
+				permit = await this.acquireBackgroundRun(
+					activation,
+					turnAbortController.signal,
+					options.waitForCapacity,
+				);
+				if (turnAbortController.signal.aborted) {
+					throw abortReason(turnAbortController.signal);
+				}
+				const preparedPrompt = options.preparePrompt
+					? options.preparePrompt(turnId)
+					: prompt;
+				startAgentTurn(activation.controlState, turnId);
+				activation.startedTurnIds.add(turnId);
+				this.emitTurnStart(activation, turnId);
+				this.emitUpdate(activation);
+				await activation.runtime.session.prompt(preparedPrompt, {
+					...(options.preparePrompt
+						? {
+								expandPromptTemplates: false,
+								source: "extension" as const,
+							}
+						: {}),
 					preflightResult: (success) => {
 						if (acceptedSettled) return;
-						acceptedSettled = true;
 						if (success) {
-							this.publish(activation);
-							if (detachAtAcceptance && signal) signal.removeEventListener("abort", abort);
-							resolveAccepted();
+							preflightSucceeded = true;
+							if (options.acceptAfterUserMessage) {
+								return;
+							}
+							options.onPromptAccepted?.(turnId);
+							acceptPrompt();
 						} else {
-							activation.suppressSettlement = true;
-							rejectAccepted(new Error("subagent prompt was rejected before acceptance"));
+							rejectPrompt(
+								new Error("subagent prompt was rejected before acceptance"),
+							);
 						}
 					},
 				});
 				if (!acceptedSettled) {
-					acceptedSettled = true;
-					this.publish(activation);
-					if (detachAtAcceptance && signal) signal.removeEventListener("abort", abort);
-					resolveAccepted();
+					if (options.acceptAfterUserMessage && preflightSucceeded) {
+						throw new Error(
+							"subagent mailbox prompt was handled before a user turn started",
+						);
+					}
+					if (turnAbortController.signal.aborted) {
+						throw abortReason(turnAbortController.signal);
+					}
+					options.onPromptAccepted?.(turnId);
+					acceptPrompt();
 				}
-				return this.collectResult(activation, "completed");
+				return this.collectResult(activation, turnId, "completed");
 			} catch (error) {
 				activation.lastError = errorText(error);
 				if (!acceptedSettled) {
-					acceptedSettled = true;
-					activation.suppressSettlement = true;
-					rejectAccepted(error instanceof Error ? error : new Error(String(error)));
+					rejectPrompt(
+						error instanceof Error ? error : new Error(String(error)),
+					);
 				}
-				const fallback = signal?.aborted ? "aborted" : "error";
-				const result = this.collectResult(activation, fallback);
+				const fallback = turnAbortController.signal.aborted ? "aborted" : "error";
+				const result = this.collectResult(activation, turnId, fallback);
 				if (!result.output) result.output = activation.lastError;
 				return result;
 			} finally {
+				activation.userMessageGates.delete(turnId);
 				if (signal) signal.removeEventListener("abort", abort);
+				if (activation.turnAbortController === turnAbortController) {
+					activation.turnAbortController = undefined;
+				}
+				if (permit) {
+					activation.holdsBackgroundSlot = false;
+					permit.release();
+				}
 			}
 		})();
 
@@ -1136,47 +2391,69 @@ export class SubagentCoordinator {
 		});
 		activation.currentRun = lifecycle;
 		void lifecycle.catch(() => {});
-		return { accepted, result: lifecycle };
-	}
-
-	private startInternalMessage(
-		activation: Activation,
-		customType: string,
-		content: string,
-		details: ParentMessageDetails,
-	): void {
-		if (activation.currentRun || activation.disposed) return;
-		activation.pendingSettlement = undefined;
-		activation.status = "running";
-		const core = Promise.resolve()
-			.then(() =>
-				activation.runtime.session.sendCustomMessage(
-					{ customType, content, display: true, details },
-					{ triggerTurn: true, deliverAs: "followUp" },
-				),
-			)
-			.then(
-				() => this.collectResult(activation, "completed"),
-				(error) => {
-					activation.lastError = errorText(error);
-					const result = this.collectResult(activation, "error");
-					if (!result.output) result.output = activation.lastError ?? "";
-					return result;
-				},
-			);
-		let lifecycle!: Promise<SubagentRunResult>;
-		lifecycle = core.then(async (result) => {
-			if (activation.currentRun === lifecycle) activation.currentRun = undefined;
-			await this.runFinished(activation, result);
-			return result;
-		});
-		activation.currentRun = lifecycle;
-		void lifecycle.catch(() => {});
+		return { turnId, accepted, result: lifecycle };
 	}
 
 	private async runFinished(activation: Activation, result: SubagentRunResult): Promise<void> {
-		activation.status = result.stopReason === "completed" ? "completed" : "failed";
+		activation.pendingMailboxClaims.delete(result.turnId);
+		activation.persistenceGate.reject(
+			new Error(
+				`subagent ${activation.agentId} ended before its session became durable`,
+			),
+		);
+		finishAgentTurn(activation.controlState, result.turnId, result.stopReason);
+		if (result.stopReason !== "completed") {
+			activation.runtime.session.clearQueue();
+		}
+		const turnStarted = activation.startedTurnIds.delete(result.turnId);
+		if (turnStarted) {
+			this.emitTurnEnd(activation, result);
+		}
 		activation.pendingSettlement = result;
+		if (
+			turnStarted
+			&& !activation.silentSettlementTurnIds.has(result.turnId)
+			&& activation.published
+			&& activation.descriptor.mode === "continuable"
+		) {
+			try {
+				appendCompletionUpdate(activation.parent.sessionManager, {
+					parentAgentId: activation.descriptor.parentAgentId,
+					childAgentId: activation.agentId,
+					result,
+				});
+			} catch (error) {
+				activation.lastError = errorText(error);
+				let durableFallback = false;
+				try {
+					appendUndeliveredCompletion(
+						activation.runtime.session.sessionManager,
+						{
+							parentAgentId:
+								activation.descriptor.parentAgentId,
+							childAgentId: activation.agentId,
+							result,
+							error: activation.lastError,
+						},
+					);
+					durableFallback = true;
+				} catch {
+					// The explicit event below remains the final observable path
+					// when both parent delivery and child fallback persistence fail.
+				}
+				this.pi.events.emit("pi-subagent:completion-error", {
+					runId: activation.runId,
+					turnId: result.turnId,
+					agentId: activation.agentId,
+					parentAgentId: activation.descriptor.parentAgentId,
+					error: activation.lastError,
+					durableFallback,
+				});
+			}
+			this.completionWaiters
+				.get(completionWaiterKey(activation.parent))
+				?.wake();
+		}
 		this.emitUpdate(activation, result);
 		if (activation.descriptor.mode === "one-shot") {
 			this.emitEnd(activation, result);
@@ -1184,7 +2461,6 @@ export class SubagentCoordinator {
 		}
 		if (activation.suppressSettlement || this.draining) return;
 		if (activation.ownedChildren.size > 0) {
-			activation.status = "waiting";
 			this.emitUpdate(activation, result);
 			return;
 		}
@@ -1192,48 +2468,59 @@ export class SubagentCoordinator {
 	}
 
 	private async finalizeContinuable(activation: Activation): Promise<void> {
-		if (activation.finalizing || activation.disposed || activation.currentRun) return;
+		const retained = await this.agentOperations.run(activation.agentId, () =>
+			this.finalizeContinuableLocked(activation),
+		);
+		if (retained) {
+			await this.trimIdleRuntimes(activation.agentId);
+		}
+	}
+
+	private async finalizeContinuableLocked(activation: Activation): Promise<boolean> {
+		if (activation.finalizing || activation.disposed || activation.currentRun) {
+			return false;
+		}
 		const result = activation.pendingSettlement;
-		if (!result || activation.ownedChildren.size > 0) return;
+		if (!result || activation.ownedChildren.size > 0) return false;
 		activation.finalizing = true;
-		activation.finalizePromise = (async () => {
-			if (!activation.suppressSettlement && !this.draining) {
-				await this.deliverSettlement(activation, result).catch((error) => {
-					activation.lastError = errorText(error);
-				});
+		const finalizePromise = (async (): Promise<boolean> => {
+			let retained = false;
+			try {
+				this.emitEnd(activation, result);
+				activation.silentSettlementTurnIds.delete(result.turnId);
+				activation.pendingSettlement = undefined;
+				if (this.shouldRetainIdleRuntime(activation)) {
+					activation.published = false;
+					activation.runId = uuidv7();
+					await this.releaseParentOwnership(activation);
+					this.touchActivation(activation);
+					retained = true;
+				} else {
+					await this.disposeActivation(activation);
+					await this.releaseParentOwnership(activation);
+				}
+			} finally {
+				if (!activation.disposed) {
+					activation.finalizing = false;
+				}
 			}
-			this.emitEnd(activation, result);
-			await this.disposeActivation(activation);
-			await this.releaseParentOwnership(activation);
+			return retained;
 		})();
-		await activation.finalizePromise;
-	}
-
-	private async deliverSettlement(activation: Activation, result: SubagentRunResult): Promise<void> {
-		const truncated = truncateUtf8(result.output, activation.descriptor.runtime.maxOutputBytes);
-		const closing = truncated.text.trim()
-			? `Its closing message:\n\n${truncated.text}`
-			: "It left no closing message.";
-		const content = `Background subagent ${activation.agentId} ${stopReasonHeadline(result.stopReason)} and will do no further work unless you send it more.\n\n${closing}${
-			truncated.truncated ? `\n\n[Closing message truncated; ${truncated.omittedBytes} bytes omitted.]` : ""
-		}`;
-		await activation.parent.deliver(
-			SETTLED_CUSTOM_TYPE,
-			content,
-			{
-				kind: "settled",
-				childAgentId: activation.agentId,
-				label: activation.descriptor.label,
-				stopReason: result.stopReason,
-				...(truncated.truncated ? { truncated: true } : {}),
-			},
-			"wakeup",
-		);
+		activation.finalizePromise = finalizePromise;
+		try {
+			return await finalizePromise;
+		} finally {
+			if (activation.finalizePromise === finalizePromise) {
+				activation.finalizePromise = undefined;
+			}
+			if (!activation.disposed) activation.finalizing = false;
+		}
 	}
 
 	private parentForActivation(activation: Activation): ParentRef {
 		return {
 			agentId: activation.agentId,
+			taskPath: descriptorTaskPath(activation.descriptor),
 			depth: activation.descriptor.depth,
 			cwd: activation.descriptor.cwd,
 			sessionManager: activation.runtime.session.sessionManager,
@@ -1242,31 +2529,30 @@ export class SubagentCoordinator {
 			thinkingLevel: activation.runtime.session.thinkingLevel,
 			projectTrusted: activation.parent.projectTrusted,
 			activation,
-			deliver: async (customType, content, details, delivery) => {
+			deliver: async (customType, content, details) => {
 				if (activation.disposed) throw new Error(`parent subagent ${activation.agentId} is no longer resident`);
 				const session = activation.runtime.session;
-				if (delivery === "quiet") {
-					await session.sendCustomMessage(
-						{ customType, content, display: true, details },
-						session.isStreaming
-							? { triggerTurn: false, deliverAs: "nextTurn" }
-							: { triggerTurn: false },
-					);
-					return;
-				}
-				if (activation.currentRun || session.isStreaming) {
-					await session.sendCustomMessage(
-						{ customType, content, display: true, details },
-						{ triggerTurn: true, deliverAs: "followUp" },
-					);
-					return;
-				}
-				this.startInternalMessage(activation, customType, content, details);
+				await session.sendCustomMessage(
+					{ customType, content, display: true, details },
+					session.isStreaming
+						? { triggerTurn: false, deliverAs: "nextTurn" }
+						: { triggerTurn: false },
+				);
 			},
 		};
 	}
 
-	private collectResult(activation: Activation, fallback: SubagentStopReason): SubagentRunResult {
+	private resetTurnCapture(activation: Activation): void {
+		activation.epochMessageStart = activation.runtime.session.messages.length;
+		activation.streamedText = "";
+		activation.usage = emptyUsage();
+	}
+
+	private collectResult(
+		activation: Activation,
+		turnId: string,
+		fallback: SubagentStopReason,
+	): SubagentRunResult {
 		const messages = activation.runtime.session.messages;
 		const output = finalAssistantText(messages, activation.epochMessageStart, activation.streamedText);
 		const stopReason = finalStopReason(messages, activation.epochMessageStart, fallback);
@@ -1274,6 +2560,7 @@ export class SubagentCoordinator {
 		const sessionFile = activation.runtime.session.sessionFile;
 		return {
 			agentId: activation.agentId,
+			turnId,
 			piSessionId: activation.runtime.session.sessionId,
 			...(sessionFile ? { sessionFile } : {}),
 			output: truncated.truncated
@@ -1281,6 +2568,12 @@ export class SubagentCoordinator {
 						sessionFile ? ` Full output: ${sessionFile}` : " Full output remains in the active child session."
 					}]`
 				: truncated.text,
+			...(truncated.truncated
+				? {
+						outputTruncated: true,
+						omittedBytes: truncated.omittedBytes,
+					}
+				: {}),
 			stopReason,
 			usage: structuredClone(activation.usage),
 		};
@@ -1301,12 +2594,47 @@ export class SubagentCoordinator {
 			this.emitUpdate(activation);
 			return;
 		}
+		if (event.type === "agent_end") {
+			void this.releaseWaitAgentDeliveries(
+				this.parentForActivation(activation),
+				"parent agent turn ended without a durable wait_agent result",
+			).catch((error) => {
+				activation.lastError = errorText(error);
+			});
+			return;
+		}
 		if (event.type !== "message_end") return;
+		if (event.message.role === "user") {
+			const turnId = currentAgentTurnId(activation.controlState);
+			const gate = turnId
+				? activation.userMessageGates.get(turnId)
+				: undefined;
+			if (turnId && gate) {
+				try {
+					gate.prepare();
+					commitMailboxClaim(
+						activation.runtime.session.sessionManager,
+						turnId,
+						event.message,
+					);
+					activation.pendingMailboxClaims.delete(turnId);
+					gate.accept();
+				} catch (error) {
+					const failure =
+						error instanceof Error ? error : new Error(String(error));
+					activation.lastError = failure.message;
+					gate.reject(failure);
+					void activation.runtime.session.abort().catch(() => {});
+				}
+			}
+			return;
+		}
 		if (event.message.role === "toolResult") {
 			if (event.message.usage) addUsage(activation.usage, event.message.usage, false);
 			return;
 		}
 		if (event.message.role !== "assistant") return;
+		activation.persistenceGate.resolve();
 		addUsage(activation.usage, event.message.usage);
 		const text = event.message.content
 			.filter((part): part is Extract<(typeof event.message.content)[number], { type: "text" }> => part.type === "text")
@@ -1327,13 +2655,16 @@ export class SubagentCoordinator {
 	private publish(activation: Activation): void {
 		if (activation.published) return;
 		activation.published = true;
+		activation.everPublished = true;
 		this.pi.events.emit("pi-subagent:start", {
 			runId: activation.runId,
 			agentId: activation.agentId,
+			taskPath: descriptorTaskPath(activation.descriptor),
 			piSessionId: activation.runtime.session.sessionId,
 			parentAgentId: activation.descriptor.parentAgentId,
 			provider: activation.descriptor.provider,
 			mode: activation.descriptor.mode,
+			context: descriptorContext(activation.descriptor),
 		});
 	}
 
@@ -1342,6 +2673,35 @@ export class SubagentCoordinator {
 		this.pi.events.emit("pi-subagent:end", {
 			runId: activation.runId,
 			agentId: activation.agentId,
+			taskPath: descriptorTaskPath(activation.descriptor),
+			piSessionId: activation.runtime.session.sessionId,
+			parentAgentId: activation.descriptor.parentAgentId,
+			provider: activation.descriptor.provider,
+			mode: activation.descriptor.mode,
+			stopReason: result.stopReason,
+			output: result.output,
+		});
+	}
+
+	private emitTurnStart(activation: Activation, turnId: string): void {
+		this.pi.events.emit("pi-subagent:turn-start", {
+			runId: activation.runId,
+			turnId,
+			agentId: activation.agentId,
+			taskPath: descriptorTaskPath(activation.descriptor),
+			piSessionId: activation.runtime.session.sessionId,
+			parentAgentId: activation.descriptor.parentAgentId,
+			provider: activation.descriptor.provider,
+			mode: activation.descriptor.mode,
+		});
+	}
+
+	private emitTurnEnd(activation: Activation, result: SubagentRunResult): void {
+		this.pi.events.emit("pi-subagent:turn-end", {
+			runId: activation.runId,
+			turnId: result.turnId,
+			agentId: activation.agentId,
+			taskPath: descriptorTaskPath(activation.descriptor),
 			piSessionId: activation.runtime.session.sessionId,
 			parentAgentId: activation.descriptor.parentAgentId,
 			provider: activation.descriptor.provider,
@@ -1355,13 +2715,21 @@ export class SubagentCoordinator {
 		return {
 			kind: "delegation",
 			agentId: activation.agentId,
+			taskPath: descriptorTaskPath(activation.descriptor),
+			...(currentAgentTurnId(activation.controlState)
+				? { turnId: currentAgentTurnId(activation.controlState) }
+				: {}),
 			piSessionId: activation.runtime.session.sessionId,
 			provider: activation.descriptor.provider,
 			mode: activation.descriptor.mode,
+			context: descriptorContext(activation.descriptor),
 			agent: activation.descriptor.agent.name,
 			label: activation.descriptor.label,
 			depth: activation.descriptor.depth,
-			status: activation.status,
+			status: delegationStatus(
+				activation.controlState,
+				activation.ownedChildren.size > 0,
+			),
 			...(activation.runtime.session.sessionFile
 				? { sessionFile: activation.runtime.session.sessionFile }
 				: {}),
@@ -1403,6 +2771,25 @@ export class SubagentCoordinator {
 	private async disposeActivation(activation: Activation): Promise<void> {
 		if (activation.disposed) return;
 		activation.disposed = true;
+		const waiterKey = completionWaiterKey(
+			this.parentForActivation(activation),
+		);
+		const waiter = this.completionWaiters.get(waiterKey);
+		if (waiter) {
+			this.removeCompletionWaiter(waiterKey, waiter);
+			waiter.reject(
+				new Error(
+					`parent subagent ${activation.agentId} was disposed while wait_agent was pending`,
+				),
+			);
+		}
+		activation.persistenceGate.reject(
+			new Error(
+				`subagent ${activation.agentId} ended before its session became durable`,
+			),
+		);
+		setAgentResidency(activation.controlState, "unloaded");
+		if (activation.descriptor.mode === "one-shot") closeAgent(activation.controlState);
 		activation.unsubscribe?.();
 		activation.unsubscribe = undefined;
 		if (!activation.runtime.session.isIdle) await activation.runtime.session.abort().catch(() => {});
@@ -1414,8 +2801,9 @@ export class SubagentCoordinator {
 	}
 
 	private async releaseParentOwnership(activation: Activation): Promise<void> {
-		const owner = activation.parent.activation;
+		const owner = activation.ownerActivation;
 		if (!owner) return;
+		activation.ownerActivation = undefined;
 		owner.ownedChildren.delete(activation.agentId);
 		if (
 			!owner.currentRun &&
@@ -1423,16 +2811,394 @@ export class SubagentCoordinator {
 			owner.pendingSettlement &&
 			owner.descriptor.mode === "continuable"
 		) {
-			await this.finalizeContinuable(owner);
+			void this.finalizeContinuable(owner).catch((error) => {
+				owner.lastError = errorText(error);
+			});
+		}
+	}
+
+	private acquireParentOwnership(
+		activation: Activation,
+		parent: ParentRef,
+	): void {
+		if (
+			activation.ownerActivation
+			&& activation.ownerActivation !== parent.activation
+		) {
+			throw new Error(
+				`subagent ${descriptorTaskPath(activation.descriptor)} is still owned by another resident parent`,
+			);
+		}
+		activation.parent = parent;
+		if (!parent.activation) return;
+		parent.activation.ownedChildren.add(activation.agentId);
+		activation.ownerActivation = parent.activation;
+	}
+
+	private touchActivation(activation: Activation): void {
+		activation.lastUsedSequence = ++this.activationSequence;
+	}
+
+	private shouldRetainIdleRuntime(activation: Activation): boolean {
+		return (
+			this.idleRuntimeLimit > 0
+			&& !this.draining
+			&& activation.descriptor.mode === "continuable"
+			&& !activation.disposed
+			&& !activation.currentRun
+			&& activation.runtime.session.isIdle
+			&& activation.ownedChildren.size === 0
+			&& activation.pendingMailboxClaims.size === 0
+			&& activation.persistenceGate.state !== "rejected"
+		);
+	}
+
+	private isEvictableIdleRuntime(activation: Activation): boolean {
+		return (
+			!activation.disposed
+			&& !activation.finalizing
+			&& activation.descriptor.mode === "continuable"
+			&& !activation.currentRun
+			&& !activation.pendingSettlement
+			&& activation.runtime.session.isIdle
+			&& activation.ownedChildren.size === 0
+			&& activation.pendingMailboxClaims.size === 0
+			&& !activation.ownerActivation
+		);
+	}
+
+	private async trimIdleRuntimes(protectedAgentId?: string): Promise<void> {
+		await this.idleRuntimeOperations.run("idle-runtime-lru", async () =>
+			this.trimIdleRuntimesLocked(protectedAgentId),
+		);
+	}
+
+	private async trimIdleRuntimesLocked(
+		protectedAgentId?: string,
+	): Promise<void> {
+		while (true) {
+			const retained = [...this.active.values()].filter(
+				(activation) =>
+					activation.agentId === protectedAgentId
+						? this.shouldRetainIdleRuntime(activation)
+						: this.isEvictableIdleRuntime(activation),
+			);
+			if (retained.length <= this.idleRuntimeLimit) return;
+			const candidate = retained
+				.filter(
+					(activation) =>
+						activation.agentId !== protectedAgentId
+						&& this.isEvictableIdleRuntime(activation),
+				)
+				.sort(
+					(left, right) =>
+						left.lastUsedSequence - right.lastUsedSequence
+						|| left.agentId.localeCompare(right.agentId),
+				)[0];
+			if (!candidate) return;
+			await this.agentOperations.run(candidate.agentId, async () => {
+				if (
+					this.active.get(candidate.agentId) === candidate
+					&& this.isEvictableIdleRuntime(candidate)
+				) {
+					await this.disposeActivation(candidate);
+				}
+			});
 		}
 	}
 
 	private assertDirectParent(parent: ParentRef, descriptor: SubagentDescriptor): void {
 		if (descriptor.parentAgentId !== parent.agentId) {
 			throw new Error(
-				`subagent ${descriptor.label} is not a direct child of ${parent.agentId}; message was not delivered`,
+				`subagent ${descriptor.label} is not a direct child of ${parent.agentId}`,
+			);
+		}
+	}
+
+	private assertContinuableDirectChild(
+		parent: ParentRef,
+		descriptor: SubagentDescriptor,
+	): void {
+		if (descriptor.mode !== "continuable") {
+			throw new Error(
+				`subagent ${descriptor.agentId} is one-shot and cannot accept follow-up work`,
 			);
 		}
+		this.assertDirectParent(parent, descriptor);
+	}
+
+	private treeRootAgentId(
+		agentId: string,
+		byId: ReadonlyMap<string, CatalogRecord>,
+	): string {
+		let current = agentId;
+		const visited = new Set<string>();
+		while (true) {
+			if (visited.has(current)) {
+				throw new Error("subagent descriptor lineage contains a cycle");
+			}
+			visited.add(current);
+			const record = byId.get(current);
+			if (!record) return current;
+			current = record.descriptor.parentAgentId;
+		}
+	}
+
+	private async reserveTask(
+		parent: ParentRef,
+		requestedName: string | undefined,
+		label: string,
+	): Promise<ReservedTask> {
+		const catalog = await this.catalogRecords(parent);
+		const usedPaths = new Set(
+			catalog.records
+				.filter(
+					(record) =>
+						record.descriptor.parentAgentId === parent.agentId,
+				)
+				.map((record) => record.taskPath),
+		);
+		const reserve = (name: string): ReservedTask | undefined => {
+			const path = taskPath(parent.taskPath, name);
+			const reservationKey = `${parent.agentId}:${path}`;
+			if (
+				usedPaths.has(path)
+				|| this.reservedTaskPaths.has(reservationKey)
+			) {
+				return undefined;
+			}
+			this.reservedTaskPaths.add(reservationKey);
+			let released = false;
+			return {
+				name,
+				path,
+				release: () => {
+					if (released) return;
+					released = true;
+					this.reservedTaskPaths.delete(reservationKey);
+				},
+			};
+		};
+
+		if (requestedName !== undefined) {
+			const name = validateTaskName(requestedName);
+			const reserved = reserve(name);
+			if (!reserved) {
+				throw new Error(
+					`task path ${taskPath(parent.taskPath, name)} is already in use`,
+				);
+			}
+			return reserved;
+		}
+
+		const base = slugTaskName(label);
+		const initial = reserve(base);
+		if (initial) return initial;
+		for (let ordinal = 2; ordinal < Number.MAX_SAFE_INTEGER; ordinal++) {
+			const candidate = reserve(numberedTaskName(base, ordinal));
+			if (candidate) return candidate;
+		}
+		throw new Error(`could not allocate a readable child path under ${parent.taskPath}`);
+	}
+
+	private async resolveTarget(
+		parent: ParentRef,
+		target: string,
+		options: { allowUnknownId?: boolean } = {},
+	): Promise<ResolvedTarget> {
+		const catalog = await this.catalogRecords(parent);
+		const byId = new Map(
+			catalog.records.map((record) => [record.agentId, record]),
+		);
+		if (isAgentId(target)) {
+			const record = byId.get(target);
+			if (record) {
+				return {
+					agentId: record.agentId,
+					taskPath: record.taskPath,
+					record,
+				};
+			}
+			if (options.allowUnknownId) {
+				return {
+					agentId: target,
+					taskPath: target,
+				};
+			}
+			return {
+				agentId: target,
+				taskPath: target,
+			};
+		}
+
+		const path = resolveTaskPath(parent.taskPath, target);
+		const rootAgentId = this.treeRootAgentId(parent.agentId, byId);
+		const matches = this.reachableTreeRecords(rootAgentId, byId).filter(
+			(record) => record.taskPath === path,
+		);
+		if (matches.length === 0) {
+			throw new Error(`unknown subagent task path: ${path}`);
+		}
+		if (matches.length > 1) {
+			throw new Error(
+				`ambiguous subagent task path ${path}; use a durable agent id`,
+			);
+		}
+		const record = matches[0]!;
+		return {
+			agentId: record.agentId,
+			taskPath: record.taskPath,
+			record,
+		};
+	}
+
+	private reachableTreeRecords(
+		rootAgentId: string,
+		byId: ReadonlyMap<string, CatalogRecord>,
+	): CatalogRecord[] {
+		const paths = new Map<string, string>([
+			[rootAgentId, ROOT_TASK_PATH],
+		]);
+		const depths = new Map<string, number>([[rootAgentId, 0]]);
+		const reachable: CatalogRecord[] = [];
+		const pending = new Set(byId.values());
+		let progressed = true;
+		while (progressed) {
+			progressed = false;
+			for (const record of [...pending]) {
+				const parentPath = paths.get(
+					record.descriptor.parentAgentId,
+				);
+				const parentDepth = depths.get(
+					record.descriptor.parentAgentId,
+				);
+				if (parentPath === undefined || parentDepth === undefined) {
+					continue;
+				}
+				{
+					let expectedPath: string;
+					try {
+						expectedPath = taskPath(
+							parentPath,
+							record.descriptor.task.name,
+						);
+					} catch {
+						pending.delete(record);
+						progressed = true;
+						continue;
+					}
+					if (
+						record.taskPath !== expectedPath
+						|| record.descriptor.depth !== parentDepth + 1
+					) {
+						pending.delete(record);
+						progressed = true;
+						continue;
+					}
+				}
+				pending.delete(record);
+				reachable.push(record);
+				paths.set(record.agentId, record.taskPath);
+				depths.set(record.agentId, record.descriptor.depth);
+				progressed = true;
+			}
+		}
+		return reachable;
+	}
+
+	private catalogTopologyDiagnostics(
+		records: readonly CatalogRecord[],
+	): CatalogDiagnostic[] {
+		const byId = new Map(
+			records.map((record) => [record.agentId, record]),
+		);
+		const problems = new Map<string, string>();
+		for (const record of records) {
+			const parent = byId.get(record.descriptor.parentAgentId);
+			if (parent) {
+				let expectedPath: string | undefined;
+				try {
+					expectedPath = taskPath(
+						parent.taskPath,
+						record.descriptor.task.name,
+					);
+				} catch {
+					problems.set(
+						record.agentId,
+						"descriptor task path cannot be joined to its parent",
+					);
+				}
+				if (
+					expectedPath !== undefined
+					&& (
+						record.taskPath !== expectedPath
+					|| record.descriptor.depth
+						!== parent.descriptor.depth + 1
+					)
+				) {
+					problems.set(
+						record.agentId,
+						"descriptor task path or depth does not match its parent",
+					);
+				}
+			} else if (
+				record.descriptor.depth === 1
+				&& record.taskPath
+					!== taskPath(
+						ROOT_TASK_PATH,
+						record.descriptor.task.name,
+					)
+			) {
+				problems.set(
+					record.agentId,
+					"root child task path does not match its task name",
+				);
+			}
+		}
+
+		for (const start of records) {
+			const chain: string[] = [];
+			const indexes = new Map<string, number>();
+			let current: CatalogRecord | undefined = start;
+			while (current) {
+				const existing = indexes.get(current.agentId);
+				if (existing !== undefined) {
+					for (const agentId of chain.slice(existing)) {
+						problems.set(
+							agentId,
+							"descriptor lineage contains a cycle",
+						);
+					}
+					break;
+				}
+				indexes.set(current.agentId, chain.length);
+				chain.push(current.agentId);
+				current = byId.get(current.descriptor.parentAgentId);
+			}
+		}
+
+		return [...problems]
+			.map(([agentId, message]) => {
+				const record = byId.get(agentId)!;
+				return {
+					kind: "diagnostic" as const,
+					piSessionId: record.piSessionId,
+					reason: "corrupt" as const,
+					...(record.sessionFile
+						? { sessionFile: record.sessionFile }
+						: {}),
+					...(record.descriptor.parentSessionFile
+						? {
+								parentSessionFile:
+									record.descriptor.parentSessionFile,
+							}
+						: {}),
+					message,
+				};
+			})
+			.sort((left, right) =>
+				left.piSessionId.localeCompare(right.piSessionId),
+			);
 	}
 
 	private async findPersistedChild(
@@ -1450,29 +3216,110 @@ export class SubagentCoordinator {
 		for (const item of persisted.descriptors) {
 			records.set(item.agentId, {
 				agentId: item.agentId,
+				piSessionId: item.piSessionId,
+				taskPath: descriptorTaskPath(item.descriptor),
 				descriptor: item.descriptor,
 				sessionFile: item.sessionFile,
+				pendingMessages: item.pendingMessages,
+				unreadUpdatesByChild: new Map(item.unreadUpdatesByChild),
 			});
 		}
 		const activeSessionIds = new Set(
 			[...this.active.values()].map((activation) => activation.runtime.session.sessionId),
 		);
+		const activeDiagnostics: CatalogEntry[] = [];
+		const rootCompletions = foldCompletionMailbox(
+			parent.sessionManager.getEntries(),
+			{ parentAgentId: parent.agentId },
+		);
+		const rootUnreadUpdatesByChild =
+			rootCompletions.kind === "valid"
+				? unreadCompletionCounts(rootCompletions.snapshot)
+				: new Map<string, number>();
+		if (rootCompletions.kind === "corrupt") {
+			const parentFile = parent.sessionManager.getSessionFile();
+			activeDiagnostics.push({
+				kind: "diagnostic",
+				piSessionId: parent.sessionManager.getSessionId(),
+				reason: "corrupt",
+				...(parentFile
+					? {
+							sessionFile: parentFile,
+							parentSessionFile: parentFile,
+						}
+					: {}),
+				message: `corrupt completion mailbox: ${rootCompletions.message}`,
+			});
+		}
 		for (const activation of this.active.values()) {
 			if (activation.descriptor.cwd !== parent.cwd) continue;
+			let pendingMessages = 0;
+			const mailbox = foldOwnedMailbox(
+				activation.runtime.session.sessionManager.getEntries(),
+				mailboxOwner(activation.descriptor),
+			);
+			if (mailbox.kind === "valid") {
+				pendingMessages = mailbox.snapshot.pending.length;
+			} else {
+				activeDiagnostics.push({
+					kind: "diagnostic",
+					piSessionId: activation.runtime.session.sessionId,
+					reason: "corrupt",
+					...(activation.runtime.session.sessionFile
+						? { sessionFile: activation.runtime.session.sessionFile }
+						: {}),
+					...(activation.descriptor.parentSessionFile
+						? { parentSessionFile: activation.descriptor.parentSessionFile }
+						: {}),
+					message: `corrupt subagent mailbox: ${mailbox.message}`,
+				});
+				continue;
+			}
+			const completions = foldCompletionMailbox(
+				activation.runtime.session.sessionManager.getEntries(),
+				{ parentAgentId: activation.agentId },
+			);
+			if (completions.kind === "corrupt") {
+				activeDiagnostics.push({
+					kind: "diagnostic",
+					piSessionId: activation.runtime.session.sessionId,
+					reason: "corrupt",
+					...(activation.runtime.session.sessionFile
+						? { sessionFile: activation.runtime.session.sessionFile }
+						: {}),
+					...(activation.descriptor.parentSessionFile
+						? { parentSessionFile: activation.descriptor.parentSessionFile }
+						: {}),
+					message: `corrupt completion mailbox: ${completions.message}`,
+				});
+				continue;
+			}
 			records.set(activation.agentId, {
 				agentId: activation.agentId,
+				piSessionId: activation.runtime.session.sessionId,
+				taskPath: descriptorTaskPath(activation.descriptor),
 				descriptor: activation.descriptor,
 				...(activation.runtime.session.sessionFile
 					? { sessionFile: activation.runtime.session.sessionFile }
 					: {}),
 				active: activation,
+				pendingMessages,
+				unreadUpdatesByChild: unreadCompletionCounts(
+					completions.snapshot,
+				),
 			});
 		}
+		const catalogRecords = [...records.values()];
 		return {
-			records: [...records.values()],
-			diagnostics: persisted.diagnostics.filter(
-				(diagnostic) => !activeSessionIds.has(diagnostic.piSessionId),
-			),
+			records: catalogRecords,
+			diagnostics: [
+				...persisted.diagnostics.filter(
+					(diagnostic) => !activeSessionIds.has(diagnostic.piSessionId),
+				),
+				...activeDiagnostics,
+				...this.catalogTopologyDiagnostics(catalogRecords),
+			],
+			rootUnreadUpdatesByChild,
 		};
 	}
 
@@ -1504,7 +3351,6 @@ export class SubagentCoordinator {
 
 export {
 	REPORT_CUSTOM_TYPE,
-	SETTLED_CUSTOM_TYPE,
 	AGENT_CUSTOM_TYPE,
 	LINEAGE_CUSTOM_TYPE,
 };