@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/monorepo/scripts/backlog/slots.test.ts

@@ -0,0 +1,1179 @@
+/**
+ * TDD spec for `scripts/backlog/slots.ts`.
+ *
+ * Runner: `node --import tsx --test scripts/backlog/slots.test.ts`
+ *
+ * Part 1 (task 3.5/3.6) — slot/lock lifecycle: acquire, heartbeat refresh, dead-PID detection,
+ * expired-TTL detection, release, double-acquire refused, and lane capacity caps (1 local, 2
+ * frontier). Implements `specs/backlog-task-dispatcher/spec.md` — "Lane capacity caps".
+ *
+ * Part 2 (task 3.7/3.8) — branch resolution and slot preparation (reset/clean/fetch/checkout, via
+ * an injectable git runner so no real repo is touched). Implements "Slot acquisition and branch
+ * resolution".
+ *
+ * Filesystem tests use `node:fs` temp dirs under `os.tmpdir()` — never the repo itself.
+ */
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, it } from 'node:test';
+import {
+  acquireSlot,
+  computeLockfileHash,
+  createRegistryLock,
+  detachSlot,
+  isLockAlive,
+  lockFilePath,
+  needsCliInstall,
+  needsInstall,
+  prepareSlot,
+  provisionCliDependencies,
+  provisionSlot,
+  readLock,
+  refreshHeartbeat,
+  releaseHeldSlotEntries,
+  releaseLock,
+  releaseSlot,
+  releaseSlotAndDetach,
+  releaseSlotEntries,
+  resolveBranch,
+  slotPathForTask,
+  updateSlots,
+  writeLock,
+} from './slots.js';
+import {
+  DEFAULT_DISPATCH_LIMITS,
+  LANE,
+  type DispatchLock,
+  type SlotInfo,
+  type SlotRegistry,
+} from './types.js';
+
+const freeSlot = (name: string): SlotInfo => ({
+  name,
+  path: `/slots/${name}`,
+  lane: null,
+  taskId: null,
+  pid: null,
+  lockfileHash: null,
+});
+
+const threeFreeSlots = (): SlotInfo[] => [
+  freeSlot('dispatch-a'),
+  freeSlot('dispatch-b'),
+  freeSlot('dispatch-c'),
+];
+
+// ── acquireSlot ────────────────────────────────────────────────────────────────
+
+describe('acquireSlot', () => {
+  it('acquires a free slot for the requested lane', () => {
+    const result = acquireSlot(LANE.LOCAL, 'T-1', { slots: threeFreeSlots() });
+    assert.equal(result.kind, 'acquired');
+    if (result.kind === 'acquired') {
+      assert.equal(result.slot.taskId, 'T-1');
+      assert.equal(result.slot.lane, LANE.LOCAL);
+    }
+  });
+
+  it('refuses a double-acquire for a task that already holds a slot', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.LOCAL, taskId: 'T-1', pid: 111 };
+    const result = acquireSlot(LANE.LOCAL, 'T-1', { slots });
+    assert.equal(result.kind, 'already-locked');
+  });
+
+  it('caps the local lane at 1 concurrent slot', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.LOCAL, taskId: 'T-9', pid: 111 };
+    const result = acquireSlot(LANE.LOCAL, 'T-2', { slots });
+    assert.equal(result.kind, 'no-free-slot');
+  });
+
+  it('caps the frontier lane at 2 concurrent slots', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.FRONTIER, taskId: 'T-8', pid: 1 };
+    slots[1] = { ...slots[1], lane: LANE.FRONTIER, taskId: 'T-9', pid: 2 };
+    const result = acquireSlot(LANE.FRONTIER, 'T-10', { slots });
+    assert.equal(result.kind, 'no-free-slot');
+  });
+
+  it('allows a second frontier task while the local lane is untouched', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.FRONTIER, taskId: 'T-8', pid: 1 };
+    const result = acquireSlot(LANE.FRONTIER, 'T-9', { slots });
+    assert.equal(result.kind, 'acquired');
+  });
+
+  // J4: the cap is `lanes.json`'s `maxParallel`, threaded in — not a module constant.
+  it('reads the per-lane cap from the injected capacity', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.LOCAL, taskId: 'T-9', pid: 111 };
+    const raised = { ...DEFAULT_DISPATCH_LIMITS.capacity, local: 2 };
+    assert.equal(acquireSlot(LANE.LOCAL, 'T-2', { slots }, raised).kind, 'acquired');
+  });
+});
+
+describe('acquireSlot — a slot held for push recovery', () => {
+  it('is never handed to a new task: it still holds the only copy of unpushed work', () => {
+    const slots = threeFreeSlots().map((slot) => ({ ...slot, heldForRecovery: true }));
+    assert.deepEqual(acquireSlot(LANE.LOCAL, 'T-9', { slots }), { kind: 'no-free-slot' });
+  });
+
+  it('still picks a free slot alongside one held for recovery', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], heldForRecovery: true };
+    const result = acquireSlot(LANE.LOCAL, 'T-9', { slots });
+    assert.equal(result.kind, 'acquired');
+    assert.equal(result.kind === 'acquired' ? result.slot.name : null, 'dispatch-b');
+  });
+});
+
+// ── releaseSlot ────────────────────────────────────────────────────────────────
+
+describe('releaseSlot', () => {
+  it('frees the slot holding the task, preserving its lockfileHash', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.LOCAL, taskId: 'T-1', pid: 111, lockfileHash: 'abc123' };
+    const result = releaseSlot('T-1', { slots });
+    const released = result.slots.find((slot) => slot.name === 'dispatch-a');
+    assert.ok(released);
+    assert.equal(released?.taskId, null);
+    assert.equal(released?.lane, null);
+    assert.equal(released?.pid, null);
+    assert.equal(released?.lockfileHash, 'abc123');
+  });
+
+  it('is a no-op when no slot holds the given task', () => {
+    const slots = threeFreeSlots();
+    const result = releaseSlot('T-999', { slots });
+    assert.deepEqual(result.slots, slots);
+  });
+
+  // H4: the maintenance sweep used to carry its own copy of this transform. One release, one
+  // definition — a divergence there means "released" means two different things on two paths.
+  it('exposes the entry-level transform maintenance releases through, byte for byte', () => {
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.LOCAL, taskId: 'T-1', pid: 111, lockfileHash: 'abc123' };
+    assert.deepEqual(releaseSlotEntries(slots, 'T-1'), releaseSlot('T-1', { slots }).slots);
+  });
+});
+
+// ── N5: the manual rescue transform behind `--release-slot` ────────────────────
+
+describe('releaseHeldSlotEntries', () => {
+  const heldSlot = (): SlotInfo[] => [
+    {
+      name: 'dispatch-a',
+      path: '/slots/dispatch-a',
+      lane: LANE.LOCAL,
+      taskId: 'T-1',
+      pid: 111,
+      lockfileHash: 'abc123',
+      heldForRecovery: true,
+      recoveryAttempts: 3,
+    },
+    freeSlot('dispatch-b'),
+  ];
+
+  // The exhausted-recovery hold is the one release `releaseSlotEntries` deliberately does NOT
+  // perform (only a successful push retry clears `heldForRecovery`), which left a rescued slot out
+  // of the pool with no documented way back in.
+  it('clears the hold, the retry counter and the task binding, keeping the install hash', () => {
+    const [released] = releaseHeldSlotEntries(heldSlot(), 'dispatch-a');
+
+    assert.equal(released.heldForRecovery, false);
+    assert.equal(released.recoveryAttempts, 0);
+    assert.equal(released.taskId, null);
+    assert.equal(released.lane, null);
+    assert.equal(released.pid, null);
+    assert.equal(released.lockfileHash, 'abc123');
+  });
+
+  it('touches no other slot', () => {
+    const slots = heldSlot();
+    assert.deepEqual(releaseHeldSlotEntries(slots, 'dispatch-a')[1], slots[1]);
+  });
+
+  it('is a no-op when the name matches no slot', () => {
+    const slots = heldSlot();
+    assert.deepEqual(releaseHeldSlotEntries(slots, 'dispatch-zzz'), slots);
+  });
+});
+
+// ── isLockAlive ──────────────────────────────────────────────────────────────
+
+describe('isLockAlive', () => {
+  const baseLock: DispatchLock = {
+    taskId: 'T-1',
+    slot: 'dispatch-a',
+    pid: 4242,
+    startedAt: '2026-09-06T10:00:00.000Z',
+    heartbeatAt: '2026-09-06T10:05:00.000Z',
+    lane: LANE.LOCAL,
+    attempt: 1,
+    branch: 'task/T-1',
+  };
+  const now = Date.parse('2026-09-06T10:06:00.000Z'); // 1 min after heartbeat
+  const ttlMs = 5 * 60 * 1000; // 5 min
+
+  it('is alive when the process check passes and the heartbeat is within TTL', () => {
+    assert.equal(
+      isLockAlive(baseLock, now, ttlMs, () => true),
+      true,
+    );
+  });
+
+  it('is dead when process.kill(pid, 0) throws (dead PID)', () => {
+    assert.equal(
+      isLockAlive(baseLock, now, ttlMs, () => false),
+      false,
+    );
+  });
+
+  it('is dead when the heartbeat is older than the TTL, even if the process is alive', () => {
+    const staleNow = Date.parse('2026-09-06T10:20:00.000Z'); // 15 min after heartbeat
+    assert.equal(
+      isLockAlive(baseLock, staleNow, ttlMs, () => true),
+      false,
+    );
+  });
+});
+
+// ── Lock file read/write/release round trip ───────────────────────────────────
+
+describe('lock file persistence', () => {
+  it('round-trips a lock through write/read/release', () => {
+    const dispatchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-dispatch-'));
+    const lock: DispatchLock = {
+      taskId: 'T-7',
+      slot: 'dispatch-b',
+      pid: 555,
+      startedAt: '2026-09-06T09:00:00.000Z',
+      heartbeatAt: '2026-09-06T09:00:00.000Z',
+      lane: LANE.FRONTIER,
+      attempt: 1,
+      branch: 'task/T-7',
+    };
+
+    assert.equal(readLock(dispatchDir, 'T-7'), null);
+
+    writeLock(dispatchDir, lock);
+    assert.ok(fs.existsSync(lockFilePath(dispatchDir, 'T-7')));
+    assert.deepEqual(readLock(dispatchDir, 'T-7'), lock);
+
+    releaseLock(dispatchDir, 'T-7');
+    assert.equal(readLock(dispatchDir, 'T-7'), null);
+  });
+
+  // The lock's `pid` is the RECONCILER's own (`entry.ts` writes `currentPid`), and only that process
+  // beats this heartbeat — so the fixture uses this process's pid, which is what the owner check
+  // added in N7 compares against.
+  const heartbeatLock = (pid = process.pid): DispatchLock => ({
+    taskId: 'T-3',
+    slot: 'dispatch-a',
+    pid,
+    startedAt: '2026-09-06T09:00:00.000Z',
+    heartbeatAt: '2026-09-06T09:00:00.000Z',
+    lane: LANE.LOCAL,
+    attempt: 1,
+    branch: 'task/T-3',
+  });
+
+  it('refreshHeartbeat updates only heartbeatAt, in place on disk', () => {
+    const dispatchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-dispatch-'));
+    writeLock(dispatchDir, heartbeatLock());
+
+    refreshHeartbeat(dispatchDir, 'T-3', '2026-09-06T09:10:00.000Z');
+
+    const reread = readLock(dispatchDir, 'T-3');
+    assert.equal(reread?.heartbeatAt, '2026-09-06T09:10:00.000Z');
+    assert.equal(reread?.startedAt, '2026-09-06T09:00:00.000Z');
+    assert.equal(reread?.pid, process.pid);
+  });
+
+  // N7: the heartbeat used to read the lock and then write it back. A maintenance sweep that
+  // declared the worker dead and REMOVED the lock in between had it recreated by the next
+  // heartbeat — resurrecting a lock for a slot already handed to another task, so the sweep never
+  // reclaimed it again. The read now happens inside the exclusive critical section.
+  it('never recreates a lock removed between the read and the write', () => {
+    const dispatchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-dispatch-'));
+    writeLock(dispatchDir, heartbeatLock());
+
+    refreshHeartbeat(dispatchDir, 'T-3', '2026-09-06T09:10:00.000Z', {
+      // Stands in for the sweep: the lock is gone by the time the critical section runs.
+      withLock: (body) => {
+        releaseLock(dispatchDir, 'T-3');
+        return body();
+      },
+    });
+
+    assert.equal(readLock(dispatchDir, 'T-3'), null);
+  });
+
+  // It runs on an UNREF'd `setInterval` inside the reconciler (`attempt.ts`), so a throw here is an
+  // uncaught exception that kills the dispatcher mid-worker. A missed beat costs nothing: the TTL is
+  // 10 minutes and the tick is 30 seconds.
+  it('never throws when the exclusive lock cannot be taken — a missed beat beats a dead pass', () => {
+    const dispatchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-dispatch-'));
+    writeLock(dispatchDir, heartbeatLock());
+
+    assert.doesNotThrow(() =>
+      refreshHeartbeat(dispatchDir, 'T-3', '2026-09-06T09:10:00.000Z', {
+        withLock: () => {
+          throw new Error('could not acquire the lock within 5000ms');
+        },
+      }),
+    );
+    assert.equal(readLock(dispatchDir, 'T-3')?.heartbeatAt, '2026-09-06T09:00:00.000Z');
+  });
+
+  // P4 (round 9): the mutex was ONE-SIDED. N7 moved the heartbeat's read inside the critical
+  // section, but the other participants — the sweep's `releaseLock` and the launch's `writeLock` —
+  // never took that lock at all, so "exclusive" only excluded a second heartbeat. A remover running
+  // while the heartbeat sits between its read and its write still resurrects the lock; the read
+  // being inside the section is worth nothing if the writer outside it never waits.
+  //
+  // Driven through the REAL `createRegistryLock` on the real lock path, so the contention is the
+  // one production has: the heartbeat holds the lock, the remover asks for it and is refused.
+  // The intruder runs INSIDE the heartbeat's real critical section, injected as a wrapper around
+  // the real lock rather than through a hook in production code: the heartbeat holds the lock, the
+  // intruder asks the same lock for the same path with a 50 ms patience, and is turned away.
+  function whileHeartbeatHoldsTheLock(dispatchDir: string, intruder: () => void): unknown {
+    const lockPath = `${lockFilePath(dispatchDir, 'T-3')}.lock`;
+    const held = createRegistryLock(lockPath, { maxWaitMs: 50, retryMs: 5 });
+    let refused: unknown = null;
+    refreshHeartbeat(dispatchDir, 'T-3', '2026-09-06T09:10:00.000Z', {
+      withLock: (body) =>
+        held(() => {
+          try {
+            intruder();
+          } catch (error) {
+            refused = error;
+          }
+          return body();
+        }),
+    });
+    return refused;
+  }
+
+  const impatientLock = (dispatchDir: string): (<T>(body: () => T) => T) =>
+    createRegistryLock(`${lockFilePath(dispatchDir, 'T-3')}.lock`, { maxWaitMs: 50, retryMs: 5 });
+
+  it('releaseLock takes the per-task lock, so it cannot interleave with a live heartbeat', () => {
+    const dispatchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-dispatch-'));
+    writeLock(dispatchDir, heartbeatLock());
+
+    const refused = whileHeartbeatHoldsTheLock(dispatchDir, () =>
+      releaseLock(dispatchDir, 'T-3', { withLock: impatientLock(dispatchDir) }),
+    );
+
+    assert.ok(refused, 'a remover that participates in the mutex cannot delete the lock mid-beat');
+    assert.equal(readLock(dispatchDir, 'T-3')?.heartbeatAt, '2026-09-06T09:10:00.000Z');
+  });
+
+  it('writeLock takes the per-task lock too — the launch write is the other participant', () => {
+    const dispatchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-dispatch-'));
+    writeLock(dispatchDir, heartbeatLock());
+
+    const refused = whileHeartbeatHoldsTheLock(dispatchDir, () =>
+      writeLock(
+        dispatchDir,
+        { ...heartbeatLock(), workerPid: 999 },
+        { withLock: impatientLock(dispatchDir) },
+      ),
+    );
+
+    assert.ok(
+      refused,
+      'a writer that participates in the mutex cannot overwrite the lock mid-beat',
+    );
+    assert.equal(readLock(dispatchDir, 'T-3')?.workerPid, undefined);
+  });
+
+  it('leaves a lock alone once it names another process — a successor owns the slot now', () => {
+    const dispatchDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-dispatch-'));
+    writeLock(dispatchDir, heartbeatLock(process.pid + 1));
+
+    refreshHeartbeat(dispatchDir, 'T-3', '2026-09-06T09:10:00.000Z');
+
+    assert.equal(readLock(dispatchDir, 'T-3')?.heartbeatAt, '2026-09-06T09:00:00.000Z');
+  });
+});
+
+// ── Install check (lockfile hash) ─────────────────────────────────────────────
+
+describe('needsInstall / computeLockfileHash', () => {
+  it('needsInstall is true when the slot hash differs from the current hash', () => {
+    const slot: SlotInfo = { ...freeSlot('dispatch-a'), lockfileHash: 'old-hash' };
+    assert.equal(needsInstall(slot, 'new-hash'), true);
+  });
+
+  it('needsInstall is false when the slot hash matches the current hash', () => {
+    const slot: SlotInfo = { ...freeSlot('dispatch-a'), lockfileHash: 'same-hash' };
+    assert.equal(needsInstall(slot, 'same-hash'), false);
+  });
+
+  it('needsInstall is true when the slot has never installed (null hash)', () => {
+    const slot: SlotInfo = { ...freeSlot('dispatch-a'), lockfileHash: null };
+    assert.equal(needsInstall(slot, 'any-hash'), true);
+  });
+
+  it('computeLockfileHash is deterministic for identical content', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-lockfile-'));
+    const file = path.join(dir, 'pnpm-lock.yaml');
+    fs.writeFileSync(file, 'lockfileVersion: 9.0\npackages: {}\n');
+    const hashA = computeLockfileHash(file);
+    const hashB = computeLockfileHash(file);
+    assert.equal(hashA, hashB);
+  });
+
+  it('computeLockfileHash differs for different content', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'backlog-lockfile-'));
+    const fileA = path.join(dir, 'a.yaml');
+    const fileB = path.join(dir, 'b.yaml');
+    fs.writeFileSync(fileA, 'packages: {}\n');
+    fs.writeFileSync(fileB, 'packages: { foo: 1 }\n');
+    assert.notEqual(computeLockfileHash(fileA), computeLockfileHash(fileB));
+  });
+});
+
+// ── Branch resolution (task 3.7) ──────────────────────────────────────────────
+
+describe('resolveBranch', () => {
+  it('a retry checks out the existing remote task/<id> branch', () => {
+    const result = resolveBranch({
+      taskId: 'T-12',
+      remoteBranches: ['main', 'task/T-12'],
+    });
+    assert.deepEqual(result, { ref: 'task/T-12', base: 'existing' });
+  });
+
+  it("a first-time subtask branches from its parent's branch", () => {
+    const result = resolveBranch({
+      taskId: 'T-13',
+      parentId: 'T-12',
+      remoteBranches: ['main', 'task/T-12'],
+    });
+    assert.deepEqual(result, { ref: 'task/T-13', base: 'origin/task/T-12' });
+  });
+
+  it('a first-time non-subtask branches from origin/main, never from the slot local main', () => {
+    const result = resolveBranch({
+      taskId: 'T-14',
+      remoteBranches: ['main'],
+    });
+    assert.deepEqual(result, { ref: 'task/T-14', base: 'origin/main' });
+  });
+
+  // G5 (superseded by T-14, 2026-09-08): the parent's branch only exists on the remote once the
+  // parent itself has been dispatched, and branching from a ref that is not there fails the
+  // checkout — which used to take the whole pass down AFTER the slot was already marked busy. This
+  // function used to paper over that by falling back to `origin/main` silently. T-4.1 measured the
+  // real cost of that fallback: `close.ts` never adopted the same fallback, so a subtask's dispatch
+  // and its close disagreed on its base branch, and the close failed `scope-check-failed` diffing
+  // against a ref that was never created. `guards.ts`'s pre-launch guard
+  // (`checkParentBranchOnRemote`) now refuses that dispatch before ANY slot is taken, so a missing
+  // parent branch reaching this function is a programming error — it throws instead of silently
+  // substituting a different branch (see `resolveTaskBase`'s doc comment in `guards.ts` for the
+  // shared rule this function now consults rather than reimplementing).
+  it('throws instead of silently falling back when the parent branch is not on the remote', () => {
+    assert.throws(
+      () =>
+        resolveBranch({
+          taskId: 'T-13',
+          parentId: 'T-12',
+          remoteBranches: ['main'],
+        }),
+      /T-13.*parent branch.*origin\/task\/T-12/s,
+    );
+  });
+
+  // Fix round B5: this throw is the LOUDEST failure in the system (guard 4b should have refused the
+  // dispatch before a slot was ever taken, per `resolveTaskBase`'s own doc comment — reaching this
+  // point is already a programming error) and `resolveTaskBase` computed `candidates` two lines
+  // above it, yet the message used to print only `origin/<branch>`, dropping them on the floor. A
+  // person debugging this crash from a log has nothing else to go on.
+  it('names the remote candidates the resolution already found, not just the branch it tried', () => {
+    assert.throws(
+      () =>
+        resolveBranch({
+          taskId: 'T-13',
+          parentId: 'T-12',
+          remoteBranches: ['main', 'wip-T-12-rescue'],
+        }),
+      /wip-T-12-rescue/,
+    );
+  });
+
+  it('branches off the parent branch with no throw when it IS on the remote', () => {
+    const result = resolveBranch({
+      taskId: 'T-13',
+      parentId: 'T-12',
+      remoteBranches: ['main', 'task/T-12'],
+    });
+    assert.equal(result.base, 'origin/task/T-12');
+  });
+
+});
+
+// ── G3: which directory holds a task's work ───────────────────────────────────
+
+describe('slotPathForTask', () => {
+  const registry = {
+    slots: [
+      {
+        name: 'dispatch-a',
+        path: '/slots/a',
+        lane: LANE.LOCAL,
+        taskId: 'T-1',
+        pid: 1,
+        lockfileHash: null,
+      },
+      {
+        name: 'dispatch-b',
+        path: '/slots/b',
+        lane: null,
+        taskId: null,
+        pid: null,
+        lockfileHash: null,
+      },
+    ],
+  };
+
+  it('returns the path of the slot currently holding the task', () => {
+    assert.equal(slotPathForTask(registry, 'T-1'), '/slots/a');
+  });
+
+  // Falling back to the main checkout made every close runner operate on the developer's own
+  // working tree: a WIP `git add -A`, a scope diff and a `gh pr create` against real work in
+  // progress. "No slot" has to be an answer the caller must handle, not a silent default.
+  it('returns null when no slot holds the task, never a fallback directory', () => {
+    assert.equal(slotPathForTask(registry, 'T-99'), null);
+  });
+});
+
+// ── G2: every registry write re-reads under an exclusive lock ─────────────────
+
+describe('updateSlots', () => {
+  function memoryStore(initial: SlotRegistry) {
+    let current = initial;
+    const locked: boolean[] = [];
+    return {
+      get current() {
+        return current;
+      },
+      locked,
+      store: {
+        readSlots: () => current,
+        writeSlots: (registry: SlotRegistry) => {
+          current = registry;
+        },
+        withLock: <T>(body: () => T): T => {
+          locked.push(true);
+          try {
+            return body();
+          } finally {
+            locked.push(false);
+          }
+        },
+      },
+    };
+  }
+
+  it('re-reads the registry inside the mutation, so a concurrent per-slot change survives', () => {
+    const held = memoryStore({
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/a',
+          lane: null,
+          taskId: null,
+          pid: null,
+          lockfileHash: null,
+        },
+        {
+          name: 'dispatch-b',
+          path: '/slots/b',
+          lane: null,
+          taskId: null,
+          pid: null,
+          lockfileHash: null,
+        },
+      ],
+    });
+
+    // Two passes each hold a stale snapshot from before the other wrote. Both mutations must land.
+    updateSlots(held.store, (current) => ({
+      slots: current.slots.map((slot) =>
+        slot.name === 'dispatch-a' ? { ...slot, taskId: 'T-1' } : slot,
+      ),
+    }));
+    updateSlots(held.store, (current) => ({
+      slots: current.slots.map((slot) =>
+        slot.name === 'dispatch-b' ? { ...slot, heldForRecovery: true } : slot,
+      ),
+    }));
+
+    assert.equal(held.current.slots[0].taskId, 'T-1');
+    assert.equal(held.current.slots[1].heldForRecovery, true);
+  });
+
+  it('runs the read-mutate-write triple inside the lock, and returns what it wrote', () => {
+    const held = memoryStore({ slots: [] });
+    const result = updateSlots(held.store, () => ({ slots: [] }));
+    assert.deepEqual(held.locked, [true, false]);
+    assert.deepEqual(result, { slots: [] });
+  });
+});
+
+describe('createRegistryLock', () => {
+  it('releases the lock file when the body throws, so the next pass is not deadlocked', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slots-lock-'));
+    const lockPath = path.join(dir, 'slots.lock');
+    const withLock = createRegistryLock(lockPath);
+
+    assert.throws(() =>
+      withLock(() => {
+        throw new Error('write failed');
+      }),
+    );
+    assert.equal(fs.existsSync(lockPath), false);
+    assert.equal(
+      withLock(() => 'second pass ran'),
+      'second pass ran',
+    );
+  });
+
+  it('breaks a lock older than the stale threshold instead of waiting forever on a dead pass', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slots-lock-'));
+    const lockPath = path.join(dir, 'slots.lock');
+    fs.writeFileSync(lockPath, 'stale');
+    const ancient = Date.now() - 60_000;
+    fs.utimesSync(lockPath, ancient / 1000, ancient / 1000);
+
+    const withLock = createRegistryLock(lockPath, { staleMs: 30_000 });
+    assert.equal(
+      withLock(() => 'ran'),
+      'ran',
+    );
+  });
+
+  // H10: a pass whose lock was broken as stale must not delete the lock its successor now holds —
+  // that hands the registry to two writers at once, which is the exact race the lock exists for.
+  it('removes only its OWN lock: a lock stolen mid-body is left for whoever holds it now', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slots-lock-'));
+    const lockPath = path.join(dir, 'slots.lock');
+    const withLock = createRegistryLock(lockPath);
+
+    withLock(() => {
+      // Another pass broke this lock as stale and took it: same path, its own nonce inside.
+      fs.writeFileSync(lockPath, 'another-pass-nonce');
+    });
+
+    assert.equal(fs.existsSync(lockPath), true, "the successor's lock must survive this release");
+    assert.equal(fs.readFileSync(lockPath, 'utf8'), 'another-pass-nonce');
+  });
+
+  it('writes an owner nonce into the lock file, so ownership is checkable at release time', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slots-lock-'));
+    const lockPath = path.join(dir, 'slots.lock');
+    let contents = '';
+
+    createRegistryLock(lockPath)(() => {
+      contents = fs.readFileSync(lockPath, 'utf8');
+    });
+
+    assert.match(
+      contents,
+      new RegExp(`^${process.pid}-\\w+$`),
+      'the nonce must name the owning pid',
+    );
+  });
+
+  it('gives up rather than clobbering a lock that is still fresh', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'slots-lock-'));
+    const lockPath = path.join(dir, 'slots.lock');
+    fs.writeFileSync(lockPath, 'fresh');
+
+    const withLock = createRegistryLock(lockPath, { staleMs: 30_000, maxWaitMs: 20, retryMs: 5 });
+    assert.throws(() => withLock(() => 'ran'), /slots\.lock/);
+  });
+});
+
+// ── Slot preparation: reset, clean, fetch, checkout-or-create (task 3.8) ──────
+
+describe('prepareSlot', () => {
+  it('resets and cleans, fetches origin, then checks out an existing branch from the REMOTE', () => {
+    const calls: Array<{ args: string[]; cwd: string }> = [];
+    const result = prepareSlot({
+      slotPath: '/slots/dispatch-a',
+      taskId: 'T-12',
+      remoteBranches: ['main', 'task/T-12'],
+      branchesCheckedOutElsewhere: [],
+      runGit: (args: string[], cwd: string) => {
+        calls.push({ args, cwd });
+      },
+    });
+
+    assert.deepEqual(result, { kind: 'prepared', ref: 'task/T-12', base: 'existing' });
+    assert.deepEqual(
+      calls.map((call) => call.args),
+      [
+        ['reset', '--hard'],
+        ['clean', '-fd'],
+        ['fetch', 'origin', '--prune'],
+        ['checkout', '-B', 'task/T-12', 'origin/task/T-12'],
+      ],
+    );
+    assert.ok(calls.every((call) => call.cwd === '/slots/dispatch-a'));
+  });
+
+  it('creates a fresh branch off the REMOTE parent branch for a first-time subtask', () => {
+    const calls: string[][] = [];
+    const result = prepareSlot({
+      slotPath: '/slots/dispatch-b',
+      taskId: 'T-13',
+      parentId: 'T-12',
+      remoteBranches: ['main', 'task/T-12'],
+      branchesCheckedOutElsewhere: [],
+      runGit: (args: string[]) => {
+        calls.push(args);
+      },
+    });
+
+    assert.deepEqual(result, { kind: 'prepared', ref: 'task/T-13', base: 'origin/task/T-12' });
+    assert.deepEqual(calls, [
+      ['reset', '--hard'],
+      ['clean', '-fd'],
+      ['fetch', 'origin', '--prune'],
+      ['checkout', '-B', 'task/T-13', 'origin/task/T-12'],
+    ]);
+  });
+
+  it('creates a fresh branch off origin/main for a first-time non-subtask', () => {
+    const calls: string[][] = [];
+    const result = prepareSlot({
+      slotPath: '/slots/dispatch-c',
+      taskId: 'T-14',
+      remoteBranches: ['main'],
+      branchesCheckedOutElsewhere: [],
+      runGit: (args: string[]) => {
+        calls.push(args);
+      },
+    });
+
+    assert.deepEqual(result, { kind: 'prepared', ref: 'task/T-14', base: 'origin/main' });
+    assert.deepEqual(calls[3], ['checkout', '-B', 'task/T-14', 'origin/main']);
+  });
+
+  // H1: a slot released without detaching leaves `task/T-nn` behind as a LOCAL branch. `-b` fails
+  // outright on a name that already exists, so a retry died on leftover state of its own making.
+  it('forces the branch onto the base with -B, so a leftover local branch cannot fail the checkout', () => {
+    const calls: string[][] = [];
+    prepareSlot({
+      slotPath: '/slots/dispatch-c',
+      taskId: 'T-15',
+      remoteBranches: ['main'],
+      branchesCheckedOutElsewhere: [],
+      runGit: (args: string[]) => {
+        calls.push(args);
+      },
+    });
+
+    assert.ok(!calls.some((args) => args[0] === 'checkout' && args[1] === '-b'));
+  });
+
+  it('refuses — without throwing — when the branch is already checked out in another slot', () => {
+    const calls: string[][] = [];
+    const result = prepareSlot({
+      slotPath: '/slots/dispatch-c',
+      taskId: 'T-14',
+      remoteBranches: ['main'],
+      branchesCheckedOutElsewhere: ['task/T-14'],
+      runGit: (args: string[]) => {
+        calls.push(args);
+      },
+    });
+
+    assert.deepEqual(result, { kind: 'branch-in-use', ref: 'task/T-14' });
+    assert.deepEqual(calls, [], 'nothing may run against a slot whose branch is taken');
+  });
+
+  // T-14 (2026-09-08): reaching this with a missing parent branch is now a programming error —
+  // `guards.ts`'s pre-launch guard (`checkParentBranchOnRemote`) refuses the dispatch before a slot
+  // is ever taken. Throwing here, before any `git` call, means the slot is never reset/cleaned
+  // against a base that does not exist — `entry.ts`'s dispatch-abort path handles the throw the same
+  // way it handles any other slot-preparation failure.
+  it("throws — without running any git command — when the subtask's parent branch is missing", () => {
+    const calls: string[][] = [];
+    assert.throws(() =>
+      prepareSlot({
+        slotPath: '/slots/dispatch-c',
+        taskId: 'T-13',
+        parentId: 'T-12',
+        remoteBranches: ['main'],
+        branchesCheckedOutElsewhere: [],
+        runGit: (args: string[]) => {
+          calls.push(args);
+        },
+      }),
+    );
+    assert.deepEqual(calls, [], 'nothing may run against a slot whose base does not exist');
+  });
+});
+
+// ── Slot provisioning: the worktree does not exist until the first acquisition ──
+
+describe('provisionSlot', () => {
+  // K4: a slot directory deleted by hand (someone clearing `.claude/worktrees/`) leaves git's own
+  // administrative record behind, and `worktree add` then refuses the path as "already registered".
+  // Pruning first is what makes a missing slot self-heal instead of blocking every later dispatch.
+  it('creates the worktree detached off origin/main, links the gitignored artifacts, installs', () => {
+    const calls: Array<{ command: string; args: string[]; cwd: string }> = [];
+    const result = provisionSlot({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      repoRoot: '/repo',
+      slotExists: false,
+      needsInstall: true,
+      run: (command, args, cwd) => {
+        calls.push({ command, args, cwd });
+      },
+    });
+
+    assert.deepEqual(calls, [
+      { command: 'git', args: ['fetch', 'origin', '--prune'], cwd: '/repo' },
+      { command: 'git', args: ['worktree', 'prune'], cwd: '/repo' },
+      {
+        command: 'git',
+        args: ['worktree', 'add', '/repo/.claude/worktrees/dispatch-a', '--detach', 'origin/main'],
+        cwd: '/repo',
+      },
+      {
+        command: 'bash',
+        args: ['scripts/worktree-link.sh'],
+        cwd: '/repo/.claude/worktrees/dispatch-a',
+      },
+      { command: 'pnpm', args: ['install'], cwd: '/repo/.claude/worktrees/dispatch-a' },
+    ]);
+    assert.deepEqual(result, { created: true, installed: true });
+  });
+
+  it('skips creation and linking for a slot that already exists, installing only when needed', () => {
+    const calls: string[][] = [];
+    const result = provisionSlot({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      repoRoot: '/repo',
+      slotExists: true,
+      needsInstall: true,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.deepEqual(calls, [['pnpm', 'install']]);
+    assert.deepEqual(result, { created: false, installed: true });
+  });
+
+  it('does nothing at all for an existing slot whose lockfile hash still matches', () => {
+    const calls: string[][] = [];
+    const result = provisionSlot({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      repoRoot: '/repo',
+      slotExists: true,
+      needsInstall: false,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.deepEqual(calls, []);
+    assert.deepEqual(result, { created: false, installed: false });
+  });
+
+  // T-50: `provisionSlot` never touches `packages/cli` at all — installing it is
+  // `provisionCliDependencies`'s job, called separately by the caller AFTER `prepareSlot`, never
+  // here. This would fail if a `pnpm --dir packages/cli install`/`pnpm cli:build` call crept back
+  // in, at any point in the sequence — `mentionsPackagesCli` checks each ARG for the substring, not
+  // for an exact array element (see the `mentionsPackagesCli` tests below for why that distinction
+  // matters).
+  it('never runs anything under packages/cli, even when the root install runs', () => {
+    const calls: string[][] = [];
+    provisionSlot({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      repoRoot: '/repo',
+      slotExists: false,
+      needsInstall: true,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.equal(
+      mentionsPackagesCli(calls),
+      false,
+      'provisionSlot must never mention packages/cli — that is provisionCliDependencies’s job',
+    );
+  });
+});
+
+/**
+ * A `string[]` array's `.includes` compares EXACT elements, not substrings. Measured:
+ * `[['pnpm','cli:build'],['node','packages/cli/bin/run.js']].every(c=>!c.includes('packages/cli'))`
+ * is `true` — writing the guard above that way would have let `packages/cli/bin/run.js` (a
+ * substring match, never an exact one) slip through silently, contradicting its own comment.
+ */
+function mentionsPackagesCli(calls: readonly string[][]): boolean {
+  return calls.some((call) => call.some((arg) => arg.includes('packages/cli')));
+}
+
+describe('mentionsPackagesCli (guarding the guard above)', () => {
+  it('catches an exact packages/cli argument', () => {
+    assert.equal(mentionsPackagesCli([['pnpm', '--dir', 'packages/cli', 'install']]), true);
+  });
+
+  it('catches a --dir ./packages/cli form (a substring, never an exact element)', () => {
+    assert.equal(mentionsPackagesCli([['pnpm', '--dir', './packages/cli', 'install']]), true);
+  });
+
+  it('catches packages/cli as part of a longer path', () => {
+    assert.equal(mentionsPackagesCli([['node', 'packages/cli/bin/run.js']]), true);
+  });
+
+  it('does not flag unrelated calls', () => {
+    assert.equal(mentionsPackagesCli([['pnpm', 'install'], ['git', 'checkout', '-B', 'main']]), false);
+  });
+});
+
+// T-50: the DECISION lives in this pure function, so a review that inverted a negation in the
+// wiring has something direct to fail against instead of only end-to-end tests.
+describe('needsCliInstall', () => {
+  it('does not install when node_modules is present and the stored hash matches the current one', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: 'same-hash',
+        currentCliLockfileHash: 'same-hash',
+      }),
+      false,
+    );
+  });
+
+  it('installs when node_modules is missing, even with a matching hash', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: false,
+        storedCliLockfileHash: 'same-hash',
+        currentCliLockfileHash: 'same-hash',
+      }),
+      true,
+    );
+  });
+
+  it("installs when the CLI's own lockfile hash changed, even with node_modules present", () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: 'old-hash',
+        currentCliLockfileHash: 'new-hash',
+      }),
+      true,
+    );
+  });
+
+  // Backward compatibility: a slot registered before `cliLockfileHash` existed reads it as
+  // `undefined`, which differs from any real hash and correctly fires the install once.
+  it('installs when the slot has no stored CLI hash at all (a legacy slot)', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: undefined,
+        currentCliLockfileHash: 'new-hash',
+      }),
+      true,
+    );
+  });
+
+  // The generated-monorepo case: `packages/cli/src/templates/monorepo/` has no `packages/`
+  // directory of its own and consumes the npm-published `catalyst` binary — this step must not
+  // apply there, regardless of what the other signals say.
+  it('never installs when the repo has no packages/cli of its own, whatever the other signals say', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: false,
+        cliNodeModulesExists: false,
+        storedCliLockfileHash: undefined,
+        currentCliLockfileHash: 'new-hash',
+      }),
+      false,
+    );
+  });
+
+  it('never fires on a hash mismatch alone when the current hash could not be read (null)', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: 'old-hash',
+        currentCliLockfileHash: null,
+      }),
+      false,
+    );
+  });
+});
+
+describe('provisionCliDependencies', () => {
+  it('runs pnpm --dir packages/cli install, from the slot, when needsCliInstall is true', () => {
+    const calls: Array<{ command: string; args: string[]; cwd: string }> = [];
+    const result = provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: true,
+      needsCliInstall: true,
+      run: (command, args, cwd) => {
+        calls.push({ command, args, cwd });
+      },
+    });
+
+    assert.deepEqual(calls, [
+      {
+        command: 'rm',
+        args: ['-rf', 'packages/cli/dist'],
+        cwd: '/repo/.claude/worktrees/dispatch-a',
+      },
+      {
+        command: 'pnpm',
+        args: ['--dir', 'packages/cli', 'install'],
+        cwd: '/repo/.claude/worktrees/dispatch-a',
+      },
+    ]);
+    assert.deepEqual(result, { installed: true });
+  });
+
+  // `dist` is gitignored, so `prepareSlot`'s `clean -fd` (no `-x`) never removes it — a worker
+  // that inherits the PREVIOUS occupant's `dist` generates silently wrong code. This must fire
+  // EVERY time packages/cli exists, whether or not the install itself runs.
+  it('removes dist even when no install is needed — a matching hash does not mean a clean dist', () => {
+    const calls: string[][] = [];
+    const result = provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: true,
+      needsCliInstall: false,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.deepEqual(calls, [['rm', '-rf', 'packages/cli/dist']]);
+    assert.deepEqual(result, { installed: false });
+  });
+
+  it('does nothing at all — no dist removal, no install — when the repo has no packages/cli', () => {
+    const calls: string[][] = [];
+    const result = provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: false,
+      needsCliInstall: true,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.deepEqual(calls, []);
+    assert.deepEqual(result, { installed: false });
+  });
+
+  it('never builds the CLI — that stays the worker’s job (T-48)', () => {
+    const calls: string[][] = [];
+    provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: true,
+      needsCliInstall: true,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.ok(
+      calls.every((call) => !call.includes('cli:build')),
+      'provisionCliDependencies must never run the CLI build',
+    );
+  });
+});
+
+// H1: EVERY release detaches. Only the close's own runner used to, so an abort, a branch-in-use
+// handback or a sweep left `task/T-nn` checked out in the slot — and git refuses that same branch
+// in any other worktree, so the task's next dispatch hit `branch-in-use` forever.
+describe('releaseSlotAndDetach', () => {
+  it('detaches the worktree BEFORE clearing the registry entry', () => {
+    const order: string[] = [];
+    releaseSlotAndDetach({
+      taskId: 'T-1',
+      slotPath: '/slots/dispatch-a',
+      runGit: (args, cwd) => order.push(`${args.join(' ')} @ ${cwd}`),
+      updateSlots: (mutate) => {
+        order.push('updateSlots');
+        return mutate({ slots: [] });
+      },
+    });
+
+    assert.deepEqual(order, ['checkout --detach @ /slots/dispatch-a', 'updateSlots']);
+  });
+
+  it('clears the registry entry even with no slot to detach — a stranded entry is the worse half', () => {
+    let released: SlotRegistry = { slots: [] };
+    const slots = threeFreeSlots();
+    slots[0] = { ...slots[0], lane: LANE.LOCAL, taskId: 'T-1', pid: 111 };
+
+    releaseSlotAndDetach({
+      taskId: 'T-1',
+      slotPath: null,
+      runGit: () => assert.fail('there is no slot to run anything in'),
+      updateSlots: (mutate) => {
+        released = mutate({ slots });
+        return released;
+      },
+    });
+
+    assert.equal(released.slots[0].taskId, null);
+  });
+
+  it('still clears the registry entry when the detach itself fails', () => {
+    let released = false;
+    releaseSlotAndDetach({
+      taskId: 'T-1',
+      slotPath: '/slots/dispatch-a',
+      runGit: () => {
+        throw new Error('not a repository');
+      },
+      updateSlots: (mutate) => {
+        released = true;
+        return mutate({ slots: [] });
+      },
+    });
+
+    assert.equal(released, true);
+  });
+});
+
+describe('detachSlot', () => {
+  it('leaves the slot on a detached HEAD so the task branch is free for the next acquisition', () => {
+    const calls: Array<{ args: string[]; cwd: string }> = [];
+    detachSlot('/slots/dispatch-a', (args, cwd) => {
+      calls.push({ args, cwd });
+    });
+    assert.deepEqual(calls, [{ args: ['checkout', '--detach'], cwd: '/slots/dispatch-a' }]);
+  });
+
+  it('never throws: a slot that cannot be detached must not abort the close', () => {
+    assert.doesNotThrow(() =>
+      detachSlot('/slots/dispatch-a', () => {
+        throw new Error('not a git repository');
+      }),
+    );
+  });
+});