@selesai/code 0.8.6 → 0.8.7

package/dist/extensions/pi-subagents/src/runs/shared/completion-guard.ts

@@ -22,6 +22,23 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 const CURSOR_FILE_MUTATION_THINKING =
 	/(?:^|\n)\s*Cursor (?:edit|write)\s*:/i;
 
+const REVIVED_TASK_PREFIX = /^You are reviving a previous subagent conversation\.\n\nOriginal run: .+\nOriginal agent: .+(?:\nOriginal session file: .+)?\n\nUse the stored session context as background\. Answer the orchestrator's follow-up below\. Do not assume the original child process is still alive\.\n\nFollow-up:\n/;
+const IMPLEMENTATION_CHALLENGE_FOLLOW_UP_PATTERN = /^(?:Run )?implementation challenge pass (?:one|two|\d+)(?:\s+and implement any better current[- ]scope change\.?|\s+for the accepted candidate\.\s+Reconsider it and implement any better current[- ]scope change\.?)?$/i;
+const NO_BETTER_CHANGE_NEEDED_PATTERN = /^\s*no (?:better|further|additional) (?:current[- ]scope )?(?:code |source |file )?(?:change|changes|edit|edits|patch|patches) (?:is|are) needed\b/i;
+const KEPT_CURRENT_IMPLEMENTATION_PATTERN = /\b(?:kept (?:the )?current (?:implementation|candidate|shape)|(?:the )?current (?:implementation|candidate|shape) was kept)\b/i;
+const NO_CHANGE_MADE_PATTERN = /\bno (?:new )?(?:(?:code|source|file|test)(?:\s*(?:,\s*or|,|\/|or)\s*(?:code|source|file|test))* changes?|changes?) (?:were|was) made\b/i;
+const NO_BETTER_CHANGE_QUALIFIER_PATTERN = /\b(?:do\s+not|don't|dont|not|never|cannot|can't|cant|unable|uncertain|unsure|unclear|disagree|wrong|false|reject|rejected|rejecting|maybe|might|may|\w+n['’]t)\b/i;
+const REPORT_SENTENCE_PATTERN = /[^.!?]+(?:[.!?]+(?=(?:["”'’]?\s)|["”'’]?$)|$)/g;
+const QUOTED_CLAIM_PATTERN = /["“]([^"”]+)["”]([.!?]?\s*[^.!?]*)/g;
+const QUOTED_CLAIM_REFERENCE_PATTERN = /\b(?:that|this|it|claim|report|message|disagree)\b/i;
+const CLAIM_CONTRADICTION_PATTERN = /\bbut\b[^.!?]*\b(?:uncertain|unsure|unclear|disagree|wrong|false|reject|rejected|rejecting)\b/i;
+const IMPLEMENTATION_RETRACTION_PATTERN = /\b(?:found|identified)\s+(?:(?:a|an|the)\s+)?(?:required|necessary|additional|better)?\s*(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:(?:implementation|code|source|file|test)\s+)?work\s+(?:remains?|is\s+(?:needed|required))\b|\b(?:(?:a|an|the)\s+)?(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\s+(?:are|is)\s+(?:needed|required)\b|\b(?:required|necessary|additional|better)\s+(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:I|we)?\s*need\s+(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:need|needs|require|requires)\s+(?:to\s+)?(?:implement|make|apply)\b/i;
+const IMPLEMENTATION_RETRACTION_GLOBAL_PATTERN = new RegExp(IMPLEMENTATION_RETRACTION_PATTERN.source, "gi");
+const DIRECT_CLAIM_RETRACTION_PATTERN = /^\s*(?:I\s+)?(?:disagree|reject|retract)\b|\b(?:disagree|retract|retracted|retracting|reject|rejected|rejecting)\b[^.!?]*\b(?:that|this|it|claim|report|message)\b|\b(?:that|this|it|claim|report|message)\b[^.!?]*\b(?:is|was)\s+(?:rejected|retracted)\b/i;
+const NEGATED_RETRACTION_PREFIX_PATTERN = /\b(?:no|not|\w+n['’]t)\b(?:\s+\w+){0,2}\s*$/i;
+const REPORTED_CLAIM_PREFIX_PATTERN = /["“]|\b(?:prior|previous)\s+(?:message|report)\b|\b(?:said|stated|reported)\b/i;
+const POST_CLAIM_SEPARATOR_PATTERN = /^[\s,;:.—–'"“‘’-]+/;
+
 interface CompletionMutationGuardInput {
 	agent: string;
 	task: string;
@@ -36,6 +53,11 @@ interface CompletionMutationGuardResult {
 	triggered: boolean;
 }
 
+interface ReportSentence {
+	text: string;
+	offset: number;
+}
+
 export function hasMutationToolCapability(tools: string[] | undefined, mcpDirectTools: string[] | undefined): boolean {
 	if ((mcpDirectTools?.length ?? 0) > 0) return true;
 	if (tools === undefined) return true;
@@ -82,14 +104,98 @@ export function hasMutationToolCall(messages: Message[]): boolean {
 	return false;
 }
 
+function hasImplementationRetraction(text: string): boolean {
+	return Array.from(text.matchAll(IMPLEMENTATION_RETRACTION_GLOBAL_PATTERN)).some((retraction) =>
+		!NEGATED_RETRACTION_PREFIX_PATTERN.test(text.slice(0, retraction.index!)));
+}
+
+function hasDirectClaimRetraction(text: string): boolean {
+	return DIRECT_CLAIM_RETRACTION_PATTERN.test(text.replace(POST_CLAIM_SEPARATOR_PATTERN, ""));
+}
+
+function isInsideQuotedText(report: string, index: number): boolean {
+	let quote: "double" | "single" | undefined;
+	for (const char of report.slice(0, index)) {
+		if (quote === "double") {
+			if (char === "\"" || char === "”") quote = undefined;
+		} else if (quote === "single") {
+			if (char === "’") quote = undefined;
+		} else if (char === "\"" || char === "“") {
+			quote = "double";
+		} else if (char === "‘") {
+			quote = "single";
+		}
+	}
+	return quote !== undefined;
+}
+
+function unqualifiedClaimIndex(report: string, sentences: ReportSentence[], pattern: RegExp): number {
+	return sentences.findIndex((sentence) => {
+		const claim = sentence.text.match(pattern);
+		if (claim === null) return false;
+		const before = sentence.text.slice(0, claim.index!);
+		const after = sentence.text.slice(claim.index! + claim[0].length);
+		const previous = before.trimEnd().at(-1);
+		return previous !== "'"
+			&& previous !== "‘"
+			&& !isInsideQuotedText(report, sentence.offset + claim.index!)
+			&& !REPORTED_CLAIM_PREFIX_PATTERN.test(before)
+			&& !NO_BETTER_CHANGE_QUALIFIER_PATTERN.test(before)
+			&& !CLAIM_CONTRADICTION_PATTERN.test(after)
+			&& !hasImplementationRetraction(after)
+			&& !hasDirectClaimRetraction(after);
+	});
+}
+
+function hasLaterClaimRetraction(sentences: ReportSentence[], claimIndex: number): boolean {
+	return sentences.slice(claimIndex + 1).some((sentence) => hasImplementationRetraction(sentence.text)
+		|| hasDirectClaimRetraction(sentence.text));
+}
+
+function explicitlyRejectsQuotedClaim(report: string): boolean {
+	for (const [, claim, response] of report.matchAll(QUOTED_CLAIM_PATTERN)) {
+		if ((KEPT_CURRENT_IMPLEMENTATION_PATTERN.test(claim!) || NO_CHANGE_MADE_PATTERN.test(claim!))
+			&& NO_BETTER_CHANGE_QUALIFIER_PATTERN.test(response!)
+			&& QUOTED_CLAIM_REFERENCE_PATTERN.test(response!)) return true;
+	}
+	return false;
+}
+
+function isImplementationChallengeTask(task: string): boolean {
+	const followUp = task.replace(REVIVED_TASK_PREFIX, "");
+	return followUp !== task && IMPLEMENTATION_CHALLENGE_FOLLOW_UP_PATTERN.test(followUp.trim());
+}
+
+function reportsNoBetterChallengeChange(messages: Message[]): boolean {
+	const report = messages
+		.filter((message) => message.role === "assistant")
+		.flatMap((message) => message.content)
+		.flatMap((part) => part.type === "text" ? [part.text] : [])
+		.join("\n");
+	if (explicitlyRejectsQuotedClaim(report)) return false;
+	const sentences = Array.from(report.matchAll(REPORT_SENTENCE_PATTERN), (match) => ({
+		text: match[0],
+		offset: match.index!,
+	}));
+	const noBetterIndex = unqualifiedClaimIndex(report, sentences, NO_BETTER_CHANGE_NEEDED_PATTERN);
+	if (noBetterIndex >= 0) return !hasLaterClaimRetraction(sentences, noBetterIndex);
+	const keptIndex = unqualifiedClaimIndex(report, sentences, KEPT_CURRENT_IMPLEMENTATION_PATTERN);
+	const noChangeIndex = unqualifiedClaimIndex(report, sentences, NO_CHANGE_MADE_PATTERN);
+	return keptIndex >= 0
+		&& noChangeIndex >= 0
+		&& !hasLaterClaimRetraction(sentences, Math.min(keptIndex, noChangeIndex));
+}
+
 export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
 	const expectedMutation = hasMutationToolCapability(input.tools, input.mcpDirectTools)
 		? expectsImplementationMutation(input.agent, input.task)
 		: false;
 	const attemptedMutation = hasMutationToolCall(input.messages);
+	const noEditChallengeComplete = isImplementationChallengeTask(input.task)
+		&& reportsNoBetterChallengeChange(input.messages);
 	return {
 		expectedMutation,
 		attemptedMutation,
-		triggered: expectedMutation && !attemptedMutation,
+		triggered: expectedMutation && !attemptedMutation && !noEditChallengeComplete,
 	};
 }

package/dist/extensions/pi-subagents/src/runs/shared/external-cli-runner.ts

@@ -35,6 +35,8 @@ export function runExternalCli(input: {
 	timeoutMessage?: string;
 	stopMessage?: string;
 	onProcess?: (process: ExternalProcessStatus) => void;
+	onStdout?: (chunk: Buffer) => void;
+	onStderr?: (chunk: Buffer) => void;
 }): Promise<ExternalCliRunResult> {
 	return new Promise((resolve, reject) => {
 		const startedAt = Date.now();
@@ -65,11 +67,13 @@ export function runExternalCli(input: {
 		input.onProcess?.(initialProcess);
 		child.stdout.on("data", (chunk: Buffer) => {
 			stdoutStream.write(chunk);
+			input.onStdout?.(chunk);
 			stdoutTail = Buffer.concat([stdoutTail, chunk]);
 			if (stdoutTail.length > MAX_OUTPUT_TAIL_BYTES) stdoutTail = stdoutTail.subarray(stdoutTail.length - MAX_OUTPUT_TAIL_BYTES);
 		});
 		child.stderr.on("data", (chunk: Buffer) => {
 			stderrStream.write(chunk);
+			input.onStderr?.(chunk);
 			stderrTail = Buffer.concat([stderrTail, chunk]);
 			if (stderrTail.length > MAX_ERROR_TAIL_BYTES) stderrTail = stderrTail.subarray(stderrTail.length - MAX_ERROR_TAIL_BYTES);
 		});

package/dist/extensions/pi-subagents/src/runs/shared/llm-intent-arbiter.ts

@@ -2,7 +2,9 @@ import { createHash } from "node:crypto";
 import { Agent, type AgentTool, type StreamFn } from "@earendil-works/pi-agent-core";
 import { convertToLlm, type ExtensionContext } from "@selesai/code";
 import { streamSimple } from "@earendil-works/pi-ai/compat";
+import type { ProviderHeaders } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
+import { agentStreamOptions } from "../../shared/agent-stream-options.ts";
 
 /**
  * LLM intent arbiter for the completion mutation guard.
@@ -28,6 +30,10 @@ export type TaskMutationArbiter = (task: string) => Promise<TaskMutationVerdict>
 const DecisionParams = Type.Object(
 	{
 		classification: Type.String({ enum: ["read_only", "implementation"] }),
+		confidence: Type.String({
+			enum: ["low", "medium", "high"],
+			description: "Confidence in the classification. Only read_only with high confidence rescues a failed run.",
+		}),
 		reason: Type.String({ description: "One concise reason for this classification." }),
 	},
 	{ additionalProperties: false },
@@ -35,6 +41,15 @@ const DecisionParams = Type.Object(
 
 type DecisionParams = Static<typeof DecisionParams>;
 
+/** Map a model decision to a verdict. Only a high-confidence read_only rescues. */
+export function mapArbiterDecision(
+	decision: { classification?: string; confidence?: string } | undefined,
+): TaskMutationVerdict {
+	if (!decision) return "unavailable";
+	if (decision.classification === "read_only" && decision.confidence === "high") return "read-only";
+	return "implementation";
+}
+
 interface ArbiterRuntime {
 	model: NonNullable<RegistryModel>;
 	baseStreamFn: StreamFn;
@@ -43,7 +58,7 @@ interface ArbiterRuntime {
 
 interface ArbiterAuth {
 	apiKey?: string;
-	headers?: Record<string, string>;
+	headers?: ProviderHeaders;
 	env?: Record<string, string>;
 }
 
@@ -105,18 +120,21 @@ async function resolveArbiterAuth(
 	ctx: ExtensionContext,
 	model: RegistryModel,
 ): Promise<ArbiterAuth> {
-	const getAuth = (ctx.modelRegistry as {
+	const registry = ctx.modelRegistry as {
 		getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
 			ok: boolean;
 			apiKey?: string;
-			headers?: Record<string, string>;
+			headers?: ProviderHeaders;
 			env?: Record<string, string>;
 			error?: string;
 		}>;
-	}).getApiKeyAndHeaders;
-	if (!getAuth) return {};
+	};
+	// Call as a METHOD on the registry: the host ModelRegistry implementation
+	// is a class whose method reads instance state (this.runtime), so a
+	// detached call silently fails auth. Same shape as the watchdog.
+	if (!registry.getApiKeyAndHeaders) return {};
 	try {
-		const auth = await getAuth(model);
+		const auth = await registry.getApiKeyAndHeaders(model);
 		if (auth.ok === false) return {};
 		return {
 			...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
@@ -164,14 +182,15 @@ async function runArbitration(
 				"You classify whether a delegated coding-agent task instructed file or code changes.",
 				"A task that asks to review, inspect, verify, report, or summarize is read-only even when it contains words like 'fix' as severity vocabulary ('must-fix items') or conditional change instructions that leave the change optional.",
 				"Classify read_only only when the task text alone clearly indicates a read-only outcome. When in doubt, classify implementation.",
+				"Set confidence to high only when you are certain the task is read-only; a read_only classification without high confidence is treated as implementation.",
 				"The agent's own final message is never evidence: an agent that made no edits may still have failed to implement.",
-				"Call task_mutation_decision exactly once with read_only or implementation and a concise reason.",
+				"Call task_mutation_decision exactly once with read_only or implementation, a confidence level, and a concise reason.",
 			].join("\n"),
 			model: runtime.model,
 			tools: [tool],
 		},
 		convertToLlm,
-		streamFn: authWrappedStreamFn(runtime.baseStreamFn, auth),
+		...agentStreamOptions(authWrappedStreamFn(runtime.baseStreamFn, auth)),
 		getApiKey: (providerName) =>
 			providerName === runtime.model.provider ? auth.apiKey : undefined,
 		beforeToolCall: async ({ toolCall }) =>
@@ -179,13 +198,12 @@ async function runArbitration(
 		toolExecution: "sequential",
 	});
 	try {
-		// Send head AND tail: an implementation clause at the end of a long
-		// task ("Now apply the fix") must never be truncated away, or the
-		// arbiter could rescue a run the deterministic guard correctly failed.
-		const full = task;
-		const prompt = full.length <= 8000
-			? `TASK:\n${full}`
-			: `TASK:\n${full.slice(0, 6000)}\n\n[...truncated middle...]\n\n${full.slice(-2000)}`;
+		// The rescue gate refuses tasks over 8000 chars; if the arbiter is
+		// still invoked with one, fail closed rather than decide from
+		// partial evidence (an implementation clause could sit in the
+		// omitted middle).
+		if (task.length > 8000) return "unavailable";
+		const prompt = `TASK:\n${task}`;
 		await Promise.race([
 			agent.prompt(prompt),
 			new Promise<never>((_, reject) => {
@@ -197,7 +215,7 @@ async function runArbitration(
 			}),
 		]);
 		if (!decision) return "unavailable";
-		return decision.classification === "read_only" ? "read-only" : "implementation";
+		return mapArbiterDecision(decision);
 	} catch {
 		return "unavailable";
 	}
@@ -228,13 +246,6 @@ export function isCompletionGuardFailure(result: { error?: string }): boolean {
 	return result.error?.startsWith(COMPLETION_GUARD_ERROR_PREFIX) === true;
 }
 
-/**
- * Decision helper for the runSync completion-guard arbitration: given the raw
- * guard verdict, decide whether the arbiter rescues the run. Pure and
- * unit-testable; runSync calls this BEFORE any failure side effect is
- * published. Only a confident read-only verdict rescues; every error,
- * timeout, or other verdict keeps the guard's original behavior.
- */
 export async function arbitrateCompletionGuardRescue(input: {
 	guardTriggered: boolean;
 	task: string;
@@ -243,6 +254,11 @@ export async function arbitrateCompletionGuardRescue(input: {
 	if (!input.guardTriggered || !input.arbiter) {
 		return { triggered: input.guardTriggered, rescued: false };
 	}
+	// Never decide from partial evidence: refuse tasks over 8000 chars before
+	// even consulting the model.
+	if (input.task.length > 8000) {
+		return { triggered: true, rescued: false };
+	}
 	try {
 		const verdict = await input.arbiter(input.task);
 		if (verdict === "read-only") return { triggered: false, rescued: true };

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

@@ -163,6 +163,20 @@ export function resolveModelCandidate(
 	return model;
 }
 
+function resolveRequiredSubagentModelCandidate(
+	model: string,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string {
+	if (!availableModels || availableModels.length === 0) return model;
+	const resolvedWhole = resolveBaseModelCandidate(model, availableModels, preferredProvider);
+	if (resolvedWhole) return resolvedWhole;
+	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
+	const resolvedBase = thinkingSuffix ? resolveBaseModelCandidate(baseModel, availableModels, preferredProvider) : undefined;
+	if (resolvedBase) return `${resolvedBase}${thinkingSuffix}`;
+	throw new Error(`Unknown subagent model '${model}' in the active Pi model registry.`);
+}
+
 export interface ResolveSubagentModelOverrideOptions {
 	/** When set with `enforce: true`, out-of-scope models are rejected. */
 	scope?: ModelScopeConfig;
@@ -207,7 +221,7 @@ export function resolveSubagentModelOverride(
 	if (explicit === undefined) {
 		resolved = parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
 	} else {
-		resolved = resolveModelCandidate(explicit, availableModels, preferredProvider);
+		resolved = resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
 	}
 	if (resolved && options?.scope?.enforce) {
 		const source: ModelSource = explicit === undefined ? "inherited" : (options.source ?? "inherited");
@@ -264,7 +278,7 @@ export function buildModelCandidates(
 	for (let index = 0; index < rawCandidates.length; index++) {
 		const raw = rawCandidates[index];
 		if (!raw) continue;
-		const normalized = resolveModelCandidate(raw.trim(), availableModels, preferredProvider);
+		const normalized = resolveRequiredSubagentModelCandidate(raw.trim(), availableModels, preferredProvider);
 		if (!normalized || seen.has(normalized)) continue;
 		if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
 			const violation = checkModelScope(normalized, options.scope, "inherited");

package/dist/extensions/pi-subagents/src/runs/shared/nested-events.ts

@@ -34,6 +34,7 @@ import { THINKING_LEVELS } from "../../shared/model-info.ts";
 export const NESTED_EVENTS_DIR = path.join(TEMP_ROOT_DIR, "nested-subagent-events");
 const ROUTE_FILE = "route.json";
 const REGISTRY_FILE = "registry.json";
+const ROUTE_INDEX_DIR = ".route-index";
 const MAX_EVENT_BYTES = 64 * 1024;
 const MAX_STEPS = 12;
 const MAX_CHILDREN = 16;
@@ -105,6 +106,18 @@ function commonRouteRoot(route: Pick<NestedRoute, "eventSink" | "controlInbox">)
 	return path.dirname(path.resolve(route.eventSink));
 }
 
+function routeIndexRoot(): string {
+	return path.join(NESTED_EVENTS_DIR, ROUTE_INDEX_DIR, "roots");
+}
+
+function routeIndexDir(rootRunId: string): string {
+	return path.join(routeIndexRoot(), encodeURIComponent(rootRunId));
+}
+
+function routeIndexPath(rootRunId: string, capabilityToken: string): string {
+	return path.join(routeIndexDir(rootRunId), `${encodeURIComponent(capabilityToken)}.json`);
+}
+
 function validateRouteShape(route: NestedRoute): void {
 	assertSafeId("rootRunId", route.rootRunId);
 	assertSafeId("capabilityToken", route.capabilityToken);
@@ -121,7 +134,10 @@ export function createNestedRoute(rootRunId: string): NestedRoute {
 	const controlInbox = path.join(routeRoot, "controls");
 	fs.mkdirSync(eventSink, { recursive: true, mode: 0o700 });
 	fs.mkdirSync(controlInbox, { recursive: true, mode: 0o700 });
-	fs.writeFileSync(path.join(routeRoot, ROUTE_FILE), `${JSON.stringify({ rootRunId, capabilityToken, createdAt: Date.now() })}\n`, { mode: 0o600 });
+	const createdAt = Date.now();
+	fs.mkdirSync(routeIndexDir(rootRunId), { recursive: true, mode: 0o700 });
+	writeAtomicJson(routeIndexPath(rootRunId, capabilityToken), { rootRunId, capabilityToken, routeRoot: path.basename(routeRoot), createdAt });
+	writeAtomicJson(path.join(routeRoot, ROUTE_FILE), { rootRunId, capabilityToken, createdAt });
 	return { rootRunId, eventSink, controlInbox, capabilityToken };
 }
 
@@ -515,68 +531,57 @@ function registryPath(route: NestedRoute): string {
 	return path.join(commonRouteRoot(route), REGISTRY_FILE);
 }
 
+function routeFromIndexEntry(rootRunId: string, filePath: string): NestedRoute | undefined {
+	try {
+		const metadata = JSON.parse(fs.readFileSync(filePath, "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown; routeRoot?: unknown; createdAt?: unknown };
+		if (metadata.rootRunId !== rootRunId || typeof metadata.capabilityToken !== "string" || typeof metadata.routeRoot !== "string") return undefined;
+		const routeRoot = path.join(NESTED_EVENTS_DIR, path.basename(metadata.routeRoot));
+		const route = {
+			rootRunId,
+			eventSink: path.join(routeRoot, "events"),
+			controlInbox: path.join(routeRoot, "controls"),
+			capabilityToken: metadata.capabilityToken,
+		};
+		validateRouteShape(route);
+		if (!fs.statSync(route.eventSink).isDirectory() || !fs.statSync(route.controlInbox).isDirectory()) return undefined;
+		const routeFilePath = path.join(routeRoot, ROUTE_FILE);
+		try {
+			const routeFile = JSON.parse(fs.readFileSync(routeFilePath, "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
+			if (routeFile.rootRunId !== rootRunId || routeFile.capabilityToken !== metadata.capabilityToken) return undefined;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") return undefined;
+			try {
+				writeAtomicJson(routeFilePath, { rootRunId, capabilityToken: metadata.capabilityToken, createdAt: typeof metadata.createdAt === "number" ? metadata.createdAt : Date.now() });
+			} catch {
+				// The route index already carries enough data for reload lookup.
+			}
+		}
+		return route;
+	} catch {
+		return undefined;
+	}
+}
+
 export function findNestedRouteForRootId(rootRunId: string): NestedRoute | undefined {
 	assertSafeId("rootRunId", rootRunId);
 	let entries: string[];
 	try {
-		entries = fs.readdirSync(NESTED_EVENTS_DIR);
+		entries = fs.readdirSync(routeIndexDir(rootRunId));
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
 		throw error;
 	}
 	for (const entry of entries) {
-		if (!entry.startsWith(`${rootRunId}-`)) continue;
-		const routeRoot = path.join(NESTED_EVENTS_DIR, entry);
-		try {
-			const metadata = JSON.parse(fs.readFileSync(path.join(routeRoot, ROUTE_FILE), "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
-			if (metadata.rootRunId !== rootRunId || typeof metadata.capabilityToken !== "string") continue;
-			const route = {
-				rootRunId,
-				eventSink: path.join(routeRoot, "events"),
-				controlInbox: path.join(routeRoot, "controls"),
-				capabilityToken: metadata.capabilityToken,
-			};
-			validateRouteShape(route);
-			return route;
-		} catch {
-			continue;
-		}
+		const route = routeFromIndexEntry(rootRunId, path.join(routeIndexDir(rootRunId), entry));
+		if (route) return route;
 	}
 	return undefined;
 }
 
-/**
- * Scan the nested-events directory once and index every route by its root run
- * id. Use this when resolving routes for many runs (e.g. listAsyncRuns) so the
- * cost is O(routes) total instead of O(runs * routes) from calling
- * findNestedRouteForRootId per run.
- */
 export function buildNestedRouteIndex(): Map<string, NestedRoute> {
-	let entries: string[];
-	try {
-		entries = fs.readdirSync(NESTED_EVENTS_DIR);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return new Map();
-		throw error;
-	}
 	const index = new Map<string, NestedRoute>();
-	for (const entry of entries) {
-		const routeRoot = path.join(NESTED_EVENTS_DIR, entry);
-		try {
-			const metadata = JSON.parse(fs.readFileSync(path.join(routeRoot, ROUTE_FILE), "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
-			if (typeof metadata.rootRunId !== "string" || typeof metadata.capabilityToken !== "string") continue;
-			if (index.has(metadata.rootRunId)) continue;
-			const route: NestedRoute = {
-				rootRunId: metadata.rootRunId,
-				eventSink: path.join(routeRoot, "events"),
-				controlInbox: path.join(routeRoot, "controls"),
-				capabilityToken: metadata.capabilityToken,
-			};
-			validateRouteShape(route);
-			index.set(metadata.rootRunId, route);
-		} catch {
-			continue;
-		}
+	for (const route of listNestedRoutes()) {
+		if (!index.has(route.rootRunId)) index.set(route.rootRunId, route);
 	}
 	return index;
 }
@@ -630,27 +635,26 @@ function collectScopedNestedRuns(children: NestedRunSummary[] | undefined, scope
 }
 
 function listNestedRoutes(): NestedRoute[] {
-	let entries: string[];
+	let rootEntries: string[];
 	try {
-		entries = fs.readdirSync(NESTED_EVENTS_DIR);
+		rootEntries = fs.readdirSync(routeIndexRoot());
 	} catch (error) {
 		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
 		throw error;
 	}
 	const routes: NestedRoute[] = [];
-	for (const entry of entries) {
-		const routeRoot = path.join(NESTED_EVENTS_DIR, entry);
+	for (const rootEntry of rootEntries) {
+		let rootRunId: string;
 		try {
-			const metadata = JSON.parse(fs.readFileSync(path.join(routeRoot, ROUTE_FILE), "utf-8")) as { rootRunId?: unknown; capabilityToken?: unknown };
-			if (typeof metadata.rootRunId !== "string" || typeof metadata.capabilityToken !== "string") continue;
-			const route = {
-				rootRunId: metadata.rootRunId,
-				eventSink: path.join(routeRoot, "events"),
-				controlInbox: path.join(routeRoot, "controls"),
-				capabilityToken: metadata.capabilityToken,
-			};
-			validateRouteShape(route);
-			routes.push(route);
+			rootRunId = decodeURIComponent(rootEntry);
+		} catch {
+			continue;
+		}
+		try {
+			for (const entry of fs.readdirSync(path.join(routeIndexRoot(), rootEntry))) {
+				const route = routeFromIndexEntry(rootRunId, path.join(routeIndexRoot(), rootEntry, entry));
+				if (route) routes.push(route);
+			}
 		} catch {
 			continue;
 		}