@north-light/crouter 0.3.255 → 0.3.256

package/dist/core/worktree-sweep.js

@@ -0,0 +1,493 @@
+// The ONE authority that physically disposes of a managed worktree after its
+// owning node is gone.
+//
+// Close, cancel, crash, and prune do not each grow a cleanup hook: they only
+// change durable state, and this primitive derives everything it does from that
+// state. It is idempotent and restartable, because Git effects and canvas
+// metadata are not one transaction — a crash between any two steps is resumed
+// by the next pass rather than repaired by hand.
+//
+// EVERY Git call here is `gitAsync`. This runs inside crtrd, whose event loop
+// also drives broker supervision and the API socket; a `spawnSync` in this path
+// would stall the whole daemon for the duration of every Git call, and a Git
+// call on a large repository is not short.
+//
+// The synchronous twin of the landing sequence lives in `worktree.ts` (`close`,
+// which runs in an API handler). The judgment both forms share — what is safe
+// to stash, what must be refused — lives once in `worktree-landing.ts`.
+import { createHash } from 'node:crypto';
+import { existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getNode, updateNode } from './canvas/index.js';
+import { withExclusiveDirectoryLockAsync } from './exclusive-lock.js';
+import { gitAsync } from './git.js';
+import { parseStatusPorcelain, planLandIntoCheckout, refDeleteTransactionStdin } from './worktree-landing.js';
+import { WORKTREE_LOCK_WAIT_MS, checkoutPathForBranchInList, persistClosedWorktreeState, samePath, worktreeLockPathForCommonDir } from './worktree.js';
+/** Escalating recheck interval, in minutes, indexed by consecutive refusal. The
+ *  last tier is the cap AND the quarantine threshold: at that point the record
+ *  needs a human, so it is listed by `crtr sys worktrees` and costs one cheap
+ *  fingerprint read an hour until something about it actually changes. */
+const BACKOFF_MINUTES = [2, 5, 15, 30, 60];
+const QUARANTINE_ATTEMPTS = BACKOFF_MINUTES.length;
+/** A record this sweep still owns: open, or closed without proven cleanup. An
+ *  abandoned record is deliberately out of scope — abandon already removed the
+ *  checkout and retains its branch for a person on purpose. */
+export function isReconcilable(wt) {
+    if (wt == null || wt.state === 'abandoned')
+        return false;
+    return wt.state === 'open' || wt.cleanup !== 'complete';
+}
+/** Whether the sweep should examine this record on a pass starting at `now`. A
+ *  record with no recorded refusal is always due. */
+export function isDueForSweep(wt, now) {
+    const next = wt.sweep?.next_attempt;
+    if (next === undefined)
+        return true;
+    const at = Date.parse(next);
+    return Number.isNaN(at) || at <= now;
+}
+// Git plumbing, all async
+async function revParseRef(cwd, ref) {
+    const res = await gitAsync(['rev-parse', '--verify', '--quiet', ref], cwd);
+    return res.status === 0 ? res.stdout.trim() : null;
+}
+function detailOf(res) {
+    return (res.stderr.trim() || res.stdout.trim()).trim();
+}
+async function commonGitDirAsync(cwd) {
+    const res = await gitAsync(['rev-parse', '--git-common-dir'], cwd);
+    if (res.status !== 0)
+        return null;
+    try {
+        return realpathSync(resolve(cwd, res.stdout.trim()));
+    }
+    catch {
+        return null;
+    }
+}
+async function isRebaseInProgressAsync(cwd) {
+    for (const logical of ['rebase-merge', 'rebase-apply']) {
+        const res = await gitAsync(['rev-parse', '--git-path', logical], cwd);
+        if (res.status !== 0)
+            return null;
+        if (existsSync(resolve(cwd, res.stdout.trim())))
+            return true;
+    }
+    return false;
+}
+/** The repository's main checkout, from a `git worktree list --porcelain` blob:
+ *  Git always lists it first. Every administrative command runs from there, so
+ *  removing a linked checkout never runs Git from inside the directory it is
+ *  deleting. */
+function mainWorktreePath(porcelain) {
+    for (const line of porcelain.split('\n')) {
+        if (line.startsWith('worktree '))
+            return line.slice('worktree '.length).trim();
+    }
+    return null;
+}
+/** Git's own spelling of the recorded checkout when it is registered to the
+ *  recorded branch, else null. Ownership is a path IDENTITY question, not a
+ *  string question — `samePath` resolves both spellings — and the answer is
+ *  Git's canonical path so every later Git call names the checkout the way the
+ *  repository's administrative metadata does. */
+function registeredCheckoutPath(porcelain, path, branch) {
+    let current = null;
+    for (const line of porcelain.split('\n')) {
+        if (line.startsWith('worktree '))
+            current = line.slice('worktree '.length).trim();
+        else if (current !== null && line === `branch refs/heads/${branch}` && samePath(current, path))
+            return current;
+    }
+    return null;
+}
+/** Refs that could prove delivery: the recorded local base, and the base's
+ *  upstream (a branch delivered by push rather than by a local land). */
+async function containmentCandidates(cwd, wt) {
+    const candidates = [];
+    const localBaseRef = `refs/heads/${wt.base_ref}`;
+    const localBase = await revParseRef(cwd, localBaseRef);
+    if (localBase !== null)
+        candidates.push({ ref: localBaseRef, sha: localBase });
+    const upstream = await gitAsync(['rev-parse', '--symbolic-full-name', '--verify', `${wt.base_ref}@{upstream}`], cwd);
+    const upstreamRef = upstream.status === 0 && upstream.stdout.trim().startsWith('refs/')
+        ? upstream.stdout.trim()
+        : `refs/remotes/origin/${wt.base_ref}`;
+    const upstreamSha = await revParseRef(cwd, upstreamRef);
+    if (upstreamSha !== null)
+        candidates.push({ ref: upstreamRef, sha: upstreamSha });
+    return candidates;
+}
+/** Does removing this branch lose content the candidate does not already have?
+ *
+ *  The invariant is about CONTENT, not history. A rebase rewrites every SHA, so
+ *  a fully-landed branch can look diverged; a squash-merge leaves no matching
+ *  commit at all. An ancestry-only proof would refuse exactly the cases this
+ *  sweep exists to clean up, so three layers run in increasing cost, and any one
+ *  of them is sufficient:
+ *
+ *  1. ancestry     — the tip is already reachable from the candidate.
+ *  2. patch identity — every commit not in the candidate by SHA has a
+ *                      patch-equivalent commit there (`git cherry`). The rebase case.
+ *  3. content no-op  — merging the branch in would change nothing. The
+ *                      squash-merge case, and most remaining "looks bad but isn't" states.
+ *
+ *  Only when all three fail does the branch genuinely carry unlanded content.
+ *  Every layer fails CLOSED: a Git version without `merge-tree --write-tree`, an
+ *  unreadable object, any non-zero exit — none of them prove anything, so the
+ *  branch survives. */
+async function proveContained(cwd, wt, branchSha) {
+    const candidates = await containmentCandidates(cwd, wt);
+    if (candidates.length === 0)
+        return null;
+    for (const candidate of candidates) {
+        if ((await gitAsync(['merge-base', '--is-ancestor', branchSha, candidate.sha], cwd)).status === 0) {
+            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'ancestry' };
+        }
+    }
+    for (const candidate of candidates) {
+        const cherry = await gitAsync(['cherry', candidate.sha, branchSha], cwd);
+        if (cherry.status !== 0)
+            continue;
+        const lines = cherry.stdout.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+        if (lines.every((line) => line.startsWith('-'))) {
+            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'patch_identity' };
+        }
+    }
+    for (const candidate of candidates) {
+        const candidateTree = await revParseRef(cwd, `${candidate.sha}^{tree}`);
+        if (candidateTree === null)
+            continue;
+        const merged = await gitAsync(['merge-tree', '--write-tree', candidate.sha, branchSha], cwd);
+        if (merged.status !== 0)
+            continue; // conflict, or a Git too old for this flag
+        if (merged.stdout.split('\n')[0]?.trim() === candidateTree) {
+            return { containingRef: candidate.ref, containingSha: candidate.sha, layer: 'content_noop' };
+        }
+    }
+    return null;
+}
+// Change detection
+/** Base tip, branch tip, and checkout state as they are right now. A pass that
+ *  reads the same three values as the refusal that preceded it can stop there:
+ *  nothing that decided the refusal has moved. An unreadable checkout records
+ *  `null`, which never compares equal, so uncertainty always re-proves. */
+async function observe(wt) {
+    const present = existsSync(wt.path);
+    const cwd = present ? wt.path : wt.repo_root;
+    const base = await revParseRef(cwd, `refs/heads/${wt.base_ref}`);
+    const branch = await revParseRef(cwd, `refs/heads/${wt.branch}`);
+    if (!present)
+        return { base, branch, checkout: 'absent' };
+    const head = await gitAsync(['rev-parse', 'HEAD'], wt.path);
+    const status = await gitAsync(['status', '--porcelain'], wt.path);
+    const checkout = head.status !== 0 || status.status !== 0
+        ? null
+        : createHash('sha256').update(`${head.stdout.trim()}\n${status.stdout}`).digest('hex');
+    return { base, branch, checkout };
+}
+function sameObservation(a, b) {
+    if (a.checkout === null || b.checkout === null)
+        return false;
+    return a.base === b.base && a.branch === b.branch && a.checkout === b.checkout;
+}
+// Recording an unfinished pass
+/** Persist why this pass did not finish, with the fingerprint it decided
+ *  against and an escalated recheck time. This NEVER writes completion and
+ *  never drops the authoritative record: the checkout, the branch, and the node
+ *  metadata that proves who owns them all survive a refusal. */
+function recordUnfinished(nodeId, wt, outcome, observed, now, guard) {
+    if (outcome.status !== 'refused' && outcome.status !== 'failed')
+        return;
+    // A node that came back to life owns its own record again: backoff written
+    // from a pass it invalidated would sit on the revived node's metadata.
+    if (!guard.stillEligible())
+        return;
+    const attempts = (wt.sweep?.attempts ?? 0) + 1;
+    const minutes = BACKOFF_MINUTES[Math.min(attempts, BACKOFF_MINUTES.length) - 1] ?? BACKOFF_MINUTES[0];
+    const current = getNode(nodeId)?.managed_worktree;
+    if (current == null || !isReconcilable(current))
+        return;
+    updateNode(nodeId, {
+        managed_worktree: {
+            ...current,
+            sweep: {
+                reason: outcome.reason,
+                ...(outcome.detail === undefined ? {} : { detail: outcome.detail }),
+                observed,
+                attempts,
+                last_attempt: new Date(now).toISOString(),
+                next_attempt: new Date(now + minutes * 60_000).toISOString(),
+                ...(attempts >= QUARANTINE_ATTEMPTS ? { quarantined: true } : {}),
+            },
+        },
+    });
+}
+// Landing a blocked close the sweep is allowed to finish
+/** The asynchronous twin of `worktree.ts`'s `landIntoBaseCheckout`. Same
+ *  sequence, same guarantees: stash only what overlaps, `apply` rather than
+ *  `pop` so a conflict cannot consume the stash, and never leave a checkout
+ *  other nodes share in a conflicted state. */
+async function landIntoBaseCheckoutAsync(baseCheckout, branch, baseSha, landedSha, guard) {
+    const status = await gitAsync(['status', '--porcelain'], baseCheckout);
+    if (status.status !== 0)
+        return { ok: false, detail: detailOf(status) };
+    const diff = await gitAsync(['diff', '--name-only', baseSha, landedSha], baseCheckout);
+    if (diff.status !== 0)
+        return { ok: false, detail: detailOf(diff) };
+    const incoming = diff.stdout.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+    const plan = planLandIntoCheckout(parseStatusPorcelain(status.stdout), incoming);
+    if (plan.kind === 'refuse') {
+        return { ok: false, detail: `untracked files in ${baseCheckout} would be overwritten by the incoming commits: ${plan.collisions.join(', ')}` };
+    }
+    // The last recheck before this sequence starts. Once a stash exists the
+    // remaining steps MUST run to completion — abandoning a stashed checkout
+    // halfway is worse than finishing a land the node no longer needs.
+    if (!guard.stillEligible())
+        return { ok: false, detail: 'node is no longer terminal', ineligible: true };
+    const merge = async () => {
+        const res = await gitAsync(['merge', '--ff-only', landedSha], baseCheckout);
+        return res.status === 0 ? { ok: true } : { ok: false, detail: detailOf(res) };
+    };
+    if (plan.kind === 'direct')
+        return merge();
+    const beforeSha = await revParseRef(baseCheckout, 'refs/stash');
+    const push = await gitAsync(['stash', 'push', '--message', `crtr landing ${branch}`], baseCheckout);
+    if (push.status !== 0)
+        return { ok: false, detail: detailOf(push) };
+    const stashSha = await revParseRef(baseCheckout, 'refs/stash');
+    if (stashSha === null || stashSha === beforeSha)
+        return merge(); // nothing was saved
+    const landed = await merge();
+    if (!landed.ok) {
+        if ((await gitAsync(['stash', 'apply', stashSha], baseCheckout)).status === 0)
+            await dropStashIfStillTip(baseCheckout, stashSha);
+        return landed;
+    }
+    if ((await gitAsync(['stash', 'apply', stashSha], baseCheckout)).status === 0) {
+        await dropStashIfStillTip(baseCheckout, stashSha);
+        return { ok: true };
+    }
+    await gitAsync(['reset', '--hard', landedSha], baseCheckout);
+    return { ok: true, stash: `local changes in ${baseCheckout} conflicted with the landed commits and were PRESERVED as stash ${stashSha}; re-apply them with \`git -C ${baseCheckout} stash apply ${stashSha}\`.` };
+}
+async function dropStashIfStillTip(cwd, stashSha) {
+    if ((await revParseRef(cwd, 'refs/stash')) === stashSha)
+        await gitAsync(['stash', 'drop'], cwd);
+}
+/** Finish the land this node already asked for and was blocked on. The sweep
+ *  reaches here ONLY for a record carrying `land_intent`: a node that crashed
+ *  mid-work and never called close does not get its half-finished commits
+ *  fast-forwarded onto a shared base branch. */
+async function finishBlockedLand(wt, porcelain, guard) {
+    const baseSha = await revParseRef(wt.path, `refs/heads/${wt.base_ref}`);
+    if (baseSha === null)
+        return { ok: false, detail: `local base branch '${wt.base_ref}' does not resolve` };
+    if (!guard.stillEligible())
+        return { ok: false, detail: 'node is no longer terminal', ineligible: true };
+    const rebase = await gitAsync(['rebase', baseSha], wt.path);
+    if (rebase.status !== 0) {
+        // A conflicted rebase must never be left in progress: the next pass would
+        // read a mid-operation checkout and refuse forever.
+        await gitAsync(['rebase', '--abort'], wt.path);
+        return { ok: false, detail: detailOf(rebase) };
+    }
+    const landedSha = await revParseRef(wt.path, 'HEAD');
+    if (landedSha === null)
+        return { ok: false, detail: 'could not read the rebased worktree tip' };
+    if ((await gitAsync(['merge-base', '--is-ancestor', baseSha, landedSha], wt.path)).status !== 0) {
+        return { ok: false, detail: `the rebased branch is not a fast-forward of '${wt.base_ref}'` };
+    }
+    const baseCheckout = checkoutPathForBranchInList(porcelain, wt.base_ref);
+    if (baseCheckout === null) {
+        if (!guard.stillEligible())
+            return { ok: false, detail: 'node is no longer terminal', ineligible: true };
+        const update = await gitAsync(['update-ref', `refs/heads/${wt.base_ref}`, landedSha, baseSha], wt.path);
+        return update.status === 0 ? { ok: true, landedSha } : { ok: false, detail: detailOf(update) };
+    }
+    const head = await gitAsync(['rev-parse', 'HEAD'], baseCheckout);
+    if (head.status !== 0 || head.stdout.trim() !== baseSha) {
+        return { ok: false, detail: `base checkout ${baseCheckout} is not at ${baseSha}` };
+    }
+    const landed = await landIntoBaseCheckoutAsync(baseCheckout, wt.branch, baseSha, landedSha, guard);
+    return landed.ok ? { ok: true, landedSha, ...(landed.stash === undefined ? {} : { stash: landed.stash }) } : landed;
+}
+/** The one outcome for "the node came back" — never a failure, never recorded as
+ *  a refusal, because nothing about the worktree is wrong. */
+const NODE_REVIVED = { status: 'skipped', reason: 'node_no_longer_terminal' };
+/** Dispose of one node's managed worktree, or explain why it must survive.
+ *
+ *  Ownership is proved from crouter's own node record, never from
+ *  `git worktree list`: a checkout the user or another tool created has no node
+ *  record and is never reachable from here. Under the repository lock the
+ *  recorded path is confirmed REGISTERED to the recorded branch — a path match
+ *  alone is not ownership — and removal is `git worktree remove <recorded
+ *  path>` without `--force`. `git worktree prune` is never run: it is
+ *  repo-wide and would touch administrative entries for worktrees crouter does
+ *  not own.
+ *
+ *  Effects are ordered checkout → branch → metadata so every interruption is
+ *  resumable: a crash before removal retries from pending; after removal but
+ *  before the branch delete, the branch is still an intact ref the next pass
+ *  finds; after both, the next pass observes both absent and marks complete. */
+export async function reconcileManagedWorktree(nodeId, guard, now = Date.now()) {
+    const wt = getNode(nodeId)?.managed_worktree;
+    if (!isReconcilable(wt) || wt == null)
+        return { status: 'skipped', reason: 'already_reconciled' };
+    const cwd = existsSync(wt.path) ? wt.path : wt.repo_root;
+    if (!existsSync(cwd)) {
+        return finish(nodeId, wt, { status: 'refused', reason: 'repo_unavailable', detail: `neither the managed checkout (${wt.path}) nor its repository root (${wt.repo_root}) is present` }, { base: null, branch: null, checkout: null }, now, guard);
+    }
+    const commonDir = await commonGitDirAsync(cwd);
+    if (commonDir === null) {
+        return finish(nodeId, wt, { status: 'failed', reason: 'git_dir_unreadable', detail: `could not resolve the git common dir from ${cwd}` }, { base: null, branch: null, checkout: null }, now, guard);
+    }
+    let observed = { base: null, branch: null, checkout: null };
+    let outcome;
+    try {
+        outcome = await withExclusiveDirectoryLockAsync(worktreeLockPathForCommonDir(commonDir), async () => {
+            if (!guard.stillEligible())
+                return NODE_REVIVED;
+            const locked = getNode(nodeId)?.managed_worktree;
+            if (!isReconcilable(locked) || locked == null)
+                return { status: 'skipped', reason: 'already_reconciled' };
+            observed = await observe(locked);
+            if (locked.sweep !== undefined && sameObservation(locked.sweep.observed, observed)) {
+                return { status: 'refused', reason: locked.sweep.reason, ...(locked.sweep.detail === undefined ? {} : { detail: locked.sweep.detail }), unchanged: true };
+            }
+            return existsSync(locked.path)
+                ? await reconcilePresentCheckout(nodeId, locked, guard)
+                : await concludeAbsentCheckout(nodeId, locked, observed, guard);
+        }, {
+            timeoutMs: WORKTREE_LOCK_WAIT_MS,
+            timeoutError: () => new Error(`timed out waiting for the managed-worktree lock on ${commonDir}`),
+        });
+    }
+    catch (err) {
+        outcome = { status: 'failed', reason: 'lock_unavailable', detail: err instanceof Error ? err.message : String(err) };
+    }
+    return finish(nodeId, wt, outcome, observed, now, guard);
+}
+function finish(nodeId, wt, outcome, observed, now, guard) {
+    recordUnfinished(nodeId, wt, outcome, observed, now, guard);
+    return outcome;
+}
+/** Record completion against the record as it stands NOW, never the copy this
+ *  pass began with: the fresh read is what keeps a concurrently-rewritten record
+ *  (a revived node's, or one a human edited) from being overwritten with this
+ *  pass's stale fields. A record that moved out from under the pass is left
+ *  alone — its checkout and branch are already gone, so the next pass observes
+ *  both absent and concludes it cleanly. */
+function persistComplete(nodeId, wt, guard) {
+    if (!guard.stillEligible())
+        return NODE_REVIVED;
+    const current = getNode(nodeId)?.managed_worktree;
+    if (current == null || current.path !== wt.path || current.branch !== wt.branch) {
+        return { status: 'skipped', reason: 'record_changed' };
+    }
+    persistClosedWorktreeState(nodeId, current, 'complete');
+    return { status: 'complete' };
+}
+/** Resume a record whose checkout is already gone — the crash-after-removal
+ *  case, and the case where the checkout was removed by hand. Filesystem
+ *  absence proves nothing about commits, so the branch is still proved before
+ *  it is deleted. */
+async function concludeAbsentCheckout(nodeId, wt, observed, guard) {
+    const admin = wt.repo_root;
+    if (observed.branch === null) {
+        // Distinguish "the ref is gone" from "the read failed"; only the first
+        // authorizes concluding this record.
+        const exists = await gitAsync(['show-ref', '--verify', '--quiet', `refs/heads/${wt.branch}`], admin);
+        if (exists.status !== 1)
+            return { status: 'failed', reason: 'branch_inspection_failed', detail: detailOf(exists) };
+        return persistComplete(nodeId, wt, guard);
+    }
+    const list = await gitAsync(['worktree', 'list', '--porcelain'], admin);
+    if (list.status !== 0)
+        return { status: 'failed', reason: 'worktree_list_failed', detail: detailOf(list) };
+    // The recorded path being absent does NOT mean the branch has no checkout:
+    // `git worktree move` relocates one. Deleting a branch checked out elsewhere
+    // would bypass Git's own protection and could abandon uncommitted work there.
+    const elsewhere = checkoutPathForBranchInList(list.stdout, wt.branch);
+    if (elsewhere !== null) {
+        return { status: 'refused', reason: 'branch_checked_out_elsewhere', detail: `${wt.branch} is checked out at ${elsewhere}` };
+    }
+    const proof = await proveContained(admin, wt, observed.branch);
+    if (proof === null) {
+        return { status: 'refused', reason: 'unlanded_work', detail: `${wt.branch} carries content no base or upstream ref contains; its checkout is already gone, so the branch is the only copy` };
+    }
+    return deleteBranchAndComplete(nodeId, wt, admin, observed.branch, proof, guard);
+}
+/** The ordinary case: a checkout that still exists and whose owner is gone. */
+async function reconcilePresentCheckout(nodeId, wt, guard) {
+    const list = await gitAsync(['worktree', 'list', '--porcelain'], wt.path);
+    if (list.status !== 0)
+        return { status: 'failed', reason: 'worktree_list_failed', detail: detailOf(list) };
+    const registeredPath = registeredCheckoutPath(list.stdout, wt.path, wt.branch);
+    if (registeredPath === null) {
+        return { status: 'refused', reason: 'not_registered', detail: `${wt.path} is not registered to refs/heads/${wt.branch}; crtr will not act on a path it cannot prove it owns` };
+    }
+    const main = mainWorktreePath(list.stdout);
+    if (main === null || samePath(main, registeredPath) || !existsSync(main)) {
+        return { status: 'refused', reason: 'repo_unavailable', detail: `the repository's main checkout is unavailable, so ${wt.path} cannot be removed from outside itself` };
+    }
+    const midOperation = await isRebaseInProgressAsync(wt.path);
+    if (midOperation === null)
+        return { status: 'failed', reason: 'git_path_failed', detail: `could not inspect in-progress operations in ${wt.path}` };
+    if (midOperation)
+        return { status: 'refused', reason: 'rebase_in_progress', detail: `${wt.path} is mid-rebase` };
+    const head = await gitAsync(['rev-parse', '--abbrev-ref', 'HEAD'], wt.path);
+    if (head.status !== 0)
+        return { status: 'failed', reason: 'branch_check_failed', detail: detailOf(head) };
+    if (head.stdout.trim() !== wt.branch) {
+        return { status: 'refused', reason: 'wrong_branch', detail: `expected ${wt.branch}, found ${head.stdout.trim() === 'HEAD' ? 'detached HEAD' : head.stdout.trim()}` };
+    }
+    // Uncommitted work blocks removal unconditionally. No containment proof
+    // overrides this: those reason about committed content, and nothing here has
+    // any claim on changes a person or a dead node never committed.
+    const status = await gitAsync(['status', '--porcelain'], wt.path);
+    if (status.status !== 0)
+        return { status: 'failed', reason: 'status_failed', detail: detailOf(status) };
+    if (status.stdout.trim() !== '') {
+        return { status: 'refused', reason: 'dirty_worktree', detail: `${wt.path} has uncommitted changes` };
+    }
+    let branchSha = await revParseRef(wt.path, 'HEAD');
+    if (branchSha === null)
+        return { status: 'failed', reason: 'head_unreadable', detail: `could not read HEAD in ${wt.path}` };
+    let proof = await proveContained(wt.path, wt, branchSha);
+    let stash;
+    if (proof === null && wt.land_intent !== undefined) {
+        const landed = await finishBlockedLand(wt, list.stdout, guard);
+        if (!landed.ok)
+            return landed.ineligible === true ? NODE_REVIVED : { status: 'refused', reason: 'land_blocked', detail: landed.detail };
+        branchSha = landed.landedSha;
+        stash = landed.stash;
+        proof = await proveContained(wt.path, wt, branchSha);
+    }
+    if (proof === null) {
+        return { status: 'refused', reason: 'unlanded_work', detail: `${wt.branch} carries commits its base does not contain, and this node never asked to land them` };
+    }
+    // The last read-only moment. Everything past here destroys something, so the
+    // guard answers immediately before each step rather than once at the top.
+    if (!guard.stillEligible())
+        return NODE_REVIVED;
+    const removed = await gitAsync(['worktree', 'remove', registeredPath], main);
+    if (removed.status !== 0)
+        return { status: 'refused', reason: 'worktree_remove_failed', detail: detailOf(removed) };
+    const completed = await deleteBranchAndComplete(nodeId, wt, main, branchSha, proof, guard);
+    return completed.status === 'complete' && stash !== undefined ? { status: 'complete', stash } : completed;
+}
+/** Compare-and-delete the branch against the EXACT SHAs the proof inspected,
+ *  then record completion. A lost race leaves the branch intact, so the work
+ *  stays reachable — and leaves the record incomplete, so its node metadata is
+ *  still protected from prune and the next pass retries. */
+async function deleteBranchAndComplete(nodeId, wt, admin, branchSha, proof, guard) {
+    if (!guard.stillEligible())
+        return NODE_REVIVED;
+    const stdin = refDeleteTransactionStdin(wt.branch, branchSha, proof.containingRef, proof.containingSha);
+    const transaction = await gitAsync(['update-ref', '--stdin'], admin, stdin);
+    if (transaction.status !== 0) {
+        return { status: 'refused', reason: 'branch_delete_failed', detail: detailOf(transaction) };
+    }
+    return persistComplete(nodeId, wt, guard);
+}

