@oai404iao/pi-subagent 0.3.0 → 0.4.0

package/src/descriptor.ts

@@ -4,24 +4,33 @@ import type {
 	AgentScope,
 	AgentSnapshot,
 	AgentSource,
-	ReportDelivery,
+	ContextInheritance,
+	RuntimeMode,
 	SubagentDescriptor,
 	SubagentMode,
 	SubagentProviderName,
+	SubagentRuntimeSnapshot,
 } from "./types.ts";
+import { DESCRIPTOR_VERSION } from "./types.ts";
+import { validateDescriptorTask } from "./task-path.ts";
 
 export const DESCRIPTOR_CUSTOM_TYPE = "pi-subagent/descriptor";
-export const DESCRIPTOR_VERSION = 2;
+export { DESCRIPTOR_VERSION };
 
 const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
-const AGENT_SOURCES = new Set<AgentSource>(["bundled", "user", "project"]);
+const AGENT_SOURCES = new Set<AgentSource>(["user", "project"]);
 const MODES = new Set<SubagentMode>(["one-shot", "continuable"]);
 const PROVIDERS = new Set<SubagentProviderName>(["spawn", "fork"]);
-const REPORT_DELIVERIES = new Set<ReportDelivery>(["wakeup", "quiet"]);
+const RUNTIME_MODES = new Set<RuntimeMode>(["foreground", "background"]);
 const AGENT_SCOPES = new Set<AgentScope>(["user", "project", "both"]);
 const AGENT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 /** UUIDv7 with the standard RFC 9562 variant bits (version 7, variant 10xx). */
 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 CONTEXT_MODES = new Set<ContextInheritance["mode"]>([
+	"fresh",
+	"all_completed",
+	"last_n_completed",
+]);
 
 type UnknownRecord = Record<string, unknown>;
 
@@ -116,10 +125,49 @@ function parseAgent(value: unknown): AgentSnapshot {
 	};
 }
 
