@pi-agents/orchid 0.1.0-beta.0

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

@@ -0,0 +1,307 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.ts";
+import { createFileCoalescer } from "../../shared/file-coalescer.ts";
+import {
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	type IntercomEventBus,
+	type NestedRunSummary,
+	type SubagentResultIntercomChild,
+	type SubagentState,
+} from "../../shared/types.ts";
+import {
+	attachNestedChildrenToResultChildren,
+	buildSubagentResultIntercomPayload,
+	compactNestedResultChildren,
+	deliverSubagentResultIntercomEvent,
+	resolveSubagentResultStatus,
+} from "../../intercom/result-intercom.ts";
+import { projectNestedRegistryForRoot, sanitizeSummary } from "../shared/nested-events.ts";
+
+const WATCHER_RESTART_DELAY_MS = 3000;
+const POLL_INTERVAL_MS = 3000;
+
+type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "watch">;
+
+type ResultWatcherTimers = {
+	setTimeout: typeof setTimeout;
+	clearTimeout: typeof clearTimeout;
+	setInterval: typeof setInterval;
+	clearInterval: typeof clearInterval;
+};
+
+type ResultWatcherDeps = {
+	fs?: ResultWatcherFs;
+	timers?: ResultWatcherTimers;
+};
+
+type ResultFileChild = {
+	agent?: string;
+	output?: string;
+	error?: string;
+	success?: boolean;
+	sessionFile?: string;
+	artifactPaths?: { outputPath?: string };
+	intercomTarget?: string;
+	children?: unknown;
+};
+
+type ResultFileData = {
+	id?: string;
+	runId?: string;
+	agent?: string;
+	success?: boolean;
+	state?: string;
+	mode?: string;
+	summary?: string;
+	results?: ResultFileChild[];
+	nestedChildren?: unknown;
+	sessionId?: string;
+	cwd?: string;
+	sessionFile?: string;
+	asyncDir?: string;
+	intercomTarget?: string;
+};
+
+function sanitizeNestedResultChildren(value: unknown, resultPath: string, label: string): NestedRunSummary[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value)) {
+		console.error(`Ignoring invalid nested children in subagent result file '${resultPath}' at ${label}: expected an array.`);
+		return undefined;
+	}
+	const children = value.map((child) => sanitizeSummary(child)).filter((child): child is NestedRunSummary => Boolean(child));
+	if (children.length !== value.length) {
+		console.error(`Ignoring ${value.length - children.length} invalid nested child record(s) in subagent result file '${resultPath}' at ${label}.`);
+	}
+	return children.length ? children : undefined;
+}
+
+function getErrorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error
+		? (error as NodeJS.ErrnoException).code
+		: undefined;
+}
+
+function isNotFoundError(error: unknown): boolean {
+	return getErrorCode(error) === "ENOENT";
+}
+
+function shouldFallBackToPolling(error: unknown): boolean {
+	const code = getErrorCode(error);
+	return code === "EMFILE" || code === "ENOSPC";
+}
+
+export function createResultWatcher(
+	pi: { events: IntercomEventBus },
+	state: SubagentState,
+	resultsDir: string,
+	completionTtlMs: number,
+	deps: ResultWatcherDeps = {},
+): {
+	startResultWatcher: () => void;
+	primeExistingResults: () => void;
+	stopResultWatcher: () => void;
+} {
+	const fsApi = deps.fs ?? fs;
+	const timers = deps.timers ?? { setTimeout, clearTimeout, setInterval, clearInterval };
+
+	const handleResult = async (file: string) => {
+		const resultPath = path.join(resultsDir, file);
+		if (!fsApi.existsSync(resultPath)) return;
+		try {
+			const data = JSON.parse(fsApi.readFileSync(resultPath, "utf-8")) as ResultFileData;
+			if (data.sessionId && data.sessionId !== state.currentSessionId) return;
+			if (!data.sessionId && data.cwd && (!state.baseCwd || data.cwd !== state.baseCwd)) return;
+
+			const runId = data.runId ?? data.id ?? file.replace(/\.json$/i, "");
+			const hasExplicitNestedChildren = data.nestedChildren !== undefined;
+			let nestedChildren = compactNestedResultChildren(sanitizeNestedResultChildren(data.nestedChildren, resultPath, "nestedChildren"));
+			if (!nestedChildren?.length && !hasExplicitNestedChildren) {
+				try {
+					nestedChildren = compactNestedResultChildren(projectNestedRegistryForRoot(runId)?.children);
+				} catch (error) {
+					console.error(`Failed to enrich subagent result file '${resultPath}' with nested registry children; will retry later:`, error);
+					return;
+				}
+			}
+			const now = Date.now();
+			const completionKey = buildCompletionKey(data, `result:${file}`);
+			if (markSeenWithTtl(state.completionSeen, completionKey, now, completionTtlMs)) {
+				fsApi.unlinkSync(resultPath);
+				return;
+			}
+
+			const hasResultChildren = Array.isArray(data.results) && data.results.length > 0;
+			const resultChildren = hasResultChildren
+				? data.results!
+				: [{
+					agent: data.agent,
+					output: data.summary,
+					success: data.success,
+				}];
+			const normalizedChildren = attachNestedChildrenToResultChildren(runId, resultChildren.map((result = {}, index): SubagentResultIntercomChild => {
+				const baseOutput = result.output ?? data.summary;
+				const hasRealOutput = typeof baseOutput === "string" && baseOutput.trim().length > 0;
+				const output = hasRealOutput ? baseOutput : "(no output)";
+				const summary = result.success === false && result.error
+					? `${result.error}${hasRealOutput ? `\n\nOutput:\n${baseOutput}` : ""}`
+					: output;
+				const sessionPath = result.sessionFile ?? (resultChildren.length === 1 ? data.sessionFile : undefined);
+				const childNestedChildren = sanitizeNestedResultChildren(result.children, resultPath, `results[${index}].children`);
+				return {
+					agent: result.agent ?? data.agent ?? `step-${index + 1}`,
+					status: resolveSubagentResultStatus({
+						success: result.success,
+						state: data.state === "paused" || typeof result.success !== "boolean" ? data.state : undefined,
+					}),
+					summary,
+					index,
+					artifactPath: result.artifactPaths?.outputPath,
+					...(typeof sessionPath === "string" && fsApi.existsSync(sessionPath) ? { sessionPath } : {}),
+					...(result.intercomTarget ? { intercomTarget: result.intercomTarget } : {}),
+					...(childNestedChildren ? { children: childNestedChildren } : {}),
+				};
+			}), nestedChildren);
+
+			const intercomTarget = data.intercomTarget?.trim();
+			if (intercomTarget) {
+				const mode = data.mode === "single" || data.mode === "parallel" || data.mode === "chain"
+					? data.mode
+					: resultChildren.length > 1 ? "chain" : "single";
+				const payload = buildSubagentResultIntercomPayload({
+					to: intercomTarget,
+					runId,
+					mode,
+					source: "async",
+					children: normalizedChildren,
+					asyncId: data.id,
+					asyncDir: data.asyncDir,
+				});
+				const delivered = await deliverSubagentResultIntercomEvent(pi.events, payload);
+				if (!delivered) {
+					console.error(`Subagent async grouped result intercom delivery was not acknowledged for '${resultPath}'.`);
+				}
+			}
+
+			pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
+				...data,
+				runId,
+				...(nestedChildren?.length ? { nestedChildren } : {}),
+				...(Array.isArray(data.results) ? {
+					results: hasResultChildren
+						? normalizedChildren.map((child, index) => ({
+							...data.results![index],
+							agent: child.agent,
+							status: child.status,
+							summary: child.summary,
+							index: child.index,
+							artifactPath: child.artifactPath,
+							sessionPath: child.sessionPath,
+							children: child.children,
+						}))
+						: [],
+				} : {}),
+			});
+			fsApi.unlinkSync(resultPath);
+		} catch (error) {
+			if (isNotFoundError(error)) return;
+			console.error(`Failed to process subagent result file '${resultPath}':`, error);
+		}
+	};
+
+	state.resultFileCoalescer = createFileCoalescer((file) => {
+		void handleResult(file);
+	}, 50);
+
+	const primeExistingResults = () => {
+		try {
+			fsApi.readdirSync(resultsDir)
+				.filter((f) => f.endsWith(".json"))
+				.forEach((file) => state.resultFileCoalescer.schedule(file, 0));
+		} catch (error) {
+			if (isNotFoundError(error)) return;
+			console.error(`Failed to scan subagent result directory '${resultsDir}':`, error);
+		}
+	};
+
+	const startPollingFallback = (reason: unknown) => {
+		state.watcher?.close();
+		state.watcher = null;
+		if (state.watcherRestartTimer) return;
+
+		console.error(
+			`Subagent result watcher for '${resultsDir}' fell back to polling because native fs.watch is unavailable (${getErrorCode(reason) ?? "unknown error"}).`,
+		);
+		primeExistingResults();
+		state.watcherRestartTimer = timers.setInterval(primeExistingResults, POLL_INTERVAL_MS);
+		state.watcherRestartTimer.unref?.();
+	};
+
+	const scheduleRestart = () => {
+		if (state.watcherRestartTimer) return;
+		state.watcherRestartTimer = timers.setTimeout(() => {
+			state.watcherRestartTimer = null;
+			try {
+				fsApi.mkdirSync(resultsDir, { recursive: true });
+				startResultWatcher();
+			} catch (error) {
+				if (shouldFallBackToPolling(error)) {
+					startPollingFallback(error);
+					return;
+				}
+				console.error(`Failed to restart subagent result watcher for '${resultsDir}':`, error);
+				scheduleRestart();
+			}
+		}, WATCHER_RESTART_DELAY_MS);
+		state.watcherRestartTimer.unref?.();
+	};
+
+	const startResultWatcher = () => {
+		if (state.watcher) return;
+		if (state.watcherRestartTimer) {
+			timers.clearTimeout(state.watcherRestartTimer);
+			timers.clearInterval(state.watcherRestartTimer);
+			state.watcherRestartTimer = null;
+		}
+		try {
+			state.watcher = fsApi.watch(resultsDir, (ev, file) => {
+				if (ev !== "rename" || !file) return;
+				const fileName = file.toString();
+				if (!fileName.endsWith(".json")) return;
+				state.resultFileCoalescer.schedule(fileName);
+			});
+			state.watcher.on("error", (error) => {
+				if (shouldFallBackToPolling(error)) {
+					startPollingFallback(error);
+					return;
+				}
+				console.error(`Subagent result watcher failed for '${resultsDir}':`, error);
+				state.watcher?.close();
+				state.watcher = null;
+				scheduleRestart();
+			});
+			state.watcher.unref?.();
+		} catch (error) {
+			if (shouldFallBackToPolling(error)) {
+				startPollingFallback(error);
+				return;
+			}
+			console.error(`Failed to start subagent result watcher for '${resultsDir}':`, error);
+			state.watcher = null;
+			scheduleRestart();
+		}
+	};
+
+	const stopResultWatcher = () => {
+		state.watcher?.close();
+		state.watcher = null;
+		if (state.watcherRestartTimer) {
+			timers.clearTimeout(state.watcherRestartTimer);
+			timers.clearInterval(state.watcherRestartTimer);
+		}
+		state.watcherRestartTimer = null;
+		state.resultFileCoalescer.clear();
+	};
+
+	return { startResultWatcher, primeExistingResults, stopResultWatcher };
+}

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

