@ferris1225/pi-subagents 4.3.5 → 4.3.7

package/src/execution/rpc-run.ts

@@ -17,6 +17,7 @@ import { SUBAGENT_TOOL_NAMES, type AgentConfig } from "../delegation/agents.ts";
 import type { ThinkingLevel } from "../configuration/config.ts";
 import { writeTempOwnerMarker } from "../isolation/temp-hygiene.ts";
 import {
+	asPlainTextRpcPrompt,
 	emptyUsage,
 	RpcRunControl,
 	type AttemptControl,
@@ -25,6 +26,8 @@ import {
 	type SubagentLiveEvent,
 } from "./rpc-control.ts";
 
+export { asPlainTextRpcPrompt };
+
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
 export const SUBAGENT_KILL_GRACE_MS = 5_000;
 /** ACK budget after the child is known to be reading RPC. */
@@ -33,6 +36,8 @@ export const RPC_COMMAND_TIMEOUT_MS = 30_000;
 /** clear_queue is stop-path hygiene ahead of the abort: give it its own short
  * budget so a hung response cannot eat into the abort-settle window. */
 const RPC_CLEAR_QUEUE_TIMEOUT_MS = 2_000;
+/** Keep logical stop responsive when a steering ACK is lost. */
+const RPC_STEER_ACK_TIMEOUT_MS = 2_000;
 /** Time allowed for the child to boot and answer get_state. */
 export const RPC_READY_TIMEOUT_MS = 60_000;
 export const RPC_ABORT_SETTLE_TIMEOUT_MS = 5_000;
@@ -41,14 +46,6 @@ export function isRpcCommandTimeoutError(message?: string): boolean {
 	return typeof message === "string" && message.includes("Timed out waiting for RPC response");
 }
 
-/** Prevent RPC prompt expansion when a control objective itself starts with
- * slash (for example `/subagents-setup`). The original text stays verbatim
- * below a non-command prefix and therefore always starts a model turn. */
-export function asPlainTextRpcPrompt(message: string): string {
-	if (!message.trimStart().startsWith("/")) return message;
-	return `Treat the following as plain-text sub-agent instructions, not a Pi command:\n\n${message}`;
-}
-
 export function currentSubagentDepth(env: NodeJS.ProcessEnv = process.env): number {
 	const raw = env[DEPTH_ENV_VAR];
 	const parsed = raw === undefined ? 0 : Number.parseInt(raw, 10);
@@ -452,29 +449,24 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 			});
 		});
 