+function parseContext(value: unknown): ContextInheritance {
+	const input = record(value, "context");
+	const mode = string(input.mode, "context.mode") as ContextInheritance["mode"];
+	if (!CONTEXT_MODES.has(mode)) {
+		throw new Error(`unsupported context.mode: ${mode}`);
+	}
+	if (mode === "last_n_completed") {
+		return {
+			mode,
+			completedTurns: boundedInteger(
+				input.completedTurns,
+				"context.completedTurns",
+				1,
+				100,
+			),
+		};
+	}
+	if (input.completedTurns !== undefined) {
+		throw new Error(
+			"context.completedTurns is available only for last_n_completed",
+		);
+	}
+	return { mode };
+}
+
+function parseRuntimeMode(value: unknown): RuntimeMode {
+	if (
+		typeof value !== "string"
+		|| !RUNTIME_MODES.has(value as RuntimeMode)
+	) {
+		throw new Error(
+			'runtime.runtimeMode must be "foreground" or "background"',
+		);
+	}
+	return value as RuntimeMode;
+}
+
 export function parseDescriptor(value: unknown): SubagentDescriptor {
 	const input = record(value, "descriptor");
 	if (input.version !== DESCRIPTOR_VERSION) {
-		throw new Error(`unsupported descriptor version: ${String(input.version)}`);
+		throw new Error(
+			`unsupported descriptor version: ${String(input.version)}; this release persists version ${DESCRIPTOR_VERSION}`,
+		);
 	}
 	const mode = string(input.mode, "mode") as SubagentMode;
 	if (!MODES.has(mode)) throw new Error(`unsupported descriptor mode: ${mode}`);
@@ -132,16 +180,36 @@ export function parseDescriptor(value: unknown): SubagentDescriptor {
 	const runtime = record(input.runtime, "runtime");
 	const agentScope = string(runtime.agentScope, "runtime.agentScope") as AgentScope;
 	if (!AGENT_SCOPES.has(agentScope)) throw new Error(`unsupported runtime.agentScope: ${agentScope}`);
-	const reportDelivery = string(runtime.reportDelivery, "runtime.reportDelivery") as ReportDelivery;
-	if (!REPORT_DELIVERIES.has(reportDelivery)) {
-		throw new Error(`unsupported runtime.reportDelivery: ${reportDelivery}`);
-	}
+	const parsedRuntime: SubagentRuntimeSnapshot = {
+		agentScope,
+		maxDepth: safeNatural(runtime.maxDepth, "runtime.maxDepth"),
+		runtimeMode: parseRuntimeMode(runtime.runtimeMode),
+		maxConcurrentBackgroundRuns: boundedInteger(
+			runtime.maxConcurrentBackgroundRuns,
+			"runtime.maxConcurrentBackgroundRuns",
+			1,
+			Number.MAX_SAFE_INTEGER,
+		),
+		maxIdleRuntimes: boundedInteger(
+			runtime.maxIdleRuntimes,
+			"runtime.maxIdleRuntimes",
+			0,
+			Number.MAX_SAFE_INTEGER,
+		),
+		inheritExtensions: boolean(runtime.inheritExtensions, "runtime.inheritExtensions"),
+		openAIIdentity: boolean(runtime.openAIIdentity, "runtime.openAIIdentity"),
+		maxOutputBytes: boundedInteger(
+			runtime.maxOutputBytes,
+			"runtime.maxOutputBytes",
+			1024,
+			1024 * 1024,
+		),
+	};
 
 	const createdAt = string(input.createdAt, "createdAt");
 	if (Number.isNaN(Date.parse(createdAt))) throw new Error("createdAt must be an ISO date string");
 
-	return {
-		version: DESCRIPTOR_VERSION,
+	const base = {
 		mode,
 		provider,
 		label: limitedString(input.label, "label", 200),
@@ -160,28 +228,17 @@ export function parseDescriptor(value: unknown): SubagentDescriptor {
 			id: string(model.id, "model.id"),
 		},
 		thinkingLevel,
-		runtime: {
-			agentScope,
-			syncBundledAgents:
-				runtime.syncBundledAgents === undefined
-					? true
-					: boolean(runtime.syncBundledAgents, "runtime.syncBundledAgents"),
-			maxDepth: safeNatural(runtime.maxDepth, "runtime.maxDepth"),
-			enableRunInBackground:
-				runtime.enableRunInBackground === undefined
-					? true
-					: boolean(runtime.enableRunInBackground, "runtime.enableRunInBackground"),
-			defaultBackground: boolean(runtime.defaultBackground, "runtime.defaultBackground"),
-			reportDelivery,
-			inheritExtensions: boolean(runtime.inheritExtensions, "runtime.inheritExtensions"),
-			openAIIdentity: boolean(runtime.openAIIdentity, "runtime.openAIIdentity"),
-			maxOutputBytes: boundedInteger(
-				runtime.maxOutputBytes,
-				"runtime.maxOutputBytes",
-				1024,
-				1024 * 1024,
-			),
-		},
+		runtime: parsedRuntime,
+	};
+	const task = record(input.task, "task");
+	return {
+		version: DESCRIPTOR_VERSION,
+		...base,
+		task: validateDescriptorTask({
+			name: string(task.name, "task.name"),
+			path: string(task.path, "task.path"),
+		}),
+		context: parseContext(input.context),
 	};
 }
 
@@ -200,3 +257,9 @@ export function foldDescriptor(entries: readonly SessionEntry[]): DescriptorFold
 		return { kind: "corrupt", message: error instanceof Error ? error.message : String(error) };
 	}
 }
+
+export function descriptorContext(
+	descriptor: SubagentDescriptor,
+): ContextInheritance {
+	return structuredClone(descriptor.context);
+}

package/src/index.ts

