pi-subagents 0.49.0 → 0.51.0

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

@@ -0,0 +1,277 @@
+import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-text.ts";
+import type { AsyncJobState, AsyncJobStep, NestedRunSummary, NestedStepSummary, SubagentRunMode, SubagentState } from "../../shared/types.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 {
+	while (snapshot.runs.length > 0 && snapshotBytes(snapshot) > snapshot.caps.maxSerializedBytes) {
+		snapshot.runs.pop();
+		snapshot.omitted.runs += 1;
+		snapshot.omitted.byteLimitExceeded = true;
+	}
+	if (snapshotBytes(snapshot) > snapshot.caps.maxSerializedBytes) snapshot.omitted.byteLimitExceeded = true;
+}
+
+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;
+}
+
+export function asyncStatusSnapshotJobsForState(state: SubagentState | undefined, sessionId: string | null | undefined): AsyncJobState[] {
+	if (!state || !sessionId || state.currentSessionId !== sessionId) return [];
+	const jobs = new Map<string, AsyncJobState>();
+	for (const job of state.asyncJobs.values()) {
+		if (job.sessionId === sessionId) jobs.set(job.asyncId, job);
+	}
+	for (const job of state.fleetJobs?.values() ?? []) {
+		if (job.sessionId === sessionId && !jobs.has(job.asyncId)) jobs.set(job.asyncId, job);
+	}
+	return [...jobs.values()];
+}
+
+export function buildAsyncStatusSnapshotForState(state: SubagentState | undefined, sessionId: string | null | undefined, options: AsyncStatusSnapshotOptions = {}): AsyncStatusSnapshotV1 {
+	return buildAsyncStatusSnapshot(asyncStatusSnapshotJobsForState(state, sessionId), options);
+}
+
+export function encodeAsyncStatusSnapshotWidget(jobs: Iterable<AsyncJobState>, options: AsyncStatusSnapshotOptions = {}): string[] {
+	return [`${ASYNC_STATUS_SNAPSHOT_WIDGET_PREFIX}${JSON.stringify(buildAsyncStatusSnapshot(jobs, options))}`];
+}

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

@@ -2,9 +2,9 @@ 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 CostSummary, type Details, type LaunchResolvedChildExtensionsV1, type RuntimeAcknowledgedChildExtensionsV1, type NestedRunSummary, type SteeringStatus, type SubagentRunMode, type TokenUsage, type TurnBudgetState, type UsageBudgetState, type ChainCheckpointState } from "../../shared/types.ts";
+import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type Details, type LaunchResolvedChildExtensionsV1, type RuntimeAcknowledgedChildExtensionsV1, type NestedRunSummary, type SteeringStatus, type SubagentRunMode, type TokenUsage, type TurnBudgetState, type UsageBudgetState } from "../../shared/types.ts";
 import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../shared/capability-ceiling.ts";
