@selesai/code 0.8.3 → 0.8.4

package/dist/extensions/pi-subagents/src/runs/background/subagent-runner.ts

@@ -5,6 +5,8 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { Message } from "@earendil-works/pi-ai";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { createFileCoalescer } from "../../shared/file-coalescer.ts";
+import { isActiveAsyncState, updateActiveRunIndex } from "./active-run-index.ts";
 import { createChildTranscriptWriter, type ChildTranscriptWriter } from "../../shared/child-transcript.ts";
 import { closeSteerInbox, consumeInterruptRequest, consumeSteerRequests, deliverInterruptRequest, deliverStopRequest, deliverTimeoutRequest, enqueueStepSteer, steerAcksDir, steerCapabilityPath, stepSteerInboxDir, watchAsyncControlInbox, type SteerAck, type SteerCapability, type SteerRequest } from "./control-channel.ts";
 import { appendJsonl as appendRawJsonl, formatOutputArtifactContent, getArtifactPaths, writeArtifact, writeMetadata } from "../../shared/artifacts.ts";
@@ -69,7 +71,7 @@ import {
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir, projectLaunchResolvedChildExtensions, resolvePiLaunchToolPlan } from "../shared/pi-args.ts";
 import { readRuntimeAcknowledgedExtensions } from "../shared/runtime-acknowledged-extensions.ts";
 import { outputEntryFromAsyncResult, resolveOutputReferences } from "../shared/chain-outputs.ts";
-import { createStructuredOutputRuntime, readStructuredOutput } from "../shared/structured-output.ts";
+import { createStructuredOutputRuntime, MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput } from "../shared/structured-output.ts";
 import { formatProcessSignalError, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { collectDynamicResults, DynamicFanoutError, materializeDynamicParallelStep, validateDynamicCollection } from "../shared/dynamic-fanout.ts";
@@ -503,6 +505,8 @@ interface RunPiStreamingResult {
 	toolBudget?: ToolBudgetState;
 	toolBudgetBlocked?: boolean;
 	observedMutationAttempt?: boolean;
+	structuredOutputToolInvoked?: boolean;
+	structuredOutputMessageStartIndex?: number;
 	watchdog?: ChildWatchdogStateSnapshot;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	processInstanceId: string;
@@ -568,6 +572,8 @@ function runPiStreaming(
 		let turnBudgetMessage: string | undefined;
 		let turnBudget: TurnBudgetState | undefined;
 		let observedMutationAttempt = false;
+		let structuredOutputToolInvoked = false;
+		let structuredOutputMessageStartIndex: number | undefined;
 		let toolCount = 0;
 		const childWatchdogConfig = decodeChildWatchdogConfig(env?.[CHILD_WATCHDOG_CONFIG_ENV]);
 		let childWatchdogState: ChildWatchdogStateSnapshot | undefined;
@@ -658,6 +664,10 @@ function runPiStreaming(
 
 			if (event.type === "tool_execution_start" && event.toolName) {
 				toolCount += 1;
+				if (event.toolName === "structured_output") {
+					structuredOutputToolInvoked = true;
+					structuredOutputMessageStartIndex = messages.length;
+				}
 				observedMutationAttempt = observedMutationAttempt || isMutatingTool(event.toolName, event.args);
 				const toolArgs = extractToolArgsPreview(event.args ?? {});
 				writeOutputLine(toolArgs ? `${event.toolName}: ${toolArgs}` : event.toolName);
@@ -923,6 +933,8 @@ function runPiStreaming(
 				turnBudgetExceeded,
 				wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined,
 				observedMutationAttempt,
+				structuredOutputToolInvoked,
+				structuredOutputMessageStartIndex,
 				watchdog: childWatchdogState,
 				processInstanceId,
 				processCloseObservedAt,
@@ -949,7 +961,7 @@ function runPiStreaming(
 			const stderr = stderrTail.text();
 			const finalOutput = getFinalOutput(messages) || rawStdoutTail.text().trim();
 			const spawnErrorMessage = spawnError instanceof Error ? spawnError.message : String(spawnError);
-			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, watchdog: childWatchdogState, processInstanceId }));
+			resolve(omitUndefinedProperties({ stderr, exitCode: 1, messages, usage, toolCount, durationMs: Date.now() - startedAt, model, error: stopped ? (stopMessage ?? "Subagent stopped by user.") : timedOut ? (timeoutMessage ?? "Subagent timed out.") : turnBudgetExceeded ? turnBudgetMessage : error ?? assistantError ?? spawnErrorMessage, protocolError, finalOutput: (timedOut || stopped) && !finalOutput.trim() ? (stopped ? stopMessage ?? "Subagent stopped by user." : timeoutMessage ?? "Subagent timed out.") : finalOutput, outputState: finalOutput.trim() ? "present" : "absent", timedOut, stopped, turnBudget, turnBudgetExceeded, wrapUpRequested: turnBudget?.outcome === "wrap-up-requested" || turnBudget?.outcome === "termination-deferred" || turnBudgetExceeded || undefined, observedMutationAttempt, structuredOutputToolInvoked, structuredOutputMessageStartIndex, watchdog: childWatchdogState, processInstanceId }));
 		});
 	});
 }