-	const send = async (command: Record<string, unknown>, timeoutMs = commandTimeoutMs): Promise<RpcResponse> => {
+	const send = async <T extends { type: string }>(command: T, timeoutMs = commandTimeoutMs): Promise<RpcResponse> => {
 		if (finished || closed) throw new Error("Subagent RPC process is no longer active.");
 		const id = `req_${++requestId}`;
 		const payload = { ...command, id };
 		return new Promise<RpcResponse>((resolve, reject) => {
 			const pending: PendingRequest = { resolve, reject };
+			pending.timer = setTimeout(() => {
+				pendingRequests.delete(id);
+				reject(new Error(`Timed out waiting for RPC response to ${String(command.type)}.`));
+			}, timeoutMs);
+			if (typeof pending.timer.unref === "function") pending.timer.unref();
 			pendingRequests.set(id, pending);
-			void writeLine(payload).then(
-				() => {
-					if (!pendingRequests.has(id)) return;
-					pending.timer = setTimeout(() => {
-						pendingRequests.delete(id);
-						reject(new Error(`Timed out waiting for RPC response to ${String(command.type)}.`));
-					}, timeoutMs);
-					if (typeof pending.timer.unref === "function") pending.timer.unref();
-				},
-				(error) => {
-					if (!pendingRequests.has(id)) return;
-					pendingRequests.delete(id);
-					if (pending.timer) clearTimeout(pending.timer);
-					reject(error instanceof Error ? error : new Error(String(error)));
-				},
-			);
+			void writeLine(payload).catch((error) => {
+				if (!pendingRequests.has(id)) return;
+				pendingRequests.delete(id);
+				if (pending.timer) clearTimeout(pending.timer);
+				reject(error instanceof Error ? error : new Error(String(error)));
+			});
 		}).then((response) => {
 			if (!response.success) {
 				throw new RpcCommandRejectedError(response.error || `RPC ${response.command} failed.`);
@@ -537,6 +529,9 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 	};
 
 	const attemptControl: AttemptControl = {
+		async steer(command): Promise<void> {
+			await send(command, RPC_STEER_ACK_TIMEOUT_MS);
+		},
 		async stop(reason = "Subagent was aborted"): Promise<void> {
 			if (finished) {
 				if (!closed) await processClosed.promise;
@@ -792,7 +787,10 @@ export async function runRpcAgentAttempt(options: RunRpcAttemptOptions): Promise
 
 	if (signal) {
 		abortHandler = () => {
-			void attemptControl.stop("Subagent was aborted").catch(() => undefined);
+			const stopping = control
+				? control.stop("Subagent was aborted")
+				: attemptControl.stop("Subagent was aborted");
+			void stopping.catch(() => undefined);
 		};
 		if (signal.aborted) abortHandler();
 		else signal.addEventListener("abort", abortHandler, { once: true });

package/src/execution/spawn.ts

@@ -344,8 +344,21 @@ export function getResultOutput(result: SingleResult): string {
 	return getFinalOutput(result.messages) || "(no output)";
 }
 
+/** Continuation rules shared by every resume flavor. The workspace clause is
+ * what keeps a retained context from becoming a liability: a parked or settled
+ * thread may return after main integrated sibling worktrees or edited the tree
+ * itself, so a file read in an earlier generation is not proof of its content. */
+const RESUME_CONTINUATION_RULES =
+	"Your earlier work — searches, reads, edits, and reasoning — is preserved in this session's history above; review it before acting. Do not redo searches, reads, or edits that already succeeded. The workspace may have changed while this thread was inactive: before editing a file, re-read it unless you read it during this continuation. Finish with the result-only handoff your role requires.";
+
 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.`;
+	return `You are resuming an earlier sub-agent session after ${reason}. ${RESUME_CONTINUATION_RULES} Current objective: ${task}. Pick up exactly where you left off and finish it. Continue now.`;
+}
+
+/** A resume with an appended objective continues the same thread: the new
+ * objective is guidance layered on retained context, not a restart. */
+export function buildAppendedObjectivePrompt(previousTask: string, objective: string): string {
+	return `You are continuing an earlier sub-agent session with an appended objective from the parent. ${RESUME_CONTINUATION_RULES} Previous objective: ${previousTask}. Appended objective: ${objective}. Complete the appended objective on top of the work already done, without restarting from scratch. Continue now.`;
 }
 
 /** Create a fresh private session directory under the given root. The owner
@@ -440,12 +453,7 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 	const disposition = controlledDisposition(options);
 	if (disposition) return disposition;
 	const objective = control?.getObjective() ?? options.task;
-	let prompt = options.stdinText ?? `Task: ${objective}`;
-	if (control && objective !== options.task) {
-		prompt = options.sessionDir && sessionExists(options.sessionDir, options.sessionId ?? "")
-			? `Abandon the previous objective. New objective: ${objective}`
-			: `Task: ${objective}`;
-	}
+	const prompt = options.stdinText ?? `Task: ${objective}`;
 	const result = await runRpcAgentAttempt({
 		defaultCwd: options.defaultCwd,
 		agent,

package/src/isolation/managed-paths.ts

@@ -0,0 +1,145 @@
+/** Canonical filesystem guards for paths recovered from durable manifests. */
+
+import { existsSync } from "node:fs";
+import { lstat, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { getProjectRoot, getSubagentsRoot } from "../execution/spawn.ts";
+
+const SESSION_DIR_NAME = /^pi-subagent-session-(?:fork-)?.+$/i;
+const WORKTREE_DIR_NAME = /^pi-subagent-worktree-.+$/i;
+const PROJECT_DIR_NAME = /^.+-[0-9a-f]{12}$/i;
+
+function comparable(path: string): string {
+	const normalized = resolve(path);
+	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function isCanonicalAbsolute(path: string): boolean {
+	return isAbsolute(path) && path === resolve(path);
+}
+
+export function samePath(left: string, right: string): boolean {
+	return comparable(left) === comparable(right);
+}
+
+async function isPlainPath(path: string, kind: "directory" | "file"): Promise<boolean> {
+	try {
+		const entry = await lstat(path);
+		return !entry.isSymbolicLink() && (kind === "directory" ? entry.isDirectory() : entry.isFile());
+	} catch {
+		return false;
+	}
+}
+
+async function isDirectRealChild(root: string, candidate: string): Promise<boolean> {
+	try {
+		const [realRoot, realCandidate] = await Promise.all([realpath(root), realpath(candidate)]);
+		return samePath(dirname(realCandidate), realRoot);
+	} catch {
+		return false;
+	}
+}
+
+async function isManagedDirectory(
+	root: string,
+	candidate: string,
+	namePattern: RegExp,
+): Promise<boolean> {
+	if (!isCanonicalAbsolute(candidate) || !samePath(dirname(candidate), root) || !namePattern.test(basename(candidate))) {
+		return false;
+	}
+	if (!existsSync(candidate)) return true;
+	return await isPlainPath(candidate, "directory") && await isDirectRealChild(root, candidate);
+}
+
+async function isManagedContainer(root: string, candidate: string, name: string): Promise<boolean> {
+	if (!samePath(candidate, join(root, name))) return false;
+	if (!existsSync(candidate)) return true;
+	return await isPlainPath(candidate, "directory") && await isDirectRealChild(root, candidate);
+}
+
+async function hasCanonicalProjectRoot(configPath: string, cwd: string, projectRoot: string): Promise<boolean> {
+	const subagentsRoot = getSubagentsRoot(configPath);
+	if (!samePath(projectRoot, getProjectRoot(configPath, cwd))) return false;
+	if (!isAbsolute(projectRoot) || !samePath(dirname(projectRoot), subagentsRoot)) return false;
+	if (!existsSync(projectRoot)) return true;
+	return await isPlainPath(projectRoot, "directory") && await isDirectRealChild(subagentsRoot, projectRoot);
+}
+
+export async function isManagedSessionDir(
+	configPath: string,
+	cwd: string,
+	sessionDir: string,
+): Promise<boolean> {
+	const projectRoot = getProjectRoot(configPath, cwd);
+	if (!await hasCanonicalProjectRoot(configPath, cwd, projectRoot)) return false;
+	const sessionsRoot = join(projectRoot, "sessions");
+	if (!await isManagedContainer(projectRoot, sessionsRoot, "sessions")) return false;
+	return isManagedDirectory(sessionsRoot, sessionDir, SESSION_DIR_NAME);
+}
+
+export interface PersistedWorktreePaths {
+	cwd: string;
+	worktreePath: string;
+	tempDir: string;
+	patchPath: string;
+}
+
+export async function isManagedWorktreeLayout(
+	configPath: string,
+	cwd: string,
+	worktree: PersistedWorktreePaths,
+): Promise<boolean> {
+	const projectRoot = getProjectRoot(configPath, cwd);
+	if (!await hasCanonicalProjectRoot(configPath, cwd, projectRoot)) return false;
+	const worktreesRoot = join(projectRoot, "worktrees");
+	if (!await isManagedContainer(projectRoot, worktreesRoot, "worktrees")) return false;
+	if (!await isManagedDirectory(worktreesRoot, worktree.tempDir, WORKTREE_DIR_NAME)) return false;
+	if (!isCanonicalAbsolute(worktree.worktreePath) || !samePath(worktree.worktreePath, join(worktree.tempDir, "worktree"))) return false;
+	if (!isCanonicalAbsolute(worktree.patchPath) || !samePath(worktree.patchPath, join(worktree.tempDir, "changes.patch"))) return false;
+	if (!isCanonicalAbsolute(worktree.cwd)) return false;
+	if (existsSync(worktree.worktreePath)) {
+		if (!await isPlainPath(worktree.worktreePath, "directory")) return false;
+		if (!await isDirectRealChild(worktree.tempDir, worktree.worktreePath)) return false;
+	}
+	if (existsSync(worktree.patchPath)) {
+		if (!await isPlainPath(worktree.patchPath, "file")) return false;
+		if (!await isDirectRealChild(worktree.tempDir, worktree.patchPath)) return false;
+	}
+	return true;
+}
+
+/** Return a recovery group only when every persisted artifact has the fixed
+ * `<root>/<project>/worktrees/<group>/{worktree,changes.patch}` shape. Existing
+ * path components must also stay inside that shape after junction resolution. */
+export async function managedRecoveryGroup(
+	configPath: string,
+	paths: { worktreePath?: string; patchPath?: string },
+): Promise<string | undefined> {
+	if (paths.worktreePath && !isCanonicalAbsolute(paths.worktreePath)) return undefined;
+	if (paths.patchPath && !isCanonicalAbsolute(paths.patchPath)) return undefined;
+	const fromWorktree = paths.worktreePath ? dirname(paths.worktreePath) : undefined;
+	const fromPatch = paths.patchPath ? dirname(paths.patchPath) : undefined;
+	const group = fromWorktree ?? fromPatch;
+	if (!group || (fromWorktree && fromPatch && !samePath(fromWorktree, fromPatch))) return undefined;
+	if (paths.worktreePath && !samePath(paths.worktreePath, join(group, "worktree"))) return undefined;
+	if (paths.patchPath && !samePath(paths.patchPath, join(group, "changes.patch"))) return undefined;
+	const worktreesRoot = dirname(group);
+	const projectRoot = dirname(worktreesRoot);
+	const subagentsRoot = getSubagentsRoot(configPath);
+	if (!samePath(worktreesRoot, join(projectRoot, "worktrees")) || !samePath(dirname(projectRoot), subagentsRoot)) {
+		return undefined;
+	}
+	if (!await isManagedDirectory(subagentsRoot, projectRoot, PROJECT_DIR_NAME)) return undefined;
+	if (!await isManagedContainer(projectRoot, worktreesRoot, "worktrees")) return undefined;
+	if (!await isManagedDirectory(worktreesRoot, group, WORKTREE_DIR_NAME)) return undefined;
+	if (paths.worktreePath && existsSync(paths.worktreePath)) {
+		if (!await isPlainPath(paths.worktreePath, "directory")) return undefined;
+		if (!await isDirectRealChild(group, paths.worktreePath)) return undefined;
+	}
+	if (paths.patchPath && existsSync(paths.patchPath)) {
+		if (!await isPlainPath(paths.patchPath, "file")) return undefined;
+		if (!await isDirectRealChild(group, paths.patchPath)) return undefined;
+	}
+	return group;
+}

package/src/isolation/recovery.ts

@@ -6,7 +6,8 @@ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { getSubagentsRoot } from "../execution/spawn.ts";
-import { removeWorktreeGroup, worktreeGroupDir, type WorktreeFinalization } from "./worktree.ts";
+import { managedRecoveryGroup } from "./managed-paths.ts";
+import { removeWorktreeGroup, type WorktreeFinalization } from "./worktree.ts";
 
 export const RECOVERY_MANIFEST_FILE_NAME = "pi-subagents-recovery.json";
 const RECOVERY_MANIFEST_VERSION = 1;
@@ -15,7 +16,7 @@ export interface RecoveryRecord {
 	runId: number;
 	createdAt: number;
 	integrated: boolean;
-	/** Repository a cleanup retry can prune stale worktree metadata against. */
+	/** Legacy diagnostic metadata; cleanup authorization comes only from managed paths. */
 	originalRoot?: string;
 	worktreePath?: string;
 	patchPath?: string;
@@ -49,38 +50,62 @@ function normalizeRecord(value: unknown): RecoveryRecord | undefined {
 
 interface RecoveryManifestRead {
 	valid: boolean;
+	sourceCount: number;
 	records: RecoveryRecord[];
 }
 
 async function readManifest(path: string): Promise<RecoveryManifestRead> {
 	try {
 		const parsed = JSON.parse(await readFile(path, "utf8")) as { records?: unknown };
-		if (!Array.isArray(parsed.records)) return { valid: false, records: [] };
+		if (!Array.isArray(parsed.records)) return { valid: false, sourceCount: 0, records: [] };
 		return {
 			valid: true,
+			sourceCount: parsed.records.length,
 			records: parsed.records.flatMap((record) => {
 				const normalized = normalizeRecord(record);
 				return normalized ? [normalized] : [];
 			}),
 		};
 	} catch {
-		return { valid: false, records: [] };
+		return { valid: false, sourceCount: 0, records: [] };
 	}
 }
 
+async function validatedRecords(configPath: string, records: readonly RecoveryRecord[]): Promise<RecoveryRecord[]> {
+	const groups = await Promise.all(records.map((record) => managedRecoveryGroup(configPath, record)));
+	return records.filter((_record, index) => groups[index] !== undefined);
+}
+
+export async function referencedRecoveryPaths(
+	configPath: string,
+	records: readonly RecoveryRecord[],
+): Promise<Set<string>> {
+	const groups = await Promise.all(records.map((record) => managedRecoveryGroup(configPath, record)));
+	return new Set(groups.filter((group): group is string => group !== undefined));
+}
+
 export async function readRecoveryRecords(configPath: string): Promise<RecoveryRecord[]> {
-	return (await readManifest(getRecoveryManifestPath(configPath))).records;
+	const path = getRecoveryManifestPath(configPath);
+	return withFileMutationQueue(path, async () => {
+		const manifest = await readManifest(path);
+		const records = await validatedRecords(configPath, manifest.records);
+		if (!manifest.valid || records.length !== manifest.sourceCount) await writeManifest(path, records);
+		return records;
+	});
 }
 
-/** Move the previous agent-root manifest into the internal-state root without
- * dropping retained artifact pointers. Invalid legacy files stay untouched. */
+/** Move valid records from the previous agent-root manifest into the internal-state
+ * root. Invalid legacy records are removed without touching their referenced paths. */
 export async function relocateRecoveryManifest(configPath: string): Promise<void> {
 	const legacyPath = join(dirname(configPath), RECOVERY_MANIFEST_FILE_NAME);
 	const currentPath = getRecoveryManifestPath(configPath);
 	if (legacyPath === currentPath || !existsSync(legacyPath)) return;
 	await withFileMutationQueue(legacyPath, async () => {
 		const legacy = await readManifest(legacyPath);
-		if (!legacy.valid) return;
+		if (!legacy.valid) {
+			await rm(legacyPath, { force: true });
+			return;
+		}
 		await persistRecoveryRecords(configPath, legacy.records);
 		await rm(legacyPath, { force: true });
 	});
@@ -118,8 +143,13 @@ export async function persistRecoveryRecords(
 	const path = getRecoveryManifestPath(configPath);
 	await withFileMutationQueue(path, async () => {
 		const merged = new Map<string, RecoveryRecord>();
-		for (const record of await readRecoveryRecords(configPath)) merged.set(recoveryKey(record), record);
-		for (const record of records) merged.set(recoveryKey(record), record);
+		const existing = await readManifest(path);
+		for (const record of await validatedRecords(configPath, existing.records)) {
+			merged.set(recoveryKey(record), record);
+		}
+		for (const record of await validatedRecords(configPath, records)) {
+			merged.set(recoveryKey(record), record);
+		}
 		await writeManifest(path, [...merged.values()]);
 	});
 }
@@ -157,11 +187,10 @@ export async function announceRecoveryRecords(
 	if (records.length === 0) return;
 	for (const record of records) {
 		if (!record.integrated || !record.worktreePath) continue;
-		const groupDir = worktreeGroupDir(record.worktreePath);
+		const groupDir = await managedRecoveryGroup(configPath, record);
 		if (!groupDir) continue;
 		if (!existsSync(record.worktreePath) && !(record.patchPath ? existsSync(record.patchPath) : false)) continue;
 		await removeWorktreeGroup({
-			originalRoot: record.originalRoot,
 			worktreePath: record.worktreePath,
 			tempDir: groupDir,
 		});

package/src/isolation/temp-hygiene.ts

@@ -14,8 +14,8 @@
  * that no manifest record claims — a settled thread still resumable in the
  * session that produced it — belongs to a live owner and survives; the same
  * directory left behind by a crash does not. Callers sweeping durable roots
- * additionally pass the paths their manifest still references, so parked work is
- * never removed even if its owner is long gone.
+ * additionally pass the paths their thread and recovery manifests still reference,
+ * so parked and retained work is never removed even if its owner is long gone.
  *
  * 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
@@ -200,11 +200,11 @@ export function sweepProjectTempDirs(
  * leaves a full worktree checkout and its session behind until the whole project
  * goes idle for days — which never happens in a checkout still being worked in.
  *
- * `keep` must report every path the threads manifest still references; parked
- * work outlives its owner by design. Removal is a plain recursive delete, the
- * same as the idle-project rule: an abandoned worktree may leave a prunable
- * registration in its origin repository, which `git worktree prune` and routine
- * gc clear on their own. */
+ * `keep` must report every path the thread and recovery manifests still reference;
+ * parked and retained recovery work outlives its owner by design. Removal is a
+ * plain recursive delete, as in idle-project cleanup. An abandoned worktree may
+ * leave a prunable registration in its origin repository, which
+ * `git worktree prune` and routine gc clear on their own. */
 export function sweepProjectDurableDirs(
 	durableRoot: string,
 	options: SweepOptions = {},

package/src/isolation/worktree.ts

@@ -10,7 +10,7 @@
 
 import { existsSync, symlinkSync } from "node:fs";
 import { copyFile, mkdir, mkdtemp, realpath, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import {
 	GIT_COMMAND_TIMEOUT_MS,
 	GIT_OUTPUT_MAX_BYTES,
@@ -187,16 +187,6 @@ export function isPathInside(root: string, candidate: string): boolean {
 	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
 }
 
-/** The temp group directory backing a worktree path, when the path actually
- * names our `<group>/worktree` layout. Recovery deletes only paths read back
- * from the manifest through this guard. */
-export function worktreeGroupDir(worktreePath: string): string | undefined {
-	const group = dirname(worktreePath);
-	return basename(worktreePath) === "worktree" && basename(group).startsWith(WORKTREE_TEMP_DIR_PREFIX)
-		? group
-		: undefined;
-}
-
 /** Delete one isolated worktree group: Git's own removal keeps metadata
  * authoritative, but Git on Windows cannot always delete deep checkouts
  * ("Filename too long"), so the Node removal decides the outcome and the prune

package/src/lifecycle/durable.ts

@@ -15,19 +15,22 @@
 
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { existsSync, type Dirent, readdirSync, statSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { uptime } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import type { UsageStats } from "../execution/rpc-control.ts";
 import type { SubagentThread } from "./runtime.ts";
 import { getResultOutput, isFailedResult, getProjectRoot, getSubagentsRoot, type SingleResult } from "../execution/spawn.ts";
+import { isManagedSessionDir, isManagedWorktreeLayout, samePath } from "../isolation/managed-paths.ts";
+import { readRecoveryRecords, referencedRecoveryPaths } from "../isolation/recovery.ts";
 import {
 	isPathInside,
+	normalizeWorktreeSnapshot,
+	resolveRepositoryRoot,
 	restoreWorktreeIsolation,
 	type IsolationMode,
-	normalizeWorktreeSnapshot,
-	worktreeSnapshot,
 	type WorktreeSnapshot,
+	worktreeSnapshot,
 } from "../isolation/worktree.ts";
 
 export const THREADS_MANIFEST_FILE_NAME = "pi-subagents-threads.json";
@@ -35,7 +38,7 @@ const THREADS_MANIFEST_VERSION = 1;
 
 /** Project directories whose newest file has not been touched for this long
  * are deleted wholesale at session start, so per-project sessions/worktrees/results
- * can never accumulate forever. Parked threads' manifest references always
+ * can never accumulate forever. Valid thread and recovery manifest references always
  * win over the age rule. */
 export const PROJECT_ROOT_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1_000;
 
@@ -190,19 +193,80 @@ function normalizeRecord(value: unknown): ThreadRecord | undefined {
 	};
 }
 
-async function readManifestRecords(path: string): Promise<ThreadRecord[]> {
+interface ThreadManifestRead {
+	valid: boolean;
+	sourceCount: number;
+	records: ThreadRecord[];
+}
+
+async function readManifest(path: string): Promise<ThreadManifestRead> {
 	try {
-		const parsed = JSON.parse(await readFile(path, "utf8")) as {
-			records?: unknown;
+		const parsed = JSON.parse(await readFile(path, "utf8")) as { records?: unknown };
+		if (!Array.isArray(parsed.records)) return { valid: false, sourceCount: 0, records: [] };
+		return {
+			valid: true,
+			sourceCount: parsed.records.length,
+			records: parsed.records.flatMap((record) => {
+				const normalized = normalizeRecord(record);
+				return normalized ? [normalized] : [];
+			}),
 		};
-		if (!Array.isArray(parsed.records)) return [];
-		return parsed.records.flatMap((record) => {
-			const normalized = normalizeRecord(record);
-			return normalized ? [normalized] : [];
-		});
 	} catch {
-		return [];
+		return { valid: false, sourceCount: 0, records: [] };
+	}
+}
+
+async function readManifestRecords(path: string): Promise<ThreadRecord[]> {
+	return (await readManifest(path)).records;
+}
+
+async function validateThreadRecord(
+	configPath: string,
+	manifestPath: string,
+	record: ThreadRecord,
+): Promise<boolean> {
+	if (
+		!isAbsolute(record.cwd) ||
+		!isAbsolute(record.executionCwd) ||
+		record.cwd !== resolve(record.cwd) ||
+		record.executionCwd !== resolve(record.executionCwd) ||
+		!samePath(dirname(manifestPath), getProjectRoot(configPath, record.cwd))
+	) {
+		return false;
 	}
+	if ((record.sessionId === undefined) !== (record.sessionDir === undefined)) return false;
+	if (record.sessionDir && !await isManagedSessionDir(configPath, record.cwd, record.sessionDir)) return false;
+	if (record.isolation === "shared") {
+		return record.worktree === undefined && samePath(record.executionCwd, record.cwd);
+	}
+	const worktree = record.worktree;
+	if (!worktree || !await isManagedWorktreeLayout(configPath, record.cwd, worktree)) return false;
+	try {
+		const canonicalCwd = await realpath(record.cwd);
+		const canonicalRoot = await resolveRepositoryRoot(record.cwd);
+		if (!samePath(worktree.originalCwd, canonicalCwd) || !samePath(worktree.originalRoot, canonicalRoot)) {
+			return false;
+		}
+		if (!isPathInside(canonicalRoot, canonicalCwd)) return false;
+		const restoredCwd = join(worktree.worktreePath, relative(canonicalRoot, canonicalCwd));
+		if (!samePath(worktree.cwd, restoredCwd) || !samePath(record.executionCwd, restoredCwd)) return false;
+		if (existsSync(worktree.cwd)) {
+			const [realWorktree, realCwd] = await Promise.all([realpath(worktree.worktreePath), realpath(worktree.cwd)]);
+			if (!samePath(realCwd, join(realWorktree, relative(canonicalRoot, canonicalCwd)))) return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function validatedManifestRecords(
+	configPath: string,
+	path: string,
+	records: readonly ThreadRecord[],
+): Promise<ThreadRecord[]> {
+	const validity = await Promise.all(records.map((record) => validateThreadRecord(configPath, path, record)));
+	return records.filter((_record, index) => validity[index]);
 }
 
 /** Manifest paths of every project that has a durable root. */
@@ -221,7 +285,12 @@ function projectManifestPaths(durableRoot: string): string[] {
 export async function readThreadRecords(configPath: string): Promise<ThreadRecord[]> {
 	const manifests = await Promise.all(
 		projectManifestPaths(getSubagentsRoot(configPath))
-			.map((path) => readManifestRecords(path)),
+			.map((path) => withFileMutationQueue(path, async () => {
+				const manifest = await readManifest(path);
+				const validated = await validatedManifestRecords(configPath, path, manifest.records);
+				if (!manifest.valid || validated.length !== manifest.sourceCount) await writeManifest(path, validated);
+				return validated;
+			})),
 	);
 	return manifests.flat();
 }
@@ -367,11 +436,14 @@ export async function pruneThreadRecords(
 	const durableRoot = getSubagentsRoot(configPath);
 	for (const path of projectManifestPaths(durableRoot)) {
 		await withFileMutationQueue(path, async () => {
-			const records = await readManifestRecords(path);
-			if (records.length === 0) return;
-			let changed = false;
+			const manifest = await readManifest(path);
+			const records = manifest.records;
+			if (manifest.valid && records.length === 0) return;
+			const validity = await Promise.all(records.map((record) => validateThreadRecord(configPath, path, record)));
+			let changed = !manifest.valid || manifest.sourceCount !== records.length || validity.some((valid) => !valid);
 			const kept: ThreadRecord[] = [];
-			for (const record of records) {
+			for (const [index, record] of records.entries()) {
+				if (!validity[index]) continue;
 				if (now - record.updatedAt <= PARKED_RECORD_MAX_AGE_MS) {
 					kept.push(record);
 					continue;
@@ -384,8 +456,8 @@ export async function pruneThreadRecords(
 	}
 }
 
-/** Paths a manifest still references; used by the state-root sweep so
- * freshly created-but-unrecorded directories are never touched. */
+/** Paths a thread manifest still references; combined with recovery references by
+ * startup retention before any durable directory is swept. */
 export function referencedDurablePaths(records: readonly ThreadRecord[]): Set<string> {
 	const paths = new Set<string>();
 	for (const record of records) {
@@ -436,13 +508,15 @@ function isIdleSince(root: string, cutoffMs: number, now: number): boolean {
 }
 
 /** 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. */
+ * been idle past PROJECT_ROOT_MAX_AGE_MS. A directory containing any path a valid
+ * thread or recovery manifest still references is never touched. 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 recoveryRecords = await readRecoveryRecords(configPath).catch(() => []);
 	const referenced = referencedDurablePaths(records);
+	for (const path of await referencedRecoveryPaths(configPath, recoveryRecords)) referenced.add(path);
 	const root = getSubagentsRoot(configPath);
 	let projects: Dirent[];
 	try {