package/dist/core/worktree.d.ts

@@ -14,6 +14,27 @@ export declare function managedWorktreesRoot(): string;
 export declare function managedWorktreePath(nodeId: string): string;
 export declare function hasOpenManagedWorktree(node: NodeMeta | null | undefined): boolean;
 export declare function openManagedWorktreeForNode(nodeId: string): ManagedWorktree | null;
+/** Shared parse for a `git worktree list --porcelain` blob already in hand —
+ *  callers that must not throw on a read failure (an absent-path proof that
+ *  needs to fail closed rather than error) call `gitSync` themselves and pass
+ *  the output here instead of going through `checkoutPathForBranch`. */
+export declare function checkoutPathForBranchInList(porcelain: string, branch: string): string | null;
+/** Are these two spellings the same directory?
+ *
+ *  Git canonicalizes every path it prints in `worktree list --porcelain`, while
+ *  a recorded managed-worktree path preserves the spelling of `CRTR_HOME`. When
+ *  the canvas home is reached through a symlink (macOS's `/var` → `/private/var`
+ *  is the everyday case) the two forms name one directory but differ as
+ *  strings, so a raw `===` reads a checkout crtr created as unowned. Resolution
+ *  failures fall back to `resolve`, which is the pre-canonical comparison — no
+ *  worse than the string compare it replaces. */
+export declare function samePath(a: string, b: string): boolean;
+export declare const WORKTREE_LOCK_WAIT_MS = 30000;
+/** The lock directory naming one repository's common Git dir. Every process
+ *  that mutates a managed worktree — the synchronous commands here and the
+ *  daemon's asynchronous sweep — derives its lock path through this function,
+ *  so the two locking styles contend for the SAME name. */
+export declare function worktreeLockPathForCommonDir(commonDir: string): string;
 export declare function rollbackManagedWorktree(wt: ManagedWorktree): void;
 export declare function createManagedWorktree(cwd: string, nodeId: string, baseRef?: string): ManagedWorktree;
 export declare function isRebaseInProgress(cwd: string): boolean;
