opencode-worktree-guardian 0.1.0

package/src/delete-worktree.ts

@@ -0,0 +1,222 @@
+import path from "node:path";
+import { expandWorktreeRoot, loadConfig } from "./config.ts";
+import { abandonBranch, createSafetyRef, deleteBranch, getBranchCommit, getDirtyFiles, getHeadCommit, getIgnoredFiles, getRepoRoot, listStashes, listWorktrees, removeWorktree } from "./git.ts";
+import { isSameOrInside, samePath } from "./filesystem-boundaries.ts";
+import { getGuardianPaths, readState, recordSession } from "./state.ts";
+import { blocked, createConfirmToken, errorMessage, withDeleteReport } from "./delete-worktree-report.ts";
+import { collectIgnoredFileFingerprint, recordAncestryPreflight } from "./delete-worktree-preflight.ts";
+import { findTarget } from "./delete-worktree-targets.ts";
+import type { GuardianSession, WorktreeEntry } from "./types.ts";
+
+function emptyDeletePreflight(repoRoot: string, mode: unknown, deleteRequestedBranch: boolean, abandonUnmerged: boolean, allowIgnoredFiles: boolean): Record<string, unknown> {
+  return {
+    repoRoot: path.resolve(repoRoot),
+    mode,
+    targetKind: null,
+    targetPath: null,
+    worktreeListed: null,
+    branch: null,
+    head: null,
+    detached: false,
+    sessionId: null,
+    sessionStatus: "unrecorded",
+    sessionRecorded: false,
+    deleteBranch: deleteRequestedBranch,
+    abandonUnmerged,
+    ancestryRef: null,
+    ancestryProven: null,
+    unmergedCommits: [],
+    unmergedCommitCount: 0,
+    allowIgnoredFiles,
+    dirtyFiles: [],
+    dirtyFileCount: 0,
+    ignoredFiles: [],
+    ignoredFileCount: 0,
+    stashCount: 0,
+    safetyRef: null,
+    blockers: [],
+  };
+}
+
+async function rejectInvalidDeleteRequest(input: Record<string, unknown>, config: Record<string, unknown>, preflight: Record<string, unknown>) {
+  const mode = input.mode;
+  if (mode !== "plan" && mode !== "apply") return blocked("mode must be plan or apply", { mode }, preflight);
+  if (input.abandonUnmerged === true && input.deleteBranch !== true) return blocked("abandonUnmerged requires deleteBranch=true", {}, preflight);
+  if (typeof input.branch === "string" && (config.protectedBranches as string[]).includes(input.branch)) {
+    preflight.branch = input.branch;
+    return blocked("protected branches cannot be deleted by guardian_delete_worktree", { branch: input.branch }, preflight);
+  }
+  return null;
+}
+
+async function loadDeleteContext(input: Record<string, unknown>, repoRoot: string, config: Record<string, unknown>) {
+  const guardianPaths = await getGuardianPaths(repoRoot);
+  const state = input.state && typeof input.state === "object" ? input.state as { sessions?: Record<string, GuardianSession> } : await readState(guardianPaths, { repoRoot, config });
+  const sessions = Object.values(state.sessions ?? {});
+  const worktrees = await listWorktrees(repoRoot) as WorktreeEntry[];
+  return { sessions, worktrees };
+}
+
+async function preflightBranchOnlyDeletion(input: Record<string, unknown>, config: Record<string, unknown>, preflight: Record<string, unknown>, worktrees: WorktreeEntry[], targetKind: "orphan-branch" | "stale-branch" | "merged-branch", session: GuardianSession | undefined, resolvedBranch: string | undefined, resolvedHead: string | undefined, ownershipProof: string | undefined, unresolvedReason: string) {
+  const repoRoot = String(preflight.repoRoot);
+  const deleteRequestedBranch = input.deleteBranch === true;
+  const abandonUnmerged = input.abandonUnmerged === true;
+  const branch = String(resolvedBranch ?? session?.branch ?? "");
+  preflight.targetPath = session?.worktree_path ? path.resolve(String(session.worktree_path)) : null;
+  preflight.branch = branch;
+  preflight.detached = false;
+  preflight.ownershipProof = ownershipProof ?? (targetKind === "orphan-branch" ? "active-session" : targetKind === "merged-branch" ? "ancestry-proof" : null);
+  if (targetKind === "stale-branch" && !ownershipProof) return blocked(unresolvedReason, { branch }, preflight);
+  if (!deleteRequestedBranch) return blocked(`${targetKind} cleanup requires deleteBranch=true`, { branch }, preflight);
+  if ((config.protectedBranches as string[]).includes(branch)) return blocked("protected branches cannot be deleted by guardian_delete_worktree", { branch }, preflight);
+  const checkedOut = worktrees.find((worktree) => worktree.branch === branch);
+  preflight.branchCheckedOut = Boolean(checkedOut);
+  if (checkedOut) return blocked("branch is checked out in a git worktree", { branch, targetPath: checkedOut.path }, preflight);
+  let head = resolvedHead;
+  try {
+    head = head ?? await getBranchCommit(repoRoot, branch);
+  } catch {
+    return blocked("branch does not exist", { branch }, preflight);
+  }
+  preflight.head = head;
+  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 baseRef = session?.base_ref ?? `${String(config.remote)}/${String(config.baseBranch)}`;
+  const proven = await recordAncestryPreflight(repoRoot, head, baseRef, preflight);
+  if (!proven && abandonUnmerged && preflight.unmergedCommitError) return blocked("unmerged commits could not be listed", { branch, head, baseRef, error: preflight.unmergedCommitError }, preflight);
+  if (!proven && !abandonUnmerged) return blocked("branch head is not proven reachable from base ref", { branch, head, baseRef }, preflight);
+  const confirmToken = createConfirmToken(preflight);
+  if (input.mode === "plan") return withDeleteReport({ ok: true, status: "planned", confirmToken }, preflight, { action: "planned" });
+  if (input.confirmToken !== confirmToken) return blocked("confirm token mismatch; re-run mode=plan and use the returned confirmToken", { tokenMatched: false }, preflight);
+  return applyBranchOnlyDeletion(input, config, preflight, session, targetKind, branch, head, proven, abandonUnmerged);
+}
+
+async function applyBranchOnlyDeletion(input: Record<string, unknown>, config: Record<string, unknown>, preflight: Record<string, unknown>, session: GuardianSession | undefined, targetKind: "orphan-branch" | "stale-branch" | "merged-branch", branch: string, head: string, proven: boolean, abandonUnmerged: boolean) {
+  const repoRoot = String(preflight.repoRoot);
+  const safetyRef = await createSafetyRef(repoRoot, { sessionId: session?.session_id ?? (targetKind === "merged-branch" ? "merged-local-branch" : "orphan-guardian-branch"), branch, commit: head, timestamp: input.timestamp });
+  preflight.safetyRef = safetyRef;
+  if (!proven && abandonUnmerged) await abandonBranch(repoRoot, branch);
+  else await deleteBranch(repoRoot, branch);
+  if (session?.session_id) {
+    await recordSession(repoRoot, config, {
+      ...session,
+      session_id: session.session_id,
+      status: !proven && abandonUnmerged ? "abandoned" : "deleted",
+      head_commit: head,
+      safety_refs: [...(session.safety_refs ?? []), safetyRef],
+      deleted_worktree_path: session.worktree_path,
+      deleted_branch: branch,
+      branch_only_delete: true,
+      abandon_unmerged: !proven && abandonUnmerged,
+      abandoned_branch: !proven && abandonUnmerged ? branch : undefined,
+      unmerged_commits: !proven && abandonUnmerged ? preflight.unmergedCommits : undefined,
+    }, { event: { type: targetKind === "stale-branch" ? "guardian_delete_stale_branch" : "guardian_delete_orphan_branch", session_id: session.session_id, ref: safetyRef } });
+  }
+  const actionPrefix = targetKind === "stale-branch" ? "stale-branch" : targetKind === "merged-branch" ? "merged-branch" : "orphan-branch";
+  return withDeleteReport({ ok: true, status: !proven && abandonUnmerged ? "abandoned" : "deleted", targetPath: session?.worktree_path ?? null, branch, head, safetyRef, branchDeleted: true, worktreeRemoved: false, abandonUnmerged: !proven && abandonUnmerged }, preflight, { action: !proven && abandonUnmerged ? `${actionPrefix}-abandoned` : `${actionPrefix}-deleted`, worktreeRemoved: false });
+}
+
+async function preflightWorktreeDeletion(input: Record<string, unknown>, config: Record<string, unknown>, preflight: Record<string, unknown>, entry: WorktreeEntry, session: GuardianSession | undefined, cwd: string) {
+  const repoRoot = String(preflight.repoRoot);
+  const deleteRequestedBranch = input.deleteBranch === true;
+  const abandonUnmerged = input.abandonUnmerged === true;
+  const allowIgnoredFiles = input.allowIgnoredFiles === true;
+  preflight.targetPath = path.resolve(entry.path);
+  preflight.worktreeListed = true;
+  preflight.branch = entry.branch ?? null;
+  preflight.head = entry.head ?? null;
+  preflight.detached = entry.detached === true || !entry.branch;
+  if (samePath(entry.path, repoRoot)) return blocked("refusing to delete the primary repo worktree", { targetPath: entry.path }, preflight);
+  const currentWorktree = await getRepoRoot(cwd);
+  preflight.currentWorktree = currentWorktree;
+  if (samePath(entry.path, currentWorktree)) return blocked("refusing to delete the current execution worktree", { targetPath: entry.path, currentWorktree }, preflight);
+  if (entry.detached || !entry.branch) return blocked("detached HEAD worktrees cannot be deleted by guardian_delete_worktree", { targetPath: entry.path }, preflight);
+  if ((config.protectedBranches as string[]).includes(entry.branch)) return blocked("protected branches cannot be deleted by guardian_delete_worktree", { branch: entry.branch }, preflight);
+  const guardianRoot = path.resolve(repoRoot, expandWorktreeRoot(String(config.worktreeRoot), repoRoot));
+  if (!session && !isSameOrInside(path.resolve(entry.path), guardianRoot)) return blocked("unrecorded worktrees outside the Guardian worktree root cannot be deleted", { targetPath: entry.path, guardianRoot }, preflight);
+  const dirtyFiles = await getDirtyFiles(entry.path);
+  preflight.dirtyFiles = dirtyFiles;
+  preflight.dirtyFileCount = dirtyFiles.length;
+  if (dirtyFiles.length > 0) return blocked("worktree has uncommitted changes", { dirtyFiles, targetPath: entry.path }, preflight);
+  const ignoredFiles = await getIgnoredFiles(entry.path);
+  preflight.ignoredFiles = ignoredFiles;
+  preflight.ignoredFileFingerprint = await collectIgnoredFileFingerprint(entry.path, ignoredFiles);
+  preflight.ignoredFileCount = ignoredFiles.length;
+  if (ignoredFiles.length > 0 && !allowIgnoredFiles) return blocked("worktree has ignored files", { ignoredFiles, targetPath: entry.path }, 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);
+  if (deleteRequestedBranch) {
+    const head = entry.head ?? await getHeadCommit(entry.path);
+    preflight.head = head;
+    const baseRef = session?.base_ref ?? `${String(config.remote)}/${String(config.baseBranch)}`;
+    const proven = await recordAncestryPreflight(repoRoot, head, baseRef, preflight);
+    if (!proven && abandonUnmerged && preflight.unmergedCommitError) return blocked("unmerged commits could not be listed", { branch: entry.branch, head, baseRef, error: preflight.unmergedCommitError }, preflight);
+    if (!proven && !abandonUnmerged) return blocked("branch head is not proven reachable from base ref", { branch: entry.branch, head, baseRef }, preflight);
+  }
+  const confirmToken = createConfirmToken(preflight);
+  if (input.mode === "plan") return withDeleteReport({ ok: true, status: "planned", confirmToken }, preflight, { action: "planned" });
+  if (input.confirmToken !== confirmToken) return blocked("confirm token mismatch; re-run mode=plan and use the returned confirmToken", { tokenMatched: false }, preflight);
+  return applyWorktreeDeletion(input, config, preflight, entry, session);
+}
+
+async function applyWorktreeDeletion(input: Record<string, unknown>, config: Record<string, unknown>, preflight: Record<string, unknown>, entry: WorktreeEntry, session: GuardianSession | undefined) {
+  const repoRoot = String(preflight.repoRoot);
+  const deleteRequestedBranch = input.deleteBranch === true;
+  const abandonUnmerged = input.abandonUnmerged === true;
+  const branch = entry.branch;
+  if (!branch) return blocked("detached HEAD worktrees cannot be deleted by guardian_delete_worktree", { targetPath: entry.path }, preflight);
+  const safetySessionId = session?.session_id ?? "unrecorded-worktree";
+  const head = String(preflight.head ?? await getHeadCommit(entry.path));
+  const safetyRef = await createSafetyRef(repoRoot, { sessionId: safetySessionId, branch, commit: head, timestamp: input.timestamp });
+  preflight.safetyRef = safetyRef;
+  await removeWorktree(repoRoot, entry.path);
+  let branchDeleted = false;
+  if (deleteRequestedBranch) {
+    try {
+      if (preflight.ancestryProven === false && abandonUnmerged) await abandonBranch(repoRoot, branch);
+      else await deleteBranch(repoRoot, branch);
+      branchDeleted = true;
+    } catch (error) {
+      return recordPartialWorktreeDeletion(repoRoot, config, preflight, entry, session, head, safetyRef, abandonUnmerged, error);
+    }
+  }
+  if (session?.session_id) {
+    const abandoned = preflight.ancestryProven === false && abandonUnmerged;
+    await recordSession(repoRoot, config, { ...session, session_id: session.session_id, status: abandoned ? "abandoned" : "deleted", head_commit: head, safety_refs: [...(session.safety_refs ?? []), safetyRef], deleted_worktree_path: entry.path, deleted_branch: branchDeleted ? branch : null, abandon_unmerged: abandoned, abandoned_branch: abandoned ? branch : undefined, unmerged_commits: abandoned ? preflight.unmergedCommits : undefined }, { event: { type: "guardian_delete_worktree", session_id: session.session_id, ref: safetyRef } });
+  }
+  const abandoned = preflight.ancestryProven === false && abandonUnmerged;
+  return withDeleteReport({ ok: true, status: abandoned ? "abandoned" : "deleted", targetPath: entry.path, branch, head, safetyRef, branchDeleted, worktreeRemoved: true, abandonUnmerged: abandoned }, preflight, { action: abandoned ? "worktree-and-branch-abandoned" : branchDeleted ? "worktree-and-branch-deleted" : "worktree-deleted", worktreeRemoved: true });
+}
+
+async function recordPartialWorktreeDeletion(repoRoot: string, config: Record<string, unknown>, preflight: Record<string, unknown>, entry: WorktreeEntry, session: GuardianSession | undefined, head: string, safetyRef: string, abandonUnmerged: boolean, error: unknown) {
+  const branchDeleteError = errorMessage(error);
+  if (session?.session_id) {
+    await recordSession(repoRoot, config, { ...session, session_id: session.session_id, status: "deleted", head_commit: head, safety_refs: [...(session.safety_refs ?? []), safetyRef], deleted_worktree_path: entry.path, deleted_branch: null, branch_delete_failed: true, branch_delete_error: branchDeleteError, abandon_unmerged: preflight.ancestryProven === false && abandonUnmerged, unmerged_commits: preflight.ancestryProven === false && abandonUnmerged ? preflight.unmergedCommits : undefined }, { event: { type: "guardian_delete_worktree_partial", session_id: session.session_id, ref: safetyRef } });
+  }
+  return withDeleteReport({ ok: false, status: "partial", reason: "worktree deleted but branch deletion failed", targetPath: entry.path, branch: entry.branch, head, safetyRef, branchDeleted: false, worktreeRemoved: true, error: branchDeleteError }, preflight, { action: "worktree-deleted-branch-delete-failed", worktreeRemoved: true, branchDeleteError });
+}
+
+export async function guardianDeleteWorktree(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 preflight = emptyDeletePreflight(repoRoot, input.mode, input.deleteBranch === true, input.abandonUnmerged === true, input.allowIgnoredFiles === true);
+  const invalid = await rejectInvalidDeleteRequest(input, config, preflight);
+  if (invalid) return invalid;
+  const { sessions, worktrees } = await loadDeleteContext(input, repoRoot, config);
+  const target = await findTarget({ ...input, repoRoot }, worktrees, sessions);
+  const { entry, session, targetKind, branch: resolvedBranch, head: resolvedHead, ownershipProof, unresolvedReason } = target;
+  if (!entry && targetKind !== "orphan-branch" && targetKind !== "stale-branch" && targetKind !== "merged-branch") return blocked(unresolvedReason, {}, preflight);
+  preflight.targetKind = targetKind ?? "worktree";
+  preflight.worktreeListed = Boolean(entry);
+  preflight.sessionId = session?.session_id ?? null;
+  preflight.sessionStatus = session?.status ?? "unrecorded";
+  preflight.sessionRecorded = Boolean(session);
+  if (targetKind === "orphan-branch" || targetKind === "stale-branch" || targetKind === "merged-branch") {
+    return preflightBranchOnlyDeletion(input, config, preflight, worktrees, targetKind, session, resolvedBranch, resolvedHead, ownershipProof, unresolvedReason);
+  }
+  if (!entry) return blocked(unresolvedReason, {}, preflight);
+  return preflightWorktreeDeletion(input, config, preflight, entry, session, cwd);
+}

