@ferris1225/pi-subagents 4.1.15 → 4.1.17

package/src/announcements.ts

@@ -1,61 +1,75 @@
-/** Session-start recovery, stale-config migration, and widget installation. */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { existsSync } from "node:fs";
-import { loadConfig, saveConfig } from "./config.ts";
-import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
-import { announceRecoveryRecords } from "./recovery.ts";
-import type { SubagentRuntime } from "./runtime.ts";
-import { pruneResultArtifacts } from "./spawn.ts";
-import { installActiveRunsWidget } from "./widget.ts";
-
-/**
- * One-time-per-stale-override migration: keep agent model selections Pi still
- * reports as available, drop the rest back to dynamic main-model routing, and
- * tell the user what was removed. Saving the cleaned config is what makes it
- * one-time — the dropped refs no longer exist to re-trigger the notice.
- */
-async function migrateUnavailableAgentModels(
-	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } } & Parameters<typeof availableModelsInScope>[0],
-	runtime: SubagentRuntime,
-): Promise<void> {
-	try {
-		const config = await loadConfig(runtime.configPath);
-		const overrides = Object.entries(config.agentModels);
-		if (overrides.length === 0) return;
-		const { kept, dropped } = filterUnavailableModelOverrides(config.agentModels, availableModelsInScope(ctx));
-		if (dropped.length === 0) return;
-		await saveConfig({ ...config, agentModels: kept }, runtime.configPath);
-		const list = dropped.map(({ agent, ref }) => `${agent}: ${ref}`).join(", ");
-		ctx.ui.notify(
-			`pi-subagents: removed stale agent model overrides that are no longer available (${list}). Those agents now follow the current main model; run /subagents-setup to re-pick.`,
-			"warning",
-		);
-	} catch {
-		/* migration failures are non-fatal */
-	}
-}
-
-export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
-	pi.on("session_start", async (_event, ctx) => {
-		pruneResultArtifacts();
-		if (!existsSync(runtime.configPath)) {
-			ctx.ui.notify(
-				"pi-subagents: no configuration yet — run /subagents-setup to pick agents, models, and thinking strengths. Defaults (all five agents on the main model) apply until then.",
-				"info",
-			);
-		}
-		await announceRecoveryRecords(runtime.configPath, ctx);
-		await migrateUnavailableAgentModels(ctx, runtime);
-		if (!runtime.restoredNotified && runtime.restoredRunIds.length > 0) {
-			runtime.restoredNotified = true;
-			const ids = runtime.restoredRunIds.map((id) => `#${id}`).join(", ");
-			ctx.ui.notify(
-				`pi-subagents: restored ${runtime.restoredRunIds.length} interrupted thread${runtime.restoredRunIds.length === 1 ? "" : "s"} from the previous session (${ids}). subagent_status lists them; subagent_control resume continues one.`,
-				"info",
-			);
-		}
-		if (ctx.mode !== "tui") return;
-		installActiveRunsWidget(ctx);
-	});
-}
+/** Session-start recovery, stale-config migration, and widget installation. */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { loadConfig, saveConfig } from "./config.ts";
+import { availableModelsInScope, filterUnavailableModelOverrides } from "./models.ts";
+import { announceRecoveryRecords } from "./recovery.ts";
+import type { SubagentRuntime } from "./runtime.ts";
+import { installActiveRunsWidget } from "./widget.ts";
+
+/**
+ * One-time-per-stale-override migration: keep agent model selections Pi still
+ * reports as available, drop the rest back to dynamic main-model routing, and
+ * tell the user what was removed. Saving the cleaned config is what makes it
+ * one-time — the dropped refs no longer exist to re-trigger the notice.
+ */
+async function migrateUnavailableAgentModels(
+	ctx: { ui: { notify: (message: string, kind: "info" | "warning" | "error") => void } } & Parameters<typeof availableModelsInScope>[0],
+	runtime: SubagentRuntime,
+): Promise<void> {
+	try {
+		const config = await loadConfig(runtime.configPath);
+		const overrides = Object.entries(config.agentModels);
+		if (overrides.length === 0) return;
+		const { kept, dropped } = filterUnavailableModelOverrides(config.agentModels, availableModelsInScope(ctx));
+		if (dropped.length === 0) return;
+		await saveConfig({ ...config, agentModels: kept }, runtime.configPath);
+		const list = dropped.map(({ agent, ref }) => `${agent}: ${ref}`).join(", ");
+		ctx.ui.notify(
+			`pi-subagents: removed stale agent model overrides that are no longer available (${list}). Those agents now follow the current main model; run /subagents-setup to re-pick.`,
+			"warning",
+		);
+	} catch {
+		/* migration failures are non-fatal */
+	}
+}
+
+export function registerAnnouncements(pi: ExtensionAPI, runtime: SubagentRuntime): void {
+	pi.on("session_start", async (_event, ctx) => {
+		if (!existsSync(runtime.configPath)) {
+			ctx.ui.notify(
+				"pi-subagents: no configuration yet — run /subagents-setup to pick agents, models, and thinking strengths. Defaults (all five agents on the main model) apply until then.",
+				"info",
+			);
+		}
+		await announceRecoveryRecords(runtime.configPath, ctx);
+		await migrateUnavailableAgentModels(ctx, runtime);
+		if (!runtime.restoredNotified && runtime.restoredRunIds.length > 0) {
+			runtime.restoredNotified = true;
+			const ids = runtime.restoredRunIds.map((id) => `#${id}`).join(", ");
+			ctx.ui.notify(
+				`pi-subagents: restored ${runtime.restoredRunIds.length} interrupted thread${runtime.restoredRunIds.length === 1 ? "" : "s"} from the previous session (${ids}). subagent_status lists them; subagent_control resume continues one.`,
+				"info",
+			);
+		}
+		if (ctx.mode !== "tui") return;
+		installActiveRunsWidget(ctx);
+	});
+
+	// Compaction failures are otherwise silent in long orchestration sessions
+	// where subagent results accumulate; aborted (user-cancelled) compactions
+	// are deliberate and not worth a notice.
+	pi.on("session_compact_failed", async (event, ctx) => {
+		if (event.aborted && !event.errorMessage) return;
+		const detail = event.errorMessage ? `: ${event.errorMessage}` : "";
+		if (event.willRetry) {
+			ctx.ui.notify(`pi-subagents: session compaction failed${detail} — retrying automatically.`, "warning");
+			return;
+		}
+		ctx.ui.notify(
+			`pi-subagents: session compaction failed${detail}. Long threads may hit context limits soon; run /compact to retry or trim old results.`,
+			"error",
+		);
+	});
+}

