@ferris1225/pi-subagents 4.1.8 → 4.1.11

package/src/setup.ts

@@ -1,25 +1,21 @@
 /**
  * Interactive configuration wizard for /subagents-setup.
  *
- * The UI intentionally has no backup pool or global thinking menu. Each agent
- * gets one optional model override; failures hand directly to the current main
- * model. Thinking defaults to Auto and manual choices are limited to levels Pi
- * reports as supported by the selected model.
+ * The wizard stays one level deep and exposes only what most users touch:
+ * which agents run, the model each runs on, and the delegation directive
+ * toggle. Everything else (per-agent thinking, agent scope, idle timeout,
+ * result lines, notifications) is config-file-only; model failures hand
+ * directly to the current main model, and thinking defaults to capability-
+ * aware Auto.
  */
 
 import { stat } from "node:fs/promises";
-import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
-	AGENT_SCOPE_VALUES,
 	BUILTIN_AGENT_NAMES,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
-	DEFAULT_IDLE_TIMEOUT_SEC,
-	DEFAULT_THINKING_LEVEL,
-	type AgentScope,
 	type SubagentsConfig,
-	type ThinkingLevel,
 	errorMessage,
 	getConfigPath,
 	loadConfig,
@@ -31,28 +27,9 @@ import {
 	availableModelsInScope,
 	buildModelPickerItems,
 	currentModelRef,
-	findModelByRef,
 	modelRef,
-	resolveThinkingLevel,
-	supportedThinkingLevels,
 } from "./models.ts";
 import { promptSelectMany, promptSelectOne } from "./ui.ts";