package/src/delete.ts

@@ -0,0 +1 @@
+export { guardianDeleteWorktree } from "./delete-worktree.ts";

package/src/deletion-fingerprint.ts

@@ -0,0 +1,59 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { relativePath } from "./filesystem-boundaries.ts";
+
+export type DeletionFingerprintEntry = Record<string, string | number>;
+
+async function collectFilesystemFingerprint(repoRoot: string, absolutePath: string) {
+  const entries: DeletionFingerprintEntry[] = [];
+  async function visit(currentAbsolute: string) {
+    const stat = await fs.lstat(currentAbsolute);
+    const currentRelative = relativePath(repoRoot, currentAbsolute);
+    if (stat.isSymbolicLink()) {
+      entries.push({ path: currentRelative, kind: "symlink", target: await fs.readlink(currentAbsolute) });
+      return;
+    }
+    if (stat.isDirectory()) {
+      entries.push({ path: currentRelative, kind: "directory" });
+      const children = await fs.readdir(currentAbsolute);
+      for (const child of children.sort((left, right) => left.localeCompare(right))) await visit(path.join(currentAbsolute, child));
+      return;
+    }
+    if (stat.isFile()) {
+      const content = await fs.readFile(currentAbsolute);
+      entries.push({ path: currentRelative, kind: "file", size: stat.size, sha256: crypto.createHash("sha256").update(content).digest("hex") });
+      return;
+    }
+    entries.push({ path: currentRelative, kind: "other", size: stat.size });
+  }
+  await visit(absolutePath);
+  return entries;
+}
+
+export function collectCleanupFingerprint(repoRoot: string, absolutePath: string) {
+  return collectFilesystemFingerprint(repoRoot, absolutePath);
+}
+
+export function collectDeleteFingerprint(repoRoot: string, absolutePath: string) {
+  return collectFilesystemFingerprint(repoRoot, absolutePath);
+}
+
+export async function collectIgnoredFileFingerprint(worktreePath: string, ignoredFiles: string[]) {
+  const entries = new Set<string>();
+  async function addEntry(relativePath: string) {
+    const normalized = relativePath.replace(/\/+/g, "/");
+    entries.add(normalized);
+    if (!normalized.endsWith("/")) return;
+    const absoluteDir = path.join(worktreePath, normalized);
+    let children: string[] = [];
+    try {
+      children = await fs.readdir(absoluteDir);
+    } catch {
+      return;
+    }
+    for (const child of children) await addEntry(`${normalized}${child}${(await fs.stat(path.join(absoluteDir, child))).isDirectory() ? "/" : ""}`);
+  }
+  for (const ignoredFile of ignoredFiles) await addEntry(ignoredFile);
+  return [...entries].sort();
+}

