pi-subagents 0.58.0 → 0.59.0

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

@@ -1,18 +1,19 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { DIRS, type AcceptanceInput, type AsyncStatus, type ResolvedTurnBudget, type SteeringRecoveryDescriptor, type SubagentRunMode } from "../../shared/types.ts";
+import { DIRS, type AcceptanceInput, type AsyncStatus, type SteeringRecoveryDescriptor, type SubagentRunMode } from "../../shared/types.ts";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { normalizeExtensionBindings } from "../shared/extension-bindings.ts";
+import { normalizeWorkflowLaneMetadata } from "../shared/lane-metadata.ts";
 import { validateAcceptanceInput } from "../shared/acceptance.ts";
 import { validateToolBudgetConfig } from "../shared/tool-budget.ts";
 import { intersectSubagentCapabilityCeilings, parseSubagentCapabilityCeiling, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
 import { validateRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
-import { resolveTurnBudgetConfig } from "../shared/turn-budget.ts";
 import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
 import { resultFilePath, resultPayloadPathForIndexedRun } from "./result-files.ts";
 import { canScanAsyncRunPrefix, MIN_SAFE_ASYNC_RUN_PREFIX_LENGTH } from "./run-id-query.ts";
 import { parallelHandoffPath, resolveRetainedWorktreeCwd } from "../shared/parallel-handoff.ts";
 import { intersectThinkingCeilings, parseThinkingLevel, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
+import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.ts";
 
 export interface AsyncResumeParams {
 	id?: string;
@@ -40,6 +41,8 @@ export type AsyncResumeTarget = {
 	state: AsyncStatus["state"];
 	mode?: SubagentRunMode;
 	agent: string;
+	/** Human-readable display name for the child session, when derived at launch. */
+	sessionName?: string;
 	index: number;
 	cwd?: string;
 	sessionFile?: string;
@@ -63,11 +66,12 @@ interface AsyncResultFile {
 	cwd?: string;
 	sessionId?: string;
 	sessionFile?: string;
+	sessionName?: string;
 	model?: string;
 	thinking?: string;
 	launchContractDigest?: string;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
-	results?: Array<{ agent?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string; launchContractDigest?: string; capabilityCeiling?: ResolvedSubagentCapabilityCeiling }>;
+	results?: Array<{ agent?: string; sessionName?: string; success?: boolean; sessionFile?: string; intercomTarget?: string; model?: string; thinking?: string; launchContractDigest?: string; capabilityCeiling?: ResolvedSubagentCapabilityCeiling }>;
 }
 
 export interface AsyncRunLocation {
@@ -104,6 +108,7 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
 			const child = ensureObject(entry, `${resultPath} results[${index}]`);
 			const agent = validateOptionalString(child, "agent", resultPath, `results[${index}].agent`);
 			const sessionFile = validateOptionalString(child, "sessionFile", resultPath, `results[${index}].sessionFile`);
+			const sessionName = validateOptionalString(child, "sessionName", resultPath, `results[${index}].sessionName`);
 			const intercomTarget = validateOptionalString(child, "intercomTarget", resultPath, `results[${index}].intercomTarget`);
 			const model = validateOptionalString(child, "model", resultPath, `results[${index}].model`);
 			const thinking = validateOptionalString(child, "thinking", resultPath, `results[${index}].thinking`);
@@ -111,7 +116,7 @@ function validateResultFile(value: unknown, resultPath: string): AsyncResultFile
 			const capabilityCeiling = child.capabilityCeiling === undefined ? undefined : parseSubagentCapabilityCeiling(child.capabilityCeiling, `async result file '${resultPath}' results[${index}].capabilityCeiling`);
 			const success = child.success;
 			if (success !== undefined && typeof success !== "boolean") throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);
-			return { agent, sessionFile, intercomTarget, model, thinking, launchContractDigest, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(typeof success === "boolean" ? { success } : {}) };
+			return { agent, sessionName, sessionFile, intercomTarget, model, thinking, launchContractDigest, ...(capabilityCeiling ? { capabilityCeiling } : {}), ...(typeof success === "boolean" ? { success } : {}) };
 		});
 	}
 	const success = data.success;
@@ -248,7 +253,7 @@ export function resolveAsyncRunLocation(params: AsyncResumeParams, asyncDirRoot:
 }
 
 function resultState(result: AsyncResultFile): AsyncStatus["state"] {
-	if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "stopped" || result.state === "running" || result.state === "queued") {
+	if (result.state === "complete" || result.state === "failed" || result.state === "partial" || result.state === "paused" || result.state === "stopped" || result.state === "running" || result.state === "queued") {
 		return result.state;
 	}
 	return result.success ? "complete" : "failed";
@@ -257,6 +262,7 @@ function resultState(result: AsyncResultFile): AsyncStatus["state"] {
 function validateStatusForResume(status: AsyncStatus | null, source: string): void {
 	if (!status) return;
 	if (typeof status.runId !== "string") throw new Error(`Invalid async status '${source}': runId must be a string.`);
+	assertWorkflowGraphHostSteps(status.workflowGraph, source, status.runId);
 	if (status.sessionId !== undefined && typeof status.sessionId !== "string") throw new Error(`Invalid async status '${source}': sessionId must be a string.`);
 	if (status.cwd !== undefined && typeof status.cwd !== "string") throw new Error(`Invalid async status '${source}': cwd must be a string.`);
 	if (status.sessionFile !== undefined && typeof status.sessionFile !== "string") throw new Error(`Invalid async status '${source}': sessionFile must be a string.`);
@@ -268,6 +274,7 @@ function validateStatusForResume(status: AsyncStatus | null, source: string): vo
 			const stepRecord = step as Record<string, unknown>;
 			if (typeof stepRecord.agent !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
 			if (stepRecord.sessionFile !== undefined && typeof stepRecord.sessionFile !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);
+			if (stepRecord.sessionName !== undefined && typeof stepRecord.sessionName !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].sessionName must be a string.`);
 			if (stepRecord.model !== undefined && typeof stepRecord.model !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].model must be a string.`);
 			if (stepRecord.thinking !== undefined && typeof stepRecord.thinking !== "string") throw new Error(`Invalid async status '${source}': steps[${index}].thinking must be a string.`);
 			if (stepRecord.thinkingCeiling !== undefined) stepRecord.thinkingCeiling = parseThinkingLevel(stepRecord.thinkingCeiling, `async status '${source}' steps[${index}].thinkingCeiling`);
@@ -283,23 +290,6 @@ function normalizeRecoveryAcceptance(value: unknown, descriptorPath: string): Ac
 	return value as AcceptanceInput;
 }
 
-function normalizeRecoveryTurnBudget(value: unknown, descriptorPath: string): ResolvedTurnBudget {
-	if (value && typeof value === "object" && !Array.isArray(value)) {
-		const {
-			outcome: _outcome,
-			turnCount: _turnCount,
-			wrapUpRequestedAtTurn: _wrapUpRequestedAtTurn,
-			terminationDeferredAtTurn: _terminationDeferredAtTurn,
-			exceededAtTurn: _exceededAtTurn,
-			...publicTurnBudget
-		} = value as Record<string, unknown>;
-		value = publicTurnBudget;
-	}
-	const result = resolveTurnBudgetConfig(value, "recoveryDescriptor.initialTurnBudget");
-	if (result.error || !result.turnBudget) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error ?? "recoveryDescriptor.initialTurnBudget is invalid."}`);
-	return result.turnBudget;
-}
-
 export function asyncReviveRequiresRecoveryDescriptor(target: Pick<AsyncResumeTarget, "recoveryDescriptor" | "mode" | "sessionFile">): boolean {
 	if (target.recoveryDescriptor) return false;
 	return !(target.mode === "workflow" && Boolean(target.sessionFile));
@@ -324,11 +314,11 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
 	const parsed = value as Record<string, unknown>;
 	const allowedFields = new Set([
-		"version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "fallbackModels", "thinking", "thinkingCeiling", "tools", "extensions",
+		"version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "fallbackModels", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "extensions",
 		"subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills",
 		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
 		"artifactsDir", "maxOutput", "controlConfig", "context", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
-		"launchResolvedExtensions", "runFanoutBudget",
+		"launchResolvedExtensions", "runFanoutBudget", "lane",
 		"extensionBindings",
 	]);
 	for (const field of Object.keys(parsed)) {
@@ -347,6 +337,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	if (parsed.capabilityCeiling !== undefined) parsed.capabilityCeiling = parseSubagentCapabilityCeiling(parsed.capabilityCeiling, `async recovery descriptor '${descriptorPath}' capabilityCeiling`);
 	if (parsed.thinkingCeiling !== undefined) parsed.thinkingCeiling = parseThinkingLevel(parsed.thinkingCeiling, `async recovery descriptor '${descriptorPath}' thinkingCeiling`);
 	if (parsed.extensionBindings !== undefined) parsed.extensionBindings = normalizeExtensionBindings(parsed.extensionBindings)!.value;
+	if (parsed.lane !== undefined) parsed.lane = normalizeWorkflowLaneMetadata(parsed.lane, `Invalid async recovery descriptor '${descriptorPath}': lane`);
 	if (parsed.agentContract !== undefined) {
 		if (!parsed.agentContract || typeof parsed.agentContract !== "object" || Array.isArray(parsed.agentContract)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be an object.`);
 		const contract = parsed.agentContract as Record<string, unknown>;
@@ -361,6 +352,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	}
 	if (parsed.inheritGlobalContext === undefined) parsed.inheritGlobalContext = parsed.inheritProjectContext;
 	else if (typeof parsed.inheritGlobalContext !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': inheritGlobalContext must be a boolean.`);
+	if (parsed.allowNestedSubagents !== undefined && typeof parsed.allowNestedSubagents !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': allowNestedSubagents must be a boolean.`);
 	if (!Number.isInteger(parsed.maxSubagentDepth) || (parsed.maxSubagentDepth as number) < 0) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxSubagentDepth must be a non-negative integer.`);
 	for (const field of ["fallbackModels", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "skills", "skillPath"] as const) {
 		const item = parsed[field];
@@ -379,7 +371,9 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	}
 	if (parsed.absoluteDeadlineAt !== undefined && (!Number.isFinite(parsed.absoluteDeadlineAt) || (parsed.absoluteDeadlineAt as number) <= 0)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': absoluteDeadlineAt must be a positive timestamp.`);
 	if (parsed.initialTurnBudget !== undefined) {
-		parsed.initialTurnBudget = normalizeRecoveryTurnBudget(parsed.initialTurnBudget, descriptorPath);
+		// Older descriptors may contain the removed turn-budget setting. Accept it
+		// for recovery compatibility, but do not restore or enforce it.
+		delete parsed.initialTurnBudget;
 	}
 	if (parsed.initialToolBudget !== undefined) {
 		const result = validateToolBudgetConfig(parsed.initialToolBudget, "recoveryDescriptor.initialToolBudget");
@@ -492,6 +486,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 					state,
 					...(mode ? { mode } : {}),
 					agent: selectedStep.agent,
+					...(selectedStep.sessionName ?? result?.results?.[requestedIndex]?.sessionName ? { sessionName: selectedStep.sessionName ?? result?.results?.[requestedIndex]?.sessionName } : {}),
 					index: requestedIndex,
 					cwd: status?.cwd ?? result?.cwd,
 					sessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
@@ -523,6 +518,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 				state,
 				...(mode ? { mode } : {}),
 				agent: selected.step.agent,
+				...(selected.step.sessionName ?? result?.results?.[selected.index]?.sessionName ? { sessionName: selected.step.sessionName ?? result?.results?.[selected.index]?.sessionName } : {}),
 				index: selected.index,
 				cwd: status?.cwd ?? result?.cwd,
 				sessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
@@ -568,6 +564,7 @@ export function resolveAsyncResumeTarget(params: AsyncResumeParams, deps: AsyncR
 		state,
 		...(mode ? { mode } : {}),
 		agent,
+		...(statusSteps[index]?.sessionName ?? resultSteps[index]?.sessionName ? { sessionName: statusSteps[index]?.sessionName ?? resultSteps[index]?.sessionName } : {}),
 		index,
 		...(resumeCwd ? { cwd: resumeCwd } : {}),
 		...(resolvedSessionFile ? { sessionFile: resolvedSessionFile } : {}),
@@ -591,6 +588,7 @@ export function applySteeringRecoveryAgentConfig(agentConfig: AgentConfig, descr
 		thinking: descriptor.thinking,
 		maxThinking: intersectThinkingCeilings(descriptor.thinkingCeiling, agentConfig.maxThinking),
 		tools: descriptor.tools ? [...descriptor.tools] : undefined,
+		allowNestedSubagents: descriptor.allowNestedSubagents,
 		extensions: descriptor.extensions ? [...descriptor.extensions] : undefined,
 		subagentOnlyExtensions: descriptor.subagentOnlyExtensions ? [...descriptor.subagentOnlyExtensions] : undefined,
 		mcpDirectTools: descriptor.mcpDirectTools ? [...descriptor.mcpDirectTools] : undefined,

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

@@ -1,268 +1,30 @@
-import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-text.ts";
-import type { AsyncJobState, AsyncJobStep, NestedRunSummary, NestedStepSummary, SubagentRunMode, SubagentState } from "../../shared/types.ts";
+import type { AsyncJobState, SubagentState } from "../../shared/types.ts";
+import {
+	projectAsyncStatusSnapshot,
+	type AsyncStatusSnapshotOptions,
+	type AsyncStatusSnapshotV1,
+} from "../shared/async-status-projection.ts";
+
+export {
+	ASYNC_STATUS_SNAPSHOT_KIND,
+	ASYNC_STATUS_SNAPSHOT_VERSION,
+} from "../shared/async-status-projection.ts";
+export type {
+	AsyncStatusSnapshotActivityV1,
+	AsyncStatusSnapshotCapsV1,
+	AsyncStatusSnapshotHostStepV1,
+	AsyncStatusSnapshotKind,
+	AsyncStatusSnapshotNodeV1,
+	AsyncStatusSnapshotOmittedV1,
+	AsyncStatusSnapshotOptions,
+	AsyncStatusSnapshotState,
+	AsyncStatusSnapshotV1,
+} from "../shared/async-status-projection.ts";
 
-export const ASYNC_STATUS_SNAPSHOT_KIND = "pi-subagents.async-status-snapshot";
-export const ASYNC_STATUS_SNAPSHOT_VERSION = 1;
 export const ASYNC_STATUS_SNAPSHOT_WIDGET_PREFIX = "PI_SUBAGENT_ASYNC_JSON:";
 
-const DEFAULT_MAX_RUNS = 20;
-const DEFAULT_MAX_CHILDREN_PER_NODE = 8;
-const DEFAULT_MAX_DEPTH = 3;
-const DEFAULT_MAX_STRING_LENGTH = 160;
-const DEFAULT_MAX_SERIALIZED_BYTES = 32 * 1024;
-
-export type AsyncStatusSnapshotState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
-export type AsyncStatusSnapshotKind = "subagent" | "workflow" | "step";
-
-export interface AsyncStatusSnapshotActivityV1 {
-	state?: string;
-	currentTool?: string;
-	lastActivityAt?: number;
-	currentToolStartedAt?: number;
-	turnCount?: number;
-	toolCount?: number;
-}
-
-export interface AsyncStatusSnapshotNodeV1 {
-	id: string;
-	kind: AsyncStatusSnapshotKind;
-	label: string;
-	state: AsyncStatusSnapshotState;
-	startedAt?: number;
-	updatedAt?: number;
-	endedAt?: number;
-	activity?: AsyncStatusSnapshotActivityV1;
-	children?: AsyncStatusSnapshotNodeV1[];
-}
-
-export interface AsyncStatusSnapshotCapsV1 {
-	maxRuns: number;
-	maxChildrenPerNode: number;
-	maxDepth: number;
-	maxStringLength: number;
-	maxSerializedBytes: number;
-}
-
-export interface AsyncStatusSnapshotOmittedV1 {
-	runs: number;
-	children: number;
-	byteLimitExceeded: boolean;
-}
-
-export interface AsyncStatusSnapshotV1 {
-	kind: typeof ASYNC_STATUS_SNAPSHOT_KIND;
-	version: typeof ASYNC_STATUS_SNAPSHOT_VERSION;
-	generatedAt: number;
-	caps: AsyncStatusSnapshotCapsV1;
-	omitted: AsyncStatusSnapshotOmittedV1;
-	runs: AsyncStatusSnapshotNodeV1[];
-}
-
-export interface AsyncStatusSnapshotOptions {
-	generatedAt?: number;
-	maxRuns?: number;
-	maxChildrenPerNode?: number;
-	maxDepth?: number;
-	maxStringLength?: number;
-	maxSerializedBytes?: number;
-}
-
-interface BuildContext {
-	caps: AsyncStatusSnapshotCapsV1;
-	omitted: AsyncStatusSnapshotOmittedV1;
-}
-
-function resolveCaps(options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotCapsV1 {
-	return {
-		maxRuns: Math.max(0, Math.floor(options.maxRuns ?? DEFAULT_MAX_RUNS)),
-		maxChildrenPerNode: Math.max(0, Math.floor(options.maxChildrenPerNode ?? DEFAULT_MAX_CHILDREN_PER_NODE)),
-		maxDepth: Math.max(0, Math.floor(options.maxDepth ?? DEFAULT_MAX_DEPTH)),
-		maxStringLength: Math.max(0, Math.floor(options.maxStringLength ?? DEFAULT_MAX_STRING_LENGTH)),
-		maxSerializedBytes: Math.max(256, Math.floor(options.maxSerializedBytes ?? DEFAULT_MAX_SERIALIZED_BYTES)),
-	};
-}
-
-function publicText(value: unknown, fallback: string, maxLength: number): string {
-	if (typeof value !== "string") return fallback;
-	const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
-	return truncateDisplayText(normalized || fallback, maxLength);
-}
-
-function publicOptionalText(value: unknown, maxLength: number): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const normalized = sanitizeDisplayText(value.slice(0, Math.max(0, maxLength * 4)));
-	return normalized ? truncateDisplayText(normalized, maxLength) : undefined;
-}
-
-function publicTime(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
-}
-
-function publicCount(value: unknown): number | undefined {
-	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
-}
-
-function normalizeState(value: string): AsyncStatusSnapshotState {
-	if (value === "completed") return "complete";
-	if (value === "pending") return "queued";
-	return value as AsyncStatusSnapshotState;
-}
-
-function terminalState(state: AsyncStatusSnapshotState): boolean {
-	return state === "complete" || state === "failed" || state === "paused" || state === "stopped" || state === "rejected";
-}
-
-function kindForMode(mode: SubagentRunMode | undefined): AsyncStatusSnapshotKind {
-	return mode === "workflow" ? "workflow" : "subagent";
-}
-
-function labelForAgents(agents: readonly string[] | undefined, fallback: string, maxLength: number): string {
-	if (!agents?.length) return publicText(fallback, fallback, maxLength);
-	const visible = agents.slice(0, 3).map((agent) => publicText(agent, "agent", maxLength)).join(", ");
-	const suffix = agents.length > 3 ? `, +${agents.length - 3} more` : "";
-	return truncateDisplayText(`${visible}${suffix}`, maxLength);
-}
-
-function activityFor(source: {
-	activityState?: unknown;
-	currentTool?: unknown;
-	lastActivityAt?: unknown;
-	currentToolStartedAt?: unknown;
-	turnCount?: unknown;
-	toolCount?: unknown;
-}, ctx: BuildContext): AsyncStatusSnapshotActivityV1 | undefined {
-	const activity: AsyncStatusSnapshotActivityV1 = {
-		...(typeof source.activityState === "string" ? { state: publicText(source.activityState, "unknown", ctx.caps.maxStringLength) } : {}),
-		...(publicOptionalText(source.currentTool, ctx.caps.maxStringLength) ? { currentTool: publicOptionalText(source.currentTool, ctx.caps.maxStringLength) } : {}),
-		...(publicTime(source.lastActivityAt) !== undefined ? { lastActivityAt: publicTime(source.lastActivityAt) } : {}),
-		...(publicTime(source.currentToolStartedAt) !== undefined ? { currentToolStartedAt: publicTime(source.currentToolStartedAt) } : {}),
-		...(publicCount(source.turnCount) !== undefined ? { turnCount: publicCount(source.turnCount) } : {}),
-		...(publicCount(source.toolCount) !== undefined ? { toolCount: publicCount(source.toolCount) } : {}),
-	};
-	return Object.keys(activity).length ? activity : undefined;
-}
-
-function appendBoundedChildren(children: AsyncStatusSnapshotNodeV1[], source: readonly AsyncStatusSnapshotNodeV1[], ctx: BuildContext): void {
-	const remaining = Math.max(0, ctx.caps.maxChildrenPerNode - children.length);
-	children.push(...source.slice(0, remaining));
-	ctx.omitted.children += Math.max(0, source.length - remaining);
-}
-
-function buildStepNode(step: AsyncJobStep | NestedStepSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
-	const state = normalizeState(step.status);
-	const updatedAt = publicTime(step.endedAt) ?? publicTime(step.lastActivityAt) ?? publicTime(step.startedAt);
-	const node: AsyncStatusSnapshotNodeV1 = {
-		id: publicText("workflowKey" in step && step.workflowKey ? step.workflowKey : "runId" in step && step.runId ? step.runId : `step:${index}`, `step:${index}`, ctx.caps.maxStringLength),
-		kind: "step",
-		label: publicText("label" in step && step.label ? step.label : step.agent, "step", ctx.caps.maxStringLength),
-		state,
-		...(publicTime(step.startedAt) !== undefined ? { startedAt: publicTime(step.startedAt) } : {}),
-		...(updatedAt !== undefined ? { updatedAt } : {}),
-		...(terminalState(state) && publicTime(step.endedAt) !== undefined ? { endedAt: publicTime(step.endedAt) } : {}),
-		...(activityFor(step, ctx) ? { activity: activityFor(step, ctx) } : {}),
-	};
-	if (depth < ctx.caps.maxDepth && step.children?.length) {
-		const nested = step.children.map((child, childIndex) => buildNestedNode(child, childIndex, depth + 1, ctx));
-		const bounded: AsyncStatusSnapshotNodeV1[] = [];
-		appendBoundedChildren(bounded, nested, ctx);
-		if (bounded.length) node.children = bounded;
-	} else if (step.children?.length) {
-		ctx.omitted.children += step.children.length;
-	}
-	return node;
-}
-
-function buildNestedNode(child: NestedRunSummary, index: number, depth: number, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
-	const state = normalizeState(child.state);
-	const updatedAt = publicTime(child.lastUpdate) ?? publicTime(child.endedAt) ?? publicTime(child.lastActivityAt) ?? publicTime(child.startedAt);
-	const node: AsyncStatusSnapshotNodeV1 = {
-		id: publicText(child.id, `nested:${index}`, ctx.caps.maxStringLength),
-		kind: kindForMode(child.mode),
-		label: child.agent ? publicText(child.agent, "subagent", ctx.caps.maxStringLength) : labelForAgents(child.agents, child.mode ?? "subagent", ctx.caps.maxStringLength),
-		state,
-		...(publicTime(child.startedAt) !== undefined ? { startedAt: publicTime(child.startedAt) } : {}),
-		...(updatedAt !== undefined ? { updatedAt } : {}),
-		...(terminalState(state) && publicTime(child.endedAt) !== undefined ? { endedAt: publicTime(child.endedAt) } : {}),
-		...(activityFor(child, ctx) ? { activity: activityFor(child, ctx) } : {}),
-	};
-	if (depth < ctx.caps.maxDepth) {
-		const nestedSteps = child.steps?.map((step, stepIndex) => buildStepNode(step, stepIndex, depth + 1, ctx)) ?? [];
-		const nestedChildren = child.children?.map((nested, childIndex) => buildNestedNode(nested, childIndex, depth + 1, ctx)) ?? [];
-		const bounded: AsyncStatusSnapshotNodeV1[] = [];
-		appendBoundedChildren(bounded, [...nestedSteps, ...nestedChildren], ctx);
-		if (bounded.length) node.children = bounded;
-	} else {
-		ctx.omitted.children += (child.steps?.length ?? 0) + (child.children?.length ?? 0);
-	}
-	return node;
-}
-
-function buildRunNode(job: AsyncJobState, ctx: BuildContext): AsyncStatusSnapshotNodeV1 {
-	const state = normalizeState(job.status);
-	const updatedAt = publicTime(job.updatedAt) ?? publicTime(job.startedAt);
-	const node: AsyncStatusSnapshotNodeV1 = {
-		id: publicText(job.asyncId, "async", ctx.caps.maxStringLength),
-		kind: kindForMode(job.mode),
-		label: labelForAgents(job.agents, job.mode ?? "subagent", ctx.caps.maxStringLength),
-		state,
-		...(publicTime(job.startedAt) !== undefined ? { startedAt: publicTime(job.startedAt) } : {}),
-		...(updatedAt !== undefined ? { updatedAt } : {}),
-		...(terminalState(state) && updatedAt !== undefined ? { endedAt: updatedAt } : {}),
-		...(activityFor(job, ctx) ? { activity: activityFor(job, ctx) } : {}),
-	};
-	if (ctx.caps.maxDepth > 0) {
-		const stepChildren = job.steps?.map((step, index) => buildStepNode(step, step.index ?? index, 1, ctx)) ?? [];
-		const nestedChildren = job.nestedChildren?.map((child, index) => buildNestedNode(child, index, 1, ctx)) ?? [];
-		const bounded: AsyncStatusSnapshotNodeV1[] = [];
-		appendBoundedChildren(bounded, [...stepChildren, ...nestedChildren], ctx);
-		if (bounded.length) node.children = bounded;
-	} else {
-		ctx.omitted.children += (job.steps?.length ?? 0) + (job.nestedChildren?.length ?? 0);
-	}
-	return node;
-}
-
-function snapshotBytes(snapshot: AsyncStatusSnapshotV1): number {
-	return Buffer.byteLength(JSON.stringify(snapshot), "utf8");
-}
-
-function enforceByteLimit(snapshot: AsyncStatusSnapshotV1): void {
-	if (snapshotBytes(snapshot) <= snapshot.caps.maxSerializedBytes) return;
-	snapshot.omitted.byteLimitExceeded = true;
-	const runs = snapshot.runs;
-	const initialOmittedRuns = snapshot.omitted.runs;
-	let lower = 0;
-	let upper = Math.max(0, runs.length - 1);
-	while (lower < upper) {
-		const retained = Math.ceil((lower + upper) / 2);
-		snapshot.runs = runs.slice(0, retained);
-		snapshot.omitted.runs = initialOmittedRuns + runs.length - retained;
-		if (snapshotBytes(snapshot) <= snapshot.caps.maxSerializedBytes) lower = retained;
-		else upper = retained - 1;
-	}
-	snapshot.runs = runs.slice(0, lower);
-	snapshot.omitted.runs = initialOmittedRuns + runs.length - lower;
-}
-
 export function buildAsyncStatusSnapshot(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
-	const caps = resolveCaps(options);
-	const ctx: BuildContext = { caps, omitted: { runs: 0, children: 0, byteLimitExceeded: false } };
-	const sorted = [...jobs].sort((left, right) => {
-		const leftUpdated = left.updatedAt ?? left.startedAt ?? 0;
-		const rightUpdated = right.updatedAt ?? right.startedAt ?? 0;
-		return rightUpdated - leftUpdated || left.asyncId.localeCompare(right.asyncId);
-	});
-	ctx.omitted.runs += Math.max(0, sorted.length - caps.maxRuns);
-	const snapshot: AsyncStatusSnapshotV1 = {
-		kind: ASYNC_STATUS_SNAPSHOT_KIND,
-		version: ASYNC_STATUS_SNAPSHOT_VERSION,
-		generatedAt: options.generatedAt ?? Date.now(),
-		caps,
-		omitted: ctx.omitted,
-		runs: sorted.slice(0, caps.maxRuns).map((job) => buildRunNode(job, ctx)),
-	};
-	enforceByteLimit(snapshot);
-	return snapshot;
+	return projectAsyncStatusSnapshot(jobs, options);
 }
 
 export function asyncStatusSnapshotJobsForState(state: SubagentState | undefined, sessionId: string | null | undefined): AsyncJobState[] {