package/src/background.ts

@@ -9,7 +9,9 @@
  * the user and the main agent instead of it vanishing into the queue.
  */
 
-export type BackgroundTask = (signal: AbortSignal) => Promise<void>;
+import { cpus } from "node:os";
+
+export type BackgroundTask = (signal: AbortSignal, controller: AbortController) => Promise<void>;
 
 interface PendingTask {
 	task: BackgroundTask;
@@ -27,13 +29,14 @@ interface PendingTask {
 	onError?: (error: unknown) => void | Promise<void>;
 }
 
-/** How many sub-agent processes may run at once. This paces execution only —
- * it never rejects work, so a wider parallel `subagent` call simply queues.
- * Fixed by design: the queue sheds load by waiting, so the knob bought nothing
- * worth its maintenance. Only manually dispatched top-level generations hold
- * slots; runtime-initiated managed continuations (gate reviews, documentation
- * sync) suspend their task's slot so they never starve manual dispatches. */
-export const MAX_CONCURRENT_SUBAGENTS = 4;
+/** How many sub-agent processes may run at once, derived from the host instead
+ * of being fixed: children wait on model I/O far more than on CPU, so the pool
+ * scales with cores while the bounds keep tiny machines usable and huge ones
+ * from fanning out into an API-rate-limit wall. Pacing only — the queue never
+ * rejects work; a wider parallel `subagent` call simply waits for a slot. */
+export function resolveSubagentConcurrency(cpuCount: number = cpus().length): number {
+	return Math.min(16, Math.max(4, Math.floor(cpuCount / 2)));
+}
 
 export class BackgroundTaskQueue {
 	private concurrency: number;
@@ -77,9 +80,22 @@ export class BackgroundTaskQueue {
 		return this.completions.get(controller) ?? Promise.resolve();
 	}
 
+	/** Slot count, exposed so dispatch/status output can state the real pacing
+	 * limit instead of leaving queued work looking like an unexplained cap. */
+	get capacity(): number {
+		return this.concurrency;
+	}
+
 	/** Stop counting a running task toward the concurrency limit. Its body keeps
 	 * running under the same abort signal; completion still releases everything
-	 * waitForTask/waitForIdle promise. Frees a slot for queued work immediately. */
+	 * waitForTask/waitForIdle promise. Frees a slot for queued work immediately.
+	 *
+	 * Used by tasks whose execution is serialized elsewhere anyway (managed
+	 * workflow continuations, shared-checkout writers waiting on the repository
+	 * lane): letting such a task also hold a global slot would let waiters
+	 * starve independent work that could start right away. The controller is
+	 * handed to the task body directly, so a task can always suspend itself
+	 * without racing the enqueue() caller's assignment. */
 	suspend(controller: AbortController | undefined): void {
 		if (!controller || this.stopped) return;
 		if (!this.active.delete(controller)) return;
@@ -149,7 +165,7 @@ export class BackgroundTaskQueue {
 			}
 
 			this.active.add(entry.controller);
-			void entry.task(entry.controller.signal)
+			void entry.task(entry.controller.signal, entry.controller)
 				.catch(async (error: unknown) => {
 					// Cancellation is not a failure: aborted work (e.g. session
 					// shutdown) must never be reported as an exception.

package/src/completion.ts

@@ -139,6 +139,9 @@ export interface ActiveRunFoot {
 	agent: string;
 	/** Optional content label (task-derived) shown next to the agent name. */
 	label?: string;
+	/** True when the run is waiting for a free process slot rather than
+	 * executing; stated so pacing is never mistaken for a stall. */
+	queued?: boolean;
 }
 
 /**
@@ -153,7 +156,10 @@ export function formatActiveRunsFooter(runs: readonly ActiveRunFoot[], maxListed
 	if (runs.length === 0) return "";
 	const listed = runs.slice(0, maxListed);
 	const items = listed
-		.map((run) => `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}`)
+		.map((run) => {
+			const tagged = run.queued ? " (queued, starts when a slot frees)" : "";
+			return `#${run.id} ${run.agent}${run.label ? `·${run.label}` : ""}${tagged}`;
+		})
 		.join(", ");
 	const more = runs.length > listed.length ? `, +${runs.length - listed.length} more` : "";
 	return `\n\n⚠ ${runs.length} other run${runs.length === 1 ? "" : "s"} still active: ${items}${more}. Do not conclude the overall task yet — wait for their results (they wake you automatically) or check subagent_status.`;

package/src/dispatch.ts

@@ -9,10 +9,9 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { Type } from "typebox";
-import { discoverAgents, resolveAgentTools, type AgentConfig } from "./agents.ts";
-import { getStateRoot } from "./durable.ts";
+import { discoverAgents, isWriteCapableAgent, resolveAgentTools, type AgentConfig } from "./agents.ts";
 import { loadConfig } from "./config.ts";
 import { formatUsage, queuedResult } from "./format.ts";
 import {
@@ -35,6 +34,7 @@ import {
 import type { SubagentRuntime } from "./runtime.ts";
 import { persistThreadCheckpoint } from "./thread-lifecycle.ts";
 import {
+	getProjectRoot,
 	getResultOutput,
 	isFailedResult,
 	reviewVerdict,
@@ -84,9 +84,23 @@ const SubagentParams = Type.Object({
 	isolation: IsolationSchema,
 });
 
-export function defaultIsolationMode(mode: "single" | "parallel", agentName: string, requested?: IsolationMode): IsolationMode {
+/** Roles that default to worktree isolation in parallel dispatches even when
+ * the live catalog cannot be consulted (render-only call sites). Custom
+ * write-capable agents join them via isWriteCapableAgent on the execute path. */
+const WORKTREE_DEFAULT_AGENTS = new Set(["worker", "cleaner", "documenter"]);
+
+/** Resolve the default isolation for a dispatch. Parallel write-capable agents
+ * get a detached worktree: shared writers serialize on the repository lane, so
+ * defaulting them to shared would turn one parallel batch into a convoy that
+ * also parks process slots. Explicit requests always win. */
+export function defaultIsolationMode(
+	mode: "single" | "parallel",
+	agentName: string,
+	requested?: IsolationMode,
+	writeCapable = WORKTREE_DEFAULT_AGENTS.has(agentName),
+): IsolationMode {
 	if (requested) return requested;
-	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
+	return mode === "parallel" && writeCapable ? "worktree" : "shared";
 }
 
 function workflowStageStatus(result: SingleResult, relation?: string): WorkflowStageStatus {
@@ -100,12 +114,13 @@ function workflowStageStatus(result: SingleResult, relation?: string): WorkflowS
 
 /** The runtime-granted write continuation of a failed gate: same reviewer
  * role, model, and retained session, but the read-only boundary is lifted for
- * this one stage so it applies its own fix instructions. */
+ * this one stage so it applies its own fix instructions. One line only: the
+ * full fix-stage contract is already in the retained session's prompt. */
 function withReviewerFixStageAgent(agent: AgentConfig): AgentConfig {
 	return {
 		...agent,
 		tools: undefined,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\nRuntime workflow context: FIX STAGE — your gate just returned REVIEW_FAIL. Your read-only boundary is lifted for this stage only: apply your own fix instructions exactly as you specified them, run the narrowest decisive checks, and report what changed. Never edit during a review and never emit a verdict in a fix stage.`,
+		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\nRuntime workflow context: FIX STAGE — your gate just returned REVIEW_FAIL. Your read-only boundary is lifted for this stage only: apply your own fix instructions exactly as specified, verify, and report what changed; never edit during a review and never emit a verdict here.`,
 	};
 }
 
@@ -187,6 +202,17 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		(mode: "single" | "parallel", background = false) =>
 		(results: SingleResult[]): SubagentDetails => ({ mode, results, background });
 
+	/** Pacing note appended to dispatch confirmations whenever runs are actually
+	 * waiting: states the real slot capacity so ordinary queueing is never
+	 * mistaken for a hard dispatch limit. Empty when everything is running. */
+	const queuePacingNote = (): string => {
+		const runs = monitor.getRuns();
+		const waiting = runs.filter((run) => run.status === "queued").length;
+		if (waiting === 0) return "";
+		const running = runs.filter((run) => run.status === "running" || run.status === "interrupting").length;
+		return ` Pacing: ${running} running · ${waiting} waiting for a free process slot (capacity ${runtime.backgroundQueue.capacity}); waiting runs start automatically as slots free — keep dispatching independent units.`;
+	};
+
 	/** Launch one workflow-internal child in a fresh model context. It sees the
 	 * parent's exact repository/worktree state and is registered by its own id,
 	 * but never enters top-level lifecycle policy or completion delivery.
@@ -240,7 +266,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					onLive,
 					makeDetails: makeDetails("single", true),
 					idleTimeoutMs: stageConfig.idleTimeoutSec * 1000,
-					sessionRoot: getStateRoot(runtime.configPath),
+					sessionRoot: join(getProjectRoot(runtime.configPath, request.executionCwd), "sessions"),
 					...(stage.session
 						? { sessionId: stage.session.sessionId, sessionDir: stage.session.sessionDir, stdinText: task }
 						: {}),
@@ -372,10 +398,9 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					"final review",
 					reviewStage,
 				);
-				// The failing gate owns its fixes until it passes: the same retained
+				// The failing gate owns its fixes: the same retained
 				// reviewer session applies its own fix instructions with write access,
-				// then a fresh gate re-scans the complete diff. Nobody outside the
-				// loop has to guess what satisfies the gate; the cap only stops
+				// then a converging re-review verifies the fixes. The cap only stops
 				// pathological burn and hands the still-failing gate to the main agent.
 				for (let round = 1; round <= MAX_REVIEW_FIX_ROUNDS; round++) {
 					const gateSession = gateReview.sessionId && gateReview.sessionDir
@@ -430,8 +455,9 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		label: "Subagent",
 		description: [
 			"Dispatch enabled agents as isolated leaf Pi child processes, singly or in parallel. Dispatching never blocks your turn — runs proceed in the background and each completion resumes you automatically; never poll or restate delivered results.",
-			"Put every genuinely independent unit in one `tasks` array (no per-call cap; extras queue for a free process slot). Single tasks share the checkout; parallel workers default to detached Git worktrees — write-capable agents only, and setup failure never silently falls back to shared.",
-			"Successful worker/cleaner runs get one automatic reviewer gate; a failing gate is fixed by the reviewer itself in a write-enabled continuation of the same session and re-reviewed until it passes. A REVIEW_FAIL from a gate you dispatched directly returns its findings to you — fix them inline or via a briefed worker without waiting for the user.",
+			"Put every genuinely independent unit in one `tasks` array (no per-call cap). Process slots scale with the machine; when all slots are busy the extra runs simply wait and start automatically as slots free — waiting is pacing, never a rejection or a limit on how much you may dispatch.",
+			"Every parallel write-capable agent (worker, cleaner, documenter, custom writers) defaults to a detached Git worktree, so writers run concurrently; shared mode serializes same-repository writers. Explicit `shared` keeps the caller's checkout; setup failure never silently falls back to shared.",
+			"Successful worker/cleaner runs get one automatic reviewer gate; a failing gate is fixed by the reviewer itself in a write-enabled continuation of the same session and re-reviewed in bounded, converging rounds. A REVIEW_FAIL from a gate you dispatched directly returns its findings to you — fix them inline or via a briefed worker without waiting for the user.",
 			"A configured child-model failure continues the retained session on the current main model. Resume a parked or settled thread with subagent_control by run id; use subagent_stop for destructive cancellation.",
 		].join(" "),
 		promptSnippet:
@@ -504,11 +530,17 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				// Preserve caller order (and deterministic completion batching) while
 				// preparing each isolated filesystem before its queue entry can start.
 				for (const item of params.tasks) {
+					const catalogAgent = agents.find((candidate) => candidate.name === item.agent);
 					results.push(await startBackground(
 						item.agent,
 						item.task,
 						item.cwd,
-						defaultIsolationMode("parallel", item.agent, item.isolation as IsolationMode | undefined),
+						defaultIsolationMode(
+							"parallel",
+							item.agent,
+							item.isolation as IsolationMode | undefined,
+							catalogAgent ? isWriteCapableAgent(catalogAgent) : undefined,
+						),
 					));
 				}
 				const startedRuns = results.filter((result) => result.exitCode === -1);
@@ -533,7 +565,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					...(failureLines.length > 0
 						? [`${failureLines.length} task${failureLines.length === 1 ? "" : "s"} failed before launch:`, ...failureLines]
 						: []),
-				].join("\n");
+				].join("\n") + queuePacingNote();
 				return {
 					content: [{ type: "text", text }],
 					details: makeDetails("parallel", true)(results),
@@ -551,7 +583,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			}
 			const runRef = result.runId === undefined ? result.agent : `#${result.runId} ${result.agent}`;
 			return {
-				content: [{ type: "text", text: `Started ${runRef} in the background. It never blocks you — dispatch more independent units now or keep working; its result resumes you automatically when you are idle.` }],
+				content: [{ type: "text", text: `Started ${runRef} in the background. It never blocks you — dispatch more independent units now or keep working; its result resumes you automatically when you are idle.${queuePacingNote()}` }],
 				details: makeDetails("single", true)([result]),
 			};
 

package/src/durable.ts

@@ -13,13 +13,14 @@
  */
 
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
-import { existsSync } from "node:fs";
+import { existsSync, type Dirent, readdirSync, statSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { UsageStats } from "./rpc-run.ts";
 import type { SubagentThread } from "./runtime.ts";
-import { getResultOutput, isFailedResult, type SingleResult } from "./spawn.ts";
+import { getResultOutput, isFailedResult, getProjectRoot, PROJECT_ROOTS_DIR_NAME, type SingleResult } from "./spawn.ts";
 import {
+	isPathInside,
 	restoreWorktreeIsolation,
 	type IsolationMode,
 	normalizeWorktreeSnapshot,
@@ -29,7 +30,12 @@ import {
 
 export const THREADS_MANIFEST_FILE_NAME = "pi-subagents-threads.json";
 const THREADS_MANIFEST_VERSION = 1;
-export const STATE_DIR_NAME = "pi-subagents-state";
+
+/** Project directories whose newest file has not been touched for this long
+ * are deleted wholesale on load, so per-project sessions/worktrees/results
+ * can never accumulate forever. Parked threads' manifest references always
+ * win over the age rule. */
+export const PROJECT_ROOT_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1_000;
 
 /** Fixed retention: parked work (which may hold unintegrated changes) stops
  * being resumable after a month. Older manifests may still carry settled
@@ -76,10 +82,6 @@ interface ThreadsManifest {
 	records: ThreadRecord[];
 }
 
-export function getStateRoot(configPath: string): string {
-	return join(dirname(configPath), STATE_DIR_NAME);
-}
-
 export function getThreadsManifestPath(configPath: string): string {
 	return join(dirname(configPath), THREADS_MANIFEST_FILE_NAME);
 }
@@ -335,3 +337,66 @@ export function referencedDurablePaths(records: readonly ThreadRecord[]): Set<st
 	}
 	return paths;
 }
+
+/** Newest modification time anywhere under root (directories count via their
+ * own entries); undefined when root cannot be read. */
+function newestMtimeMs(root: string, now: number = Date.now()): number | undefined {
+	let newest: number | undefined;
+	const stack: string[] = [root];
+	while (stack.length > 0) {
+		const dir = stack.pop()!;
+		let entries: Dirent[];
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const path = join(dir, entry.name);
+			let mtime: number;
+			try {
+				mtime = statSync(path).mtimeMs;
+			} catch {
+				continue;
+			}
+			if (mtime > 0 && mtime <= now && (newest === undefined || mtime > newest)) newest = mtime;
+			if (entry.isDirectory() && !entry.isSymbolicLink()) stack.push(path);
+		}
+	}
+	return newest;
+}
+
+/** Delete project directories under the ferris-pi-subagents root that have
+ * been idle past PROJECT_ROOT_MAX_AGE_MS. A directory containing any path the
+ * threads manifest still references is never touched, so parked work outlives
+ * the age rule. Returns the removed directory names. */
+export async function pruneStaleProjectRoots(configPath: string, options: { now?: number } = {}): Promise<string[]> {
+	const now = options.now ?? Date.now();
+	const records = await readThreadRecords(configPath).catch(() => [] as ThreadRecord[]);
+	const referenced = referencedDurablePaths(records);
+	const root = join(dirname(configPath), PROJECT_ROOTS_DIR_NAME);
+	let projects: Dirent[];
+	try {
+		projects = readdirSync(root, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const removed: string[] = [];
+	for (const project of projects) {
+		if (!project.isDirectory() || project.isSymbolicLink()) continue;
+		const projectDir = join(root, project.name);
+		if (containsReferencedPath(projectDir, referenced)) continue;
+		const newest = newestMtimeMs(projectDir, now);
+		if (newest === undefined || now - newest <= PROJECT_ROOT_MAX_AGE_MS) continue;
+		await rm(projectDir, { recursive: true, force: true }).catch(() => undefined);
+		if (!existsSync(projectDir)) removed.push(project.name);
+	}
+	return removed;
+}
+
+function containsReferencedPath(projectDir: string, referenced: ReadonlySet<string>): boolean {
+	for (const path of referenced) {
+		if (isPathInside(projectDir, path)) return true;
+	}
+	return false;
+}