-import { discoverAgents } from "./agents.ts";
-
-const AUTO_THINKING = "__auto_thinking__";
-
-function actualAgentThinkingDefault(
-	ctx: ExtensionCommandContext,
-	config: SubagentsConfig,
-	agentName: string,
-): ThinkingLevel {
-	const { agents } = discoverAgents(ctx.cwd, {
-		scope: config.agentScope,
-		enabledNames: config.enabledAgents,
-		projectTrusted: ctx.isProjectTrusted(),
-	});
-	return agents.find((agent) => agent.name === agentName)?.thinking ?? DEFAULT_THINKING_LEVEL;
-}
 
 /** Short, selection-friendly descriptions for the built-in agents. */
 const MODULE_HINTS: Record<string, string> = {
@@ -121,61 +98,6 @@ async function pickAgentModel(
 	return pickConfiguredModel(ctx, `Model for "${agentName}"?`, currentRef, escNote);
 }
 
-const THINKING_LEVEL_HINTS: Record<ThinkingLevel, string> = {
-	off: "no reasoning tokens",
-	minimal: "minimal reasoning",
-	low: "light reasoning",
-	medium: "balanced reasoning",
-	high: "deep reasoning",
-	xhigh: "extra-deep reasoning",
-	max: "strongest reasoning",
-};
-
-function effectiveModelForChoice(
-	ctx: ExtensionCommandContext,
-	choice: string,
-): Model<Api> | undefined {
-	if (choice === CURRENT_MAIN_MODEL) return ctx.model;
-	return findModelByRef(availableModelsInScope(ctx), choice);
-}
-
-/** Auto is the default. Manual rows are exactly the levels Pi exposes for the
- * selected model; unsupported xhigh/max entries never appear. */
-async function pickAgentStrength(
-	ctx: ExtensionCommandContext,
-	agentName: string,
-	model: Model<Api> | undefined,
-	current: ThinkingLevel | undefined,
-	agentDefault: ThinkingLevel,
-	escNote = "cancels this setup pass",
-): Promise<ThinkingLevel | typeof AUTO_THINKING | undefined> {
-	const supported = supportedThinkingLevels(model);
-	const automatic = resolveThinkingLevel(model, agentDefault);
-	// No model metadata, or a non-reasoning model whose only valid value is off:
-	// Auto is already the complete and least surprising choice.
-	if (supported.length <= 1) return AUTO_THINKING;
-
-	const currentEffective = current ? resolveThinkingLevel(model, current) : undefined;
-	const modelName = model ? modelRef(model) : "current main model";
-	const options = [
-		{
-			value: AUTO_THINKING,
-			label: `auto — ${automatic} for ${modelName}${current === undefined ? " (current, recommended)" : " (recommended)"}`,
-		},
-		...supported.map((level) => ({
-			value: level,
-			label: `${level} — ${THINKING_LEVEL_HINTS[level]}${current !== undefined && currentEffective === level ? " (current)" : ""}`,
-		})),
-	];
-	return promptSelectOne(
-		ctx,
-		`Thinking for "${agentName}"?`,
-		`Only levels supported by ${modelName} are shown • Enter selects • Esc ${escNote}`,
-		options,
-		current === undefined ? AUTO_THINKING : currentEffective,
-	) as Promise<ThinkingLevel | typeof AUTO_THINKING | undefined>;
-}
-
 async function pickAgentToConfigure(
 	ctx: ExtensionCommandContext,
 	enabledAgents: readonly string[],
@@ -195,11 +117,10 @@ async function pickAgentToConfigure(
 interface ConfiguredAgentChoice {
 	name: string;
 	model: string;
-	strength: ThinkingLevel | typeof AUTO_THINKING;
 }
 
-/** Configure one agent while preserving the UI back stack: thinking → model →
- * agent selection. Esc from agent selection ends this configuration pass. */
+/** Configure agents while preserving the UI back stack: model selection returns
+ * to the agent picker on Esc; agent-picker Esc ends this configuration pass. */
 async function configureOneAgent(
 	ctx: ExtensionCommandContext,
 	config: SubagentsConfig,
@@ -207,27 +128,14 @@ async function configureOneAgent(
 	while (true) {
 		const name = await pickAgentToConfigure(ctx, config.enabledAgents);
 		if (name === undefined) return undefined;
-
-		while (true) {
-			const modelChoice = await pickAgentModel(
-				ctx,
-				name,
-				config.agentModels[name],
-				"returns to agent selection",
-			);
-			if (modelChoice === undefined) break;
-			const model = effectiveModelForChoice(ctx, modelChoice);
-			const strength = await pickAgentStrength(
-				ctx,
-				name,
-				model,
-				config.agentThinkingLevels[name],
-				actualAgentThinkingDefault(ctx, config, name),
-				"returns to model selection",
-			);
-			if (strength === undefined) continue;
-			return { name, model: modelChoice, strength };
-		}
+		const model = await pickAgentModel(
+			ctx,
+			name,
+			config.agentModels[name],
+			"returns to agent selection",
+		);
+		if (model === undefined) continue;
+		return { name, model };
 	}
 }
 
@@ -239,40 +147,6 @@ async function pickInjection(ctx: ExtensionCommandContext, current: boolean): Pr
 	return choice.startsWith("On");
 }
 
-const IDLE_TIMEOUT_STEPS = [0, 30, 60, 90, 120, 180, 300, 600];
-
-async function pickCount(
-	ctx: ExtensionCommandContext,
-	title: string,
-	steps: readonly number[],
-	current: number,
-	defaultValue: number,
-): Promise<number | undefined> {
-	const values = [...new Set([...steps, current])].sort((a, b) => a - b);
-	const options = values.map((value) => {
-		const tags = [value === current ? "current" : "", value === defaultValue ? "default" : ""]
-			.filter(Boolean)
-			.join(", ");
-		return tags ? `${value} (${tags})` : String(value);
-	});
-	const choice = await ctx.ui.select(title, options);
-	return choice === undefined ? undefined : Number.parseInt(choice, 10);
-}
-
-async function pickScope(ctx: ExtensionCommandContext, current: AgentScope): Promise<AgentScope | undefined> {
-	const labels: Record<AgentScope, string> = {
-		user: "user — built-in + ~/.pi/agent/agents (default)",
-		project: "project — built-in + nearest .pi/agents only",
-		both: "both — user agents, overridden by project agents",
-	};
-	const options = AGENT_SCOPE_VALUES.map((scope) =>
-		scope === current ? `${labels[scope]} (current)` : labels[scope],
-	);
-	const choice = await ctx.ui.select("Which agent directories to discover from?", options);
-	if (choice === undefined) return undefined;
-	return AGENT_SCOPE_VALUES.find((scope) => choice.startsWith(scope));
-}
-
 function keepAgentEntries<T>(record: Record<string, T>, enabled: readonly string[]): Record<string, T> {
 	const keep = new Set(enabled);
 	return Object.fromEntries(Object.entries(record).filter(([name]) => keep.has(name)));
@@ -291,16 +165,6 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 
 	const injection = await pickInjection(ctx, base.proactiveInjection);
 	if (injection === undefined) return false;
-	const scope = await pickScope(ctx, base.agentScope);
-	if (scope === undefined) return false;
-	const idleTimeoutSec = await pickCount(
-		ctx,
-		"Idle timeout in seconds? (0 = disabled)",
-		IDLE_TIMEOUT_STEPS,
-		base.idleTimeoutSec,
-		DEFAULT_IDLE_TIMEOUT_SEC,
-	);
-	if (idleTimeoutSec === undefined) return false;
 
 	const next: SubagentsConfig = {
 		enabledAgents: enabled,
@@ -310,49 +174,20 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 		notifyOnReviewPass: base.notifyOnReviewPass,
 		maxResultLines: base.maxResultLines,
 		proactiveInjection: injection,
-		agentScope: scope,
-		idleTimeoutSec,
+		agentScope: base.agentScope,
+		idleTimeoutSec: base.idleTimeoutSec,
 	};
 	await saveConfig(next, configPath);
 	ctx.ui.notify(`pi-subagents configured with Auto thinking. Saved to ${configPath}`, "info");
 	return true;
 }
 
-async function updateRuntimeSetting(
-	ctx: ExtensionCommandContext,
-	config: SubagentsConfig,
-): Promise<SubagentsConfig | undefined> {
-	while (true) {
-		const choice = await ctx.ui.select("Runtime setting", [
-			"Proactive injection",
-			"Agent scope",
-			"Idle timeout",
-		]);
-		if (choice === undefined) return undefined;
-		const next = { ...config };
-		if (choice.startsWith("Proactive")) {
-			const value = await pickInjection(ctx, config.proactiveInjection);
-			if (value === undefined) continue;
-			next.proactiveInjection = value;
-		} else if (choice.startsWith("Agent scope")) {
-			const value = await pickScope(ctx, config.agentScope);
-			if (value === undefined) continue;
-			next.agentScope = value;
-		} else {
-			const value = await pickCount(ctx, "Idle timeout in seconds?", IDLE_TIMEOUT_STEPS, config.idleTimeoutSec, DEFAULT_IDLE_TIMEOUT_SEC);
-			if (value === undefined) continue;
-			next.idleTimeoutSec = value;
-		}
-		return next;
-	}
-}
-
 async function runMenu(ctx: ExtensionCommandContext, configPath: string, config: SubagentsConfig): Promise<void> {
 	while (true) {
 		const choice = await ctx.ui.select("pi-subagents settings", [
 			"Enable/disable agents",
-			"Configure an agent (model + thinking)",
-			"Runtime settings",
+			"Configure agent models",
+			"Proactive injection",
 			"Full re-setup",
 		]);
 		if (choice === undefined) return;
@@ -395,17 +230,14 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 			next.agentModels = keepAgentEntries(next.agentModels, enabled);
 			next.agentThinkingLevels = keepAgentEntries(next.agentThinkingLevels, enabled);
 		} else if (choice.startsWith("Configure")) {
-			// Per-agent loop: thinking Esc returns to that agent's model picker;
-			// model Esc returns to the agent picker; agent-picker Esc saves completed
-			// choices and returns to this settings menu.
+			// Per-agent loop: model Esc returns to the agent picker; agent-picker
+			// Esc saves completed choices and returns to this settings menu.
 			let configuredAny = false;
 			while (true) {
 				const picked = await configureOneAgent(ctx, next);
 				if (!picked) break;
 				configuredAny = true;
 				next.agentModels = applyAgentModelChoice(next.agentModels, picked.name, picked.model);
-				if (picked.strength === AUTO_THINKING) delete next.agentThinkingLevels[picked.name];
-				else next.agentThinkingLevels[picked.name] = picked.strength;
 			}
 			if (!configuredAny) continue;
 			await saveConfig(next, configPath);
@@ -413,9 +245,9 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 			config = next;
 			continue;
 		} else {
-			const updated = await updateRuntimeSetting(ctx, next);
-			if (updated === undefined) continue;
-			next = updated;
+			const injection = await pickInjection(ctx, next.proactiveInjection);
+			if (injection === undefined) continue;
+			next.proactiveInjection = injection;
 		}
 
 		await saveConfig(next, configPath);

package/src/spawn.ts

@@ -10,7 +10,7 @@
 
 import { createHash, randomUUID } from "node:crypto";
 import { type Dirent, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
@@ -202,7 +202,7 @@ export function writeResultArtifact(output: string, agentName: string, cwd?: str
 }
 
 export function isFailedResult(result: SingleResult): boolean {
-	if (result.parked) return false;
+
 	return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 }
 
@@ -308,12 +308,12 @@ async function waitForControlledRetry(
 ): Promise<boolean> {
 	let remaining = normalizeStartupRetryDelay(delayMs);
 	while (remaining > 0) {
-		if (control?.isParkRequested() || control?.isStopRequested()) return false;
+		if (control?.isStopRequested()) return false;
 		const slice = Math.min(remaining, 50);
 		if (!(await waitForStartupRetry(slice, signal))) return false;
 		remaining -= slice;
 	}
-	return !signal?.aborted && !control?.isParkRequested() && !control?.isStopRequested();
+	return !signal?.aborted && !control?.isStopRequested();
 }
 
 export function getResultOutput(result: SingleResult): string {
@@ -330,6 +330,12 @@ export function buildResumePrompt(task: string, reason: string): string {
 	return `You are resuming an earlier sub-agent session after ${reason}. Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Current objective: ${task}. Pick up exactly where you left off and finish it. Do NOT redo searches, reads, or edits you already completed unless a step clearly failed. Continue now.`;
 }
 
+/** Create a fresh private session directory under the given root. */
+export async function createSessionDir(root: string = tmpdir()): Promise<string> {
+	await mkdir(root, { recursive: true });
+	return mkdtemp(join(root, "pi-subagent-session-"));
+}
+
 export function buildFallbackResumeReason(fromModel?: string): string {
 	return fromModel
 		? `the selected model (${fromModel}) failed at the model/provider level, so the current main model is continuing`
@@ -349,6 +355,10 @@ export interface RunSingleOptions {
 	startupRetryDelaysMs?: readonly number[];
 	sessionDir?: string;
 	sessionId?: string;
+	/** Parent directory for a fresh session directory. Defaults to the OS temp
+	 * dir; dispatch passes the durable state root so retained sessions survive
+	 * reloads and restarts. */
+	sessionRoot?: string;
 	/** Initial RPC prompt. Kept under the old name to limit caller churn. */
 	stdinText?: string;
 	/** Refresh parent-derived tools immediately before every startup retry and
@@ -366,7 +376,7 @@ export interface RunSingleOptions {
 
 function controlledDisposition(options: RunSingleOptions, base?: SingleResult): SingleResult | undefined {
 	const control = options.control;
-	if (!control?.isParkRequested() && !control?.isStopRequested()) return undefined;
+	if (!control?.isStopRequested()) return undefined;
 	const result: SingleResult = base ?? {
 		agent: options.agentName,
 		task: control.getObjective(),
@@ -380,23 +390,14 @@ function controlledDisposition(options: RunSingleOptions, base?: SingleResult):
 		sessionDir: options.sessionDir,
 	};
 	result.task = control.getObjective();
-	if (control.isParkRequested()) {
-		result.parked = true;
-		result.exitCode = 0;
-		result.stopReason = undefined;
-		result.errorMessage = undefined;
-	} else {
-		result.parked = undefined;
-		result.exitCode = 1;
-		result.stopReason = "aborted";
-		result.errorMessage = control.getStopMessage();
-	}
+	result.exitCode = 1;
+	result.stopReason = "aborted";
+	result.errorMessage = control.getStopMessage();
 	return result;
 }
 
 function signalAbortDisposition(options: RunSingleOptions, base: SingleResult): SingleResult | undefined {
 	if (!options.signal?.aborted) return undefined;
-	base.parked = undefined;
 	base.exitCode = 1;
 	base.stopReason = "aborted";
 	base.errorMessage = "Subagent was aborted";
@@ -459,8 +460,17 @@ export async function runSingleAgentWithMainFallback(
 	const startupDelays = customStartupDelays ?? SUBAGENT_STARTUP_RETRY_DELAYS_MS;
 
 	const sessionId = options.sessionId ?? randomUUID();
-	const sessionDir = options.sessionDir ?? (await mkdtemp(join(tmpdir(), "pi-subagent-session-")));
+	const sessionDir = options.sessionDir ?? (await createSessionDir(options.sessionRoot));
 	const baseOptions: RunSingleOptions = { ...options, sessionDir, sessionId };
+	if (!options.sessionDir) {
+		// Surface the fresh session immediately so the dispatching thread can
+		// persist a durable checkpoint before the child settles.
+		try {
+			options.onLive?.({ kind: "session", sessionId, sessionDir });
+		} catch {
+			/* never throw from event handling */
+		}
+	}
 
 	const dispatchFailure = async (error: unknown): Promise<SingleResult> => {
 		const errorMessage = error instanceof Error ? error.message : String(error);
@@ -489,14 +499,7 @@ export async function runSingleAgentWithMainFallback(
 		let retries = 0;
 		for (let attempt = 0; ; attempt++) {
 			const immediate = controlledDisposition(opts);
-			if (immediate) {
-				if (immediate.parked && !options.sessionDir && !sessionExists(sessionDir, sessionId)) {
-					await rm(sessionDir, { recursive: true, force: true }).catch(() => undefined);
-					immediate.sessionId = undefined;
-					immediate.sessionDir = undefined;
-				}
-				return immediate;
-			}
+			if (immediate) return immediate;
 			const start = Date.now();
 			try {
 				const attemptOptions = opts.resolveAgentForAttempt
@@ -510,7 +513,7 @@ export async function runSingleAgentWithMainFallback(
 			const durationMs = Date.now() - start;
 			const controlled = controlledDisposition(opts, lastResult);
 			if (controlled) return controlled;
-			if (lastResult.parked || lastResult.stopReason === "aborted") return lastResult;
+			if (lastResult.stopReason === "aborted") return lastResult;
 			if (!isRetryableStartupFailure(lastResult, durationMs)) {
 				if (retries > 0 && !isFailedResult(lastResult)) lastResult.startupRetries = retries;
 				return lastResult;
@@ -627,7 +630,7 @@ export async function runSingleAgentWithMainFallback(
 		}
 
 		result = await runWithStartupRetry(candidateOptions);
-		if (result.parked || result.stopReason === "aborted") return finish(result);
+		if (result.stopReason === "aborted") return finish(result);
 		if (!isModelLevelFailure(result)) return finish(result);
 		// Any model-level failure advances immediately to the sole fallback (the
 		// current main model). Retain selected-attempt tool diagnostics and usage;

package/src/temp-hygiene.ts

@@ -0,0 +1,194 @@
+/**
+ * Temp hygiene: ownership markers and startup sweeps for the directories this
+ * extension creates.
+ *
+ * Every short-lived temp directory (child prompt/policy files) gets an owner
+ * marker with the creating pid. At extension load, directories whose owner is
+ * dead are removed; unmarked legacy leaks fall back to an age cap. The same
+ * load pass sweeps the durable state root for directories no manifest record
+ * references anymore (crashes between creation and the first record write).
+ *
+ * A live sibling pi instance never loses its directories: `kill(pid, 0)` only
+ * reports "no such process" when the pid genuinely does not exist, so a live
+ * owner always survives the sweep. Pid reuse merely delays cleanup until the
+ * reusing process exits or the age cap catches the directory.
+ */
+
+import { spawn } from "node:child_process";
+import { type Dirent, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const TEMP_OWNER_FILE_NAME = "owner.json";
+
+/** Directories this extension creates in the OS temp dir. Session and
+ * worktree prefixes cover legacy leaks from versions that used tmpdir for
+ * retained state; policy/prompt prefixes cover per-run transient files. */
+const TEMP_DIR_PREFIXES = [
+	"pi-subagent-session-",
+	"pi-subagent-session-fork-",
+	"pi-subagent-worktree-",
+	"pi-subagents-policy-",
+	"pi-subagents-",
+] as const;
+
+/** Owned by pruneResultArtifacts; never swept here. */
+const TEMP_DIR_EXCLUDED_NAMES = new Set(["pi-subagents-results"]);
+
+/** Unmarked directories (legacy leaks) must outlive this age before removal. */
+export const UNMARKED_TEMP_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+/** State-root directories missing from every manifest record (crash between
+ * directory creation and the first record persist) after this age. */
+export const UNREFERENCED_STATE_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+
+interface TempOwner {
+	pid: number;
+	createdAt: number;
+}
+
+export function isProcessAlive(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		// EPERM means the process exists but belongs to another user.
+		return (error as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+
+/** Best-effort marker write; a missing marker only delays cleanup. */
+export function writeTempOwnerMarker(dir: string, now = Date.now()): void {
+	try {
+		writeFileSync(
+			join(dir, TEMP_OWNER_FILE_NAME),
+			`${JSON.stringify({ pid: process.pid, createdAt: now } satisfies TempOwner)}\n`,
+			"utf8",
+		);
+	} catch {
+		/* marker failures must never break the creating operation */
+	}
+}
+
+function readTempOwnerMarker(dir: string): TempOwner | undefined {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dir, TEMP_OWNER_FILE_NAME), "utf8")) as Partial<TempOwner>;
+		if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid <= 0) return undefined;
+		return { pid: parsed.pid, createdAt: typeof parsed.createdAt === "number" ? parsed.createdAt : 0 };
+	} catch {
+		return undefined;
+	}
+}
+
+/** Terminate a whole process tree without waiting. Used on restore for child
+ * processes orphaned by a reload or crash that still hold a retained session. */
+export function killProcessTree(pid: number): void {
+	if (!Number.isInteger(pid) || pid <= 0) return;
+	if (process.platform === "win32") {
+		try {
+			spawn("taskkill", ["/pid", String(pid), "/t", "/f"], {
+				stdio: "ignore",
+				windowsHide: true,
+			}).once("error", () => undefined);
+		} catch {
+			/* the process is gone */
+		}
+		return;
+	}
+	try {
+		process.kill(pid, "SIGKILL");
+	} catch {
+		/* the process is gone */
+	}
+}
+
+export interface SweepOptions {
+	now?: number;
+	/** Injectable pid liveness probe for tests. */
+	isAlive?: (pid: number) => boolean;
+	/** Override the unmarked-directory age cap for tests. */
+	unmarkedMaxAgeMs?: number;
+}
+
+function removeDir(path: string): boolean {
+	try {
+		rmSync(path, { recursive: true, force: true });
+		return true;
+	} catch {
+		// Windows locks (antivirus, indexer) leave the directory for a later sweep.
+		return false;
+	}
+}
+
+function directoryAgeMs(entry: Dirent, dir: string, now: number): number | undefined {
+	try {
+		return now - statSync(join(dir, entry.name)).mtimeMs;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Remove OS-temp directories owned by dead processes plus old unmarked
+ * legacy leaks. Returns how many directories were removed. */
+export function sweepOrphanTempDirs(
+	rootDir: string = tmpdir(),
+	options: SweepOptions = {},
+): number {
+	const now = options.now ?? Date.now();
+	const isAlive = options.isAlive ?? isProcessAlive;
+	const unmarkedMaxAgeMs = options.unmarkedMaxAgeMs ?? UNMARKED_TEMP_MAX_AGE_MS;
+	let entries: Dirent[];
+	try {
+		entries = readdirSync(rootDir, { withFileTypes: true });
+	} catch {
+		return 0;
+	}
+	let removed = 0;
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+		if (TEMP_DIR_EXCLUDED_NAMES.has(entry.name)) continue;
+		if (!TEMP_DIR_PREFIXES.some((prefix) => entry.name.startsWith(prefix))) continue;
+		const path = join(rootDir, entry.name);
+		const owner = readTempOwnerMarker(path);
+		if (owner) {
+			// An unmarked fresh sibling race is impossible here: the marker is
+			// written immediately after mkdtemp. A marked dir dies only with its
+			// owning process.
+			if (isAlive(owner.pid)) continue;
+			if (removeDir(path)) removed++;
+			continue;
+		}
+		const ageMs = directoryAgeMs(entry, rootDir, now);
+		if (ageMs !== undefined && ageMs > unmarkedMaxAgeMs && removeDir(path)) removed++;
+	}
+	return removed;
+}
+
+/** Remove state-root directories no manifest record references. Fresh
+ * directories (a run just created but not yet recorded) are protected by the
+ * age cap, since the sweep only runs at extension load before new work. */
+export function sweepUnreferencedState(
+	stateRoot: string,
+	referencedPaths: ReadonlySet<string>,
+	options: SweepOptions = {},
+): number {
+	const now = options.now ?? Date.now();
+	const maxAgeMs = options.unmarkedMaxAgeMs ?? UNREFERENCED_STATE_MAX_AGE_MS;
+	const pathKey = (path: string): string => (process.platform === "win32" ? path.toLowerCase() : path);
+	const referenced = new Set([...referencedPaths].map(pathKey));
+	let entries: Dirent[];
+	try {
+		entries = readdirSync(stateRoot, { withFileTypes: true });
+	} catch {
+		return 0;
+	}
+	let removed = 0;
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+		const path = join(stateRoot, entry.name);
+		if (referenced.has(pathKey(path))) continue;
+		const ageMs = directoryAgeMs(entry, stateRoot, now);
+		if (ageMs !== undefined && ageMs > maxAgeMs && removeDir(path)) removed++;
+	}
+	return removed;
+}