@@ -976,7 +988,7 @@ async function exportSessionHtml(sessionFile: string, outputDir: string, piPacka
 
 function createShareLink(htmlPath: string): { shareUrl: string; gistUrl: string } | { error: string } {
 	try {
-		const auth = spawnSync("gh", ["auth", "status"], { encoding: "utf-8", windowsHide: true });
+		const auth = spawnSync("gh", ["auth", "status"], { encoding: "utf-8" });
 		if (auth.status !== 0) {
 			return { error: "GitHub CLI is not logged in. Run 'gh auth login' first." };
 		}
@@ -985,7 +997,7 @@ function createShareLink(htmlPath: string): { shareUrl: string; gistUrl: string
 	}
 
 	try {
-		const result = spawnSync("gh", ["gist", "create", htmlPath], { encoding: "utf-8", windowsHide: true });
+		const result = spawnSync("gh", ["gist", "create", htmlPath], { encoding: "utf-8" });
 		if (result.status !== 0) {
 			const err = (result.stderr || "").trim() || "Failed to create gist.";
 			return { error: err };
@@ -1444,31 +1456,42 @@ async function runSingleStep(
 		const runtimeAcknowledgedExtensions = readRuntimeAcknowledgedExtensions(runtimeAcknowledgedExtensionsPath);
 		cleanupTempDir(tempDir);
 
-		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError ? detectSubagentError(run.messages) : null;
-		const missingStructuredOutput = effectiveStructuredOutput
-			? !fs.existsSync(effectiveStructuredOutput.outputPath)
-			: false;
+		let structuredOutput: unknown;
+		let structuredError: string | undefined;
+		let validatedStructuredOutput = false;
+		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError) {
+			if (!run.structuredOutputToolInvoked) {
+				structuredError = MISSING_STRUCTURED_OUTPUT_CALL_ERROR;
+			} else {
+				const structured = await readStructuredOutput({
+					schema: effectiveStructuredOutput.schema,
+					schemaPath: effectiveStructuredOutput.schemaPath,
+					outputPath: effectiveStructuredOutput.outputPath,
+				});
+				if (structured.error) structuredError = structured.error;
+				else {
+					structuredOutput = structured.value;
+					validatedStructuredOutput = true;
+				}
+			}
+		}
+		const errorMessages = validatedStructuredOutput
+			? run.messages.slice(run.structuredOutputMessageStartIndex ?? run.messages.length)
+			: run.messages;
+		const hiddenError = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError
+			? detectSubagentError(errorMessages)
+			: null;
 		const emptyOutputError = run.exitCode === 0
 			&& !run.error
 			&& !toolAvailabilityError
+			&& !structuredError
 			&& !run.finalOutput.trim()
-			&& (!effectiveStructuredOutput || missingStructuredOutput)
+			&& !validatedStructuredOutput
 			&& (!hiddenError?.hasError || hasEmptyTerminalAssistantResponse(run.messages))
 			? "Subagent produced no output (possible model cold-start or empty response)."
 			: undefined;
-		let structuredOutput: unknown;
-		let structuredError: string | undefined;
-		if (effectiveStructuredOutput && run.exitCode === 0 && !run.error && !toolAvailabilityError && !hiddenError?.hasError && !emptyOutputError) {
-			const structured = await readStructuredOutput({
-				schema: effectiveStructuredOutput.schema,
-				schemaPath: effectiveStructuredOutput.schemaPath,
-				outputPath: effectiveStructuredOutput.outputPath,
-			});
-			if (structured.error) structuredError = structured.error;
-			else structuredOutput = structured.value;
-		}
 		const completionGuardEnabled = isAgentContractV1(step.agentContract) ? step.completionGuard === true : step.completionGuard !== false;
-		const completionGuard = run.exitCode === 0 && !run.error && !toolAvailabilityError && !hiddenError?.hasError && !emptyOutputError && completionGuardEnabled
+		const completionGuard = run.exitCode === 0 && !run.error && !toolAvailabilityError && !structuredError && !hiddenError?.hasError && !emptyOutputError && completionGuardEnabled
 			? evaluateCompletionMutationGuard(omitUndefinedProperties({
 				agent: step.agent,
 				task: taskForCompletionGuard,
@@ -1635,6 +1658,8 @@ async function runSingleStep(
 			signal: combinedAbortSignal([ctx.timeoutSignal, ctx.stopSignal]),
 			abortMessage: ctx.stopSignal?.aborted ? ctx.stopMessage ?? "Subagent stopped by user." : ctx.timeoutMessage ?? "Subagent timed out.",
 			reportOptional: isAgentContractV1(step.agentContract),
+			artifactsDir: ctx.artifactsDir,
+			runId: ctx.id,
 		}))
 		: undefined;
 	const stoppedAfterAcceptance = finalResult?.stopped === true || ctx.stopSignal?.aborted === true;
@@ -1932,6 +1957,47 @@ function combinedAbortSignal(signals: Array<AbortSignal | undefined>): AbortSign
 	return controller.signal;
 }
 
+async function runSingleStepWithTimeout(
+	step: SubagentStep,
+	ctx: SingleStepContext,
+	parentDeadlineAt?: number,
+): Promise<SingleStepResult> {
+	if (step.timeoutMs === undefined) return runSingleStep(step, ctx);
+
+	const parentRemainingMs = parentDeadlineAt === undefined ? undefined : Math.max(0, parentDeadlineAt - Date.now());
+	const timeoutMs = parentRemainingMs === undefined ? step.timeoutMs : Math.min(step.timeoutMs, parentRemainingMs);
+	const timeoutMessage = parentRemainingMs !== undefined && parentRemainingMs <= step.timeoutMs
+		? ctx.timeoutMessage
+		: `Subagent timed out after ${step.timeoutMs}ms.`;
+	const timeoutController = new AbortController();
+	let timeoutAction: (() => void) | undefined;
+	let timeoutTriggered = false;
+	const triggerTimeout = (): void => {
+		if (timeoutTriggered) return;
+		timeoutTriggered = true;
+		timeoutController.abort();
+		timeoutAction?.();
+	};
+	const registerTimeout = (action: (() => void) | undefined): void => {
+		timeoutAction = action;
+		ctx.registerTimeout?.(action ? triggerTimeout : undefined);
+		if (action && timeoutTriggered) action();
+	};
+	const timer = setTimeout(triggerTimeout, timeoutMs);
+	timer.unref?.();
+	try {
+		return await runSingleStep(step, {
+			...ctx,
+			registerTimeout,
+			timeoutSignal: combinedAbortSignal([ctx.timeoutSignal, timeoutController.signal]),
+			timeoutMessage,
+		});
+	} finally {
+		clearTimeout(timer);
+		ctx.registerTimeout?.(undefined);
+	}
+}
+
 async function runSubagent(
 	config: SubagentRunConfig,
 	onWriterProcess?: (writer: { state: "none" | "spawning" } | { state: "running"; pid: number }) => void,
@@ -2116,6 +2182,7 @@ async function runSubagent(
 
 	fs.mkdirSync(asyncDir, { recursive: true });
 	writeAtomicJson(statusPath, statusPayload);
+	updateActiveRunIndex(asyncDir, statusPayload.state);
 	let pendingParallelUsageCost: CostSummary = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
 	const currentUsageTotals = (): CostSummary => {
 		const cost = results.reduce<CostSummary>((sum, result) => ({
@@ -2188,11 +2255,25 @@ async function runSubagent(
 		for (const node of graph.nodes) updateNode(node);
 		statusPayload.workflowGraph = graph;
 	};
-	const writeStatusPayload = (): void => {
+	let lastIndexedActiveState = isActiveAsyncState(statusPayload.state);
+	const writeStatusPayloadNow = (): void => {
 		refreshWorkflowGraph();
 		writeAtomicJson(statusPath, statusPayload);
+		const activeState = isActiveAsyncState(statusPayload.state);
+		if (activeState !== lastIndexedActiveState) {
+			updateActiveRunIndex(asyncDir, statusPayload.state);
+			lastIndexedActiveState = activeState;
+		}
 		emitNestedSelfEvent(statusPayload.state === "running" || statusPayload.state === "queued" ? "subagent.nested.updated" : "subagent.nested.completed");
 	};
+	const statusWriteCoalescer = createFileCoalescer(writeStatusPayloadNow, 100);
+	const writeStatusPayload = (immediate = true): void => {
+		if (immediate || statusPayload.state !== "running" || statusPayload.activityState !== undefined) {
+			if (!statusWriteCoalescer.flush(statusPath)) writeStatusPayloadNow();
+			return;
+		}
+		statusWriteCoalescer.schedule(statusPath);
+	};
 	const updateExternalProcess = (index: number, process: ExternalProcessStatus): void => {
 		requiredStatusStep(statusPayload, index).externalProcess = process;
 		statusPayload.lastUpdate = Date.now();
@@ -2264,7 +2345,7 @@ async function runSubagent(
 			const nestedAsyncDir = run.asyncDir ?? resolveNestedAsyncDir(config.nestedRoute.rootRunId, run);
 			if (!nestedAsyncDir) continue;
 			try {
-				deliverInterruptRequest(omitUndefinedProperties({ asyncDir: nestedAsyncDir, pid: run.pid, source: "ancestor-interrupt" }));
+				deliverInterruptRequest({ asyncDir: nestedAsyncDir, source: "ancestor-interrupt" });
 			} catch (error) {
 				appendJsonl(eventsPath, JSON.stringify({
 					type: "subagent.nested.interrupt_failed",
@@ -2611,7 +2692,10 @@ async function runSubagent(
 		const now = Date.now();
 		if (ack.state === "delivered") {
 			updateSteeringLifecycleTarget(ack.requestId, ack.index, late ? "late" : "delivered", now, omitUndefinedProperties({ reason: late ? "acknowledged after recovery commit" : undefined }));
-			emitSteeringEvent("subagent.steer.delivered", { type: "steer", id: ack.requestId, ts: now, message: ack.message }, ack.index, { late, message: ack.message });
+			emitSteeringEvent("subagent.steer.delivered", { type: "steer", id: ack.requestId, ts: now, message: ack.message }, ack.index, { late, deliveryStatus: "delivered", message: ack.message });
+		} else if (ack.state === "queued") {
+			updateSteeringLifecycleTarget(ack.requestId, ack.index, "queued", now);
+			emitSteeringEvent("subagent.steer.queued", { type: "steer", id: ack.requestId, ts: now, message: ack.message }, ack.index, { deliveryStatus: "queued", message: ack.message });
 		} else {
 			markSteeringAttention(ack.index);
 			updateSteeringLifecycleTarget(ack.requestId, ack.index, "failed", now, { reason: ack.message });
@@ -2716,7 +2800,7 @@ async function runSubagent(
 			step.lastActivityAt = now;
 			statusPayload.lastActivityAt = now;
 			statusPayload.lastUpdate = now;
-			writeStatusPayload();
+			writeStatusPayload(false);
 			return;
 		}
 		if (event.type === "tool_execution_start" && event.toolName) {
@@ -2852,7 +2936,7 @@ async function runSubagent(
 		statusPayload.lastActivityAt = now;
 		statusPayload.lastUpdate = now;
 		maybeEmitActiveLongRunning(flatIndex, now);
-		writeStatusPayload();
+		writeStatusPayload(false);
 	};
 	const updateRunnerActivityState = (now: number): boolean => {
 		if (!controlConfig.enabled) return false;
@@ -3423,7 +3507,7 @@ async function runSubagent(
 				writeStatusPayload();
 				appendJsonl(eventsPath, JSON.stringify({ type: "subagent.step.started", ts: taskStartTime, runId: id, stepIndex: fi, agent: task.agent }));
 				flushPendingStepSteers(fi);
-				const singleResult = await runSingleStep(task, compactOptional<SingleStepContext>({
+				const singleResult = await runSingleStepWithTimeout(task, compactOptional<SingleStepContext>({
 					previousOutput, placeholder, cwd, sessionEnabled,
 					outputs,
 					sessionDir: config.sessionDir ? path.join(config.sessionDir, `dynamic-${stepIndex}-${taskIdx}`) : undefined,
@@ -3453,7 +3537,7 @@ async function runSubagent(
 					onWriterProcess,
 					onExternalProcess: (process) => updateExternalProcess(fi, process),
 					skipAcceptance: () => timedOut || stopped,
-				}));
+				}), config.deadlineAt);
 				const taskEndTime = Date.now();
 				const childInterrupted = singleResult.interrupted === true;
 				const childStopped = singleResult.stopped === true;
@@ -3805,7 +3889,7 @@ async function runSubagent(
 						const { taskForRun, taskCwd } = prepareParallelTaskRun(task, cwd, worktreeSetup, taskIdx);
 						flushPendingStepSteers(fi);
 
-						const singleResult = await runSingleStep(taskForRun, compactOptional<SingleStepContext>({
+						const singleResult = await runSingleStepWithTimeout(taskForRun, compactOptional<SingleStepContext>({
 							previousOutput, placeholder, cwd: taskCwd, sessionEnabled,
 							outputs,
 							sessionDir: taskSessionDir,
@@ -3835,7 +3919,7 @@ async function runSubagent(
 							onWriterProcess,
 							onExternalProcess: (process) => updateExternalProcess(fi, process),
 							skipAcceptance: () => timedOut || stopped,
-						}));
+						}), config.deadlineAt);
 						if (task.sessionFile) {
 							latestSessionFile = task.sessionFile;
 						}
@@ -4094,7 +4178,7 @@ async function runSubagent(
 			}));
 
 			flushPendingStepSteers(flatIndex);
-			const singleResult = await runSingleStep(seqStep, compactOptional<SingleStepContext>({
+			const singleResult = await runSingleStepWithTimeout(seqStep, compactOptional<SingleStepContext>({
 				previousOutput, placeholder, cwd, sessionEnabled,
 				outputs: statusPayload.mode === "single" ? undefined : outputs,
 				sessionDir: config.sessionDir,
@@ -4124,7 +4208,7 @@ async function runSubagent(
 				onWriterProcess,
 				onExternalProcess: (process) => updateExternalProcess(flatIndex, process),
 				skipAcceptance: () => timedOut || stopped,
-			}));
+			}), config.deadlineAt);
 			if (seqStep.sessionFile) {
 				latestSessionFile = seqStep.sessionFile;
 			}
@@ -4370,11 +4454,12 @@ async function runSubagent(
 	for (const request of steeringLifecycle.recent) {
 		let changed = false;
 		for (const target of request.targets) {
-			if (target.state !== "scheduled" && target.state !== "routed") continue;
+			if (target.state !== "scheduled" && target.state !== "routed" && target.state !== "queued") continue;
 			changed = true;
-			updateSteeringLifecycleTarget(request.id, target.index, "failed", Date.now(), { reason: "child terminated before steering delivery" });
+			const reason = target.state === "queued" ? "run ended before queued follow-up delivery" : "child terminated before steering delivery";
+			updateSteeringLifecycleTarget(request.id, target.index, "failed", Date.now(), { reason });
 			markSteeringAttention(target.index);
-			emitSteeringEvent("subagent.steer.failed", { type: "steer", id: request.id, ts: request.requestedAt, message: "child terminated before steering delivery" }, target.index, { reason: "child terminated before steering delivery" });
+			emitSteeringEvent("subagent.steer.failed", { type: "steer", id: request.id, ts: request.requestedAt, message: reason }, target.index, { reason });
 		}
 		if (changed) emitTerminalSteeringNotice(request.id, `Steering failed for run ${id}: child terminated before delivery.`);
 	}
@@ -4413,39 +4498,6 @@ async function runSubagent(
 		}
 	}
 	writeStatusPayload();
-	appendJsonl(
-		eventsPath,
-		JSON.stringify({
-			type: "subagent.run.completed",
-			lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
-			ts: runEndedAt,
-			runId: id,
-			status: statusPayload.state,
-			durationMs: runEndedAt - overallStartTime,
-			totalTokens: statusPayload.totalTokens,
-			totalCost: finalTotalCost,
-			usageBudget: statusPayload.usageBudget,
-		}),
-	);
-	writeRunLog(logPath, omitUndefinedProperties({
-		id,
-		mode: statusPayload.mode,
-		cwd,
-		startedAt: overallStartTime,
-		endedAt: runEndedAt,
-		steps: statusPayload.steps.map((step) => omitUndefinedProperties({
-			agent: step.agent,
-			status: step.status,
-			durationMs: step.durationMs,
-		})),
-		summary,
-		truncated,
-		artifactsDir,
-		sessionFile: effectiveSessionFile,
-		shareUrl,
-		shareError,
-	}));
-
 	try {
 		writeAtomicJson(resultPath, {
 			lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
@@ -4545,6 +4597,38 @@ async function runSubagent(
 	} catch (err) {
 		console.error(`Failed to write result file ${resultPath}:`, err);
 	}
+	appendJsonl(
+		eventsPath,
+		JSON.stringify({
+			type: "subagent.run.completed",
+			lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+			ts: runEndedAt,
+			runId: id,
+			status: statusPayload.state,
+			durationMs: runEndedAt - overallStartTime,
+			totalTokens: statusPayload.totalTokens,
+			totalCost: finalTotalCost,
+			usageBudget: statusPayload.usageBudget,
+		}),
+	);
+	writeRunLog(logPath, omitUndefinedProperties({
+		id,
+		mode: statusPayload.mode,
+		cwd,
+		startedAt: overallStartTime,
+		endedAt: runEndedAt,
+		steps: statusPayload.steps.map((step) => omitUndefinedProperties({
+			agent: step.agent,
+			status: step.status,
+			durationMs: step.durationMs,
+		})),
+		summary,
+		truncated,
+		artifactsDir,
+		sessionFile: effectiveSessionFile,
+		shareUrl,
+		shareError,
+	}));
 	if (config.runnerProcessInstanceId) {
 		const writers: Record<string, Array<{ processInstanceId: string; kind: "pi-writer"; attempt: number; closeObservedAt: number; exitCode: number | null; signal: string | null }>> = {};
 		const expectedWriters: Record<string, number> = {};

package/dist/extensions/pi-subagents/src/runs/background/subagent-wait.ts

@@ -58,8 +58,11 @@ import {
 	type Details,
 	type ForegroundResumeRun,
 	type SubagentState,
+	type WaitCompletion,
 } from "../../shared/types.ts";
 import { formatDuration, shortenPath } from "../../shared/formatters.ts";
+import { collectWaitCompletions } from "./wait-completions.ts";
+import { formatResumeFirstFailedRunsNote } from "./resume-guidance.ts";
 export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
 
 /** States that mean a run is still in flight (not yet resolved). */
@@ -303,11 +306,15 @@ function summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount =
 	return parts.join(", ");
 }
 
-function result(text: string, isError = false): AgentToolResult<Details> {
+function result(text: string, isError = false, completions?: WaitCompletion[]): AgentToolResult<Details> {
 	return {
 		content: [{ type: "text", text }],
 		...(isError ? { isError: true } : {}),
-		details: { mode: "management", results: [] },
+		details: {
+			mode: "management",
+			results: [],
+			...(completions && completions.length > 0 ? { completions } : {}),
+		},
 	};
 }
 
@@ -597,6 +604,8 @@ export async function waitForSubagents(
 	let terminalSummary: string;
 	let finishedAsyncCount: number;
 	let failedAsyncCount: number;
+	let completions: WaitCompletion[] | undefined;
+	let resumeGuidance = "";
 	const activeProviderIds = new Set(providerActive.map(backgroundWorkIdentity));
 	const providerFinishedCount = [...initialProviderIds].filter((id) => !activeProviderIds.has(id)).length;
 	try {
@@ -605,6 +614,8 @@ export async function waitForSubagents(
 		finishedAsyncCount = terminal.length;
 		failedAsyncCount = terminal.filter((run) => run.state === "failed").length;
 		terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
+		resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
+		completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
 	} catch (error) {
 		return result(error instanceof Error ? error.message : String(error), true);
 	}
@@ -629,8 +640,9 @@ export async function waitForSubagents(
 				: `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
 		const status = relevantAttention.length > 0 ? "attention required" : "done";
 		return result(
-			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
+			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
 			deps.failOnFailedRuns === true && failedAsyncCount > 0,
+			completions,
 		);
 	}
 
@@ -645,7 +657,8 @@ export async function waitForSubagents(
 		? `${relevantAttention.length} of ${initialCount} ${subject} need attention`
 		: `${finishedCount} of ${initialCount} ${subject} finished`;
 	return result(
-		`Waited ${elapsed}; ${progress}.${outcome}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
+		`Waited ${elapsed}; ${progress}.${outcome}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
 		deps.failOnFailedRuns === true && failedAsyncCount > 0,
+		completions,
 	);
 }

package/dist/extensions/pi-subagents/src/runs/background/wait-completions.ts

@@ -0,0 +1,146 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ArtifactPaths, SubagentState, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
+import type { AsyncRunSummary } from "./async-status.ts";
+import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
+
+function asNonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value ? value : undefined;
+}
+
+function errorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error
+		? (error as NodeJS.ErrnoException).code
+		: undefined;
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Project a terminal result payload into the slim shape that is safe to surface in
+ * tool_result details: run identity, per-child outcome, and the artifact trail.
+ * Output text is deliberately excluded — it already travels in the tool result
+ * content, and duplicating it in details would double the payload for every wait.
+ */
+export function toWaitCompletion(data: Record<string, unknown>, runId: string): WaitCompletion {
+	const results = Array.isArray(data.results)
+		? data.results.flatMap((entry): WaitCompletionChild[] => {
+			if (entry === null || typeof entry !== "object") return [];
+			const child = entry as Record<string, unknown>;
+			const outputState = child.outputState === "present" || child.outputState === "absent" || child.outputState === "unknown"
+				? child.outputState
+				: undefined;
+			const artifactPaths = child.artifactPaths !== null && typeof child.artifactPaths === "object"
+				? (child.artifactPaths as Partial<ArtifactPaths>)
+				: undefined;
+			const agent = asNonEmptyString(child.agent);
+			const childRunId = asNonEmptyString(child.runId);
+			const error = asNonEmptyString(child.error);
+			const model = asNonEmptyString(child.model);
+			return [{
+				...(agent ? { agent } : {}),
+				...(childRunId ? { runId: childRunId } : {}),
+				...(typeof child.success === "boolean" ? { success: child.success } : {}),
+				...(outputState ? { outputState } : {}),
+				...(error ? { error } : {}),
+				...(model ? { model } : {}),
+				...(artifactPaths ? { artifactPaths } : {}),
+			}];
+		})
+		: undefined;
+	const agent = asNonEmptyString(data.agent);
+	const mode = asNonEmptyString(data.mode);
+	const state = asNonEmptyString(data.state);
+	return {
+		runId,
+		...(agent ? { agent } : {}),
+		...(mode ? { mode } : {}),
+		...(state ? { state } : {}),
+		...(typeof data.success === "boolean" ? { success: data.success } : {}),
+		...(results && results.length > 0 ? { results } : {}),
+	};
+}
+
+/**
+ * Record a consumed terminal payload for later surfacing by subagent_wait, pruning
+ * stale entries with the same TTL that dedupes completion notifications. The result
+ * file is deleted after delivery, so this record is the only in-process source once
+ * the watcher has consumed it.
+ */
+export function recordWaitCompletion(
+	state: SubagentState,
+	runId: string,
+	data: Record<string, unknown>,
+	now: number,
+	ttlMs: number,
+	persistence?: { resultsDir: string; sessionId: string },
+): void {
+	const store = state.completedResults ??= new Map();
+	for (const [key, entry] of store) {
+		if (now - entry.seenAt > ttlMs) store.delete(key);
+	}
+	let completion = toWaitCompletion(data, runId);
+	if (persistence) {
+		try {
+			completion = writeCompletionReplay({
+				...persistence,
+				runId,
+				completion,
+				data,
+				now,
+				ttlMs,
+			}).completion;
+		} catch (error) {
+			console.error(`Failed to persist completion replay for '${runId}':`, error);
+		}
+	}
+	store.set(runId, { seenAt: now, completion });
+}
+
+/**
+ * Terminal payloads for the runs a wait covered: the watcher's in-memory record
+ * first, then the not-yet-consumed result file. Result files are written atomically,
+ * so a direct read never observes a torn write; the read is deliberately read-only —
+ * the watcher owns notification and cleanup.
+ */
+export function collectWaitCompletions(terminal: AsyncRunSummary[], state: SubagentState, resultsDir: string): WaitCompletion[] | undefined {
+	if (terminal.length === 0) return undefined;
+	const completions: WaitCompletion[] = [];
+	for (const run of terminal) {
+		const recorded = state.completedResults?.get(run.id);
+		if (recorded) {
+			completions.push(recorded.completion);
+			continue;
+		}
+		const resultPath = path.join(resultsDir, `${run.id}.json`);
+		try {
+			const raw = JSON.parse(fs.readFileSync(resultPath, "utf-8")) as Record<string, unknown>;
+			completions.push(toWaitCompletion(raw, run.id));
+		} catch (error) {
+			if (errorCode(error) !== "ENOENT") {
+				throw new Error(`Failed to read subagent result '${resultPath}': ${errorMessage(error)}`, {
+					cause: error instanceof Error ? error : undefined,
+				});
+			}
+			// The watcher may have consumed the file between the store check and the
+			// read. Prefer its in-memory record, then the durable replay written before
+			// result cleanup so watcher reloads do not lose completion details.
+			const late = state.completedResults?.get(run.id);
+			if (late) {
+				completions.push(late.completion);
+				continue;
+			}
+			try {
+				const replay = readCompletionReplay(resultsDir, run.id, { sessionId: run.sessionId });
+				if (replay) completions.push(replay.completion);
+			} catch (replayError) {
+				throw new Error(`Failed to read completion replay for '${run.id}': ${errorMessage(replayError)}`, {
+					cause: replayError instanceof Error ? replayError : undefined,
+				});
+			}
+		}
+	}
+	return completions.length > 0 ? completions : undefined;
+}