pi-subagents 0.49.0 → 0.50.0

package/src/runs/background/result-watcher.ts

@@ -22,12 +22,14 @@ import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-
 import { resolveWatchPath } from "../../shared/utils.ts";
 import { recordWaitCompletion } from "./wait-completions.ts";
 import { MISSION_BINDING_FILE, syncMissionFromAsyncCompletion } from "../../missions/lifecycle.ts";
+import { missionObserverResultCandidateFiles, promotePendingResultFile, removeMissionObserverIndex, removeResultIndex, resultCandidateFilesForSession, resultPayloadPathForIndexedRun, resultPayloadPathForMissionObserverRun, resultPayloadPathForSessionRun, writeAsyncResultFile, writeResultIndexForData } from "./result-files.ts";
 import type { CompletionNotifier, CompletionNotification } from "./notify.ts";
 
 const WATCHER_RESTART_DELAY_MS = 3000;
 const POLL_INTERVAL_MS = 3000;
 const HEALTHY_SCAN_INTERVAL_MS = 60_000;
 const RETRY_DELAY_MS = 100;
+const SLOW_RESULT_SCAN_MS = 500;
 
 type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "realpathSync" | "statSync" | "watch">;
 
@@ -50,6 +52,8 @@ type ResultWatcherDeps = {
 	parseResult?: (raw: string) => ResultFileData;
 	/** External grouped-result transport. Disable when native completion notifications own delivery. */
 	deliverIntercomResults?: boolean;
+	/** Coalesces result-file events. Tests can lower this without changing retry timing. */
+	coalesceDelayMs?: number;
 };
 
 type ResultFileChild = {
@@ -79,6 +83,7 @@ type ResultFileData = CompletionNotification & {
 	asyncDir?: string;
 	intercomTarget?: string;
 	parallelHandoff?: ParallelHandoffReference;
+	notificationDeliveredAt?: unknown;
 };
 
 type ResultFileIdentity = {
@@ -87,6 +92,12 @@ type ResultFileIdentity = {
 	asyncDir?: string;
 };
 
+interface ResultScanStats {
+	files: number;
+	scheduled: number;
+	startedAt: number;
+}
+
 function jsonStringProperty(raw: string, property: string): string | undefined {
 	const matches = raw.matchAll(new RegExp(`"${property}"\\s*:\\s*("(?:\\\\.|[^"\\\\])*")`, "g"));
 	let encoded: string | undefined;
@@ -134,6 +145,16 @@ function shouldPoll(error: unknown): boolean {
 	return code === "EMFILE" || code === "ENOSPC";
 }
 
+function hasDeliveredNotification(data: ResultFileData): boolean {
+	return typeof data.notificationDeliveredAt === "number" && Number.isFinite(data.notificationDeliveredAt);
+}
+
+function markDeliveredNotification(resultPath: string, data: ResultFileData, runId: string, now: number): ResultFileData {
+	const marked = { ...data, runId, notificationDeliveredAt: now };
+	writeAsyncResultFile(resultPath, marked);
+	return marked;
+}
+
 /**
  * Watches persisted async results for the session currently owned by this
  * runtime. `stopResultWatcher()` revokes ownership before closing resources,
@@ -177,16 +198,55 @@ export function createResultWatcher(
 		state.resultFileCoalescer.schedule(file, delayMs);
 	};
 
-	const inspectResult = (file: string): ResultFileIdentity | undefined => {
-		const resultPath = path.join(resultsDir, file);
+	const publicResultPath = (file: string): string => path.join(resultsDir, file);
+	const publicResultFileExists = (file: string): boolean => {
+		try {
+			return fsApi.statSync(publicResultPath(file)).isFile();
+		} catch (error) {
+			if (!isNotFound(error)) console.error(`Failed to inspect subagent result file '${publicResultPath(file)}':`, error);
+			return false;
+		}
+	};
+	const resultPayloadPath = (file: string, observed?: ReadonlySet<string>): string | undefined => {
+		if (file !== path.basename(file) || !file.endsWith(".json")) return undefined;
+		const runId = file.replace(/\.json$/i, "");
+		const sessionResult = state.currentSessionId ? resultPayloadPathForSessionRun(resultsDir, state.currentSessionId, runId) : undefined;
+		if (sessionResult) return sessionResult;
+		const observerResult = resultPayloadPathForMissionObserverRun(resultsDir, runId);
+		if (observerResult) return observerResult;
+		if (observed?.has(runId)) {
+			const indexedResult = resultPayloadPathForIndexedRun(resultsDir, runId);
+			if (indexedResult) return indexedResult;
+		}
+		return publicResultFileExists(file) ? publicResultPath(file) : undefined;
+	};
+	const resultSignature = (file: string, observed?: ReadonlySet<string>): string | undefined => {
+		const resultPath = resultPayloadPath(file, observed);
+		if (!resultPath) {
+			identityCache.delete(file);
+			return undefined;
+		}
 		try {
 			const stat = fsApi.statSync(resultPath);
-			const signature = `${stat.size}:${stat.mtimeMs}`;
+			if (!stat.isFile()) return undefined;
+			return `${resultPath}:${stat.size}:${stat.mtimeMs}`;
+		} catch (error) {
+			identityCache.delete(file);
+			if (!isNotFound(error)) console.error(`Failed to inspect subagent result file '${resultPath}':`, error);
+			return undefined;
+		}
+	};
+	const inspectResult = (file: string, knownSignature?: string, observed?: ReadonlySet<string>): { identity: ResultFileIdentity; signature: string } | undefined => {
+		const resultPath = resultPayloadPath(file, observed);
+		if (!resultPath) return undefined;
+		try {
+			const signature = knownSignature ?? resultSignature(file, observed);
+			if (!signature) return undefined;
 			const cached = identityCache.get(file);
-			if (cached?.signature === signature) return cached.identity;
+			if (cached?.signature === signature) return { identity: cached.identity, signature };
 			const identity = resultFileIdentity(fsApi.readFileSync(resultPath, "utf-8"), file);
 			identityCache.set(file, { signature, identity });
-			return identity;
+			return { identity, signature };
 		} catch (error) {
 			identityCache.delete(file);
 			if (!isNotFound(error)) console.error(`Failed to inspect subagent result file '${resultPath}':`, error);
@@ -203,9 +263,10 @@ export function createResultWatcher(
 		}
 	};
 
-	const shouldProcessResult = (file: string, observed?: ReadonlySet<string>): boolean => {
-		const identity = inspectResult(file);
-		if (!identity) return false;
+	const shouldProcessResult = (file: string, observed?: ReadonlySet<string>, knownSignature?: string): boolean => {
+		const inspected = inspectResult(file, knownSignature, observed);
+		if (!inspected) return false;
+		const { identity } = inspected;
 		// Missing identity stays on the normal parser path so malformed or legacy
 		// files keep their existing diagnostics and compatibility behavior.
 		if (!identity.sessionId) return true;
@@ -215,32 +276,80 @@ export function createResultWatcher(
 		return Boolean(deps.observeCompletion && !deps.observedCompletionRunIds);
 	};
 
+	const removeDeliveredResult = (file: string, sessionId: string, runId: string, toolCallId: string | undefined): boolean => {
+		try {
+			if (publicResultFileExists(file)) fsApi.unlinkSync(publicResultPath(file));
+			identityCache.delete(file);
+			removeResultIndex(resultsDir, sessionId, runId, toolCallId);
+			return true;
+		} catch (error) {
+			if (!isNotFound(error)) {
+				console.error(`Failed to remove delivered subagent result '${publicResultPath(file)}'; will retry:`, error);
+				return false;
+			}
+			return true;
+		}
+	};
 	const handleResult = async (file: string, triggerTurn: boolean) => {
-		const resultPath = path.join(resultsDir, file);
-		if (processing.has(file) || !fsApi.existsSync(resultPath)) return;
-		if (!shouldProcessResult(file)) return;
+		if (processing.has(file)) return;
+		let observed: ReadonlySet<string> | undefined;
+		if (!shouldProcessResult(file)) {
+			const runId = file === path.basename(file) && file.endsWith(".json") ? file.replace(/\.json$/i, "") : undefined;
+			observed = observedRunIds();
+			if (!runId || !observed.has(runId) || !shouldProcessResult(file, observed)) return;
+		}
 		processing.add(file);
+		let resultPath = publicResultPath(file);
 		try {
-			const data = parseResult(fsApi.readFileSync(resultPath, "utf-8"));
+			const payloadPath = resultPayloadPath(file, observed);
+			if (!payloadPath) return;
+			resultPath = payloadPath;
+			let raw = fsApi.readFileSync(resultPath, "utf-8");
+			let identity = resultFileIdentity(raw, file);
+			if (identity.sessionId && identity.runId) {
+				const pendingState = promotePendingResultFile(resultsDir, identity.sessionId, identity.runId, file);
+				if (pendingState === "promoted") {
+					identityCache.delete(file);
+					resultPath = publicResultPath(file);
+					raw = fsApi.readFileSync(resultPath, "utf-8");
+					identity = resultFileIdentity(raw, file);
+				} else if (pendingState === "pending") {
+					const pendingPath = resultPayloadPathForSessionRun(resultsDir, identity.sessionId, identity.runId);
+					if (!pendingPath) {
+						scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
+						return;
+					}
+					resultPath = pendingPath;
+					raw = fsApi.readFileSync(resultPath, "utf-8");
+					identity = resultFileIdentity(raw, file);
+				}
+			}
+			let data = parseResult(raw);
 			if (typeof data.sessionId !== "string" || !data.sessionId) return;
+			const sessionId = data.sessionId;
 			const runId = data.runId ?? data.id ?? file.replace(/\.json$/i, "");
+			const toolCallId = typeof data.toolCallId === "string" ? data.toolCallId : undefined;
+			let observerSucceeded = true;
 			try {
 				syncMissionFromAsyncCompletion({ ...data, runId });
 			} catch (error) {
+				observerSucceeded = false;
 				console.error(`Mission completion sync failed for '${resultPath}':`, error);
 			}
 			try {
 				deps.observeCompletion?.({ ...data, runId });
 			} catch (error) {
+				observerSucceeded = false;
 				console.error(`Completion observer failed for '${resultPath}':`, error);
 			}
+			if (observerSucceeded) removeMissionObserverIndex(resultsDir, runId);
 			const epoch = deliveryEpoch;
-			if (!ownsSession(data.sessionId, epoch)) return;
+			if (!ownsSession(sessionId, epoch)) return;
 			// Recorded before dedupe and before the unlink below so subagent_wait can
 			// use the in-memory record or its bounded durable replay after cleanup.
 			recordWaitCompletion(state, runId, data, Date.now(), completionTtlMs, {
 				resultsDir,
-				sessionId: data.sessionId,
+				sessionId,
 			});
 			const hasExplicitNestedChildren = data.nestedChildren !== undefined;
 			let nestedChildren = compactNestedResultChildren(sanitizeNestedResultChildren(data.nestedChildren, resultPath, "nestedChildren"));
@@ -255,20 +364,17 @@ export function createResultWatcher(
 			}
 
 			const completionKey = buildCompletionKey(data, `result:${file}`);
+			const alreadyDelivered = hasDeliveredNotification(data);
 			const lastSeenAt = state.completionSeen.get(completionKey);
 			if (lastSeenAt !== undefined && Date.now() - lastSeenAt > completionTtlMs) {
 				state.completionSeen.delete(completionKey);
 			} else if (lastSeenAt !== undefined) {
-				if (!ownsSession(data.sessionId, epoch) || !fsApi.existsSync(resultPath)) return;
-				try {
-					fsApi.unlinkSync(resultPath);
-					identityCache.delete(file);
-				} catch (error) {
-					if (!isNotFound(error)) {
-						console.error(`Failed to remove delivered subagent result '${resultPath}'; will retry:`, error);
-						scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
-					}
+				if (!observerSucceeded) {
+					scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
+					return;
 				}
+				if (!ownsSession(sessionId, epoch)) return;
+				if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 				return;
 			}
 
@@ -316,6 +422,17 @@ export function createResultWatcher(
 				};
 			}), nestedChildren);
 
+			if (alreadyDelivered) {
+				markSeenWithTtl(state.completionSeen, completionKey, Date.now(), completionTtlMs);
+				if (!observerSucceeded) {
+					scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
+					return;
+				}
+				if (!ownsSession(sessionId, epoch)) return;
+				if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
+				return;
+			}
+
 			const intercomTarget = data.intercomTarget?.trim();
 			let intercomDelivered = false;
 			if (deliverIntercomResults && intercomTarget && triggerTurn) {
@@ -332,7 +449,7 @@ export function createResultWatcher(
 					asyncDir: data.asyncDir,
 					...(data.parallelHandoff ? { parallelHandoff: data.parallelHandoff } : {}),
 				}));
-				if (!ownsSession(data.sessionId, epoch)) return;
+				if (!ownsSession(sessionId, epoch)) return;
 				if (!intercomDelivered) console.error(`Subagent async grouped result intercom delivery was not acknowledged for '${resultPath}'.`);
 			}
 
@@ -356,11 +473,19 @@ export function createResultWatcher(
 					})) : [],
 				} : {}),
 			});
-			if (!ownsSession(data.sessionId, epoch)) return;
+			if (!ownsSession(sessionId, epoch)) return;
 			if (!accepted) {
 				scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 				return;
 			}
+			try {
+				data = markDeliveredNotification(publicResultPath(file), data, runId, Date.now());
+				identityCache.delete(file);
+			} catch (error) {
+				console.error(`Failed to mark subagent result notification delivered for '${resultPath}'; will retry:`, error);
+				scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
+				return;
+			}
 			markSeenWithTtl(state.completionSeen, completionKey, Date.now(), completionTtlMs);
 			try {
 				pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
@@ -385,16 +510,12 @@ export function createResultWatcher(
 			} catch (error) {
 				console.error(`Completion observer failed for '${resultPath}':`, error);
 			}
-			if (!ownsSession(data.sessionId, epoch) || !fsApi.existsSync(resultPath)) return;
-			try {
-				fsApi.unlinkSync(resultPath);
-				identityCache.delete(file);
-			} catch (error) {
-				if (!isNotFound(error)) {
-					console.error(`Failed to remove delivered subagent result '${resultPath}'; will retry:`, error);
-					scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
-				}
+			if (!observerSucceeded) {
+				scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
+				return;
 			}
+			if (!ownsSession(sessionId, epoch)) return;
+			if (!removeDeliveredResult(file, sessionId, runId, toolCallId)) scheduleResult(file, triggerTurn, RETRY_DELAY_MS);
 		} catch (error) {
 			if (!isNotFound(error)) console.error(`Failed to process subagent result file '${resultPath}':`, error);
 		} finally {
@@ -406,18 +527,39 @@ export function createResultWatcher(
 		const triggerTurn = pendingTriggerTurn.get(file) !== false;
 		pendingTriggerTurn.delete(file);
 		void handleResult(file, triggerTurn);
-	}, 50);
+	}, deps.coalesceDelayMs ?? 50);
 
+	const logScanStats = (stats: ResultScanStats) => {
+		const elapsed = Date.now() - stats.startedAt;
+		if (elapsed < SLOW_RESULT_SCAN_MS) return;
+		console.error(`Subagent result scan inspected ${stats.files} indexed result file(s), scheduled ${stats.scheduled} in ${elapsed}ms (${resultsDir}).`);
+	};
+	const indexedResultCandidates = (observed: ReadonlySet<string>): string[] => {
+		const files = new Set<string>();
+		if (state.currentSessionId) {
+			for (const file of resultCandidateFilesForSession(resultsDir, state.currentSessionId)) files.add(file);
+		}
+		for (const runId of state.asyncJobs.keys()) files.add(`${runId}.json`);
+		for (const file of missionObserverResultCandidateFiles(resultsDir)) files.add(file);
+		for (const runId of observed) files.add(`${runId}.json`);
+		return [...files];
+	};
 	const primeExistingResults = (options: { triggerTurn?: boolean } = {}) => {
 		try {
 			const triggerTurn = options.triggerTurn !== false;
-			fsApi.readdirSync(resultsDir)
-				.filter((f) => f.endsWith(".json"))
-				.forEach((file) => {
-					if (shouldProcessResult(file)) scheduleResult(file, triggerTurn);
-				});
+			const stats: ResultScanStats = { files: 0, scheduled: 0, startedAt: Date.now() };
+			const observed = observedRunIds();
+			for (const file of indexedResultCandidates(observed)) {
+				stats.files += 1;
+				const signature = resultSignature(file, observed);
+				if (!signature) continue;
+				if (!shouldProcessResult(file, observed, signature)) continue;
+				stats.scheduled += 1;
+				scheduleResult(file, triggerTurn);
+			}
+			logScanStats(stats);
 		} catch (error) {
-			if (!isNotFound(error)) console.error(`Failed to scan subagent result directory '${resultsDir}':`, error);
+			if (!isNotFound(error)) console.error(`Failed to scan subagent result index in '${resultsDir}':`, error);
 		}
 	};
 
@@ -474,6 +616,11 @@ export function createResultWatcher(
 				const fileName = file.toString();
 				if (fileName.endsWith(".json")) {
 					identityCache.delete(fileName);
+					try {
+						writeResultIndexForData(path.join(resultsDir, fileName), JSON.parse(fsApi.readFileSync(path.join(resultsDir, fileName), "utf-8")) as Record<string, unknown>);
+					} catch {
+						// The writer may still be renaming the file; handleResult will retry from the normal result path.
+					}
 					scheduleResult(fileName, true);
 				}
 			});

package/src/runs/background/retained-children.ts

@@ -1,32 +1,68 @@
 import * as fs from "node:fs";
-import { listAsyncRuns } from "./async-status.ts";
+import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
+import { readAsyncRecoveryDescriptor } from "./async-resume.ts";
 import type { TokenUsage } from "../../shared/types.ts";
 
 const MAX_RETAINED_CHILDREN = 10;
 const MAX_TASK_SUMMARY_LENGTH = 120;
 
+type RetainedChildState = "complete" | "failed" | "paused" | "stopped";
+type RetainedChildResumability =
+	| { state: "resumable"; sessionPath: string }
+	| { state: "not-resumable"; reason: string };
+
 export interface RetainedChild {
 	runId: string;
 	parentRunId?: string;
 	workflowKey?: string;
-	state: "complete" | "failed" | "paused";
+	state: RetainedChildState;
 	agent: string;
 	taskSummary: string;
 	completedAt: number;
-	sessionPath: string;
+	resumability: RetainedChildResumability;
+	sessionPath?: string;
 	tokenTotals?: TokenUsage;
 }
 
-function retainedSessionFile(sessionFile: string | undefined): sessionFile is string {
-	if (!sessionFile?.endsWith(".jsonl")) return false;
+function isRetainedChildState(state: AsyncRunSummary["state"]): state is RetainedChildState {
+	return state === "complete" || state === "failed" || state === "paused" || state === "stopped";
+}
+
+function isTerminalStepStatus(status: AsyncRunSummary["steps"][number]["status"]): boolean {
+	return status === "complete" || status === "completed" || status === "failed" || status === "paused" || status === "stopped";
+}
+
+function retainedSessionFile(sessionFile: string | undefined): RetainedChildResumability {
+	if (!sessionFile) return { state: "not-resumable", reason: "no persisted session file" };
+	if (!sessionFile.endsWith(".jsonl")) return { state: "not-resumable", reason: "persisted session file is not a .jsonl file" };
 	try {
 		const stat = fs.lstatSync(sessionFile);
-		return stat.isFile() && !stat.isSymbolicLink();
-	} catch {
-		return false;
+		if (!stat.isFile() || stat.isSymbolicLink()) return { state: "not-resumable", reason: "persisted session file is not a regular file" };
+		return { state: "resumable", sessionPath: sessionFile };
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+			return { state: "not-resumable", reason: `persisted session file is missing: ${sessionFile}` };
+		}
+		return { state: "not-resumable", reason: `persisted session file could not be inspected: ${error instanceof Error ? error.message : String(error)}` };
 	}
 }
 
+function childResumability(run: AsyncRunSummary, step: AsyncRunSummary["steps"][number]): RetainedChildResumability {
+	if (run.state === "stopped" || step.status === "stopped") return { state: "not-resumable", reason: "stopped run" };
+	if (step.runner?.type === "external-cli") return { state: "not-resumable", reason: "external CLI runner" };
+	const session = retainedSessionFile(step.sessionFile ?? run.sessionFile);
+	if (session.state === "not-resumable") return session;
+	try {
+		const recoveryDescriptor = readAsyncRecoveryDescriptor(run.asyncDir);
+		if (!recoveryDescriptor) return { state: "not-resumable", reason: "missing recovery descriptor" };
+		if (recoveryDescriptor.sourceRunId !== run.id) return { state: "not-resumable", reason: `recovery descriptor belongs to run ${recoveryDescriptor.sourceRunId}` };
+		if (recoveryDescriptor.agent !== step.agent) return { state: "not-resumable", reason: `recovery descriptor belongs to agent ${recoveryDescriptor.agent}` };
+	} catch (error) {
+		return { state: "not-resumable", reason: `invalid recovery descriptor: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	return session;
+}
+
 function boundedTaskSummary(value: string | undefined): string {
 	const normalized = value?.replace(/\s+/g, " ").trim() ?? "";
 	return normalized.length > MAX_TASK_SUMMARY_LENGTH
@@ -35,15 +71,15 @@ function boundedTaskSummary(value: string | undefined): string {
 }
 
 export function listRetainedChildren(asyncDirRoot: string, sessionId: string): RetainedChild[] {
-	return listAsyncRuns(asyncDirRoot, { sessionId, states: ["complete", "failed", "paused"], reconcile: false })
+	const children = listAsyncRuns(asyncDirRoot, { sessionId, states: ["complete", "failed", "paused", "stopped"], reconcile: false })
 		.flatMap((run) => {
 			if (!run.parentWorkflowRunId || run.steps.length !== 1) return [];
-			if (run.state !== "complete" && run.state !== "failed" && run.state !== "paused") return [];
+			if (!isRetainedChildState(run.state)) return [];
 			const step = run.steps[0]!;
-			const terminalStep = step.status === "complete" || step.status === "completed" || step.status === "failed" || step.status === "paused";
-			if (!terminalStep || !retainedSessionFile(step.sessionFile ?? run.sessionFile)) return [];
+			if (!isTerminalStepStatus(step.status)) return [];
 			const completedAt = run.endedAt ?? run.lastUpdate;
 			if (completedAt === undefined) return [];
+			const resumability = childResumability(run, step);
 			return [{
 				runId: run.id,
 				...(run.parentWorkflowRunId ? { parentRunId: run.parentWorkflowRunId } : {}),
@@ -52,25 +88,38 @@ export function listRetainedChildren(asyncDirRoot: string, sessionId: string): R
 				agent: step.agent,
 				taskSummary: boundedTaskSummary(step.description),
 				completedAt,
-				sessionPath: step.sessionFile ?? run.sessionFile!,
+				resumability,
+				...(resumability.state === "resumable" ? { sessionPath: resumability.sessionPath } : {}),
 				...(step.tokens ?? run.totalTokens ? { tokenTotals: step.tokens ?? run.totalTokens } : {}),
 			}];
 		})
-		.sort((left, right) => right.completedAt - left.completedAt)
-		.slice(0, MAX_RETAINED_CHILDREN);
+		.sort((left, right) => right.completedAt - left.completedAt);
+	return children;
 }
 
 export function formatRetainedChildren(children: RetainedChild[]): string {
-	if (children.length === 0) return "No recoverable retained children in the active parent session.";
+	if (children.length === 0) return "No retained workflow children in the active parent session. If a retained-writer challenge is required, launch a same-role fallback challenge and label it as fallback.";
+	const retained = children.slice(0, MAX_RETAINED_CHILDREN);
+	if (!retained.some((child) => child.resumability.state === "resumable")) {
+		const resumable = children.slice(MAX_RETAINED_CHILDREN).find((child) => child.resumability.state === "resumable");
+		if (resumable && retained.length === MAX_RETAINED_CHILDREN) retained[MAX_RETAINED_CHILDREN - 1] = resumable;
+	}
+	const hasResumableChild = retained.some((child) => child.resumability.state === "resumable");
 	return [
-		`Recoverable retained children (newest first, last ${MAX_RETAINED_CHILDREN}):`,
-		...children.flatMap((child) => [
+		`Retained workflow children (up to ${MAX_RETAINED_CHILDREN}; newest first, with a resumable child retained when available):`,
+		...retained.flatMap((child) => [
 			`- ${child.runId} | ${child.agent} | ${child.state} | ${new Date(child.completedAt).toISOString()}`,
 			...(child.parentRunId ? [`  workflow: ${child.parentRunId}${child.workflowKey ? ` (${child.workflowKey})` : ""}`] : []),
 			`  task: ${child.taskSummary || "(no task summary)"}`,
-			`  session: ${child.sessionPath}`,
-			`  resume: subagent({ action: "resume", id: "${child.runId}", message: "..." })`,
+			child.resumability.state === "resumable"
+				? "  resumability: resumable"
+				: `  resumability: not resumable (${child.resumability.reason})`,
+			...(child.resumability.state === "resumable" ? [
+				`  session: ${child.resumability.sessionPath}`,
+				`  resume: subagent({ action: "resume", id: "${child.runId}", message: "..." })`,
+			] : []),
 			...(child.tokenTotals ? [`  tokens: input ${child.tokenTotals.input}, output ${child.tokenTotals.output}, total ${child.tokenTotals.total}`] : []),
 		]),
+		...(hasResumableChild ? [] : ["No resumable retained child is listed. Launch a same-role fallback challenge and label it as fallback."]),
 	].join("\n");
 }

package/src/runs/background/run-id-resolver.ts

@@ -3,6 +3,8 @@ import * as path from "node:path";
 import { DIRS, type SubagentState } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { findAsyncRunPrefixMatches, type AsyncRunLocation } from "./async-resume.ts";
+import { resultFilePath, resultFilesForToolCall } from "./result-files.ts";
+import { readActiveRunToolCallIndex } from "./active-run-index.ts";
 import { assertSafeNestedId, findNestedRunMatchesById, type NestedRoute, type NestedRunMatch, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 
 export type ResolvedSubagentRunId =
@@ -19,7 +21,7 @@ export interface ResolveSubagentRunIdDeps {
 
 function exactAsyncLocation(id: string, asyncDirRoot: string, resultsDir: string): AsyncRunLocation | undefined {
 	const asyncDir = path.join(asyncDirRoot, id);
-	const resultPath = path.join(resultsDir, `${id}.json`);
+	const resultPath = resultFilePath(resultsDir, id);
 	if (!fs.existsSync(asyncDir) && !fs.existsSync(resultPath)) return undefined;
 	return {
 		asyncDir: fs.existsSync(asyncDir) ? asyncDir : null,
@@ -52,39 +54,28 @@ function readWorkflowResultIdentity(resultPath: string): WorkflowResultIdentity
 	};
 }
 
-function directoryEntries(root: string): string[] {
-	try {
-		return fs.readdirSync(root);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-		throw error;
-	}
-}
-
 function resultPathFor(resultsDir: string, runId: string): string | null {
-	const resultPath = path.join(resultsDir, `${runId}.json`);
+	const resultPath = resultFilePath(resultsDir, runId);
 	return fs.existsSync(resultPath) ? resultPath : null;
 }
 
-function toolCallIdMatches(value: string | undefined, query: string, options: { prefix?: boolean }): boolean {
-	if (value === undefined) return false;
-	return options.prefix === true ? value.startsWith(query) : value === query;
+function toolCallIdMatches(value: string | undefined, query: string): boolean {
+	return value === query;
 }
 
-function toolCallIdAsyncLocations(toolCallId: string, asyncDirRoot: string, resultsDir: string, options: { prefix?: boolean } = {}): AsyncRunMatch[] {
+function indexedToolCallIdAsyncLocations(toolCallId: string, asyncDirRoot: string, resultsDir: string): AsyncRunMatch[] {
 	const byId = new Map<string, AsyncRunLocation>();
-	for (const entry of directoryEntries(asyncDirRoot)) {
+	for (const entry of readActiveRunToolCallIndex(asyncDirRoot, toolCallId)) {
 		const asyncDir = path.join(asyncDirRoot, entry);
 		const status = readStatus(asyncDir);
-		if (!status || !toolCallIdMatches(status.toolCallId, toolCallId, options)) continue;
+		if (!status || !toolCallIdMatches(status.toolCallId, toolCallId)) continue;
 		const runId = status.runId || entry;
 		byId.set(runId, { asyncDir, resultPath: resultPathFor(resultsDir, runId), resolvedId: runId });
 	}
-	for (const entry of directoryEntries(resultsDir)) {
-		if (!entry.endsWith(".json")) continue;
+	for (const entry of resultFilesForToolCall(resultsDir, toolCallId)) {
 		const resultPath = path.join(resultsDir, entry);
 		const identity = readWorkflowResultIdentity(resultPath);
-		if (!identity || !toolCallIdMatches(identity.toolCallId, toolCallId, options)) continue;
+		if (!identity || !toolCallIdMatches(identity.toolCallId, toolCallId)) continue;
 		const runId = identity.runId ?? identity.id ?? entry.slice(0, -".json".length);
 		const asyncDir = path.join(asyncDirRoot, runId);
 		byId.set(runId, { asyncDir: fs.existsSync(asyncDir) ? asyncDir : null, resultPath, resolvedId: runId });
@@ -109,6 +100,22 @@ function hasExactForegroundId(state: SubagentState | undefined, id: string): boo
 	return Boolean(remembered && state.currentSessionId && remembered.sessionId === state.currentSessionId);
 }
 
+function exactLiveAsyncToolCallMatch(state: SubagentState | undefined, toolCallId: string, asyncDirRoot: string, resultsDir: string): AsyncRunMatch | undefined {
+	if (!state?.asyncJobs) return undefined;
+	const matches = [...state.asyncJobs.values()].filter((job) => job.toolCallId === toolCallId);
+	if (matches.length > 1) throw new Error(`Subagent tool-call id '${toolCallId}' is ambiguous across async runs. Use the returned asyncId instead.`);
+	const match = matches[0];
+	if (!match) return undefined;
+	return {
+		id: match.asyncId,
+		location: {
+			asyncDir: fs.existsSync(match.asyncDir) ? match.asyncDir : path.join(asyncDirRoot, match.asyncId),
+			resultPath: resultPathFor(resultsDir, match.asyncId),
+			resolvedId: match.asyncId,
+		},
+	};
+}
+
 function nestedScopeFromState(state: SubagentState | undefined): NestedRunResolutionScope | undefined {
 	if (!state) return undefined;
 	const routes: NestedRoute[] = [];
@@ -138,7 +145,9 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
 	if (hasExactForegroundId(deps.state, id)) return { kind: "foreground", id };
 	const exactAsync = exactAsyncLocation(id, asyncDirRoot, resultsDir);
 	if (exactAsync) return { kind: "async", id, location: exactAsync };
-	const exactToolCallIdMatches = toolCallIdAsyncLocations(id, asyncDirRoot, resultsDir);
+	const exactLiveToolCallMatch = exactLiveAsyncToolCallMatch(deps.state, id, asyncDirRoot, resultsDir);
+	if (exactLiveToolCallMatch) return { kind: "async", id: exactLiveToolCallMatch.id, location: exactLiveToolCallMatch.location };
+	const exactToolCallIdMatches = indexedToolCallIdAsyncLocations(id, asyncDirRoot, resultsDir);
 	if (exactToolCallIdMatches.length > 1) throw new Error(`Subagent tool-call id '${id}' is ambiguous across async runs. Use the returned asyncId instead.`);
 	if (exactToolCallIdMatches[0]) return { kind: "async", id: exactToolCallIdMatches[0].id, location: exactToolCallIdMatches[0].location };
 	const exactNested = findNestedRunMatchesById(id, nestedScope ? { scope: nestedScope } : {});
@@ -152,9 +161,6 @@ export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps
 	for (const match of asyncPrefixMatches(id, asyncDirRoot, resultsDir)) {
 		matches.push({ kind: "async", id: match.id, location: match.location });
 	}
-	for (const match of toolCallIdAsyncLocations(id, asyncDirRoot, resultsDir, { prefix: true })) {
-		matches.push({ kind: "async", id: match.id, location: match.location });
-	}
 	for (const match of findNestedRunMatchesById(id, nestedScope ? { prefix: true, scope: nestedScope } : { prefix: true })) {
 		matches.push({ kind: "nested", id: match.run.id, match });
 	}

package/src/runs/background/run-status.ts

@@ -113,15 +113,20 @@ function formatCheckpointGuidance(runId: string | undefined, checkpoint: AsyncSt
 	return `Checkpoint: ${checkpoint.name}${checkpoint.message ? ` — ${checkpoint.message}` : ""}\nApprove: subagent({ action: "approve-checkpoint", id: "${runId}" })\nReject: subagent({ action: "reject-checkpoint", id: "${runId}" })`;
 }
 
-function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown; runId?: unknown; workflowKey?: unknown }>, fallbackSessionFile?: unknown, options: { stopped?: boolean } = {}): string {
+function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown; runId?: unknown; workflowKey?: unknown; status?: unknown; activityState?: unknown }>, fallbackSessionFile?: unknown, options: { stopped?: boolean } = {}): string {
 	if (options.stopped) return "Resume: unavailable; stopped runs are not resumable. Start a new run instead.";
 	const knownChildren = children
 		.map((child, index) => ({ child, index }))
 		.filter(({ child }) => typeof child.agent === "string");
 	if (!runId || knownChildren.length === 0) return "Resume: unavailable; no child session file was persisted.";
 	const workflowChildren = knownChildren.filter(({ child }) => typeof child.runId === "string" && child.runId.trim() && hasExistingSessionFile(child.sessionFile));
+	const supervisorDetachedWorkflowChildren = workflowChildren.filter(({ child }) => child.status === "paused" && child.activityState === "needs_attention");
+	const resumableWorkflowChildren = workflowChildren.filter(({ child }) => !(child.status === "paused" && child.activityState === "needs_attention"));
 	if (workflowChildren.length > 0) {
-		return workflowChildren.map(({ child }) => `Revive workflow child${typeof child.workflowKey === "string" && child.workflowKey.trim() ? ` '${child.workflowKey}'` : ""}: subagent({ action: "resume", id: "${child.runId}", message: "..." })`).join("\n");
+		return [
+			...supervisorDetachedWorkflowChildren.map(({ child }) => `Recovery workflow child${typeof child.workflowKey === "string" && child.workflowKey.trim() ? ` '${child.workflowKey}'` : ""}: reply to the supervisor request first, then wait with subagent_wait({ id: "${child.runId}" }). Use subagent({ action: "status", id: "${child.runId}" }) to recover the result; do not resume or launch a replacement while it remains detached.`),
+			...resumableWorkflowChildren.map(({ child }) => `Revive workflow child${typeof child.workflowKey === "string" && child.workflowKey.trim() ? ` '${child.workflowKey}'` : ""}: subagent({ action: "resume", id: "${child.runId}", message: "..." })`),
+		].join("\n");
 	}
 	const singleSessionFile = knownChildren[0]?.child.sessionFile ?? fallbackSessionFile;
 	if (children.length === 1 && knownChildren.length === 1 && hasExistingSessionFile(singleSessionFile)) {