@north-light/crouter 0.3.226 → 0.3.228

package/dist/core/__tests__/{serial → integration}/spawn-root.test.js

@@ -3,7 +3,7 @@
 // only — no subscription wires back to the spawner.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createServer } from 'node:net';
@@ -17,6 +17,8 @@ import { readGoal } from '../../runtime/kickoff.js';
 import { spawnChild, resolveSpawner } from '../../runtime/spawn.js';
 import { headlessBrokerHost } from '../../runtime/host.js';
 import { recordFault } from '../../runtime/fault.js';
+import { piSessionsRoot } from '../../runtime/pi-vendored.js';
+import { emptyContextExposureState, exposureTarget, loadContextExposureState, registerExposure, saveContextExposureState, } from '../../substrate/injected-store.js';
 import { ROOT_PROFILE_ID } from '../../profiles/manifest.js';
 let home;
 function spawner(id) {
@@ -113,6 +115,107 @@ test('spawnChild crashes the node when launch/preflight throws', async () => {
         rmSync(home, { recursive: true, force: true });
     }
 });
+test('fork spawn resolves path and UUID provenance to the same transcript-only exposure seed', async () => {
+    const previousHome = process.env['HOME'];
+    const previousPiDir = process.env['PI_CODING_AGENT_DIR'];
+    const previousNodeId = process.env['CRTR_NODE_ID'];
+    const previousTmux = process.env['TMUX'];
+    const previousTmuxPane = process.env['TMUX_PANE'];
+    const localHome = mkdtempSync(join(tmpdir(), 'crtr-fork-seed-home-'));
+    const localCwd = mkdtempSync(join(tmpdir(), 'crtr-fork-seed-cwd-'));
+    const originalLaunch = headlessBrokerHost.launch;
+    const launched = [];
+    try {
+        process.env['HOME'] = localHome;
+        process.env['PI_CODING_AGENT_DIR'] = join(localHome, 'pi-agent');
+        process.env['CRTR_NODE_ID'] = 'fork-source';
+        delete process.env['TMUX'];
+        delete process.env['TMUX_PANE'];
+        const sessionId = '12345678-1234-4234-8234-123456789abc';
+        const sourceFile = join(piSessionsRoot(), 'source-project', `2026-08-19T00-00-00-000Z_${sessionId}.jsonl`);
+        mkdirSync(join(piSessionsRoot(), 'source-project'), { recursive: true });
+        writeFileSync(sourceFile, `${JSON.stringify({
+            type: 'session',
+            version: 3,
+            id: sessionId,
+            timestamp: new Date().toISOString(),
+            cwd: localCwd,
+        })}\n`);
+        createNode({
+            ...spawner('fork-source'),
+            cwd: localCwd,
+            pi_session_id: sessionId,
+            pi_session_file: sourceFile,
+        });
+        const canonicalSourceFile = getNode('fork-source').pi_session_file;
+        const sourceExposure = emptyContextExposureState();
+        registerExposure(exposureTarget(sourceExposure, 'system'), 'source-system', 'content');
+        registerExposure(exposureTarget(sourceExposure, 'transcript'), 'source-transcript', 'preview');
+        saveContextExposureState('fork-source', sourceExposure);
+        headlessBrokerHost.launch = (nodeId, inv) => {
+            launched.push({ nodeId, argv: inv.argv });
+            return { pid: process.pid, exited: new Promise(() => { }) };
+        };
+        const byPath = await spawnChild({
+            kind: 'developer',
+            cwd: localCwd,
+            root: true,
+            readiness: 'launch',
+            nodeId: 'fork-by-path',
+            prompt: 'path fork',
+            forkFrom: sourceFile,
+        });
+        const byUuid = await spawnChild({
+            kind: 'developer',
+            cwd: localCwd,
+            root: true,
+            readiness: 'launch',
+            nodeId: 'fork-by-uuid',
+            prompt: 'uuid fork',
+            forkFrom: sessionId,
+        });
+        for (const [result, rawOperand] of [[byPath, sourceFile], [byUuid, sessionId]]) {
+            const meta = getNode(result.node.node_id);
+            assert.equal(meta.fork_from, rawOperand);
+            assert.equal(meta.fork_source_file, canonicalSourceFile);
+            const exposure = loadContextExposureState(meta.node_id);
+            assert.deepEqual(exposure.exposures.get('source-transcript'), { transcript: 2 });
+            assert.equal(exposure.exposures.has('source-system'), false);
+            assert.equal(exposure.preferenceSnapshot, null);
+        }
+        assert.equal(launched.length, 2);
+        for (const launch of launched) {
+            const forkIndex = launch.argv.indexOf('--fork');
+            assert.ok(forkIndex >= 0, `${launch.nodeId} launches through Pi's fork seam`);
+            assert.equal(launch.argv[forkIndex + 1], canonicalSourceFile);
+        }
+    }
+    finally {
+        headlessBrokerHost.launch = originalLaunch;
+        if (previousHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = previousHome;
+        if (previousPiDir === undefined)
+            delete process.env['PI_CODING_AGENT_DIR'];
+        else
+            process.env['PI_CODING_AGENT_DIR'] = previousPiDir;
+        if (previousNodeId === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = previousNodeId;
+        if (previousTmux === undefined)
+            delete process.env['TMUX'];
+        else
+            process.env['TMUX'] = previousTmux;
+        if (previousTmuxPane === undefined)
+            delete process.env['TMUX_PANE'];
+        else
+            process.env['TMUX_PANE'] = previousTmuxPane;
+        rmSync(localHome, { recursive: true, force: true });
+        rmSync(localCwd, { recursive: true, force: true });
+    }
+});
 test('spawnChild: a root from a shell gets the stable root profile id', async () => {
     const previousHome = process.env.HOME;
     const previousNodeId = process.env.CRTR_NODE_ID;

package/dist/core/__tests__/integration/subscription-delivery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/{serial → integration}/subscription-delivery.test.js

@@ -1,4 +1,4 @@
-// Run with: npm run test:serial
+// Run with: npm run test:integration
 //
 // THE DAEMON WAKE HALF of delivery-vs-wake, on a graph >=2 levels deep. Routing
 // itself (active → inbox.jsonl, passive → passive.jsonl) is owned by

package/dist/core/__tests__/integration/tmux-surface.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/{serial → integration}/tmux-surface.test.js

@@ -1,4 +1,4 @@
-// Run with: npm run test:serial
+// Run with: npm run test:integration
 //
 // STEP 2 of the placement/focus migration: guards on the tmux Surface (driver).
 //

package/dist/core/__tests__/integration/worktree-land.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/integration/worktree-land.test.js

@@ -0,0 +1,400 @@
+// Managed worktrees: create, and the land/close half — base-ref recording,
+// rebase-onto-captured-SHA, the dirty gate, and what close is allowed to touch.
+// Split from its reap half (worktree-reap.test.ts) only so the two run as two
+// parallel files; they share the fixture shape, not state.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, existsSync, 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 { createManagedWorktree, closeManagedWorktree, managedWorktreePath, rollbackManagedWorktree } 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 #710: close lands from a live caller, so it must preserve the
+// caller checkout rather than starting Git's recursive removal beneath it.
+test('closeManagedWorktree leaves the active caller checkout intact with named deferred cleanup', () => {
+    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, false);
+    assert.match(result.worktree_remove_error ?? '', /cleanup pending/);
+    assert.ok(existsSync(join(wt.path, 'README.md')), 'the caller checkout keeps its tracked files');
+    assert.ok(statSync(wt.path).isDirectory(), 'the caller cwd remains a directory');
+    const list = gitSync(['worktree', 'list', '--porcelain'], sourceDir);
+    assert.ok(list.stdout.includes(wt.path), 'Git keeps the intact caller checkout registered');
+    const meta = getNode(nodeId);
+    assert.equal(meta?.managed_worktree?.state, 'closed');
+    assert.equal(meta?.managed_worktree?.cleanup, 'pending');
+    assert.equal(meta?.cwd, wt.repo_root, 'a later revive uses the durable base checkout');
+});
+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, false);
+    assert.match(result.worktree_remove_error ?? '', /cleanup pending/);
+});
+// 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', 'tracked.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', 'tracked.md'), 'edited tracked memory doc\n');
+    const editStatus = gitSync(['status', '--porcelain'], editWt.path).stdout;
+    assert.ok(editStatus.includes('M .crouter/memory/tracked.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 });
+});

package/dist/core/__tests__/integration/worktree-reap.test.d.ts

@@ -0,0 +1 @@
+export {};