@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

package/dist/builtin/subagents/src/runs/shared/model-fallback.ts

@@ -426,7 +426,6 @@ function structuredSignal(
 		if (isRefusalSignal(diagnosticSignal)) return diagnosticSignal;
 		firstNestedFallbackSignal ??= diagnosticSignal;
 	}
-
 	const cause = causeOf(value);
 	const causeSignal = structuredSignal(cause, nestedSeen, source)
 		?? fallbackSignalFromMessage(cause, source);
@@ -434,38 +433,29 @@ function structuredSignal(
 		if (isRefusalSignal(causeSignal)) return causeSignal;
 		firstNestedFallbackSignal ??= causeSignal;
 	}
-
 	const statusKind = kindFromStatus(statusFrom(value));
 	if (statusKind !== undefined) return makeSignal(statusKind, value, source);
 	if (codeKind !== undefined) return makeSignal(codeKind, value, source);
 	if (nameKind !== undefined) return makeSignal(nameKind, value, source);
-
 	if (firstNestedFallbackSignal !== undefined) return firstNestedFallbackSignal;
-
 	if (stopReason === "error") return makeSignal("provider_unavailable", value, source);
-
 	return undefined;
 }
-
 function messageFromUnknown(value: unknown, seen: Set<unknown>): string | undefined {
 	if (value === undefined || value === null || seen.has(value)) return undefined;
 	if (typeof value === "string") return value.trim().length > 0 ? value : undefined;
 	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
 	if (typeof value === "symbol" || typeof value === "function") return undefined;
 	seen.add(value);
-
 	if (value instanceof Error && value.message.trim().length > 0) return value.message;
 	const directMessage = directMessageFrom(value);
 	if (directMessage !== undefined) return directMessage;
-
 	for (const diagnosticError of diagnosticErrors(value)) {
 		const diagnosticMessage = messageFromUnknown(diagnosticError, seen);
 		if (diagnosticMessage !== undefined) return diagnosticMessage;
 	}
-
 	const causeMessage = messageFromUnknown(causeOf(value), seen);
 	if (causeMessage !== undefined) return causeMessage;
-
 	const stopReason = stopReasonFrom(value);
 	if (stopReason !== undefined) return `Assistant message ended with stopReason:${stopReason}`;
 	const finishReason = finishReasonFrom(value);
@@ -474,21 +464,17 @@ function messageFromUnknown(value: unknown, seen: Set<unknown>): string | undefi
 	if (status !== undefined) return `Model request failed with status ${status}`;
 	const code = codeFrom(value);
 	if (code !== undefined) return `Model request failed with code ${String(code)}`;
-
 	return undefined;
 }
-
 export function modelFailureMessage(error: unknown): string {
 	const structuredMessage = messageFromUnknown(error, new Set());
 	if (structuredMessage !== undefined) return structuredMessage;
 	const rendered = String(error);
 	return rendered === "[object Object]" ? "Model request failed" : rendered;
 }
-
 export function normalizeModelFailureSignal(error: unknown): ModelFallbackFailureSignal {
 	const structured = structuredSignal(error, new Set());
 	if (structured !== undefined) return structured;
-
 	const message = modelFailureMessage(error);
 	const name = errorName(error);
 	const fallbackKind = message.trim().length > 0
@@ -501,13 +487,11 @@ export function normalizeModelFailureSignal(error: unknown): ModelFallbackFailur
 		...(name !== undefined ? { name } : {}),
 	};
 }
-
 export function isRetryableModelFailure(error: unknown): boolean {
 	if (error === undefined) return false;
 	const signal = normalizeModelFailureSignal(error);
 	return FALLBACKABLE_FAILURE_KINDS.has(signal.kind);
 }
-
 export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
 	const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
 	return nextModel

package/dist/builtin/subagents/src/runs/shared/nested-events-control.ts