-import { pruneStatusCacheForAsyncRoot, readStatus } from "../../shared/utils.ts";
+import { readStatus } from "../../shared/utils.ts";
 import { attachRootChildrenToSteps, buildNestedRouteIndex, findNestedRouteForRootId, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
 import { formatRunFanoutBudget, getRunFanoutBudgetSnapshot, readRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
@@ -12,7 +12,9 @@ import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-grou
 import { contextModeLabel, summarizeContextModes, type ContextMode, type ContextSummary } from "../shared/context-mode.ts";
 import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
 import { readProcessTerminal, sanitizeProcessTerminal } from "./process-terminal.ts";
-import { ACTIVE_RUN_INDEX_DIR, isActiveAsyncState, readActiveRunIndex, releaseActiveRunIndex, updateActiveRunIndex } from "./active-run-index.ts";
+import { ACTIVE_RUN_INDEX_DIR, DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS, activeRunMarkerAgeMs, isActiveAsyncState, readActiveRunIndex, releaseActiveRunIndex, updateActiveRunIndex } from "./active-run-index.ts";
+import { readRecentTerminalRunIndex, TERMINAL_RUN_INDEX_DIR } from "./terminal-run-index.ts";
+import { canScanAsyncRunPrefix } from "./run-id-query.ts";
 
 interface AsyncRunStepSummary {
 	index: number;
@@ -23,8 +25,8 @@ interface AsyncRunStepSummary {
 	phase?: string;
 	outputName?: string;
 	structured?: boolean;
-	checkpoint?: ChainCheckpointState;
 	status: AsyncJobStep["status"];
+	runner?: AsyncJobStep["runner"];
 	activityState?: ActivityState;
 	lastActivityAt?: number;
 	currentTool?: string;
@@ -82,6 +84,7 @@ export interface AsyncRunSummary {
 	mode: SubagentRunMode;
 	context?: ContextSummary;
 	cwd?: string;
+	sessionRoot?: string;
 	startedAt: number;
 	lastUpdate?: number;
 	endedAt?: number;
@@ -97,7 +100,6 @@ export interface AsyncRunSummary {
 	pendingAppends?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
 	steps: AsyncRunStepSummary[];
-	checkpoint?: ChainCheckpointState;
 	sessionDir?: string;
 	outputFile?: string;
 	totalTokens?: TokenUsage;
@@ -121,13 +123,18 @@ interface AsyncRunListOptions {
 	states?: Array<AsyncRunSummary["state"]>;
 	sessionId?: string;
 	limit?: number;
-	/** Limits status-file reads after candidates are ordered by status mtime. */
+	/** Limits terminal candidates using the timestamp embedded in index marker names. */
 	entryLimit?: number;
 	resultsDir?: string;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
 	reconcile?: boolean;
 	runId?: string;
+	/** The caller already holds a canonical run id; never interpret a miss as a prefix. */
+	exactRunId?: boolean;
+	includeNested?: boolean;
+	/** Explicit repair/debug escape hatch. Normal runtime paths must not set this. */
+	repairScan?: boolean;
 }
 
 function getErrorMessage(error: unknown): string {
@@ -155,7 +162,7 @@ function isAsyncRunDir(root: string, entry: string): boolean {
 
 type TargetedAsyncRunResolution =
 	| { kind: "exact"; id: string }
-	| { kind: "scan" }
+	| { kind: "prefix" }
 	| { kind: "reject" };
 
 /**
@@ -163,13 +170,13 @@ type TargetedAsyncRunResolution =
  * accepting a path whose canonical location escaped the async root.
  */
 export function resolveTargetedAsyncRun(asyncDirRoot: string, id: string, sessionId?: string): TargetedAsyncRunResolution {
-	if (!id || id === "." || id === ".." || id === ACTIVE_RUN_INDEX_DIR || path.basename(id) !== id) return { kind: "reject" };
+	if (!id || id === "." || id === ".." || id === ACTIVE_RUN_INDEX_DIR || id === TERMINAL_RUN_INDEX_DIR || path.basename(id) !== id) return { kind: "reject" };
 	const asyncDir = path.join(asyncDirRoot, id);
 	let entryStat: fs.Stats;
 	try {
 		entryStat = fs.lstatSync(asyncDir);
 	} catch (error) {
-		if (isNotFoundError(error)) return { kind: "scan" };
+		if (isNotFoundError(error)) return canScanAsyncRunPrefix(id) ? { kind: "prefix" } : { kind: "reject" };
 		throw new Error(`Failed to inspect async run path '${asyncDir}': ${getErrorMessage(error)}`, {
 			cause: error instanceof Error ? error : undefined,
 		});
@@ -187,7 +194,7 @@ export function resolveTargetedAsyncRun(asyncDirRoot: string, id: string, sessio
 	}
 	if (sessionId !== undefined) {
 		const status = readStatus(asyncDir);
-		if (status?.sessionId !== sessionId) return { kind: "scan" };
+		if (status?.sessionId !== sessionId) return canScanAsyncRunPrefix(id) ? { kind: "prefix" } : { kind: "reject" };
 	}
 	return { kind: "exact", id };
 }
@@ -251,8 +258,8 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(step.phase ? { phase: step.phase } : {}),
 			...(step.outputName ? { outputName: step.outputName } : {}),
 			...(step.structured ? { structured: step.structured } : {}),
-			...(step.checkpoint ? { checkpoint: step.checkpoint } : {}),
 			status: step.status,
+			...(step.runner ? { runner: step.runner } : {}),
 			...(stepActivityState ? { activityState: stepActivityState } : {}),
 			...(stepLastActivityAt ? { lastActivityAt: stepLastActivityAt } : {}),
 			...(step.currentTool ? { currentTool: step.currentTool } : {}),
@@ -312,6 +319,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		mode: status.mode,
 		...(summarizeContextModes(summarizedSteps.map((step) => step.context)) ? { context: summarizeContextModes(summarizedSteps.map((step) => step.context)) } : {}),
 		cwd: status.cwd,
+		...(status.sessionRoot ? { sessionRoot: status.sessionRoot } : {}),
 		startedAt: status.startedAt,
 		lastUpdate: status.lastUpdate,
 		endedAt: status.endedAt,
@@ -327,7 +335,6 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		...(status.pendingAppends !== undefined ? { pendingAppends: status.pendingAppends } : {}),
 		...(parallelGroups.length ? { parallelGroups } : {}),
 		steps: summarizedSteps,
-		...(status.checkpoint ? { checkpoint: status.checkpoint } : {}),
 		...(nestedChildren.length ? { nestedChildren } : {}),
 		...(nestedWarnings.length ? { nestedWarnings } : {}),
 		...(processTerminal ? { processTerminal } : {}),
@@ -376,34 +383,39 @@ function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
 
 export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions = {}): AsyncRunSummary[] {
 	let entries: string[];
-	let scannedCompleteRoot = false;
-	let usedActiveIndex = false;
-	const activeOnly = options.runId === undefined
-		&& options.entryLimit === undefined
-		&& options.states !== undefined
-		&& options.states.length > 0
-		&& options.states.every(isActiveAsyncState);
+	const activeEntries = new Set<string>();
+	const wantsActive = options.states === undefined || options.states.some(isActiveAsyncState);
+	const wantsTerminal = options.states === undefined || options.states.some((state) => !isActiveAsyncState(state));
+	const includeNested = options.includeNested !== false;
 	try {
 		if (options.runId !== undefined) {
 			const resolution = resolveTargetedAsyncRun(asyncDirRoot, options.runId, options.sessionId);
 			entries = resolution.kind === "exact"
 				? [resolution.id]
-				: resolution.kind === "scan"
+				: resolution.kind === "prefix" && options.exactRunId !== true
 					? fs.readdirSync(asyncDirRoot).filter((entry) =>
 						(entry === options.runId || entry.startsWith(options.runId!))
 						&& resolveTargetedAsyncRun(asyncDirRoot, entry, options.sessionId).kind === "exact"
 					)
 					: [];
-		} else if (activeOnly) {
-			entries = (readActiveRunIndex(asyncDirRoot) ?? []).filter((entry) => {
-				if (resolveTargetedAsyncRun(asyncDirRoot, entry).kind === "exact") return true;
-				updateActiveRunIndex(path.join(asyncDirRoot, entry), "failed");
-				return false;
-			});
-			usedActiveIndex = true;
+		} else if (options.repairScan === true) {
+			entries = fs.readdirSync(asyncDirRoot).filter((entry) => entry !== ACTIVE_RUN_INDEX_DIR && entry !== TERMINAL_RUN_INDEX_DIR && isAsyncRunDir(asyncDirRoot, entry));
 		} else {
-			entries = fs.readdirSync(asyncDirRoot).filter((entry) => entry !== ACTIVE_RUN_INDEX_DIR && isAsyncRunDir(asyncDirRoot, entry));
-			scannedCompleteRoot = true;
+			const indexed = new Set<string>();
+			if (wantsActive) {
+				for (const entry of readActiveRunIndex(asyncDirRoot) ?? []) {
+					if (resolveTargetedAsyncRun(asyncDirRoot, entry).kind === "exact") {
+						indexed.add(entry);
+						activeEntries.add(entry);
+					} else {
+						updateActiveRunIndex(path.join(asyncDirRoot, entry), "failed");
+					}
+				}
+			}
+			if (wantsTerminal) {
+				for (const entry of readRecentTerminalRunIndex(asyncDirRoot, { sessionId: options.sessionId, ...(options.entryLimit !== undefined ? { limit: options.entryLimit } : {}) })) indexed.add(entry);
+			}
+			entries = [...indexed];
 		}
 	} catch (error) {
 		if (isNotFoundError(error)) return [];
@@ -412,28 +424,6 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 		});
 	}
 
-	if (options.entryLimit !== undefined) {
-		scannedCompleteRoot = false;
-		const limit = Math.max(0, Math.floor(options.entryLimit));
-		entries = entries
-			.map((entry) => {
-				try {
-					return { entry, mtimeMs: fs.statSync(path.join(asyncDirRoot, entry, "status.json")).mtimeMs };
-				} catch (error) {
-					if (isNotFoundError(error)) return undefined;
-					throw new Error(`Failed to inspect async status file for '${entry}': ${getErrorMessage(error)}`, {
-						cause: error instanceof Error ? error : undefined,
-					});
-				}
-			})
-			.filter((candidate): candidate is { entry: string; mtimeMs: number } => candidate !== undefined)
-			.sort((left, right) => right.mtimeMs - left.mtimeMs)
-			.slice(0, limit)
-			.map((candidate) => candidate.entry);
-	}
-
-	if (scannedCompleteRoot) pruneStatusCacheForAsyncRoot(asyncDirRoot, entries);
-
 	const allowedStates = options.states ? new Set(options.states) : undefined;
 	const runs: AsyncRunSummary[] = [];
 	// Route resolution for every run shares a single index built from the
@@ -443,7 +433,8 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 	// entirely when no active runs match.
 	let nestedRouteIndex: Map<string, NestedRoute> | undefined;
 	const resolveNestedRoute = (rootRunId: string): NestedRoute | undefined => {
-		if (usedActiveIndex) return findNestedRouteForRootId(rootRunId);
+		if (!includeNested) return undefined;
+		if (activeEntries.has(rootRunId)) return findNestedRouteForRootId(rootRunId);
 		if (!nestedRouteIndex) nestedRouteIndex = buildNestedRouteIndex();
 		return nestedRouteIndex.get(rootRunId);
 	};
@@ -454,12 +445,12 @@ 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) {
-			if (usedActiveIndex) updateActiveRunIndex(asyncDir, "failed");
+			if (activeEntries.has(entry)) updateActiveRunIndex(asyncDir, "failed");
 			continue;
 		}
-		if (usedActiveIndex && !isActiveAsyncState(status.state)) {
+		if (activeEntries.has(entry) && !isActiveAsyncState(status.state)) {
 			const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId });
-			if (processTerminal?.state === "observed") releaseActiveRunIndex(asyncDir);
+			if (processTerminal?.state === "observed" || (activeRunMarkerAgeMs(asyncDir, options.now?.()) ?? 0) > DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS) releaseActiveRunIndex(asyncDir);
 		}
 		if (status.displayDismissedAt !== undefined) continue;
 		// Filter before the nested-route lookup: the lookup builds an index over
@@ -470,7 +461,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 		if (options.sessionId && status.sessionId !== options.sessionId) continue;
 		const nestedWarnings: string[] = [];
 		let nestedRoute: NestedRoute | undefined;
-		if (options.reconcile !== false) {
+		if (options.reconcile !== false && includeNested) {
 			try {
 				nestedRoute = resolveNestedRoute(status.runId || path.basename(asyncDir));
 				if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });

package/src/runs/background/chain-append.ts

@@ -5,8 +5,8 @@ import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { appendJsonl } from "../../shared/artifacts.ts";
 import type { AsyncParallelGroupStatus, AsyncStatus, WorkflowGraphNode, WorkflowGraphSnapshot } from "../../shared/types.ts";
 import { PROMPT_REDACTED, readStatus } from "../../shared/utils.ts";
-import type { DynamicRunnerGroup, ParallelStepGroup, RunnerStep, RunnerSubagentStep, RunnerCheckpointStep } from "../shared/parallel-utils.ts";
-import { isCheckpointRunnerStep, isDynamicRunnerGroup, isParallelGroup } from "../shared/parallel-utils.ts";
+import type { DynamicRunnerGroup, ParallelStepGroup, RunnerStep, RunnerSubagentStep } from "../shared/parallel-utils.ts";
+import { isDynamicRunnerGroup, isParallelGroup } from "../shared/parallel-utils.ts";
 
 const APPEND_REQUESTS_DIR = "append-requests";
 
@@ -52,9 +52,7 @@ export function countPendingChainAppendRequests(asyncDir: string): number {
 export function runnerStepOutputNames(steps: RunnerStep[]): string[] {
 	const names: string[] = [];
 	for (const step of steps) {
-		if (isCheckpointRunnerStep(step)) {
-			continue;
-		} else if (isParallelGroup(step)) {
+		if (isParallelGroup(step)) {
 			names.push(...step.parallel.map((task) => task.outputName).filter((name): name is string => Boolean(name)));
 		} else if (isDynamicRunnerGroup(step)) {
 			if (step.collect.as) names.push(step.collect.as);
@@ -181,20 +179,7 @@ function statusStepForTask(task: RunnerSubagentStep): StatusStep {
 	};
 }
 
-function statusStepForCheckpoint(step: RunnerCheckpointStep, stepIndex: number): StatusStep {
-	return {
-		agent: `checkpoint:${step.checkpoint}`,
-		phase: step.phase,
-		label: step.label ?? step.checkpoint,
-		status: "pending",
-		checkpoint: { name: step.checkpoint, ...(step.message ? { message: step.message } : {}), status: "pending", stepIndex },
-		recentTools: [],
-		recentOutput: [],
-	};
-}
-
 function statusStepsForRunnerStep(step: RunnerStep, stepIndex: number): StatusStep[] {
-	if (isCheckpointRunnerStep(step)) return [statusStepForCheckpoint(step, stepIndex)];
 	if (isParallelGroup(step)) return step.parallel.map(statusStepForTask);
 	if (isDynamicRunnerGroup(step)) {
 		return [{
@@ -286,21 +271,6 @@ function graphNodeForDynamic(step: DynamicRunnerGroup, stepIndex: number): Workf
 
 function appendWorkflowNode(graph: WorkflowGraphSnapshot | undefined, step: RunnerStep, stepIndex: number, flatIndex: number): void {
 	if (!graph) return;
-	if (isCheckpointRunnerStep(step)) {
-		const node: WorkflowGraphNode = {
-			id: `step-${stepIndex}`,
-			kind: "checkpoint",
-			phase: step.phase,
-			label: step.label?.trim() || step.checkpoint,
-			status: "pending",
-			flatIndex,
-			stepIndex,
-			checkpoint: { name: step.checkpoint, ...(step.message ? { message: step.message } : {}), status: "pending", stepIndex },
-		};
-		graph.nodes.push(node);
-		pushPhase(graph, step.phase, node.id);
-		return;
-	}
 	if (isParallelGroup(step)) {
 		graph.nodes.push(graphNodeForParallel(step, stepIndex, flatIndex, graph));
 		return;

package/src/runs/background/chain-root-attachment.ts

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
+import { resultFilePath } from "./result-files.ts";
 import type { AcceptanceLedger, AsyncStatus, CostSummary, ModelAttempt } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 
@@ -195,5 +195,5 @@ export async function waitForImportedAsyncRoot(
 }
 
 export function resolveAsyncRootResultPath(resultsDir: string, runId: string): string {
-	return path.join(resultsDir, `${runId}.json`);
+	return resultFilePath(resultsDir, runId);
 }

package/src/runs/background/completion-replay.ts

@@ -9,6 +9,8 @@ const ARCHIVE_VERSION = 1;
 const ARCHIVE_TEXT_LIMIT_BYTES = 64 * 1024;
 const REPLAY_DIR_NAME = "completion-replay";
 const ARCHIVE_DIR_NAME = "output-archives";
+const CLEANUP_INTERVAL_MS = 60_000;
+const lastCleanupByResultsDir = new Map<string, number>();
 
 export interface CompletionArchiveEntry {
 	agent?: string;
@@ -194,7 +196,7 @@ export function writeCompletionReplay(input: {
 		archivePath,
 	};
 	writePrivateAtomicJson(completionReplayPath(input.resultsDir, input.runId), record);
-	cleanupCompletionReplay(input.resultsDir, input.now, input.ttlMs);
+	cleanupCompletionReplayIfDue(input.resultsDir, input.now, input.ttlMs);
 	return record;
 }
 
@@ -233,6 +235,14 @@ export function readCompletionArchive(archivePath: string): CompletionArchive |
 	}
 }
 
+export function cleanupCompletionReplayIfDue(resultsDir: string, now: number, maxAgeMs: number, intervalMs = CLEANUP_INTERVAL_MS): boolean {
+	const last = lastCleanupByResultsDir.get(resultsDir);
+	if (last !== undefined && now - last < intervalMs) return false;
+	lastCleanupByResultsDir.set(resultsDir, now);
+	cleanupCompletionReplay(resultsDir, now, maxAgeMs);
+	return true;
+}
+
 /** Opportunistically remove expired replay and orphan archive files without affecting delivery. */
 export function cleanupCompletionReplay(resultsDir: string, now: number, maxAgeMs: number): void {
 	const replayDir = path.join(resultsDir, REPLAY_DIR_NAME);