@north-light/crouter 0.3.154

package/dist/core/__tests__/worktree.test.js

@@ -0,0 +1,876 @@
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, existsSync, readdirSync, statSync, writeFileSync, chmodSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { gitSync } from '../git.js';
+import { push } from '../feed/feed.js';
+import { createManagedWorktree, closeManagedWorktree, managedWorktreePath, rollbackManagedWorktree, setWorktreeCleanupRunnerForTest } from '../worktree.js';
+import { createNode, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+let home;
+let remoteDir;
+let sourceDir;
+function run(args, cwd) {
+    const res = gitSync(args, cwd);
+    if (res.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed in ${cwd}: ${res.stderr || res.stdout}`);
+    }
+}
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-worktree-home-'));
+    process.env['CRTR_HOME'] = home;
+    // Bare "remote" wired up as origin so the test can prove landing NEVER pushes
+    // to it (managed worktrees are based on and land onto local `main` only).
+    remoteDir = mkdtempSync(join(tmpdir(), 'crtr-worktree-remote-'));
+    run(['init', '--bare'], remoteDir);
+    sourceDir = mkdtempSync(join(tmpdir(), 'crtr-worktree-source-'));
+    run(['init', '-b', 'main'], sourceDir);
+    run(['config', 'user.email', 'test@example.com'], sourceDir);
+    run(['config', 'user.name', 'Test'], sourceDir);
+    writeFileSync(join(sourceDir, 'README.md'), 'hello\n');
+    run(['add', '.'], sourceDir);
+    run(['commit', '-m', 'init'], sourceDir);
+    run(['remote', 'add', 'origin', remoteDir], sourceDir);
+    run(['push', '-u', 'origin', 'main'], sourceDir);
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    process.env['CRTR_HOME'] = home;
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(remoteDir, { recursive: true, force: true });
+    rmSync(sourceDir, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+// Regression for #120: `git worktree remove` deletes the checkout directory
+// that 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 that
+// dir is gone every subsequent bash in that node fails permanently and the
+// mandated post-close `crtr push final` can never run. closeManagedWorktree
+// must leave the path resolvable (as an empty tombstone dir) even though the
+// git worktree registration itself is gone.
+test('closeManagedWorktree recreates the worktree path as a tombstone dir so the node cwd still resolves', () => {
+    const nodeId = 'wt-close-1';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    assert.equal(wt.base_ref, 'main', 'default base must remain backward-compatible with persisted main worktrees');
+    assert.equal(wt.path, managedWorktreePath(nodeId));
+    assert.ok(existsSync(wt.path), 'worktree checkout should exist after create');
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    const result = closeManagedWorktree(nodeId);
+    assert.equal(result.worktree_removed, true);
+    // The path must still resolve as a directory — this is the actual fix: a
+    // node whose cwd was wt.path can still chdir there / run bash / push final.
+    assert.ok(existsSync(wt.path), 'worktree path must still exist after close (tombstone)');
+    assert.ok(statSync(wt.path).isDirectory(), 'recreated path must be a directory');
+    assert.deepEqual(readdirSync(wt.path), [], 'tombstone dir should be empty — git already removed the real checkout');
+    // git itself no longer tracks it as a worktree.
+    const list = gitSync(['worktree', 'list', '--porcelain'], sourceDir);
+    assert.ok(!list.stdout.includes(wt.path), 'git should no longer register the removed worktree');
+    const meta = getNode(nodeId);
+    assert.equal(meta?.managed_worktree?.state, 'closed');
+    // Regression for #519: a later park/revive must relaunch from the durable
+    // base checkout, not the torn-down worktree dir (best-effort tombstone —
+    // reapable by concurrent git GC, and not a real repo checkout even while
+    // it survives). closeManagedWorktree must repoint the persisted cwd.
+    assert.equal(meta?.cwd, wt.repo_root, 'closed node cwd must repoint to the repo root, not the removed worktree path');
+});
+test('two concurrent creates from linked worktrees serialize on their shared repository', async () => {
+    const worktreeModule = new URL('../worktree.ts', import.meta.url).href;
+    const createFrom = (cwd, nodeId) => new Promise((resolve, reject) => {
+        const script = `import { createManagedWorktree } from ${JSON.stringify(worktreeModule)}; createManagedWorktree(${JSON.stringify(cwd)}, ${JSON.stringify(nodeId)});`;
+        const child = spawn(process.execPath, ['--import', 'tsx/esm', '--input-type=module', '--eval', script], { env: { ...process.env, CRTR_HOME: home }, stdio: 'pipe' });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', reject);
+        child.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`concurrent create exited ${code}: ${stderr}`)));
+    });
+    const linkedCheckout = mkdtempSync(join(tmpdir(), 'crtr-worktree-linked-'));
+    rmSync(linkedCheckout, { recursive: true, force: true });
+    run(['worktree', 'add', '-b', 'wt-concurrent-source', linkedCheckout], sourceDir);
+    try {
+        await Promise.all([createFrom(sourceDir, 'wt-concurrent-1'), createFrom(linkedCheckout, 'wt-concurrent-2')]);
+        for (const nodeId of ['wt-concurrent-1', 'wt-concurrent-2']) {
+            const path = managedWorktreePath(nodeId);
+            assert.ok(existsSync(path), `${nodeId} checkout should exist`);
+            assert.equal(gitSync(['rev-parse', '--abbrev-ref', 'HEAD'], path).stdout.trim(), `crtr/${nodeId}`);
+            rollbackManagedWorktree({
+                state: 'open', path, branch: `crtr/${nodeId}`, repo_root: sourceDir, base_ref: 'main',
+                base_sha: gitSync(['rev-parse', 'main'], sourceDir).stdout.trim(), created: new Date().toISOString(),
+            });
+        }
+    }
+    finally {
+        run(['worktree', 'remove', '--force', linkedCheckout], sourceDir);
+        run(['branch', '-D', 'wt-concurrent-source'], sourceDir);
+    }
+});
+test('failure after branch creation removes only the failed attempt resources', () => {
+    // A file at the managed-worktree root makes `git worktree add` fail only
+    // after this attempt created its branch. No checkout can be registered.
+    mkdirSync(home, { recursive: true });
+    writeFileSync(join(home, 'worktrees'), 'blocked');
+    const nodeId = 'wt-failed-checkout';
+    assert.throws(() => createManagedWorktree(sourceDir, nodeId));
+    assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/crtr/${nodeId}`], sourceDir).status, 1, 'failed attempt branch must be removed');
+    assert.ok(!gitSync(['worktree', 'list', '--porcelain'], sourceDir).stdout.includes(`crtr/${nodeId}`), 'failed attempt must not leave a worktree registration');
+    assert.ok(!existsSync(managedWorktreePath(nodeId)), 'failed attempt must not leave a checkout directory');
+});
+// Landing is purely local: a commit made in the managed worktree must advance
+// the source repo's LOCAL main to that commit, and origin/main must stay put
+// (close never pushes to origin).
+test('closeManagedWorktree fast-forwards local main to the worktree tip without touching origin', () => {
+    const nodeId = 'wt-close-2';
+    const originMainBefore = gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim();
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    // Commit real work inside the managed worktree.
+    writeFileSync(join(wt.path, 'feature.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'feature'], wt.path);
+    const workSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    const result = closeManagedWorktree(nodeId);
+    assert.equal(result.landed_sha, workSha, 'landed_sha should be the committed work');
+    // Local main in the source (primary) checkout advanced to the work.
+    const localMainAfter = gitSync(['rev-parse', 'main'], sourceDir).stdout.trim();
+    assert.equal(localMainAfter, workSha, 'local main must fast-forward to the worktree tip');
+    // origin/main is untouched — nothing was pushed.
+    const originMainAfter = gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim();
+    assert.equal(originMainAfter, originMainBefore, 'origin/main must not move — landing is local-only');
+});
+test('custom local base is recorded and fast-forwarded without touching main or origin', () => {
+    const nodeId = 'wt-custom-base';
+    run(['branch', 'feature/custom-base'], sourceDir);
+    const baseSha = gitSync(['rev-parse', 'feature/custom-base'], sourceDir).stdout.trim();
+    const mainBefore = gitSync(['rev-parse', 'main'], sourceDir).stdout.trim();
+    const originMainBefore = gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim();
+    const wt = createManagedWorktree(sourceDir, nodeId, 'feature/custom-base');
+    assert.equal(wt.base_ref, 'feature/custom-base');
+    assert.equal(wt.base_sha, baseSha);
+    assert.equal(gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim(), baseSha, 'dedicated branch starts at the custom base');
+    assert.equal(gitSync(['rev-parse', '--abbrev-ref', 'HEAD'], wt.path).stdout.trim(), `crtr/${nodeId}`, 'the worktree checks out its own dedicated crtr/<node-id> branch, not the base branch');
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'custom-base.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'custom base work'], wt.path);
+    // The base can advance while the child works. Close must rebase onto that
+    // new tip before atomically advancing the base to the child work.
+    run(['checkout', 'feature/custom-base'], sourceDir);
+    writeFileSync(join(sourceDir, 'base-advance.txt'), 'base work\n');
+    run(['add', '.'], sourceDir);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'base advance'], sourceDir);
+    const advancedBaseSha = gitSync(['rev-parse', 'HEAD'], sourceDir).stdout.trim();
+    run(['checkout', 'main'], sourceDir);
+    const originalWorkSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    const result = closeManagedWorktree(nodeId);
+    assert.equal(gitSync(['merge-base', '--is-ancestor', originalWorkSha, result.landed_sha], sourceDir).status, 1, 'rebasing onto an advanced base must rewrite the child commit');
+    assert.equal(gitSync(['merge-base', '--is-ancestor', advancedBaseSha, result.landed_sha], sourceDir).status, 0, 'landed work must be rebased onto the latest base tip');
+    assert.equal(gitSync(['rev-parse', 'feature/custom-base'], sourceDir).stdout.trim(), result.landed_sha, 'custom base must fast-forward to the worktree tip');
+    assert.equal(gitSync(['rev-parse', 'main'], sourceDir).stdout.trim(), mainBefore, 'main must remain untouched');
+    assert.equal(gitSync(['rev-parse', 'origin/main'], sourceDir).stdout.trim(), originMainBefore, 'origin/main must remain untouched');
+});
+test('refuses a custom-base close when its unchecked base advances after rebase', () => {
+    const nodeId = 'wt-custom-base-cas-race';
+    const base = 'feature/cas-race-base';
+    run(['branch', base], sourceDir);
+    const baseSha = gitSync(['rev-parse', base], sourceDir).stdout.trim();
+    const wt = createManagedWorktree(sourceDir, nodeId, base);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'cas-child.txt'), 'child work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'cas child work'], wt.path);
+    // Pre-create the other writer's commit, then reset the base so the rebase
+    // begins from baseSha. A test-only git wrapper advances it when close calls
+    // its final update-ref CAS, immediately before the real git receives that
+    // CAS request.
+    run(['checkout', base], sourceDir);
+    writeFileSync(join(sourceDir, 'cas-base.txt'), 'base work\n');
+    run(['add', '.'], sourceDir);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'cas base work'], sourceDir);
+    const advancedBaseSha = gitSync(['rev-parse', 'HEAD'], sourceDir).stdout.trim();
+    run(['checkout', 'main'], sourceDir);
+    run(['update-ref', `refs/heads/${base}`, baseSha], sourceDir);
+    const wrapperDir = mkdtempSync(join(tmpdir(), 'crtr-git-wrapper-'));
+    const wrapperPath = join(wrapperDir, 'git');
+    const originalPath = process.env['PATH'] ?? '';
+    writeFileSync(wrapperPath, `#!/bin/sh
+if [ "$1" = "update-ref" ] && [ "$2" = "refs/heads/${base}" ] && [ "$4" = "${baseSha}" ]; then
+  PATH="$CRTR_TEST_REAL_PATH" git -C "${sourceDir}" update-ref "refs/heads/${base}" "${advancedBaseSha}"
+fi
+PATH="$CRTR_TEST_REAL_PATH" exec git "$@"
+`);
+    chmodSync(wrapperPath, 0o755);
+    process.env['CRTR_TEST_REAL_PATH'] = originalPath;
+    process.env['PATH'] = `${wrapperDir}:${originalPath}`;
+    try {
+        assert.throws(() => closeManagedWorktree(nodeId), (error) => error instanceof Error && 'code' in error && error.code === 'land_base_failed');
+    }
+    finally {
+        process.env['PATH'] = originalPath;
+        delete process.env['CRTR_TEST_REAL_PATH'];
+        rmSync(wrapperDir, { recursive: true, force: true });
+    }
+    assert.equal(gitSync(['rev-parse', base], sourceDir).stdout.trim(), advancedBaseSha, 'CAS failure must preserve the concurrent base advance');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'failed landing must leave the worktree open for retry or human resolution');
+});
+test('rebases onto the captured SHA when an unchecked base advances before rebase starts', () => {
+    const nodeId = 'wt-custom-base-rebase-race';
+    const base = 'feature/rebase-race-base';
+    run(['branch', base], sourceDir);
+    const baseSha = gitSync(['rev-parse', base], sourceDir).stdout.trim();
+    const wt = createManagedWorktree(sourceDir, nodeId, base);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'rebase-race-child.txt'), 'child work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'rebase race child work'], wt.path);
+    // Prepare another writer's commit, then move the unchecked base back to the
+    // SHA close will capture. The wrapper advances the base immediately before
+    // the real rebase starts. Close must still rebase onto its captured SHA, not
+    // resolve the now-advanced symbolic branch, and the stale landing CAS fails.
+    run(['checkout', base], sourceDir);
+    writeFileSync(join(sourceDir, 'rebase-race-base.txt'), 'base work\n');
+    run(['add', '.'], sourceDir);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'rebase race base work'], sourceDir);
+    const advancedBaseSha = gitSync(['rev-parse', 'HEAD'], sourceDir).stdout.trim();
+    run(['checkout', 'main'], sourceDir);
+    run(['update-ref', `refs/heads/${base}`, baseSha], sourceDir);
+    const wrapperDir = mkdtempSync(join(tmpdir(), 'crtr-git-wrapper-'));
+    const wrapperPath = join(wrapperDir, 'git');
+    const originalPath = process.env['PATH'] ?? '';
+    writeFileSync(wrapperPath, `#!/bin/sh
+if [ "$1" = "rebase" ] && [ "$2" = "${baseSha}" ]; then
+  PATH="$CRTR_TEST_REAL_PATH" git -C "${sourceDir}" update-ref "refs/heads/${base}" "${advancedBaseSha}"
+fi
+PATH="$CRTR_TEST_REAL_PATH" exec git "$@"
+`);
+    chmodSync(wrapperPath, 0o755);
+    process.env['CRTR_TEST_REAL_PATH'] = originalPath;
+    process.env['PATH'] = `${wrapperDir}:${originalPath}`;
+    try {
+        assert.throws(() => closeManagedWorktree(nodeId), (error) => error instanceof Error && 'code' in error && error.code === 'land_base_failed');
+    }
+    finally {
+        process.env['PATH'] = originalPath;
+        delete process.env['CRTR_TEST_REAL_PATH'];
+        rmSync(wrapperDir, { recursive: true, force: true });
+    }
+    const rebasedChildSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    assert.equal(gitSync(['rev-parse', base], sourceDir).stdout.trim(), advancedBaseSha, 'CAS failure must preserve the advance that raced with rebase');
+    assert.equal(gitSync(['merge-base', '--is-ancestor', advancedBaseSha, rebasedChildSha], sourceDir).status, 1, 'the child must not rebase onto a symbolic base advance after baseSha was captured');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'failed landing must leave the worktree open for retry or human resolution');
+});
+test('refuses to land when a checked-out base is reset after its SHA is captured', () => {
+    const nodeId = 'wt-custom-base-checked-out-reset-race';
+    const base = 'feature/checked-out-reset-race-base';
+    run(['checkout', '-b', base], sourceDir);
+    const resetSha = gitSync(['rev-parse', 'HEAD'], sourceDir).stdout.trim();
+    writeFileSync(join(sourceDir, 'checked-out-reset-base.txt'), 'base work\n');
+    run(['add', '.'], sourceDir);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'checked out reset base work'], sourceDir);
+    const baseSha = gitSync(['rev-parse', 'HEAD'], sourceDir).stdout.trim();
+    const wt = createManagedWorktree(sourceDir, nodeId, base);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'checked-out-reset-child.txt'), 'child work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'checked out reset child work'], wt.path);
+    // Reset the checked-out base backward immediately before the child rebases.
+    // The real rebase still targets captured baseSha, so only the explicit HEAD
+    // equality check can prevent an ff-only merge from restoring discarded work.
+    const wrapperDir = mkdtempSync(join(tmpdir(), 'crtr-git-wrapper-'));
+    const wrapperPath = join(wrapperDir, 'git');
+    const originalPath = process.env['PATH'] ?? '';
+    writeFileSync(wrapperPath, `#!/bin/sh
+if [ "$1" = "rebase" ] && [ "$2" = "${baseSha}" ]; then
+  PATH="$CRTR_TEST_REAL_PATH" git -C "${sourceDir}" reset --hard "${resetSha}"
+fi
+PATH="$CRTR_TEST_REAL_PATH" exec git "$@"
+`);
+    chmodSync(wrapperPath, 0o755);
+    process.env['CRTR_TEST_REAL_PATH'] = originalPath;
+    process.env['PATH'] = `${wrapperDir}:${originalPath}`;
+    try {
+        assert.throws(() => closeManagedWorktree(nodeId), (error) => error instanceof Error && 'code' in error && error.code === 'land_base_failed');
+    }
+    finally {
+        process.env['PATH'] = originalPath;
+        delete process.env['CRTR_TEST_REAL_PATH'];
+        rmSync(wrapperDir, { recursive: true, force: true });
+    }
+    assert.equal(gitSync(['rev-parse', 'HEAD'], sourceDir).stdout.trim(), resetSha, 'failed landing must leave the checked-out base at the concurrent reset SHA');
+    assert.equal(gitSync(['rev-parse', base], sourceDir).stdout.trim(), resetSha, 'failed landing must not restore discarded base commits');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'failed landing must leave the worktree open for retry or human resolution');
+    run(['checkout', 'main'], sourceDir);
+});
+test('close fast-forwards a custom base in its checked-out worktree', () => {
+    const nodeId = 'wt-custom-base-checked-out';
+    run(['checkout', '-b', 'feature/checked-out-base'], sourceDir);
+    const wt = createManagedWorktree(sourceDir, nodeId, 'feature/checked-out-base');
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'checked-out-base.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'checked out base work'], wt.path);
+    const workSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    closeManagedWorktree(nodeId);
+    assert.equal(gitSync(['rev-parse', 'feature/checked-out-base'], sourceDir).stdout.trim(), workSha);
+    assert.equal(gitSync(['rev-parse', 'HEAD'], sourceDir).stdout.trim(), workSha, 'checked-out base worktree must advance with its ref');
+    run(['checkout', 'main'], sourceDir);
+});
+test('rejects remote and nonexistent worktree bases before creating any resources', () => {
+    for (const [nodeId, base] of [['wt-remote-base', 'origin/main'], ['wt-bogus-base', 'feature/does-not-exist']]) {
+        assert.throws(() => createManagedWorktree(sourceDir, nodeId, base), (error) => error instanceof Error
+            && 'code' in error
+            && error.code === 'missing_base_branch'
+            && error.message.includes(base));
+        assert.ok(!existsSync(managedWorktreePath(nodeId)), `${base} must not leave a worktree directory`);
+        assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/crtr/${nodeId}`], sourceDir).status, 1, `${base} must not leave a dedicated branch`);
+    }
+});
+test('refuses to close when the recorded base was deleted and leaves the worktree open', () => {
+    const nodeId = 'wt-deleted-base';
+    run(['branch', 'feature/deleted-base'], sourceDir);
+    const mainBefore = gitSync(['rev-parse', 'main'], sourceDir).stdout.trim();
+    const wt = createManagedWorktree(sourceDir, nodeId, 'feature/deleted-base');
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'deleted-base.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'deleted base work'], wt.path);
+    run(['branch', '-D', 'feature/deleted-base'], sourceDir);
+    assert.throws(() => closeManagedWorktree(nodeId), (error) => error instanceof Error && 'code' in error && error.code === 'missing_base_branch');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'a missing base must not silently close or retarget the worktree');
+    assert.ok(existsSync(wt.path), 'the worktree must remain available for a human decision');
+    assert.equal(gitSync(['rev-parse', 'main'], sourceDir).stdout.trim(), mainBefore, 'missing base must never auto-land onto main');
+});
+// Regression for #330/#331: crtr's own untracked `.crouter/config.json` /
+// `state.json` bookkeeping (written by ordinary project-scope init) must
+// never block `close`'s dirty check — Fix A seeds `.git/info/exclude` for
+// exactly those two filenames at worktree-creation time.
+test('close ignores crtr\'s own untracked .crouter/config.json and state.json bookkeeping', () => {
+    const nodeId = 'wt-crtr-bookkeeping';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    mkdirSync(join(wt.path, '.crouter'), { recursive: true });
+    writeFileSync(join(wt.path, '.crouter', 'config.json'), '{}\n');
+    writeFileSync(join(wt.path, '.crouter', 'state.json'), '{}\n');
+    // The seeded exclude is on the SHARED common git dir — assert git itself
+    // reports a clean tree, not just that close happens not to notice.
+    assert.equal(gitSync(['status', '--porcelain'], wt.path).stdout.trim(), '', 'git status must already be clean with only crtr bookkeeping present');
+    const result = closeManagedWorktree(nodeId);
+    assert.equal(result.worktree_removed, true);
+});
+// The exclude must be narrow: it must NEVER hide real, committable node work
+// that merely happens to live under `.crouter/` — this mirrors crouter's OWN
+// repo, which tracks `.crouter/memory/`. Set up a dedicated repo (not the
+// shared sourceDir, which never tracks `.crouter/`) that already tracks a
+// memory doc, then prove BOTH a modification to it and a brand-new untracked
+// doc beside it still block close exactly as before Fix A.
+test('close still blocks on real .crouter/memory/ work — a tracked-file edit and a new untracked doc', () => {
+    const memoryRepo = mkdtempSync(join(tmpdir(), 'crtr-worktree-memoryrepo-'));
+    run(['init', '-b', 'main'], memoryRepo);
+    run(['config', 'user.email', 'test@example.com'], memoryRepo);
+    run(['config', 'user.name', 'Test'], memoryRepo);
+    mkdirSync(join(memoryRepo, '.crouter', 'memory'), { recursive: true });
+    writeFileSync(join(memoryRepo, '.crouter', 'memory', 'AGENTS.md'), 'tracked memory doc\n');
+    run(['add', '.'], memoryRepo);
+    run(['commit', '-m', 'init with tracked memory'], memoryRepo);
+    const editNodeId = 'wt-real-crouter-memory-edit';
+    const editWt = createManagedWorktree(memoryRepo, editNodeId);
+    createNode(node(editNodeId, { cwd: editWt.path, managed_worktree: editWt }));
+    writeFileSync(join(editWt.path, '.crouter', 'memory', 'AGENTS.md'), 'edited tracked memory doc\n');
+    const editStatus = gitSync(['status', '--porcelain'], editWt.path).stdout;
+    assert.ok(editStatus.includes('M .crouter/memory/AGENTS.md'), 'a tracked .crouter/memory/ edit must still show as modified — exclude can never hide a tracked-file change');
+    assert.throws(() => closeManagedWorktree(editNodeId), (error) => error instanceof Error && 'code' in error && error.code === 'dirty_worktree');
+    const newDocNodeId = 'wt-real-crouter-memory-new-doc';
+    const newDocWt = createManagedWorktree(memoryRepo, newDocNodeId);
+    createNode(node(newDocNodeId, { cwd: newDocWt.path, managed_worktree: newDocWt }));
+    writeFileSync(join(newDocWt.path, '.crouter', 'memory', 'new-doc.md'), 'a legitimate new memory doc\n');
+    const newDocStatus = gitSync(['status', '--porcelain'], newDocWt.path).stdout;
+    assert.ok(newDocStatus.includes('.crouter/memory/new-doc.md'), 'a brand-new untracked doc under an already-tracked .crouter/memory/ must still show as dirty');
+    assert.throws(() => closeManagedWorktree(newDocNodeId), (error) => error instanceof Error && 'code' in error && error.code === 'dirty_worktree');
+    rmSync(memoryRepo, { recursive: true, force: true });
+});
+// Fix B (#327/#333): a managed worktree with zero commits ahead of its base
+// and nothing uncommitted has nothing to land — push-final's auto-drop path
+// (autoDropCleanManagedWorktree) must close it without requiring an explicit
+// `node worktree close`.
+test('autoDropCleanManagedWorktree drops a clean, zero-commit worktree', async () => {
+    const { autoDropCleanManagedWorktree } = await import('../worktree.js');
+    const nodeId = 'wt-auto-drop-empty';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    const result = autoDropCleanManagedWorktree(nodeId);
+    assert.ok(result !== null, 'a worktree with zero commits and a clean tree must be droppable');
+    assert.equal(result?.worktree_removed, true);
+    const meta = getNode(nodeId);
+    assert.equal(meta?.managed_worktree?.state, 'closed');
+    assert.ok(!gitSync(['worktree', 'list', '--porcelain'], sourceDir).stdout.includes(wt.path), 'git must no longer register the dropped worktree');
+    // Regression for #519: auto-drop must persist the SAME closed-worktree
+    // transition explicit close does — repointing `cwd` to the durable base
+    // checkout, atomically with `state: 'closed'`. Before the fix, auto-drop
+    // left `cwd` at the removed worktree path; that path is recreated as an
+    // empty tombstone dir (see `bestEffortRemoveWorktreeCheckout`), so a later
+    // `--reopen` revive's `existsSync(meta.cwd)` preflight passed anyway and
+    // launched into a non-checkout instead of failing loud or landing somewhere
+    // real. `cwd` must be durable: a real git checkout, not a reapable stand-in.
+    assert.equal(meta?.cwd, wt.repo_root, 'auto-dropped node cwd must repoint to the repo root, not the removed worktree path');
+    assert.equal(gitSync(['rev-parse', '--git-dir'], meta.cwd).status, 0, 'repointed cwd must resolve to a real git checkout a reopen/revive can launch from');
+    assert.equal(existsSync(join(wt.path, '.git')), false, 'the tombstoned worktree path must NOT itself resolve as a git checkout');
+});
+// The same real-commit case close already protects: a worktree with actual
+// unlanded work must NEVER be auto-dropped by push-final.
+test('autoDropCleanManagedWorktree refuses a worktree with a real commit ahead of base', async () => {
+    const { autoDropCleanManagedWorktree } = await import('../worktree.js');
+    const nodeId = 'wt-auto-drop-real-work';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'real-work.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'real work'], wt.path);
+    const result = autoDropCleanManagedWorktree(nodeId);
+    assert.equal(result, null, 'a worktree with a real commit ahead of base must never be silently dropped');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'the worktree must remain open for an explicit close');
+    assert.ok(existsSync(wt.path), 'the checkout with real work must remain intact');
+});
+// Real uncommitted (non-crtr-bookkeeping) changes must also refuse auto-drop,
+// even with zero commits.
+test('autoDropCleanManagedWorktree refuses a worktree with real uncommitted changes', async () => {
+    const { autoDropCleanManagedWorktree } = await import('../worktree.js');
+    const nodeId = 'wt-auto-drop-dirty';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'uncommitted.txt'), 'not yet committed\n');
+    const result = autoDropCleanManagedWorktree(nodeId);
+    assert.equal(result, null, 'real uncommitted changes must never be silently dropped');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open');
+});
+// The actual #327 positive case: a branch with REAL commits whose tip is
+// already contained in a base that moved forward past this worktree's
+// original base_sha (a manager landed the same change another way, without
+// ever going through crtr's own close path). This must auto-drop and, above
+// all, must never lose the work — it stays reachable from the moved base.
+test('autoDropCleanManagedWorktree drops a branch with real commits already contained in a moved base (#327)', async () => {
+    const { autoDropCleanManagedWorktree } = await import('../worktree.js');
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-327-'));
+    run(['init', '-b', 'main'], repo);
+    run(['config', 'user.email', 'test@example.com'], repo);
+    run(['config', 'user.name', 'Test'], repo);
+    writeFileSync(join(repo, 'README.md'), 'hello\n');
+    run(['add', '.'], repo);
+    run(['commit', '-m', 'init'], repo);
+    const nodeId = 'wt-327-positive';
+    const wt = createManagedWorktree(repo, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'feature.txt'), 'landed elsewhere\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'feature'], wt.path);
+    const branchSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    // A manager fast-forwards main past this branch's own tip directly in the
+    // primary checkout — the base moved AFTER the worktree was created, and
+    // this branch's commits are now redundant, not lost.
+    run(['merge', '--ff-only', branchSha], repo);
+    assert.equal(gitSync(['rev-parse', 'main'], repo).stdout.trim(), branchSha);
+    const result = autoDropCleanManagedWorktree(nodeId);
+    assert.ok(result !== null, 'a branch whose commits are already contained in a moved base has nothing left to land');
+    assert.equal(result?.branch_deleted, true);
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'closed');
+    assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/${wt.branch}`], repo).status, 1, 'the now-redundant branch ref must actually be gone');
+    // The work itself is NOT lost — it stays reachable from main, which is the point.
+    assert.equal(gitSync(['merge-base', '--is-ancestor', branchSha, 'main'], repo).status, 0, 'the landed commit must remain reachable from main after the drop');
+    rmSync(repo, { recursive: true, force: true });
+});
+// A base that no longer resolves (renamed/deleted local branch) must refuse
+// auto-drop rather than guess — the SAME guard `resolveLandableBase` already
+// gives the explicit close path.
+test('autoDropCleanManagedWorktree refuses when the recorded base branch no longer resolves', async () => {
+    const { autoDropCleanManagedWorktree } = await import('../worktree.js');
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-missingbase-'));
+    run(['init', '-b', 'main'], repo);
+    run(['config', 'user.email', 'test@example.com'], repo);
+    run(['config', 'user.name', 'Test'], repo);
+    writeFileSync(join(repo, 'README.md'), 'hello\n');
+    run(['add', '.'], repo);
+    run(['commit', '-m', 'init'], repo);
+    const nodeId = 'wt-missing-base';
+    const wt = createManagedWorktree(repo, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    // The recorded base branch ('main') has been renamed away since creation.
+    run(['branch', '-m', 'main', 'renamed-main'], repo);
+    const result = autoDropCleanManagedWorktree(nodeId);
+    assert.equal(result, null, 'an unresolvable base must never be treated as safe to drop');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open');
+    assert.ok(existsSync(wt.path));
+    rmSync(repo, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// The Critical fix: the TOCTOU race between proving clean-and-contained and
+// the destructive branch delete. `proveCleanEmptyManagedWorktree` and
+// `autoDropCleanManagedWorktreeLocked` are exported specifically so these
+// tests can inject a race deterministically in the window between them —
+// exactly the window the repository lock does NOT close (it only serializes
+// crtr's own worktree mutations, not ordinary `git commit`/`git reset`/an
+// external base rewrite run by any other process against the checkout).
+// ---------------------------------------------------------------------------
+// A concurrent commit lands on the managed branch after the predicate proved
+// it clean-and-contained, but before cleanup deletes it. The atomic
+// compare-and-delete must refuse, leaving the branch (and the new commit)
+// fully intact.
+test('the atomic delete refuses when a commit lands on the branch between the predicate and cleanup', async () => {
+    const { proveCleanEmptyManagedWorktree, autoDropCleanManagedWorktreeLocked } = await import('../worktree.js');
+    const nodeId = 'wt-race-branch-commit';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    const proof = proveCleanEmptyManagedWorktree(wt);
+    assert.ok(proof !== null, 'a fresh clean, zero-commit worktree must prove droppable');
+    // Simulate a concurrent process committing new work on the managed branch
+    // in the window between the predicate and cleanup.
+    writeFileSync(join(wt.path, 'concurrent-work.txt'), 'a real commit landed mid-cleanup\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'concurrent work'], wt.path);
+    const concurrentSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    assert.notEqual(concurrentSha, proof?.branchSha, 'the branch must have actually moved past the proven SHA for this test to be meaningful');
+    const result = autoDropCleanManagedWorktreeLocked(nodeId, wt, proof);
+    assert.equal(result, null, 'the atomic delete must refuse once the branch has moved past the proven SHA');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'state must stay open — nothing may be marked safely dropped');
+    assert.ok(existsSync(wt.path), 'the path must still resolve (tombstoned if the checkout itself was removed) — never left dangling');
+    // The actual safety property: the branch ref, and the concurrent commit it
+    // now names, are fully preserved — regardless of whether the checkout
+    // itself survived (git requires removing it before the ref delete can even
+    // be attempted; see the ordering note on autoDropCleanManagedWorktreeLocked).
+    const refCheck = gitSync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], wt.repo_root);
+    assert.equal(refCheck.status, 0, 'the branch ref must still exist');
+    assert.equal(refCheck.stdout.trim(), concurrentSha, 'the branch, and the concurrent commit it names, must still be reachable — nothing was lost');
+});
+// An external rewrite of the base branch (e.g. a force-reset) invalidates the
+// containment proof in the same window. The re-verification immediately
+// before the delete must catch this even though the branch itself never
+// moved.
+test('the re-verified base containment refuses when the base is rewritten between the predicate and cleanup', async () => {
+    const { proveCleanEmptyManagedWorktree, autoDropCleanManagedWorktreeLocked } = await import('../worktree.js');
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-race-base-'));
+    run(['init', '-b', 'main'], repo);
+    run(['config', 'user.email', 'test@example.com'], repo);
+    run(['config', 'user.name', 'Test'], repo);
+    writeFileSync(join(repo, 'README.md'), 'hello\n');
+    run(['add', '.'], repo);
+    run(['commit', '-m', 'init'], repo);
+    const nodeId = 'wt-race-base-rewrite';
+    const wt = createManagedWorktree(repo, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    const proof = proveCleanEmptyManagedWorktree(wt);
+    assert.ok(proof !== null, 'a fresh clean, zero-commit worktree must prove droppable');
+    // Simulate an external force-reset of the base branch in the same window —
+    // an unrelated rewrite (not a fast-forward), so the proven branch tip is no
+    // longer an ancestor of the new base tip.
+    writeFileSync(join(repo, 'rewritten.txt'), 'unrelated history\n');
+    run(['add', '.'], repo);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '--amend', '-m', 'rewritten base tip'], repo);
+    const rewrittenBaseSha = gitSync(['rev-parse', 'main'], repo).stdout.trim();
+    assert.notEqual(rewrittenBaseSha, proof?.baseSha, 'the base must have actually moved for this test to be meaningful');
+    const stillAncestor = gitSync(['merge-base', '--is-ancestor', proof.branchSha, rewrittenBaseSha], repo);
+    assert.notEqual(stillAncestor.status, 0, 'the rewrite must actually break containment for this test to be meaningful');
+    const result = autoDropCleanManagedWorktreeLocked(nodeId, wt, proof);
+    assert.equal(result, null, 'a base rewrite that breaks containment must refuse the drop');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'state must stay open — nothing may be marked safely dropped');
+    assert.ok(existsSync(wt.path), 'the checkout must remain intact');
+    assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/${wt.branch}`], repo).status, 0, 'the branch ref must still exist — nothing was lost');
+    rmSync(repo, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// The base-ref TOCTOU: a branch-only compare-and-delete refuses when the
+// BRANCH moves, but a base force-reset between the containment proof and the
+// delete could still leave the delete's own condition (the branch equals the
+// proven SHA) satisfied while the branch is no longer contained in anything.
+// `bestEffortDeleteBranchWithBaseProof` closes this by binding the base's
+// live value into the SAME atomic transaction as the branch delete. These
+// tests reproduce the race against real Git by wrapping the `git worktree
+// remove` call each cleanup path makes strictly between its live ancestry
+// re-check and its ref-deletion transaction — the same technique used above
+// for the branch-only race, and the same one the independent re-review used
+// to reproduce this exact Critical against `6de1c8d`.
+// ---------------------------------------------------------------------------
+test('auto-drop atomic delete refuses when the base is force-reset between the live ancestry check and the ref transaction', async () => {
+    const { proveCleanEmptyManagedWorktree, autoDropCleanManagedWorktreeLocked } = await import('../worktree.js');
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-auto-drop-base-window-'));
+    run(['init', '-b', 'main'], repo);
+    run(['config', 'user.email', 'test@example.com'], repo);
+    run(['config', 'user.name', 'Test'], repo);
+    writeFileSync(join(repo, 'README.md'), 'hello\n');
+    run(['add', '.'], repo);
+    run(['commit', '-m', 'init'], repo);
+    const preMergeMainSha = gitSync(['rev-parse', 'main'], repo).stdout.trim();
+    const nodeId = 'wt-auto-drop-base-window';
+    const wt = createManagedWorktree(repo, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'feature.txt'), 'landed elsewhere\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'feature'], wt.path);
+    const branchSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+    // A manager fast-forwards main past this branch's own tip, exactly like
+    // the #327 positive case, so the branch proves clean-and-contained.
+    run(['merge', '--ff-only', branchSha], repo);
+    assert.equal(gitSync(['rev-parse', 'main'], repo).stdout.trim(), branchSha);
+    const proof = proveCleanEmptyManagedWorktree(wt);
+    assert.ok(proof !== null, 'the branch, now contained in the moved base, must prove droppable');
+    // Wrap `git worktree remove` — the call `autoDropCleanManagedWorktreeLocked`
+    // makes strictly AFTER its own live ancestry re-check and strictly BEFORE
+    // its ref-deletion transaction — to force-reset main back to its pre-merge
+    // tip right before the real removal runs. A sequential re-check placed
+    // anywhere before this point cannot see this rewrite; only binding the
+    // base's live value into the delete transaction itself can.
+    const wrapperDir = mkdtempSync(join(tmpdir(), 'crtr-git-wrapper-'));
+    const wrapperPath = join(wrapperDir, 'git');
+    const originalPath = process.env['PATH'] ?? '';
+    writeFileSync(wrapperPath, `#!/bin/sh
+if [ "$1" = "worktree" ] && [ "$2" = "remove" ] && [ "$3" = "${wt.path}" ]; then
+  PATH="$CRTR_TEST_REAL_PATH" git -C "${repo}" update-ref refs/heads/main "${preMergeMainSha}"
+fi
+PATH="$CRTR_TEST_REAL_PATH" exec git "$@"
+`);
+    chmodSync(wrapperPath, 0o755);
+    process.env['CRTR_TEST_REAL_PATH'] = originalPath;
+    process.env['PATH'] = `${wrapperDir}:${originalPath}`;
+    let result;
+    try {
+        result = autoDropCleanManagedWorktreeLocked(nodeId, wt, proof);
+    }
+    finally {
+        process.env['PATH'] = originalPath;
+        delete process.env['CRTR_TEST_REAL_PATH'];
+        rmSync(wrapperDir, { recursive: true, force: true });
+    }
+    assert.equal(result, null, 'a base rewritten strictly after the live ancestry check must still refuse the atomic delete');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'state must stay open — nothing may be marked safely dropped');
+    const refCheck = gitSync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], repo);
+    assert.equal(refCheck.status, 0, 'the source branch must be preserved');
+    assert.equal(refCheck.stdout.trim(), branchSha, 'the branch must still name the proven commit — the source commit remains reachable from this head');
+    rmSync(repo, { recursive: true, force: true });
+});
+test('close-landed atomic delete refuses when the base is force-reset between landing and the cleanup delete', () => {
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-close-base-window-'));
+    run(['init', '-b', 'main'], repo);
+    run(['config', 'user.email', 'test@example.com'], repo);
+    run(['config', 'user.name', 'Test'], repo);
+    writeFileSync(join(repo, 'README.md'), 'hello\n');
+    run(['add', '.'], repo);
+    run(['commit', '-m', 'init'], repo);
+    const preLandMainSha = gitSync(['rev-parse', 'main'], repo).stdout.trim();
+    const nodeId = 'wt-close-base-window';
+    const wt = createManagedWorktree(repo, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'feature.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'feature'], wt.path);
+    // Wrap `git worktree remove` — the call `bestEffortRemoveWorktreeCheckout`
+    // makes right after landing (fast-forwarding main to the new tip) but
+    // strictly before the atomic base+branch delete transaction — to reset main
+    // away from the just-landed tip in exactly that window.
+    const wrapperDir = mkdtempSync(join(tmpdir(), 'crtr-git-wrapper-'));
+    const wrapperPath = join(wrapperDir, 'git');
+    const originalPath = process.env['PATH'] ?? '';
+    writeFileSync(wrapperPath, `#!/bin/sh
+if [ "$1" = "worktree" ] && [ "$2" = "remove" ] && [ "$3" = "${wt.path}" ]; then
+  PATH="$CRTR_TEST_REAL_PATH" git -C "${repo}" update-ref refs/heads/main "${preLandMainSha}"
+fi
+PATH="$CRTR_TEST_REAL_PATH" exec git "$@"
+`);
+    chmodSync(wrapperPath, 0o755);
+    process.env['CRTR_TEST_REAL_PATH'] = originalPath;
+    process.env['PATH'] = `${wrapperDir}:${originalPath}`;
+    let result;
+    try {
+        result = closeManagedWorktree(nodeId);
+    }
+    finally {
+        process.env['PATH'] = originalPath;
+        delete process.env['CRTR_TEST_REAL_PATH'];
+        rmSync(wrapperDir, { recursive: true, force: true });
+    }
+    assert.equal(result.branch_deleted, false, 'a base reset in the window between landing and cleanup must refuse the branch delete');
+    assert.ok(result.branch_delete_error, 'the refusal must be surfaced as a non-fatal cleanup error');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'closed', 'the land already succeeded — a cleanup refusal must not un-close it');
+    const refCheck = gitSync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], repo);
+    assert.equal(refCheck.status, 0, 'the source branch must be preserved when cleanup refuses');
+    assert.equal(refCheck.stdout.trim(), result.landed_sha, 'the preserved branch must still name the landed commit — no orphaned landed commit');
+    rmSync(repo, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// Checkout-removal refusal: `bestEffortRemoveWorktreeCheckout` can report
+// `worktreeRemoved: false` (real Git refused `worktree remove` because a
+// file reappeared after the clean predicate ran). That refusal must itself
+// refuse the whole cleanup — never reach the low-level ref-deletion
+// transaction, which bypasses Git's own checked-out-branch protection.
+// ---------------------------------------------------------------------------
+test('auto-drop refuses and preserves the branch and checkout when checkout removal is refused after the clean predicate', async () => {
+    const { proveCleanEmptyManagedWorktree, autoDropCleanManagedWorktreeLocked } = await import('../worktree.js');
+    const nodeId = 'wt-auto-drop-removal-refused';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    const proof = proveCleanEmptyManagedWorktree(wt);
+    assert.ok(proof !== null, 'a fresh clean, zero-commit worktree must prove droppable');
+    // A file appears after the clean predicate ran — real `git worktree
+    // remove` (no --force) correctly refuses to remove a dirty checkout.
+    writeFileSync(join(wt.path, 'late-arrival.txt'), 'appeared after the clean predicate\n');
+    const result = autoDropCleanManagedWorktreeLocked(nodeId, wt, proof);
+    assert.equal(result, null, 'a checkout-removal refusal must refuse the whole drop, not just skip the branch delete');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'open', 'refused cleanup must never mutate managed-worktree state');
+    assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/${wt.branch}`], sourceDir).status, 0, 'the branch must never reach the ref-deletion transaction');
+    const list = gitSync(['worktree', 'list', '--porcelain'], sourceDir);
+    assert.ok(list.stdout.includes(wt.path), 'the checkout must remain registered and recoverable');
+    assert.ok(existsSync(join(wt.path, 'late-arrival.txt')), 'the live checkout, including its uncommitted file, must remain intact');
+});
+test('post-land cleanup timeout preserves the land and releases the repository lock', async () => {
+    const nodeId = 'wt-close-cleanup-timeout';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'cleanup-timeout-work.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'cleanup timeout work'], wt.path);
+    const baseBefore = gitSync(['rev-parse', 'main'], sourceDir).stdout.trim();
+    setWorktreeCleanupRunnerForTest((args, cwd, options) => {
+        if (args[0] === 'worktree' && args[1] === 'remove' && args[2] === wt.path) {
+            assert.equal(options.timeoutMs, 5_000, 'only post-land cleanup gets the finite deadline');
+            return { status: 1, stdout: '', stderr: '', timedOut: true };
+        }
+        if (args[0] === 'worktree' && args[1] === 'list') {
+            assert.equal(options.timeoutMs, 5_000, 'residual inspection gets the same finite deadline');
+            const inspection = gitSync(args, cwd, undefined, options);
+            return {
+                ...inspection,
+                // Branch identity is not checkout-validity: a switch/detach racing the
+                // timed-out remove still leaves a live registration that needs --force.
+                stdout: inspection.stdout.replace(`branch refs/heads/${wt.branch}`, 'branch refs/heads/externally-switched'),
+            };
+        }
+        return gitSync(args, cwd, undefined, options);
+    });
+    try {
+        const started = Date.now();
+        const result = closeManagedWorktree(nodeId);
+        const elapsed = Date.now() - started;
+        const cleanupDeadlineMs = 5_000;
+        const schedulingMarginMs = 500;
+        assert.ok(elapsed < cleanupDeadlineMs - schedulingMarginMs, `cleanup timeout must return promptly, took ${elapsed}ms`);
+        assert.notEqual(result.landed_sha, baseBefore, 'the land must contain a new commit');
+        assert.equal(gitSync(['rev-parse', 'main'], sourceDir).stdout.trim(), result.landed_sha, 'the base must contain the landed commit');
+        assert.equal(getNode(nodeId)?.managed_worktree?.state, 'closed', 'timeout must preserve the closed state');
+        assert.equal(result.worktree_removed, false);
+        assert.equal(result.branch_deleted, false);
+        assert.match(result.worktree_remove_error ?? '', /timed out/);
+        assert.match(result.worktree_remove_error ?? '', /git -C .* worktree remove --force/);
+        assert.doesNotMatch(result.worktree_remove_error ?? '', /worktree prune/, 'a valid registered checkout needs force-removal even if its branch changed');
+        assert.equal(gitSync(['show-ref', '--verify', '--quiet', `refs/heads/${wt.branch}`], sourceDir).status, 0, 'the source branch must remain reachable');
+        // The node that timed out must still be able to complete its own finalization
+        // from the recreated cwd; a different-node lock check alone is insufficient.
+        await push(nodeId, { kind: 'final', body: 'timed-out cleanup node finalized' });
+        assert.equal(getNode(nodeId)?.status, 'done', 'the timed-out node must finalize itself successfully');
+        assert.ok(getNode(nodeId)?.final_report, 'the timed-out node must record its canonical final');
+        // A second close must acquire the same repository lock and complete, proving
+        // the timed-out cleanup did not strand the lock around the finished land.
+        const followupId = 'wt-close-after-cleanup-timeout';
+        const followup = createManagedWorktree(sourceDir, followupId);
+        createNode(node(followupId, { cwd: followup.path, managed_worktree: followup }));
+        writeFileSync(join(followup.path, 'followup-work.txt'), 'followup\n');
+        run(['add', '.'], followup.path);
+        run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'followup work'], followup.path);
+        const followupResult = closeManagedWorktree(followupId);
+        assert.equal(followupResult.worktree_removed, true, 'subsequent finalization must complete');
+        assert.equal(getNode(followupId)?.managed_worktree?.state, 'closed');
+    }
+    finally {
+        setWorktreeCleanupRunnerForTest();
+    }
+});
+test('post-land cleanup timeout gives prune guidance for a tombstone residual', () => {
+    const nodeId = 'wt-close-cleanup-timeout-tombstone';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'cleanup-tombstone-work.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'cleanup tombstone work'], wt.path);
+    setWorktreeCleanupRunnerForTest((args, cwd, options) => {
+        if (args[0] === 'worktree' && args[1] === 'remove' && args[2] === wt.path) {
+            assert.equal(options.timeoutMs, 5_000, 'the timed-out remove gets the finite deadline');
+            rmSync(wt.path, { recursive: true, force: true });
+            mkdirSync(wt.path, { recursive: true });
+            return { status: 1, stdout: '', stderr: '', timedOut: true };
+        }
+        if (args[0] === 'worktree' && args[1] === 'list') {
+            assert.equal(options.timeoutMs, 5_000, 'residual inspection gets the same finite deadline');
+            const branchSha = gitSync(['rev-parse', `refs/heads/${wt.branch}`], sourceDir).stdout.trim();
+            return {
+                status: 0,
+                stdout: `worktree ${wt.path}\nHEAD ${branchSha}\nbranch refs/heads/${wt.branch}\nprunable gitdir file points to non-existent location\n`,
+                stderr: '',
+            };
+        }
+        return gitSync(args, cwd, undefined, options);
+    });
+    try {
+        const result = closeManagedWorktree(nodeId);
+        const guidance = result.worktree_remove_error ?? '';
+        assert.equal(result.worktree_removed, false);
+        assert.equal(result.branch_deleted, false);
+        assert.match(guidance, /git -C .* worktree prune/);
+        assert.match(guidance, /rm -rf/);
+        assert.doesNotMatch(guidance, /worktree remove --force/);
+        assert.ok(existsSync(wt.path), 'the tombstone residual must remain available for guided cleanup');
+    }
+    finally {
+        setWorktreeCleanupRunnerForTest();
+    }
+});
+test('close-landed never low-level-deletes the source branch when checkout removal is refused', () => {
+    const nodeId = 'wt-close-removal-refused';
+    const wt = createManagedWorktree(sourceDir, nodeId);
+    createNode(node(nodeId, { cwd: wt.path, managed_worktree: wt }));
+    writeFileSync(join(wt.path, 'removal-refused-work.txt'), 'work\n');
+    run(['add', '.'], wt.path);
+    run(['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'feature'], wt.path);
+    // Wrap `git worktree remove` to drop an untracked file into the checkout
+    // immediately before delegating to the real removal, so the real
+    // `git worktree remove` (no --force) refuses — exactly as it would if a
+    // process wrote into the checkout after close's own dirty check ran.
+    const wrapperDir = mkdtempSync(join(tmpdir(), 'crtr-git-wrapper-'));
+    const wrapperPath = join(wrapperDir, 'git');
+    const originalPath = process.env['PATH'] ?? '';
+    writeFileSync(wrapperPath, `#!/bin/sh
+if [ "$1" = "worktree" ] && [ "$2" = "remove" ] && [ "$3" = "${wt.path}" ]; then
+  echo "late arrival" > "${wt.path}/late-arrival.txt"
+fi
+PATH="$CRTR_TEST_REAL_PATH" exec git "$@"
+`);
+    chmodSync(wrapperPath, 0o755);
+    process.env['CRTR_TEST_REAL_PATH'] = originalPath;
+    process.env['PATH'] = `${wrapperDir}:${originalPath}`;
+    let result;
+    try {
+        result = closeManagedWorktree(nodeId);
+    }
+    finally {
+        process.env['PATH'] = originalPath;
+        delete process.env['CRTR_TEST_REAL_PATH'];
+        rmSync(wrapperDir, { recursive: true, force: true });
+    }
+    assert.equal(result.worktree_removed, false, 'the real checkout removal must genuinely refuse');
+    assert.equal(result.branch_deleted, false, 'a checkout-removal refusal must never be treated as safe to low-level-delete the branch');
+    assert.equal(getNode(nodeId)?.managed_worktree?.state, 'closed', 'the land already succeeded — a cleanup refusal must not un-close it');
+    const refCheck = gitSync(['rev-parse', '--verify', `refs/heads/${wt.branch}`], sourceDir);
+    assert.equal(refCheck.status, 0, 'the source branch must be preserved when its checkout could not be removed');
+    assert.equal(refCheck.stdout.trim(), result.landed_sha, 'the preserved branch must still name the landed commit');
+});