@ferris1225/pi-subagents 4.3.4 → 4.3.6

package/src/isolation/git-command.ts

@@ -0,0 +1,147 @@
+/** Bounded, abortable process runner used by Git isolation operations. */
+
+import { spawn, type ChildProcess } from "node:child_process";
+
+export interface CommandRunOptions {
+	cwd: string;
+	input?: Buffer;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	maxOutputBytes?: number;
+	/** Extra environment entries merged over the inherited environment. */
+	env?: Record<string, string>;
+}
+
+export interface CommandResult {
+	code: number;
+	stdout: Buffer;
+	stderr: Buffer;
+}
+
+/** Injectable, shell-free command runner used by every Git operation. */
+export type CommandRunner = (
+	command: string,
+	args: readonly string[],
+	options: CommandRunOptions,
+) => Promise<CommandResult>;
+
+export const GIT_COMMAND_TIMEOUT_MS = 120_000;
+export const GIT_COMMAND_KILL_GRACE_MS = 2_000;
+export const GIT_OUTPUT_MAX_BYTES = 64 * 1024 * 1024;
+export const WORKTREE_PATCH_MAX_BYTES = GIT_OUTPUT_MAX_BYTES;
+
+/** Terminate the complete spawned process tree so checkout filters cannot
+ * survive an abort or timeout. */
+function terminateCommandTree(child: ChildProcess, force: boolean, processGroup: boolean): void {
+	if (process.platform === "win32" && child.pid !== undefined) {
+		const fallback = (): void => {
+			try {
+				child.kill(force ? "SIGKILL" : "SIGTERM");
+			} catch {
+				/* process may already be gone */
+			}
+		};
+		const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+			stdio: "ignore",
+			windowsHide: true,
+		});
+		killer.once("error", fallback);
+		killer.once("close", (code) => {
+			if (code !== 0) fallback();
+		});
+		return;
+	}
+	try {
+		if (processGroup && child.pid !== undefined) {
+			process.kill(-child.pid, force ? "SIGKILL" : "SIGTERM");
+		} else {
+			child.kill(force ? "SIGKILL" : "SIGTERM");
+		}
+	} catch {
+		/* process may already be gone */
+	}
+}
+
+/** Default argument-safe runner. Output is bounded before binary patches enter
+ * memory, and timeout/abort terminates the complete checkout-filter process tree. */
+export const runCommand: CommandRunner = (command, args, options) =>
+	new Promise<CommandResult>((resolveResult, reject) => {
+		if (options.signal?.aborted) {
+			reject(new Error(`Command aborted before start: ${command}`));
+			return;
+		}
+		const usePosixProcessGroup = process.platform !== "win32";
+		const child = spawn(command, [...args], {
+			cwd: options.cwd,
+			shell: false,
+			windowsHide: true,
+			stdio: ["pipe", "pipe", "pipe"],
+			detached: usePosixProcessGroup,
+			...(options.env ? { env: { ...process.env, ...options.env } } : {}),
+		});
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+		const maxOutputBytes = options.maxOutputBytes ?? GIT_OUTPUT_MAX_BYTES;
+		let outputBytes = 0;
+		let finished = false;
+		let failure: Error | undefined;
+		let timeout: ReturnType<typeof setTimeout> | undefined;
+		let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+
+		const terminate = (): void => {
+			terminateCommandTree(child, false, usePosixProcessGroup);
+			if (!forceKillTimer) {
+				forceKillTimer = setTimeout(
+					() => terminateCommandTree(child, true, usePosixProcessGroup),
+					GIT_COMMAND_KILL_GRACE_MS,
+				);
+				if (typeof forceKillTimer.unref === "function") forceKillTimer.unref();
+			}
+		};
+		const fail = (error: Error): void => {
+			if (failure || finished) return;
+			failure = error;
+			terminate();
+		};
+		const append = (target: Buffer[], chunk: Buffer | string): void => {
+			if (failure || finished) return;
+			const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+			outputBytes += value.length;
+			if (outputBytes > maxOutputBytes) {
+				fail(new Error(`Command output exceeded ${maxOutputBytes} bytes: ${command}`));
+				return;
+			}
+			target.push(value);
+		};
+		const onAbort = (): void => fail(new Error(`Command aborted: ${command}`));
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
+			timeout = setTimeout(
+				() => fail(new Error(`Command timed out after ${options.timeoutMs}ms: ${command}`)),
+				options.timeoutMs,
+			);
+			if (typeof timeout.unref === "function") timeout.unref();
+		}
+
+		child.stdout?.on("data", (chunk: Buffer | string) => append(stdout, chunk));
+		child.stderr?.on("data", (chunk: Buffer | string) => append(stderr, chunk));
+		child.once("error", (error) => fail(error));
+		child.once("close", (code) => {
+			if (finished) return;
+			finished = true;
+			if (timeout) clearTimeout(timeout);
+			if (forceKillTimer) clearTimeout(forceKillTimer);
+			options.signal?.removeEventListener("abort", onAbort);
+			if (failure) {
+				reject(failure);
+				return;
+			}
+			resolveResult({
+				code: code ?? 1,
+				stdout: Buffer.concat(stdout),
+				stderr: Buffer.concat(stderr),
+			});
+		});
+		child.stdin?.once("error", () => undefined);
+		child.stdin?.end(options.input);
+	});

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/{recovery.ts → isolation/recovery.ts}

