pi-subagents 0.24.4 → 0.27.0

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

@@ -2,14 +2,20 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
 import { formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.ts";
-import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type SubagentRunMode, type TokenUsage } from "../../shared/types.ts";
+import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type NestedRunSummary, type SubagentRunMode, type TokenUsage } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
+import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot } from "../shared/nested-events.ts";
+import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
-import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
 
 interface AsyncRunStepSummary {
 	index: number;
 	agent: string;
+	label?: string;
+	phase?: string;
+	outputName?: string;
+	structured?: boolean;
 	status: AsyncJobStep["status"];
 	activityState?: ActivityState;
 	lastActivityAt?: number;
@@ -28,6 +34,7 @@ interface AsyncRunStepSummary {
 	thinking?: string;
 	attemptedModels?: string[];
 	error?: string;
+	children?: NestedRunSummary[];
 }
 
 export interface AsyncRunSummary {
@@ -55,6 +62,8 @@ export interface AsyncRunSummary {
 	outputFile?: string;
 	totalTokens?: TokenUsage;
 	sessionFile?: string;
+	nestedChildren?: NestedRunSummary[];
+	nestedWarnings?: string[];
 }
 
 interface AsyncRunListOptions {
@@ -112,7 +121,7 @@ function deriveAsyncActivityState(asyncDir: string, status: AsyncStatus): { acti
 	};
 }
 
-function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string }): AsyncRunSummary {
+function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string }, nestedWarnings: string[] = []): AsyncRunSummary {
 	if (status.sessionId !== undefined && typeof status.sessionId !== "string") {
 		throw new Error(`Invalid async status '${path.join(asyncDir, "status.json")}': sessionId must be a string.`);
 	}
@@ -120,6 +129,46 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	const steps = status.steps ?? [];
 	const chainStepCount = status.chainStepCount ?? steps.length;
 	const parallelGroups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
+	let nestedChildren: NestedRunSummary[] = [];
+	if (nestedWarnings.length === 0) {
+		try {
+			nestedChildren = projectNestedRegistryForRoot(status.runId || path.basename(asyncDir))?.children ?? [];
+		} catch (error) {
+			nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
+		}
+	}
+	const summarizedSteps = steps.map((step, index) => {
+		const stepActivityState = step.activityState;
+		const stepLastActivityAt = step.lastActivityAt;
+		return {
+			index,
+			agent: step.agent,
+			...(step.label ? { label: step.label } : {}),
+			...(step.phase ? { phase: step.phase } : {}),
+			...(step.outputName ? { outputName: step.outputName } : {}),
+			...(step.structured ? { structured: step.structured } : {}),
+			status: step.status,
+			...(stepActivityState ? { activityState: stepActivityState } : {}),
+			...(stepLastActivityAt ? { lastActivityAt: stepLastActivityAt } : {}),
+			...(step.currentTool ? { currentTool: step.currentTool } : {}),
+			...(step.currentToolArgs ? { currentToolArgs: step.currentToolArgs } : {}),
+			...(step.currentToolStartedAt ? { currentToolStartedAt: step.currentToolStartedAt } : {}),
+			...(step.currentPath ? { currentPath: step.currentPath } : {}),
+			...(step.recentTools ? { recentTools: step.recentTools.map((tool) => ({ ...tool })) } : {}),
+			...(step.recentOutput ? { recentOutput: [...step.recentOutput] } : {}),
+			...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
+			...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
+			...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
+			...(step.tokens ? { tokens: step.tokens } : {}),
+			...(step.skills ? { skills: step.skills } : {}),
+			...(step.model ? { model: step.model } : {}),
+			...(step.thinking ? { thinking: step.thinking } : {}),
+			...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
+			...(step.error ? { error: step.error } : {}),
+			...(step.children?.length ? { children: step.children } : {}),
+		};
+	});
+	attachRootChildrenToSteps(status.runId || path.basename(asyncDir), summarizedSteps, nestedChildren);
 	return {
 		id: status.runId || path.basename(asyncDir),
 		asyncDir,
@@ -140,32 +189,9 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		currentStep: status.currentStep,
 		...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
 		...(parallelGroups.length ? { parallelGroups } : {}),
-		steps: steps.map((step, index) => {
-			const stepActivityState = step.activityState;
-			const stepLastActivityAt = step.lastActivityAt;
-			return {
-				index,
-				agent: step.agent,
-				status: step.status,
-				...(stepActivityState ? { activityState: stepActivityState } : {}),
-				...(stepLastActivityAt ? { lastActivityAt: stepLastActivityAt } : {}),
-				...(step.currentTool ? { currentTool: step.currentTool } : {}),
-				...(step.currentToolArgs ? { currentToolArgs: step.currentToolArgs } : {}),
-				...(step.currentToolStartedAt ? { currentToolStartedAt: step.currentToolStartedAt } : {}),
-				...(step.currentPath ? { currentPath: step.currentPath } : {}),
-				...(step.recentTools ? { recentTools: step.recentTools.map((tool) => ({ ...tool })) } : {}),
-				...(step.recentOutput ? { recentOutput: [...step.recentOutput] } : {}),
-				...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
-				...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
-				...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
-				...(step.tokens ? { tokens: step.tokens } : {}),
-				...(step.skills ? { skills: step.skills } : {}),
-				...(step.model ? { model: step.model } : {}),
-				...(step.thinking ? { thinking: step.thinking } : {}),
-				...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
-				...(step.error ? { error: step.error } : {}),
-			};
-		}),
+		steps: summarizedSteps,
+		...(nestedChildren.length ? { nestedChildren } : {}),
+		...(nestedWarnings.length ? { nestedWarnings } : {}),
 		...(status.sessionDir ? { sessionDir: status.sessionDir } : {}),
 		...(status.outputFile ? { outputFile: status.outputFile } : {}),
 		...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
@@ -212,7 +238,14 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 			: reconcileAsyncRun(asyncDir, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
 		const status = (reconciliation?.status ?? readStatus(asyncDir)) as (AsyncStatus & { cwd?: string }) | null;
 		if (!status) continue;
-		const summary = statusToSummary(asyncDir, status);
+		const nestedWarnings: string[] = [];
+		try {
+			const nestedRoute = findNestedRouteForRootId(status.runId || path.basename(asyncDir));
+			if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
+		} catch (error) {
+			nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
+		}
+		const summary = statusToSummary(asyncDir, status, nestedWarnings);
 		if (allowedStates && !allowedStates.has(summary.state)) continue;
 		if (options.sessionId && summary.sessionId !== options.sessionId) continue;
 		runs.push(summary);
@@ -234,7 +267,9 @@ function formatActivityFacts(input: { activityState?: ActivityState; lastActivit
 }
 
 function formatStepLine(step: AsyncRunStepSummary): string {
-	const parts = [`${step.index + 1}. ${step.agent}`, step.status];
+	const display = step.label ? `${step.label} (${step.agent})` : step.agent;
+	const phase = step.phase ? `[${step.phase}] ` : "";
+	const parts = [`${step.index + 1}. ${phase}${display}`, step.status];
 	const activity = formatActivityFacts(step);
 	if (activity) parts.push(activity);
 	const modelThinking = formatModelThinking(step.model, step.thinking);
@@ -285,7 +320,12 @@ export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active as
 		lines.push(`- ${formatRunHeader(run)}`);
 		for (const step of run.steps) {
 			lines.push(`  ${formatStepLine(step)}`);
+			lines.push(...formatNestedRunStatusLines(step.children, { indent: "    ", maxLines: 12 }));
 		}
+		const attached = new Set(run.steps.flatMap((step) => step.children?.map((child) => child.id) ?? []));
+		const unattached = run.nestedChildren?.filter((child) => !attached.has(child.id)) ?? [];
+		lines.push(...formatNestedRunStatusLines(unattached, { indent: "  ", maxLines: 12 }));
+		for (const warning of run.nestedWarnings ?? []) lines.push(`  Warning: ${warning}`);
 		const outputPath = formatAsyncRunOutputPath(run);
 		if (outputPath) lines.push(`  output: ${shortenPath(outputPath)}`);
 		if (run.sessionFile) lines.push(`  session: ${shortenPath(run.sessionFile)}`);

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

@@ -5,13 +5,18 @@ 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;
@@ -30,6 +35,47 @@ type ResultWatcherDeps = {
 	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
@@ -63,32 +109,21 @@ export function createResultWatcher(
 		const resultPath = path.join(resultsDir, file);
 		if (!fsApi.existsSync(resultPath)) return;
 		try {
-			const data = JSON.parse(fsApi.readFileSync(resultPath, "utf-8")) as {
-				id?: string;
-				runId?: string;
-				agent?: string;
-				success?: boolean;
-				state?: string;
-				mode?: string;
-				summary?: string;
-				results?: Array<{
-					agent?: string;
-					output?: string;
-					error?: string;
-					success?: boolean;
-					sessionFile?: string;
-					artifactPaths?: { outputPath?: string };
-					intercomTarget?: string;
-				}>;
-				sessionId?: string;
-				cwd?: string;
-				sessionFile?: string;
-				asyncDir?: string;
-				intercomTarget?: string;
-			};
+			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)) {
@@ -96,45 +131,49 @@ export function createResultWatcher(
 				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 childResults = Array.isArray(data.results) && data.results.length > 0
-					? data.results
-					: [{
-						agent: data.agent,
-						output: data.summary,
-						success: data.success,
-					}];
-				const runId = data.runId ?? data.id ?? file.replace(/\.json$/i, "");
 				const mode = data.mode === "single" || data.mode === "parallel" || data.mode === "chain"
 					? data.mode
-					: childResults.length > 1 ? "chain" : "single";
+					: resultChildren.length > 1 ? "chain" : "single";
 				const payload = buildSubagentResultIntercomPayload({
 					to: intercomTarget,
 					runId,
 					mode,
 					source: "async",
-					children: childResults.map((result = {}, index) => {
-						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 ?? (childResults.length === 1 ? data.sessionFile : undefined);
-						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 } : {}),
-							intercomTarget: result.intercomTarget,
-						};
-					}),
+					children: normalizedChildren,
 					asyncId: data.id,
 					asyncDir: data.asyncDir,
 				});
@@ -144,7 +183,25 @@ export function createResultWatcher(
 				}
 			}
 
-			pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, data);
+			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;

package/src/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/runs/background/run-status.ts

@@ -2,13 +2,16 @@ 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 } from "../../shared/types.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 } from "./stale-run-reconciler.ts";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegistryForRoot, type NestedRunResolutionScope } from "../shared/nested-events.ts";
 
 interface RunStatusParams {
 	action?: "status";
@@ -22,6 +25,8 @@ interface RunStatusDeps {
 	resultsDir?: string;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
+	state?: SubagentState;
+	nested?: NestedRunResolutionScope;
 }
 
 function hasExistingSessionFile(value: unknown): value is string {
@@ -44,6 +49,11 @@ function formatResumeGuidance(runId: string | undefined, children: Array<{ agent
 	return "Resume: unavailable; no child session file was persisted.";
 }
 
+function formatAcceptanceFinalizationSummary(finalization: NonNullable<NonNullable<AsyncStatus["steps"]>[number]["acceptance"]>["finalization"] | undefined): string {
+	if (!finalization) return "";
+	return `, finalization: ${finalization.status} after ${finalization.turns.length}/${finalization.maxTurns} turns`;
+}
+
 function stepLineLabel(status: AsyncStatus, index: number): string {
 	const steps = status.steps ?? [];
 	if (status.mode === "parallel") return `Agent ${index + 1}/${steps.length || 1}`;
@@ -57,10 +67,53 @@ function stepLineLabel(status: AsyncStatus, index: number): string {
 	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 {
@@ -79,7 +132,20 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 
 	let location;
 	try {
-		location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
+		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 {
@@ -115,6 +181,16 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 		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,
@@ -146,13 +222,22 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 				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}`);
+				const finalizationText = formatAcceptanceFinalizationSummary(step.acceptance?.finalization);
+				const acceptanceText = step.acceptance?.status ? `, acceptance: ${step.acceptance.status}${finalizationText}` : "";
+				const display = step.label ? `${step.label} (${step.agent})` : step.agent;
+				const phase = step.phase ? `[${step.phase}] ` : "";
+				lines.push(`${stepLineLabel(status, index)}: ${phase}${display} ${step.status}${modelText}${stepActivityText ? `, ${stepActivityText}` : ""}${acceptanceText}${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));