@north-light/crouter 0.3.154

package/dist/core/worktree.js

@@ -0,0 +1,732 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join, resolve } from 'node:path';
+import { gitSync } from './git.js';
+import { crtrHome } from './canvas/paths.js';
+import { getNode, updateNode } from './canvas/index.js';
+import { CONFIG_FILE, CRTR_DIR_NAME, STATE_FILE } from '../types.js';
+export class WorktreeError extends Error {
+    code;
+    next;
+    detail;
+    constructor(code, message, next, detail) {
+        super(message);
+        this.name = 'WorktreeError';
+        this.code = code;
+        this.next = next;
+        this.detail = detail;
+    }
+}
+function runGit(cwd, args, code, next) {
+    const res = gitSync(args, cwd);
+    if (res.status !== 0) {
+        const detail = (res.stderr.trim() || res.stdout.trim()).trim();
+        throw new WorktreeError(code, `git ${args.join(' ')} failed`, next, detail);
+    }
+    return res.stdout.trim();
+}
+export function managedWorktreesRoot() {
+    return `${crtrHome()}/worktrees`;
+}
+export function managedWorktreePath(nodeId) {
+    return `${managedWorktreesRoot()}/${nodeId}`;
+}
+export function hasOpenManagedWorktree(node) {
+    return node?.managed_worktree?.state === 'open';
+}
+export function openManagedWorktreeForNode(nodeId) {
+    const node = getNode(nodeId);
+    const wt = node?.managed_worktree;
+    return wt?.state === 'open' ? wt : null;
+}
+function repoRootFor(cwd) {
+    return runGit(cwd, ['rev-parse', '--show-toplevel'], 'not_git_repo', 'Pass --cwd pointing inside a git repository.');
+}
+function resolveLandableBase(repoRoot, baseRef) {
+    const ref = `refs/heads/${baseRef}`;
+    // Verify the exact refs/heads name first: rev-parse alone accepts revision
+    // syntax, which could turn a SHA or a `^{commit}` suffix into a non-landable
+    // base even though no local branch by that exact name exists.
+    const exists = gitSync(['show-ref', '--verify', '--quiet', ref], repoRoot);
+    if (exists.status !== 0) {
+        throw new WorktreeError('missing_base_branch', `managed worktree base '${baseRef}' does not name an existing local branch`, 'The base must be a local branch that landing can fast-forward — freshen your local branch from origin first (rebase-not-merge), then base on it.');
+    }
+    return runGit(repoRoot, ['rev-parse', '--verify', ref], 'base_branch_resolve_failed', 'Inspect the local base branch, then retry.');
+}
+/** Path of the worktree where a local branch is currently checked out, or null
+ *  if it is not checked out in any worktree. */
+function checkoutPathForBranch(repoRoot, branch) {
+    const out = runGit(repoRoot, ['worktree', 'list', '--porcelain'], 'worktree_list_failed', 'Inspect the repository worktrees manually, then retry.');
+    let current = null;
+    for (const line of out.split('\n')) {
+        if (line.startsWith('worktree '))
+            current = line.slice('worktree '.length).trim();
+        else if (line === `branch refs/heads/${branch}`)
+            return current;
+    }
+    return null;
+}
+const WORKTREE_LOCK_WAIT_MS = 30_000;
+const WORKTREE_LOCK_POLL_MS = 20;
+const WORKTREE_CLEANUP_TIMEOUT_MS = 5_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Serialize worktree mutation for one repository across crtr processes. Git's
+ * own worktree metadata lock is intentionally short-lived and rejects a second
+ * add instead of waiting, so callers take this transaction lock first. */
+function commonGitDir(repoRoot) {
+    const commonDir = runGit(repoRoot, ['rev-parse', '--git-common-dir'], 'git_common_dir_failed', 'Inspect the repository git metadata, then retry.');
+    return realpathSync(resolve(repoRoot, commonDir));
+}
+function ownerIsAlive(owner) {
+    const pid = Number(owner.split(':', 1)[0]);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+function reclaimDeadLock(lockPath, incumbent) {
+    // A hard-link claim elects exactly one reclaimer without moving lockPath.
+    // Its inode remains the stale lock even if a new owner appears later.
+    const claimPath = `${lockPath}.reclaim`;
+    try {
+        linkSync(lockPath, claimPath);
+    }
+    catch {
+        // A crashed reclaimer can leave its claim behind. Removing that claim is
+        // safe: it names only the already-dead incumbent, and any live reclaimer
+        // then loses authority because its inode check below fails.
+        try {
+            unlinkSync(claimPath);
+        }
+        catch { /* claimant is still resolving it */ }
+        return;
+    }
+    try {
+        const lock = statSync(lockPath);
+        const claim = statSync(claimPath);
+        if (lock.ino === claim.ino && readFileSync(claimPath, 'utf8') === incumbent && !ownerIsAlive(incumbent)) {
+            unlinkSync(lockPath);
+        }
+    }
+    catch { /* owner or another reclaimer changed state; leave it alone */ }
+    finally {
+        try {
+            unlinkSync(claimPath);
+        }
+        catch { /* a later reclaimer will clear this stale claim */ }
+    }
+}
+function withRepositoryWorktreeLock(repoRoot, action) {
+    const commonDir = commonGitDir(repoRoot);
+    const lockRoot = `${crtrHome()}/worktree-locks`;
+    const lockName = createHash('sha256').update(commonDir).digest('hex');
+    const lockPath = `${lockRoot}/${lockName}`;
+    const owner = `${process.pid}:${randomUUID()}`;
+    const tempPath = `${lockPath}.${owner}.tmp`;
+    mkdirSync(lockRoot, { recursive: true });
+    const deadline = Date.now() + WORKTREE_LOCK_WAIT_MS;
+    for (;;) {
+        // Write the owner before atomically linking it into the contention name;
+        // a killed creator leaves only an ignored temp file, never a partial lock.
+        writeFileSync(tempPath, owner, { flag: 'wx' });
+        try {
+            linkSync(tempPath, lockPath);
+            unlinkSync(tempPath);
+            break;
+        }
+        catch (err) {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch { /* process crash leaves harmless temp */ }
+            if (err.code !== 'EEXIST')
+                throw err;
+            let incumbent;
+            try {
+                incumbent = readFileSync(lockPath, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (!ownerIsAlive(incumbent))
+                reclaimDeadLock(lockPath, incumbent);
+            if (Date.now() >= deadline) {
+                throw new WorktreeError('worktree_lock_timeout', `timed out waiting to create a managed worktree in ${commonDir}`, 'Wait for the other managed-worktree operation to finish, then retry.');
+            }
+            sleepSync(WORKTREE_LOCK_POLL_MS);
+        }
+    }
+    try {
+        return action();
+    }
+    finally {
+        // Token-checking release cannot unlock a replacement owner's lock.
+        try {
+            if (readFileSync(lockPath, 'utf8') === owner)
+                unlinkSync(lockPath);
+        }
+        catch { /* already reclaimed after a process-level failure */ }
+    }
+}
+function registeredWorktree(repoRoot, path, branch) {
+    const list = gitSync(['worktree', 'list', '--porcelain'], repoRoot);
+    if (list.status !== 0)
+        return null;
+    let current = null;
+    for (const line of list.stdout.split('\n')) {
+        if (line.startsWith('worktree '))
+            current = line.slice('worktree '.length).trim();
+        else if (current === path && line === `branch refs/heads/${branch}`)
+            return true;
+    }
+    return false;
+}
+/** Undo a creation attempt, but only resources whose recorded path, branch,
+ * and original base still prove they belong to that attempt. */
+function rollbackManagedWorktreeLocked(wt, pathWasAbsent) {
+    const branch = gitSync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], wt.repo_root);
+    // A branch at the original base is the ownership proof for every destructive
+    // rollback step. If it was advanced or repurposed, preserve all resources.
+    if (branch.status !== 0 || branch.stdout.trim() !== wt.base_sha)
+        return;
+    const registration = registeredWorktree(wt.repo_root, wt.path, wt.branch);
+    // A failed registry read proves nothing. Preserve every resource rather than
+    // guessing that an uninspected checkout belongs to this failed attempt.
+    if (registration === null)
+        return;
+    if (registration) {
+        if (gitSync(['worktree', 'remove', '--force', wt.path], wt.repo_root).status !== 0)
+            return;
+        if (registeredWorktree(wt.repo_root, wt.path, wt.branch) !== false)
+            return;
+    }
+    else if (pathWasAbsent && existsSync(wt.path)) {
+        // The caller observed this path absent while holding the repository lock;
+        // only its failed `worktree add` can have created it.
+        try {
+            rmSync(wt.path, { recursive: true, force: true });
+        }
+        catch {
+            return;
+        }
+    }
+    // Compare-and-delete retains the ownership guard through the final mutation.
+    try {
+        gitSync(['update-ref', '-d', `refs/heads/${wt.branch}`, wt.base_sha], wt.repo_root);
+    }
+    catch { /* best-effort */ }
+}
+export function rollbackManagedWorktree(wt) {
+    withRepositoryWorktreeLock(wt.repo_root, () => rollbackManagedWorktreeLocked(wt, false));
+}
+// Fix #330/#331: every crtr process auto-initializes a project scope's
+// `.crouter/config.json` (`ensureProjectScope` → `ensureScopeInitialized`)
+// the first time it runs against a project root that has no ancestor
+// `.crouter/` yet — which every fresh managed worktree checkout is, unless
+// the repo itself already tracks `.crouter/memory/` (crouter's own repo does).
+// That write is untracked crtr bookkeeping, not node work, so `git status`
+// inside the worktree always shows `?? .crouter/config.json` and `close`'s
+// dirty check refuses to land. `state.json` is the same category (written at
+// project scope by explicit `pkg`/`canvas config` commands) — excluded
+// defensively even though no automatic path writes it today.
+//
+// These two filenames, NOT the whole `.crouter/` directory, are the only
+// patterns seeded below. `.git/info/exclude` only ever suppresses UNTRACKED
+// paths from `git status` — it can never hide a modification to an
+// already-tracked file — but crouter's own repo tracks `.crouter/memory/`,
+// and a node can legitimately add a brand-new (untracked until committed)
+// memory doc there. A blanket `.crouter/` exclude would silently hide that
+// new doc from `git status` too, letting close/push-final land or auto-drop
+// while it is quietly lost. Naming exactly `config.json`/`state.json` avoids
+// that: nothing crtr writes automatically ever lands under `.crouter/memory/`.
+const MANAGED_WORKTREE_EXCLUDE_MARKER = '# crtr: exclude crtr\'s own untracked project-scope bookkeeping (auto-added at managed-worktree creation)';
+const MANAGED_WORKTREE_EXCLUDE_PATTERNS = [
+    `/${CRTR_DIR_NAME}/${CONFIG_FILE}`,
+    `/${CRTR_DIR_NAME}/${STATE_FILE}`,
+];
+/** Seed the repository's SHARED `.git/info/exclude` (one file per common git
+ *  dir, not per worktree — `git rev-parse --git-path info/exclude` resolves
+ *  there from every linked worktree, including the primary checkout) with
+ *  crtr's own runtime bookkeeping patterns, idempotently. Leading `/` anchors
+ *  each pattern to the toplevel of WHICHEVER worktree `git status` runs in,
+ *  which is exactly where `ensureScopeInitialized` writes `.crouter/config.json`
+ *  — the managed worktree's own root. Called once per managed-worktree
+ *  creation, already inside `withRepositoryWorktreeLock`, so concurrent
+ *  creators cannot race the append. */
+function seedManagedWorktreeExclude(repoRoot) {
+    try {
+        const excludePath = join(commonGitDir(repoRoot), 'info', 'exclude');
+        mkdirSync(dirname(excludePath), { recursive: true });
+        let existing = '';
+        try {
+            existing = readFileSync(excludePath, 'utf8');
+        }
+        catch { /* first worktree this repo has ever had */ }
+        const present = new Set(existing.split('\n').map((l) => l.trim()));
+        const missing = MANAGED_WORKTREE_EXCLUDE_PATTERNS.filter((p) => !present.has(p));
+        if (missing.length === 0)
+            return;
+        const needsLeadingNewline = existing.length > 0 && !existing.endsWith('\n');
+        const block = (needsLeadingNewline ? '\n' : '') + MANAGED_WORKTREE_EXCLUDE_MARKER + '\n' + missing.join('\n') + '\n';
+        writeFileSync(excludePath, existing + block);
+    }
+    catch { /* best-effort; a failure here is cosmetic (one extra untracked bookkeeping line in git status) and must never fail worktree creation */ }
+}
+export function createManagedWorktree(cwd, nodeId, baseRef = 'main') {
+    const repoRoot = repoRootFor(cwd);
+    return withRepositoryWorktreeLock(repoRoot, () => {
+        const baseSha = resolveLandableBase(repoRoot, baseRef);
+        const path = managedWorktreePath(nodeId);
+        const branch = `crtr/${nodeId}`;
+        if (existsSync(path)) {
+            throw new WorktreeError('worktree_path_exists', `managed worktree path already exists: ${path}`, 'Remove the stale path or choose a fresh node id.');
+        }
+        if (gitSync(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], repoRoot).status === 0) {
+            throw new WorktreeError('worktree_branch_exists', `managed worktree branch already exists: ${branch}`, 'Remove the stale branch or choose a fresh node id.');
+        }
+        const wt = {
+            state: 'open', path, branch, repo_root: repoRoot, base_ref: baseRef, base_sha: baseSha, created: new Date().toISOString(),
+        };
+        runGit(repoRoot, ['branch', branch, baseSha], 'worktree_branch_create_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
+        try {
+            runGit(repoRoot, ['worktree', 'add', path, branch], 'worktree_add_failed', 'Inspect the git error, fix the repository/worktree state, then retry spawning with --worktree.');
+            seedManagedWorktreeExclude(repoRoot);
+            return wt;
+        }
+        catch (err) {
+            rollbackManagedWorktreeLocked(wt, true);
+            throw err;
+        }
+    });
+}
+function statusPorcelain(cwd) {
+    return runGit(cwd, ['status', '--porcelain'], 'status_failed', 'Inspect the worktree manually, then retry.');
+}
+function currentBranch(cwd) {
+    return runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'], 'branch_check_failed', 'Inspect the worktree manually, then retry.');
+}
+function gitPath(cwd, logicalPath) {
+    return runGit(cwd, ['rev-parse', '--git-path', logicalPath], 'git_path_failed', 'Inspect the worktree manually, then retry.');
+}
+export function isRebaseInProgress(cwd) {
+    return existsSync(gitPath(cwd, 'rebase-merge')) || existsSync(gitPath(cwd, 'rebase-apply'));
+}
+/** The ONE authoritative closed-worktree state transition, shared by both
+ *  closing paths (explicit `closeManagedWorktreeLocked` land, and the clean
+ *  `autoDropCleanManagedWorktreeLocked` push-final drop): persist
+ *  `managed_worktree.state: 'closed'` AND repoint the node's launch `cwd` to
+ *  the durable base checkout, atomically, in the same `updateNode` write.
+ *  The worktree dir is torn down by cleanup around this call (at best left
+ *  as an empty tombstone so an in-flight `push final` can still run) and
+ *  must never remain the node's recorded launch directory — an existing
+ *  tombstone directory still passes a naive `existsSync(cwd)` revive
+ *  preflight, so a caller that forgets this repoint lets a later park/revive
+ *  launch into a directory that no longer holds a real checkout. Both
+ *  closing paths MUST go through this helper instead of hand-rolling the
+ *  `updateNode` call, so neither can drift out of sync with the other. */
+function persistClosedWorktreeState(nodeId, wt) {
+    updateNode(nodeId, { cwd: wt.repo_root, managed_worktree: { ...wt, state: 'closed', closed: new Date().toISOString() } });
+}
+function closeManagedWorktreeLocked(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        throw new WorktreeError('unknown_node', `unknown node: ${nodeId}`, 'Run this from a live node, or pass a real node id once that command supports it.');
+    }
+    const wt = openManagedWorktreeForNode(nodeId);
+    if (wt === null) {
+        throw new WorktreeError('no_managed_worktree', `node ${nodeId} has no open managed worktree`, 'Nothing to close for this node.');
+    }
+    if (!existsSync(wt.path)) {
+        throw new WorktreeError('worktree_missing', `managed worktree path is missing: ${wt.path}`, 'Ask the human with `crtr human ask` before changing node state; the checkout disappeared outside crouter.');
+    }
+    if (isRebaseInProgress(wt.path)) {
+        throw new WorktreeError('rebase_in_progress', 'this managed worktree is mid-rebase', `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr node worktree close\`.`);
+    }
+    const dirty = statusPorcelain(wt.path);
+    if (dirty !== '') {
+        throw new WorktreeError('dirty_worktree', 'managed worktree has uncommitted changes', `Commit the work in ${wt.path} (or ask the human with \`crtr human ask\` if you do not know whether to keep it), then rerun \`crtr node worktree close\`.`);
+    }
+    const branch = currentBranch(wt.path);
+    if (branch !== wt.branch) {
+        const found = branch === 'HEAD' ? 'detached HEAD' : branch;
+        throw new WorktreeError('wrong_branch', `managed worktree is not on its recorded branch (expected ${wt.branch}, found ${found})`, `Check out ${wt.branch} in ${wt.path} before closing, or ask the human with \`crtr human ask\` if you are unsure why it changed, then rerun \`crtr node worktree close\`.`);
+    }
+    const baseSha = resolveLandableBase(wt.repo_root, wt.base_ref);
+    const rebase = gitSync(['rebase', baseSha], wt.path);
+    if (rebase.status !== 0) {
+        const detail = (rebase.stderr.trim() || rebase.stdout.trim()).trim();
+        throw new WorktreeError('rebase_failed', `rebase onto local base branch '${wt.base_ref}' did not complete`, `Resolve conflicts in ${wt.path}, run \`git rebase --continue\` there, then rerun \`crtr node worktree close\`. If the blocker is not mechanical, ask the human with \`crtr human ask\`.`, detail);
+    }
+    const landedSha = runGit(wt.path, ['rev-parse', 'HEAD'], 'landed_sha_failed', 'Inspect the worktree checkout manually, then rerun `crtr node worktree close`.');
+    // Fast-forward the local base branch to the worktree tip rebased onto the
+    // captured baseSha — landing is purely local, nothing is ever pushed to
+    // origin. Both landing paths require the base to still be exactly at that
+    // captured tip, so neither can overwrite a concurrent base change.
+    const fastForward = gitSync(['merge-base', '--is-ancestor', baseSha, landedSha], wt.repo_root);
+    if (fastForward.status !== 0) {
+        throw new WorktreeError('land_base_failed', `rebased worktree is not a fast-forward of local base branch '${wt.base_ref}'`, 'Ask the human with `crtr human ask` how to land this managed worktree.', (fastForward.stderr.trim() || fastForward.stdout.trim()).trim());
+    }
+    const baseCheckout = checkoutPathForBranch(wt.repo_root, wt.base_ref);
+    if (baseCheckout !== null) {
+        const checkoutHead = gitSync(['rev-parse', 'HEAD'], baseCheckout);
+        const actualHead = checkoutHead.stdout.trim();
+        if (checkoutHead.status !== 0 || actualHead !== baseSha) {
+            const detail = checkoutHead.status !== 0
+                ? (checkoutHead.stderr.trim() || actualHead).trim()
+                : `expected ${baseSha}, found ${actualHead}`;
+            throw new WorktreeError('land_base_failed', `local base branch '${wt.base_ref}' changed while this worktree was closing`, `Reconcile the base checkout at ${baseCheckout}, then rerun \`crtr node worktree close\`. If you are unsure, ask the human with \`crtr human ask\`.`, detail);
+        }
+    }
+    const land = baseCheckout !== null
+        ? gitSync(['merge', '--ff-only', landedSha], baseCheckout)
+        : gitSync(['update-ref', `refs/heads/${wt.base_ref}`, landedSha, baseSha], wt.repo_root);
+    if (land.status !== 0) {
+        const detail = (land.stderr.trim() || land.stdout.trim()).trim();
+        throw new WorktreeError('land_base_failed', `could not fast-forward local base branch '${wt.base_ref}' to this worktree`, baseCheckout !== null
+            ? `Local base branch '${wt.base_ref}' is checked out at ${baseCheckout} in a state that blocks a fast-forward (uncommitted changes, or it has diverged). Reconcile it there, then rerun \`crtr node worktree close\`. If you are unsure, ask the human with \`crtr human ask\`.`
+            : 'Ask the human with `crtr human ask` how to land this managed worktree.', detail);
+    }
+    // Landing on the local base branch IS the point of no return: persist `state: 'closed'`
+    // IMMEDIATELY, before attempting any cleanup below. Worktree removal and
+    // branch deletion are best-effort from here on — their failure is cosmetic
+    // (a stray checkout / local ref) and must never re-strand `state: 'open'`
+    // behind a dead end that permanently blocks push-final. See
+    // `persistClosedWorktreeState` for why `cwd` is repointed in the same write.
+    persistClosedWorktreeState(nodeId, wt);
+    const { worktreeRemoved, worktreeRemoveError } = bestEffortRemoveWorktreeCheckout(wt, { timeoutMs: WORKTREE_CLEANUP_TIMEOUT_MS });
+    // Delete via the atomic base+branch transaction, keyed on `landedSha` for
+    // BOTH refs: the fast-forward above just moved `refs/heads/<wt.base_ref>`
+    // to `landedSha`, and `wt.branch`'s tip (as of `landedSha`) is provably
+    // contained in it. Binding both refs into one transaction closes the
+    // window a branch-only check leaves open: if a concurrent commit lands a
+    // new tip on this branch, or a concurrent force-reset moves the base off
+    // `landedSha`, before this call runs, the transaction fails closed and
+    // preserves the branch — it cannot ever delete the last ref to work that
+    // is no longer contained in the base. A refusal here is cosmetic and
+    // non-fatal exactly as before: the land already happened (state is closed
+    // above), only cleanup of the source branch is best-effort. Skip the
+    // attempt entirely when the checkout itself could not be removed — this
+    // branch is still checked out somewhere, so deleting its ref underneath
+    // that checkout must never be attempted.
+    const { branchDeleted, branchDeleteError } = worktreeRemoved
+        ? bestEffortDeleteBranchWithBaseProof(wt, landedSha, landedSha)
+        : {
+            branchDeleted: false,
+            branchDeleteError: `local branch ${wt.branch} was left in place because its checkout at ${wt.path} could not be removed automatically; resolve the checkout, then run \`git -C ${shellQuote(wt.repo_root)} branch -D ${shellQuote(wt.branch)}\` after confirming it is merged.`,
+        };
+    return {
+        node_id: nodeId,
+        branch: wt.branch,
+        worktree_path: wt.path,
+        landed_sha: landedSha,
+        worktree_removed: worktreeRemoved,
+        ...(worktreeRemoveError !== undefined ? { worktree_remove_error: worktreeRemoveError } : {}),
+        branch_deleted: branchDeleted,
+        ...(branchDeleteError !== undefined ? { branch_delete_error: branchDeleteError } : {}),
+    };
+}
+export function closeManagedWorktree(nodeId) {
+    const wt = openManagedWorktreeForNode(nodeId);
+    // Preserve the existing precise unknown/no-open-worktree errors without a
+    // repository to lock; every state-mutating close path runs under the lock.
+    if (wt === null)
+        return closeManagedWorktreeLocked(nodeId);
+    return withRepositoryWorktreeLock(wt.repo_root, () => closeManagedWorktreeLocked(nodeId));
+}
+const defaultWorktreeCleanupRunner = (args, cwd, options) => gitSync(args, cwd, undefined, options);
+let worktreeCleanupRunner = defaultWorktreeCleanupRunner;
+/** Test seam for the bounded post-land cleanup regression. */
+export function setWorktreeCleanupRunnerForTest(runner) {
+    worktreeCleanupRunner = runner ?? defaultWorktreeCleanupRunner;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function isValidRegisteredCheckout(output, wt) {
+    let path = null;
+    let prunable = false;
+    const samePath = (candidate) => {
+        try {
+            return realpathSync(candidate) === realpathSync(wt.path);
+        }
+        catch {
+            return resolve(candidate) === resolve(wt.path);
+        }
+    };
+    const matches = () => path !== null
+        && samePath(path)
+        && existsSync(path)
+        && existsSync(join(path, '.git'))
+        && !prunable;
+    for (const line of output.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            if (matches())
+                return true;
+            path = line.slice('worktree '.length).trim();
+            prunable = false;
+        }
+        else if (path !== null && line.startsWith('prunable')) {
+            prunable = true;
+        }
+    }
+    return matches();
+}
+function timeoutRecoveryGuidance(wt, options) {
+    const force = `git -C ${shellQuote(wt.repo_root)} worktree remove --force ${shellQuote(wt.path)}`;
+    const prune = `git -C ${shellQuote(wt.repo_root)} worktree prune`;
+    const removeResidual = `rm -rf ${shellQuote(wt.path)}`;
+    try {
+        const inspection = worktreeCleanupRunner(['worktree', 'list', '--porcelain'], wt.repo_root, options);
+        if (inspection.status === 0) {
+            return isValidRegisteredCheckout(inspection.stdout, wt)
+                ? `run \`${force}\` after confirming it is safe to delete.`
+                : `run \`${prune}\`, then run \`${removeResidual}\` after confirming the leftover directory is safe to delete.`;
+        }
+    }
+    catch {
+        // Inspection is advisory only. Emit both recovery shapes when Git could
+        // not tell us which residual state remains.
+    }
+    return `if ${shellQuote(wt.path)} is a valid non-prunable checkout (its .git exists and its worktree-list record is not prunable), run \`${force}\`; otherwise run \`${prune}\` and then \`${removeResidual}\` after confirming it is safe to delete.`;
+}
+/** Best-effort `git worktree remove` shared by a real land (close) and an
+ *  auto-drop (nothing was ever landed). Either way `wt.path` IS the calling
+ *  node's own pi-process cwd — a process can never chdir itself out of a
+ *  directory that vanishes out from under it, so once removal deletes it,
+ *  every subsequent bash/chdir in this node fails permanently and the
+ *  mandated post-close `crtr push final` can never run. Recreate it as an
+ *  empty tombstone directory so the path still resolves regardless. */
+function bestEffortRemoveWorktreeCheckout(wt, options = {}) {
+    const remove = worktreeCleanupRunner(['worktree', 'remove', wt.path], wt.repo_root, options);
+    const worktreeRemoved = remove.status === 0;
+    if (worktreeRemoved && existsSync(wt.path)) {
+        // `git worktree remove` can leave the (now empty) mount dir behind; tidy it best-effort.
+        try {
+            rmdirSync(wt.path);
+        }
+        catch { /* non-empty or busy — leave it */ }
+    }
+    if (!existsSync(wt.path)) {
+        try {
+            mkdirSync(wt.path, { recursive: true });
+        }
+        catch { /* best-effort; leaves cwd broken only if this also fails */ }
+    }
+    if (worktreeRemoved)
+        return { worktreeRemoved };
+    const detail = (remove.stderr.trim() || remove.stdout.trim()).trim();
+    const timeoutDetail = remove.timedOut
+        ? `cleanup timed out after ${options.timeoutMs}ms`
+        : `could not be removed automatically${detail ? ` (${detail})` : ''}`;
+    const manualGuidance = remove.timedOut
+        ? timeoutRecoveryGuidance(wt, options)
+        : `run \`git -C ${shellQuote(wt.repo_root)} worktree remove ${shellQuote(wt.path)}\` after confirming it is safe to delete.`;
+    return {
+        worktreeRemoved,
+        worktreeRemoveError: `the checkout at ${wt.path} ${timeoutDetail} ${manualGuidance}`,
+    };
+}
+/** Atomic multi-ref transaction shared by close and auto-drop: as ONE Git ref
+ *  transaction, verifies `refs/heads/<wt.base_ref>` still equals `baseSha`
+ *  AND deletes `refs/heads/<wt.branch>` only if it still equals `branchSha`
+ *  — both preconditions and the delete are checked and applied together via
+ *  `git update-ref --stdin`, which commits every command in its input
+ *  atomically (any failed precondition aborts the whole transaction; see
+ *  `rollbackManagedWorktreeLocked` above for the single-ref precursor of
+ *  this pattern). A single-ref compare-and-delete on the branch alone is not
+ *  enough: both callers prove containment against a specific base SHA, and
+ *  that base can move (an external force-reset) in the window between the
+ *  proof and this call just as easily as the branch can. Binding the base's
+ *  live value into the SAME transaction as the branch delete closes that
+ *  window — the delete can only succeed at the instant both refs are
+ *  simultaneously exactly what was proven, so a base rewrite can never leave
+ *  a proven commit unreachable from any head. */
+function bestEffortDeleteBranchWithBaseProof(wt, branchSha, baseSha) {
+    const stdin = `verify refs/heads/${wt.base_ref} ${baseSha}\ndelete refs/heads/${wt.branch} ${branchSha}\n`;
+    const transaction = gitSync(['update-ref', '--stdin'], wt.repo_root, stdin);
+    const branchDeleted = transaction.status === 0;
+    if (branchDeleted)
+        return { branchDeleted };
+    const detail = (transaction.stderr.trim() || transaction.stdout.trim()).trim();
+    return {
+        branchDeleted,
+        branchDeleteError: `local branch ${wt.branch} could not be deleted automatically (${detail}); run \`git -C ${shellQuote(wt.repo_root)} branch -D ${shellQuote(wt.branch)}\` after confirming it is merged.`,
+    };
+}
+/** Fix B's shared "nothing to land" test — the SAME clean-worktree definition
+ *  `close`'s own dirty check now naturally satisfies once `.git/info/exclude`
+ *  hides crtr's own `.crouter/config.json`/`state.json` bookkeeping (Fix A),
+ *  plus one more requirement close doesn't need: the branch tip must already
+ *  be a git-ancestor of (or equal to) the CURRENT tip of its recorded base
+ *  branch — i.e. landing it would be a pure no-op. Any ambiguity (missing
+ *  path, mid-rebase, wrong branch, an unresolvable base, or a real ancestry
+ *  divergence) returns null: this function only ever proves "safe to drop"
+ *  when a live git check establishes it, never on a heuristic guess, so real
+ *  unlanded work always falls through to the existing explicit-close guard.
+ *  This proof is NOT itself the safety boundary — it only decides whether
+ *  auto-drop is even attempted. `autoDropCleanManagedWorktreeLocked` below
+ *  re-proves containment against the LIVE base immediately before the
+ *  destructive delete, refuses outright if the checkout cannot be removed,
+ *  and conditions the delete itself on BOTH `branchSha` and that same live
+ *  base SHA via `bestEffortDeleteBranchWithBaseProof`'s atomic multi-ref
+ *  transaction — those checks, not this one, are what close the TOCTOU gap.
+ *  Exported (alongside
+ *  `autoDropCleanManagedWorktreeLocked`) purely so regression tests can
+ *  inject a race in the window between proving and cleanup; production code
+ *  must always go through `autoDropCleanManagedWorktree`. */
+export function proveCleanEmptyManagedWorktree(wt) {
+    if (wt.state !== 'open')
+        return null;
+    if (!existsSync(wt.path))
+        return null;
+    if (isRebaseInProgress(wt.path))
+        return null;
+    const branch = gitSync(['rev-parse', '--abbrev-ref', 'HEAD'], wt.path);
+    if (branch.status !== 0 || branch.stdout.trim() !== wt.branch)
+        return null;
+    const status = gitSync(['status', '--porcelain'], wt.path);
+    if (status.status !== 0 || status.stdout.trim() !== '')
+        return null;
+    let baseSha;
+    try {
+        baseSha = resolveLandableBase(wt.repo_root, wt.base_ref);
+    }
+    catch {
+        return null;
+    }
+    const head = gitSync(['rev-parse', 'HEAD'], wt.path);
+    if (head.status !== 0)
+        return null;
+    const branchSha = head.stdout.trim();
+    const ancestor = gitSync(['merge-base', '--is-ancestor', branchSha, baseSha], wt.repo_root);
+    if (ancestor.status !== 0)
+        return null;
+    return { branchSha, baseSha };
+}
+/** Exported (see `proveCleanEmptyManagedWorktree`'s doc) so regression tests
+ *  can call it directly with a proof captured before injecting a race.
+ *  Returns null — persisting NO state change — when the immediate base
+ *  re-verification, the checkout removal, or the atomic base+branch delete
+ *  refuses: the caller (`autoDropCleanManagedWorktree`, and `push final`
+ *  above it) then falls through to the existing `open_managed_worktree`
+ *  guard exactly as if this worktree had never looked droppable. In every
+ *  refusal case the branch, and every commit reachable from it, is
+ *  unconditionally preserved — that is the actual safety property this
+ *  function guarantees. A checkout-removal refusal in particular must be
+ *  treated as a full refusal, not a partial success: if the checkout cannot
+ *  be removed (e.g. a file reappeared after the clean predicate ran), the
+ *  branch is still checked out somewhere, so this function must never reach
+ *  the ref-deletion transaction or mutate managed-worktree state — both the
+ *  branch and the live checkout stay fully recoverable and the caller's
+ *  `open_managed_worktree` guard fires. */
+export function autoDropCleanManagedWorktreeLocked(nodeId, wt, proof) {
+    // Re-verify containment against the LIVE base immediately before doing
+    // anything destructive: the proof above may already be stale by the time
+    // we get here — `withRepositoryWorktreeLock` only serializes crtr's OWN
+    // worktree mutations, not ordinary `git commit`/`git reset` run by any
+    // other process in the checkout, nor an external force-reset of the base
+    // branch. Re-resolving the base and re-running the ancestor check fresh
+    // (rather than trusting `proof.baseSha`) means a base fast-forward keeps a
+    // genuinely-contained tip provably contained, while any other base
+    // rewrite (or the base vanishing) fails this closed before we touch
+    // anything. This SAME `liveBaseSha` is what the ref transaction below
+    // verifies again at the moment of the delete — re-checking it here only
+    // decides whether to attempt cleanup at all; the transaction is what
+    // actually closes the race.
+    let liveBaseSha;
+    try {
+        liveBaseSha = resolveLandableBase(wt.repo_root, wt.base_ref);
+    }
+    catch {
+        return null;
+    }
+    const stillContained = gitSync(['merge-base', '--is-ancestor', proof.branchSha, liveBaseSha], wt.repo_root);
+    if (stillContained.status !== 0)
+        return null;
+    // Checkout removal has to come BEFORE the ref-deletion transaction, not
+    // after: `git worktree remove`'s cleanliness check needs the checked-out
+    // branch's ref to still resolve to compute a diff, so deleting the ref
+    // first turns every tracked file into what looks like an unresolvable path
+    // and `worktree remove` refuses outright (verified directly against git).
+    // This ordering is still safe: removal alone never touches
+    // `refs/heads/<branch>` or anything reachable from it — a commit that
+    // lands here is fully preserved as an ordinary (no longer checked-out)
+    // local branch, exactly as droppable-or-not as it was, until the
+    // transaction below either consumes it or refuses. A removal REFUSAL,
+    // though, must stop cleanup here entirely: low-level ref deletion bypasses
+    // Git's own checked-out-branch protection, so deleting the branch while
+    // its checkout is still live would strand that checkout with no branch to
+    // point at it.
+    const { worktreeRemoved } = bestEffortRemoveWorktreeCheckout(wt);
+    if (!worktreeRemoved)
+        return null;
+    // THE safety boundary: this only succeeds if `refs/heads/<wt.base_ref>` is
+    // still exactly `liveBaseSha` AND `refs/heads/<branch>` is still exactly
+    // `proof.branchSha`, verified and applied as one atomic transaction. A
+    // commit made anywhere in the checkout, or an external rewrite of the
+    // base, at any point up to and including this instant makes the whole
+    // transaction fail closed instead of silently destroying new work. On
+    // refusal the branch, and everything reachable from it, is fully intact
+    // and enumerable; only the convenience checkout may already be gone
+    // (tombstoned by the removal above), recoverable with a fresh
+    // `git worktree add` against the still-live branch. `state` is left
+    // untouched ('open') below specifically so this refusal is never mistaken
+    // for a completed drop.
+    const { branchDeleted } = bestEffortDeleteBranchWithBaseProof(wt, proof.branchSha, liveBaseSha);
+    if (!branchDeleted)
+        return null;
+    // Only now — with the branch ref provably gone at the proven SHA and the
+    // base provably unchanged — is it safe to commit to the drop. Reuse the
+    // shared closed-worktree transition (see `persistClosedWorktreeState`) so
+    // this path repoints `cwd` to the base checkout exactly like an explicit
+    // close — a later revive's tombstone-vs-missing-cwd check depends on it.
+    persistClosedWorktreeState(nodeId, wt);
+    return {
+        node_id: nodeId,
+        branch: wt.branch,
+        worktree_path: wt.path,
+        worktree_removed: true,
+        branch_deleted: true,
+    };
+}
+/** `push final`'s escape hatch (#327, #333): a managed worktree that has
+ *  nothing to land is auto-dropped instead of blocking on an explicit
+ *  `node worktree close` — one the caller may have been told NOT to run
+ *  because a manager already landed the same change another way (#327), or
+ *  that never had anything to close in the first place (#333, a read-only
+ *  review node). Returns null and changes nothing when the worktree is not
+ *  PROVABLY empty-and-clean by `proveCleanEmptyManagedWorktree`, OR when a
+ *  concurrent mutation invalidates that proof before the destructive delete
+ *  (see `autoDropCleanManagedWorktreeLocked`); the caller's existing
+ *  `open_managed_worktree` guard then still applies unchanged — real
+ *  commits, real uncommitted changes, and a lost race all require the
+ *  explicit path. */
+export function autoDropCleanManagedWorktree(nodeId) {
+    const wt = openManagedWorktreeForNode(nodeId);
+    if (wt === null)
+        return null;
+    // A negative read-only preflight must fail before waiting on the repository
+    // mutation lock: real unlanded work should reach push-final's guard promptly.
+    if (proveCleanEmptyManagedWorktree(wt) === null)
+        return null;
+    return withRepositoryWorktreeLock(wt.repo_root, () => {
+        // Re-fetch inside the lock: state may have changed since the caller's
+        // hasOpenManagedWorktree check ran outside it.
+        const locked = openManagedWorktreeForNode(nodeId);
+        if (locked === null)
+            return null;
+        // The preflight only avoids needless lock contention. Re-prove the full
+        // predicate under the lock before any cleanup.
+        const proof = proveCleanEmptyManagedWorktree(locked);
+        if (proof === null)
+            return null;
+        return autoDropCleanManagedWorktreeLocked(nodeId, locked, proof);
+    });
+}