pi-subagents 0.64.0 → 0.65.1

package/src/runs/background/async-job-tracker.ts

@@ -39,6 +39,8 @@ interface AsyncJobTrackerOptions {
 	watch?: typeof fs.watch;
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	now?: () => number;
+	/** Resolve native supervisor requests without scanning supervisor mailboxes. */
+	supervisorRequestState?: (event: ControlEvent) => "pending" | "resolved" | "unknown";
 }
 
 const CONTROL_EVENT_READ_CHUNK_BYTES = 64 * 1024;
@@ -293,6 +295,15 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
 				if ((parsed as { type?: unknown }).type !== "subagent.control") return;
 				const record = parsed as { event?: ControlEvent; channels?: string[]; childIntercomTarget?: string; noticeText?: string; intercom?: { to?: string; message?: string } };
 				if (!record.event || !Array.isArray(record.channels)) return;
+				if (record.event.type === "needs_attention" && record.event.reason === "supervisor_request" && options.supervisorRequestState) {
+					let requestState: "pending" | "resolved" | "unknown" = "unknown";
+					try {
+						requestState = options.supervisorRequestState(record.event);
+					} catch (error) {
+						console.error(`Failed to resolve supervisor request state for async control event in '${job.asyncDir}':`, error);
+					}
+					if (requestState === "resolved") return;
+				}
 				const payload = {
 					event: record.event,
 					source: "async" as const,

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

@@ -12,8 +12,10 @@ import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
 import { resultFilePath, resultPayloadPathForIndexedRun } from "./result-files.ts";
 import { canScanAsyncRunPrefix, MIN_SAFE_ASYNC_RUN_PREFIX_LENGTH } from "./run-id-query.ts";
 import { parallelHandoffPath, resolveRetainedWorktreeCwd } from "../shared/parallel-handoff.ts";
+import { normalizeWorktreeBaseRef } from "../shared/worktree.ts";
 import { intersectThinkingCeilings, parseThinkingLevel, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
 import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.ts";
+import { validateModelResponseAliases } from "../../shared/model-response-aliases.ts";
 
 export interface AsyncResumeParams {
 	id?: string;
@@ -316,11 +318,11 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
 	const parsed = value as Record<string, unknown>;
 	const allowedFields = new Set([
-		"version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "modelOrigin", "fallbackModels", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "extensions",
+		"modelResponseAliases", "version", "launchContractDigest", "sourceRunId", "agentContract", "agent", "sessionFile", "cwd", "model", "modelProvider", "modelOverrideFromParent", "modelOrigin", "fallbackModels", "thinking", "thinkingCeiling", "tools", "allowNestedSubagents", "extensions",
 		"subagentOnlyExtensions", "mcpDirectTools", "excludeTools", "mutationTools", "systemPrompt", "systemPromptMode", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills",
 		"skillPath", "agentFilePath", "completionGuard", "memory", "outputPath", "outputMode", "structuredOutputSchema", "acceptance", "sessionDir", "artifactConfig",
 		"artifactsDir", "maxOutput", "controlConfig", "context", "intercomBridge", "absoluteDeadlineAt", "initialTurnBudget", "initialToolBudget", "maxSubagentDepth", "share", "capabilityCeiling",
-		"launchResolvedExtensions", "runFanoutBudget", "lane",
+		"launchResolvedExtensions", "runFanoutBudget", "lane", "baseRef",
 		"extensionBindings",
 	]);
 	for (const field of Object.keys(parsed)) {
@@ -336,6 +338,7 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	} catch (error) {
 		throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
 	}
+	validateModelResponseAliases(parsed.modelResponseAliases, `async recovery descriptor '${descriptorPath}' modelResponseAliases`);
 	if (parsed.capabilityCeiling !== undefined) parsed.capabilityCeiling = parseSubagentCapabilityCeiling(parsed.capabilityCeiling, `async recovery descriptor '${descriptorPath}' capabilityCeiling`);
 	if (parsed.thinkingCeiling !== undefined) parsed.thinkingCeiling = parseThinkingLevel(parsed.thinkingCeiling, `async recovery descriptor '${descriptorPath}' thinkingCeiling`);
 	if (parsed.extensionBindings !== undefined) parsed.extensionBindings = normalizeExtensionBindings(parsed.extensionBindings)!.value;
@@ -366,6 +369,14 @@ export function readAsyncRecoveryDescriptor(asyncDir: string | undefined): Steer
 	for (const field of ["launchContractDigest", "sessionFile", "model", "modelProvider", "thinking", "agentFilePath", "outputPath", "sessionDir", "artifactsDir"] as const) {
 		if (parsed[field] !== undefined && (typeof parsed[field] !== "string" || !(parsed[field] as string).trim())) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
 	}
+	if (parsed.baseRef !== undefined) {
+		if (typeof parsed.baseRef !== "string") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': baseRef must be a string.`);
+		try {
+			parsed.baseRef = normalizeWorktreeBaseRef(parsed.baseRef);
+		} catch (error) {
+			throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
 	if (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean") throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
 	if (parsed.structuredOutputSchema !== undefined && (!parsed.structuredOutputSchema || typeof parsed.structuredOutputSchema !== "object" || Array.isArray(parsed.structuredOutputSchema))) throw new Error(`Invalid async recovery descriptor '${descriptorPath}': structuredOutputSchema must be an object.`);
 	if (parsed.memory !== undefined) {
@@ -623,7 +634,7 @@ export function buildRevivedAsyncTask(target: AsyncResumeTarget, message: string
 		`Original agent: ${target.agent}`,
 		target.sessionFile ? `Original session file: ${target.sessionFile}` : undefined,
 		"",
-		"Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child process is still alive.",
+		"Use the stored session context as background. Answer the orchestrator's follow-up below. Do not assume the original child session is still running.",
 		"",
 		"Follow-up:",
 		message,

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

@@ -320,7 +320,16 @@ function readCursor(root: string): RetentionCursor {
 	return value?.version === 1 ? value as unknown as RetentionCursor : { version: 1 };
 }
 
+let currentProcessStartIdentity: string | undefined | null = null;
+
 function processStartIdentity(pid: number): string | undefined {
+	// Foreign PIDs can be reused while this process lives, so resolve them afresh.
+	if (pid !== process.pid) return computeProcessStartIdentity(pid);
+	if (currentProcessStartIdentity === null) currentProcessStartIdentity = computeProcessStartIdentity(pid);
+	return currentProcessStartIdentity;
+}
+
+function computeProcessStartIdentity(pid: number): string | undefined {
 	if (process.platform === "linux") {
 		try {
 			const stat = fs.readFileSync(`/proc/${pid}/stat`).toString("utf8");

package/src/runs/background/control-channel.ts

@@ -1,7 +1,7 @@
 /**
  * Cross-OS control channel for async subagent runs.
  *
- * Background runs use child processes. Unix detaches them from the parent process.
+ * Background runs use a detached runner process. Unix detaches it from the parent process.
  * The original control path delivered an interrupt with
  * `process.kill(pid, SIGUSR2|SIGBREAK)`, but Windows cannot
  * deliver those signals cross-process via `process.kill` and throws `ENOSYS`,
@@ -74,33 +74,10 @@ export interface SteerRequest {
 	source?: string;
 }
 
-export interface SteerCapability {
-	type: "steer-capability";
-	protocolVersion: 1;
-	index: number;
-	pid: number;
-	readyAt: number;
-	supported: boolean;
-}
-
-export interface SteerAck {
-	type: "steer-ack";
-	protocolVersion: 1;
-	requestId: string;
-	index: number;
-	ts: number;
-	state: "delivered" | "queued" | "failed";
-	deliveryStatus?: SteerDeliveryStatus;
-	message: string;
-}
-
 const STEER_REQUESTS_DIR = "steer-requests";
 const STOP_REQUESTS_DIR = "stop-requests";
 const REVIVAL_BRIEFS_DIR = "revival-briefs";
 export const MAX_STEER_QUEUE_SIZE = 20;
-const STEER_TARGETS_DIR = "steer-targets";
-const STEER_CAPABILITIES_DIR = "steer-capabilities";
-const STEER_ACKS_DIR = "steer-acks";
 const STEER_INBOX_CLOSED_FILE = "steer-inbox-closed.json";
 const MAX_STEER_MESSAGE_BYTES = 128 * 1024;
 const MAX_STEER_REQUEST_ID_LENGTH = 256;
@@ -143,35 +120,6 @@ export function closeSteerInbox(asyncDir: string, state: string, write: (filePat
 	write(steerInboxClosedPath(asyncDir), { version: 1, closedAt: Date.now(), state });
 }
 
-/** Per-child inbox consumed by the child prompt runtime inside the Pi process. */
-export function stepSteerInboxDir(asyncDir: string, index: number): string {
-	assertChildIndex(index);
-	return path.join(controlInboxDir(asyncDir), STEER_TARGETS_DIR, String(index));
-}
-
-export function steerCapabilitiesDir(asyncDir: string): string {
-	return path.join(controlInboxDir(asyncDir), STEER_CAPABILITIES_DIR);
-}
-
-export function steerCapabilityPath(asyncDir: string, index: number): string {
-	assertChildIndex(index);
-	return path.join(steerCapabilitiesDir(asyncDir), `${index}.json`);
-}
-
-export function steerAcksDir(asyncDir: string, index: number): string {
-	assertChildIndex(index);
-	return path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR, String(index));
-}
-
-function steerAckFileName(requestId: string): string {
-	return `${Buffer.from(requestId).toString("base64url")}.json`;
-}
-
-export function steerAckPathFromDir(dir: string, requestId: string): string {
-	if (!/^[^\s]+$/.test(requestId) || requestId.length > 256) throw new Error("steer acknowledgment requestId is invalid.");
-	return path.join(dir, steerAckFileName(requestId));
-}
-
 function assertChildIndex(index: number): void {
 	if (!Number.isInteger(index) || index < 0 || index > 1_000_000) throw new Error("child index must be a non-negative integer.");
 }
@@ -229,45 +177,6 @@ export function writeSteerRequestToExistingDir(dir: string, request: SteerReques
 	return requestPath;
 }
 
-export function writeSteerCapabilityAt(filePath: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
-	assertChildIndex(capability.index);
-	if (!Number.isInteger(capability.pid) || capability.pid <= 0) throw new Error("steer capability pid must be a positive integer.");
-	if (!Number.isFinite(capability.readyAt) || capability.readyAt <= 0) throw new Error("steer capability readyAt must be a finite timestamp.");
-	const record: SteerCapability = { type: "steer-capability", protocolVersion: 1, ...capability };
-	writeAtomicJson(filePath, record);
-	return filePath;
-}
-
-export function writeSteerCapability(asyncDir: string, capability: Omit<SteerCapability, "type" | "protocolVersion">): string {
-	return writeSteerCapabilityAt(steerCapabilityPath(asyncDir, capability.index), capability);
-}
-
-function steerAckWritePath(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
-	const parsed = path.parse(filePath);
-	const stateOrder = ack.state === "queued" ? "0" : ack.state === "delivered" ? "1" : "2";
-	const timestamp = String(Math.trunc(ack.ts)).padStart(13, "0");
-	for (let suffix = 0; suffix < 1_000; suffix += 1) {
-		const candidate = path.join(parsed.dir, `${parsed.name}-${timestamp}-${stateOrder}-${ack.state}${suffix === 0 ? "" : `-${suffix}`}${parsed.ext}`);
-		if (!fs.existsSync(candidate)) return candidate;
-	}
-	throw new Error("steer acknowledgment queue is full.");
-}
-
-export function writeSteerAckAt(filePath: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
-	assertChildIndex(ack.index);
-	if (!/^[^\s]+$/.test(ack.requestId) || ack.requestId.length > 256) throw new Error("steer acknowledgment requestId is invalid.");
-	if (!Number.isFinite(ack.ts) || ack.ts <= 0) throw new Error("steer acknowledgment ts must be a finite timestamp.");
-	if (!ack.message.trim() || ack.message.length > 1000) throw new Error("steer acknowledgment message is invalid.");
-	const record: SteerAck = { type: "steer-ack", protocolVersion: 1, ...ack, message: ack.message.trim() };
-	const ackPath = steerAckWritePath(filePath, ack);
-	writeAtomicJson(ackPath, record);
-	return ackPath;
-}
-
-export function writeSteerAck(asyncDir: string, ack: Omit<SteerAck, "type" | "protocolVersion">): string {
-	return writeSteerAckAt(path.join(steerAcksDir(asyncDir, ack.index), steerAckFileName(ack.requestId)), ack);
-}
-
 /**
  * Parent side: drop a portable interrupt request the runner's inbox watcher will
  * pick up regardless of OS. Written atomically (temp + rename), dir auto-created.
@@ -350,97 +259,6 @@ export function requestAsyncSteer(
 	return requestPath;
 }
 
-export function enqueueStepSteer(asyncDir: string, index: number, request: SteerRequest): string {
-	assertChildIndex(index);
-	const { targetIndexes: _targetIndexes, ...singleTargetRequest } = request;
-	return writeSteerRequestToDir(stepSteerInboxDir(asyncDir, index), { ...singleTargetRequest, targetIndex: index, type: "steer" });
-}
-
-function parseSteerCapability(raw: unknown): SteerCapability | undefined {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-	const input = raw as Partial<SteerCapability>;
-	if (input.type !== "steer-capability" || input.protocolVersion !== 1) return undefined;
-	const { index, pid, readyAt, supported } = input;
-	if (typeof index !== "number" || !Number.isInteger(index) || index < 0 || index > 1_000_000) return undefined;
-	if (typeof pid !== "number" || typeof readyAt !== "number" || !Number.isInteger(pid) || pid <= 0 || !Number.isFinite(readyAt) || readyAt <= 0 || typeof supported !== "boolean") return undefined;
-	return { type: "steer-capability", protocolVersion: 1, index, pid, readyAt, supported };
-}
-
-function parseSteerAck(raw: unknown): SteerAck | undefined {
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-	const input = raw as Partial<SteerAck>;
-	if (input.type !== "steer-ack" || input.protocolVersion !== 1 || typeof input.requestId !== "string" || !/^[^\s]+$/.test(input.requestId) || input.requestId.length > 256) return undefined;
-	const { index, ts, state, message } = input;
-	if (typeof index !== "number" || typeof ts !== "number" || !Number.isInteger(index) || index < 0 || index > 1_000_000 || !Number.isFinite(ts) || ts <= 0) return undefined;
-	if (state !== "delivered" && state !== "queued" && state !== "failed") return undefined;
-	if (input.deliveryStatus !== undefined && input.deliveryStatus !== "delivered" && input.deliveryStatus !== "queued") return undefined;
-	if (typeof message !== "string" || !message.trim() || message.length > 1000) return undefined;
-	return { type: "steer-ack", protocolVersion: 1, requestId: input.requestId, index, ts, state, ...(input.deliveryStatus ? { deliveryStatus: input.deliveryStatus } : {}), message: message.trim() };
-}
-
-export function readSteerCapability(asyncDir: string, index: number): SteerCapability | undefined {
-	try {
-		return parseSteerCapability(JSON.parse(fs.readFileSync(steerCapabilityPath(asyncDir, index), "utf-8")));
-	} catch {
-		return undefined;
-	}
-}
-
-export function consumeSteerCapabilities(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync"> = fs): SteerCapability[] {
-	const dir = steerCapabilitiesDir(asyncDir);
-	if (!fsImpl.existsSync(dir)) return [];
-	const capabilities: SteerCapability[] = [];
-	for (const entry of fsImpl.readdirSync(dir).filter((name) => /^\d+\.json$/.test(name)).sort()) {
-		try {
-			const capability = parseSteerCapability(JSON.parse(fsImpl.readFileSync(path.join(dir, entry), "utf-8")));
-			if (capability) capabilities.push(capability);
-		} catch {
-			// A partially written or malformed capability is ignored until a valid one arrives.
-		}
-	}
-	return capabilities;
-}
-
-export function consumeSteerAckFromDir(
-	dir: string,
-	requestId: string,
-	fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs,
-): SteerAck | undefined {
-	if (!fsImpl.existsSync(dir)) return undefined;
-	let entries: string[];
-	try { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); } catch { return undefined; }
-	for (const entry of entries) {
-		const target = path.join(dir, entry);
-		let ack: SteerAck | undefined;
-		try { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, "utf-8"))); } catch { ack = undefined; }
-		if (ack?.requestId !== requestId) continue;
-		try { fsImpl.rmSync(target, { force: true }); } catch { return undefined; }
-		return ack;
-	}
-	return undefined;
-}
-
-export function consumeSteerAcks(asyncDir: string, fsImpl: Pick<typeof fs, "existsSync" | "readdirSync" | "readFileSync" | "rmSync"> = fs): SteerAck[] {
-	const root = path.join(controlInboxDir(asyncDir), STEER_ACKS_DIR);
-	if (!fsImpl.existsSync(root)) return [];
-	const acks: SteerAck[] = [];
-	let indexNames: string[];
-	try { indexNames = fsImpl.readdirSync(root).filter((name) => /^\d+$/.test(name)); } catch { return []; }
-	for (const indexName of indexNames) {
-		const dir = path.join(root, indexName);
-		let entries: string[];
-		try { entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); } catch { continue; }
-		for (const entry of entries) {
-			const target = path.join(dir, entry);
-			let ack: SteerAck | undefined;
-			try { ack = parseSteerAck(JSON.parse(fsImpl.readFileSync(target, "utf-8"))); } catch { ack = undefined; }
-			try { fsImpl.rmSync(target, { force: true }); } catch { continue; }
-			if (ack) acks.push(ack);
-		}
-	}
-	return acks;
-}
-
 function parseSteerRequest(raw: unknown): SteerRequest | undefined {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const input = raw as Partial<SteerRequest>;
@@ -665,8 +483,6 @@ export function watchAsyncControlInbox(
 		onTimeout?: () => void;
 		onStop?: (request: StopRequest) => void;
 		onSteer?: (request: SteerRequest) => void;
-		onSteerCapability?: (capability: SteerCapability) => void;
-		onSteerAck?: (ack: SteerAck) => void;
 		pollIntervalMs?: number;
 		safetyPollIntervalMs?: number;
 		platform?: NodeJS.Platform;
@@ -691,8 +507,6 @@ export function watchAsyncControlInbox(
 			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
 			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
 			for (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);
-			for (const capability of consumeSteerCapabilities(asyncDir, fsImpl)) opts.onSteerCapability?.(capability);
-			for (const ack of consumeSteerAcks(asyncDir, fsImpl)) opts.onSteerAck?.(ack);
 		} catch {
 			// Never let inbox errors crash the runner.
 		}
@@ -718,32 +532,16 @@ export function watchAsyncControlInbox(
 	const watchDir = (target: string, create = false): void => {
 		if (disposed || watchedDirs.has(target)) return;
 		if (create) fsImpl.mkdirSync(target, { recursive: true });
-		const watcher = fsImpl.watch(resolveWatchPath(target, fsImpl.realpathSync.native), () => {
-			watchExistingSteerAckDirs();
-			check();
-		});
+		const watcher = fsImpl.watch(resolveWatchPath(target, fsImpl.realpathSync.native), () => check());
 		watcher.on?.("error", startPolling);
 		watchers.push(watcher);
 		watchedDirs.add(target);
 	};
-	const watchExistingSteerAckDirs = (): void => {
-		const ackRoot = path.join(dir, STEER_ACKS_DIR);
-		let entries: string[];
-		try {
-			entries = fsImpl.readdirSync(ackRoot).filter((name) => /^\d+$/.test(name));
-		} catch {
-			return;
-		}
-		for (const entry of entries) watchDir(path.join(ackRoot, entry));
-	};
 	try {
 		if (shouldUseNativeFsWatch("runner-control-inbox", opts.platform)) {
 			watchDir(dir);
 			watchDir(stopRequestsDir(asyncDir), true);
 			watchDir(steerRequestsDir(asyncDir), true);
-			watchDir(steerCapabilitiesDir(asyncDir), true);
-			watchDir(path.join(dir, STEER_ACKS_DIR), true);
-			watchExistingSteerAckDirs();
 			startSafetyPolling();
 		} else {
 			startPolling();

package/src/runs/background/notify.ts

@@ -123,6 +123,7 @@ export interface RegisterSubagentNotifyOptions {
 
 export interface CompletionNotifier {
 	deliver(result: CompletionNotification): Promise<boolean>;
+	hasPendingDelivery(): boolean;
 	dispose(): void;
 }
 
@@ -628,6 +629,7 @@ export default function registerSubagentNotify(
 
 	return {
 		deliver,
+		hasPendingDelivery: () => pending.size > 0,
 		dispose() {
 			if (disposed) return;
 			disposed = true;

package/src/runs/background/process-terminal.ts

@@ -115,7 +115,7 @@ export function writeProcessTerminalCandidate(asyncDir: string, candidate: Proce
 	writePrivateAtomicJson(processTerminalCandidatePath(asyncDir), candidate);
 }
 
-/** Establish ownership before authorizing a runner to launch any child process. */
+/** Establish ownership before authorizing a runner to start any child session. */
 export function initializeProcessTerminal(asyncDir: string, runId: string, runnerProcessInstanceId: string): void {
 	writeProcessTerminalCandidate(asyncDir, {
 		version: 1,

package/src/runs/background/retained-nested-route-tracker.ts

@@ -0,0 +1,96 @@
+import * as fs from "node:fs";
+import type { SubagentState } from "../../shared/types.ts";
+import { shouldUseNativeFsWatch } from "../../shared/watch-strategy.ts";
+import { hasLiveNestedDescendants, projectNestedEvents } from "../shared/nested-events.ts";
+
+interface RetainedNestedRouteTrackerOptions {
+	pollIntervalMs?: number;
+	platform?: NodeJS.Platform;
+	watch?: typeof fs.watch;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const REFRESH_DEBOUNCE_MS = 25;
+
+export function createRetainedNestedRouteTracker(
+	state: Pick<SubagentState, "retainedForegroundNestedRoutes">,
+	options: RetainedNestedRouteTrackerOptions = {},
+): { track: (rootRunId: string) => void; clear: () => void } {
+	const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const watch = options.watch ?? fs.watch;
+	const watchers = new Map<string, fs.FSWatcher>();
+	const refreshTimers = new Map<string, ReturnType<typeof setTimeout>>();
+	let poller: ReturnType<typeof setInterval> | undefined;
+
+	const close = (rootRunId: string): void => {
+		watchers.get(rootRunId)?.close();
+		watchers.delete(rootRunId);
+		const timer = refreshTimers.get(rootRunId);
+		if (timer) clearTimeout(timer);
+		refreshTimers.delete(rootRunId);
+	};
+
+	const refresh = (rootRunId: string): void => {
+		const retained = state.retainedForegroundNestedRoutes?.get(rootRunId);
+		if (!retained) {
+			close(rootRunId);
+			return;
+		}
+		try {
+			if (hasLiveNestedDescendants(projectNestedEvents(retained).children)) return;
+			state.retainedForegroundNestedRoutes?.delete(rootRunId);
+			close(rootRunId);
+		} catch (error) {
+			console.error(`Failed to refresh retained nested descendants for foreground run '${rootRunId}':`, error);
+		}
+	};
+
+	const scheduleRefresh = (rootRunId: string): void => {
+		if (refreshTimers.has(rootRunId)) return;
+		const timer = setTimeout(() => {
+			refreshTimers.delete(rootRunId);
+			refresh(rootRunId);
+		}, REFRESH_DEBOUNCE_MS);
+		timer.unref?.();
+		refreshTimers.set(rootRunId, timer);
+	};
+
+	const ensurePoller = (): void => {
+		if (poller || (state.retainedForegroundNestedRoutes?.size ?? 0) === 0) return;
+		poller = setInterval(() => {
+			for (const rootRunId of state.retainedForegroundNestedRoutes?.keys() ?? []) refresh(rootRunId);
+			if ((state.retainedForegroundNestedRoutes?.size ?? 0) > 0) return;
+			if (poller) clearInterval(poller);
+			poller = undefined;
+		}, pollIntervalMs);
+		poller.unref?.();
+	};
+
+	const track = (rootRunId: string): void => {
+		const retained = state.retainedForegroundNestedRoutes?.get(rootRunId);
+		if (!retained) return;
+		if (shouldUseNativeFsWatch("retained-nested-route-tracker", options.platform) && !watchers.has(rootRunId)) {
+			try {
+				const watcher = watch(retained.eventSink, () => scheduleRefresh(rootRunId));
+				watcher.on("error", () => close(rootRunId));
+				watcher.unref?.();
+				watchers.set(rootRunId, watcher);
+			} catch {
+				// The bounded safety poll below covers unsupported or failed watchers.
+			}
+		}
+		scheduleRefresh(rootRunId);
+		ensurePoller();
+	};
+
+	const clear = (): void => {
+		if (poller) clearInterval(poller);
+		poller = undefined;
+		for (const rootRunId of watchers.keys()) close(rootRunId);
+		for (const timer of refreshTimers.values()) clearTimeout(timer);
+		refreshTimers.clear();
+		state.retainedForegroundNestedRoutes?.clear();
+	};
+
+	return { track, clear };
+}