opencode-worktree-guardian 0.1.0

package/src/unblock-finish.ts

@@ -0,0 +1,298 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { expandWorktreeRoot, loadConfig, normalizeConfig } from "./config.ts";
+import { createSafetyRef, getCurrentBranch, getHeadCommit, getRepoRoot, listWorktrees, runGit } from "./git.ts";
+import { getGuardianPaths, readState, recordSession } from "./state.ts";
+import type { GuardianSession, MutableRecord, WorktreeEntry } from "./types.ts";
+import { isRecordLike } from "./types.ts";
+
+type LooseRecord = MutableRecord;
+
+type StatusEntry = {
+  index: string;
+  worktree: string;
+  path: string;
+  sourcePath: string | null;
+  hash: string | null;
+  symlink: boolean;
+  classification: "review-artifact" | "other";
+};
+
+type ResolvedTarget = {
+  worktreePath: string;
+  branch: string | null;
+  targetSource: "state" | "branch" | "worktreePath";
+};
+type UnblockStateInput = {
+  readonly sessions?: Record<string, GuardianSession>;
+};
+export type GuardianUnblockFinishResult = MutableRecord & {
+  readonly action?: string;
+  readonly committedPaths?: readonly string[];
+  readonly confirmToken?: string;
+  readonly otherDirtyPaths?: readonly string[];
+  readonly preflight: MutableRecord & {
+    readonly branch?: string | null;
+    readonly otherDirtyPaths?: readonly string[];
+    readonly reviewArtifactPaths?: readonly string[];
+    readonly sessionRecorded?: boolean;
+    readonly targetSource?: string | null;
+    readonly worktreePath?: string | null;
+  };
+  readonly reason?: string;
+  readonly safetyRef?: string;
+};
+
+const REVIEW_ARTIFACT_PATTERN = /^\.milestones\/reviews\/[^/]*impl-rating-\d{8}\.(md|txt)$/;
+
+function sha256(value: string | Buffer) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function blocked(reason: string, details: LooseRecord, preflight: LooseRecord) {
+  const previousBlockers = Array.isArray(preflight.blockers) ? preflight.blockers.filter((blocker): blocker is string => typeof blocker === "string") : [];
+  const blockers = [...previousBlockers, reason];
+  preflight.blockers = blockers;
+  return { ok: false, status: "blocked", reason, ...details, preflight: { ...preflight, blockers } };
+}
+
+function relativeGitPath(value: string) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function samePath(left: string, right: string) {
+  return path.resolve(left) === path.resolve(right);
+}
+
+function sameOrInside(candidate: string, root: string) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+async function contentHash(repoRoot: string, entryPath: string) {
+  try {
+    return sha256(await fs.readFile(path.join(repoRoot, entryPath)));
+  } catch {
+    return null;
+  }
+}
+
+async function isSymlink(repoRoot: string, entryPath: string) {
+  try {
+    return (await fs.lstat(path.join(repoRoot, entryPath))).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+async function statusEntries(worktreePath: string): Promise<StatusEntry[]> {
+  const { stdout } = await runGit(worktreePath, ["status", "--porcelain=v1", "--untracked-files=all"]);
+  if (!stdout) return [];
+  const entries: StatusEntry[] = [];
+  for (const line of stdout.split("\n")) {
+    if (!line) continue;
+    const index = line[0] ?? " ";
+    const worktree = line[1] ?? " ";
+    const rawPath = relativeGitPath(line.slice(3));
+    const [sourcePath, entryPath] = rawPath.includes(" -> ")
+      ? [relativeGitPath(rawPath.split(" -> ")[0] ?? rawPath), relativeGitPath(rawPath.split(" -> ").at(-1) ?? rawPath)]
+      : [null, rawPath];
+    const symlink = await isSymlink(worktreePath, entryPath);
+    entries.push({
+      index,
+      worktree,
+      path: entryPath,
+      sourcePath,
+      hash: await contentHash(worktreePath, entryPath),
+      symlink,
+      classification: !sourcePath && !symlink && REVIEW_ARTIFACT_PATTERN.test(entryPath) ? "review-artifact" : "other",
+    });
+  }
+  return entries;
+}
+
+function createConfirmToken(preflight: LooseRecord) {
+  const material = {
+    repoRoot: preflight.repoRoot,
+    sessionId: preflight.sessionId,
+    targetSource: preflight.targetSource,
+    sessionRecorded: preflight.sessionRecorded,
+    worktreePath: preflight.worktreePath,
+    branch: preflight.branch,
+    head: preflight.head,
+    action: preflight.action,
+    entries: preflight.entries,
+  };
+  return sha256(JSON.stringify(material));
+}
+
+function defaultCommitMessage(entries: StatusEntry[]) {
+  if (entries.length === 1) {
+    const base = path.basename(entries[0].path).replace(/-?impl-rating-\d{8}\.(md|txt)$/i, "").replace(/[-_]+/g, " ").trim();
+    if (base) return `docs: add ${base} implementation rating`;
+  }
+  return "docs: add implementation review artifacts";
+}
+
+function preflightBlockers(preflight: LooseRecord): string[] {
+  return Array.isArray(preflight.blockers) ? preflight.blockers.filter((blocker): blocker is string => typeof blocker === "string") : [];
+}
+
+function isUnblockStateInput(value: unknown): value is UnblockStateInput {
+  return isRecordLike(value) && (value.sessions === undefined || isRecordLike(value.sessions));
+}
+
+async function resolveListedWorktree(repoRoot: string, predicate: (worktree: WorktreeEntry) => boolean, targetSource: ResolvedTarget["targetSource"], missingReason: string, multipleReason: string, expectedBranch?: string | null): Promise<{ target: ResolvedTarget | null; reason: string | null }> {
+  const matches = (await listWorktrees(repoRoot)).filter(predicate);
+  if (matches.length !== 1) return { target: null, reason: matches.length > 1 ? multipleReason : missingReason };
+  const match = matches[0];
+  if (match.detached || !match.branch) return { target: null, reason: "target worktree is detached" };
+  if (expectedBranch && match.branch !== expectedBranch) return { target: null, reason: "recorded branch does not match checked-out worktree branch" };
+  return { target: { worktreePath: match.path, branch: match.branch, targetSource }, reason: null };
+}
+
+async function resolveExplicitTarget(repoRoot: string, input: LooseRecord): Promise<{ target: ResolvedTarget | null; reason: string | null }> {
+  const explicitWorktreePath = typeof input.worktreePath === "string" && input.worktreePath.length > 0 ? input.worktreePath : null;
+  const explicitBranch = typeof input.branch === "string" && input.branch.length > 0 ? input.branch : null;
+  if (!explicitWorktreePath && !explicitBranch) return { target: null, reason: "current session is not recorded in guardian state" };
+
+  if (explicitWorktreePath) {
+    const resolved = path.resolve(repoRoot, explicitWorktreePath);
+    return resolveListedWorktree(repoRoot, (worktree) => samePath(worktree.path, resolved), "worktreePath", "worktreePath is not checked out in git worktree list", "worktreePath matches multiple git worktrees", explicitBranch);
+  }
+
+  return resolveListedWorktree(repoRoot, (worktree) => worktree.branch === explicitBranch, "branch", "branch is not checked out in git worktree list", "branch matches multiple git worktrees");
+}
+
+function validateResolvedTarget(repoRoot: string, config: LooseRecord, target: ResolvedTarget) {
+  if (samePath(target.worktreePath, repoRoot)) return "target worktree is the primary repository worktree";
+  if (!target.branch) return "target worktree is detached";
+  const protectedBranches = Array.isArray(config.protectedBranches) ? config.protectedBranches : [];
+  if (protectedBranches.includes(target.branch)) return "target branch is protected";
+  if (target.targetSource !== "state") {
+    const configuredRoot = typeof config.worktreeRoot === "string" ? config.worktreeRoot : ".worktrees/$REPO";
+    const worktreeRoot = path.resolve(repoRoot, expandWorktreeRoot(configuredRoot, repoRoot));
+    if (!sameOrInside(target.worktreePath, worktreeRoot)) return "explicit target is outside Guardian worktree root";
+  }
+  return null;
+}
+
+async function preflightFor(input: LooseRecord) {
+  const cwd = typeof input.cwd === "string" ? input.cwd : typeof input.repoRoot === "string" ? input.repoRoot : process.cwd();
+  const repoRoot = typeof input.repoRoot === "string" ? input.repoRoot : await getRepoRoot(cwd);
+  const { config } = isRecordLike(input.config) ? { config: normalizeConfig(input.config) } : await loadConfig(repoRoot);
+  const sessionId = typeof input.sessionId === "string" ? input.sessionId : null;
+  const preflight: LooseRecord = {
+    repoRoot: path.resolve(repoRoot),
+    mode: input.mode,
+    action: typeof input.action === "string" ? input.action : "commit-review-artifacts",
+    sessionId,
+    sessionRecorded: false,
+    targetSource: null,
+    worktreePath: null,
+    branch: null,
+    head: null,
+    entries: [],
+    reviewArtifactPaths: [],
+    otherDirtyPaths: [],
+    blockers: [],
+  };
+  if (!sessionId) return { preflight, config, session: null, entries: [], reviewEntries: [], otherEntries: [], reason: "sessionId is required" };
+
+  const state = isUnblockStateInput(input.state) ? input.state : await readState(await getGuardianPaths(repoRoot), { repoRoot, config });
+  const session = state.sessions?.[sessionId] ?? null;
+  preflight.sessionRecorded = Boolean(session);
+  let target: ResolvedTarget | null = null;
+  if (session?.worktree_path) {
+    const resolved = await resolveListedWorktree(
+      repoRoot,
+      (worktree) => typeof session.worktree_path === "string" && samePath(worktree.path, session.worktree_path),
+      "state",
+      "recorded worktree is not checked out in git worktree list",
+      "recorded worktree path matches multiple git worktrees",
+      typeof session.branch === "string" ? session.branch : null,
+    );
+    target = resolved.target;
+    if (resolved.reason) return { preflight, config, session, entries: [], reviewEntries: [], otherEntries: [], reason: resolved.reason };
+  } else {
+    const resolved = await resolveExplicitTarget(repoRoot, input);
+    target = resolved.target;
+    if (resolved.reason) return { preflight, config, session, entries: [], reviewEntries: [], otherEntries: [], reason: resolved.reason };
+  }
+  if (!target) return { preflight, config, session, entries: [], reviewEntries: [], otherEntries: [], reason: "current session is not recorded in guardian state" };
+  const invalidTargetReason = validateResolvedTarget(repoRoot, config, target);
+  if (invalidTargetReason) return { preflight, config, session, entries: [], reviewEntries: [], otherEntries: [], reason: invalidTargetReason };
+  preflight.worktreePath = target.worktreePath;
+  preflight.targetSource = target.targetSource;
+  if (!await fs.access(target.worktreePath).then(() => true, () => false)) return { preflight, config, session, entries: [], reviewEntries: [], otherEntries: [], reason: "recorded worktree is missing" };
+
+  const branch = await getCurrentBranch(target.worktreePath);
+  const head = await getHeadCommit(target.worktreePath);
+  const entries = await statusEntries(target.worktreePath);
+  const reviewEntries = entries.filter((entry) => entry.classification === "review-artifact" && entry.index !== "D" && entry.worktree !== "D");
+  const otherEntries = entries.filter((entry) => !reviewEntries.includes(entry));
+  preflight.branch = branch;
+  preflight.head = head;
+  preflight.entries = entries;
+  preflight.reviewArtifactPaths = reviewEntries.map((entry) => entry.path);
+  preflight.otherDirtyPaths = otherEntries.map((entry) => entry.path);
+  return { preflight, config, session, entries, reviewEntries, otherEntries, reason: null };
+}
+
+export async function guardianUnblockFinish(input: LooseRecord = {}): Promise<GuardianUnblockFinishResult> {
+  const mode = input.mode;
+  const action = typeof input.action === "string" ? input.action : "commit-review-artifacts";
+  const { preflight, config, session, entries, reviewEntries, otherEntries, reason } = await preflightFor({ ...input, action });
+  if (mode !== "plan" && mode !== "apply") return blocked("mode must be plan or apply", { mode }, preflight);
+  if (action !== "commit-review-artifacts") return blocked("unsupported unblock action", { action }, preflight);
+  if (reason) return blocked(reason, {}, preflight);
+  if (entries.length === 0) return blocked("worktree is already clean", {}, preflight);
+  if (reviewEntries.length === 0) return blocked("no committable review artifacts found", {}, preflight);
+  if (otherEntries.length > 0) return blocked("dirty files include non-review artifacts", { otherDirtyPaths: otherEntries.map((entry: StatusEntry) => entry.path) }, preflight);
+
+  const confirmToken = createConfirmToken(preflight);
+  if (mode === "plan") {
+    return {
+      ok: true,
+      status: "planned",
+      action,
+      confirmToken,
+      commitMessage: defaultCommitMessage(reviewEntries),
+      preflight: { ...preflight, blockers: preflightBlockers(preflight) },
+      suggestedCommand: "guardian_unblock_finish mode=apply action=commit-review-artifacts confirmToken=<token>",
+    };
+  }
+
+  if (input.confirmToken !== confirmToken) return blocked("confirm token does not match current unblock plan", {}, preflight);
+  const worktreePath = String(preflight.worktreePath);
+  const branch = String(preflight.branch);
+  const head = String(preflight.head);
+  const sessionId = String(preflight.sessionId);
+  const safetyRef = await createSafetyRef(worktreePath, { sessionId, branch, commit: head, timestamp: input.timestamp });
+  const paths = reviewEntries.map((entry: StatusEntry) => entry.path);
+  await runGit(worktreePath, ["add", "--", ...paths]);
+  const commitMessage = typeof input.commitMessage === "string" && input.commitMessage.trim() ? input.commitMessage.trim() : defaultCommitMessage(reviewEntries);
+  await runGit(worktreePath, ["commit", "-m", commitMessage, "--", ...paths]);
+  const newHead = await getHeadCommit(worktreePath);
+  await recordSession(String(preflight.repoRoot), config, {
+    ...(session ?? {}),
+    session_id: sessionId,
+    status: session?.status ?? "active",
+    branch,
+    worktree_path: worktreePath,
+    base_ref: session?.base_ref ?? `${config.remote}/${config.baseBranch}`,
+    head_commit: newHead,
+    safety_refs: [...(session?.safety_refs ?? []), safetyRef],
+  }, { event: { type: "guardian_unblock_finish", session_id: sessionId, ref: safetyRef, action, paths } });
+  return {
+    ok: true,
+    status: "applied",
+    action,
+    committedPaths: paths,
+    commit: newHead,
+    commitMessage,
+    safetyRef,
+    preflight: { ...preflight, blockers: preflightBlockers(preflight) },
+  };
+}

package/src/workflow-candidates.ts

@@ -0,0 +1,111 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { expandWorktreeRoot } from "./config.ts";
+import { guardianDeleteWorktree } from "./delete.ts";
+import { getDirtyFiles, getRepoRoot, isAncestor, listBranches, listWorktrees } from "./git.ts";
+
+export const MAX_WORKFLOW_CLEANUP_CANDIDATES = 25;
+
+export function samePath(left: string, right: string): boolean {
+  return path.resolve(left) === path.resolve(right);
+}
+
+export function isInside(candidate: string, parent: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || (Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function candidateTokenMaterial(candidate: Record<string, unknown>): Record<string, unknown> {
+  return {
+    kind: candidate.kind,
+    targetPath: candidate.targetPath ?? null,
+    branch: candidate.branch ?? null,
+    head: candidate.head ?? null,
+    targetKind: candidate.targetKind ?? null,
+  };
+}
+
+export function createWorkflowToken(preflight: Record<string, unknown>, candidates: readonly Record<string, unknown>[]): string {
+  const material = {
+    repoRoot: preflight.repoRoot,
+    baseRef: preflight.baseRef,
+    baseRefOid: preflight.baseRefOid,
+    candidates: candidates.map(candidateTokenMaterial),
+  };
+  return crypto.createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}
+
+export function isGuardianWorktreeStatusPath(repoRoot: string, guardianRoot: string, statusPath: string): boolean {
+  const absoluteStatusPath = path.resolve(repoRoot, statusPath.replace(/\/$/, ""));
+  return isInside(absoluteStatusPath, guardianRoot);
+}
+
+export async function plannedCandidate(repoRoot: string, config: Record<string, unknown>, input: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const plan = await guardianDeleteWorktree({ repoRoot, cwd: repoRoot, mode: "plan", deleteBranch: true, config, ...input });
+  if (!plan.ok) return { ok: false, reason: plan.reason, plan };
+  const preflight = plan.preflight as Record<string, unknown>;
+  return {
+    ok: true,
+    confirmToken: plan.confirmToken,
+    targetKind: preflight.targetKind,
+    targetPath: preflight.targetPath ?? null,
+    branch: preflight.branch ?? null,
+    head: preflight.head ?? null,
+    ancestryProven: preflight.ancestryProven,
+    plan,
+  };
+}
+
+export async function discoverCandidates(repoRoot: string, cwd: string, config: Record<string, unknown>, preflight: Record<string, unknown>): Promise<{ readonly candidates: Record<string, unknown>[]; readonly blockers: Record<string, unknown>[] }> {
+  const baseRef = `${String(config.remote)}/${String(config.baseBranch)}`;
+  const guardianRoot = path.resolve(repoRoot, expandWorktreeRoot(String(config.worktreeRoot), repoRoot));
+  const currentWorktree = await getRepoRoot(cwd);
+  const worktrees = await listWorktrees(repoRoot) as Array<{ path: string; branch?: string; head?: string }>;
+  const checkedOutBranches = new Set(worktrees.map((worktree) => worktree.branch).filter(Boolean));
+  const candidates: Record<string, unknown>[] = [];
+  const blockers: Record<string, unknown>[] = [];
+
+  for (const worktree of worktrees) {
+    if (samePath(worktree.path, repoRoot) || samePath(worktree.path, currentWorktree)) continue;
+    if (!isInside(path.resolve(worktree.path), guardianRoot)) continue;
+    if (!worktree.branch || !worktree.head) {
+      blockers.push({ kind: "worktree", targetPath: worktree.path, branch: worktree.branch ?? null, head: worktree.head ?? null, reason: "detached Guardian worktree cannot be cleaned by finish workflow" });
+      continue;
+    }
+    if ((config.protectedBranches as string[]).includes(worktree.branch)) {
+      blockers.push({ kind: "worktree", targetPath: worktree.path, branch: worktree.branch, head: worktree.head, reason: "protected branch worktree cannot be cleaned by finish workflow" });
+      continue;
+    }
+    const dirtyFiles = await getDirtyFiles(worktree.path);
+    if (dirtyFiles.length > 0) {
+      blockers.push({ kind: "worktree", targetPath: worktree.path, branch: worktree.branch, reason: "worktree has uncommitted changes", dirtyFileCount: dirtyFiles.length });
+      continue;
+    }
+    if (!(await isAncestor(repoRoot, worktree.head, baseRef))) {
+      blockers.push({ kind: "worktree", targetPath: worktree.path, branch: worktree.branch, head: worktree.head, reason: "worktree branch is not proven reachable from base ref" });
+      continue;
+    }
+    const candidate = await plannedCandidate(repoRoot, config, { targetPath: worktree.path });
+    if (candidate.ok) candidates.push({ kind: "worktree", ...candidate });
+    else blockers.push({ kind: "worktree", targetPath: worktree.path, branch: worktree.branch, reason: candidate.reason });
+  }
+
+  const branches = await listBranches(repoRoot) as Array<{ name: string; commit: string }>;
+  for (const branch of branches) {
+    if (!branch.name || !branch.commit) continue;
+    if (checkedOutBranches.has(branch.name)) continue;
+    if ((config.protectedBranches as string[]).includes(branch.name)) continue;
+    if (!(await isAncestor(repoRoot, branch.commit, baseRef))) continue;
+    const candidate = await plannedCandidate(repoRoot, config, { branch: branch.name });
+    if (candidate.ok) candidates.push({ kind: "branch", ...candidate });
+  }
+
+  if (candidates.length > MAX_WORKFLOW_CLEANUP_CANDIDATES) {
+    blockers.push({ kind: "candidate-bound", reason: `cleanup candidate count exceeds maximum ${MAX_WORKFLOW_CLEANUP_CANDIDATES}`, candidateCount: candidates.length, maxCandidateCount: MAX_WORKFLOW_CLEANUP_CANDIDATES });
+  }
+
+  preflight.candidateCount = candidates.length;
+  preflight.blockerCount = blockers.length;
+  preflight.maxCandidateCount = MAX_WORKFLOW_CLEANUP_CANDIDATES;
+  return { candidates, blockers };
+}

package/src/workflow.ts

@@ -0,0 +1,84 @@
+import path from "node:path";
+import { expandWorktreeRoot, loadConfig } from "./config.ts";
+import { guardianDeleteWorktree } from "./delete.ts";
+import { fetchRemote, getCurrentBranch, getDirtyFiles, getRefCommit, getRepoRoot, listStashes } from "./git.ts";
+import { candidateTokenMaterial, createWorkflowToken, discoverCandidates, isGuardianWorktreeStatusPath } from "./workflow-candidates.ts";
+
+function blocked(reason: string, details: Record<string, unknown> = {}, preflight?: Record<string, unknown>): Record<string, unknown> {
+  if (preflight) preflight.blockers = [...((preflight.blockers as string[] | undefined) ?? []), reason];
+  return { ok: false, status: "blocked", reason, ...details, ...(preflight ? { preflight } : {}) };
+}
+
+export async function guardianFinishWorkflow(input: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
+  const cwd = typeof input.cwd === "string" ? input.cwd : typeof input.repoRoot === "string" ? input.repoRoot : process.cwd();
+  const repoRoot = typeof input.repoRoot === "string" ? input.repoRoot : await getRepoRoot(cwd);
+  const { config } = input.config && typeof input.config === "object" ? { config: input.config as Record<string, unknown> } : await loadConfig(repoRoot);
+  const mode = input.mode ?? "plan";
+  const baseRef = `${String(config.remote)}/${String(config.baseBranch)}`;
+  const guardianRoot = path.resolve(repoRoot, expandWorktreeRoot(String(config.worktreeRoot), repoRoot));
+  const preflight: Record<string, unknown> = {
+    repoRoot: path.resolve(repoRoot),
+    mode,
+    remote: config.remote,
+    baseBranch: config.baseBranch,
+    baseRef,
+    baseRefOid: null,
+    baseRefFetched: false,
+    currentBranch: null,
+    dirtyFiles: [],
+    dirtyFileCount: 0,
+    stashCount: 0,
+    candidateCount: 0,
+    blockerCount: 0,
+    blockers: [],
+  };
+
+  if (mode !== "plan" && mode !== "apply") return blocked("mode must be plan or apply", { mode }, preflight);
+
+  try {
+    await fetchRemote(repoRoot, String(config.remote));
+    preflight.baseRefFetched = true;
+    preflight.baseRefOid = await getRefCommit(repoRoot, baseRef);
+  } catch (error) {
+    return blocked("remote base ref could not be fetched or resolved", { baseRef, error: error instanceof Error ? error.message : String(error) }, preflight);
+  }
+
+  preflight.currentBranch = await getCurrentBranch(repoRoot);
+  const dirtyFiles = await getDirtyFiles(repoRoot);
+  const blockingDirtyFiles = dirtyFiles.filter((file) => !isGuardianWorktreeStatusPath(repoRoot, guardianRoot, file));
+  const ignoredGuardianWorktreeFiles = dirtyFiles.filter((file) => isGuardianWorktreeStatusPath(repoRoot, guardianRoot, file));
+  preflight.dirtyFiles = dirtyFiles;
+  preflight.dirtyFileCount = dirtyFiles.length;
+  preflight.blockingDirtyFiles = blockingDirtyFiles;
+  preflight.blockingDirtyFileCount = blockingDirtyFiles.length;
+  preflight.ignoredGuardianWorktreeFiles = ignoredGuardianWorktreeFiles;
+  preflight.ignoredGuardianWorktreeFileCount = ignoredGuardianWorktreeFiles.length;
+  if (blockingDirtyFiles.length > 0) return blocked("primary worktree has uncommitted changes; commit implemented code before finish workflow cleanup", { dirtyFiles: blockingDirtyFiles }, preflight);
+
+  const stashes = await listStashes(repoRoot);
+  preflight.stashCount = stashes.length;
+  if (stashes.length > 0 && config.allowStashIfUnrelated !== true) return blocked("stash inventory is non-empty", { stashes }, preflight);
+
+  const { candidates, blockers } = await discoverCandidates(repoRoot, cwd, config, preflight);
+  if (blockers.length > 0) return blocked("cleanup blockers must be resolved before apply", { candidates, blockers }, preflight);
+  const confirmToken = createWorkflowToken(preflight, candidates);
+  if (mode === "plan") return { ok: true, status: "planned", confirmToken, preflight, candidates, blockers };
+  if (input.confirmToken !== confirmToken) return blocked("confirm token mismatch; re-run mode=plan and use the returned confirmToken", { tokenMatched: false, candidates, blockers }, preflight);
+
+  const results = [];
+  for (const candidate of candidates) {
+    const targetKind = typeof candidate.targetKind === "string" ? candidate.targetKind : undefined;
+    const targetPath = targetKind === "worktree" && typeof candidate.targetPath === "string" ? candidate.targetPath : undefined;
+    const branch = targetKind !== "worktree" && typeof candidate.branch === "string" ? candidate.branch : undefined;
+    const plan = await guardianDeleteWorktree({ repoRoot, cwd: repoRoot, mode: "plan", targetPath, branch, deleteBranch: true, config });
+    if (!plan.ok) {
+      results.push({ ...candidateTokenMaterial(candidate), ok: false, status: "blocked", reason: plan.reason });
+      continue;
+    }
+    const apply = await guardianDeleteWorktree({ repoRoot, cwd: repoRoot, mode: "apply", targetPath, branch, deleteBranch: true, confirmToken: plan.confirmToken, config });
+    results.push({ ...candidateTokenMaterial(candidate), ok: apply.ok, status: apply.status, reason: apply.reason, worktreeRemoved: apply.worktreeRemoved, branchDeleted: apply.branchDeleted, safetyRef: apply.safetyRef });
+  }
+
+  const failedResults = results.filter((result) => result.ok !== true);
+  return { ok: failedResults.length === 0, status: failedResults.length === 0 ? "cleaned" : "partial", preflight, candidates, blockers, results };
+}