@@ -5,8 +5,9 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
-import { getSubagentsRoot } from "./spawn.ts";
-import { removeWorktreeGroup, worktreeGroupDir, type WorktreeFinalization } from "./worktree.ts";
+import { getSubagentsRoot } from "../execution/spawn.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/{temp-hygiene.ts → 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/{worktree.ts → isolation/worktree.ts}

@@ -8,10 +8,17 @@
  * Failed integration deliberately retains both the worktree and patch.
  */
 
-import { spawn, type ChildProcess } from "node:child_process";
 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,
+	runCommand,
+	type CommandResult,
+	type CommandRunner,
+	WORKTREE_PATCH_MAX_BYTES,
+} from "./git-command.ts";
 import { writeTempOwnerMarker } from "./temp-hygiene.ts";
 
 export type IsolationMode = "shared" | "worktree";
@@ -28,151 +35,6 @@ export function worktreeGroupId(worktree: Pick<WorktreeIsolation, "tempDir">): s
 		: base;
 }
 
-export interface CommandRunOptions {
-	cwd: string;
-	input?: Buffer;
-	signal?: AbortSignal;
-	timeoutMs?: number;
-	maxOutputBytes?: number;
-	/** Extra environment entries merged over the inherited environment. */
-	env?: Record<string, string>;
-}
-
-export interface CommandResult {
-	code: number;
-	stdout: Buffer;
-	stderr: Buffer;
-}
-
-/** Injectable, shell-free command runner used by every Git operation. */
-export type CommandRunner = (
-	command: string,
-	args: readonly string[],
-	options: CommandRunOptions,
-) => Promise<CommandResult>;
-
-export const GIT_COMMAND_TIMEOUT_MS = 120_000;
-export const GIT_COMMAND_KILL_GRACE_MS = 2_000;
-export const GIT_OUTPUT_MAX_BYTES = 64 * 1024 * 1024;
-export const WORKTREE_PATCH_MAX_BYTES = GIT_OUTPUT_MAX_BYTES;
-
-/** Git apply validates and writes in one process. The repository lane
- * (thread-lifecycle) already serializes every finalize against all writers of
- * the same canonical checkout, so applies never race each other here. */
-function terminateCommandTree(child: ChildProcess, force: boolean, processGroup: boolean): void {
-	if (process.platform === "win32" && child.pid !== undefined) {
-		const fallback = (): void => {
-			try {
-				child.kill(force ? "SIGKILL" : "SIGTERM");
-			} catch {
-				/* process may already be gone */
-			}
-		};
-		const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
-			stdio: "ignore",
-			windowsHide: true,
-		});
-		killer.once("error", fallback);
-		killer.once("close", (code) => {
-			if (code !== 0) fallback();
-		});
-		return;
-	}
-	try {
-		if (processGroup && child.pid !== undefined) {
-			process.kill(-child.pid, force ? "SIGKILL" : "SIGTERM");
-		} else {
-			child.kill(force ? "SIGKILL" : "SIGTERM");
-		}
-	} catch {
-		/* process may already be gone */
-	}
-}
-
-/** Default argument-safe runner. Output is bounded before binary patches enter
- * memory, and timeout/abort terminates the complete checkout-filter process tree. */
-export const runCommand: CommandRunner = (command, args, options) =>
-	new Promise<CommandResult>((resolveResult, reject) => {
-		if (options.signal?.aborted) {
-			reject(new Error(`Command aborted before start: ${command}`));
-			return;
-		}
-		const usePosixProcessGroup = process.platform !== "win32";
-		const child = spawn(command, [...args], {
-			cwd: options.cwd,
-			shell: false,
-			windowsHide: true,
-			stdio: ["pipe", "pipe", "pipe"],
-			detached: usePosixProcessGroup,
-			...(options.env ? { env: { ...process.env, ...options.env } } : {}),
-		});
-		const stdout: Buffer[] = [];
-		const stderr: Buffer[] = [];
-		const maxOutputBytes = options.maxOutputBytes ?? GIT_OUTPUT_MAX_BYTES;
-		let outputBytes = 0;
-		let finished = false;
-		let failure: Error | undefined;
-		let timeout: ReturnType<typeof setTimeout> | undefined;
-		let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
-
-		const terminate = (): void => {
-			terminateCommandTree(child, false, usePosixProcessGroup);
-			if (!forceKillTimer) {
-				forceKillTimer = setTimeout(
-					() => terminateCommandTree(child, true, usePosixProcessGroup),
-					GIT_COMMAND_KILL_GRACE_MS,
-				);
-				if (typeof forceKillTimer.unref === "function") forceKillTimer.unref();
-			}
-		};
-		const fail = (error: Error): void => {
-			if (failure || finished) return;
-			failure = error;
-			terminate();
-		};
-		const append = (target: Buffer[], chunk: Buffer | string): void => {
-			if (failure || finished) return;
-			const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-			outputBytes += value.length;
-			if (outputBytes > maxOutputBytes) {
-				fail(new Error(`Command output exceeded ${maxOutputBytes} bytes: ${command}`));
-				return;
-			}
-			target.push(value);
-		};
-		const onAbort = (): void => fail(new Error(`Command aborted: ${command}`));
-		options.signal?.addEventListener("abort", onAbort, { once: true });
-		if (options.timeoutMs !== undefined && options.timeoutMs > 0) {
-			timeout = setTimeout(
-				() => fail(new Error(`Command timed out after ${options.timeoutMs}ms: ${command}`)),
-				options.timeoutMs,
-			);
-			if (typeof timeout.unref === "function") timeout.unref();
-		}
-
-		child.stdout?.on("data", (chunk: Buffer | string) => append(stdout, chunk));
-		child.stderr?.on("data", (chunk: Buffer | string) => append(stderr, chunk));
-		child.once("error", (error) => fail(error));
-		child.once("close", (code) => {
-			if (finished) return;
-			finished = true;
-			if (timeout) clearTimeout(timeout);
-			if (forceKillTimer) clearTimeout(forceKillTimer);
-			options.signal?.removeEventListener("abort", onAbort);
-			if (failure) {
-				reject(failure);
-				return;
-			}
-			resolveResult({
-				code: code ?? 1,
-				stdout: Buffer.concat(stdout),
-				stderr: Buffer.concat(stderr),
-			});
-		});
-		child.stdin?.once("error", () => undefined);
-		child.stdin?.end(options.input);
-	});
-
 export interface WorktreeTarget {
 	/** Canonical cwd requested by the caller. */
 	originalCwd: string;
@@ -325,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
@@ -663,7 +515,8 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 	 * that index, so everything runs against a private copy of the checkout's
 	 * index: the copy first absorbs the current unstaged state (`add -A`),
 	 * making the working tree "ours" of the merge, and the user's real staged
-	 * state is never touched. */
+	 * state is never touched. The repository lane serializes finalization, and
+	 * each `git apply` validates and writes in one process. */
 	private async applyPatchThreeWay(): Promise<boolean> {
 		const indexCopy = join(this.tempDir, "apply-index");
 		try {

package/src/{completion.ts → lifecycle/completion.ts}

@@ -7,8 +7,8 @@
  * failure directly so it is never delayed.
  */
 
-import { formatUsageCompact, sumUsage, type RunWaitReason } from "./monitor.ts";
-import type { UsageStats } from "./rpc-run.ts";
+import { formatUsageCompact, sumUsage, type RunWaitReason } from "../presentation/monitor.ts";
+import type { UsageStats } from "../execution/rpc-control.ts";
 
 export interface CompletionBatchTimings {
 	debounceMs: number;