@bastani/atomic 0.9.12 → 0.9.13-alpha.1

package/dist/builtin/subagents/src/runs/background/result-retry-scheduler.ts

@@ -1,48 +0,0 @@
-export interface RetrySchedulerTimers {
-	setTimeout: typeof setTimeout;
-	clearTimeout: typeof clearTimeout;
-}
-
-export interface RetryScheduler {
-	has(key: string): boolean;
-	attempt(key: string): number;
-	schedule(key: string, callback: () => void): boolean;
-	clear(key: string): void;
-	clearAll(): void;
-}
-
-export function createRetryScheduler(
-	timers: RetrySchedulerTimers,
-	baseDelayMs: number,
-	maxDelayMs: number,
-): RetryScheduler {
-	const pending = new Map<string, ReturnType<typeof setTimeout>>();
-	const attempts = new Map<string, number>();
-	const clear = (key: string) => {
-		const timer = pending.get(key);
-		if (timer) timers.clearTimeout(timer);
-		pending.delete(key);
-		attempts.delete(key);
-	};
-	return {
-		has: (key) => pending.has(key),
-		attempt: (key) => attempts.get(key) ?? 0,
-		schedule(key, callback) {
-			if (pending.has(key)) return false;
-			const attempt = (attempts.get(key) ?? 0) + 1;
-			attempts.set(key, attempt);
-			const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** Math.min(attempt - 1, 30));
-			const timer = timers.setTimeout(() => {
-				pending.delete(key);
-				callback();
-			}, delay);
-			timer.unref?.();
-			pending.set(key, timer);
-			return true;
-		},
-		clear,
-		clearAll() {
-			for (const key of [...pending.keys()]) clear(key);
-		},
-	};
-}

package/dist/builtin/subagents/src/runs/background/result-status.ts

