@selesai/code 0.8.6 → 0.8.8

package/dist/extensions/pi-subagents/src/runs/background/result-watcher.ts

@@ -22,6 +22,7 @@ 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;
@@ -50,6 +51,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 +82,7 @@ type ResultFileData = CompletionNotification & {
 	asyncDir?: string;
 	intercomTarget?: string;
 	parallelHandoff?: ParallelHandoffReference;
+	notificationDeliveredAt?: unknown;
 };
 
 type ResultFileIdentity = {
@@ -134,6 +138,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,
@@ -194,16 +208,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);
@@ -220,9 +273,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;
@@ -233,32 +287,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"));
@@ -273,20 +375,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;
 			}
 
@@ -334,6 +433,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) {
@@ -350,7 +460,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}'.`);
 			}
 
@@ -374,11 +484,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, {
@@ -403,16 +521,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 {
@@ -424,18 +538,45 @@ export function createResultWatcher(
 		const triggerTurn = pendingTriggerTurn.get(file) !== false;
 		pendingTriggerTurn.delete(file);
 		void handleResult(file, triggerTurn);
-	}, 50);
+	}, deps.coalesceDelayMs ?? 50);
 
+	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 observed = observedRunIds();
+			for (const file of indexedResultCandidates(observed)) {
+				const signature = resultSignature(file, observed);
+				if (!signature) continue;
+				if (!shouldProcessResult(file, observed, signature)) continue;
+				scheduleResult(file, triggerTurn);
+			}
+			// Selesai fork: during the lineage adoption window, also scan flat
+			// result files written directly under the results root by a previous
+			// session's runtime, so completions that raced the session switch are
+			// adopted instead of left behind. Bounded to the window; outside it,
+			// flat files are stale leftovers and only the indexed inbox is scanned.
+			if (state.adoptedResultWindowStart !== undefined) {
+				const indexed = indexedResultCandidates(observed);
+				for (const file of fsApi.readdirSync(resultsDir)) {
+					if (!file.endsWith(".json") || indexed.includes(file)) continue;
+					const signature = resultSignature(file, observed);
+					if (!signature) continue;
+					if (!shouldProcessResult(file, observed, signature)) continue;
+					scheduleResult(file, triggerTurn);
+				}
+			}
 		} 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);
 		}
 	};
 
@@ -492,6 +633,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/dist/extensions/pi-subagents/src/runs/background/resume-guidance.ts

@@ -1,6 +1,19 @@
 import * as fs from "node:fs";
 import type { AsyncRunSummary } from "./async-status.ts";
 
+const INTERCOM_DETACH_ERROR = "detached for intercom coordination";
+
+function isIntercomDetached(run: AsyncRunSummary): boolean {
+	return run.steps.some((step) => step.execution?.status === "detached"
+		|| step.error?.toLowerCase().includes(INTERCOM_DETACH_ERROR) === true)
+		|| run.error?.toLowerCase().includes(INTERCOM_DETACH_ERROR) === true;
+}
+
+function formatIntercomDetachGuidance(run: AsyncRunSummary): string | undefined {
+	if (!isIntercomDetached(run)) return undefined;
+	return `Run "${run.id}" detached for intercom coordination. Reply to the supervisor request first, then wait with subagent_wait({ id: "${run.id}" }). Use subagent({ action: "status", id: "${run.id}" }) to recover the result; do not resume or launch a replacement while it remains detached.`;
+}
+
 export function formatAsyncReviveCommand(run: AsyncRunSummary): string | undefined {
 	const step = run.steps.find((candidate) => candidate.status === "failed" && candidate.sessionFile && fs.existsSync(candidate.sessionFile));
 	if (!step) {
@@ -15,19 +28,26 @@ export function formatAsyncReviveCommand(run: AsyncRunSummary): string | undefin
 
 export function formatResumeFirstFailedRunDetail(run: AsyncRunSummary): string | undefined {
 	if (run.state !== "failed") return undefined;
+	const detachGuidance = formatIntercomDetachGuidance(run);
+	if (detachGuidance) return detachGuidance;
 	const command = formatAsyncReviveCommand(run);
 	if (!command) return undefined;
 	return `Resume-first: failed run "${run.id}" has a persisted child session. Revive the original run with ${command} before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`;
 }
 
 export function formatResumeFirstFailedRunsNote(runs: AsyncRunSummary[]): string {
-	const resumable = runs
-		.filter((run) => run.state === "failed")
+	const failedRuns = runs.filter((run) => run.state === "failed");
+	const detachGuidance = failedRuns
+		.map(formatIntercomDetachGuidance)
+		.filter((guidance): guidance is string => Boolean(guidance));
+	const resumable = failedRuns
+		.filter((run) => !isIntercomDetached(run))
 		.map((run) => ({ run, command: formatAsyncReviveCommand(run) }))
 		.filter((entry): entry is { run: AsyncRunSummary; command: string } => Boolean(entry.command));
-	if (resumable.length === 0) return "";
-	const guidance = resumable.length === 1
-		? `failed run "${resumable[0]!.run.id}" has a persisted child session. Revive the original run with ${resumable[0]!.command}`
-		: `${resumable.length} failed runs have persisted child sessions. Inspect status and revive each original run before retrying`;
-	return ` Resume-first: ${guidance} before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`;
+	const resumeGuidance = resumable.length === 0
+		? ""
+		: resumable.length === 1
+			? ` Resume-first: failed run "${resumable[0]!.run.id}" has a persisted child session. Revive the original run with ${resumable[0]!.command} before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`
+			: ` Resume-first: ${resumable.length} failed runs have persisted child sessions. Inspect status and revive each original run before reporting failure or launching a replacement. Launch a replacement only if revive fails or the user explicitly asks for one.`;
+	return `${detachGuidance.length > 0 ? ` ${detachGuidance.join(" ")}` : ""}${resumeGuidance}`;
 }

package/dist/extensions/pi-subagents/src/runs/background/retained-children.ts

@@ -1,30 +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: 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
@@ -32,37 +70,56 @@ function boundedTaskSummary(value: string | undefined): string {
 		: normalized;
 }
 
-export function listRetainedChildren(asyncDirRoot: string, sessionIds: string[]): RetainedChild[] {
-	return listAsyncRuns(asyncDirRoot, { sessionIds, states: ["complete"], reconcile: false })
+export function listRetainedChildren(asyncDirRoot: string, sessionIds: string | string[]): RetainedChild[] {
+	const children = listAsyncRuns(asyncDirRoot, { sessionIds: Array.isArray(sessionIds) ? sessionIds : [sessionIds], states: ["complete", "failed", "paused", "stopped"], reconcile: false })
 		.flatMap((run) => {
 			if (!run.parentWorkflowRunId || run.steps.length !== 1) return [];
+			if (!isRetainedChildState(run.state)) return [];
 			const step = run.steps[0]!;
-			if ((step.status !== "complete" && step.status !== "completed") || !retainedSessionFile(step.sessionFile ?? run.sessionFile)) return [];
-			const completedAt = run.endedAt;
+			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 } : {}),
+				...(run.workflowKey ? { workflowKey: run.workflowKey } : {}),
+				state: run.state,
 				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 completed 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 [
-		`Completed retained children (newest first, last ${MAX_RETAINED_CHILDREN}):`,
-		...children.flatMap((child) => [
-			`- ${child.runId} | ${child.agent} | ${new Date(child.completedAt).toISOString()}`,
+		`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}`,
+			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");
 }