@pi-agents/orchid 0.1.0-beta.0

package/src/subagents/runs/background/async-job-tracker.ts

@@ -0,0 +1,310 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { renderWidget, widgetRenderKey } from "../../tui/render.ts";
+import { formatControlNoticeMessage } from "../shared/subagent-control.ts";
+import {
+	type AsyncJobState,
+	type AsyncStartedEvent,
+	type ControlEvent,
+	type SubagentState,
+	POLL_INTERVAL_MS,
+	RESULTS_DIR,
+	SUBAGENT_CONTROL_EVENT,
+	SUBAGENT_CONTROL_INTERCOM_EVENT,
+} from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+import { normalizeParallelGroups } from "./parallel-groups.ts";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { hasLiveNestedDescendants, updateAsyncJobNestedProjection } from "../shared/nested-events.ts";
+
+interface AsyncJobTrackerOptions {
+	completionRetentionMs?: number;
+	pollIntervalMs?: number;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+}
+
+export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: SubagentState, asyncDirRoot: string, options: AsyncJobTrackerOptions = {}): {
+	ensurePoller: () => void;
+	handleStarted: (data: unknown) => void;
+	handleComplete: (data: unknown) => void;
+	resetJobs: (ctx?: ExtensionContext) => void;
+} {
+	const completionRetentionMs = options.completionRetentionMs ?? 10000;
+	const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+	const resultsDir = options.resultsDir ?? RESULTS_DIR;
+	const rerenderWidget = (ctx: ExtensionContext, jobs = Array.from(state.asyncJobs.values())) => {
+		renderWidget(ctx, jobs);
+		ctx.ui.requestRender?.();
+	};
+	const cancelCleanup = (asyncId: string) => {
+		const existingTimer = state.cleanupTimers.get(asyncId);
+		if (!existingTimer) return;
+		clearTimeout(existingTimer);
+		state.cleanupTimers.delete(asyncId);
+	};
+	const scheduleCleanup = (asyncId: string) => {
+		cancelCleanup(asyncId);
+		const timer = setTimeout(() => {
+			state.cleanupTimers.delete(asyncId);
+			state.asyncJobs.delete(asyncId);
+			if (state.lastUiContext) {
+				rerenderWidget(state.lastUiContext);
+			}
+		}, completionRetentionMs);
+		state.cleanupTimers.set(asyncId, timer);
+	};
+	const emitNewControlEvents = (job: AsyncJobState) => {
+		const eventsPath = path.join(job.asyncDir, "events.jsonl");
+		let fd: number;
+		try {
+			fd = fs.openSync(eventsPath, "r");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			console.error(`Failed to open async control events for '${job.asyncDir}':`, error);
+			return;
+		}
+		try {
+			const stat = fs.fstatSync(fd);
+			const cursor = stat.size < (job.controlEventCursor ?? 0) ? 0 : (job.controlEventCursor ?? 0);
+			if (stat.size <= cursor) return;
+			const buffer = Buffer.alloc(stat.size - cursor);
+			fs.readSync(fd, buffer, 0, buffer.length, cursor);
+			const lastNewline = buffer.lastIndexOf(0x0a);
+			if (lastNewline === -1) return;
+			job.controlEventCursor = cursor + lastNewline + 1;
+			for (const line of buffer.subarray(0, lastNewline).toString("utf-8").split("\n")) {
+				if (!line.trim()) continue;
+				let parsed: unknown;
+				try {
+					parsed = JSON.parse(line);
+				} catch (error) {
+					console.error(`Ignoring malformed async control event in '${eventsPath}':`, error);
+					continue;
+				}
+				if (!parsed || typeof parsed !== "object" || (parsed as { type?: unknown }).type !== "subagent.control") continue;
+				const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
+				if (!record.event || !Array.isArray(record.channels)) continue;
+				const payload = {
+					event: record.event,
+					source: "async" as const,
+					asyncDir: job.asyncDir,
+					childIntercomTarget: record.childIntercomTarget,
+					noticeText: record.noticeText ?? formatControlNoticeMessage(record.event, record.childIntercomTarget),
+				};
+				if (record.channels.includes("event")) {
+					pi.events.emit(SUBAGENT_CONTROL_EVENT, payload);
+				}
+				if (record.event.type !== "active_long_running" && record.channels.includes("intercom") && record.intercom?.to && record.intercom.message) {
+					pi.events.emit(SUBAGENT_CONTROL_INTERCOM_EVENT, {
+						...payload,
+						to: record.intercom.to,
+						message: record.intercom.message,
+					});
+				}
+			}
+		} catch (error) {
+			console.error(`Failed to read async control events for '${job.asyncDir}':`, error);
+		} finally {
+			fs.closeSync(fd);
+		}
+	};
+
+	const ensurePoller = () => {
+		if (state.poller) return;
+		state.poller = setInterval(() => {
+			if (state.asyncJobs.size === 0) {
+				if (state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext, []);
+				if (state.poller) {
+					clearInterval(state.poller);
+					state.poller = null;
+				}
+				return;
+			}
+
+			let widgetChanged = false;
+			for (const job of state.asyncJobs.values()) {
+				const widgetStateBefore = widgetRenderKey(job);
+				let nestedRefreshFailed = false;
+				const refreshNestedProjection = () => {
+					try {
+						updateAsyncJobNestedProjection(job);
+					} catch (error) {
+						nestedRefreshFailed = true;
+						console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
+					}
+				};
+				const reconcileNestedDescendants = () => {
+					try {
+						if (job.nestedRoute) reconcileNestedAsyncDescendants(job.nestedRoute, { resultsDir, kill: options.kill, now: options.now });
+					} catch (error) {
+						nestedRefreshFailed = true;
+						console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
+					}
+					refreshNestedProjection();
+				};
+				try {
+					emitNewControlEvents(job);
+					reconcileNestedDescendants();
+					const reconciliation = reconcileAsyncRun(job.asyncDir, {
+						resultsDir,
+						kill: options.kill,
+						now: options.now,
+						startedRun: {
+							runId: job.asyncId,
+							pid: job.pid,
+							sessionId: job.sessionId,
+							mode: job.mode,
+							agents: job.agents,
+							chainStepCount: job.chainStepCount,
+							parallelGroups: job.parallelGroups,
+							startedAt: job.startedAt,
+							sessionFile: job.sessionFile,
+						},
+					});
+					const status = reconciliation.status ?? readStatus(job.asyncDir);
+					if (status) {
+						const previousStatus = job.status;
+						job.status = status.state;
+						if (job.status !== "complete" && job.status !== "failed" && job.status !== "paused") cancelCleanup(job.asyncId);
+						job.sessionId = status.sessionId ?? job.sessionId;
+						job.activityState = status.activityState;
+						job.lastActivityAt = status.lastActivityAt ?? job.lastActivityAt;
+						job.currentTool = status.currentTool;
+						job.currentToolStartedAt = status.currentToolStartedAt;
+						job.currentPath = status.currentPath;
+						job.turnCount = status.turnCount ?? job.turnCount;
+						job.toolCount = status.toolCount ?? job.toolCount;
+						job.mode = status.mode;
+						job.currentStep = status.currentStep ?? job.currentStep;
+						job.chainStepCount = status.chainStepCount ?? job.chainStepCount;
+						job.startedAt = status.startedAt ?? job.startedAt;
+						if (status.lastUpdate !== undefined) job.updatedAt = status.lastUpdate;
+						if (status.steps?.length) {
+							const groups = normalizeParallelGroups(status.parallelGroups, status.steps.length, status.chainStepCount ?? status.steps.length);
+							job.parallelGroups = groups.length ? groups : job.parallelGroups;
+							job.hasParallelGroups = groups.length > 0 || job.hasParallelGroups;
+							const activeGroup = status.currentStep !== undefined
+								? groups.find((group) => status.currentStep! >= group.start && status.currentStep! < group.start + group.count)
+								: undefined;
+							const visibleSteps = activeGroup
+								? status.steps.slice(activeGroup.start, activeGroup.start + activeGroup.count).map((step, index) => ({ ...step, index: activeGroup.start + index }))
+								: status.steps.map((step, index) => ({ ...step, index }));
+							job.activeParallelGroup = Boolean(activeGroup);
+							job.agents = visibleSteps.map((step) => step.agent);
+							job.steps = visibleSteps;
+							refreshNestedProjection();
+							job.stepsTotal = visibleSteps.length;
+							job.runningSteps = visibleSteps.filter((step) => step.status === "running").length;
+							job.completedSteps = visibleSteps.filter((step) => step.status === "complete" || step.status === "completed").length;
+							if (status.state === "complete") job.completedSteps = visibleSteps.length;
+						}
+						job.sessionDir = status.sessionDir ?? job.sessionDir;
+						job.outputFile = status.outputFile ?? job.outputFile;
+						job.totalTokens = status.totalTokens ?? job.totalTokens;
+						job.sessionFile = status.sessionFile ?? job.sessionFile;
+						if ((job.status === "complete" || job.status === "failed" || job.status === "paused") && !nestedRefreshFailed && !hasLiveNestedDescendants(job.nestedChildren) && (previousStatus !== job.status || !state.cleanupTimers.has(job.asyncId))) {
+							scheduleCleanup(job.asyncId);
+						}
+						if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
+						continue;
+					}
+					if (job.status === "queued") {
+						job.status = "running";
+						job.updatedAt = Date.now();
+					}
+				} catch (error) {
+					if (job.status !== "failed") {
+						console.error(`Failed to read async status for '${job.asyncDir}':`, error);
+						job.status = "failed";
+						job.updatedAt = Date.now();
+					}
+					if (!hasLiveNestedDescendants(job.nestedChildren) && !state.cleanupTimers.has(job.asyncId)) {
+						scheduleCleanup(job.asyncId);
+					}
+				}
+				if (widgetRenderKey(job) !== widgetStateBefore) widgetChanged = true;
+			}
+
+			if (widgetChanged && state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
+		}, pollIntervalMs);
+		state.poller.unref?.();
+	};
+
+	const handleStarted = (data: unknown) => {
+		const info = data as AsyncStartedEvent;
+		if (!info.id) return;
+		const now = Date.now();
+		const asyncDir = info.asyncDir ?? path.join(asyncDirRoot, info.id);
+		const rawAgents = info.agents?.length ? info.agents : info.chain && info.chain.length > 0 ? info.chain : info.agent ? [info.agent] : undefined;
+		const validParallelGroups = normalizeParallelGroups(info.parallelGroups, Number.MAX_SAFE_INTEGER, info.chainStepCount ?? Number.MAX_SAFE_INTEGER);
+		const firstGroup = validParallelGroups.find((group) => group.start === 0);
+		const firstGroupCount = firstGroup?.count;
+		const agents = firstGroupCount && firstGroupCount > 0
+			? rawAgents?.slice(0, firstGroupCount)
+			: rawAgents;
+		state.asyncJobs.set(info.id, {
+			asyncId: info.id,
+			asyncDir,
+			status: "queued",
+			pid: typeof info.pid === "number" ? info.pid : undefined,
+			...(typeof info.sessionId === "string" ? { sessionId: info.sessionId } : {}),
+			mode: info.mode ?? (info.chain ? "chain" : "single"),
+			agents,
+			chainStepCount: info.chainStepCount,
+			parallelGroups: validParallelGroups,
+			nestedRoute: info.nestedRoute,
+			stepsTotal: firstGroupCount ?? agents?.length,
+			hasParallelGroups: validParallelGroups.length > 0,
+			activeParallelGroup: Boolean(firstGroupCount && firstGroupCount > 0),
+			startedAt: now,
+			updatedAt: now,
+		});
+		ensurePoller();
+		if (state.lastUiContext) {
+			rerenderWidget(state.lastUiContext);
+		}
+	};
+
+	const handleComplete = (data: unknown) => {
+		const result = data as { id?: string; success?: boolean; asyncDir?: string };
+		const asyncId = result.id;
+		if (!asyncId) return;
+		const job = state.asyncJobs.get(asyncId);
+		let nestedRefreshFailed = false;
+		if (job) {
+			job.status = result.success ? "complete" : "failed";
+			job.updatedAt = Date.now();
+			if (result.asyncDir) job.asyncDir = result.asyncDir;
+			try {
+				updateAsyncJobNestedProjection(job);
+			} catch (error) {
+				nestedRefreshFailed = true;
+				console.error(`Failed to refresh nested async descendants for '${job.asyncDir}':`, error);
+			}
+		}
+		if (state.lastUiContext) {
+			rerenderWidget(state.lastUiContext);
+		}
+		if (!nestedRefreshFailed && !hasLiveNestedDescendants(job?.nestedChildren)) scheduleCleanup(asyncId);
+	};
+
+	const resetJobs = (ctx?: ExtensionContext) => {
+		for (const timer of state.cleanupTimers.values()) {
+			clearTimeout(timer);
+		}
+		state.cleanupTimers.clear();
+		state.asyncJobs.clear();
+		state.foregroundControls?.clear();
+		state.lastForegroundControlId = null;
+		state.resultFileCoalescer.clear();
+		if (ctx?.hasUI) {
+			state.lastUiContext = ctx;
+			rerenderWidget(ctx, []);
+		}
+	};
+
+	return { ensurePoller, handleStarted, handleComplete, resetJobs };
+}

package/src/subagents/runs/background/async-resume.ts

@@ -0,0 +1,345 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus } from "../../shared/types.ts";
+import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
+import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
+
+export interface AsyncResumeParams {
+	id?: string;
+	runId?: string;
+	dir?: string;
+	index?: number;
+}
+
+export interface AsyncResumeDeps {
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+}
+
+export type AsyncResumeTarget = {
+	kind: "live" | "revive";
+	runId: string;
+	asyncDir?: string;
+	state: AsyncStatus["state"];
+	agent: string;
+	index: number;
+	intercomTarget: string;
+	cwd?: string;
+	sessionFile?: string;
+};
+
+interface AsyncResultFile {
+	id?: string;
+	runId?: string;
+	agent?: string;
+	mode?: string;
+	state?: string;
+	success?: boolean;
+	cwd?: string;
+	sessionFile?: string;
+	results?: Array<{ agent?: string; success?: boolean; sessionFile?: string; intercomTarget?: string }>;
+}
+
+export interface AsyncRunLocation {
+	asyncDir: string | null;
+	resultPath: string | null;
+	resolvedId?: string;
+}
+
+function getErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function ensureObject(value: unknown, source: string): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error(`Async result file '${source}' must contain a JSON object.`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function validateOptionalString(value: Record<string, unknown>, field: string, source: string, displayField = field): string | undefined {
+	const fieldValue = value[field];
+	if (fieldValue === undefined) return undefined;
+	if (typeof fieldValue !== "string") throw new Error(`Invalid async result file '${source}': ${displayField} must be a string.`);
+	return fieldValue;
+}
+
+function validateResultFile(value: unknown, resultPath: string): AsyncResultFile {
+	const data = ensureObject(value, resultPath);
+	const resultsValue = data.results;
+	let results: AsyncResultFile["results"];
+	if (resultsValue !== undefined) {
+		if (!Array.isArray(resultsValue)) throw new Error(`Invalid async result file '${resultPath}': results must be an array.`);
+		results = resultsValue.map((entry, index) => {
+			const child = ensureObject(entry, `${resultPath} results[${index}]`);
+			const agent = validateOptionalString(child, "agent", resultPath, `results[${index}].agent`);
+			const sessionFile = validateOptionalString(child, "sessionFile", resultPath, `results[${index}].sessionFile`);
+			const intercomTarget = validateOptionalString(child, "intercomTarget", resultPath, `results[${index}].intercomTarget`);
+			const success = child.success;
+			if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);
+			return { agent, sessionFile, intercomTarget, ...(typeof success === "boolean" ? { success } : {}) };
+		});
+	}
+	const success = data.success;
+	if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': success must be a boolean.`);
+	return {
+		id: validateOptionalString(data, "id", resultPath),
+		runId: validateOptionalString(data, "runId", resultPath),
+		agent: validateOptionalString(data, "agent", resultPath),
+		mode: validateOptionalString(data, "mode", resultPath),
+		state: validateOptionalString(data, "state", resultPath),
+		cwd: validateOptionalString(data, "cwd", resultPath),
+		sessionFile: validateOptionalString(data, "sessionFile", resultPath),
+		...(typeof success === "boolean" ? { success } : {}),
+		...(results ? { results } : {}),
+	};
+}
+
+function readResultFile(resultPath: string): AsyncResultFile {
+	let raw: string;
+	try {
+		raw = fs.readFileSync(resultPath, "utf-8");
+	} catch (error) {
+		throw new Error(`Failed to read async result file '${resultPath}': ${getErrorMessage(error)}`, {
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+	try {
+		return validateResultFile(JSON.parse(raw), resultPath);
+	} catch (error) {
+		if (error instanceof SyntaxError) {
+			throw new Error(`Failed to parse async result file '${resultPath}': ${getErrorMessage(error)}`, {
+				cause: error,
+			});
+		}
+		throw error;
+	}
+}
+
+function assertRunId(value: string | undefined, field: "id" | "runId"): string | undefined {
+	if (value === undefined) return undefined;
+	if (value.trim() === "") throw new Error(`${field} must not be empty.`);
+	if (path.isAbsolute(value) || /[\\/]/.test(value) || value.includes("..")) {
+		throw new Error(`${field} must be an async run id or prefix, not a path.`);
+	}
+	return value;
+}
+
+function assertInsideRoot(root: string, target: string, label: string): void {
+	const rootPath = path.resolve(root);
+	const targetPath = path.resolve(target);
+	const relative = path.relative(rootPath, targetPath);
+	if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) return;
+	throw new Error(`${label} must be inside ${rootPath}.`);
+}
+
+function prefixedRunIds(dir: string, prefix: string, suffix = ""): string[] {
+	if (!fs.existsSync(dir)) return [];
+	return fs.readdirSync(dir)
+		.filter((entry) => entry.startsWith(prefix) && (!suffix || entry.endsWith(suffix)))
+		.map((entry) => suffix ? entry.slice(0, -suffix.length) : entry)
+		.sort();
+}
+
+function exactResultPath(resultsDir: string, runId: string): string | null {
+	const resultPath = path.join(resultsDir, `${runId}.json`);
+	assertInsideRoot(resultsDir, resultPath, "Async result file");
+	return fs.existsSync(resultPath) ? resultPath : null;
+}
+
+export function findAsyncRunPrefixMatches(prefix: string, asyncDirRoot: string, resultsDir: string): Array<{ id: string; location: AsyncRunLocation }> {
+	const requestedId = assertRunId(prefix, "id");
+	if (!requestedId) return [];
+	const asyncRoot = path.resolve(asyncDirRoot);
+	const resultRoot = path.resolve(resultsDir);
+	const matchingIds = [...new Set([
+		...prefixedRunIds(asyncRoot, requestedId),
+		...prefixedRunIds(resultRoot, requestedId, ".json"),
+	])].sort();
+	return matchingIds.map((id) => {
+		const asyncDir = path.join(asyncRoot, id);
+		assertInsideRoot(asyncRoot, asyncDir, "Async run directory");
+		return {
+			id,
+			location: {
+				asyncDir: fs.existsSync(asyncDir) ? asyncDir : null,
+				resultPath: exactResultPath(resultRoot, id),
+				resolvedId: id,
+			},
+		};
+	});
+}
+
+export function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot: string, resultsDir: string): AsyncRunLocation {
+	const asyncRoot = path.resolve(asyncDirRoot);
+	const resultRoot = path.resolve(resultsDir);
+	const requestedId = assertRunId(params.id, "id") ?? assertRunId(params.runId, "runId");
+	if (params.dir) {
+		const asyncDir = path.resolve(params.dir);
+		assertInsideRoot(asyncRoot, asyncDir, "Async run directory");
+		const resolvedId = requestedId ?? path.basename(asyncDir);
+		if (requestedId && requestedId !== path.basename(asyncDir)) {
+			throw new Error(`Async run id '${requestedId}' does not match directory '${path.basename(asyncDir)}'.`);
+		}
+		return { asyncDir, resultPath: exactResultPath(resultRoot, resolvedId), resolvedId };
+	}
+	if (!requestedId) return { asyncDir: null, resultPath: null };
+
+	const directAsyncDir = path.join(asyncRoot, requestedId);
+	assertInsideRoot(asyncRoot, directAsyncDir, "Async run directory");
+	const directResultPath = exactResultPath(resultRoot, requestedId);
+	if (fs.existsSync(directAsyncDir) || directResultPath) {
+		return {
+			asyncDir: fs.existsSync(directAsyncDir) ? directAsyncDir : null,
+			resultPath: directResultPath,
+			resolvedId: requestedId,
+		};
+	}
+
+	const matching = findAsyncRunPrefixMatches(requestedId, asyncRoot, resultRoot);
+	if (matching.length === 0) return { asyncDir: null, resultPath: null, resolvedId: requestedId };
+	if (matching.length > 1) {
+		throw new Error(`Ambiguous async run id prefix '${requestedId}' matched: ${matching.map((match) => match.id).join(", ")}. Provide a longer id.`);
+	}
+	return matching[0]!.location;
+}
+
+function resultState(result: AsyncResultFile): AsyncStatus["state"] {
+	if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "running" || result.state === "queued") {
+		return result.state;
+	}
+	return result.success ? "complete" : "failed";
+}
+
+function validateStatusForResume(status: AsyncStatus | null, source: string): void {
+	if (!status) return;
+	if (typeof status.runId !== "string") throw new Error(`Invalid async status '${source}': runId must be a string.`);
+	if (status.sessionId !== undefined && typeof status.sessionId !== "string") throw new Error(`Invalid async status '${source}': sessionId must be a string.`);
+	if (status.cwd !== undefined && typeof status.cwd !== "string") throw new Error(`Invalid async status '${source}': cwd must be a string.`);
+	if (status.sessionFile !== undefined && typeof status.sessionFile !== "string") throw new Error(`Invalid async status '${source}': sessionFile must be a string.`);
+	if (status.steps !== undefined) {
+		if (!Array.isArray(status.steps)) throw new Error(`Invalid async status '${source}': steps must be an array.`);
+		status.steps.forEach((step, index) => {
+			if (!step || typeof step !== "object" || Array.isArray(step)) throw new Error(`Invalid async status '${source}': steps[${index}] must be an object.`);
+			if (typeof step.agent !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
+			if (step.sessionFile !== undefined && typeof step.sessionFile !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);
+		});
+	}
+}
+
+function validateResumeSessionFile(runId: string, sessionFile: string): string {
+	if (path.extname(sessionFile) !== ".jsonl") throw new Error(`Async run '${runId}' session file must be a .jsonl file: ${sessionFile}`);
+	const resolved = path.resolve(sessionFile);
+	if (!fs.existsSync(resolved)) throw new Error(`Async run '${runId}' session file does not exist: ${sessionFile}`);
+	return resolved;
+}
+
+export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncResumeDeps = {}): AsyncResumeTarget {
+	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	const location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
+	if (!location.asyncDir && !location.resultPath) {
+		throw new Error("Async run not found. Provide id or dir.");
+	}
+
+	const reconciliation = location.asyncDir
+		? reconcileAsyncRun(location.asyncDir, { resultsDir, kill: deps.kill, now: deps.now })
+		: undefined;
+	const status = reconciliation?.status ?? null;
+	validateStatusForResume(status, location.asyncDir ? path.join(location.asyncDir, "status.json") : "status.json");
+	const result = location.resultPath ? readResultFile(location.resultPath) : undefined;
+	const runId = status?.runId ?? result?.runId ?? result?.id ?? location.resolvedId ?? (location.asyncDir ? path.basename(location.asyncDir) : "unknown");
+	const state = status?.state ?? (result ? resultState(result) : undefined);
+	if (!state) throw new Error(`Status file not found for async run '${runId}'.`);
+
+	const statusSteps = status?.steps ?? [];
+	const resultSteps = result?.results ?? [];
+	const stepCount = statusSteps.length || resultSteps.length || (result?.agent ? 1 : 0);
+	const requestedIndex = params.index;
+	if (requestedIndex !== undefined && !Number.isInteger(requestedIndex)) throw new Error(`Async run '${runId}' index must be an integer.`);
+	const terminalStepStatuses = new Set(["complete", "completed", "failed", "paused"]);
+
+	if (state === "running") {
+		if (requestedIndex !== undefined) {
+			if (requestedIndex < 0 || requestedIndex >= stepCount) throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${requestedIndex} is out of range.`);
+			const selectedStep = statusSteps[requestedIndex];
+			if (selectedStep?.status === "running") {
+				return {
+					kind: "live",
+					runId,
+					asyncDir: location.asyncDir ?? undefined,
+					state,
+					agent: selectedStep.agent,
+					index: requestedIndex,
+					intercomTarget: resolveSubagentIntercomTarget(runId, selectedStep.agent, requestedIndex),
+					cwd: status?.cwd ?? result?.cwd,
+					sessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+				};
+			}
+			if (selectedStep?.status === "pending") throw new Error(`Async run '${runId}' child ${requestedIndex} is pending and has not started yet. Wait for it to run or complete before resuming.`);
+			if (selectedStep && !terminalStepStatuses.has(selectedStep.status)) throw new Error(`Async run '${runId}' child ${requestedIndex} is ${selectedStep.status} and cannot be revived yet.`);
+		} else {
+			const running = statusSteps
+				.map((step, index) => ({ step, index }))
+				.filter(({ step }) => step.status === "running");
+			const selected = running.length === 1 ? running[0] : undefined;
+			if (!selected) {
+				throw new Error(`Async run '${runId}' has ${running.length} running children. Provide index to choose one.`);
+			}
+			return {
+				kind: "live",
+				runId,
+				asyncDir: location.asyncDir ?? undefined,
+				state,
+				agent: selected.step.agent,
+				index: selected.index,
+				intercomTarget: resolveSubagentIntercomTarget(runId, selected.step.agent, selected.index),
+				cwd: status?.cwd ?? result?.cwd,
+				sessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+			};
+		}
+	}
+
+	if (stepCount > 1 && requestedIndex === undefined) {
+		throw new Error(`Async run '${runId}' has ${stepCount} children. Provide index to choose one.`);
+	}
+	const index = requestedIndex ?? 0;
+	if (!Number.isInteger(index)) throw new Error(`Async run '${runId}' index must be an integer.`);
+	if (index < 0 || index >= stepCount) throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${index} is out of range.`);
+	const agent = statusSteps[index]?.agent ?? resultSteps[index]?.agent ?? result?.agent;
+	if (!agent) throw new Error(`Could not determine child agent for async run '${runId}'.`);
+	const sessionFile = statusSteps[index]?.sessionFile
+		?? resultSteps[index]?.sessionFile
+		?? (stepCount === 1 ? status?.sessionFile ?? result?.sessionFile : undefined);
+	if (!sessionFile) throw new Error(`Async run '${runId}' child ${index} does not have a persisted session file to resume from.`);
+	const resolvedSessionFile = validateResumeSessionFile(runId, sessionFile);
+
+	return {
+		kind: "revive",
+		runId,
+		asyncDir: location.asyncDir ?? undefined,
+		state,
+		agent,
+		index,
+		intercomTarget: resolveSubagentIntercomTarget(runId, agent, index),
+		cwd: status?.cwd ?? result?.cwd,
+		sessionFile: resolvedSessionFile,
+	};
+}
+
+export function buildRevivedAsyncTask(target: AsyncResumeTarget, message: string): string {
+	return [
+		"You are reviving a previous subagent conversation.",
+		"",
+		`Original run: ${target.runId}`,
+		`Original agent: ${target.agent}`,
+		target.sessionFile ? `Original session file: ${target.sessionFile}` : undefined,
+		"",
+		"Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child process is still alive.",
+		"",
+		"Follow-up:",
+		message,
+	].filter((line): line is string => line !== undefined).join("\n");
+}