pi-subagents 0.48.0 → 0.50.0

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

@@ -12,7 +12,7 @@ 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";
 
 interface AsyncRunStepSummary {
 	index: number;
@@ -25,6 +25,7 @@ interface AsyncRunStepSummary {
 	structured?: boolean;
 	checkpoint?: ChainCheckpointState;
 	status: AsyncJobStep["status"];
+	runner?: AsyncJobStep["runner"];
 	activityState?: ActivityState;
 	lastActivityAt?: number;
 	currentTool?: string;
@@ -128,6 +129,7 @@ interface AsyncRunListOptions {
 	now?: () => number;
 	reconcile?: boolean;
 	runId?: string;
+	includeNested?: boolean;
 }
 
 function getErrorMessage(error: unknown): string {
@@ -253,6 +255,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(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 } : {}),
@@ -383,6 +386,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 		&& options.states !== undefined
 		&& options.states.length > 0
 		&& options.states.every(isActiveAsyncState);
+	const includeNested = options.includeNested !== false;
 	try {
 		if (options.runId !== undefined) {
 			const resolution = resolveTargetedAsyncRun(asyncDirRoot, options.runId, options.sessionId);
@@ -443,6 +447,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 (!includeNested) return undefined;
 		if (usedActiveIndex) return findNestedRouteForRootId(rootRunId);
 		if (!nestedRouteIndex) nestedRouteIndex = buildNestedRouteIndex();
 		return nestedRouteIndex.get(rootRunId);
@@ -459,7 +464,7 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 		}
 		if (usedActiveIndex && !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 +475,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-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);

package/src/runs/background/fleet-view.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { safeTerminalText } from "../../shared/display-text.ts";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
 import { formatActivityLabel } from "../../shared/status-format.ts";
 import {
@@ -196,7 +197,7 @@ function readSessionTranscriptTail(sessionFile: string, maxLines: number, truste
 		try {
 			const parsed = JSON.parse(line) as unknown;
 			const messageLine = sessionMessageLine(parsed);
-			if (messageLine) lines.push(messageLine);
+			if (messageLine) lines.push(...messageLine.split(/\r?\n/));
 		} catch {
 			malformed++;
 		}
@@ -410,6 +411,18 @@ function appendKnownArtifacts(lines: string[], input: { outputPaths: string[]; s
 	for (const artifact of artifacts) lines.push(`  ${artifact}`);
 }
 
+/**
+ * Sanitizes each assembled line independently.
+ *
+ * Sanitizing the joined response would let a single binary fragment in child
+ * output collapse the whole transcript, including run state, artifact paths, and
+ * warnings, into the binary placeholder. Per-line sanitization keeps that damage
+ * to the offending line.
+ */
+function safeTranscriptLines(lines: string[]): string {
+	return lines.map((line) => safeTerminalText(line)).join("\n");
+}
+
 function appendTranscriptBody(lines: string[], sourceLabel: string, sourceLines: string[], truncated: boolean): void {
 	lines.push(`${sourceLabel}${truncated ? " (tail truncated)" : ""}:`);
 	if (sourceLines.length === 0) {
@@ -430,6 +443,8 @@ export function formatAsyncRunTranscript(status: AsyncStatus, asyncDir: string,
 		: uniqueStrings([runOutputPath]);
 	const sessionFile = selected.index !== undefined ? selected.step?.sessionFile : status.sessionFile;
 	const eventsPath = path.join(asyncDir, "events.jsonl");
+	// Synthesized output paths can name files that were never written. Keep the unfiltered paths
+	// below so a present-but-unreadable file still reports its read error.
 
 	const context = contextModeLabel(status.context ?? summarizeContextModes((status.steps ?? []).map((step) => step.context)));
 	const lines = [
@@ -439,7 +454,7 @@ export function formatAsyncRunTranscript(status: AsyncStatus, asyncDir: string,
 		stepStateLine(status.mode, selected.index, selected.step),
 		selected.hint,
 	].filter((line): line is string => Boolean(line));
-	appendKnownArtifacts(lines, { outputPaths, sessionFile, eventsPath: fs.existsSync(eventsPath) ? eventsPath : undefined, logPath: fs.existsSync(logPath) ? logPath : undefined });
+	appendKnownArtifacts(lines, { outputPaths: outputPaths.filter((outputPath) => fs.existsSync(outputPath)), sessionFile, eventsPath: fs.existsSync(eventsPath) ? eventsPath : undefined, logPath: fs.existsSync(logPath) ? logPath : undefined });
 
 	const warnings: string[] = [];
 	let transcriptLines: string[] = [];
@@ -470,7 +485,7 @@ export function formatAsyncRunTranscript(status: AsyncStatus, asyncDir: string,
 		for (const warning of warnings) lines.push(`  ${warning}`);
 	}
 	appendTranscriptBody(lines, transcriptSource, transcriptLines, truncated);
-	return lines.join("\n");
+	return safeTranscriptLines(lines);
 }
 
 export function formatNestedRunTranscript(run: NestedRunSummary, options: TranscriptOptions = {}): string {
@@ -488,7 +503,7 @@ export function formatNestedRunTranscript(run: NestedRunSummary, options: Transc
 	appendKnownArtifacts(lines, { outputPaths: [], sessionFile: run.sessionFile });
 	if (!run.sessionFile) {
 		appendTranscriptBody(lines, "Transcript tail", [], false);
-		return lines.join("\n");
+		return safeTranscriptLines(lines);
 	}
 	const sessionTail = readSessionTranscriptTail(run.sessionFile, lineLimit, options.sessionRoots ?? []);
 	if (sessionTail.warnings.length) {
@@ -496,7 +511,7 @@ export function formatNestedRunTranscript(run: NestedRunSummary, options: Transc
 		for (const warning of sessionTail.warnings) lines.push(`  ${warning}`);
 	}
 	appendTranscriptBody(lines, `Session transcript tail from ${run.sessionFile}`, sessionTail.lines, false);
-	return lines.join("\n");
+	return safeTranscriptLines(lines);
 }
 
 export function formatAsyncResultTranscript(data: {
@@ -536,5 +551,5 @@ export function formatAsyncResultTranscript(data: {
 	].filter((line): line is string => Boolean(line));
 	appendKnownArtifacts(lines, { outputPaths: [], sessionFile, resultPath });
 	appendTranscriptBody(lines, "Result transcript tail", transcriptLines.filter((line) => line.trim()), output.split(/\r?\n/).length > lineLimit);
-	return lines.join("\n");
+	return safeTranscriptLines(lines);
 }

package/src/runs/background/result-files.ts

@@ -0,0 +1,437 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import { MISSION_BINDING_FILE } from "../../missions/lifecycle.ts";
+
+const RESULT_INDEX_VERSION = 1;
+const RESULT_INDEX_DIR = "result-index";
+const SESSION_INDEX_DIR = "sessions";
+const OBSERVER_INDEX_DIR = "observers";
+const TOOL_CALL_INDEX_DIR = "tool-calls";
+const RESULT_PENDING_DIR = "result-pending";
+const MISSION_OBSERVER = "mission";
+
+export interface ResultIndexEntry {
+	version: 1;
+	runId: string;
+	sessionId: string;
+	file: string;
+	writtenAt: number;
+	asyncDir?: string;
+}
+
+function encodeSegment(value: string): string {
+	return encodeURIComponent(value);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export function resultFileName(runId: string): string {
+	return `${runId}.json`;
+}
+
+export function resultFilePath(resultsDir: string, runId: string): string {
+	return path.join(resultsDir, resultFileName(runId));
+}
+
+function sessionIndexDir(resultsDir: string, sessionId: string): string {
+	return path.join(resultsDir, RESULT_INDEX_DIR, SESSION_INDEX_DIR, encodeSegment(sessionId));
+}
+
+function resultIndexPath(resultsDir: string, sessionId: string, runId: string): string {
+	return path.join(sessionIndexDir(resultsDir, sessionId), `${encodeSegment(runId)}.json`);
+}
+
+function resultPendingPath(resultsDir: string, sessionId: string, runId: string): string {
+	return path.join(resultsDir, RESULT_PENDING_DIR, encodeSegment(sessionId), `${encodeSegment(runId)}.json`);
+}
+
+function observerIndexDir(resultsDir: string, observer: string): string {
+	return path.join(resultsDir, RESULT_INDEX_DIR, OBSERVER_INDEX_DIR, observer);
+}
+
+function observerIndexPath(resultsDir: string, observer: string, runId: string): string {
+	return path.join(observerIndexDir(resultsDir, observer), `${encodeSegment(runId)}.json`);
+}
+
+function toolCallIndexDir(resultsDir: string, toolCallId: string): string {
+	return path.join(resultsDir, RESULT_INDEX_DIR, TOOL_CALL_INDEX_DIR, encodeSegment(toolCallId));
+}
+
+function toolCallIndexPath(resultsDir: string, toolCallId: string, runId: string): string {
+	return path.join(toolCallIndexDir(resultsDir, toolCallId), `${encodeSegment(runId)}.json`);
+}
+
+function parseResultIndexEntry(value: unknown): ResultIndexEntry | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Partial<ResultIndexEntry>;
+	if (record.version !== RESULT_INDEX_VERSION
+		|| typeof record.runId !== "string"
+		|| typeof record.sessionId !== "string"
+		|| typeof record.file !== "string"
+		|| typeof record.writtenAt !== "number") return undefined;
+	return {
+		version: RESULT_INDEX_VERSION,
+		runId: record.runId,
+		sessionId: record.sessionId,
+		file: record.file,
+		writtenAt: record.writtenAt,
+		...(typeof record.asyncDir === "string" ? { asyncDir: record.asyncDir } : {}),
+	};
+}
+
+export function writeResultIndexForData(resultPath: string, data: Record<string, unknown>): void {
+	const runId = nonEmptyString(data.runId) ?? nonEmptyString(data.id) ?? path.basename(resultPath, ".json");
+	const sessionId = nonEmptyString(data.sessionId);
+	if (!runId || !sessionId) return;
+	const file = path.basename(resultPath);
+	const entry: ResultIndexEntry = {
+		version: RESULT_INDEX_VERSION,
+		runId,
+		sessionId,
+		file,
+		writtenAt: Date.now(),
+		...(nonEmptyString(data.asyncDir) ? { asyncDir: nonEmptyString(data.asyncDir)! } : {}),
+	};
+	const resultsDir = path.dirname(resultPath);
+	writeAtomicJson(resultIndexPath(resultsDir, sessionId, runId), entry);
+	const toolCallId = nonEmptyString(data.toolCallId);
+	try {
+		if (toolCallId) writeAtomicJson(toolCallIndexPath(resultsDir, toolCallId, runId), entry);
+	} catch (error) {
+		console.error(`Failed to write async result tool-call index for '${resultPath}':`, error);
+	}
+	try {
+		if (entry.asyncDir && fs.existsSync(path.join(entry.asyncDir, MISSION_BINDING_FILE))) {
+			writeAtomicJson(observerIndexPath(resultsDir, MISSION_OBSERVER, runId), entry);
+		}
+	} catch (error) {
+		console.error(`Failed to write async result observer index for '${resultPath}':`, error);
+	}
+}
+
+function writeIndexedPendingResultFile(resultPath: string, data: Record<string, unknown>): { runId: string; sessionId: string; resultsDir: string } {
+	const runId = nonEmptyString(data.runId) ?? nonEmptyString(data.id) ?? path.basename(resultPath, ".json");
+	const sessionId = nonEmptyString(data.sessionId);
+	if (!sessionId) throw new Error(`Cannot write async result '${resultPath}' without a sessionId.`);
+	const resultsDir = path.dirname(resultPath);
+	writeAtomicJson(resultPendingPath(resultsDir, sessionId, runId), data);
+	writeResultIndexForData(resultPath, data);
+	return { runId, sessionId, resultsDir };
+}
+
+export function writePendingAsyncResultFile(resultPath: string, data: Record<string, unknown>): void {
+	writeIndexedPendingResultFile(resultPath, data);
+}
+
+export function writeAsyncResultFile(resultPath: string, data: Record<string, unknown>): { state: "public" | "pending" } {
+	const { runId, sessionId, resultsDir } = writeIndexedPendingResultFile(resultPath, data);
+	return promotePendingResultFile(resultsDir, sessionId, runId, path.basename(resultPath), { logFailure: false }) === "promoted"
+		? { state: "public" }
+		: { state: "pending" };
+}
+
+export function removeResultIndex(resultsDir: string, sessionId: string | undefined, runId: string | undefined, toolCallId?: string): void {
+	if (!runId) return;
+	if (sessionId) {
+		try {
+			fs.rmSync(resultIndexPath(resultsDir, sessionId, runId), { force: true });
+		} catch {
+			// Index cleanup must not affect result delivery.
+		}
+		try {
+			fs.rmSync(resultPendingPath(resultsDir, sessionId, runId), { force: true });
+		} catch {
+			// Pending cleanup must not affect result delivery.
+		}
+	}
+	if (toolCallId) {
+		try {
+			fs.rmSync(toolCallIndexPath(resultsDir, toolCallId, runId), { force: true });
+		} catch {
+			// Index cleanup must not affect result delivery.
+		}
+	}
+	try {
+		fs.rmSync(observerIndexPath(resultsDir, MISSION_OBSERVER, runId), { force: true });
+	} catch {
+		// Index cleanup must not affect result delivery.
+	}
+}
+
+export function removeMissionObserverIndex(resultsDir: string, runId: string | undefined): void {
+	if (!runId) return;
+	try {
+		fs.rmSync(observerIndexPath(resultsDir, MISSION_OBSERVER, runId), { force: true });
+	} catch {
+		// Observer index cleanup must not affect result delivery.
+	}
+}
+
+function existingResultFile(resultPath: string): boolean {
+	try {
+		return fs.statSync(resultPath).isFile();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Failed to inspect async result payload '${resultPath}':`, error);
+		return false;
+	}
+}
+
+function pendingResultExists(resultsDir: string, sessionId: string, runId: string): boolean {
+	return existingResultFile(resultPendingPath(resultsDir, sessionId, runId));
+}
+
+function pendingResultPayloadMatches(filePath: string, sessionId: string, runId: string): boolean {
+	try {
+		const data = JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<string, unknown>;
+		return (nonEmptyString(data.runId) ?? nonEmptyString(data.id)) === runId && nonEmptyString(data.sessionId) === sessionId;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid pending async result '${filePath}':`, error);
+		return false;
+	}
+}
+
+export function promotePendingResultFile(resultsDir: string, sessionId: string, runId: string, file = resultFileName(runId), options: { logFailure?: boolean } = {}): "none" | "promoted" | "pending" {
+	if (file !== path.basename(file) || !file.endsWith(".json")) return "none";
+	const pendingPath = resultPendingPath(resultsDir, sessionId, runId);
+	if (!existingResultFile(pendingPath)) return "none";
+	const resultPath = path.join(resultsDir, file);
+	try {
+		fs.rmSync(resultPath, { force: true });
+		fs.renameSync(pendingPath, resultPath);
+		return existingResultFile(resultPath) ? "promoted" : "pending";
+	} catch (error) {
+		if (options.logFailure !== false) console.error(`Failed to promote pending async result '${pendingPath}' to '${resultPath}':`, error);
+		return "pending";
+	}
+}
+
+interface ResultPayloadLocation {
+	file: string;
+	path: string;
+	state: "public" | "pending";
+}
+
+function pendingResultLocationForSessionRun(resultsDir: string, sessionId: string, runId: string, file = resultFileName(runId)): ResultPayloadLocation | undefined {
+	if (file !== path.basename(file) || !file.endsWith(".json")) return undefined;
+	const pendingPath = resultPendingPath(resultsDir, sessionId, runId);
+	return existingResultFile(pendingPath) && pendingResultPayloadMatches(pendingPath, sessionId, runId)
+		? { file, path: pendingPath, state: "pending" }
+		: undefined;
+}
+
+function pendingResultLocationForIndexedRun(resultsDir: string, runId: string): ResultPayloadLocation | undefined {
+	const root = path.join(resultsDir, RESULT_PENDING_DIR);
+	let sessions: fs.Dirent[];
+	try {
+		sessions = fs.readdirSync(root, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Failed to inspect pending async result root '${root}':`, error);
+		return undefined;
+	}
+	for (const session of sessions) {
+		if (!session.isDirectory()) continue;
+		let sessionId: string;
+		try {
+			sessionId = decodeURIComponent(session.name);
+		} catch {
+			continue;
+		}
+		const location = pendingResultLocationForSessionRun(resultsDir, sessionId, runId);
+		if (location) return location;
+	}
+	return undefined;
+}
+
+function resultPayloadLocationFromIndex(resultsDir: string, entry: ResultIndexEntry): ResultPayloadLocation | undefined {
+	if (entry.file !== path.basename(entry.file) || !entry.file.endsWith(".json")) return undefined;
+	const pendingState = promotePendingResultFile(resultsDir, entry.sessionId, entry.runId, entry.file);
+	if (pendingState === "pending") {
+		return pendingResultLocationForSessionRun(resultsDir, entry.sessionId, entry.runId, entry.file);
+	}
+	const resultPath = path.join(resultsDir, entry.file);
+	if (pendingState === "promoted" || existingResultFile(resultPath)) return { file: entry.file, path: resultPath, state: "public" };
+	return undefined;
+}
+
+function readResultIndexForSessionRun(resultsDir: string, sessionId: string, runId: string): ResultIndexEntry | undefined {
+	try {
+		const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(resultIndexPath(resultsDir, sessionId, runId), "utf-8")));
+		if (!entry || entry.sessionId !== sessionId || entry.runId !== runId) return undefined;
+		return entry;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code !== "ENOENT" && code !== "ENOTDIR") console.error(`Ignoring invalid async result index for '${runId}':`, error);
+		return undefined;
+	}
+}
+
+export function resultPayloadPathForSessionRun(resultsDir: string, sessionId: string, runId: string): string | undefined {
+	const entry = readResultIndexForSessionRun(resultsDir, sessionId, runId);
+	return (entry ? resultPayloadLocationFromIndex(resultsDir, entry) : undefined)?.path
+		?? pendingResultLocationForSessionRun(resultsDir, sessionId, runId)?.path;
+}
+
+export function resultPayloadPathForMissionObserverRun(resultsDir: string, runId: string): string | undefined {
+	try {
+		const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(observerIndexPath(resultsDir, MISSION_OBSERVER, runId), "utf-8")));
+		if (!entry || entry.runId !== runId) return undefined;
+		return resultPayloadLocationFromIndex(resultsDir, entry)?.path;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid async result observer index for '${runId}':`, error);
+		return undefined;
+	}
+}
+
+export function resultPayloadPathForIndexedRun(resultsDir: string, runId: string): string | undefined {
+	const root = path.join(resultsDir, RESULT_INDEX_DIR, SESSION_INDEX_DIR);
+	let sessions: fs.Dirent[] = [];
+	try {
+		sessions = fs.readdirSync(root, { withFileTypes: true });
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code !== "ENOENT" && code !== "ENOTDIR") console.error(`Failed to inspect async result session index root '${root}':`, error);
+	}
+	for (const session of sessions) {
+		if (!session.isDirectory()) continue;
+		const entryPath = path.join(root, session.name, `${encodeSegment(runId)}.json`);
+		try {
+			const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(entryPath, "utf-8")));
+			if (!entry || entry.runId !== runId) continue;
+			const location = resultPayloadLocationFromIndex(resultsDir, entry);
+			if (location) return location.path;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid async result index '${entryPath}':`, error);
+		}
+	}
+	return pendingResultLocationForIndexedRun(resultsDir, runId)?.path;
+}
+
+function indexedResultFile(resultsDir: string, entry: ResultIndexEntry, includePending = false): string | undefined {
+	const location = resultPayloadLocationFromIndex(resultsDir, entry);
+	if (!location) return undefined;
+	return includePending || location.state === "public" ? location.file : undefined;
+}
+
+function listIndexFiles(dir: string): string[] {
+	let files: string[];
+	try {
+		files = fs.readdirSync(dir, { withFileTypes: true })
+			.filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+			.map((entry) => path.join(dir, entry.name));
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "ENOTDIR") return [];
+		throw error;
+	}
+	return files;
+}
+
+function resultFilesFromIndexDir(resultsDir: string, dir: string, includePending = false): string[] {
+	const candidates = new Set<string>();
+	for (const entryPath of listIndexFiles(dir)) {
+		try {
+			const entry = parseResultIndexEntry(JSON.parse(fs.readFileSync(entryPath, "utf-8")));
+			if (!entry) {
+				fs.rmSync(entryPath, { force: true });
+				continue;
+			}
+			const resultFile = indexedResultFile(resultsDir, entry, includePending);
+			if (resultFile) candidates.add(resultFile);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid async result index '${entryPath}':`, error);
+		}
+	}
+	return [...candidates];
+}
+
+export function resultFilesForSession(resultsDir: string, sessionId: string): string[] {
+	return resultFilesFromIndexDir(resultsDir, sessionIndexDir(resultsDir, sessionId));
+}
+
+function pendingResultFilesForSession(resultsDir: string, sessionId: string): string[] {
+	const dir = path.join(resultsDir, RESULT_PENDING_DIR, encodeSegment(sessionId));
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+		throw error;
+	}
+	const files = new Set<string>();
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+		const pendingPath = path.join(dir, entry.name);
+		try {
+			const data = JSON.parse(fs.readFileSync(pendingPath, "utf-8")) as Record<string, unknown>;
+			const runId = nonEmptyString(data.runId) ?? nonEmptyString(data.id);
+			if (runId && nonEmptyString(data.sessionId) === sessionId) files.add(resultFileName(runId));
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid pending async result '${pendingPath}':`, error);
+		}
+	}
+	return [...files];
+}
+
+export function resultCandidateFilesForSession(resultsDir: string, sessionId: string): string[] {
+	return [...new Set([
+		...resultFilesFromIndexDir(resultsDir, sessionIndexDir(resultsDir, sessionId), true),
+		...pendingResultFilesForSession(resultsDir, sessionId),
+	])];
+}
+
+export function resultFilesForToolCall(resultsDir: string, toolCallId: string): string[] {
+	return resultFilesFromIndexDir(resultsDir, toolCallIndexDir(resultsDir, toolCallId));
+}
+
+export function missionObserverResultFiles(resultsDir: string): string[] {
+	return resultFilesFromIndexDir(resultsDir, observerIndexDir(resultsDir, MISSION_OBSERVER));
+}
+
+export function missionObserverResultCandidateFiles(resultsDir: string): string[] {
+	return resultFilesFromIndexDir(resultsDir, observerIndexDir(resultsDir, MISSION_OBSERVER), true);
+}
+
+export function cleanupResultIndexes(resultsDir: string, now = Date.now(), maxAgeMs = 24 * 60 * 60 * 1000): number {
+	const root = path.join(resultsDir, RESULT_INDEX_DIR);
+	const cutoff = now - maxAgeMs;
+	let removed = 0;
+	const visit = (dir: string): void => {
+		let entries: fs.Dirent[];
+		try {
+			entries = fs.readdirSync(dir, { withFileTypes: true });
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				visit(fullPath);
+				try { fs.rmdirSync(fullPath); } catch {}
+				continue;
+			}
+			if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+			try {
+				const stat = fs.statSync(fullPath);
+				const index = parseResultIndexEntry(JSON.parse(fs.readFileSync(fullPath, "utf-8")));
+				const resultFile = index ? indexedResultFile(resultsDir, index) : undefined;
+				const pendingFile = index ? pendingResultExists(resultsDir, index.sessionId, index.runId) : false;
+				if (!index || (!resultFile && !pendingFile && stat.mtimeMs <= cutoff)) {
+					fs.rmSync(fullPath, { force: true });
+					removed += 1;
+				}
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "ENOENT") console.error(`Ignoring invalid async result index '${fullPath}':`, error);
+				try {
+					fs.rmSync(fullPath, { force: true });
+					removed += 1;
+				} catch {}
+			}
+		}
+	};
+	visit(root);
+	return removed;
+}