@selesai/code 0.8.3 → 0.8.5

package/dist/extensions/pi-subagents/src/runs/background/async-status.ts

@@ -4,13 +4,15 @@ import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "
 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 { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../shared/capability-ceiling.ts";
-import { readStatus } from "../../shared/utils.ts";
-import { attachRootChildrenToSteps, buildNestedRouteIndex, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
+import { pruneStatusCacheForAsyncRoot, 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";
 import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
 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";
 
 interface AsyncRunStepSummary {
 	index: number;
@@ -65,6 +67,7 @@ interface AsyncRunStepSummary {
 export interface AsyncRunSummary {
 	id: string;
 	asyncDir: string;
+	toolCallId?: string;
 	sessionId?: string;
 	state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
 	error?: string;
@@ -104,6 +107,7 @@ export interface AsyncRunSummary {
 	nestedChildren?: NestedRunSummary[];
 	nestedWarnings?: string[];
 	processTerminal?: AsyncStatus["processTerminal"];
+	runFanoutBudget?: AsyncStatus["runFanoutBudget"];
 	launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
 	runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
 	capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -159,7 +163,7 @@ 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 === ".." || path.basename(id) !== id) return { kind: "reject" };
+	if (!id || id === "." || id === ".." || id === ACTIVE_RUN_INDEX_DIR || path.basename(id) !== id) return { kind: "reject" };
 	const asyncDir = path.join(asyncDirRoot, id);
 	let entryStat: fs.Stats;
 	try {
@@ -206,7 +210,10 @@ function deriveAsyncActivityState(asyncDir: string, status: AsyncStatus): { acti
 	const currentStep = typeof status.currentStep === "number" ? status.steps?.[status.currentStep] : undefined;
 	return {
 		activityState: status.activityState,
-		lastActivityAt: status.lastActivityAt ?? outputFileMtime(outputPath) ?? currentStep?.lastActivityAt ?? currentStep?.startedAt ?? status.startedAt,
+		lastActivityAt: status.lastActivityAt
+			?? outputFileMtime(outputPath)
+			?? currentStep?.lastActivityAt
+			?? (status.mode === "workflow" ? undefined : currentStep?.startedAt ?? status.startedAt),
 	};
 }
 
@@ -217,6 +224,8 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	const { activityState, lastActivityAt } = deriveAsyncActivityState(asyncDir, status);
 	const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId })
 		?? sanitizeProcessTerminal(status.processTerminal, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId }, path.join(asyncDir, "status.json"));
+	const runFanoutBudgetDescriptor = readRunFanoutBudgetDescriptor(asyncDir);
+	const runFanoutBudget = runFanoutBudgetDescriptor ? getRunFanoutBudgetSnapshot(runFanoutBudgetDescriptor) : status.runFanoutBudget;
 	const steps = status.steps ?? [];
 	const chainStepCount = status.chainStepCount ?? steps.length;
 	const parallelGroups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
@@ -288,6 +297,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	return {
 		id: status.runId || path.basename(asyncDir),
 		asyncDir,
+		...(status.toolCallId ? { toolCallId: status.toolCallId } : {}),
 		...(status.sessionId ? { sessionId: status.sessionId } : {}),
 		state: status.state,
 		...(status.error ? { error: status.error } : {}),
@@ -321,6 +331,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		...(nestedChildren.length ? { nestedChildren } : {}),
 		...(nestedWarnings.length ? { nestedWarnings } : {}),
 		...(processTerminal ? { processTerminal } : {}),
+		...(runFanoutBudget ? { runFanoutBudget } : {}),
 		...(status.launchContractDigest ? { launchContractDigest: status.launchContractDigest } : {}),
 		...(status.launchResolvedExtensions ? { launchResolvedExtensions: status.launchResolvedExtensions } : {}),
 		...(status.runtimeAcknowledgedExtensions ? { runtimeAcknowledgedExtensions: status.runtimeAcknowledgedExtensions } : {}),
@@ -365,6 +376,13 @@ 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);
 	try {
 		if (options.runId !== undefined) {
 			const resolution = resolveTargetedAsyncRun(asyncDirRoot, options.runId, options.sessionId);
@@ -376,8 +394,16 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 						&& 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 {
-			entries = fs.readdirSync(asyncDirRoot).filter((entry) => isAsyncRunDir(asyncDirRoot, entry));
+			entries = fs.readdirSync(asyncDirRoot).filter((entry) => entry !== ACTIVE_RUN_INDEX_DIR && isAsyncRunDir(asyncDirRoot, entry));
+			scannedCompleteRoot = true;
 		}
 	} catch (error) {
 		if (isNotFoundError(error)) return [];
@@ -387,6 +413,7 @@ 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) => {
@@ -405,6 +432,8 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 			.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
@@ -414,6 +443,7 @@ 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 (!nestedRouteIndex) nestedRouteIndex = buildNestedRouteIndex();
 		return nestedRouteIndex.get(rootRunId);
 	};
@@ -423,7 +453,15 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 			? undefined
 			: 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;
+		if (!status) {
+			if (usedActiveIndex) updateActiveRunIndex(asyncDir, "failed");
+			continue;
+		}
+		if (usedActiveIndex && !isActiveAsyncState(status.state)) {
+			const processTerminal = readProcessTerminal(asyncDir, { runId: status.runId, runnerProcessInstanceId: status.processTerminal?.runnerProcessInstanceId });
+			if (processTerminal?.state === "observed") releaseActiveRunIndex(asyncDir);
+		}
+		if (status.displayDismissedAt !== undefined) continue;
 		// Filter before the nested-route lookup: the lookup builds an index over
 		// the nested-events directory, so deferring it for filtered-out runs keeps
 		// restoration at load from scanning that directory when no active runs
@@ -526,6 +564,7 @@ export function formatAsyncRunList(runs: AsyncRunSummary[], heading = "Active as
 		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 }));
+		if (run.runFanoutBudget) lines.push(`  ${formatRunFanoutBudget(run.runFanoutBudget)}`);
 		if (run.error) lines.push(`  Error: ${run.error}`);
 		for (const warning of run.nestedWarnings ?? []) lines.push(`  Warning: ${warning}`);
 		const outputPath = formatAsyncRunOutputPath(run);

package/dist/extensions/pi-subagents/src/runs/background/chain-append.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
 import { appendJsonl } from "../../shared/artifacts.ts";
 import type { AsyncParallelGroupStatus, AsyncStatus, WorkflowGraphNode, WorkflowGraphSnapshot } from "../../shared/types.ts";
-import { readStatus } from "../../shared/utils.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";
 
@@ -19,6 +19,7 @@ export interface ChainAppendRequest {
 export interface ChainAppendResult {
 	request: ChainAppendRequest;
 	pendingCount: number;
+	bookkeepingError?: string;
 }
 
 type StatusStep = NonNullable<AsyncStatus["steps"]>[number];
@@ -69,6 +70,7 @@ export function enqueueChainAppendRequest(input: {
 	runId: string;
 	steps: RunnerStep[];
 	now?: number;
+	admit?: (persist: () => void) => void;
 }): ChainAppendResult {
 	const status = readStatus(input.asyncDir);
 	if (!status) throw new Error(`No async run status found for '${input.runId}'.`);
@@ -85,20 +87,36 @@ export function enqueueChainAppendRequest(input: {
 		steps: input.steps,
 	};
 	fs.mkdirSync(appendDir(input.asyncDir), { recursive: true });
-	writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
-	const pendingCount = countPendingChainAppendRequests(input.asyncDir);
+	const persist = () => writeAtomicJson(appendRequestPath(input.asyncDir, request), request);
+	if (input.admit) input.admit(persist);
+	else persist();
+	let pendingCount = 1;
+	const bookkeepingErrors: string[] = [];
+	try {
+		pendingCount = countPendingChainAppendRequests(input.asyncDir);
+	} catch (error) {
+		bookkeepingErrors.push(`pending append count failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
 	const statusPath = path.join(input.asyncDir, "status.json");
 	const updatedStatus = { ...status, pendingAppends: pendingCount, lastUpdate: request.createdAt };
-	writeAtomicJson(statusPath, updatedStatus);
-	appendJsonl(path.join(input.asyncDir, "events.jsonl"), JSON.stringify({
-		type: "subagent.chain.append.requested",
-		ts: request.createdAt,
-		runId: input.runId,
-		requestId: request.id,
-		stepCount: input.steps.length,
-		pendingAppends: pendingCount,
-	}));
-	return { request, pendingCount };
+	try {
+		writeAtomicJson(statusPath, updatedStatus);
+	} catch (error) {
+		bookkeepingErrors.push(`status update failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	try {
+		appendJsonl(path.join(input.asyncDir, "events.jsonl"), JSON.stringify({
+			type: "subagent.chain.append.requested",
+			ts: request.createdAt,
+			runId: input.runId,
+			requestId: request.id,
+			stepCount: input.steps.length,
+			pendingAppends: pendingCount,
+		}));
+	} catch (error) {
+		bookkeepingErrors.push(`event append failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	return { request, pendingCount, ...(bookkeepingErrors.length > 0 ? { bookkeepingError: bookkeepingErrors.join("; ") } : {}) };
 }
 
 function readAppendRequest(filePath: string): ChainAppendRequest | undefined {
@@ -135,8 +153,8 @@ const MAX_STATUS_STEP_DESCRIPTION_CHARS = 160;
 
 /** Bounded one-line per-step task description persisted into status.json for fleet display. */
 export function statusStepDescription(task: string | undefined): string | undefined {
-	const description = task?.replace(/\s+/g, " ").trim();
-	if (!description) return undefined;
+	if (!task?.trim()) return undefined;
+	const description = PROMPT_REDACTED;
 	return description.length > MAX_STATUS_STEP_DESCRIPTION_CHARS
 		? `${description.slice(0, MAX_STATUS_STEP_DESCRIPTION_CHARS - 1)}…`
 		: description;

package/dist/extensions/pi-subagents/src/runs/background/completion-replay.ts

@@ -0,0 +1,267 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
+import type { WaitCompletion } from "../../shared/types.ts";
+import { utf8Tail } from "../../shared/utf8.ts";
+
+const REPLAY_VERSION = 1;
+const ARCHIVE_VERSION = 1;
+const ARCHIVE_TEXT_LIMIT_BYTES = 64 * 1024;
+const REPLAY_DIR_NAME = "completion-replay";
+const ARCHIVE_DIR_NAME = "output-archives";
+
+export interface CompletionArchiveEntry {
+	agent?: string;
+	source: "output-artifact" | "session" | "result-tail";
+	path?: string;
+	text?: string;
+	truncated?: boolean;
+}
+
+export interface CompletionArchive {
+	version: 1;
+	runId: string;
+	createdAt: number;
+	entries: CompletionArchiveEntry[];
+}
+
+export interface CompletionReplayRecord {
+	version: 1;
+	runId: string;
+	sessionId: string;
+	completedAt: number;
+	expiresAt: number;
+	completion: WaitCompletion;
+	archivePath: string;
+}
+
+function safeRunFile(runId: string): string {
+	return `${encodeURIComponent(runId)}.json`;
+}
+
+export function completionReplayPath(resultsDir: string, runId: string): string {
+	return path.join(resultsDir, REPLAY_DIR_NAME, safeRunFile(runId));
+}
+
+export function completionArchivePath(resultsDir: string, runId: string): string {
+	return path.join(resultsDir, ARCHIVE_DIR_NAME, safeRunFile(runId));
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function existingFile(value: unknown): string | undefined {
+	const filePath = nonEmptyString(value);
+	if (!filePath) return undefined;
+	try {
+		return fs.statSync(filePath).isFile() ? filePath : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function outputArtifactPath(child: Record<string, unknown>): string | undefined {
+	if (!child.artifactPaths || typeof child.artifactPaths !== "object" || Array.isArray(child.artifactPaths)) return undefined;
+	return existingFile((child.artifactPaths as Record<string, unknown>).outputPath);
+}
+
+/** Create a small archive that references saved child artifacts and retains only bounded fallback output text. */
+export function writeCompletionArchive(resultsDir: string, runId: string, data: Record<string, unknown>, createdAt: number): string {
+	const entries: CompletionArchiveEntry[] = [];
+	const fallback: string[] = [];
+	const results = Array.isArray(data.results) ? data.results : [];
+	for (const value of results) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+		const child = value as Record<string, unknown>;
+		const agent = nonEmptyString(child.agent);
+		const artifactPath = outputArtifactPath(child);
+		if (artifactPath) {
+			entries.push({ ...(agent ? { agent } : {}), source: "output-artifact", path: artifactPath });
+			continue;
+		}
+		const sessionPath = existingFile(child.sessionFile);
+		if (sessionPath) {
+			entries.push({ ...(agent ? { agent } : {}), source: "session", path: sessionPath });
+			continue;
+		}
+		const output = nonEmptyString(child.output);
+		const error = nonEmptyString(child.error);
+		if (output || error) {
+			fallback.push([agent ? `[${agent}]` : undefined, error ? `Error: ${error}` : undefined, output].filter(Boolean).join("\n"));
+		}
+	}
+	if (results.length === 0) {
+		const sessionPath = existingFile(data.sessionFile);
+		if (sessionPath) entries.push({ source: "session", path: sessionPath });
+	}
+	if (entries.length === 0 && fallback.length === 0) {
+		const summary = nonEmptyString(data.summary);
+		if (summary) fallback.push(summary);
+	}
+	if (fallback.length > 0) {
+		const bounded = utf8Tail(fallback.join("\n\n"), ARCHIVE_TEXT_LIMIT_BYTES);
+		entries.push({ source: "result-tail", text: bounded.text, ...(bounded.truncated ? { truncated: true } : {}) });
+	}
+	const archive: CompletionArchive = { version: ARCHIVE_VERSION, runId, createdAt, entries };
+	const archivePath = completionArchivePath(resultsDir, runId);
+	writePrivateAtomicJson(archivePath, archive);
+	return archivePath;
+}
+
+function parseCompletion(value: unknown, runId: string): WaitCompletion | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const completion = value as Partial<WaitCompletion>;
+	if (completion.runId !== runId) return undefined;
+	return completion as WaitCompletion;
+}
+
+function parseReplay(value: unknown): CompletionReplayRecord | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Partial<CompletionReplayRecord>;
+	if (record.version !== REPLAY_VERSION
+		|| typeof record.runId !== "string"
+		|| typeof record.sessionId !== "string"
+		|| typeof record.completedAt !== "number"
+		|| typeof record.expiresAt !== "number"
+		|| typeof record.archivePath !== "string") return undefined;
+	const completion = parseCompletion(record.completion, record.runId);
+	return completion ? { ...record, completion } as CompletionReplayRecord : undefined;
+}
+
+function validateReplayRecord(resultsDir: string, runId: string, record: CompletionReplayRecord): CompletionReplayRecord | undefined {
+	if (record.runId !== runId) return undefined;
+	const archivePath = completionArchivePath(resultsDir, runId);
+	return path.resolve(record.archivePath) === path.resolve(archivePath)
+		? { ...record, archivePath, completion: { ...record.completion, archivePath } }
+		: undefined;
+}
+
+function runIdFromReplayFile(file: string): string | undefined {
+	if (!file.endsWith(".json")) return undefined;
+	try {
+		const runId = decodeURIComponent(file.slice(0, -".json".length));
+		return safeRunFile(runId) === file ? runId : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function removeBestEffort(filePath: string): void {
+	try {
+		fs.rmSync(filePath, { force: true });
+	} catch { /* cleanup only */ }
+}
+
+function parseArchive(value: unknown): CompletionArchive | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const archive = value as Partial<CompletionArchive>;
+	if (archive.version !== ARCHIVE_VERSION || typeof archive.runId !== "string" || typeof archive.createdAt !== "number" || !Array.isArray(archive.entries)) return undefined;
+	const entries = archive.entries.flatMap((value): CompletionArchiveEntry[] => {
+		if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+		const entry = value as Partial<CompletionArchiveEntry>;
+		if (entry.source !== "output-artifact" && entry.source !== "session" && entry.source !== "result-tail") return [];
+		return [{
+			...(typeof entry.agent === "string" ? { agent: entry.agent } : {}),
+			source: entry.source,
+			...(typeof entry.path === "string" ? { path: entry.path } : {}),
+			...(typeof entry.text === "string" ? { text: entry.text } : {}),
+			...(entry.truncated === true ? { truncated: true } : {}),
+		}];
+	});
+	return { version: ARCHIVE_VERSION, runId: archive.runId, createdAt: archive.createdAt, entries };
+}
+
+/** Persist a terminal completion before its one-shot result file is removed. */
+export function writeCompletionReplay(input: {
+	resultsDir: string;
+	runId: string;
+	sessionId: string;
+	completion: WaitCompletion;
+	data: Record<string, unknown>;
+	now: number;
+	ttlMs: number;
+}): CompletionReplayRecord {
+	const archivePath = writeCompletionArchive(input.resultsDir, input.runId, input.data, input.now);
+	const completion = { ...input.completion, archivePath };
+	const record: CompletionReplayRecord = {
+		version: REPLAY_VERSION,
+		runId: input.runId,
+		sessionId: input.sessionId,
+		completedAt: input.now,
+		expiresAt: input.now + input.ttlMs,
+		completion,
+		archivePath,
+	};
+	writePrivateAtomicJson(completionReplayPath(input.resultsDir, input.runId), record);
+	cleanupCompletionReplay(input.resultsDir, input.now, input.ttlMs);
+	return record;
+}
+
+/** Read a current replay record. Unknown fields are ignored and unknown versions are skipped. */
+export function readCompletionReplay(resultsDir: string, runId: string, options: { sessionId?: string; now?: number } = {}): CompletionReplayRecord | undefined {
+	const replayPath = completionReplayPath(resultsDir, runId);
+	let parsed: CompletionReplayRecord | undefined;
+	try {
+		parsed = parseReplay(JSON.parse(fs.readFileSync(replayPath, "utf-8")));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	if (!parsed) return undefined;
+	const safeRecord = validateReplayRecord(resultsDir, runId, parsed);
+	if (!safeRecord) {
+		removeBestEffort(replayPath);
+		return undefined;
+	}
+	parsed = safeRecord;
+	if (options.sessionId !== undefined && parsed.sessionId !== options.sessionId) return undefined;
+	if (parsed.expiresAt <= (options.now ?? Date.now())) {
+		removeBestEffort(replayPath);
+		removeBestEffort(parsed.archivePath);
+		return undefined;
+	}
+	return parsed;
+}
+
+export function readCompletionArchive(archivePath: string): CompletionArchive | undefined {
+	try {
+		return parseArchive(JSON.parse(fs.readFileSync(archivePath, "utf-8")));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+/** 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);
+	try {
+		for (const file of fs.readdirSync(replayDir)) {
+			const runId = runIdFromReplayFile(file);
+			if (!runId) continue;
+			const filePath = path.join(replayDir, file);
+			try {
+				const record = parseReplay(JSON.parse(fs.readFileSync(filePath, "utf-8")));
+				const safeRecord = record ? validateReplayRecord(resultsDir, runId, record) : undefined;
+				if (record && !safeRecord) {
+					fs.rmSync(filePath, { force: true });
+				} else if (safeRecord && safeRecord.expiresAt <= now) {
+					fs.rmSync(filePath, { force: true });
+					fs.rmSync(safeRecord.archivePath, { force: true });
+				} else if (!record && now - fs.statSync(filePath).mtimeMs > maxAgeMs) {
+					fs.rmSync(filePath, { force: true });
+				}
+			} catch { /* one bad entry must not block cleanup */ }
+		}
+	} catch { /* replay directory may not exist yet */ }
+	const archiveDir = path.join(resultsDir, ARCHIVE_DIR_NAME);
+	try {
+		for (const file of fs.readdirSync(archiveDir)) {
+			const filePath = path.join(archiveDir, file);
+			try {
+				if (now - fs.statSync(filePath).mtimeMs > maxAgeMs) fs.rmSync(filePath, { force: true });
+			} catch { /* one bad entry must not block cleanup */ }
+		}
+	} catch { /* archive directory may not exist yet */ }
+}