pi-subagents 0.69.0 → 0.70.0

package/src/runs/shared/worktree-cleanup-plan.ts

@@ -1,869 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { PROJECT_SUBAGENTS_RELATIVE_DIR } from "../../shared/artifacts.ts";
-import { DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS, activeRunMarkerAgeMs } from "../background/active-run-index.ts";
-import type {
-	AsyncStatus,
-	ParallelHandoffChild,
-	ParallelHandoffCleanupTask,
-	ParallelHandoffGroup,
-	ParallelHandoffManifest,
-} from "../../shared/types.ts";
-import { getAgentDir } from "../../shared/utils.ts";
-import { isTerminalParallelHandoffChildStatus } from "./parallel-handoff.ts";
-import { MACHINE_DIFF_OPTIONS, validateWorktreePatchRepresentsCurrentWorktree } from "./worktree.ts";
-
-export const WORKTREE_CLEANUP_PLAN_VERSION = 1 as const;
-export const WORKTREE_CLEANUP_PLAN_TTL_MS = 30 * 60 * 1000;
-const MAX_DISCOVERED_HANDOFFS = 256;
-const MAX_PLAN_ENTRIES = 512;
-const MAX_METADATA_FILE_BYTES = 2 * 1024 * 1024;
-
-export type WorktreeCleanupPlanState = "safe" | "ineligible" | "stale" | "dirty" | "active" | "unknown";
-export type WorktreeCleanupPlanDecision = "remove" | "keep" | "unknown";
-export type WorktreeCleanupPlanSource = "git" | "metadata" | "both";
-export type ForegroundRunOwnership = "active" | "terminal" | "unknown";
-
-export interface WorktreeCleanupPlanPreconditions {
-	path: string;
-	branch: string;
-	worktreeHead?: string;
-	branchTip?: string;
-	baseCommit?: string;
-	statusDigest?: string;
-	recordedBaseDir?: string;
-	targetRef?: string;
-}
-
-export interface WorktreeCleanupPlanEntry {
-	path: string;
-	branch: string;
-	decision: WorktreeCleanupPlanDecision;
-	state: WorktreeCleanupPlanState;
-	reasons: string[];
-	source: WorktreeCleanupPlanSource;
-	willDeleteBranch?: boolean;
-	runId?: string;
-	handoffPath?: string;
-	taskIndex?: number;
-	baseCommit?: string;
-	patchPath?: string;
-	targetRef?: string;
-	preconditions: WorktreeCleanupPlanPreconditions;
-}
-
-export interface WorktreeCleanupPlan {
-	version: typeof WORKTREE_CLEANUP_PLAN_VERSION;
-	planId: string;
-	repoRoot: string;
-	createdAt: number;
-	expiresAt: number;
-	baseDirs: string[];
-	metadataPaths: string[];
-	entries: WorktreeCleanupPlanEntry[];
-	pruneCandidates: string[];
-	warnings?: string[];
-	contentHash: string;
-}
-
-export interface BuildWorktreeCleanupPlanInput {
-	repo: string;
-	handoffPath?: string;
-	/** Internal test and migration seam for explicitly supplied handoff records. */
-	handoffPaths?: string[];
-	worktreeBaseDir?: string;
-	now?: number;
-	planId?: string;
-	/** Current-process proof for foreground owners; unknown must remain non-removable. */
-	foregroundRunOwnership?: (runId: string) => ForegroundRunOwnership;
-}
-
-export interface CreatedWorktreeCleanupPlan {
-	plan: WorktreeCleanupPlan;
-	planPath: string;
-}
-
-interface GitResult {
-	stdout: string;
-	stderr: string;
-	status: number | null;
-	error?: Error;
-}
-
-interface GitWorktreeRecord {
-	path: string;
-	head: string;
-	branch?: string;
-	prunable?: string;
-}
-
-interface ManifestMetadataRecord {
-	manifestPath: string;
-	manifest: ParallelHandoffManifest;
-	group: ParallelHandoffGroup;
-	task: ParallelHandoffCleanupTask;
-	child: ParallelHandoffChild;
-	status?: AsyncStatus;
-	statusPath: string;
-	statusError?: string;
-}
-
-interface ManifestReadResult {
-	manifest?: ParallelHandoffManifest;
-	error?: string;
-}
-
-interface PathInspection {
-	resolved: string;
-	realpath?: string;
-	missing: boolean;
-	symlink: boolean;
-	directory: boolean;
-	error?: string;
-}
-
-interface RunStateInspection {
-	kind: "terminal" | "active" | "unknown" | "stale";
-	reason?: string;
-}
-
-function runGit(cwd: string, args: string[]): GitResult {
-	try {
-		const result = spawnSync("git", ["-C", cwd, ...args], { encoding: "utf-8", windowsHide: true });
-		return {
-			stdout: result.stdout ?? "",
-			stderr: result.stderr ?? "",
-			status: result.status,
-			...(result.error ? { error: result.error } : {}),
-		};
-	} catch (error) {
-		return {
-			stdout: "",
-			stderr: "",
-			status: null,
-			error: error instanceof Error ? error : new Error(String(error)),
-		};
-	}
-}
-
-function gitFailure(result: GitResult, command: string): string {
-	return result.error?.message || result.stderr.trim() || result.stdout.trim() || `${command} failed`;
-}
-
-function runGitChecked(cwd: string, args: string[]): string {
-	const result = runGit(cwd, args);
-	if (result.status !== 0) throw new Error(gitFailure(result, `git -C ${cwd} ${args.join(" ")}`));
-	return result.stdout.trim();
-}
-
-function realpathExisting(
-	candidate: string,
-	nativeRealpath: (filePath: string) => string = fs.realpathSync.native,
-	fallbackRealpath: (filePath: string) => string = fs.realpathSync,
-): string {
-	try {
-		return nativeRealpath(candidate);
-	} catch {
-		return fallbackRealpath(candidate);
-	}
-}
-
-/** Internal test seam; this is not part of the public subagent tool API. */
-export const __testables = { realpathExisting };
-
-function comparablePath(candidate: string): string {
-	let current = path.resolve(candidate);
-	const missingSegments: string[] = [];
-	let canonical = current;
-	while (true) {
-		try {
-			canonical = path.join(realpathExisting(current), ...missingSegments.reverse());
-			break;
-		} catch {
-			const parent = path.dirname(current);
-			if (parent === current) break;
-			missingSegments.push(path.basename(current));
-			current = parent;
-		}
-	}
-	const normalized = path.normalize(canonical);
-	return process.platform === "win32" ? normalized.toLowerCase() : normalized;
-}
-
-function samePath(left: string, right: string): boolean {
-	if (comparablePath(left) === comparablePath(right)) return true;
-	if (process.platform !== "win32") return false;
-	// Git for Windows and Node can spell the same temp directory with different
-	// drive/short-name aliases. The directory identity is the final bounded
-	// fallback; never accept aliases when the filesystem cannot prove identity.
-	try {
-		const leftStat = fs.statSync(left);
-		const rightStat = fs.statSync(right);
-		return leftStat.dev !== 0 && leftStat.ino !== 0 && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
-	} catch {
-		return false;
-	}
-}
-
-function resolveExistingPath(candidate: string): string {
-	try {
-		return realpathExisting(candidate);
-	} catch {
-		return path.resolve(candidate);
-	}
-}
-
-function pathInside(root: string, candidate: string, strict = false): boolean {
-	const normalizedRoot = comparablePath(root);
-	const normalizedCandidate = comparablePath(candidate);
-	if (!strict && normalizedRoot === normalizedCandidate) return true;
-	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative !== ""
-		&& relative !== ".."
-		&& !relative.startsWith(`..${path.sep}`)
-		&& !path.isAbsolute(relative);
-}
-
-function sha256(value: string): string {
-	return createHash("sha256").update(value, "utf-8").digest("hex");
-}
-
-function validatePlanId(planId: string): string {
-	if (!/^[A-Za-z0-9._-]+$/.test(planId) || planId === "." || planId === "..") {
-		throw new Error("worktree cleanup plan id must contain only letters, numbers, dots, underscores, or hyphens");
-	}
-	return planId;
-}
-
-function resolveRepoRoot(repo: string): string {
-	const requested = path.resolve(repo);
-	const toplevel = runGitChecked(requested, ["rev-parse", "--show-toplevel"]);
-	return realpathExisting(toplevel);
-}
-
-function resolveCleanupBaseDir(repoRoot: string, configuredBaseDir: string | undefined): string {
-	const raw = configuredBaseDir ?? process.env.PI_SUBAGENTS_WORKTREE_DIR;
-	let dedicatedRoot: string;
-	if (raw === undefined || (configuredBaseDir === undefined && !raw.trim())) {
-		dedicatedRoot = path.join(path.dirname(repoRoot), "worktrees");
-	} else {
-		const trimmed = raw.trim();
-		if (!trimmed) throw new Error("worktree base directory cannot be empty");
-		const expanded = trimmed.startsWith("~/") ? path.join(os.homedir(), trimmed.slice(2)) : trimmed;
-		dedicatedRoot = path.isAbsolute(expanded) ? expanded : path.resolve(repoRoot, expanded);
-	}
-	return path.resolve(path.join(dedicatedRoot, path.basename(repoRoot)));
-}
-
-function cleanupContainmentInvalid(repoRoot: string, projectDir: string): boolean {
-	const extensionsDir = path.join(getAgentDir(), "extensions");
-	return samePath(projectDir, repoRoot)
-		|| pathInside(repoRoot, projectDir, true)
-		|| pathInside(extensionsDir, projectDir);
-}
-
-export function parseGitWorktreeList(raw: string): GitWorktreeRecord[] {
-	const records: GitWorktreeRecord[] = [];
-	let current: GitWorktreeRecord | undefined;
-	const flush = (): void => {
-		if (current?.path) records.push(current);
-		current = undefined;
-	};
-
-	for (const line of raw.split(/\r?\n/)) {
-		if (!line.trim()) {
-			flush();
-			continue;
-		}
-		if (line.startsWith("worktree ")) {
-			flush();
-			current = { path: line.slice("worktree ".length), head: "" };
-			continue;
-		}
-		if (!current) continue;
-		if (line.startsWith("HEAD ")) current.head = line.slice("HEAD ".length).trim();
-		else if (line.startsWith("branch refs/heads/")) current.branch = line.slice("branch refs/heads/".length).trim();
-		else if (line === "detached") delete current.branch;
-		else if (line.startsWith("prunable ")) current.prunable = line.slice("prunable ".length).trim();
-	}
-	flush();
-	return records;
-}
-
-function listGitWorktrees(repoRoot: string): GitWorktreeRecord[] {
-	const result = runGit(repoRoot, ["worktree", "list", "--porcelain"]);
-	if (result.status !== 0) throw new Error(gitFailure(result, `git -C ${repoRoot} worktree list --porcelain`));
-	return parseGitWorktreeList(result.stdout);
-}
-
-function readJsonFile(filePath: string): unknown {
-	return JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function readManifest(manifestPath: string): ManifestReadResult {
-	try {
-		const stat = fs.lstatSync(manifestPath);
-		if (stat.isSymbolicLink() || !stat.isFile()) return { error: `parallel handoff manifest is not a regular file: ${manifestPath}` };
-		if (stat.size > MAX_METADATA_FILE_BYTES) return { error: `parallel handoff manifest exceeds the ${MAX_METADATA_FILE_BYTES}-byte limit: ${manifestPath}` };
-		const parsed = readJsonFile(manifestPath);
-		if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.groups)) {
-			return { error: `invalid parallel handoff manifest version or groups: ${manifestPath}` };
-		}
-		return { manifest: parsed as unknown as ParallelHandoffManifest };
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
-		if (code === "ENOENT") return { error: `parallel handoff manifest not found: ${manifestPath}` };
-		return { error: `failed to read parallel handoff manifest ${manifestPath}: ${error instanceof Error ? error.message : String(error)}` };
-	}
-}
-
-function discoverHandoffPaths(repoRoot: string, input: BuildWorktreeCleanupPlanInput): { paths: string[]; warnings: string[] } {
-	const paths: string[] = [];
-	const warnings: string[] = [];
-	const add = (candidate: string): void => {
-		const resolved = path.isAbsolute(candidate) ? path.resolve(candidate) : path.resolve(repoRoot, candidate);
-		if (!paths.some((existing) => comparablePath(existing) === comparablePath(resolved))) paths.push(resolved);
-	};
-
-	if (input.handoffPath) add(input.handoffPath);
-	for (const candidate of input.handoffPaths ?? []) add(candidate);
-
-	// Project artifacts have a fixed, shallow handoff layout. Do not walk a temp
-	// or session root: those roots contain unrelated operator data and are not a
-	// source of ownership for cleanup candidates.
-	const artifactsDir = path.join(repoRoot, PROJECT_SUBAGENTS_RELATIVE_DIR, "artifacts");
-	const projectHandoffPath = path.join(artifactsDir, "handoff.json");
-	if (fs.existsSync(projectHandoffPath)) add(projectHandoffPath);
-	const handoffsDir = path.join(artifactsDir, "handoffs");
-	try {
-		const stat = fs.lstatSync(handoffsDir);
-		if (stat.isSymbolicLink() || !stat.isDirectory()) {
-			warnings.push(`ignored non-directory handoff metadata root: ${handoffsDir}`);
-		} else {
-			const entries = fs.readdirSync(handoffsDir, { withFileTypes: true })
-				.filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-				.map((entry) => entry.name)
-				.sort()
-				.slice(0, MAX_DISCOVERED_HANDOFFS);
-			for (const entry of entries) add(path.join(handoffsDir, entry));
-			if (entries.length === MAX_DISCOVERED_HANDOFFS) warnings.push(`handoff metadata discovery capped at ${MAX_DISCOVERED_HANDOFFS} files`);
-		}
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
-		if (code !== "ENOENT") warnings.push(`failed to inspect handoff metadata root ${handoffsDir}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-
-	return { paths: paths.sort((left, right) => comparablePath(left).localeCompare(comparablePath(right))), warnings: [...new Set(warnings)].sort() };
-}
-
-function readStatusBesideManifest(manifestPath: string): { status?: AsyncStatus; statusPath: string; error?: string } {
-	const statusPath = path.join(path.dirname(manifestPath), "status.json");
-	try {
-		const stat = fs.lstatSync(statusPath);
-		if (stat.isSymbolicLink() || !stat.isFile()) return { statusPath, error: `async status is not a regular file: ${statusPath}` };
-		if (stat.size > MAX_METADATA_FILE_BYTES) return { statusPath, error: `async status exceeds the ${MAX_METADATA_FILE_BYTES}-byte limit: ${statusPath}` };
-		const parsed = readJsonFile(statusPath);
-		if (!isRecord(parsed) || typeof parsed.state !== "string" || typeof parsed.runId !== "string") {
-			return { statusPath, error: `invalid async status beside manifest: ${statusPath}` };
-		}
-		return { status: parsed as unknown as AsyncStatus, statusPath };
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
-		if (code === "ENOENT") return { statusPath };
-		return { statusPath, error: `failed to read async status ${statusPath}: ${error instanceof Error ? error.message : String(error)}` };
-	}
-}
-
-function manifestMetadata(manifestPath: string, manifest: ParallelHandoffManifest, warnings: string[]): ManifestMetadataRecord[] {
-	const records: ManifestMetadataRecord[] = [];
-	const groups = manifest.groups.slice(0, MAX_PLAN_ENTRIES);
-	if (manifest.groups.length > groups.length) warnings.push(`handoff group discovery capped at ${MAX_PLAN_ENTRIES} groups in ${manifestPath}`);
-	for (const group of groups) {
-		if (!isRecord(group) || !Array.isArray(group.cleanup?.tasks) || !Array.isArray(group.children)) {
-			warnings.push(`ignored malformed handoff group in ${manifestPath}`);
-			continue;
-		}
-		const statusInfo = readStatusBesideManifest(manifestPath);
-		const tasks = group.cleanup.tasks.slice(0, MAX_PLAN_ENTRIES);
-		if (group.cleanup.tasks.length > tasks.length) warnings.push(`cleanup task discovery capped at ${MAX_PLAN_ENTRIES} tasks in ${manifestPath}`);
-		for (const task of tasks) {
-			if (!isRecord(task) || typeof task.path !== "string" || !task.path.trim() || typeof task.branch !== "string" || !task.branch.trim() || typeof task.index !== "number" || !Number.isInteger(task.index) || task.index < 0) {
-				warnings.push(`ignored malformed cleanup task in ${manifestPath}`);
-				continue;
-			}
-			const matchingChildren = group.children.filter((candidate) => isRecord(candidate) && candidate.taskIndex === task.index);
-			if (matchingChildren.length !== 1 || !isRecord(matchingChildren[0]) || typeof matchingChildren[0].status !== "string") {
-				warnings.push(`cleanup task ${task.index} does not have exactly one valid child metadata record in ${manifestPath}`);
-				continue;
-			}
-			records.push({
-				manifestPath,
-				manifest,
-				group,
-				task: task as unknown as ParallelHandoffCleanupTask,
-				child: matchingChildren[0] as unknown as ParallelHandoffChild,
-				...(statusInfo.status ? { status: statusInfo.status } : {}),
-				statusPath: statusInfo.statusPath,
-				...(statusInfo.error ? { statusError: statusInfo.error } : {}),
-			});
-		}
-	}
-	return records;
-}
-
-function loadMetadata(input: BuildWorktreeCleanupPlanInput, repoRoot: string): { records: ManifestMetadataRecord[]; paths: string[]; warnings: string[] } {
-	const discovered = discoverHandoffPaths(repoRoot, input);
-	const records: ManifestMetadataRecord[] = [];
-	const warnings = [...discovered.warnings];
-	const explicitPath = input.handoffPath ? path.isAbsolute(input.handoffPath) ? path.resolve(input.handoffPath) : path.resolve(repoRoot, input.handoffPath) : undefined;
-	for (const manifestPath of discovered.paths) {
-		const result = readManifest(manifestPath);
-		if (!result.manifest) {
-			if (explicitPath && comparablePath(manifestPath) === comparablePath(explicitPath)) warnings.push(result.error!);
-			continue;
-		}
-		const manifestRoot = resolveExistingPath(manifestPath);
-		if (manifestRoot !== manifestPath && fs.lstatSync(manifestPath).isSymbolicLink()) {
-			warnings.push(`ignored symlinked handoff manifest: ${manifestPath}`);
-			continue;
-		}
-		records.push(...manifestMetadata(manifestPath, result.manifest, warnings));
-	}
-	return { records, paths: discovered.paths, warnings: [...new Set(warnings)].sort() };
-}
-
-function inspectPath(candidate: string): PathInspection {
-	const resolved = path.resolve(candidate);
-	try {
-		const stat = fs.lstatSync(resolved);
-		if (stat.isSymbolicLink()) return { resolved, missing: false, symlink: true, directory: false };
-		return { resolved, realpath: realpathExisting(resolved), missing: false, symlink: false, directory: stat.isDirectory() };
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? (error as NodeJS.ErrnoException).code : undefined;
-		if (code === "ENOENT") return { resolved, missing: true, symlink: false, directory: false };
-		return { resolved, missing: false, symlink: false, directory: false, error: error instanceof Error ? error.message : String(error) };
-	}
-}
-
-function metadataPath(manifestPath: string, candidate: string): string {
-	return path.isAbsolute(candidate) ? path.resolve(candidate) : path.resolve(path.dirname(manifestPath), candidate);
-}
-
-function metadataRecordPath(record: ManifestMetadataRecord): string {
-	return metadataPath(record.manifestPath, record.task.path);
-}
-
-function metadataPatchPath(record: ManifestMetadataRecord): string | undefined {
-	const patchPath = record.child.patch?.path;
-	return typeof patchPath === "string" && patchPath.trim() ? metadataPath(record.manifestPath, patchPath) : undefined;
-}
-
-function metadataOutputPaths(record: ManifestMetadataRecord): string[] {
-	return [record.child.outputPath, record.child.structuredOutputPath, record.child.sessionPath, record.child.patch?.path]
-		.filter((candidate): candidate is string => typeof candidate === "string" && candidate.trim().length > 0)
-		.map((candidate) => metadataPath(record.manifestPath, candidate));
-}
-
-function metadataReportPaths(record: ManifestMetadataRecord): string[] {
-	return [record.child.outputPath, record.child.structuredOutputPath, record.child.sessionPath]
-		.filter((candidate): candidate is string => typeof candidate === "string" && candidate.trim().length > 0)
-		.map((candidate) => metadataPath(record.manifestPath, candidate));
-}
-
-function terminalRunState(status: AsyncStatus["state"]): boolean {
-	return status === "complete" || status === "failed" || status === "partial" || status === "paused" || status === "stopped" || status === "rejected";
-}
-
-function inspectRunState(record: ManifestMetadataRecord, now: number, foregroundRunOwnership?: (runId: string) => ForegroundRunOwnership): RunStateInspection {
-	if (record.statusError) return { kind: "unknown", reason: record.statusError };
-	if (record.status) {
-		if (record.status.runId !== record.manifest.runId) return { kind: "unknown", reason: `status run id '${record.status.runId}' does not match manifest run '${record.manifest.runId}'` };
-		if (record.status.state === "queued" || record.status.state === "running") return { kind: "active", reason: `owning run is ${record.status.state}` };
-		if (!terminalRunState(record.status.state)) return { kind: "unknown", reason: `owning run has unknown state '${record.status.state}'` };
-	} else if (record.manifest.source === "async") {
-		return { kind: "unknown", reason: `async status is missing beside ${record.manifestPath}` };
-	}
-
-	if (record.group.children.length === 0 || !record.group.children.every((child) => isTerminalParallelHandoffChildStatus(child.status))) {
-		return { kind: "active", reason: "owning handoff still has a non-terminal child" };
-	}
-	if (record.manifest.source === "foreground") {
-		try {
-			const ownership = foregroundRunOwnership?.(record.manifest.runId) ?? "unknown";
-			if (ownership === "active") return { kind: "active", reason: "owning foreground run is still active" };
-			if (ownership !== "terminal") return { kind: "unknown", reason: "foreground owning-run state is not provably terminal" };
-			return { kind: "terminal" };
-		} catch (error) {
-			return { kind: "unknown", reason: `failed to inspect foreground owning run: ${error instanceof Error ? error.message : String(error)}` };
-		}
-	}
-
-	try {
-		const markerAge = activeRunMarkerAgeMs(path.dirname(record.statusPath), now);
-		if (markerAge !== undefined) {
-			if (markerAge <= DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS) return { kind: "active", reason: "owning run still has a recent active marker" };
-			return { kind: "stale", reason: `terminal active marker is stale (${Math.floor(markerAge / 1000)}s old)` };
-		}
-	} catch (error) {
-		return { kind: "unknown", reason: `failed to inspect active-run marker: ${error instanceof Error ? error.message : String(error)}` };
-	}
-	return { kind: "terminal" };
-}
-
-function buildEntryBase(input: {
-	path: string;
-	branch: string;
-	source: WorktreeCleanupPlanSource;
-	git?: GitWorktreeRecord;
-	metadata?: ManifestMetadataRecord;
-	targetHead: string;
-}): WorktreeCleanupPlanEntry {
-	const recordedBaseDir = path.dirname(input.path);
-	const patchPath = input.metadata ? metadataPatchPath(input.metadata) : undefined;
-	return {
-		path: input.path,
-		branch: input.branch,
-		decision: "unknown",
-		state: "unknown",
-		reasons: [],
-		source: input.source,
-		...(input.metadata ? { runId: input.metadata.manifest.runId, handoffPath: input.metadata.manifestPath, taskIndex: input.metadata.task.index } : {}),
-		...(input.metadata?.group.baseCommit ? { baseCommit: input.metadata.group.baseCommit } : {}),
-		...(patchPath ? { patchPath } : {}),
-		targetRef: input.targetHead,
-		preconditions: {
-			path: input.path,
-			branch: input.branch,
-			...(input.git?.head ? { worktreeHead: input.git.head } : {}),
-			...(input.metadata?.group.baseCommit ? { baseCommit: input.metadata.group.baseCommit } : {}),
-			recordedBaseDir,
-			targetRef: input.targetHead,
-		},
-	};
-}
-
-function blockedEntry(entry: WorktreeCleanupPlanEntry, state: WorktreeCleanupPlanState, decision: WorktreeCleanupPlanDecision, reason: string): WorktreeCleanupPlanEntry {
-	return { ...entry, state, decision, reasons: [...entry.reasons, reason] };
-}
-
-function inspectStatus(worktreePath: string): { output?: string; digest?: string; error?: string } {
-	const result = runGit(worktreePath, ["status", "--porcelain=v1", "--untracked-files=all"]);
-	if (result.status !== 0) return { error: gitFailure(result, `git -C ${worktreePath} status --porcelain=v1`) };
-	const output = result.stdout;
-	return { output, digest: sha256(output) };
-}
-
-function resolveCommit(repoRoot: string, commit: string): { value?: string; error?: string } {
-	const result = runGit(repoRoot, ["rev-parse", "--verify", `${commit}^{commit}`]);
-	if (result.status !== 0) return { error: gitFailure(result, `git -C ${repoRoot} rev-parse ${commit}`) };
-	return { value: result.stdout.trim() };
-}
-
-function resolveBranchTip(repoRoot: string, branch: string): { value?: string; error?: string } {
-	const result = runGit(repoRoot, ["rev-parse", "--verify", `refs/heads/${branch}^{commit}`]);
-	if (result.status !== 0) return { error: gitFailure(result, `git -C ${repoRoot} rev-parse refs/heads/${branch}`) };
-	return { value: result.stdout.trim() };
-}
-
-function isPatchCaptured(record: ManifestMetadataRecord, worktreePath: string, baseCommit: string): { path?: string; error?: string } {
-	const patchPath = metadataPatchPath(record);
-	if (!patchPath || record.child.patch?.error !== undefined || record.child.patch?.changed !== true) return {};
-	const inspection = inspectPath(patchPath);
-	if (inspection.error) return { error: `captured patch cannot be inspected: ${inspection.error}` };
-	if (inspection.missing || !inspection.realpath) return { error: "captured handoff patch is missing" };
-	let patchStat: fs.Stats;
-	try {
-		patchStat = fs.statSync(patchPath);
-	} catch (error) {
-		return { error: `captured patch cannot be inspected: ${error instanceof Error ? error.message : String(error)}` };
-	}
-	if (!patchStat.isFile()) return { error: "captured handoff patch is not a file" };
-	if (pathInside(worktreePath, inspection.realpath)) return { error: "durable handoff patch lives inside the worktree" };
-	if (patchStat.size <= 0) return { error: "captured handoff patch is empty" };
-	const validationError = validateWorktreePatchRepresentsCurrentWorktree(worktreePath, baseCommit, patchPath);
-	if (validationError) return { error: `captured handoff patch failed validation: ${validationError}` };
-	return { path: patchPath };
-}
-
-function buildManagedEntry(input: {
-	repoRoot: string;
-	baseDir: string;
-	containmentInvalid: boolean;
-	targetHead: string;
-	rootPath: string;
-	git: GitWorktreeRecord;
-	record: ManifestMetadataRecord;
-	otherGitRecords: GitWorktreeRecord[];
-	now: number;
-	foregroundRunOwnership?: (runId: string) => ForegroundRunOwnership;
-}): WorktreeCleanupPlanEntry {
-	const { repoRoot, baseDir, targetHead, rootPath, git, record, foregroundRunOwnership } = input;
-	const gitWorktreePath = path.resolve(git.path);
-	const metadataWorktreePath = metadataRecordPath(record);
-	const worktreePath = resolveExistingPath(metadataWorktreePath);
-	const entry = buildEntryBase({ path: worktreePath, branch: git.branch ?? "", source: "both", git, metadata: record, targetHead });
-	if (typeof record.manifest.runId !== "string" || !record.manifest.runId.trim()) return blockedEntry(entry, "unknown", "unknown", "handoff metadata has no valid owning run id");
-	if (record.manifest.source !== "foreground" && record.manifest.source !== "async") return blockedEntry(entry, "unknown", "unknown", "handoff metadata has an unknown source");
-	if (typeof record.group.repoRoot !== "string" || !record.group.repoRoot.trim()) return blockedEntry(entry, "unknown", "unknown", "handoff metadata has no repository root");
-	if (!samePath(metadataWorktreePath, gitWorktreePath)) return blockedEntry(entry, "unknown", "unknown", "metadata worktree path does not identify the Git worktree");
-	const gitPathInspection = inspectPath(gitWorktreePath);
-	if (gitPathInspection.error) return blockedEntry(entry, "unknown", "unknown", `Git worktree path could not be inspected: ${gitPathInspection.error}`);
-	if (gitPathInspection.missing) return blockedEntry(entry, "stale", "unknown", "Git worktree path is missing from disk");
-	if (gitPathInspection.symlink) return blockedEntry(entry, "unknown", "unknown", "Git worktree path is a symlink; cleanup requires a real directory");
-	const pathInspection = inspectPath(worktreePath);
-	if (pathInspection.error) return blockedEntry(entry, "unknown", "unknown", `worktree path could not be inspected: ${pathInspection.error}`);
-	if (pathInspection.missing) return blockedEntry(entry, "stale", "unknown", "worktree path is missing from disk");
-	if (pathInspection.symlink) return blockedEntry(entry, "unknown", "unknown", "worktree path is a symlink; cleanup requires a real directory");
-	if (!pathInspection.directory || !pathInspection.realpath) return blockedEntry(entry, "unknown", "unknown", "worktree path is not a directory");
-	const extensionsDir = path.join(getAgentDir(), "extensions");
-	if (pathInside(extensionsDir, pathInspection.realpath)) return blockedEntry(entry, "ineligible", "keep", `worktree real path is inside Pi extensions directory '${extensionsDir}'`);
-	if (input.containmentInvalid || !pathInside(baseDir, pathInspection.realpath, true)) return blockedEntry(entry, "ineligible", "keep", `worktree real path is outside configured base directory '${baseDir}'`);
-
-	if (rootPath === comparablePath(pathInspection.realpath)) return blockedEntry(entry, "ineligible", "keep", "worktree is the repository root");
-	if (!git.branch) return blockedEntry(entry, "unknown", "unknown", "detached worktrees have no metadata-recorded branch");
-	if (record.task.branch !== git.branch) return blockedEntry(entry, "unknown", "unknown", `metadata branch '${record.task.branch}' does not match Git branch '${git.branch}'`);
-	if (record.task.worktreeRemoved) return blockedEntry(entry, "stale", "unknown", "handoff metadata already records this worktree as removed");
-	if (record.task.preserved !== true) return blockedEntry(entry, "unknown", "unknown", "handoff metadata does not mark this worktree as preserved");
-	if (record.group.cleanup.state !== "partial") return blockedEntry(entry, "unknown", "unknown", "handoff cleanup state does not indicate a preserved worktree pending cleanup");
-	const cleanupReason = typeof record.task.reason === "string" ? record.task.reason.toLowerCase() : "";
-	if (cleanupReason.includes("retained child resume")) return blockedEntry(entry, "ineligible", "keep", "retained child resume still requires this worktree cwd");
-	if (cleanupReason.includes("cleanup pending durable handoff capture")) return blockedEntry(entry, "ineligible", "keep", "durable handoff capture is still pending for this worktree");
-	if (record.group.repoRoot && comparablePath(resolveExistingPath(record.group.repoRoot)) !== comparablePath(repoRoot)) {
-		return blockedEntry(entry, "unknown", "unknown", "handoff repository root does not match the requested repository");
-	}
-	if (input.otherGitRecords.some((candidate) => candidate.branch === git.branch && comparablePath(candidate.path) !== comparablePath(git.path))) {
-		return blockedEntry(entry, "unknown", "unknown", "metadata-recorded branch is checked out in another Git worktree");
-	}
-	if (git.branch === input.otherGitRecords.find((candidate) => comparablePath(candidate.path) === rootPath)?.branch) {
-		return blockedEntry(entry, "ineligible", "keep", "metadata-recorded branch is checked out at the repository root");
-	}
-
-	const runState = inspectRunState(record, input.now, foregroundRunOwnership);
-	if (runState.kind === "unknown") return blockedEntry(entry, "unknown", "unknown", runState.reason ?? "owning run state is unknown");
-	if (runState.kind === "active") return blockedEntry(entry, "active", "keep", runState.reason ?? "owning run is active");
-	if (runState.kind === "stale") return blockedEntry(entry, "stale", "unknown", runState.reason ?? "terminal active marker is stale");
-
-	const baseCommit = record.group.baseCommit;
-	if (typeof baseCommit !== "string" || !baseCommit.trim()) return blockedEntry(entry, "unknown", "unknown", "handoff metadata has no base commit");
-	const resolvedBase = resolveCommit(repoRoot, baseCommit);
-	if (!resolvedBase.value) return blockedEntry(entry, "unknown", "unknown", `handoff base commit is not a valid local commit: ${resolvedBase.error ?? "unknown error"}`);
-	entry.baseCommit = resolvedBase.value;
-	entry.preconditions.baseCommit = resolvedBase.value;
-	const branchTip = resolveBranchTip(repoRoot, git.branch);
-	if (!branchTip.value) return blockedEntry(entry, "unknown", "unknown", `branch tip could not be resolved: ${branchTip.error ?? "unknown error"}`);
-	entry.preconditions.branchTip = branchTip.value;
-	entry.preconditions.worktreeHead = git.head;
-	if (branchTip.value !== git.head) return blockedEntry(entry, "unknown", "unknown", "branch tip and worktree HEAD do not match");
-
-	const status = inspectStatus(worktreePath);
-	if (status.error) return blockedEntry(entry, "unknown", "unknown", `git status failed: ${status.error}`);
-	entry.preconditions.statusDigest = status.digest;
-	if (status.output && status.output.trim()) return blockedEntry(entry, "dirty", "keep", "worktree has uncommitted or untracked changes");
-
-	const diff = runGit(worktreePath, ["diff", "--quiet", ...MACHINE_DIFF_OPTIONS, resolvedBase.value, "--"]);
-	if (diff.status !== 0 && diff.status !== 1) return blockedEntry(entry, "unknown", "unknown", `git diff safety check failed: ${gitFailure(diff, "git diff")}`);
-	const ancestor = runGit(repoRoot, ["merge-base", "--is-ancestor", git.head, targetHead]);
-	if (ancestor.status !== 0 && ancestor.status !== 1) return blockedEntry(entry, "unknown", "unknown", `local merge safety check failed: ${gitFailure(ancestor, "git merge-base --is-ancestor")}`);
-	const branchTipIsAncestor = ancestor.status === 0;
-	let divergenceSafe = diff.status === 0;
-	if (!divergenceSafe) {
-		const captured = isPatchCaptured(record, worktreePath, resolvedBase.value);
-		if (captured.error) return blockedEntry(entry, "ineligible", "keep", captured.error);
-		if (captured.path) {
-			entry.patchPath = captured.path;
-			divergenceSafe = true;
-		} else {
-			if (branchTipIsAncestor) divergenceSafe = true;
-			else return blockedEntry(entry, "ineligible", "keep", "committed divergence is neither preserved by a handoff patch nor merged into the local target HEAD");
-		}
-	}
-	if (!divergenceSafe) return blockedEntry(entry, "unknown", "unknown", "worktree divergence safety could not be established");
-
-	for (const reportPath of [record.manifestPath, ...metadataReportPaths(record)]) {
-		const inspection = inspectPath(reportPath);
-		if (inspection.error) return blockedEntry(entry, "unknown", "unknown", `durable handoff path could not be inspected: ${inspection.error}`);
-		const comparable = inspection.realpath ?? (inspection.symlink ? resolveExistingPath(reportPath) : inspection.resolved);
-		if (pathInside(pathInspection.realpath, comparable)) return blockedEntry(entry, "ineligible", "keep", `durable handoff path is inside the worktree: ${reportPath}`);
-		if (inspection.missing) return blockedEntry(entry, "unknown", "unknown", `durable handoff path is missing: ${reportPath}`);
-		if (inspection.symlink) return blockedEntry(entry, "unknown", "unknown", `durable handoff path is a symlink: ${reportPath}`);
-	}
-
-	for (const durablePath of metadataOutputPaths(record)) {
-		const inspection = inspectPath(durablePath);
-		const comparable = inspection.realpath ?? (inspection.symlink ? resolveExistingPath(durablePath) : inspection.resolved);
-		if (pathInside(pathInspection.realpath, comparable)) return blockedEntry(entry, "ineligible", "keep", `durable report or patch path is inside the worktree: ${durablePath}`);
-	}
-
-	entry.state = "safe";
-	entry.decision = "remove";
-	entry.willDeleteBranch = branchTipIsAncestor;
-	entry.reasons.push("extension-owned metadata, terminal run, contained clean worktree, and local divergence checks passed");
-	if (!branchTipIsAncestor) entry.reasons.push("local branch tip is not an ancestor of target HEAD; future apply must retain the branch");
-	return entry;
-}
-
-function buildUnknownGitEntry(input: { git: GitWorktreeRecord; targetHead: string }): WorktreeCleanupPlanEntry {
-	const pathValue = resolveExistingPath(input.git.path);
-	const entry = buildEntryBase({ path: pathValue, branch: input.git.branch ?? "", source: "git", git: input.git, targetHead: input.targetHead });
-	return blockedEntry(entry, "unknown", "unknown", "no matching extension-owned handoff metadata was found");
-}
-
-function buildMissingMetadataEntry(input: { record: ManifestMetadataRecord; targetHead: string }): WorktreeCleanupPlanEntry | undefined {
-	if (input.record.task.worktreeRemoved && input.record.task.branchRemoved) return undefined;
-	const pathValue = metadataRecordPath(input.record);
-	const entry = buildEntryBase({ path: pathValue, branch: input.record.task.branch, source: "metadata", metadata: input.record, targetHead: input.targetHead });
-	return blockedEntry(entry, "stale", "unknown", "handoff metadata records a worktree that is not present in Git worktree state");
-}
-
-function contentPayload(plan: Omit<WorktreeCleanupPlan, "contentHash" | "planId" | "createdAt" | "expiresAt">): unknown {
-	return {
-		version: plan.version,
-		repoRoot: plan.repoRoot,
-		baseDirs: plan.baseDirs,
-		metadataPaths: plan.metadataPaths,
-		entries: plan.entries,
-		pruneCandidates: plan.pruneCandidates,
-		...(plan.warnings ? { warnings: plan.warnings } : {}),
-	};
-}
-
-function stableEntrySort(left: WorktreeCleanupPlanEntry, right: WorktreeCleanupPlanEntry): number {
-	return comparablePath(left.path).localeCompare(comparablePath(right.path)) || left.branch.localeCompare(right.branch);
-}
-
-export function buildWorktreeCleanupPlan(input: BuildWorktreeCleanupPlanInput): WorktreeCleanupPlan {
-	if (typeof input.repo !== "string" || !input.repo.trim()) throw new Error("worktree cleanup plan requires a repository path");
-	const repoRoot = resolveRepoRoot(input.repo);
-	const now = input.now ?? Date.now();
-	if (!Number.isFinite(now)) throw new Error("worktree cleanup plan timestamp must be finite");
-	const baseDir = resolveCleanupBaseDir(repoRoot, input.worktreeBaseDir);
-	const containmentInvalid = cleanupContainmentInvalid(repoRoot, baseDir);
-	const gitRecords = listGitWorktrees(repoRoot);
-	const targetHead = runGitChecked(repoRoot, ["rev-parse", "HEAD"]);
-	const rootPath = comparablePath(repoRoot);
-	const metadata = loadMetadata(input, repoRoot);
-	const metadataByPath = new Map<string, ManifestMetadataRecord[]>();
-	for (const record of metadata.records) {
-		const key = comparablePath(metadataRecordPath(record));
-		const records = metadataByPath.get(key) ?? [];
-		records.push(record);
-		metadataByPath.set(key, records);
-	}
-
-	const linkedGit = gitRecords.filter((record) => !samePath(record.path, repoRoot));
-	const entries: WorktreeCleanupPlanEntry[] = [];
-	const matchedMetadataRecords = new Set<ManifestMetadataRecord>();
-	for (const git of linkedGit) {
-		const records = metadataByPath.get(comparablePath(git.path)) ?? (git.branch
-			? metadata.records.filter((record) => record.task.branch === git.branch && samePath(metadataRecordPath(record), git.path))
-			: []);
-		if (records.length === 1) matchedMetadataRecords.add(records[0]!);
-		if (records.length !== 1) entries.push(buildUnknownGitEntry({ git, targetHead }));
-		else entries.push(buildManagedEntry({
-			repoRoot,
-			baseDir,
-			containmentInvalid,
-			targetHead,
-			rootPath,
-			git,
-			record: records[0]!,
-			otherGitRecords: gitRecords,
-			now,
-			foregroundRunOwnership: input.foregroundRunOwnership,
-		}));
-	}
-
-	const gitPathKeys = new Set(linkedGit.map((record) => comparablePath(record.path)));
-	for (const [key, records] of metadataByPath) {
-		if (gitPathKeys.has(key) || records.length !== 1 || matchedMetadataRecords.has(records[0]!)) continue;
-		const missing = buildMissingMetadataEntry({ record: records[0]!, targetHead });
-		if (missing) entries.push(missing);
-	}
-
-	entries.sort(stableEntrySort);
-	const warnings = metadata.warnings;
-	if (entries.length > MAX_PLAN_ENTRIES) {
-		warnings.push(`cleanup plan entry count capped at ${MAX_PLAN_ENTRIES}; remaining worktrees are not evaluated`);
-		entries.splice(MAX_PLAN_ENTRIES);
-	}
-	const pruneCandidates = entries
-		.filter((entry) => entry.decision === "unknown" && entry.state === "stale" && gitRecords.some((record) => record.prunable && comparablePath(record.path) === comparablePath(entry.path)))
-		.map((entry) => entry.path)
-		.sort((left, right) => comparablePath(left).localeCompare(comparablePath(right)));
-	const basePlan = {
-		version: WORKTREE_CLEANUP_PLAN_VERSION,
-		repoRoot,
-		baseDirs: [baseDir],
-		metadataPaths: metadata.paths,
-		entries,
-		pruneCandidates,
-		...(warnings.length ? { warnings: [...new Set(warnings)].sort() } : {}),
-	};
-	const contentHash = sha256(JSON.stringify(contentPayload(basePlan)));
-	const planId = validatePlanId(input.planId ?? randomUUID());
-	return {
-		...basePlan,
-		planId,
-		createdAt: now,
-		expiresAt: now + WORKTREE_CLEANUP_PLAN_TTL_MS,
-		contentHash,
-	};
-}
-
-export function worktreeCleanupPlanPath(repoRoot: string, planId: string): string {
-	return path.join(repoRoot, PROJECT_SUBAGENTS_RELATIVE_DIR, "cleanup-plans", `${validatePlanId(planId)}.json`);
-}
-
-export function createWorktreeCleanupPlan(input: BuildWorktreeCleanupPlanInput): CreatedWorktreeCleanupPlan {
-	const plan = buildWorktreeCleanupPlan(input);
-	const planPath = worktreeCleanupPlanPath(plan.repoRoot, plan.planId);
-	writeAtomicJson(planPath, plan);
-	return { plan, planPath };
-}
-
-function formatPlanEntry(entry: WorktreeCleanupPlanEntry): string {
-	const target = entry.branch ? `${entry.path} [${entry.branch}]` : entry.path;
-	return `- ${target}: ${entry.reasons.join("; ") || "no reason recorded"}`;
-}
-
-export function formatWorktreeCleanupPlan(created: CreatedWorktreeCleanupPlan): string {
-	const { plan, planPath } = created;
-	const removable = plan.entries.filter((entry) => entry.decision === "remove");
-	const branches = removable.filter((entry) => entry.willDeleteBranch === true);
-	const kept = plan.entries.filter((entry) => entry.decision === "keep");
-	const unknown = plan.entries.filter((entry) => entry.decision === "unknown");
-	const section = (title: string, entries: WorktreeCleanupPlanEntry[], empty: string): string[] => [
-		title,
-		...(entries.length ? entries.map(formatPlanEntry) : [`- ${empty}`]),
-	];
-	const lines = [
-		`Worktree cleanup plan ${plan.planId}`,
-		`Repository: ${plan.repoRoot}`,
-		`Expires: ${new Date(plan.expiresAt).toISOString()}`,
-		`Entries: ${plan.entries.length}`,
-		"",
-		...section("Will remove", removable, "none"),
-		"",
-		...section("Will delete local branches", branches, "none (plan-only mode; no branch will be deleted)"),
-		"",
-		...section("Will keep, with reasons", kept, "none"),
-		"",
-		...section("Unknown, needs manual review", unknown, "none"),
-		"",
-		"Prune candidates",
-		...(plan.pruneCandidates.length ? plan.pruneCandidates.map((candidate) => `- ${candidate}`) : ["- none (plan-only mode does not prune Git metadata)"]),
-		...(plan.warnings?.length ? ["", "Warnings", ...plan.warnings.map((warning) => `- ${warning}`)] : []),
-		"",
-		`Plan saved: ${planPath}`,
-		"Plan-only mode: no worktrees or branches were removed.",
-	];
-	return lines.join("\n");
-}