package/src/done-primary-publish.ts

@@ -0,0 +1,129 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { createSafetyRef, fetchRemote, getCurrentBranch, getHeadCommit, getRefCommit, getRepoRoot, isAncestor, listStashes, runGit } from "./git.ts";
+import { guardianFinishWorkflow } from "./workflow.ts";
+import type { GuardianConfig, MutableRecord } from "./types.ts";
+import type { DirtySnapshot } from "./done-primary-snapshot.ts";
+import { dirtySnapshot } from "./done-primary-snapshot.ts";
+import { blocked, errorMessage, samePath, text } from "./done-shared.ts";
+
+type PrimaryPreflightResult =
+  | { readonly ok: false; readonly preflight: MutableRecord; readonly result: MutableRecord }
+  | { readonly ok: true; readonly preflight: MutableRecord; readonly snapshot: DirtySnapshot; readonly commitMessage: string; readonly confirmToken: string };
+
+export function createPrimaryToken(preflight: Record<string, unknown>, snapshot: Record<string, unknown>, commitMessage: string): string {
+  const material = {
+    repoRoot: preflight.repoRoot,
+    branch: preflight.currentBranch,
+    head: preflight.head,
+    baseRef: preflight.baseRef,
+    baseRefOid: preflight.baseRefOid,
+    commitMessage,
+    snapshot,
+  };
+  return crypto.createHash("sha256").update(JSON.stringify(material)).digest("hex");
+}
+
+export async function primaryPreflight(repoRoot: string, cwd: string, config: GuardianConfig, input: Record<string, unknown>): Promise<PrimaryPreflightResult> {
+  const currentWorktree = await getRepoRoot(cwd);
+  const branch = await getCurrentBranch(currentWorktree);
+  const baseRef = `${String(config.remote)}/${String(config.baseBranch)}`;
+  const preflight: MutableRecord = {
+    repoRoot: path.resolve(repoRoot),
+    currentWorktree,
+    currentBranch: branch,
+    baseBranch: config.baseBranch,
+    remote: config.remote,
+    baseRef,
+    baseRefOid: null,
+    baseRefFetched: false,
+    head: null,
+    branchProtected: Array.isArray(config.protectedBranches) && typeof branch === "string" ? config.protectedBranches.includes(branch) : false,
+    stashCount: 0,
+    dirtyFileCount: 0,
+    dirtyFiles: [],
+    blockers: [],
+  };
+
+  if (!samePath(currentWorktree, repoRoot)) return { ok: false, preflight, result: blocked("primary-main publish requires the primary repository worktree", { currentWorktree, repoRoot }, preflight) };
+  if (!branch) return { ok: false, preflight, result: blocked("detached HEAD cannot be published by guardian_done", {}, preflight) };
+  if (branch !== config.baseBranch) return { ok: false, preflight, result: blocked("primary-main publish requires the configured base branch", { branch, baseBranch: config.baseBranch }, preflight) };
+  if (!preflight.branchProtected) return { ok: false, preflight, result: blocked("primary-main publish lane requires a protected base branch", { branch }, preflight) };
+
+  try {
+    await fetchRemote(repoRoot, String(config.remote));
+    preflight.baseRefFetched = true;
+    preflight.baseRefOid = await getRefCommit(repoRoot, baseRef);
+  } catch (error) {
+    return { ok: false, preflight, result: blocked("remote base ref could not be fetched or resolved", { baseRef, error: errorMessage(error) }, preflight) };
+  }
+
+  const head = await getHeadCommit(repoRoot);
+  preflight.head = head;
+  if (head !== preflight.baseRefOid) return { ok: false, preflight, result: blocked("primary base branch is not synced to remote; sync before publishing dirty primary work", { head, baseRefOid: preflight.baseRefOid }, preflight) };
+
+  const stashes = await listStashes(repoRoot);
+  preflight.stashCount = stashes.length;
+  if (stashes.length > 0 && config.allowStashIfUnrelated !== true) return { ok: false, preflight, result: blocked("stash inventory is non-empty", { stashes }, preflight) };
+
+  const snapshot = await dirtySnapshot(repoRoot, config);
+  preflight.dirtyFiles = snapshot.paths;
+  preflight.dirtyFileCount = snapshot.paths.length;
+  if (snapshot.paths.length === 0) return { ok: false, preflight, result: blocked("primary-main publish requires dirty implemented code; use cleanup-only lane instead", {}, preflight) };
+
+  const commitMessage = text(input.commitMessage).trim();
+  if (!commitMessage) return { ok: false, preflight, result: blocked("commitMessage is required for primary-main publish", { dirtyFiles: snapshot.paths }, preflight) };
+
+  const confirmToken = createPrimaryToken(preflight, snapshot, commitMessage);
+  return { ok: true, preflight, snapshot, commitMessage, confirmToken };
+}
+
+export async function primaryMainDone(repoRoot: string, cwd: string, config: GuardianConfig, input: Record<string, unknown>): Promise<MutableRecord> {
+  const mode = input.mode ?? "plan";
+  const planned = await primaryPreflight(repoRoot, cwd, config, input);
+  if (!planned.ok) return planned.result;
+  const { preflight, snapshot, commitMessage, confirmToken } = planned;
+  const plan = {
+    ok: true,
+    status: "planned",
+    lane: "primary-main-publish",
+    confirmToken,
+    commitMessage,
+    preflight,
+    dirtySnapshot: snapshot,
+    nextAction: "After explicit user confirmation, apply with confirm=true and the same commitMessage to create a safety ref, commit the token-bound dirty files, push the base branch, fetch, and return a fresh cleanup plan.",
+  };
+  if (mode === "plan") return plan;
+  if (mode !== "apply") return blocked("mode must be plan or apply", { mode }, preflight);
+  if (input.confirmToken !== confirmToken) return blocked("plan changed; rerun plan and review the updated dirty files before applying", { tokenMatched: false }, preflight);
+
+  const branch = String(preflight.currentBranch);
+  const head = String(preflight.head);
+  const safetySessionId = typeof input.sessionId === "string" && input.sessionId.length > 0 ? input.sessionId : "primary-main";
+  const safetyRef = await createSafetyRef(repoRoot, { sessionId: safetySessionId, branch, commit: head, timestamp: input.timestamp });
+  preflight.safetyRef = safetyRef;
+  const dirtyPaths = snapshot.paths;
+  const snapshotEntries = snapshot.entries;
+  const missingPaths = new Set(snapshot.fingerprints.filter((fingerprint) => fingerprint.kind === "missing").map((fingerprint) => fingerprint.path));
+  const unstagedDeletedPaths = new Set(snapshotEntries.filter((entry) => entry.status[1] === "D").flatMap((entry) => [entry.path, entry.sourcePath].filter((value): value is string => typeof value === "string")));
+  const stageablePaths = dirtyPaths.filter((dirtyPath) => !missingPaths.has(dirtyPath) || unstagedDeletedPaths.has(dirtyPath));
+  try {
+    if (stageablePaths.length > 0) await runGit(repoRoot, ["add", "--all", "--", ...stageablePaths]);
+    await runGit(repoRoot, ["commit", "-m", commitMessage]);
+  } catch (error) {
+    return blocked("commit failed", { safetyRef, error: errorMessage(error) }, preflight);
+  }
+
+  const commit = await getHeadCommit(repoRoot);
+  try {
+    await runGit(repoRoot, ["push", String(config.remote), branch]);
+    await fetchRemote(repoRoot, String(config.remote));
+  } catch (error) {
+    return blocked("push failed after commit; safety ref preserves the pre-commit head", { safetyRef, commit, error: errorMessage(error) }, preflight);
+  }
+
+  const proven = await isAncestor(repoRoot, commit, `${String(config.remote)}/${String(config.baseBranch)}`);
+  if (!proven) return blocked("published commit is not proven reachable from remote base", { safetyRef, commit }, preflight);
+  const cleanupPlan = await guardianFinishWorkflow({ repoRoot, cwd: repoRoot, mode: "plan", config });
+  return { ok: true, status: "published", lane: "primary-main-publish", branch, commit, safetyRef, preflight, cleanupPlan };
+}