@@ -0,0 +1,83 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ASYNC_DIR, RESULTS_DIR, type SubagentState } from "../../shared/types.ts";
+import { findAsyncRunPrefixMatches, type AsyncRunLocation } from "./async-resume.ts";
+import { assertSafeNestedId, findNestedRunMatchesById, type NestedRoute, type NestedRunMatch, type NestedRunResolutionScope } from "../shared/nested-events.ts";
+
+export type ResolvedSubagentRunId =
+	| { kind: "foreground"; id: string }
+	| { kind: "async"; id: string; location: AsyncRunLocation }
+	| { kind: "nested"; id: string; match: NestedRunMatch };
+
+export interface ResolveSubagentRunIdDeps {
+	state?: SubagentState;
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	nested?: NestedRunResolutionScope;
+}
+
+function exactAsyncLocation(id: string, asyncDirRoot: string, resultsDir: string): AsyncRunLocation | undefined {
+	const asyncDir = path.join(asyncDirRoot, id);
+	const resultPath = path.join(resultsDir, `${id}.json`);
+	if (!fs.existsSync(asyncDir) && !fs.existsSync(resultPath)) return undefined;
+	return {
+		asyncDir: fs.existsSync(asyncDir) ? asyncDir : null,
+		resultPath: fs.existsSync(resultPath) ? resultPath : null,
+		resolvedId: id,
+	};
+}
+
+function foregroundIds(state: SubagentState | undefined): string[] {
+	return state ? [...state.foregroundControls.keys()] : [];
+}
+
+function nestedScopeFromState(state: SubagentState | undefined): NestedRunResolutionScope | undefined {
+	if (!state) return undefined;
+	const routes: NestedRoute[] = [];
+	const seen = new Set<string>();
+	const add = (route: NestedRoute | undefined) => {
+		if (!route) return;
+		const key = `${route.rootRunId}:${route.eventSink}:${route.controlInbox}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		routes.push(route);
+	};
+	for (const control of state.foregroundControls.values()) add(control.nestedRoute as NestedRoute | undefined);
+	for (const job of state.asyncJobs.values()) add(job.nestedRoute as NestedRoute | undefined);
+	return { routes };
+}
+
+function asyncPrefixMatches(prefix: string, asyncDirRoot: string, resultsDir: string): Array<{ id: string; location: AsyncRunLocation }> {
+	return findAsyncRunPrefixMatches(prefix, asyncDirRoot, resultsDir);
+}
+
+export function resolveSubagentRunId(id: string, deps: ResolveSubagentRunIdDeps = {}): ResolvedSubagentRunId | undefined {
+	assertSafeNestedId("id", id);
+	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+
+	const nestedScope = deps.nested ?? nestedScopeFromState(deps.state);
+	if (deps.state?.foregroundControls.has(id)) return { kind: "foreground", id };
+	const exactAsync = exactAsyncLocation(id, asyncDirRoot, resultsDir);
+	if (exactAsync) return { kind: "async", id, location: exactAsync };
+	const exactNested = findNestedRunMatchesById(id, nestedScope ? { scope: nestedScope } : {});
+	if (exactNested.length > 1) throw new Error(`Nested run id '${id}' is ambiguous across authorized registries. Provide the full id after stale registries are cleaned up.`);
+	if (exactNested[0]) return { kind: "nested", id, match: exactNested[0] };
+
+	const matches: ResolvedSubagentRunId[] = [];
+	for (const foregroundId of foregroundIds(deps.state).filter((candidate) => candidate.startsWith(id))) {
+		matches.push({ kind: "foreground", id: foregroundId });
+	}
+	for (const match of asyncPrefixMatches(id, asyncDirRoot, resultsDir)) {
+		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 });
+	}
+	const unique = new Map(matches.map((match) => [`${match.kind}:${match.id}`, match]));
+	const values = [...unique.values()];
+	if (values.length > 1) {
+		throw new Error(`Ambiguous subagent run id prefix '${id}' matched: ${values.map((match) => `${match.kind}:${match.id}`).join(", ")}. Provide a longer id.`);
+	}
+	return values[0];
+}

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

@@ -0,0 +1,269 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { formatAsyncRunList, formatAsyncRunOutputPath, formatAsyncRunProgressLabel, listAsyncRuns } from "./async-status.ts";
+import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
+import { formatModelThinking } from "../../shared/formatters.ts";
+import { formatActivityLabel } from "../../shared/status-format.ts";
+import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type Details, type NestedRunSummary, type SubagentState } from "../../shared/types.ts";
+import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
+import { resolveAsyncRunLocation } from "./async-resume.ts";
+import { resolveSubagentRunId } from "./run-id-resolver.ts";
+import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot, type NestedRunResolutionScope } from "../shared/nested-events.ts";
+
+interface RunStatusParams {
+	action?: "status";
+	id?: string;
+	runId?: string;
+	dir?: string;
+}
+
+interface RunStatusDeps {
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+	state?: SubagentState;
+	nested?: NestedRunResolutionScope;
+}
+
+function hasExistingSessionFile(value: unknown): value is string {
+	return typeof value === "string" && fs.existsSync(value);
+}
+
+function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown }>, fallbackSessionFile?: unknown): string {
+	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 singleSessionFile = knownChildren[0]?.child.sessionFile ?? fallbackSessionFile;
+	if (children.length === 1 && knownChildren.length === 1 && hasExistingSessionFile(singleSessionFile)) {
+		return `Revive: subagent({ action: "resume", id: "${runId}", message: "..." })`;
+	}
+	const childWithSession = knownChildren.find(({ child }) => hasExistingSessionFile(child.sessionFile));
+	if (childWithSession) {
+		return `Revive child: subagent({ action: "resume", id: "${runId}", index: ${childWithSession.index}, message: "..." })`;
+	}
+	return "Resume: unavailable; no child session file was persisted.";
+}
+
+function stepLineLabel(status: AsyncStatus, index: number): string {
+	const steps = status.steps ?? [];
+	if (status.mode === "parallel") return `Agent ${index + 1}/${steps.length || 1}`;
+	if (status.mode === "chain") {
+		const chainStepCount = status.chainStepCount ?? (steps.length || 1);
+		const groups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
+		const group = groups.find((candidate) => index >= candidate.start && index < candidate.start + candidate.count);
+		if (group) return `Step ${group.stepIndex + 1}/${chainStepCount} Agent ${index - group.start + 1}/${group.count}`;
+		return `Step ${flatToLogicalStepIndex(index, chainStepCount, groups) + 1}/${chainStepCount}`;
+	}
+	return `Step ${index + 1}`;
+}
+
+function nestedRunDisplayName(run: NestedRunSummary): string {
+	if (run.agent) return run.agent;
+	if (run.agents?.length) return run.agents.join(", ");
+	return run.id;
+}
+
+function formatNestedExactStatus(rootRunId: string, run: NestedRunSummary): string {
+	const lines = [
+		`Nested run: ${run.id}`,
+		`Root: ${rootRunId}`,
+		`Parent: ${run.parentRunId}${run.parentStepIndex !== undefined ? ` step ${run.parentStepIndex + 1}` : ""}`,
+		`State: ${run.state}`,
+		run.activityState || run.lastActivityAt ? `Activity: ${formatActivityLabel(run.lastActivityAt, run.activityState)}` : undefined,
+		run.mode ? `Mode: ${run.mode}` : undefined,
+		`Agent: ${nestedRunDisplayName(run)}`,
+		run.currentStep !== undefined ? `Progress: step ${run.currentStep + 1}/${run.chainStepCount ?? run.steps?.length ?? 1}` : undefined,
+		run.asyncDir ? `Dir: ${run.asyncDir}` : undefined,
+		run.sessionFile ? `Session: ${run.sessionFile}` : undefined,
+		run.error ? `Error: ${run.error}` : undefined,
+	].filter((line): line is string => Boolean(line));
+	if (run.path.length) {
+		lines.push(`Path: ${run.path.map((part) => `${part.runId}${part.stepIndex !== undefined ? `:${part.stepIndex + 1}` : ""}${part.agent ? `:${part.agent}` : ""}`).join(" > ")} > ${run.id}`);
+	}
+	if (run.steps?.length) {
+		lines.push("Steps:");
+		for (const [index, step] of run.steps.entries()) {
+			const activity = step.status === "running" ? formatActivityLabel(step.lastActivityAt, step.activityState) : undefined;
+			lines.push(`  ${index + 1}. ${step.agent} ${step.status}${activity ? `, ${activity}` : ""}${step.error ? `, error: ${step.error}` : ""}`);
+			lines.push(...formatNestedRunStatusLines(step.children, { indent: "    ", commandHints: true }));
+		}
+	}
+	lines.push(...formatNestedRunStatusLines(run.children, { indent: "  ", commandHints: true }));
+	lines.push("Commands:", `  Status: subagent({ action: "status", id: "${run.id}" })`, `  Interrupt: subagent({ action: "interrupt", id: "${run.id}" })`, `  Resume: subagent({ action: "resume", id: "${run.id}", message: "..." })`, `  Root status: subagent({ action: "status", id: "${rootRunId}" })`);
+	return lines.join("\n");
+}
+
+export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDeps = {}): AgentToolResult<Details> {
+	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	if (!params.id && !params.runId && !params.dir) {
+		if (deps.nested) {
+			return {
+				content: [{ type: "text", text: "Child-safe subagent status requires an id when no foreground run is active." }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+		try {
+			const runs = listAsyncRuns(asyncDirRoot, { states: ["queued", "running"], resultsDir, kill: deps.kill, now: deps.now });
+			return {
+				content: [{ type: "text", text: formatAsyncRunList(runs) }],
+				details: { mode: "single", results: [] },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	let location;
+	try {
+		const requestedId = params.id ?? params.runId;
+		if (!params.dir && requestedId) {
+			const resolved = resolveSubagentRunId(requestedId, { asyncDirRoot, resultsDir, state: deps.state, nested: deps.nested });
+			if (resolved?.kind === "nested") {
+				reconcileNestedAsyncDescendants(resolved.match.route, { resultsDir, kill: deps.kill, now: deps.now });
+				const refreshed = resolveSubagentRunId(requestedId, { asyncDirRoot, resultsDir, state: deps.state, nested: deps.nested });
+				const nested = refreshed?.kind === "nested" ? refreshed : resolved;
+				return { content: [{ type: "text", text: formatNestedExactStatus(nested.match.rootRunId, nested.match.run) }], details: { mode: "single", results: [] } };
+			}
+			if (resolved?.kind === "async") location = resolved.location;
+			else location = { asyncDir: null, resultPath: null, resolvedId: requestedId };
+		} else {
+			location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: message }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+	const { asyncDir, resultPath, resolvedId } = location;
+
+	if (!asyncDir && !resultPath) {
+		return {
+			content: [{ type: "text", text: "Async run not found. Provide id or dir." }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+
+	if (asyncDir) {
+		let reconciliation;
+		try {
+			reconciliation = reconcileAsyncRun(asyncDir, { resultsDir, kill: deps.kill, now: deps.now });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+		const status = reconciliation.status;
+		const effectiveRunId = status?.runId ?? resolvedId ?? "unknown";
+		const logPath = path.join(asyncDir, `subagent-log-${effectiveRunId}.md`);
+		const eventsPath = path.join(asyncDir, "events.jsonl");
+		if (status) {
+			let nestedChildren: NestedRunSummary[] = [];
+			let nestedWarning: string | undefined;
+			try {
+				const nestedRoute = findNestedRouteForRootId(status.runId);
+				if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir, kill: deps.kill, now: deps.now });
+				nestedChildren = projectNestedRegistryForRoot(status.runId)?.children ?? [];
+				attachRootChildrenToSteps(status.runId, status.steps, nestedChildren);
+			} catch (error) {
+				nestedWarning = `Nested status unavailable: ${error instanceof Error ? error.message : String(error)}`;
+			}
+			const outputPath = formatAsyncRunOutputPath({ asyncDir, outputFile: status.outputFile });
+			const progressLabel = formatAsyncRunProgressLabel({
+				mode: status.mode,
+				state: status.state,
+				currentStep: status.currentStep,
+				chainStepCount: status.chainStepCount,
+				parallelGroups: status.parallelGroups,
+				steps: (status.steps ?? []).map((step, index) => ({ index, agent: step.agent, status: step.status })),
+			});
+			const started = new Date(status.startedAt).toISOString();
+			const updated = status.lastUpdate ? new Date(status.lastUpdate).toISOString() : "n/a";
+			const statusActivityText = status.state === "running" ? formatActivityLabel(status.lastActivityAt, status.activityState) : undefined;
+
+			const lines = [
+				`Run: ${status.runId}`,
+				`State: ${status.state}`,
+				statusActivityText ? `Activity: ${statusActivityText}` : undefined,
+				`Mode: ${status.mode}`,
+				`Progress: ${progressLabel}`,
+				`Started: ${started}`,
+				`Updated: ${updated}`,
+				`Dir: ${asyncDir}`,
+				outputPath ? `Output: ${outputPath}` : undefined,
+				reconciliation.message ? `Diagnosis: ${reconciliation.message}` : undefined,
+				reconciliation.resultPath && fs.existsSync(reconciliation.resultPath) ? `Result: ${reconciliation.resultPath}` : undefined,
+			].filter((line): line is string => Boolean(line));
+			for (const [index, step] of (status.steps ?? []).entries()) {
+				const stepActivityText = step.status === "running" ? formatActivityLabel(step.lastActivityAt, step.activityState) : undefined;
+				const modelThinking = formatModelThinking(step.model, step.thinking);
+				const modelText = modelThinking ? ` (${modelThinking})` : "";
+				const errorText = step.error ? `, error: ${step.error}` : "";
+				lines.push(`${stepLineLabel(status, index)}: ${step.agent} ${step.status}${modelText}${stepActivityText ? `, ${stepActivityText}` : ""}${errorText}`);
+				lines.push(...formatNestedRunStatusLines(step.children, { indent: "  ", commandHints: true, maxLines: 20 }));
+				const stepOutputPath = path.join(asyncDir, `output-${index}.log`);
+				if (stepOutputPath !== outputPath && fs.existsSync(stepOutputPath)) lines.push(`  Output: ${stepOutputPath}`);
+				if (step.status === "running") {
+					lines.push(`  Intercom target: ${resolveSubagentIntercomTarget(status.runId, step.agent, index)} (if registered)`);
+				}
+			}
+			const attached = new Set((status.steps ?? []).flatMap((step) => step.children?.map((child) => child.id) ?? []));
+			const unattached = nestedChildren.filter((child) => !attached.has(child.id));
+			lines.push(...formatNestedRunStatusLines(unattached, { indent: "", commandHints: true, maxLines: 20 }));
+			if (nestedWarning) lines.push(`Warning: ${nestedWarning}`);
+			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
+			if (status.state !== "running") {
+				lines.push(formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile));
+			}
+			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
+			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
+
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		}
+	}
+
+	if (resultPath) {
+		try {
+			const raw = fs.readFileSync(resultPath, "utf-8");
+			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; exitCode?: number; state?: string; sessionFile?: string; results?: Array<{ agent?: string; sessionFile?: string }> };
+			const status = data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
+			const runId = data.runId ?? data.id ?? resolvedId;
+			const lines = [`Run: ${runId}`, `State: ${status}`, `Result: ${resultPath}`];
+			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
+			lines.push(formatResumeGuidance(runId, children, data.sessionFile));
+			if (data.summary) lines.push("", data.summary);
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: `Failed to read async result file: ${message}` }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	return {
+		content: [{ type: "text", text: "Status file not found." }],
+		isError: true,
+		details: { mode: "single", results: [] },
+	};
+}