@@ -29,7 +50,23 @@ export interface CloseManagedWorktreeResult {
     /** Always false while the pending-cleanup checkout has this branch checked out. */
     branch_deleted: boolean;
     branch_delete_error?: string;
+    /** Present ONLY when landing had to stash local changes in the base checkout
+     *  and re-applying them conflicted: names the preserved stash and how to
+     *  re-apply it. Its absence means nothing local was left over. */
+    base_checkout_stash?: string;
 }
+/** The ONE authoritative closed-worktree state transition, shared by every
+ * closing path (explicit `closeManagedWorktreeLocked` land, the clean
+ * `autoDropCleanManagedWorktreeLocked` push-final drop, and the daemon sweep's
+ * `reconcileManagedWorktree`): persist
+ * `managed_worktree.state: 'closed'`, name its cleanup state, and repoint the
+ * node's launch `cwd` to the durable base checkout. The caller broker stays
+ * alive and is Pi's sole transcript writer, so its session header cannot be
+ * safely rewritten here; clear the session coordinates and let the later
+ * revive launch fresh instead. Both closing paths MUST go through this helper
+ * instead of hand-rolling the `updateNode` call, so neither can drift out of
+ * sync. */
+export declare function persistClosedWorktreeState(nodeId: string, wt: ManagedWorktree, cleanup?: 'pending' | 'complete'): void;
 export declare function closeManagedWorktree(nodeId: string): CloseManagedWorktreeResult;
 export interface AbandonManagedWorktreeResult {
     node_id: string;