pi-subagents 0.49.0 → 0.51.0

package/src/runs/shared/external-job-runner.ts

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ExternalJobProviderError, type ExternalJobHandle, type ExternalJobResult, type ExternalJobState } from "../../api/external-job-provider.ts";
+import type { ExternalJobStatus } from "../../shared/types.ts";
+import { requestExternalJobOperation } from "./external-job-bridge.ts";
+
+const STATUS_POLL_INTERVAL_MS = 1_000;
+
+export interface ExternalJobRunResult {
+	output: string;
+	exitCode: number;
+	error?: string;
+	timedOut?: boolean;
+	stopped?: boolean;
+	externalJob: ExternalJobStatus;
+}
+
+export function externalJobPromptDigest(prompt: string): string {
+	return createHash("sha256").update(prompt).digest("hex");
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function terminal(state: ExternalJobState): boolean {
+	return state === "completed" || state === "failed" || state === "stopped" || state === "blocked";
+}
+
+function formatError(error: ExternalJobProviderError, provider: string): string {
+	const blocking = error.blockingJobId ? ` Blocking provider job: ${error.blockingJobId}.` : "";
+	return `External-job provider '${provider}' failed closed (${error.code}): ${error.message}.${blocking}`;
+}
+
+function isNotFound(error: unknown): boolean {
+	return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function malformedStatus(statusPath: string): ExternalJobProviderError {
+	return new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable" });
+}
+
+function parseExternalJobStatus(value: unknown, statusPath: string): ExternalJobStatus {
+	if (!isRecord(value)) throw malformedStatus(statusPath);
+	const provider = value.provider;
+	const promptDigest = value.promptDigest;
+	const state = value.state;
+	if (typeof provider !== "string" || provider.length === 0) throw malformedStatus(statusPath);
+	if (typeof promptDigest !== "string" || promptDigest.length === 0) throw malformedStatus(statusPath);
+	if (state !== "queued" && state !== "running" && state !== "completed" && state !== "failed" && state !== "stopped" && state !== "blocked") throw malformedStatus(statusPath);
+	if (value.options !== undefined && !isRecord(value.options)) throw malformedStatus(statusPath);
+	const providerJobId = value.providerJobId;
+	const handleUrl = value.handleUrl;
+	const conversationUrl = value.conversationUrl;
+	const resultArtifactPath = value.resultArtifactPath;
+	const failureCode = value.failureCode;
+	const failureMessage = value.failureMessage;
+	const blockingJobId = value.blockingJobId;
+	const startedAt = value.startedAt;
+	const updatedAt = value.updatedAt;
+	if (providerJobId !== undefined && (typeof providerJobId !== "string" || providerJobId.length === 0)) throw malformedStatus(statusPath);
+	if (handleUrl !== undefined && typeof handleUrl !== "string") throw malformedStatus(statusPath);
+	if (conversationUrl !== undefined && typeof conversationUrl !== "string") throw malformedStatus(statusPath);
+	if (resultArtifactPath !== undefined && typeof resultArtifactPath !== "string") throw malformedStatus(statusPath);
+	if (failureCode !== undefined && typeof failureCode !== "string") throw malformedStatus(statusPath);
+	if (failureMessage !== undefined && typeof failureMessage !== "string") throw malformedStatus(statusPath);
+	if (blockingJobId !== undefined && typeof blockingJobId !== "string") throw malformedStatus(statusPath);
+	if (startedAt !== undefined && typeof startedAt !== "number") throw malformedStatus(statusPath);
+	if (updatedAt !== undefined && typeof updatedAt !== "number") throw malformedStatus(statusPath);
+	return {
+		provider,
+		promptDigest,
+		options: value.options ?? {},
+		state,
+		...(providerJobId ? { providerJobId } : {}),
+		...(handleUrl ? { handleUrl } : {}),
+		...(conversationUrl ? { conversationUrl } : {}),
+		...(resultArtifactPath ? { resultArtifactPath } : {}),
+		...(failureCode ? { failureCode } : {}),
+		...(failureMessage ? { failureMessage } : {}),
+		...(blockingJobId ? { blockingJobId } : {}),
+		...(startedAt !== undefined ? { startedAt } : {}),
+		...(updatedAt !== undefined ? { updatedAt } : {}),
+	};
+}
+
+function readExistingExternalJob(asyncDir: string, stepIndex: number): ExternalJobStatus | undefined {
+	const statusPath = path.join(asyncDir, "status.json");
+	let raw: string;
+	try {
+		raw = fs.readFileSync(statusPath, "utf-8");
+	} catch (error) {
+		if (isNotFound(error)) return undefined;
+		throw new ExternalJobProviderError(`Unreadable external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		throw new ExternalJobProviderError(`Malformed external-job status '${statusPath}'. Refusing to redispatch the prompt.`, { code: "status-unreadable", cause: error });
+	}
+	if (!isRecord(parsed) || !Array.isArray(parsed.steps)) throw malformedStatus(statusPath);
+	const step = parsed.steps[stepIndex];
+	if (step === undefined || !isRecord(step)) throw malformedStatus(statusPath);
+	if (step.externalJob === undefined) return undefined;
+	return parseExternalJobStatus(step.externalJob, statusPath);
+}
+
+function statusFromHandle(input: {
+	provider: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	startedAt?: number;
+	previous?: ExternalJobStatus;
+	handle: ExternalJobHandle;
+	resultArtifactPath?: string;
+}): ExternalJobStatus {
+	return {
+		provider: input.provider,
+		providerJobId: input.handle.providerJobId,
+		promptDigest: input.promptDigest,
+		options: input.options,
+		handleUrl: input.handle.handleUrl ?? input.previous?.handleUrl,
+		conversationUrl: input.handle.conversationUrl ?? input.previous?.conversationUrl,
+		resultArtifactPath: input.resultArtifactPath ?? input.previous?.resultArtifactPath,
+		state: input.handle.state,
+		failureCode: input.handle.failureCode,
+		failureMessage: input.handle.failureMessage,
+		blockingJobId: input.handle.blockingJobId,
+		startedAt: input.previous?.startedAt ?? input.startedAt,
+		updatedAt: Date.now(),
+	};
+}
+
+function failureStatus(input: {
+	provider: string;
+	promptDigest: string;
+	options: Record<string, unknown>;
+	previous?: ExternalJobStatus;
+	code: string;
+	message: string;
+	blockingJobId?: string;
+}): ExternalJobStatus {
+	return {
+		provider: input.provider,
+		providerJobId: input.previous?.providerJobId,
+		promptDigest: input.promptDigest,
+		options: input.options,
+		handleUrl: input.previous?.handleUrl,
+		conversationUrl: input.previous?.conversationUrl,
+		resultArtifactPath: input.previous?.resultArtifactPath,
+		state: input.blockingJobId ? "blocked" : "failed",
+		failureCode: input.code,
+		failureMessage: input.message,
+		blockingJobId: input.blockingJobId,
+		startedAt: input.previous?.startedAt,
+		updatedAt: Date.now(),
+	};
+}
+
+function resultOutput(result: ExternalJobResult, artifactPath: string | undefined): string {
+	if (result.output?.trim()) return result.output.trim();
+	if (artifactPath) return `External job finished. Result artifact: ${artifactPath}`;
+	return "External job finished without text output.";
+}
+
+function blocksStartRedispatch(status: ExternalJobStatus, provider: string, promptDigest: string): boolean {
+	return status.provider === provider
+		&& status.promptDigest === promptDigest
+		&& !status.providerJobId
+		&& status.failureCode !== "provider-unavailable";
+}
+
+export async function runExternalJob(input: {
+	provider: string;
+	options?: Record<string, unknown>;
+	cwd: string;
+	prompt: string;
+	asyncDir: string;
+	stepIndex: number;
+	runId: string;
+	agent: string;
+	sessionId?: string;
+	registerTimeout?: (stop: (() => void) | undefined) => void;
+	registerStop?: (stop: (() => void) | undefined) => void;
+	timeoutMessage?: string;
+	stopMessage?: string;
+	onExternalJob?: (status: ExternalJobStatus) => void;
+}): Promise<ExternalJobRunResult> {
+	const provider = input.provider;
+	const options = input.options ?? {};
+	const promptDigest = externalJobPromptDigest(input.prompt);
+	const startedAt = Date.now();
+	let timedOut = false;
+	let stopped = false;
+	let current: ExternalJobStatus | undefined;
+	const timeout = () => { timedOut = true; };
+	const stop = () => { stopped = true; };
+	input.registerTimeout?.(timeout);
+	input.registerStop?.(stop);
+	const publish = (status: ExternalJobStatus) => {
+		current = status;
+		input.onExternalJob?.(status);
+	};
+	const localCancellation = () => {
+		if (!timedOut && !stopped) return undefined;
+		const message = stopped
+			? input.stopMessage ?? `Subagent stopped locally before external provider '${provider}' returned a job id. The provider start may still be running.`
+			: input.timeoutMessage ?? `Subagent timed out locally before external provider '${provider}' returned a job id. The provider start may still be running.`;
+		return new ExternalJobProviderError(message, { code: stopped ? "local-stop" : "local-timeout" });
+	};
+	try {
+		current = readExistingExternalJob(input.asyncDir, input.stepIndex);
+		let handle: ExternalJobHandle;
+		if (current?.providerJobId) {
+			if (current.provider !== provider || current.promptDigest !== promptDigest) {
+				const message = `Existing external job '${current.providerJobId}' does not match provider or prompt digest. Refusing to redispatch prompt.`;
+				const status = failureStatus({ provider, promptDigest, options, previous: current, code: "recovery-mismatch", message });
+				publish(status);
+				return { output: message, exitCode: 1, error: message, externalJob: status };
+			}
+			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "reattach", provider, providerJobId: current.providerJobId });
+		} else {
+			if (current && blocksStartRedispatch(current, provider, promptDigest)) {
+				const message = `External-job start for provider '${provider}' previously ended without a durable provider job id. Refusing to redispatch the prompt automatically.`;
+				const status = failureStatus({ provider, promptDigest, options, previous: current, code: "start-redispatch-blocked", message });
+				publish(status);
+				return { output: message, exitCode: 1, error: message, externalJob: status };
+			}
+			publish({ provider, promptDigest, options, state: "queued", startedAt, updatedAt: Date.now() });
+				handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, {
+				operation: "start",
+				provider,
+				start: {
+					prompt: input.prompt,
+					promptDigest,
+					cwd: input.cwd,
+					runId: input.runId,
+					stepIndex: input.stepIndex,
+					agent: input.agent,
+					options,
+					...(input.sessionId ? { sessionId: input.sessionId } : {}),
+				},
+			}, undefined, localCancellation);
+		}
+		publish(statusFromHandle({ provider, promptDigest, options, startedAt, previous: current, handle }));
+		while (!terminal(handle.state)) {
+			if (timedOut || stopped) {
+				const message = stopped
+					? input.stopMessage ?? `Subagent stopped locally; external provider job '${handle.providerJobId}' may still be running.`
+					: input.timeoutMessage ?? `Subagent timed out locally; external provider job '${handle.providerJobId}' may still be running.`;
+				return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: current! };
+			}
+			await sleep(STATUS_POLL_INTERVAL_MS);
+			handle = await requestExternalJobOperation<ExternalJobHandle>(input.asyncDir, { operation: "status", provider, providerJobId: handle.providerJobId });
+			publish(statusFromHandle({ provider, promptDigest, options, previous: current, handle }));
+		}
+		const result = await requestExternalJobOperation<ExternalJobResult>(input.asyncDir, { operation: "result", provider, providerJobId: handle.providerJobId });
+		let artifactPath = result.artifactPath;
+		if (!artifactPath && result.output !== undefined) {
+			artifactPath = path.join(input.asyncDir, `external-job-${input.stepIndex}.result.md`);
+			fs.writeFileSync(artifactPath, result.output, "utf-8");
+		}
+		const finalStatus = statusFromHandle({ provider, promptDigest, options, previous: current, handle: result, resultArtifactPath: artifactPath });
+		publish(finalStatus);
+		const output = resultOutput(result, artifactPath);
+		const error = result.state === "completed" ? undefined : result.failureMessage ?? `External job ${result.state}.`;
+		return { output, exitCode: result.state === "completed" ? 0 : 1, ...(error ? { error } : {}), externalJob: finalStatus };
+	} catch (error) {
+		const providerError = error instanceof ExternalJobProviderError
+			? error
+			: new ExternalJobProviderError(error instanceof Error ? error.message : String(error), { code: "provider-error", cause: error });
+		const message = formatError(providerError, provider);
+		const status = failureStatus({ provider, promptDigest, options, previous: current, code: providerError.code, message, ...(providerError.blockingJobId ? { blockingJobId: providerError.blockingJobId } : {}) });
+		publish(status);
+		return { output: message, exitCode: 1, error: message, ...(timedOut ? { timedOut: true } : {}), ...(stopped ? { stopped: true } : {}), externalJob: status };
+	} finally {
+		input.registerTimeout?.(undefined);
+		input.registerStop?.(undefined);
+	}
+}

package/src/runs/shared/mcp-direct-tool-allowlist.ts

@@ -32,6 +32,12 @@ interface ServerEntry {
 	cwd?: string;
 	url?: string;
 	headers?: Record<string, string>;
+	requestHeadersCommand?: {
+		command: string;
+		args?: string[];
+		env?: Record<string, string>;
+		timeoutMs?: number;
+	};
 	auth?: "oauth" | "bearer" | false;
 	bearerToken?: string;
 	bearerTokenEnv?: string;
@@ -279,6 +285,14 @@ export function computeMcpServerHash(definition: ServerEntry): string {
 		cwd: resolveConfigPath(definition.cwd),
 		url: resolveServerUrl(definition),
 		headers: interpolateEnvRecord(definition.headers),
+		requestHeadersCommand: definition.requestHeadersCommand
+			? {
+				command: interpolateEnvVars(definition.requestHeadersCommand.command),
+				args: definition.requestHeadersCommand.args?.map(interpolateEnvVars),
+				env: interpolateEnvRecord(definition.requestHeadersCommand.env),
+				timeoutMs: definition.requestHeadersCommand.timeoutMs,
+			}
+			: undefined,
 		auth: definition.auth,
 		bearerToken: resolveBearerToken(definition),
 		bearerTokenEnv: definition.bearerTokenEnv,

package/src/runs/shared/model-fallback.ts

@@ -163,6 +163,29 @@ export function resolveModelCandidate(
 	return model;
 }
 
+function resolveSubagentModelCandidate(
+	model: string,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string | undefined {
+	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;
+	return resolvedBase ? `${resolvedBase}${thinkingSuffix}` : undefined;
+}
+
+function resolveRequiredSubagentModelCandidate(
+	model: string,
+	availableModels: AvailableModelInfo[] | undefined,
+	preferredProvider?: string,
+): string {
+	const resolved = resolveSubagentModelCandidate(model, availableModels, preferredProvider);
+	if (resolved) return resolved;
+	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 +230,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,8 +287,15 @@ 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);
-		if (!normalized || seen.has(normalized)) continue;
+		const model = raw.trim();
+		const normalized = index === 0
+			? resolveRequiredSubagentModelCandidate(model, availableModels, preferredProvider)
+			: resolveSubagentModelCandidate(model, availableModels, preferredProvider);
+		if (!normalized) {
+			console.warn(`[pi-subagents] Skipping fallback model '${model}' because it is unavailable in this environment.`);
+			continue;
+		}
+		if (seen.has(normalized)) continue;
 		if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
 			const violation = checkModelScope(normalized, options.scope, "inherited");
 			if (violation) {
@@ -281,6 +311,7 @@ export function buildModelCandidates(
 
 const RETRYABLE_MODEL_FAILURE_PATTERNS = [
 	/rate\s*limit/i,
+	/usage\s*limit/i,
 	/too many requests/i,
 	/\b429\b/,
 	/quota/i,

package/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;
 		}