@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/runs/shared/worktree-cleanup-plan.js

@@ -0,0 +1,721 @@
+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 { isTerminalParallelHandoffChildStatus } from "./parallel-handoff.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);
+  }
+}
+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;
+}
+function samePath(left, right) {
+  if (comparablePath(left) === comparablePath(right))
+    return true;
+  if (process.platform !== "win32")
+    return false;
+  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) {
+  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;
+}
+function resolveRepoRoot(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.DM_SUBAGENTS_WORKTREE_DIR ?? os.tmpdir();
+  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;
+  return path.resolve(path.isAbsolute(expanded) ? expanded : path.resolve(repoRoot, expanded));
+}
+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.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);
+}
+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 = 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 };
+  } 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);
+  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,
+        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];
+  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) {
+  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 = 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, 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) {
+  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" };
+  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");
+  if (!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", 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);
+    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) {
+  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;
+  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) {
+  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 = 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 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) {
+    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,
+        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, 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 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, 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"),
+    "",
+    ...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(`
+`);
+}