@@ -1,87 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { ASYNC_DIR } from "../../shared/types.ts";
-import { NESTED_RUNS_DIR } from "../shared/nested-events.ts";
-import type { ResultFileData } from "./result-watcher-data.js";
-
-const TERMINAL_ASYNC_STATES = new Set(["complete", "failed", "paused"]);
-export const DEFAULT_MAX_STATUS_BYTES = 1024 * 1024;
-
-export interface ResultStatusFs {
-	realpathSync: typeof fs.realpathSync;
-	lstatSync: typeof fs.lstatSync;
-	openSync: typeof fs.openSync;
-	fstatSync: typeof fs.fstatSync;
-	readSync: typeof fs.readSync;
-	closeSync: typeof fs.closeSync;
-}
-
-export interface ResultStatusOptions {
-	allowedRoots?: string[];
-	maxBytes?: number;
-}
-
-function contained(root: string, candidate: string): boolean {
-	const relative = path.relative(root, candidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
-}
-
-function canonicalRoots(fsApi: ResultStatusFs, roots: string[]): string[] {
-	const resolved: string[] = [];
-	for (const root of roots) {
-		try {
-			resolved.push(fsApi.realpathSync(root));
-		} catch {
-			/* unavailable roots cannot authorize a status path */
-		}
-	}
-	return resolved;
-}
-
-function readBoundedRegularFile(statusPath: string, fsApi: ResultStatusFs, maxBytes: number): string | undefined {
-	const linkStat = fsApi.lstatSync(statusPath);
-	if (linkStat.isSymbolicLink() || !linkStat.isFile() || linkStat.size > maxBytes) return undefined;
-	const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-	const handle = fsApi.openSync(statusPath, fs.constants.O_RDONLY | noFollow);
-	try {
-		const stat = fsApi.fstatSync(handle);
-		if (!stat.isFile() || stat.size > maxBytes) return undefined;
-		const buffer = Buffer.alloc(stat.size);
-		let offset = 0;
-		while (offset < buffer.length) {
-			const count = fsApi.readSync(handle, buffer, offset, buffer.length - offset, offset);
-			if (count === 0) break;
-			offset += count;
-		}
-		return buffer.subarray(0, offset).toString("utf-8");
-	} finally {
-		fsApi.closeSync(handle);
-	}
-}
-
-export function modernResultHasTerminalStatus(
-	data: ResultFileData,
-	fsApi: ResultStatusFs = fs,
-	options: ResultStatusOptions = {},
-): boolean {
-	if (!Object.hasOwn(data, "asyncDir")) return true;
-	const asyncDir = data.asyncDir?.trim();
-	const resultRunId = data.runId?.trim() || data.id?.trim();
-	if (!asyncDir || !resultRunId) return false;
-	try {
-		const canonicalAsyncDir = fsApi.realpathSync(asyncDir);
-		const roots = canonicalRoots(fsApi, options.allowedRoots ?? [ASYNC_DIR, NESTED_RUNS_DIR]);
-		if (!roots.some((root) => contained(root, canonicalAsyncDir))) return false;
-		const statusPath = path.join(canonicalAsyncDir, "status.json");
-		const content = readBoundedRegularFile(statusPath, fsApi, options.maxBytes ?? DEFAULT_MAX_STATUS_BYTES);
-		if (content === undefined) return false;
-		const status = JSON.parse(content) as { state?: string; runId?: string };
-		return (
-			status.runId?.trim() === resultRunId &&
-			typeof status.state === "string" &&
-			TERMINAL_ASYNC_STATES.has(status.state)
-		);
-	} catch {
-		return false;
-	}
-}

package/dist/builtin/subagents/src/runs/background/result-watcher-data.ts

@@ -1,72 +0,0 @@
-import { createHash } from "node:crypto";
-import type { NestedRunSummary } from "../../shared/types.ts";
-import { sanitizeSummary } from "../shared/nested-events.ts";
-
-export interface ResultFileChild {
-	agent?: string;
-	output?: string;
-	error?: string;
-	success?: boolean;
-	sessionFile?: string;
-	artifactPaths?: { outputPath?: string };
-	intercomTarget?: string;
-	children?: unknown;
-}
-
-export interface ResultFileData {
-	id?: string;
-	runId?: string;
-	agent?: string;
-	success?: boolean;
-	state?: string;
-	mode?: string;
-	summary?: string;
-	results?: ResultFileChild[];
-	nestedChildren?: unknown;
-	sessionId?: string;
-	cwd?: string;
-	sessionFile?: string;
-	asyncDir?: string;
-	intercomTarget?: string;
-}
-
-function stableStringify(value: unknown): string {
-	if (value === null || value === undefined || typeof value !== "object") {
-		const serialized = JSON.stringify(value);
-		return serialized === undefined ? "undefined" : serialized;
-	}
-	if (Array.isArray(value)) return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
-	const object = value as Record<string, unknown>;
-	return `{${Object.keys(object)
-		.sort()
-		.map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`)
-		.join(",")}}`;
-}
-
-/** Stable identity for every value exposed through local or Intercom completion delivery. */
-export function buildCompletionSignature(delivery: Record<string, unknown>): string {
-	return createHash("sha256").update(stableStringify(delivery)).digest("hex");
-}
-
-export function sanitizeNestedResultChildren(
-	value: unknown,
-	resultPath: string,
-	label: string,
-): NestedRunSummary[] | undefined {
-	if (value === undefined) return undefined;
-	if (!Array.isArray(value)) {
-		console.error(
-			`Ignoring invalid nested children in subagent result file '${resultPath}' at ${label}: expected an array.`,
-		);
-		return undefined;
-	}
-	const children = value
-		.map((child) => sanitizeSummary(child))
-		.filter((child): child is NestedRunSummary => Boolean(child));
-	if (children.length !== value.length) {
-		console.error(
-			`Ignoring ${value.length - children.length} invalid nested child record(s) in subagent result file '${resultPath}' at ${label}.`,
-		);
-	}
-	return children.length ? children : undefined;
-}

package/dist/builtin/subagents/src/runs/background/result-watcher.ts

@@ -1,320 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { isSafeFsWatchPathError, watchWithErrorHandler } from "@bastani/atomic";
-import { createFileCoalescer } from "../../shared/file-coalescer.js";
-import type { IntercomEventBus, SubagentState } from "../../shared/types.ts";
-import { processResultEntry, type ResultProcessorFs } from "./result-delivery-processor.js";
-import { claimIdFromScheduleKey, claimScheduleKey, listResultClaims } from "./result-file-claims.js";
-import { createRetryScheduler } from "./result-retry-scheduler.js";
-import type { ResultFileData } from "./result-watcher-data.js";
-
-const WATCHER_RESTART_DELAY_MS = 3000;
-const POLL_INTERVAL_MS = 3000;
-const DIRECTORY_RESCAN_DELAY_MS = 50;
-const STATUS_RECHECK_BASE_MS = 250;
-const STATUS_RECHECK_MAX_MS = 30_000;
-const DELIVERY_RETRY_BASE_MS = 1000;
-const DELIVERY_RETRY_MAX_MS = 30_000;
-
-type ResultWatcherFs = ResultProcessorFs & Pick<typeof fs, "existsSync" | "readdirSync" | "mkdirSync" | "watch">;
-type ResultWatcherTimers = {
-	setTimeout: typeof setTimeout;
-	clearTimeout: typeof clearTimeout;
-	setInterval: typeof setInterval;
-	clearInterval: typeof clearInterval;
-};
-type ResultWatcherSafeWatch = typeof watchWithErrorHandler;
-
-type ResultWatcherDeps = {
-	fs?: ResultWatcherFs;
-	timers?: ResultWatcherTimers;
-	safeWatch?: ResultWatcherSafeWatch;
-	statusRecheckBaseMs?: number;
-	statusRecheckMaxMs?: number;
-	deliveryRetryBaseMs?: number;
-	deliveryRetryMaxMs?: number;
-	maxNoProgressFailures?: number;
-	intercomTimeoutMs?: number | false;
-	allowedStatusRoots?: string[];
-	maxStatusBytes?: number;
-};
-
-function getErrorCode(error: unknown): string | undefined {
-	return typeof error === "object" && error !== null && "code" in error
-		? (error as NodeJS.ErrnoException).code
-		: undefined;
-}
-
-function isNotFoundError(error: unknown): boolean {
-	return getErrorCode(error) === "ENOENT";
-}
-
-function shouldFallBackToPolling(error: unknown): boolean {
-	const code = getErrorCode(error);
-	return code === "EMFILE" || code === "ENOSPC" || isSafeFsWatchPathError(error);
-}
-
-export function createResultWatcher(
-	pi: { events: IntercomEventBus },
-	state: SubagentState,
-	resultsDir: string,
-	completionTtlMs: number,
-	deps: ResultWatcherDeps = {},
-): { startResultWatcher: () => void; primeExistingResults: () => void; stopResultWatcher: () => void } {
-	const fsApi = deps.fs ?? fs;
-	const timers = deps.timers ?? { setTimeout, clearTimeout, setInterval, clearInterval };
-	const safeWatch = deps.safeWatch ?? watchWithErrorHandler;
-	let directoryRescanTimer: ReturnType<typeof setTimeout> | null = null;
-	let stopped = false;
-	let processingEpoch = 0;
-	let watcherInstallation = 0;
-	let activeWatcherInstallation = 0;
-	const inFlight = new Set<string>();
-	const rerunAfterFlight = new Set<string>();
-	const statusRetries = createRetryScheduler(
-		timers,
-		deps.statusRecheckBaseMs ?? STATUS_RECHECK_BASE_MS,
-		deps.statusRecheckMaxMs ?? STATUS_RECHECK_MAX_MS,
-	);
-	const deliveryRetries = createRetryScheduler(
-		timers,
-		deps.deliveryRetryBaseMs ?? DELIVERY_RETRY_BASE_MS,
-		deps.deliveryRetryMaxMs ?? DELIVERY_RETRY_MAX_MS,
-	);
-	const isEpochActive = (epoch: number): boolean => !stopped && epoch === processingEpoch;
-	const entryExists = (entry: string): boolean => {
-		const claimId = claimIdFromScheduleKey(entry);
-		return claimId
-			? Boolean(listResultClaims(resultsDir, fsApi).some((claim) => claim.id === claimId))
-			: fsApi.existsSync(path.join(resultsDir, entry));
-	};
-	const ownsResult = (data: ResultFileData): boolean =>
-		!stopped &&
-		(!data.sessionId || data.sessionId === state.currentSessionId) &&
-		Boolean(data.sessionId || !data.cwd || (state.baseCwd && data.cwd === state.baseCwd));
-
-	const coalescerKey = (entry: string, epoch: number): string => `${epoch}\0${entry}`;
-	const parseCoalescerKey = (key: string): { epoch: number; entry: string } => {
-		const split = key.indexOf("\0");
-		return { epoch: Number(key.slice(0, split)), entry: key.slice(split + 1) };
-	};
-	const scheduleResultEntry = (entry: string, delay = 0, epoch = processingEpoch): boolean => {
-		if (!isEpochActive(epoch) || statusRetries.has(entry) || deliveryRetries.has(entry)) return false;
-		return state.resultFileCoalescer.schedule(coalescerKey(entry, epoch), delay);
-	};
-	const scheduleStatusRecheck = (entry: string, epoch: number) => {
-		if (!isEpochActive(epoch)) return;
-		statusRetries.schedule(entry, () => {
-			if (!isEpochActive(epoch) || !entryExists(entry)) {
-				statusRetries.clear(entry);
-				return;
-			}
-			scheduleResultEntry(entry, 0, epoch);
-		});
-	};
-	const scheduleDeliveryRetry = (entry: string, epoch: number) => {
-		if (!isEpochActive(epoch)) return;
-		deliveryRetries.schedule(entry, () => {
-			if (!isEpochActive(epoch) || !entryExists(entry)) {
-				deliveryRetries.clear(entry);
-				return;
-			}
-			scheduleResultEntry(entry, 0, epoch);
-		});
-	};
-
-	const handleResult = async (entry: string, epoch: number) => {
-		if (!isEpochActive(epoch)) return;
-		const flightKey = coalescerKey(entry, epoch);
-		if (inFlight.has(flightKey)) {
-			rerunAfterFlight.add(flightKey);
-			return;
-		}
-		inFlight.add(flightKey);
-		try {
-			const outcome = await processResultEntry(entry, {
-				pi,
-				state,
-				resultsDir,
-				completionTtlMs,
-				fsApi,
-				allowedStatusRoots: deps.allowedStatusRoots,
-				maxStatusBytes: deps.maxStatusBytes,
-				maxNoProgressFailures: deps.maxNoProgressFailures,
-				intercomTimeoutMs: deps.intercomTimeoutMs,
-				isActive: () => isEpochActive(epoch),
-				ownsResult: (data) => isEpochActive(epoch) && ownsResult(data),
-			});
-			const nextEntry = outcome.entry ?? entry;
-			if (outcome.status === "status-pending") scheduleStatusRecheck(nextEntry, epoch);
-			else if (outcome.status === "delivery-retry") scheduleDeliveryRetry(nextEntry, epoch);
-			else {
-				statusRetries.clear(entry);
-				deliveryRetries.clear(entry);
-			}
-		} catch (error) {
-			if (!isNotFoundError(error)) {
-				console.error(`Failed to process subagent result entry '${entry}':`, error);
-				if (isEpochActive(epoch) && entryExists(entry)) scheduleDeliveryRetry(entry, epoch);
-			}
-		} finally {
-			inFlight.delete(flightKey);
-			if (rerunAfterFlight.delete(flightKey) && entryExists(entry)) scheduleResultEntry(entry, 0, epoch);
-		}
-	};
-
-	state.resultFileCoalescer = createFileCoalescer(
-		(key) => {
-			const { epoch, entry } = parseCoalescerKey(key);
-			void handleResult(entry, epoch);
-		},
-		50,
-		{ setTimeout: timers.setTimeout, clearTimeout: timers.clearTimeout },
-	);
-
-	const primeExistingResults = () => {
-		if (stopped) return;
-		const epoch = processingEpoch;
-		try {
-			for (const file of fsApi.readdirSync(resultsDir))
-				if (file.endsWith(".json")) scheduleResultEntry(file, 0, epoch);
-			for (const claim of listResultClaims(resultsDir, fsApi))
-				scheduleResultEntry(claimScheduleKey(claim.id), 0, epoch);
-		} catch (error) {
-			if (!isNotFoundError(error)) console.error(`Failed to scan subagent result directory '${resultsDir}':`, error);
-		}
-	};
-	const scheduleDirectoryRescan = (epoch: number) => {
-		if (!isEpochActive(epoch)) return;
-		if (directoryRescanTimer) timers.clearTimeout(directoryRescanTimer);
-		directoryRescanTimer = timers.setTimeout(() => {
-			directoryRescanTimer = null;
-			if (isEpochActive(epoch)) primeExistingResults();
-		}, DIRECTORY_RESCAN_DELAY_MS);
-		directoryRescanTimer.unref?.();
-	};
-
-	const startPollingFallback = (reason: unknown, epoch: number, installation?: number) => {
-		if (!isEpochActive(epoch) || (installation !== undefined && installation !== activeWatcherInstallation)) return;
-		state.watcher?.close();
-		state.watcher = null;
-		activeWatcherInstallation = 0;
-		if (state.watcherRestartTimer) return;
-		console.error(
-			`Subagent result watcher for '${resultsDir}' fell back to polling because native fs.watch is unavailable (${getErrorCode(reason) ?? "unknown error"}).`,
-		);
-		primeExistingResults();
-		state.watcherRestartTimer = timers.setInterval(() => {
-			if (isEpochActive(epoch)) primeExistingResults();
-		}, POLL_INTERVAL_MS);
-		state.watcherRestartTimer.unref?.();
-	};
-
-	function scheduleRestart(epoch: number): void {
-		if (!isEpochActive(epoch) || state.watcherRestartTimer) return;
-		let timer!: ReturnType<typeof setTimeout>;
-		timer = timers.setTimeout(() => {
-			if (state.watcherRestartTimer !== timer || !isEpochActive(epoch)) return;
-			state.watcherRestartTimer = null;
-			try {
-				fsApi.mkdirSync(resultsDir, { recursive: true });
-				openResultWatcher(epoch);
-			} catch (error) {
-				if (!isEpochActive(epoch)) return;
-				if (shouldFallBackToPolling(error)) startPollingFallback(error, epoch);
-				else {
-					console.error(`Failed to restart subagent result watcher for '${resultsDir}':`, error);
-					scheduleRestart(epoch);
-				}
-			}
-		}, WATCHER_RESTART_DELAY_MS);
-		state.watcherRestartTimer = timer;
-		timer.unref?.();
-	}
-
-	function openResultWatcher(epoch: number): void {
-		if (!isEpochActive(epoch) || state.watcher) return;
-		const installation = ++watcherInstallation;
-		let handle: fs.FSWatcher | null = null;
-		let pendingSynchronousError: Error | undefined;
-		const handleWatcherError = (error: Error) => {
-			if (!handle) {
-				pendingSynchronousError = error;
-				return;
-			}
-			if (!isEpochActive(epoch) || installation !== activeWatcherInstallation || state.watcher !== handle) return;
-			if (shouldFallBackToPolling(error)) {
-				startPollingFallback(error, epoch, installation);
-				return;
-			}
-			console.error(`Subagent result watcher failed for '${resultsDir}':`, error);
-			handle.close();
-			if (state.watcher === handle) state.watcher = null;
-			activeWatcherInstallation = 0;
-			scheduleRestart(epoch);
-		};
-		try {
-			handle = safeWatch(
-				resultsDir,
-				(_event, file) => {
-					if (!isEpochActive(epoch) || installation !== activeWatcherInstallation) return;
-					if (file) {
-						const name = file.toString();
-						if (name.endsWith(".json")) scheduleResultEntry(name, 50, epoch);
-					}
-					scheduleDirectoryRescan(epoch);
-				},
-				handleWatcherError,
-				{ watch: fsApi.watch, realpathSyncNative: fsApi.realpathSync?.native },
-			);
-			if (!handle) throw pendingSynchronousError ?? new Error("Result watcher installation returned no handle");
-			if (!isEpochActive(epoch)) {
-				handle.close();
-				return;
-			}
-			state.watcher = handle;
-			activeWatcherInstallation = installation;
-			handle.unref?.();
-			if (pendingSynchronousError) handleWatcherError(pendingSynchronousError);
-		} catch (error) {
-			handle?.close();
-			if (state.watcher === handle) state.watcher = null;
-			activeWatcherInstallation = 0;
-			if (!isEpochActive(epoch)) return;
-			if (shouldFallBackToPolling(error)) startPollingFallback(error, epoch);
-			else {
-				console.error(`Failed to start subagent result watcher for '${resultsDir}':`, error);
-				scheduleRestart(epoch);
-			}
-		}
-	}
-
-	const startResultWatcher = () => {
-		stopped = false;
-		processingEpoch += 1;
-		if (state.watcherRestartTimer) {
-			timers.clearTimeout(state.watcherRestartTimer);
-			timers.clearInterval(state.watcherRestartTimer);
-			state.watcherRestartTimer = null;
-		}
-		openResultWatcher(processingEpoch);
-	};
-	const stopResultWatcher = () => {
-		stopped = true;
-		processingEpoch += 1;
-		state.watcher?.close();
-		state.watcher = null;
-		activeWatcherInstallation = 0;
-		if (state.watcherRestartTimer) {
-			timers.clearTimeout(state.watcherRestartTimer);
-			timers.clearInterval(state.watcherRestartTimer);
-		}
-		state.watcherRestartTimer = null;
-		if (directoryRescanTimer) timers.clearTimeout(directoryRescanTimer);
-		directoryRescanTimer = null;
-		statusRetries.clearAll();
-		deliveryRetries.clearAll();
-		state.resultFileCoalescer.clear();
-	};
-	return { startResultWatcher, primeExistingResults, stopResultWatcher };
-}

package/dist/builtin/subagents/src/runs/background/run-id-resolver.ts

@@ -1,105 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { ASYNC_DIR, RESULTS_DIR, type SubagentState } from "../../shared/types.ts";
-import {
-	assertSafeNestedId,
-	findNestedRunMatchesById,
-	type NestedRoute,
-	type NestedRunMatch,
-	type NestedRunResolutionScope,
-} from "../shared/nested-events.ts";
-import { type AsyncRunLocation, findAsyncRunPrefixMatches } from "./async-resume.ts";
-
-export type ResolvedSubagentRunId =
-	| { kind: "foreground"; id: string }
-	| { kind: "async"; id: string; location: AsyncRunLocation }
-	| { kind: "nested"; id: string; match: NestedRunMatch };
-
-export interface ResolveSubagentRunIdDeps {
-	state?: SubagentState;
-	asyncDirRoot?: string;
-	resultsDir?: string;
-	nested?: NestedRunResolutionScope;
-}
-
-function exactAsyncLocation(id: string, asyncDirRoot: string, resultsDir: string): AsyncRunLocation | undefined {
-	const asyncDir = path.join(asyncDirRoot, id);
-	const resultPath = path.join(resultsDir, `${id}.json`);
-	if (!fs.existsSync(asyncDir) && !fs.existsSync(resultPath)) return undefined;
-	return {
-		asyncDir: fs.existsSync(asyncDir) ? asyncDir : null,
-		resultPath: fs.existsSync(resultPath) ? resultPath : null,
-		resolvedId: id,
-	};
-}
-
-function foregroundIds(state: SubagentState | undefined): string[] {
-	if (!state) return [];
-	return [...new Set([...state.foregroundControls.keys(), ...(state.foregroundRuns?.keys() ?? [])])];
-}
-
-export function nestedScopeFromState(state: SubagentState | undefined): NestedRunResolutionScope | undefined {
-	if (!state) return undefined;
-	const routes: NestedRoute[] = [];
-	const seen = new Set<string>();
-	const add = (route: NestedRoute | undefined) => {
-		if (!route) return;
-		const key = `${route.rootRunId}:${route.eventSink}:${route.controlInbox}`;
-		if (seen.has(key)) return;
-		seen.add(key);
-		routes.push(route);
-	};
-	for (const control of state.foregroundControls.values()) add(control.nestedRoute as NestedRoute | undefined);
-	for (const job of state.asyncJobs.values()) add(job.nestedRoute as NestedRoute | undefined);
-	return { routes };
-}
-
-function asyncPrefixMatches(
-	prefix: string,
-	asyncDirRoot: string,
-	resultsDir: string,
-): Array<{ id: string; location: AsyncRunLocation }> {
-	return findAsyncRunPrefixMatches(prefix, asyncDirRoot, resultsDir);
-}
-
-export function resolveSubagentRunId(
-	id: string,
-	deps: ResolveSubagentRunIdDeps = {},
-): ResolvedSubagentRunId | undefined {
-	assertSafeNestedId("id", id);
-	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
-	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
-
-	const nestedScope = deps.nested ?? nestedScopeFromState(deps.state);
-	if (deps.state?.foregroundControls.has(id) || deps.state?.foregroundRuns?.has(id)) return { kind: "foreground", id };
-	const exactAsync = exactAsyncLocation(id, asyncDirRoot, resultsDir);
-	if (exactAsync) return { kind: "async", id, location: exactAsync };
-	const exactNested = findNestedRunMatchesById(id, nestedScope ? { scope: nestedScope } : {});
-	if (exactNested.length > 1)
-		throw new Error(
-			`Nested run id '${id}' is ambiguous across authorized registries. Provide a more specific authorized run id.`,
-		);
-	if (exactNested[0]) return { kind: "nested", id, match: exactNested[0] };
-
-	const matches: ResolvedSubagentRunId[] = [];
-	for (const foregroundId of foregroundIds(deps.state).filter((candidate) => candidate.startsWith(id))) {
-		matches.push({ kind: "foreground", id: foregroundId });
-	}
-	for (const match of asyncPrefixMatches(id, asyncDirRoot, resultsDir)) {
-		matches.push({ kind: "async", id: match.id, location: match.location });
-	}
-	for (const match of findNestedRunMatchesById(
-		id,
-		nestedScope ? { prefix: true, scope: nestedScope } : { prefix: true },
-	)) {
-		matches.push({ kind: "nested", id: match.run.id, match });
-	}
-	const unique = new Map(matches.map((match) => [`${match.kind}:${match.id}`, match]));
-	const values = [...unique.values()];
-	if (values.length > 1) {
-		throw new Error(
-			`Ambiguous subagent run id prefix '${id}' matched: ${values.map((match) => `${match.kind}:${match.id}`).join(", ")}. Provide a longer id.`,
-		);
-	}
-	return values[0];
-}