@@ -4,7 +4,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_SETTINGS, loadSettings } from "./config.ts";
 import {
 	REPORT_CUSTOM_TYPE,
-	SETTLED_CUSTOM_TYPE,
 	SubagentCoordinator,
 	type DelegationInput,
 } from "./coordinator.ts";
@@ -14,9 +13,11 @@ import {
 } from "./agents.ts";
 import type { AgentSyncResult } from "./agent-sync.ts";
 import {
+	FollowupTaskParameters,
 	InterruptParameters,
 	ListAgentsParameters,
 	SendMessageParameters,
+	WaitAgentParameters,
 	delegationParameters,
 	forkDelegationParameters,
 } from "./schemas.ts";
@@ -58,56 +59,53 @@ function disableOwnedTools(
 }
 
 function assertBackgroundControlsEnabled(settings: SubagentSettings, toolName: string): void {
-	if (!settings.enableRunInBackground) {
+	if (settings.runtimeMode === "foreground") {
 		throw new Error(
-			`tool "${toolName}" is unavailable in foreground-only mode (enableRunInBackground: false)`,
+			`tool "${toolName}" is unavailable in foreground-only mode (runtimeMode: "foreground")`,
 		);
 	}
 }
 
+function modeDescription(settings: SubagentSettings): string {
+	return settings.runtimeMode === "foreground"
+		? "Delegate a complete task to a named child path with selectable completed-turn context. " +
+				"This foreground-only tool waits for the child and returns its final answer. " +
+				"Independent sibling calls may still execute in parallel."
+		: "Delegate a complete task to a named child path with selectable completed-turn context. " +
+				"Background mode is continuable and returns a readable path plus durable id; use send_message to enqueue, followup_task to start, and wait_agent for quiet completions. " +
+				"Start independent children together in one assistant message.";
+}
+
 function registerDelegationTool(
 	pi: ExtensionAPI,
 	coordinator: SubagentCoordinator,
 	settings: SubagentSettings,
 	agentDiscovery?: AgentDiscoveryResult,
 ): unknown {
-	const { enableRunInBackground, defaultBackground } = settings;
+	const foregroundOnly = settings.runtimeMode === "foreground";
 	const agentNames = agentDiscovery?.agents.map((agent) => agent.name);
-	const description = !enableRunInBackground
-		? "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
-			"This foreground-only tool waits for the child and returns its final answer. " +
-			"Independent sibling calls may still execute in parallel."
-		: defaultBackground
-		? "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
-			"Background mode is continuable and returns a durable agent id; use send_message for later FIFO turns. " +
-			"Start independent children together in one assistant message."
-		: "Delegate a complete standalone task to a fresh child with its own Pi session and context. " +
-			"This tool waits for the result by default; set run_in_background to true to return a durable agent id.";
-	const promptGuidelines = !enableRunInBackground
+	const promptGuidelines = (foregroundOnly
 		? [
 				"Use subagent for focused independent work and give it a complete standalone prompt.",
 				"This subagent tool is foreground-only: every call waits for and returns the child's final answer.",
 				"Independent subagent calls can still be issued together in one assistant message and execute in parallel.",
 			]
-		: defaultBackground
-			? [
-					"Use subagent for focused independent work and give it a complete standalone prompt.",
-					"Call subagent multiple times in one assistant message when delegations are independent.",
-					"Keep useful parent work moving after a background subagent starts; use foreground only when the next action needs its result.",
-				]
-			: [
-					"Use subagent for focused independent work and give it a complete standalone prompt.",
-					"Subagent calls wait for the result by default; request background mode only when work can continue independently.",
-					"Independent subagent calls can still be issued together in one assistant message and execute in parallel.",
-				];
-	const parameters = delegationParameters(enableRunInBackground, agentNames);
+		: [
+				"Use subagent for focused independent work and give it a complete standalone prompt.",
+				"Call subagent multiple times in one assistant message when delegations are independent.",
+				"Every child is durable: continue parent work, then use send_message plus followup_task to give it more work and wait_agent for its completion updates.",
+			]).concat([
+					"Set task_name when a stable readable path will help later control calls; otherwise a name is generated from description.",
+					"Use fresh context by default and request all_completed or last_n_completed only when parent history materially helps.",
+				]);
+	const parameters = delegationParameters(agentNames);
 	pi.registerTool({
 		name: "subagent",
 		label: "Subagent",
-		description,
-		promptSnippet: enableRunInBackground
-			? "Delegate focused independent work to fresh child agents"
-			: "Run focused independent work in foreground child agents",
+		description: modeDescription(settings),
+		promptSnippet: foregroundOnly
+			? "Run focused independent work in foreground child agents"
+			: "Delegate focused work to named child agents",
 		promptGuidelines,
 		executionMode: "parallel",
 		parameters,
@@ -129,7 +127,7 @@ function registerDelegationTool(
 			return coordinator.outcomeToolResult(outcome);
 		},
 		renderCall(args, theme) {
-			return renderDelegationCall(args, theme, "spawn");
+			return renderDelegationCall(args, theme, "spawn", settings.runtimeMode);
 		},
 		renderResult(result, options, theme) {
 			return renderDelegationResult(
@@ -155,8 +153,11 @@ function registerForkDelegationTool(
 		name: "subagent_fork",
 		label: "Subagent Fork",
 		description:
-			"Delegate a one-shot task to a child seeded with all completed turns in this conversation. " +
-			"The current in-flight tool-calling turn is excluded. Use this when the child needs parent history.",
+			"Delegate a task to a child seeded with all completed turns in this conversation. " +
+			"The current in-flight tool-calling turn is excluded. " +
+			(settings.runtimeMode === "foreground"
+				? "This foreground-only tool waits for the child's final answer."
+				: "The fork is continuable and returns a readable path plus durable id."),
 		promptSnippet: "Delegate context-dependent work to a child seeded with completed turns",
 		promptGuidelines: [
 			"Use subagent_fork only when completed conversation history materially helps the delegated task.",
@@ -181,7 +182,7 @@ function registerForkDelegationTool(
 			return coordinator.outcomeToolResult(outcome);
 		},
 		renderCall(args, theme) {
-			return renderDelegationCall(args, theme, "fork");
+			return renderDelegationCall(args, theme, "fork", settings.runtimeMode);
 		},
 		renderResult(result, options, theme) {
 			return renderDelegationResult(
@@ -206,6 +207,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	registerForkDelegationTool(pi, coordinator, DEFAULT_SETTINGS);
 	const backgroundControlParameters = new Map<string, unknown>([
 		["send_message", SendMessageParameters],
+		["followup_task", FollowupTaskParameters],
+		["wait_agent", WaitAgentParameters],
 		["interrupt_agent", InterruptParameters],
 		["list_agents", ListAgentsParameters],
 	]);
@@ -214,23 +217,107 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		name: "send_message",
 		label: "Send Message",
 		description:
-			"Queue a message as a direct continuable child's next FIFO turn. If it is inactive, its persisted session is cold-resumed by agent id. " +
+			"Send a message to a direct continuable child. It is durably appended to the child's FIFO mailbox and requires followup_task to start a turn. " +
 			"This call returns acceptance only, never the child's answer.",
-		promptSnippet: "Send a later FIFO turn to a direct continuable subagent",
+		promptSnippet: "Send or enqueue a message for a direct continuable subagent",
 		executionMode: "parallel",
 		parameters: SendMessageParameters,
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			assertBackgroundControlsEnabled(sessionSettings, "send_message");
 			const parent = await coordinator.parentFromContext(ctx);
-			await coordinator.sendMessage(parent, params.subagent_id, params.message, signal);
+			const delivery = await coordinator.sendMessageWithOutcome(
+				parent,
+				params.subagent_id,
+				params.message,
+				signal,
+			);
+			return {
+				content: [
+					{
+						type: "text",
+						text: `message ${delivery.messageId} durably enqueued for ${delivery.taskPath}; ${delivery.pendingMessages} pending`,
+					},
+				],
+				details: {
+					kind: "control",
+					action: "send",
+					agentId: delivery.agentId,
+					taskPath: delivery.taskPath,
+					messageId: delivery.messageId,
+					pendingMessages: delivery.pendingMessages,
+				} satisfies ControlDetails,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "followup_task",
+		label: "Follow-up Task",
+		description:
+			"For a direct continuable child, atomically claim its current pending FIFO mailbox and start exactly one scheduled turn. " +
+			"This call returns turn acceptance, not the child's answer.",
+		promptSnippet: "Start one child turn from queued mailbox messages",
+		executionMode: "parallel",
+		parameters: FollowupTaskParameters,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			assertBackgroundControlsEnabled(sessionSettings, "followup_task");
+			const parent = await coordinator.parentFromContext(ctx);
+			const outcome = await coordinator.followupTask(
+				parent,
+				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,
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "wait_agent",
+		label: "Wait Agent",
+		description:
+			"Wait event-driven for unread completion updates from direct children. Existing updates return immediately; timeout does not consume later updates.",
+		promptSnippet: "Wait for quiet child completion updates",
+		parameters: WaitAgentParameters,
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			assertBackgroundControlsEnabled(sessionSettings, "wait_agent");
+			const parent = await coordinator.parentFromContext(ctx);
+			const outcome = await coordinator.waitAgent(
+				parent,
+				toolCallId,
+				params.timeout_ms,
+				signal,
+			);
 			return {
 				content: [
 					{
 						type: "text",
-						text: `message queued as the next turn for subagent ${params.subagent_id}`,
+						text: coordinator.formatWaitAgentOutcome(outcome),
 					},
 				],
-				details: { kind: "control", action: "send", agentId: params.subagent_id } satisfies ControlDetails,
+				details: {
+					kind: "control",
+					action: "wait",
+					timedOut: outcome.timedOut,
+					completionIds: outcome.updates.map(
+						(update) => update.completionId,
+					),
+					unreadUpdates: outcome.unreadUpdates,
+				} satisfies ControlDetails,
 			};
 		},
 	});
@@ -247,10 +334,18 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			assertBackgroundControlsEnabled(sessionSettings, "interrupt_agent");
 			const parent = await coordinator.parentFromContext(ctx);
-			await coordinator.interrupt(parent, params.agent_id);
+			const outcome = await coordinator.interruptWithOutcome(
+				parent,
+				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,
 			};
 		},
 	});
@@ -260,7 +355,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		label: "List Agents",
 		description:
 			"List direct continuable children or all descendants. running means an active turn, idle means resident between turns, " +
-			"and ready means persisted and cold-resumable.",
+			"ready means persisted and cold-resumable, and children show pending task messages separately from unread completion updates.",
 		promptSnippet: "List continuable child agents and their lifecycle status",
 		parameters: ListAgentsParameters,
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -275,7 +370,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	for (const customType of [REPORT_CUSTOM_TYPE, SETTLED_CUSTOM_TYPE]) {
+	for (const customType of [REPORT_CUSTOM_TYPE]) {
 		pi.registerMessageRenderer<ParentMessageDetails>(customType, (message, options, theme) => {
 			const content =
 				typeof message.content === "string"
@@ -300,18 +395,19 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				);
 			const parent = await coordinator.parentFromContext(ctx);
 			const entries = await coordinator.list(parent, "descendants");
-			const schedulingMode = !sessionSettings.enableRunInBackground
-				? "foreground-only"
-				: sessionSettings.defaultBackground
-					? "background-first"
-					: "foreground-first";
 			const sections = [
-				`Mode: ${schedulingMode}`,
+				`Mode: ${sessionSettings.runtimeMode}`,
+				`Background concurrency: ${sessionSettings.maxConcurrentBackgroundRuns}`,
+				`Idle runtime LRU: ${sessionSettings.maxIdleRuntimes}`,
+				"Background protocol: durable mailbox",
 				`OpenAI identity inline: ${sessionSettings.openAIIdentity ? "enabled" : "disabled"}`,
-				sessionSettings.syncBundledAgents
-					? `Bundled presets: synchronized to ${agentSync?.userAgentsDir ?? coordinator.getUserAgentsDir()}`
-					: "Bundled presets: package defaults (no filesystem sync)",
+				agentSync?.diagnostics.length
+					? "Bundled templates: initialization skipped (see diagnostics)"
+					: `Bundled templates: initialization only (${agentSync?.packageVersion ?? "not initialized"})`,
 				`User agent dir: ${agentSync?.userAgentsDir ?? coordinator.getUserAgentsDir()}`,
+				agentSync && agentSync.retired.length > 0
+					? `Deleted presets (never restored): ${agentSync.retired.join(", ")}`
+					: null,
 				`Agents:\n${formatAgentCatalog(discovery.agents)}`,
 				`Children:\n${coordinator.formatCatalog(entries, "descendants")}`,
 			];
@@ -324,10 +420,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_start", async (_event, ctx) => {
 		const loaded = loadSettings({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() });
+		coordinator.configureBackgroundRuns(
+			loaded.settings.maxConcurrentBackgroundRuns,
+		);
+		await coordinator.configureIdleRuntimes(
+			loaded.settings.maxIdleRuntimes,
+		);
 		sessionSettings = loaded.settings;
-		agentSync = sessionSettings.syncBundledAgents
-			? coordinator.synchronizeBundledAgents()
-			: undefined;
+		agentSync = coordinator.synchronizeBundledAgents();
 		sessionDiscovery = coordinator.discoverAvailableAgents(
 			ctx.cwd,
 			sessionSettings,
@@ -346,7 +446,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		if (sessionDiscovery.agents.length === 0) {
 			disableOwnedTools(pi, registeredParameters);
 		}
-		if (!sessionSettings.enableRunInBackground) {
+		if (sessionSettings.runtimeMode === "foreground") {
 			disableOwnedTools(pi, backgroundControlParameters);
 		}
 		if (!agentSyncNotified && agentSync) {
@@ -361,6 +461,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			if (agentSync.removed.length > 0) {
 				lines.push(`retired: ${agentSync.removed.join(", ")}`);
 			}
+			if (agentSync.retirementChanged && agentSync.retired.length > 0) {
+				lines.push(
+					`deleted by you (not restored): ${agentSync.retired.join(", ")}`,
+				);
+			}
+			if (agentSync.restored.length > 0) {
+				lines.push(`restored as managed presets: ${agentSync.restored.join(", ")}`);
+			}
 			if (agentSync.backups.length > 0) {
 				lines.push("backups:", ...agentSync.backups.map((backup) => `- ${backup.name}: ${backup.path}`));
 			}
@@ -368,6 +476,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				agentSync.installed.length > 0 ||
 				agentSync.updated.length > 0 ||
 				agentSync.removed.length > 0 ||
+				(agentSync.retirementChanged && agentSync.retired.length > 0) ||
+				agentSync.restored.length > 0 ||
 				agentSync.backups.length > 0
 			) {
 				ctx.ui.notify(lines.join("\n"), "info");
@@ -378,6 +488,14 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 	});
 
+	pi.on("agent_end", async (_event, ctx) => {
+		const parent = await coordinator.parentFromContext(ctx);
+		await coordinator.releaseWaitAgentDeliveries(
+			parent,
+			"parent agent turn ended without a durable wait_agent result",
+		);
+	});
+
 	pi.on("session_shutdown", async () => {
 		await coordinator.shutdown();
 	});