package/src/done-primary-snapshot.ts

@@ -0,0 +1,79 @@
+import { execFile } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { expandWorktreeRoot } from "./config.ts";
+import type { RecordLike } from "./types.ts";
+import { errorCode } from "./types.ts";
+
+const execFileAsync = promisify(execFile);
+
+export type StatusEntry = { readonly status: string; readonly path: string; readonly sourcePath?: string };
+
+export type FileFingerprint = {
+  readonly path: string;
+  readonly kind: "file" | "directory" | "other" | "missing";
+  readonly size: number | null;
+  readonly hash: string | null;
+};
+
+export type DirtySnapshot = {
+  readonly entries: readonly StatusEntry[];
+  readonly paths: readonly string[];
+  readonly fingerprints: readonly FileFingerprint[];
+};
+
+function isInside(candidate: string, parent: string): boolean {
+  const relative = path.relative(parent, candidate);
+  return relative === "" || (Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export function isGuardianWorktreeStatusPath(repoRoot: string, config: RecordLike, statusPath: string): boolean {
+  const guardianRoot = path.resolve(repoRoot, expandWorktreeRoot(String(config.worktreeRoot), repoRoot));
+  const absoluteStatusPath = path.resolve(repoRoot, statusPath.replace(/\/$/, ""));
+  return isInside(absoluteStatusPath, guardianRoot);
+}
+
+export async function statusEntries(repoRoot: string): Promise<StatusEntry[]> {
+  const { stdout } = await execFileAsync("git", ["-C", repoRoot, "status", "--porcelain=v1", "--untracked-files=all", "-z"], { maxBuffer: 10 * 1024 * 1024 });
+  if (!stdout) return [];
+  const rawEntries = stdout.split("\0").filter(Boolean);
+  const entries: StatusEntry[] = [];
+  for (let index = 0; index < rawEntries.length; index += 1) {
+    const entry = rawEntries[index];
+    const status = entry.slice(0, 2);
+    const filePath = entry.slice(3);
+    if (!filePath) continue;
+    if (status.includes("R") || status.includes("C")) {
+      const sourcePath = rawEntries[index + 1];
+      entries.push({ status, path: filePath, sourcePath });
+      index += 1;
+    } else {
+      entries.push({ status, path: filePath });
+    }
+  }
+  return entries;
+}
+
+export async function fileFingerprint(repoRoot: string, relativePath: string): Promise<FileFingerprint> {
+  const absolutePath = path.join(repoRoot, relativePath);
+  try {
+    const stat = await fs.lstat(absolutePath);
+    if (!stat.isFile()) return { path: relativePath, kind: stat.isDirectory() ? "directory" : "other", size: stat.size, hash: null };
+    const content = await fs.readFile(absolutePath);
+    return { path: relativePath, kind: "file", size: stat.size, hash: crypto.createHash("sha256").update(content).digest("hex") };
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return { path: relativePath, kind: "missing", size: null, hash: null };
+    throw error;
+  }
+}
+
+export async function dirtySnapshot(repoRoot: string, config?: RecordLike): Promise<DirtySnapshot> {
+  const allEntries = await statusEntries(repoRoot);
+  const entries = config ? allEntries.filter((entry) => !isGuardianWorktreeStatusPath(repoRoot, config, entry.path)) : allEntries;
+  const paths = [...new Set(entries.flatMap((entry) => [entry.path, entry.sourcePath].filter((value): value is string => typeof value === "string" && value.length > 0)))].sort((left, right) => left.localeCompare(right));
+  const fingerprints = [];
+  for (const filePath of paths) fingerprints.push(await fileFingerprint(repoRoot, filePath));
+  return { entries, paths, fingerprints };
+}

package/src/done-reattach.ts

@@ -0,0 +1,32 @@
+import path from "node:path";
+import { expandWorktreeRoot } from "./config.ts";
+import { guardianFinish } from "./finish.ts";
+import { getHeadCommit } from "./git.ts";
+import { recordSession } from "./state.ts";
+import type { GuardianConfig, MutableRecord } from "./types.ts";
+import { blocked, isInside } from "./done-shared.ts";
+
+export async function reattachCurrentGuardianWorktree(repoRoot: string, currentWorktree: string, currentBranch: string | null, config: GuardianConfig, sessionId: string, input: Record<string, unknown>): Promise<MutableRecord> {
+  const guardianRoot = path.resolve(repoRoot, expandWorktreeRoot(String(config.worktreeRoot), repoRoot));
+  if (!isInside(currentWorktree, guardianRoot)) {
+    return blocked("no active Guardian lane is recorded for this session; run guardian_status for recovery details", { lane: "missing-session-lane" });
+  }
+  if (!currentBranch) return blocked("detached HEAD cannot be reattached by guardian_done", { lane: "missing-session-lane", currentWorktree });
+  const protectedBranches = Array.isArray(config.protectedBranches) ? config.protectedBranches : [];
+  if (protectedBranches.includes(currentBranch)) {
+    return blocked("protected branches cannot be reattached as Guardian-owned worktrees", { lane: "missing-session-lane", currentBranch, currentWorktree });
+  }
+
+  const headCommit = await getHeadCommit(currentWorktree);
+  await recordSession(repoRoot, config, {
+    session_id: sessionId,
+    status: "active",
+    branch: currentBranch,
+    worktree_path: currentWorktree,
+    base_ref: `${String(config.remote)}/${String(config.baseBranch)}`,
+    head_commit: headCommit,
+    safety_refs: [],
+  }, { event: { type: "guardian_done_reattach", session_id: sessionId } });
+  const result = await guardianFinish({ ...input, repoRoot, cwd: currentWorktree, sessionId, config });
+  return { ...result, lane: "session-finish", reattached: true };
+}

package/src/done-shared.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { isRecordLike } from "./types.ts";
+
+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 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 function text(input: unknown): string {
+  return typeof input === "string" ? input : "";
+}
+
+export function errorMessage(error: unknown): string {
+  if (isRecordLike(error)) {
+    if (typeof error.gitStderr === "string" && error.gitStderr.length > 0) return error.gitStderr;
+    if (typeof error.message === "string" && error.message.length > 0) return error.message;
+  }
+  return String(error);
+}

package/src/done.ts

@@ -0,0 +1,80 @@
+import { loadConfig, normalizeConfig } from "./config.ts";
+import { guardianFinish } from "./finish.ts";
+import { getCurrentBranch, getRepoRoot } from "./git.ts";
+import { isActiveSession } from "./lifecycle.ts";
+import { getGuardianPaths, readState } from "./state.ts";
+import { isRecordLike } from "./types.ts";
+import { reattachCurrentGuardianWorktree } from "./done-reattach.ts";
+import { primaryMainDone } from "./done-primary-publish.ts";
+import { dirtySnapshot } from "./done-primary-snapshot.ts";
+import { blocked, samePath } from "./done-shared.ts";
+import { guardianFinishWorkflow } from "./workflow.ts";
+
+export async function guardianDone(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 = isRecordLike(input.config) ? normalizeConfig(input.config) : (await loadConfig(repoRoot)).config;
+  const mode = input.mode ?? "plan";
+  if (mode !== "plan" && mode !== "apply") return { ok: false, status: "blocked", reason: "mode must be plan or apply", mode };
+
+  const currentWorktree = await getRepoRoot(cwd);
+  const currentBranch = await getCurrentBranch(currentWorktree);
+  const baseBranch = String(config.baseBranch);
+  const protectedBranches = Array.isArray(config.protectedBranches) ? config.protectedBranches : [];
+  const state = await readState(await getGuardianPaths(repoRoot), { repoRoot, config });
+  const sessionId = typeof input.sessionId === "string" && input.sessionId.trim().length > 0 ? input.sessionId : null;
+  const currentSession = sessionId ? state.sessions?.[sessionId] : null;
+
+  if (currentSession && isActiveSession(currentSession) && typeof currentSession.worktree_path === "string") {
+    if (!samePath(currentWorktree, currentSession.worktree_path)) {
+      const snapshot = samePath(currentWorktree, repoRoot) ? await dirtySnapshot(repoRoot, config) : { paths: [] };
+      if (snapshot.paths.length > 0) {
+        if (currentBranch === baseBranch && protectedBranches.includes(baseBranch)) {
+          return primaryMainDone(repoRoot, currentWorktree, config, input);
+        }
+        return blocked("changes were made outside the active Guardian lane; consolidate them before finishing", {
+          lane: "wrong-lane-dirty-work",
+          dirtyFiles: snapshot.paths,
+          nextAction: "Review the dirty files, then rerun guardian_done after they are moved into the active lane.",
+        });
+      }
+      const result = await guardianFinish({ ...input, repoRoot, cwd: currentSession.worktree_path, sessionId, config });
+      return { ...result, lane: "session-finish" };
+    }
+    const result = await guardianFinish({ ...input, repoRoot, cwd: currentWorktree, sessionId, config });
+    return { ...result, lane: "session-finish" };
+  }
+
+  if (typeof input.sessionId === "string" && !samePath(currentWorktree, repoRoot)) {
+    return reattachCurrentGuardianWorktree(repoRoot, currentWorktree, currentBranch, config, input.sessionId, input);
+  }
+
+  if (samePath(currentWorktree, repoRoot) && currentBranch === baseBranch && protectedBranches.includes(baseBranch)) {
+    const snapshot = await dirtySnapshot(repoRoot, config);
+    if (snapshot.paths.length > 0) return primaryMainDone(repoRoot, currentWorktree, config, input);
+    const cleanup = await guardianFinishWorkflow({ ...input, repoRoot, cwd: repoRoot, config });
+    return { ...cleanup, lane: "cleanup-only" };
+  }
+
+  if (samePath(currentWorktree, repoRoot) && currentBranch && protectedBranches.includes(currentBranch)) {
+    return {
+      ok: false,
+      status: "blocked",
+      lane: "primary-rescue-recommended",
+      reason: "dirty protected primary work is not on the configured base branch; rescue it to a Guardian worktree before finishing",
+      currentBranch,
+      baseBranch,
+      suggestedCommands: ["guardian_start createWorktree=true", "guardian_status"],
+    };
+  }
+
+  return {
+    ok: false,
+    status: "blocked",
+    lane: "blocked",
+    reason: "guardian_done could not choose a safe finish lane; use guardian_status for evidence or guardian_finish from an owned session worktree",
+    currentWorktree,
+    currentBranch,
+    baseBranch,
+  };
+}