@emiliosp/pi-maestro 0.17.0 → 0.18.1

package/node_modules/pi-subagents/src/runs/shared/worktree-cleanup-plan.js

@@ -1,804 +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.js";
-import { PROJECT_SUBAGENTS_RELATIVE_DIR } from "../../shared/artifacts.js";
-import { DEFAULT_STALE_TERMINAL_ACTIVE_MARKER_MS, activeRunMarkerAgeMs } from "../background/active-run-index.js";
-import { getAgentDir } from "../../shared/utils.js";
-import { isTerminalParallelHandoffChildStatus, readParallelHandoffManifest } from "./parallel-handoff.js";
-import { MACHINE_DIFF_OPTIONS, validateWorktreePatchRepresentsCurrentWorktree } from "./worktree.js";
-export const WORKTREE_CLEANUP_PLAN_VERSION = 1;
-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;
-function runGit(cwd, args) {
-    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, command) {
-    return result.error?.message || result.stderr.trim() || result.stdout.trim() || `${command} failed`;
-}
-function runGitChecked(cwd, args) {
-    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, nativeRealpath = fs.realpathSync.native, fallbackRealpath = fs.realpathSync) {
-    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) {
-    let current = path.resolve(candidate);
-    const missingSegments = [];
-    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;
-}
-export function samePath(left, right) {
-    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, { bigint: true });
-        const rightStat = fs.statSync(right, { bigint: true });
-        return leftStat.dev !== 0n && leftStat.ino !== 0n && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
-    }
-    catch {
-        return false;
-    }
-}
-function resolveExistingPath(candidate) {
-    try {
-        return realpathExisting(candidate);
-    }
-    catch {
-        return path.resolve(candidate);
-    }
-}
-function pathInside(root, candidate, strict = false) {
-    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) {
-    return createHash("sha256").update(value, "utf-8").digest("hex");
-}
-function validatePlanId(planId) {
-    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;
-}
-export function resolveCleanupRepoRoot(repo) {
-    const requested = path.resolve(repo);
-    const toplevel = runGitChecked(requested, ["rev-parse", "--show-toplevel"]);
-    return realpathExisting(toplevel);
-}
-function resolveCleanupBaseDir(repoRoot, configuredBaseDir) {
-    const raw = configuredBaseDir ?? process.env.PI_SUBAGENTS_WORKTREE_DIR;
-    let dedicatedRoot;
-    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, projectDir) {
-    const extensionsDir = path.join(getAgentDir(), "extensions");
-    return samePath(projectDir, repoRoot)
-        || pathInside(repoRoot, projectDir, true)
-        || pathInside(extensionsDir, projectDir);
-}
-export function parseGitWorktreeList(raw) {
-    const records = [];
-    let current;
-    const flush = () => {
-        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 === "locked" || line.startsWith("locked "))
-            current.locked = true;
-        else if (line.startsWith("prunable "))
-            current.prunable = line.slice("prunable ".length).trim();
-    }
-    flush();
-    return records;
-}
-function listGitWorktrees(repoRoot) {
-    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);
-}
-export function isRegisteredCleanupWorktree(repoRoot, candidate) {
-    return listGitWorktrees(repoRoot).some((tree) => samePath(tree.path, candidate));
-}
-function readJsonFile(filePath) {
-    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-}
-function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-function readManifest(manifestPath) {
-    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 = readParallelHandoffManifest(manifestPath);
-        if (!parsed) {
-            return { error: `invalid parallel handoff manifest version or groups: ${manifestPath}` };
-        }
-        return { manifest: parsed };
-    }
-    catch (error) {
-        const code = error && typeof error === "object" && "code" in error ? error.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, input) {
-    const paths = [];
-    const warnings = [];
-    const add = (candidate) => {
-        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.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) {
-    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, statusPath };
-    }
-    catch (error) {
-        const code = error && typeof error === "object" && "code" in error ? error.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, manifest, warnings) {
-    const records = [];
-    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,
-                child: matchingChildren[0],
-                ...(statusInfo.status ? { status: statusInfo.status } : {}),
-                statusPath: statusInfo.statusPath,
-                ...(statusInfo.error ? { statusError: statusInfo.error } : {}),
-            });
-        }
-    }
-    return records;
-}
-function loadMetadata(input, repoRoot) {
-    const discovered = discoverHandoffPaths(repoRoot, input);
-    const records = [];
-    const warnings = [...discovered.warnings];
-    for (const manifestPath of discovered.paths) {
-        const result = readManifest(manifestPath);
-        if (!result.manifest) {
-            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) {
-    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.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, candidate) {
-    return path.isAbsolute(candidate) ? path.resolve(candidate) : path.resolve(path.dirname(manifestPath), candidate);
-}
-function metadataRecordPath(record) {
-    return metadataPath(record.manifestPath, record.task.path);
-}
-function metadataPatchPath(record) {
-    const patchPath = record.child.patch?.path;
-    return typeof patchPath === "string" && patchPath.trim() ? metadataPath(record.manifestPath, patchPath) : undefined;
-}
-function metadataOutputPaths(record) {
-    return [record.child.outputPath, record.child.structuredOutputPath, record.child.sessionPath, record.child.patch?.path]
-        .filter((candidate) => typeof candidate === "string" && candidate.trim().length > 0)
-        .map((candidate) => metadataPath(record.manifestPath, candidate));
-}
-function metadataReportPaths(record) {
-    return [record.child.outputPath, record.child.structuredOutputPath, record.child.sessionPath]
-        .filter((candidate) => typeof candidate === "string" && candidate.trim().length > 0)
-        .map((candidate) => metadataPath(record.manifestPath, candidate));
-}
-function terminalRunState(status) {
-    return status === "complete" || status === "failed" || status === "partial" || status === "paused" || status === "stopped" || status === "rejected";
-}
-function inspectRunState(record, now, foregroundRunOwnership) {
-    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) {
-    const recordedBaseDir = input.metadata?.task.recordedBaseDir;
-    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 ? { recordedBaseDir } : {}),
-            targetRef: input.targetHead,
-        },
-    };
-}
-function blockedEntry(entry, state, decision, reason) {
-    return { ...entry, state, decision, reasons: [...entry.reasons, reason] };
-}
-function inspectStatus(worktreePath) {
-    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, commit) {
-    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, branch) {
-    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, worktreePath, baseCommit) {
-    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;
-    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) {
-    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}'`);
-    const recordedBaseDir = record.task.recordedBaseDir;
-    if (typeof recordedBaseDir !== "string" || !path.isAbsolute(recordedBaseDir))
-        return blockedEntry(entry, "unknown", "keep", "handoff metadata has no creation-time base directory proof");
-    // Compare the saved canonical string, without following a newly replaced ancestor.
-    const creationRelative = path.relative(recordedBaseDir, pathInspection.realpath);
-    if (!creationRelative || creationRelative === ".." || creationRelative.startsWith(`..${path.sep}`) || path.isAbsolute(creationRelative))
-        return blockedEntry(entry, "ineligible", "keep", `worktree real path is outside its creation-time recorded base directory '${recordedBaseDir}'`);
-    if (rootPath === comparablePath(pathInspection.realpath))
-        return blockedEntry(entry, "ineligible", "keep", "worktree is the repository root");
-    if (git.locked)
-        return blockedEntry(entry, "ineligible", "keep", "Git worktree is locked");
-    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 retainedSession = record.child.sessionPath ?? record.status?.steps?.[record.child.index]?.sessionFile ?? record.status?.sessionFile;
-    if (typeof retainedSession === "string" && retainedSession.trim())
-        return blockedEntry(entry, "ineligible", "keep", "retained child resume still has a recorded session dependency");
-    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 ignored = runGit(worktreePath, ["ls-files", "--others", "--ignored", "--exclude-standard", "-z"]);
-    if (ignored.status !== 0)
-        return blockedEntry(entry, "unknown", "unknown", `ignored-file inspection failed: ${gitFailure(ignored, "git ls-files")}`);
-    if (ignored.stdout)
-        return blockedEntry(entry, "ineligible", "keep", "worktree contains ignored files; cleanup preserves them");
-    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 = false;
-    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) {
-    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) {
-    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");
-}
-export function worktreeCleanupContentPayload(plan) {
-    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, right) {
-    return comparablePath(left.path).localeCompare(comparablePath(right.path)) || left.branch.localeCompare(right.branch);
-}
-export function buildWorktreeCleanupPlan(input) {
-    if (typeof input.repo !== "string" || !input.repo.trim())
-        throw new Error("worktree cleanup plan requires a repository path");
-    const repoRoot = resolveCleanupRepoRoot(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();
-    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 = [];
-    const matchedMetadataRecords = new Set();
-    for (const git of linkedGit) {
-        if (input.candidatePaths && !input.candidatePaths.some((candidate) => samePath(candidate, git.path)))
-            continue;
-        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(worktreeCleanupContentPayload(basePlan)));
-    const planId = validatePlanId(input.planId ?? randomUUID());
-    return {
-        ...basePlan,
-        planId,
-        createdAt: now,
-        expiresAt: now + WORKTREE_CLEANUP_PLAN_TTL_MS,
-        contentHash,
-    };
-}
-export function worktreeCleanupPlanPath(repoRoot, planId) {
-    return path.join(repoRoot, PROJECT_SUBAGENTS_RELATIVE_DIR, "cleanup-plans", `${validatePlanId(planId)}.json`);
-}
-export function createWorktreeCleanupPlan(input) {
-    const plan = buildWorktreeCleanupPlan(input);
-    const planPath = worktreeCleanupPlanPath(plan.repoRoot, plan.planId);
-    writeAtomicJson(planPath, plan);
-    return { plan, planPath };
-}
-function formatPlanEntry(entry) {
-    const target = entry.branch ? `${entry.path} [${entry.branch}]` : entry.path;
-    return `- ${target}: ${entry.reasons.join("; ") || "no reason recorded"}`;
-}
-export function formatWorktreeCleanupPlan(created) {
-    const { plan, planPath } = created;
-    const removable = plan.entries.filter((entry) => entry.decision === "remove");
-    const kept = plan.entries.filter((entry) => entry.decision === "keep");
-    const unknown = plan.entries.filter((entry) => entry.decision === "unknown");
-    const section = (title, entries, empty) => [
-        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"),
-        "",
-        "Local branches: all retained, including after apply.",
-        "",
-        ...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.",
-        `Apply this reviewed plan: subagent({ action: "worktree.cleanup", options: { mode: "apply", repo: ${JSON.stringify(plan.repoRoot)}, planId: ${JSON.stringify(plan.planId)} } })`,
-    ];
-    return lines.join("\n");
-}
-//# sourceMappingURL=worktree-cleanup-plan.js.map