pi-subagents 0.24.3 → 0.25.0

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

@@ -11,7 +11,7 @@ import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
-import { injectSingleOutputInstruction, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildChainInstructions, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
@@ -24,6 +24,7 @@ import {
 	type ArtifactConfig,
 	type Details,
 	type MaxOutputConfig,
+	type NestedRouteInfo,
 	type ResolvedControlConfig,
 	type SubagentRunMode,
 	ASYNC_DIR,
@@ -33,6 +34,7 @@ import {
 	getAsyncConfigPath,
 	resolveChildMaxSubagentDepth,
 } from "../../shared/types.ts";
+import { nestedResultsPath, resolveInheritedNestedRouteFromEnv, resolveNestedParentAddressFromEnv, writeNestedEvent } from "../shared/nested-events.ts";
 
 const require = createRequire(import.meta.url);
 const piPackageRoot = resolvePiPackageRoot();
@@ -111,6 +113,7 @@ interface AsyncChainParams {
 	controlConfig?: ResolvedControlConfig;
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	nestedRoute?: NestedRouteInfo;
 }
 
 interface AsyncSingleParams {
@@ -126,7 +129,7 @@ interface AsyncSingleParams {
 	sessionRoot?: string;
 	sessionFile?: string;
 	skills?: string[];
-	output?: string | false;
+	output?: string | boolean;
 	outputMode?: "inline" | "file-only";
 	modelOverride?: string;
 	availableModels?: AvailableModelInfo[];
@@ -136,6 +139,7 @@ interface AsyncSingleParams {
 	controlConfig?: ResolvedControlConfig;
 	controlIntercomTarget?: string;
 	childIntercomTarget?: (agent: string, index: number) => string | undefined;
+	nestedRoute?: NestedRouteInfo;
 }
 
 interface AsyncExecutionResult {
@@ -236,6 +240,7 @@ export function executeAsyncChain(
 		controlConfig,
 		controlIntercomTarget,
 		childIntercomTarget,
+		nestedRoute,
 	} = params;
 	const resultMode = params.resultMode ?? "chain";
 	const chainSkills = params.chainSkills ?? [];
@@ -261,7 +266,11 @@ export function executeAsyncChain(
 		}
 	}
 
-	const asyncDir = path.join(ASYNC_DIR, id);
+	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
+	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
+	const asyncDir = inheritedNestedRoute
+		? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
+		: path.join(ASYNC_DIR, id);
 	try {
 		fs.mkdirSync(asyncDir, { recursive: true });
 	} catch (error) {
@@ -323,6 +332,7 @@ export function executeAsyncChain(
 			tools: a.tools,
 			extensions: a.extensions,
 			mcpDirectTools: a.mcpDirectTools,
+			completionGuard: a.completionGuard,
 			systemPrompt,
 			systemPromptMode: a.systemPromptMode,
 			inheritProjectContext: a.inheritProjectContext,
@@ -392,7 +402,7 @@ export function executeAsyncChain(
 			{
 				id,
 				steps,
-				resultPath: path.join(RESULTS_DIR, `${id}.json`),
+				resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : path.join(RESULTS_DIR, `${id}.json`),
 				cwd: runnerCwd,
 				placeholder: "{previous}",
 				maxOutput,
@@ -410,6 +420,13 @@ export function executeAsyncChain(
 				controlIntercomTarget,
 				childIntercomTargets,
 				resultMode,
+				nestedRoute: nestedRoute ?? inheritedNestedRoute,
+				nestedSelf: inheritedNestedRoute && nestedAddress ? {
+					parentRunId: nestedAddress.parentRunId,
+					parentStepIndex: nestedAddress.parentStepIndex,
+					depth: nestedAddress.depth,
+					path: nestedAddress.path,
+				} : undefined,
 			},
 			id,
 			runnerCwd,
@@ -442,6 +459,40 @@ export function executeAsyncChain(
 				flatStepStart++;
 			}
 		}
+		if (inheritedNestedRoute && nestedAddress) {
+			const now = Date.now();
+			try {
+				writeNestedEvent(inheritedNestedRoute, {
+					type: "subagent.nested.started",
+					ts: now,
+					parentRunId: nestedAddress.parentRunId,
+					parentStepIndex: nestedAddress.parentStepIndex,
+					child: {
+						id,
+						parentRunId: nestedAddress.parentRunId,
+						parentStepIndex: nestedAddress.parentStepIndex,
+						depth: nestedAddress.depth,
+						path: nestedAddress.path,
+						asyncDir,
+						pid: spawnResult.pid,
+						ownerIntercomTarget: process.env.PI_SUBAGENT_INTERCOM_SESSION_NAME,
+						leafIntercomTarget: childIntercomTargets?.[0],
+						intercomTarget: childIntercomTargets?.[0],
+						ownerState: "live",
+						mode: resultMode,
+						state: "running",
+						agent: firstAgents[0],
+						agents: flatAgents,
+						chainStepCount: chain.length,
+						parallelGroups,
+						startedAt: now,
+						lastUpdate: now,
+					},
+				});
+			} catch (error) {
+				console.error("Failed to emit nested async start event:", error);
+			}
+		}
 		ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
 			id,
 			pid: spawnResult.pid,
@@ -459,6 +510,7 @@ export function executeAsyncChain(
 			parallelGroups,
 			cwd: runnerCwd,
 			asyncDir,
+			nestedRoute,
 		});
 	}
 
@@ -498,6 +550,7 @@ export function executeAsyncSingle(
 		controlConfig,
 		controlIntercomTarget,
 		childIntercomTarget,
+		nestedRoute,
 	} = params;
 	const task = params.task ?? "";
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
@@ -511,7 +564,11 @@ export function executeAsyncSingle(
 		systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
 	}
 
-	const asyncDir = path.join(ASYNC_DIR, id);
+	const inheritedNestedRoute = resolveInheritedNestedRouteFromEnv();
+	const nestedAddress = inheritedNestedRoute ? resolveNestedParentAddressFromEnv() : undefined;
+	const asyncDir = inheritedNestedRoute
+		? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", inheritedNestedRoute.rootRunId, id)
+		: path.join(ASYNC_DIR, id);
 	try {
 		fs.mkdirSync(asyncDir, { recursive: true });
 	} catch (error) {
@@ -523,7 +580,8 @@ export function executeAsyncSingle(
 		};
 	}
 
-	const outputPath = resolveSingleOutputPath(params.output, ctx.cwd, runnerCwd);
+	const effectiveOutput = normalizeSingleOutputOverride(params.output, agentConfig.output);
+	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd);
 	const outputMode = params.outputMode ?? "inline";
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
@@ -550,6 +608,7 @@ export function executeAsyncSingle(
 						tools: agentConfig.tools,
 						extensions: agentConfig.extensions,
 						mcpDirectTools: agentConfig.mcpDirectTools,
+						completionGuard: agentConfig.completionGuard,
 						systemPrompt,
 						systemPromptMode: agentConfig.systemPromptMode,
 						inheritProjectContext: agentConfig.inheritProjectContext,
@@ -561,7 +620,7 @@ export function executeAsyncSingle(
 						maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
 					},
 				],
-				resultPath: path.join(RESULTS_DIR, `${id}.json`),
+				resultPath: inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : path.join(RESULTS_DIR, `${id}.json`),
 				cwd: runnerCwd,
 				placeholder: "{previous}",
 				maxOutput,
@@ -579,6 +638,13 @@ export function executeAsyncSingle(
 				controlIntercomTarget,
 				childIntercomTargets: childIntercomTarget ? [childIntercomTarget(agent, 0)] : undefined,
 				resultMode: "single",
+				nestedRoute: nestedRoute ?? inheritedNestedRoute,
+				nestedSelf: inheritedNestedRoute && nestedAddress ? {
+					parentRunId: nestedAddress.parentRunId,
+					parentStepIndex: nestedAddress.parentStepIndex,
+					depth: nestedAddress.depth,
+					path: nestedAddress.path,
+				} : undefined,
 			},
 			id,
 			runnerCwd,
@@ -593,6 +659,39 @@ export function executeAsyncSingle(
 	}
 
 	if (spawnResult.pid) {
+		if (inheritedNestedRoute && nestedAddress) {
+			const now = Date.now();
+			try {
+				writeNestedEvent(inheritedNestedRoute, {
+					type: "subagent.nested.started",
+					ts: now,
+					parentRunId: nestedAddress.parentRunId,
+					parentStepIndex: nestedAddress.parentStepIndex,
+					child: {
+						id,
+						parentRunId: nestedAddress.parentRunId,
+						parentStepIndex: nestedAddress.parentStepIndex,
+						depth: nestedAddress.depth,
+						path: nestedAddress.path,
+						asyncDir,
+						pid: spawnResult.pid,
+						ownerIntercomTarget: process.env.PI_SUBAGENT_INTERCOM_SESSION_NAME,
+						leafIntercomTarget: childIntercomTarget?.(agent, 0),
+						intercomTarget: childIntercomTarget?.(agent, 0),
+						ownerState: "live",
+						mode: "single",
+						state: "running",
+						agent,
+						agents: [agent],
+						chainStepCount: 1,
+						startedAt: now,
+						lastUpdate: now,
+					},
+				});
+			} catch (error) {
+				console.error("Failed to emit nested async start event:", error);
+			}
+		}
 		ctx.pi.events.emit(SUBAGENT_ASYNC_STARTED_EVENT, {
 			id,
 			pid: spawnResult.pid,
@@ -602,6 +701,7 @@ export function executeAsyncSingle(
 			task: task?.slice(0, 50),
 			cwd: runnerCwd,
 			asyncDir,
+			nestedRoute,
 		});
 	}
 

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

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { renderWidget } from "../../tui/render.ts";
+import { renderWidget, widgetRenderKey } from "../../tui/render.ts";
 import { formatControlNoticeMessage } from "../shared/subagent-control.ts";
 import {
 	type AsyncJobState,
@@ -15,7 +15,8 @@ import {
 } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { normalizeParallelGroups } from "./parallel-groups.ts";
-import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { hasLiveNestedDescendants, updateAsyncJobNestedProjection } from "../shared/nested-events.ts";
 
 interface AsyncJobTrackerOptions {
 	completionRetentionMs?: number;
@@ -38,9 +39,14 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		renderWidget(ctx, jobs);
 		ctx.ui.requestRender?.();
 	};
-	const scheduleCleanup = (asyncId: string) => {
+	const cancelCleanup = (asyncId: string) => {
 		const existingTimer = state.cleanupTimers.get(asyncId);
-		if (existingTimer) clearTimeout(existingTimer);
+		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);
@@ -118,9 +124,30 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				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,
@@ -141,6 +168,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 					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;
@@ -153,7 +181,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						job.currentStep = status.currentStep ?? job.currentStep;
 						job.chainStepCount = status.chainStepCount ?? job.chainStepCount;
 						job.startedAt = status.startedAt ?? job.startedAt;
-						job.updatedAt = status.lastUpdate ?? Date.now();
+						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;
@@ -167,6 +195,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 							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;
@@ -176,24 +205,30 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 						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") && (previousStatus !== job.status || !state.cleanupTimers.has(job.asyncId))) {
+						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;
 					}
-					job.status = job.status === "queued" ? "running" : job.status;
-					job.updatedAt = Date.now();
+					if (job.status === "queued") {
+						job.status = "running";
+						job.updatedAt = Date.now();
+					}
 				} catch (error) {
-					console.error(`Failed to read async status for '${job.asyncDir}':`, error);
-					job.status = "failed";
-					job.updatedAt = Date.now();
-					if (!state.cleanupTimers.has(job.asyncId)) {
+					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 (state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
+			if (widgetChanged && state.lastUiContext?.hasUI) rerenderWidget(state.lastUiContext);
 		}, pollIntervalMs);
 		state.poller.unref?.();
 	};
@@ -220,6 +255,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 			agents,
 			chainStepCount: info.chainStepCount,
 			parallelGroups: validParallelGroups,
+			nestedRoute: info.nestedRoute,
 			stepsTotal: firstGroupCount ?? agents?.length,
 			hasParallelGroups: validParallelGroups.length > 0,
 			activeParallelGroup: Boolean(firstGroupCount && firstGroupCount > 0),
@@ -237,15 +273,22 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 		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);
 		}
-		scheduleCleanup(asyncId);
+		if (!nestedRefreshFailed && !hasLiveNestedDescendants(job?.nestedChildren)) scheduleCleanup(asyncId);
 	};
 
 	const resetJobs = (ctx?: ExtensionContext) => {

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

@@ -149,6 +149,29 @@ function exactResultPath(resultsDir: string, runId: string): string | null {
 	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);
@@ -175,22 +198,12 @@ export function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot:
 		};
 	}
 
-	const matchingIds = [...new Set([
-		...prefixedRunIds(asyncRoot, requestedId),
-		...prefixedRunIds(resultRoot, requestedId, ".json"),
-	])].sort();
-	if (matchingIds.length === 0) return { asyncDir: null, resultPath: null, resolvedId: requestedId };
-	if (matchingIds.length > 1) {
-		throw new Error(`Ambiguous async run id prefix '${requestedId}' matched: ${matchingIds.join(", ")}. Provide a longer id.`);
+	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.`);
 	}
-	const resolvedId = matchingIds[0]!;
-	const asyncDir = path.join(asyncRoot, resolvedId);
-	assertInsideRoot(asyncRoot, asyncDir, "Async run directory");
-	return {
-		asyncDir: fs.existsSync(asyncDir) ? asyncDir : null,
-		resultPath: exactResultPath(resultRoot, resolvedId),
-		resolvedId,
-	};
+	return matching[0]!.location;
 }
 
 function resultState(result: AsyncResultFile): AsyncStatus["state"] {

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

@@ -2,10 +2,12 @@ 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;
@@ -28,6 +30,7 @@ interface AsyncRunStepSummary {
 	thinking?: string;
 	attemptedModels?: string[];
 	error?: string;
+	children?: NestedRunSummary[];
 }
 
 export interface AsyncRunSummary {
@@ -55,6 +58,8 @@ export interface AsyncRunSummary {
 	outputFile?: string;
 	totalTokens?: TokenUsage;
 	sessionFile?: string;
+	nestedChildren?: NestedRunSummary[];
+	nestedWarnings?: string[];
 }
 
 interface AsyncRunListOptions {
@@ -112,7 +117,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 +125,42 @@ 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,
+			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 +181,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 +230,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);
@@ -285,7 +310,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)}`);