@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV,
+	SUBAGENT_PARENT_CONTROL_INBOX_ENV,
+	SUBAGENT_PARENT_EVENT_SINK_ENV,
+	SUBAGENT_PARENT_ROOT_RUN_ID_ENV,
+} from "./pi-args.ts";
+import {
+	MAX_NESTED_EVENT_BYTES,
+	assertSafeId,
+	clampNumber,
+	containedPath,
+	isSafeNestedId,
+	stringValue,
+	validateRouteShape,
+	type NestedControlRequestRecord,
+	type NestedControlResultRecord,
+	type NestedRoute,
+} from "./nested-events-core.ts";
+import { writeRouteRecord } from "./nested-events-registry.ts";
+
+export function parseNestedControlRequest(content: string, route: NestedRoute): NestedControlRequestRecord | undefined {
+	if (Buffer.byteLength(content, "utf-8") > MAX_NESTED_EVENT_BYTES) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object") return undefined;
+	const raw = parsed as Record<string, unknown>;
+	if (raw.type !== "subagent.nested.control-request") return undefined;
+	if (raw.rootRunId !== route.rootRunId || raw.capabilityToken !== route.capabilityToken) return undefined;
+	if (!isSafeNestedId(raw.requestId) || !isSafeNestedId(raw.targetRunId)) return undefined;
+	if (raw.action !== "interrupt" && raw.action !== "resume") return undefined;
+	const ts = clampNumber(raw.ts);
+	if (ts === undefined) return undefined;
+	return {
+		type: "subagent.nested.control-request",
+		ts,
+		rootRunId: route.rootRunId,
+		capabilityToken: route.capabilityToken,
+		requestId: raw.requestId,
+		targetRunId: raw.targetRunId,
+		action: raw.action,
+		...(stringValue(raw.message, 16_000) ? { message: stringValue(raw.message, 16_000) } : {}),
+	};
+}
+
+export function parseNestedControlResult(content: string, route: NestedRoute): NestedControlResultRecord | undefined {
+	if (Buffer.byteLength(content, "utf-8") > MAX_NESTED_EVENT_BYTES) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object") return undefined;
+	const raw = parsed as Record<string, unknown>;
+	if (raw.type !== "subagent.nested.control-result") return undefined;
+	if (raw.rootRunId !== route.rootRunId || raw.capabilityToken !== route.capabilityToken) return undefined;
+	if (!isSafeNestedId(raw.requestId) || !isSafeNestedId(raw.targetRunId)) return undefined;
+	const ts = clampNumber(raw.ts);
+	if (ts === undefined || typeof raw.ok !== "boolean") return undefined;
+	return {
+		type: "subagent.nested.control-result",
+		ts,
+		rootRunId: route.rootRunId,
+		capabilityToken: route.capabilityToken,
+		requestId: raw.requestId,
+		targetRunId: raw.targetRunId,
+		ok: raw.ok,
+		message: stringValue(raw.message, 16_000) ?? (raw.ok ? "Control request completed." : "Control request failed."),
+	};
+}
+
+export function writeNestedControlRequest(route: NestedRoute, request: Omit<NestedControlRequestRecord, "type" | "rootRunId" | "capabilityToken">): string {
+	validateRouteShape(route);
+	assertSafeId("requestId", request.requestId);
+	assertSafeId("targetRunId", request.targetRunId);
+	const record: NestedControlRequestRecord = {
+		type: "subagent.nested.control-request",
+		...request,
+		rootRunId: route.rootRunId,
+		capabilityToken: route.capabilityToken,
+	};
+	const sanitized = parseNestedControlRequest(JSON.stringify(record), route);
+	if (!sanitized) throw new Error("Nested control request failed validation.");
+	return writeRouteRecord(route.controlInbox, sanitized.ts, sanitized);
+}
+
+export function readNestedControlRequests(route: NestedRoute): Array<NestedControlRequestRecord & { filePath: string }> {
+	validateRouteShape(route);
+	let entries: string[] = [];
+	try {
+		entries = fs.readdirSync(route.controlInbox).filter((entry) => entry.endsWith(".json")).sort();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	const requests: Array<NestedControlRequestRecord & { filePath: string }> = [];
+	for (const entry of entries) {
+		const filePath = path.join(route.controlInbox, entry);
+		if (!containedPath(route.controlInbox, filePath)) continue;
+		try {
+			const stat = fs.statSync(filePath);
+			if (!stat.isFile() || stat.size > MAX_NESTED_EVENT_BYTES) continue;
+			const request = parseNestedControlRequest(fs.readFileSync(filePath, "utf-8"), route);
+			if (request) requests.push({ ...request, filePath });
+		} catch {
+			continue;
+		}
+	}
+	return requests;
+}
+
+export function writeNestedControlResult(route: NestedRoute, result: Omit<NestedControlResultRecord, "type" | "rootRunId" | "capabilityToken">): void {
+	validateRouteShape(route);
+	assertSafeId("requestId", result.requestId);
+	assertSafeId("targetRunId", result.targetRunId);
+	const record: NestedControlResultRecord = {
+		type: "subagent.nested.control-result",
+		...result,
+		rootRunId: route.rootRunId,
+		capabilityToken: route.capabilityToken,
+	};
+	const sanitized = parseNestedControlResult(JSON.stringify(record), route);
+	if (!sanitized) throw new Error("Nested control result failed validation.");
+	writeRouteRecord(route.eventSink, sanitized.ts, sanitized);
+}
+
+export function readNestedControlResults(route: NestedRoute): NestedControlResultRecord[] {
+	validateRouteShape(route);
+	let entries: string[] = [];
+	try {
+		entries = fs.readdirSync(route.eventSink).filter((entry) => entry.endsWith(".json") || entry.endsWith(".jsonl")).sort();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	const results: NestedControlResultRecord[] = [];
+	for (const entry of entries) {
+		const eventPath = path.join(route.eventSink, entry);
+		if (!containedPath(route.eventSink, eventPath)) continue;
+		try {
+			const stat = fs.statSync(eventPath);
+			if (!stat.isFile() || stat.size > MAX_NESTED_EVENT_BYTES) continue;
+			const content = fs.readFileSync(eventPath, "utf-8");
+			const lines = content.includes("\n") ? content.split("\n").filter((line) => line.trim()) : [content];
+			for (const line of lines) {
+				const result = parseNestedControlResult(line, route);
+				if (result) results.push(result);
+			}
+		} catch {
+			continue;
+		}
+	}
+	return results;
+}
+
+export function nestedRouteEnv(route: NestedRoute): Record<string, string> {
+	return {
+		[SUBAGENT_PARENT_EVENT_SINK_ENV]: route.eventSink,
+		[SUBAGENT_PARENT_CONTROL_INBOX_ENV]: route.controlInbox,
+		[SUBAGENT_PARENT_ROOT_RUN_ID_ENV]: route.rootRunId,
+		[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV]: route.capabilityToken,
+	};
+}

package/dist/builtin/subagents/src/runs/shared/nested-events-core.ts

@@ -0,0 +1,219 @@
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { TEMP_ROOT_DIR, type NestedRouteInfo, type NestedRunSummary } from "../../shared/types.ts";
+import { isSafeNestedPathId, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
+import {
+	SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV,
+	SUBAGENT_PARENT_CHILD_INDEX_ENV,
+	SUBAGENT_PARENT_CONTROL_INBOX_ENV,
+	SUBAGENT_PARENT_DEPTH_ENV,
+	SUBAGENT_PARENT_EVENT_SINK_ENV,
+	SUBAGENT_PARENT_PATH_ENV,
+	SUBAGENT_PARENT_ROOT_RUN_ID_ENV,
+	SUBAGENT_PARENT_RUN_ID_ENV,
+	SUBAGENT_PARENT_MAX_DEPTH,
+} from "./pi-args.ts";
+import { getEnvValue } from "@bastani/atomic";
+
+export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
+export const NESTED_RUNS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-runs");
+export const ROUTE_FILE = "route.json";
+export const REGISTRY_FILE = "registry.json";
+export const MAX_NESTED_EVENT_BYTES = 64 * 1024;
+export const MAX_NESTED_STEPS = 12;
+export const MAX_NESTED_CHILDREN = 16;
+export const MAX_NESTED_DEPTH = SUBAGENT_PARENT_MAX_DEPTH;
+export const MAX_PROCESSED_NESTED_EVENTS = 20_000;
+type NestedStatusEventType = "subagent.nested.started" | "subagent.nested.updated" | "subagent.nested.completed";
+type NestedControlResultEventType = "subagent.nested.control-result";
+
+export type NestedRoute = NestedRouteInfo;
+
+export interface NestedEventRecord {
+	type: NestedStatusEventType;
+	ts: number;
+	rootRunId: string;
+	parentRunId: string;
+	parentStepIndex?: number;
+	capabilityToken: string;
+	child: NestedRunSummary;
+}
+
+export interface NestedControlResultRecord {
+	type: NestedControlResultEventType;
+	ts: number;
+	rootRunId: string;
+	capabilityToken: string;
+	requestId: string;
+	targetRunId: string;
+	ok: boolean;
+	message: string;
+}
+
+export interface NestedControlRequestRecord {
+	type: "subagent.nested.control-request";
+	ts: number;
+	rootRunId: string;
+	capabilityToken: string;
+	requestId: string;
+	targetRunId: string;
+	action: "interrupt" | "resume";
+	message?: string;
+}
+
+export interface NestedRegistry {
+	rootRunId: string;
+	updatedAt: number;
+	children: NestedRunSummary[];
+	processedEvents: string[];
+}
+
+export function isSafeNestedId(value: unknown): value is string {
+	return isSafeNestedPathId(value);
+}
+
+export function assertSafeNestedId(label: string, value: string): void {
+	if (!isSafeNestedId(value)) throw new Error(`${label} must be a non-empty safe id token.`);
+}
+
+export function assertSafeId(label: string, value: string): void {
+	assertSafeNestedId(label, value);
+}
+
+export function containedPath(base: string, candidate: string): boolean {
+	const resolvedBase = path.resolve(base);
+	const resolvedCandidate = path.resolve(candidate);
+	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
+}
+
+export function commonRouteRoot(route: Pick<NestedRoute, "eventSink" | "controlInbox">): string {
+	return path.dirname(path.resolve(route.eventSink));
+}
+
+export function validateNestedRouteShape(route: NestedRoute): void {
+	assertSafeId("rootRunId", route.rootRunId);
+	assertSafeId("capabilityToken", route.capabilityToken);
+	if (!containedPath(NESTED_EVENTS_DIR, route.eventSink)) throw new Error("Nested event sink is outside the subagent nested event root.");
+	if (!containedPath(NESTED_EVENTS_DIR, route.controlInbox)) throw new Error("Nested control inbox is outside the subagent nested event root.");
+	if (commonRouteRoot(route) !== path.dirname(path.resolve(route.controlInbox))) throw new Error("Nested event sink and control inbox must share one route root.");
+}
+
+export function validateRouteShape(route: NestedRoute): void {
+	validateNestedRouteShape(route);
+}
+
+export function createNestedRoute(rootRunId: string): NestedRoute {
+	assertSafeId("rootRunId", rootRunId);
+	const capabilityToken = randomUUID();
+	const routeRoot = path.join(NESTED_EVENTS_DIR, `${rootRunId}-${capabilityToken}`);
+	const eventSink = path.join(routeRoot, "events");
+	const controlInbox = path.join(routeRoot, "controls");
+	fs.mkdirSync(eventSink, { recursive: true, mode: 0o700 });
+	fs.mkdirSync(controlInbox, { recursive: true, mode: 0o700 });
+	fs.writeFileSync(path.join(routeRoot, ROUTE_FILE), `${JSON.stringify({ rootRunId, capabilityToken, createdAt: Date.now() })}\n`, { mode: 0o600 });
+	return { rootRunId, eventSink, controlInbox, capabilityToken };
+}
+
+function newestMtimeMs(filePath: string): number {
+	let newest = fs.statSync(filePath).mtimeMs;
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(filePath);
+	} catch {
+		return newest;
+	}
+	for (const entry of entries) {
+		const childPath = path.join(filePath, entry);
+		try {
+			const stat = fs.statSync(childPath);
+			newest = Math.max(newest, stat.isDirectory() ? newestMtimeMs(childPath) : stat.mtimeMs);
+		} catch {
+			// Nested runtime cleanup is best-effort housekeeping.
+		}
+	}
+	return newest;
+}
+
+function cleanupOldSubdirectories(root: string, maxAgeDays: number): void {
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(root);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+		throw error;
+	}
+	const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+	for (const entry of entries) {
+		const entryPath = path.join(root, entry);
+		try {
+			if (newestMtimeMs(entryPath) < cutoff) fs.rmSync(entryPath, { recursive: true, force: true });
+		} catch {
+			// Keep startup resilient if a child process removes or rewrites an entry while scanning.
+		}
+	}
+}
+
+export function cleanupOldNestedRuntimeDirs(maxAgeDays: number): void {
+	cleanupOldSubdirectories(NESTED_EVENTS_DIR, maxAgeDays);
+	cleanupOldSubdirectories(NESTED_RUNS_DIR, maxAgeDays);
+}
+
+export function readSubagentEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
+	if (env === process.env) return getEnvValue(name);
+	// Atomic keeps reading legacy pi-prefixed env vars so older parent processes can route nested children.
+	const legacyName = name.replace(/^[A-Z0-9]+_/, "PI_");
+	return env[name] ?? (legacyName === name ? undefined : env[legacyName]);
+}
+
+export function resolveNestedRouteFromEnv(env: NodeJS.ProcessEnv = process.env): NestedRoute | undefined {
+	const rootRunId = readSubagentEnv(env, SUBAGENT_PARENT_ROOT_RUN_ID_ENV);
+	const eventSink = readSubagentEnv(env, SUBAGENT_PARENT_EVENT_SINK_ENV);
+	const controlInbox = readSubagentEnv(env, SUBAGENT_PARENT_CONTROL_INBOX_ENV);
+	const capabilityToken = readSubagentEnv(env, SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV);
+	if (!rootRunId || !eventSink || !controlInbox || !capabilityToken) return undefined;
+	const route = { rootRunId, eventSink, controlInbox, capabilityToken };
+	validateRouteShape(route);
+	const routeFile = path.join(commonRouteRoot(route), ROUTE_FILE);
+	const metadata = JSON.parse(fs.readFileSync(routeFile, "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
+	if (metadata.rootRunId !== rootRunId || metadata.capabilityToken !== capabilityToken) {
+		throw new Error("Nested event route metadata does not match the provided root id and capability token.");
+	}
+	return route;
+}
+
+export function resolveInheritedNestedRouteFromEnv(env: NodeJS.ProcessEnv = process.env): NestedRoute | undefined {
+	try {
+		return resolveNestedRouteFromEnv(env);
+	} catch (error) {
+		console.error("Ignoring invalid nested subagent event route:", error);
+		return undefined;
+	}
+}
+
+export function resolveNestedParentAddressFromEnv(env: NodeJS.ProcessEnv = process.env): { parentRunId: string; parentStepIndex?: number; depth: number; path: NestedPathEntry[] } | undefined {
+	const parentRunId = readSubagentEnv(env, SUBAGENT_PARENT_RUN_ID_ENV);
+	if (!isSafeNestedId(parentRunId)) return undefined;
+	const rawIndex = readSubagentEnv(env, SUBAGENT_PARENT_CHILD_INDEX_ENV);
+	const parentStepIndex = rawIndex && /^\d+$/.test(rawIndex) ? Number(rawIndex) : undefined;
+	const depth = Math.min(Math.max(1, clampNumber(Number(readSubagentEnv(env, SUBAGENT_PARENT_DEPTH_ENV))) ?? 1), MAX_NESTED_DEPTH);
+	const parsedPath = parseNestedPathEnv(readSubagentEnv(env, SUBAGENT_PARENT_PATH_ENV));
+	const nestedPath = parsedPath.length ? parsedPath : [{ runId: parentRunId, ...(parentStepIndex !== undefined ? { stepIndex: parentStepIndex } : {}) }];
+	return { parentRunId, ...(parentStepIndex !== undefined ? { parentStepIndex } : {}), depth, path: nestedPath };
+}
+
+export function resolveNestedAsyncDir(rootRunId: string, run: NestedRunSummary): string | undefined {
+	if (!run.asyncDir) return undefined;
+	const resolved = path.resolve(run.asyncDir);
+	const nestedRoot = path.resolve(NESTED_RUNS_DIR, rootRunId, run.id);
+	const relative = path.relative(nestedRoot, resolved);
+	return resolved === nestedRoot || (!relative.startsWith("..") && !path.isAbsolute(relative)) ? resolved : undefined;
+}
+
+export function clampNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function stringValue(value: unknown, max = 512): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value.slice(0, max) : undefined;
+}

package/dist/builtin/subagents/src/runs/shared/nested-events-projection.ts

@@ -0,0 +1,121 @@
+import * as path from "node:path";
+import { APP_NAME } from "@bastani/atomic";
+import {
+	ASYNC_DIR,
+	RESULTS_DIR,
+	type AsyncJobState,
+	type AsyncStatus,
+	type NestedRunSummary,
+	type SubagentRunMode,
+	type SubagentState,
+} from "../../shared/types.ts";
+import {
+	MAX_NESTED_CHILDREN,
+	MAX_NESTED_STEPS,
+	NESTED_RUNS_DIR,
+	assertSafeId,
+	containedPath,
+} from "./nested-events-core.ts";
+import { projectNestedEvents } from "./nested-events-registry.ts";
+import { terminal } from "./nested-events-sanitize.ts";
+
+export function attachRootChildrenToSteps<T extends { children?: NestedRunSummary[]; index?: number }>(rootRunId: string, steps: T[] | undefined, children: NestedRunSummary[] | undefined): void {
+	if (!steps?.length) return;
+	for (const step of steps) {
+		step.children = undefined;
+	}
+	if (!children?.length) return;
+	for (const child of children) {
+		if (child.parentRunId !== rootRunId || child.parentStepIndex === undefined) continue;
+		const step = steps.find((candidate, index) => (candidate.index ?? index) === child.parentStepIndex);
+		if (!step) continue;
+		step.children ??= [];
+		step.children = [...step.children.filter((existing) => existing.id !== child.id), child].slice(0, MAX_NESTED_CHILDREN);
+	}
+}
+
+export function updateAsyncJobNestedProjection(job: AsyncJobState): void {
+	if (!job.nestedRoute) return;
+	const registry = projectNestedEvents(job.nestedRoute);
+	job.nestedChildren = registry.children;
+	attachRootChildrenToSteps(job.asyncId, job.steps, registry.children);
+}
+
+export function updateForegroundNestedProjection(control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never): void {
+	if (!control.nestedRoute) return;
+	const registry = projectNestedEvents(control.nestedRoute);
+	control.nestedChildren = registry.children;
+}
+
+export function hasLiveNestedDescendants(children: NestedRunSummary[] | undefined): boolean {
+	if (!children?.length) return false;
+	for (const child of children) {
+		if (!terminal(child.state)) return true;
+		if (hasLiveNestedDescendants(child.children)) return true;
+		if (hasLiveNestedDescendants(child.steps?.flatMap((step) => step.children ?? []))) return true;
+	}
+	return false;
+}
+
+export function nestedSummaryFromAsyncStatus(status: AsyncStatus, asyncDir: string, fallback: { id: string; parentRunId: string; parentStepIndex?: number; depth: number; path?: Array<{ runId: string; stepIndex?: number; agent?: string }>; mode?: SubagentRunMode; ts: number }): NestedRunSummary {
+	return {
+		id: status.runId || fallback.id,
+		parentRunId: fallback.parentRunId,
+		...(fallback.parentStepIndex !== undefined ? { parentStepIndex: fallback.parentStepIndex } : {}),
+		depth: fallback.depth,
+		path: fallback.path ?? [{ runId: fallback.parentRunId, ...(fallback.parentStepIndex !== undefined ? { stepIndex: fallback.parentStepIndex } : {}) }],
+		asyncDir,
+		...(status.pid ? { pid: status.pid } : {}),
+		...(status.sessionId ? { sessionId: status.sessionId } : {}),
+		mode: status.mode ?? fallback.mode,
+		state: status.state,
+		...(status.currentStep !== undefined ? { currentStep: status.currentStep } : {}),
+		...(status.chainStepCount !== undefined ? { chainStepCount: status.chainStepCount } : {}),
+		...(status.activityState ? { activityState: status.activityState } : {}),
+		...(status.lastActivityAt !== undefined ? { lastActivityAt: status.lastActivityAt } : {}),
+		...(status.currentTool ? { currentTool: status.currentTool } : {}),
+		...(status.currentToolStartedAt !== undefined ? { currentToolStartedAt: status.currentToolStartedAt } : {}),
+		...(status.currentPath ? { currentPath: status.currentPath } : {}),
+		...(status.turnCount !== undefined ? { turnCount: status.turnCount } : {}),
+		...(status.toolCount !== undefined ? { toolCount: status.toolCount } : {}),
+		...(status.totalTokens ? { totalTokens: status.totalTokens } : {}),
+		...(status.startedAt !== undefined ? { startedAt: status.startedAt } : { startedAt: fallback.ts }),
+		...(status.endedAt !== undefined ? { endedAt: status.endedAt } : {}),
+		lastUpdate: status.lastUpdate ?? fallback.ts,
+		...(status.sessionFile ? { sessionFile: status.sessionFile } : {}),
+		...(status.steps?.length ? { steps: status.steps.map((step) => ({
+			agent: step.agent,
+			status: step.status,
+			...(step.sessionFile ? { sessionFile: step.sessionFile } : {}),
+			...(step.activityState ? { activityState: step.activityState } : {}),
+			...(step.lastActivityAt !== undefined ? { lastActivityAt: step.lastActivityAt } : {}),
+			...(step.currentTool ? { currentTool: step.currentTool } : {}),
+			...(step.currentToolStartedAt !== undefined ? { currentToolStartedAt: step.currentToolStartedAt } : {}),
+			...(step.currentPath ? { currentPath: step.currentPath } : {}),
+			...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
+			...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
+			...(step.startedAt !== undefined ? { startedAt: step.startedAt } : {}),
+			...(step.endedAt !== undefined ? { endedAt: step.endedAt } : {}),
+			...(step.error ? { error: step.error } : {}),
+		})).slice(0, MAX_NESTED_STEPS) } : {}),
+	};
+}
+
+export function nestedArtifactEnv(rootRunId: string, parentRunId: string): Record<string, string> {
+	const envPrefix = APP_NAME.toUpperCase();
+	return {
+		[`${envPrefix}_SUBAGENT_NESTED_ROOT_RUN_ID`]: rootRunId,
+		[`${envPrefix}_SUBAGENT_NESTED_PARENT_RUN_ID`]: parentRunId,
+	};
+}
+
+export function isTopLevelAsyncDir(asyncDir: string): boolean {
+	const resolved = path.resolve(asyncDir);
+	return containedPath(ASYNC_DIR, resolved) && !containedPath(NESTED_RUNS_DIR, resolved);
+}
+
+export function nestedResultsPath(rootRunId: string, id: string): string {
+	assertSafeId("rootRunId", rootRunId);
+	assertSafeId("id", id);
+	return path.join(RESULTS_DIR, "nested", rootRunId, `${id}.json`);
+}