@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

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

@@ -0,0 +1,1545 @@
+/**
+ * TDD spec for `scripts/backlog/entry.ts` (tasks 3.17/3.18).
+ *
+ * Runner: `node --import tsx --test scripts/backlog/entry.test.ts`
+ *
+ * Covers `resolveContext` (`BACKLOG_CWD` resolution via an injected `findRepoRoot`),
+ * `acquireSingleFlight`/`releaseSingleFlight` (a concurrent second invocation is refused; a stale
+ * lock naming a dead PID is replaced), `shouldDispatchFromCallback` (the anti-loop guard:
+ * `specs/backlog-task-dispatcher/spec.md` — "Anti-loop guard on status transitions"), and
+ * `selectNextTask` (priority then age — "Task selection ordering"). `runOnce`'s wiring order
+ * (maintenance → selection → guards → slot → launch → close) is asserted through recording
+ * doubles for every injected collaborator, so this suite never touches a real filesystem, git
+ * repository, or `claude` process.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  acquireSingleFlight,
+  formatOutcome,
+  isDispatcherOwnedCallback,
+  releaseSingleFlight,
+  resolveContext,
+  runOnce,
+  selectNextTask,
+  shouldDispatchFromCallback,
+  type RunOnceContext,
+  type SingleFlightFs,
+} from './entry.js';
+import type { MaintenanceContext } from './maintenance.js';
+import {
+  EXECUTION_PATH,
+  LANE,
+  TASK_STATUS,
+  TIER,
+  type SettingsAllowRule,
+  type SlotRegistry,
+  type Task,
+} from './types.js';
+
+// ── resolveContext ───────────────────────────────────────────────────────────
+
+/** Loaded allow rules as the PROJECT settings file contributes them. */
+const projectRules = (...rules: string[]): SettingsAllowRule[] =>
+  rules.map((rule) => ({ rule, source: 'project' as const }));
+const userRules = (...rules: string[]): SettingsAllowRule[] =>
+  rules.map((rule) => ({ rule, source: 'user' as const }));
+
+describe('resolveContext', () => {
+  it('resolves the main checkout path via the injected findRepoRoot, from the given cwd', () => {
+    const calls: string[] = [];
+    const result = resolveContext({
+      cwd: '/repo/.claude/worktrees/dispatch-a',
+      env: {},
+      findRepoRoot: (startDir) => {
+        calls.push(startDir);
+        return '/repo';
+      },
+    });
+    assert.equal(result.mainCheckoutPath, '/repo');
+    assert.deepEqual(calls, ['/repo/.claude/worktrees/dispatch-a']);
+  });
+
+  it('prefers an explicit BACKLOG_CWD over findRepoRoot, without even calling it', () => {
+    const calls: string[] = [];
+    const result = resolveContext({
+      cwd: '/repo',
+      env: { BACKLOG_CWD: '/tmp/isolated-backlog-project' },
+      findRepoRoot: (startDir) => {
+        calls.push(startDir);
+        return '/repo';
+      },
+    });
+    assert.equal(result.mainCheckoutPath, '/tmp/isolated-backlog-project');
+    assert.deepEqual(calls, []);
+  });
+});
+
+// ── acquireSingleFlight / releaseSingleFlight ─────────────────────────────────
+
+function makeSingleFlightFs(initialPid: number | null): {
+  fs: SingleFlightFs;
+  written: number[];
+  removed: number;
+} {
+  let stored = initialPid;
+  const written: number[] = [];
+  let removed = 0;
+  return {
+    fs: {
+      readLockPid: () => stored,
+      writeLockPid: (pid: number) => {
+        stored = pid;
+        written.push(pid);
+      },
+      removeLock: () => {
+        stored = null;
+        removed += 1;
+      },
+    },
+    written: written,
+    get removed() {
+      return removed;
+    },
+  } as unknown as { fs: SingleFlightFs; written: number[]; removed: number };
+}
+
+describe('acquireSingleFlight', () => {
+  it('acquires when no lock file exists', () => {
+    const { fs, written } = makeSingleFlightFs(null);
+    const result = acquireSingleFlight(fs, 555, () => true);
+    assert.deepEqual(result, { kind: 'acquired' });
+    assert.deepEqual(written, [555]);
+  });
+
+  it('refuses a concurrent second invocation when the recorded PID is alive', () => {
+    const { fs } = makeSingleFlightFs(111);
+    const result = acquireSingleFlight(fs, 555, (pid) => pid === 111);
+    assert.deepEqual(result, { kind: 'already-running', pid: 111 });
+  });
+
+  it('replaces a stale lock naming a dead PID', () => {
+    const { fs, written } = makeSingleFlightFs(999);
+    const result = acquireSingleFlight(fs, 555, (pid) => pid !== 999);
+    assert.deepEqual(result, { kind: 'acquired' });
+    assert.deepEqual(written, [555]);
+  });
+
+  it('releaseSingleFlight removes the lock', () => {
+    const { fs } = makeSingleFlightFs(555);
+    releaseSingleFlight(fs);
+    assert.equal(fs.readLockPid(), null);
+  });
+
+  it('releaseSingleFlight with an owner pid keeps a lock another pass already took', () => {
+    const { fs } = makeSingleFlightFs(777);
+    releaseSingleFlight(fs, 555);
+    assert.equal(fs.readLockPid(), 777, 'a pass must never delete the lock a later pass acquired');
+  });
+
+  it('releaseSingleFlight with a matching owner pid still removes it', () => {
+    const { fs } = makeSingleFlightFs(555);
+    releaseSingleFlight(fs, 555);
+    assert.equal(fs.readLockPid(), null);
+  });
+});
+
+// ── shouldDispatchFromCallback ─────────────────────────────────────────────────
+
+describe('shouldDispatchFromCallback', () => {
+  it('dispatches on a genuine Queued transition with no active sentinel', () => {
+    assert.equal(shouldDispatchFromCallback({ NEW_STATUS: 'Queued', OLD_STATUS: 'To Do' }), true);
+  });
+
+  it('refuses when the new status is not Queued', () => {
+    assert.equal(
+      shouldDispatchFromCallback({ NEW_STATUS: 'Blocked', OLD_STATUS: 'In Progress' }),
+      false,
+    );
+  });
+
+  it('refuses when the old status was already Queued', () => {
+    assert.equal(shouldDispatchFromCallback({ NEW_STATUS: 'Queued', OLD_STATUS: 'Queued' }), false);
+  });
+
+  it("refuses a worker's own write, even Queued<-not-Queued, when BACKLOG_DISPATCH_ACTIVE is set", () => {
+    assert.equal(
+      shouldDispatchFromCallback({
+        NEW_STATUS: 'Queued',
+        OLD_STATUS: 'To Do',
+        BACKLOG_DISPATCH_ACTIVE: '1',
+      }),
+      false,
+    );
+  });
+
+  it('is true (not a callback at all) when NEW_STATUS/OLD_STATUS are absent — the timer/gh-poll triggers', () => {
+    assert.equal(shouldDispatchFromCallback({}), true);
+  });
+
+  it('refuses a worker-spawned invocation with no NEW_STATUS at all: the sentinel wins outright', () => {
+    assert.equal(shouldDispatchFromCallback({ BACKLOG_DISPATCH_ACTIVE: '1' }), false);
+  });
+});
+
+// ── isDispatcherOwnedCallback ────────────────────────────────────────────────
+//
+// Measured defect (T-5, 2026-09-07): `shouldDispatchFromCallback` only ever suppresses task
+// SELECTION — `runOnce` still runs maintenance unconditionally underneath it (spec: "Maintenance
+// pass precedes task selection"). A dispatcher-owned write (`setInProgress`, `onBlock`, ...) used
+// to fire `onStatusChange` with no sentinel at all, so the nested pass it spawned ran its OWN
+// maintenance sweep — including a `.backlog` git commit — concurrently with the pass that was
+// still mid-dispatch in the SAME checkout, and that concurrent commit is what failed with git
+// exit 128. `dispatch.ts`'s own `realBacklog`/`tickOwnedDod` writes now carry
+// `BACKLOG_DISPATCH_ACTIVE='1'` in their env (see `dispatch.test.ts`), so this predicate is what
+// `main()` checks BEFORE resolving context or running maintenance at all, to skip the nested pass
+// outright rather than merely skip its selection step.
+describe('isDispatcherOwnedCallback', () => {
+  it('is true for the callback a dispatcher-owned write fires — TASK_ID, a status, and the sentinel', () => {
+    assert.equal(
+      isDispatcherOwnedCallback({
+        TASK_ID: 'T-5',
+        NEW_STATUS: 'In Progress',
+        BACKLOG_DISPATCH_ACTIVE: '1',
+      }),
+      true,
+    );
+  });
+
+  it('is false for a genuine human callback with no sentinel, even with TASK_ID and NEW_STATUS present', () => {
+    assert.equal(isDispatcherOwnedCallback({ TASK_ID: 'T-5', NEW_STATUS: 'Queued' }), false);
+  });
+
+  it('is false for the launchd timer / gh-poll trigger — no TASK_ID at all, sentinel or not', () => {
+    assert.equal(isDispatcherOwnedCallback({ BACKLOG_DISPATCH_ACTIVE: '1' }), false);
+  });
+});
+
+// ── selectNextTask ───────────────────────────────────────────────────────────
+
+const baseTask = (overrides: Partial<Task> = {}): Task => ({
+  id: 'T-1',
+  status: TASK_STATUS.QUEUED,
+  tier: TIER.MINOR,
+  lane: LANE.LOCAL,
+  path: EXECUTION_PATH.DIRECT,
+  // Non-empty on purpose: guard 1 blocks a `lane:local` task that declares no files to touch.
+  filesToTouch: ['scripts/backlog/entry.ts'],
+  testCommand: 'pnpm test:backlog',
+  acceptanceCriteria: [],
+  definitionOfDone: [],
+  dependsOn: [],
+  attempts: 0,
+  priority: 0,
+  createdAt: 0,
+  updatedAt: 0,
+  ...overrides,
+});
+
+describe('selectNextTask', () => {
+  it('returns null when there is nothing queued', () => {
+    assert.equal(selectNextTask([]), null);
+  });
+
+  it('picks the higher-priority task regardless of queue order', () => {
+    const low = baseTask({ id: 'T-1', priority: 1, createdAt: 0 });
+    const high = baseTask({ id: 'T-2', priority: 5, createdAt: 10 });
+    assert.equal(selectNextTask([low, high])?.id, 'T-2');
+  });
+
+  it('breaks a priority tie by age (earlier createdAt wins)', () => {
+    const older = baseTask({ id: 'T-1', priority: 3, createdAt: 5 });
+    const newer = baseTask({ id: 'T-2', priority: 3, createdAt: 50 });
+    assert.equal(selectNextTask([newer, older])?.id, 'T-1');
+  });
+});
+
+// ── runOnce: wiring order via recording doubles ────────────────────────────────
+
+function freeSlots(): SlotRegistry {
+  return {
+    slots: [
+      {
+        name: 'dispatch-a',
+        path: '/slots/dispatch-a',
+        lane: null,
+        taskId: null,
+        pid: null,
+        lockfileHash: null,
+      },
+    ],
+  };
+}
+
+// The maintenance pass now OWNS the registry `runOnce` acts on (it returns the post-sweep one), so
+// the double must read back exactly the slots the test set up — not an empty registry.
+function noopMaintenanceContext(tasks: Task[], slots: SlotRegistry): MaintenanceContext {
+  return {
+    now: 0,
+    ttlMs: 60_000,
+    isPidAlive: () => true,
+    tasks,
+    // These fixtures ARE the whole board: nothing here exercises the partial-read path (that lives
+    // in `maintenance.test.ts`), and claiming otherwise would suppress the sweep this suite drives.
+    boardComplete: true,
+    fs: {
+      readSlots: () => slots,
+      updateSlots: (mutate) => mutate(slots),
+      // A live lock per busy slot: without one the orphan sweep would release the very slots a
+      // capacity test set up as occupied, and the test would measure the double, not `runOnce`.
+      readLocks: () =>
+        slots.slots
+          .filter((slot): slot is typeof slot & { taskId: string } => slot.taskId !== null)
+          .map((slot) => ({
+            taskId: slot.taskId,
+            slot: slot.name,
+            pid: slot.pid ?? 1,
+            startedAt: new Date(0).toISOString(),
+            heartbeatAt: new Date(0).toISOString(),
+            lane: slot.lane ?? LANE.LOCAL,
+            attempt: 1,
+            branch: `task/${slot.taskId}`,
+          })),
+      removeLock: () => {},
+      // T-8 defect 3: no fixture in this suite exercises a Complex parent's close-attempt
+      // derivation (that lives in `maintenance.test.ts`), so a constant `false`/no-op pair is the
+      // whole contract this double owes `MaintenanceFs`.
+      hasCloseAttemptBeenEnqueued: () => false,
+      markCloseAttemptEnqueued: () => {},
+    },
+    gh: { isPrMerged: () => false },
+    backlog: { setStatus: () => {}, comment: () => {} },
+    git: {
+      hasPendingBacklogChanges: () => false,
+      commitBacklogChanges: () => {},
+      saveWipAndPush: () => ({ pushSucceeded: true }),
+      detachSlot: () => {},
+    },
+    killProcess: () => {},
+    notify: () => {},
+  };
+}
+
+/**
+ * The registry lives in the fake as MUTABLE state, exactly as `slots.json` does on disk: every
+ * `updateSlots` re-reads what is there and applies the caller's transform to it. A fake that
+ * ignored the current value would hide the very class of bug the primitive exists to prevent.
+ */
+function makeRunOnceContext(
+  overrides: Partial<RunOnceContext> & { tasks: Task[]; slots?: SlotRegistry },
+  calls: string[],
+): RunOnceContext {
+  let registry = overrides.slots ?? freeSlots();
+  return {
+    shouldSelect: true,
+    maintenance: noopMaintenanceContext(overrides.tasks, registry),
+    // The whole `BoardLoad`, not just the array: `complete` is what the close's parent derivation
+    // reads, and a fake that returned only the tasks could not express a partial read at all.
+    reloadTasks: () => ({ tasks: overrides.tasks, complete: true }),
+    updateSlots: (mutate) => {
+      registry = mutate(registry);
+      calls.push('updateSlots');
+      return registry;
+    },
+    removeLock: () => calls.push('removeLock'),
+    onDispatchFailure: () => calls.push('onDispatchFailure'),
+    mainCheckoutPath: '/repo',
+    currentPid: 4242,
+    attempt: (task) => task.attempts + 1,
+    onBlock: () => calls.push('onBlock'),
+    remoteBranches: [],
+    branchesCheckedOutElsewhere: [],
+    runGit: (args) => calls.push(`runGit(${args.join(' ')})`),
+    provisionSlot: (slot) => {
+      calls.push('provisionSlot');
+      return slot;
+    },
+    writeLock: () => calls.push('writeLock'),
+    // The default fake still owns the lock: it echoes back what this pass would have written.
+    readLock: (taskId) => ({
+      taskId,
+      slot: 'dispatch-a',
+      pid: overrides.currentPid ?? 4242,
+      startedAt: '2026-09-06T00:00:00.000Z',
+      heartbeatAt: '2026-09-06T00:00:00.000Z',
+      lane: LANE.LOCAL,
+      attempt: 1,
+      branch: `task/${taskId}`,
+    }),
+    setInProgress: () => calls.push('setInProgress'),
+    releaseSingleFlight: () => calls.push('releaseSingleFlight'),
+    resetInjectorCache: () => calls.push('resetInjectorCache'),
+    isLocalModelLoaded: async () => {
+      calls.push('isLocalModelLoaded');
+      return true;
+    },
+    onLocalModelMissing: () => calls.push('onLocalModelMissing'),
+    beginAttempt: () => {
+      calls.push('beginAttempt');
+      const collected: string[] = [];
+      return {
+        onLine: (line: string) => collected.push(line),
+        finish: () => {
+          calls.push('finishAttempt');
+          return collected;
+        },
+        stopHeartbeat: () => calls.push('stopHeartbeat'),
+      };
+    },
+    buildPrompt: () => 'assembled prompt',
+    workerSystemPromptPath: '/Users/carlos/Projects/aurora/aurora-catalyst/.claude/skills/catalyst-backlog/worker-system-prompt.md',
+    writeFrontierAddendum: (task, attempt) =>
+      `/dispatch/${task.id}/intento-${attempt}/frontier-addendum.md`,
+    laneConfig: {
+      slotsRoot: '.claude/worktrees',
+      slots: ['dispatch-a'],
+      attempts: 3,
+      orphanInProgressThresholdHours: 4,
+      lanes: {
+        local: {
+          settings: 'scripts/backlog/lanes/local.settings.json',
+          maxParallel: 1,
+          effort: 'medium',
+          maxTurns: 40,
+          timeoutMinutes: 30,
+          healthCheckUrl: 'http://localhost:1234',
+          reviewerModel: 'sonnet',
+          reviewerTimeoutMinutes: 15,
+        },
+        frontier: {
+          settings: 'scripts/backlog/lanes/frontier.settings.json',
+          maxParallel: 2,
+          model: { direct: 'sonnet', sdd: 'opus' },
+          maxTurns: 120,
+          maxBudgetUsd: 5,
+          timeoutMinutes: 90,
+        },
+      },
+    },
+    // A read AND a write rule on both lanes: `buildLaunch`'s `assertLaneGrantsFileAccess` refuses
+    // to launch a worker that cannot open or change a file, which would turn every dispatch
+    // assertion below into a `blocked` result about the fixture rather than about `runOnce`.
+    loadLocalSettings: () => ({
+      model: 'qwen/qwen3.8-27b',
+      permissions: { allow: ['Read', 'Edit(./**)'] },
+    }),
+    loadFrontierSettings: () => ({ permissions: { allow: ['Read', 'Edit(./**)'] } }),
+    // The settings sources a frontier worker would load on top of the lane list; empty here, so the
+    // launch composes no extra deny (the subtraction itself is tested in `launch.test.ts`).
+    loadSettingsAllowRules: () => [],
+    spawnWorker: async (_launch, onLine, hooks) => {
+      calls.push('spawnWorker');
+      hooks?.onSpawn?.(9001);
+      onLine('{"type":"result","subtype":"success","is_error":false}');
+    },
+    logPathFor: () => '.backlog/.dispatch/T-1/intento-1/run.log',
+    buildCloseRunners: () => ({
+      boardCheck: () => {
+        calls.push('boardCheck');
+        return { ok: true };
+      },
+      scopeCheck: () => {
+        calls.push('scopeCheck');
+        return { ok: true, humanReviewFiles: [] };
+      },
+      formatLintTest: () => {
+        calls.push('formatLintTest');
+        return { ok: true };
+      },
+      mirrorRegen: () => {
+        calls.push('mirrorRegen');
+        return { ok: true };
+      },
+      reviewer: () => {
+        calls.push('reviewer');
+        return { ok: true };
+      },
+      acCheck: () => {
+        calls.push('acCheck');
+        return { ok: true };
+      },
+      openPr: () => {
+        calls.push('openPr');
+        return { ok: true };
+      },
+      releaseSlot: () => calls.push('releaseSlot'),
+      recomputeParent: () => calls.push('recomputeParent'),
+      drain: () => calls.push('drain'),
+      saveWork: () => {
+        calls.push('saveWork');
+        return { pushSucceeded: true };
+      },
+      leftoverFiles: () => {
+        calls.push('leftoverFiles');
+        return { forbiddenFiles: [], humanReviewFiles: [] };
+      },
+      block: () => calls.push('block'),
+      blockKeepSlot: () => calls.push('blockKeepSlot'),
+    }),
+    ...overrides,
+  };
+}
+
+/** Records every registry the context's `updateSlots` produced, in order. */
+function recordingUpdates(ctx: RunOnceContext, written: SlotRegistry[]): RunOnceContext {
+  const inner = ctx.updateSlots;
+  return {
+    ...ctx,
+    updateSlots: (mutate) => {
+      const next = inner(mutate);
+      written.push(next);
+      return next;
+    },
+  };
+}
+
+describe('runOnce', () => {
+  it('runs maintenance and stops right there when the anti-loop guard says not to select', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [], shouldSelect: false }, calls);
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, { kind: 'skipped-by-guard' });
+    assert.deepEqual(calls, []);
+  });
+
+  it('reports no-queued-task when nothing is Queued, after maintenance', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask({ status: TASK_STATUS.TO_DO })] }, calls);
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, { kind: 'no-queued-task' });
+  });
+
+  it('blocks via onBlock when the selected task fails a guard, and dispatches nothing further', async () => {
+    const calls: string[] = [];
+    const untriaged = baseTask({ tier: undefined });
+    const ctx = makeRunOnceContext({ tasks: [untriaged] }, calls);
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'blocked');
+    assert.deepEqual(calls, ['onBlock']);
+  });
+
+  it('leaves the task Queued (waiting) when no slot is free, without touching the launch pipeline', async () => {
+    const calls: string[] = [];
+    const busy: SlotRegistry = {
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/dispatch-a',
+          lane: LANE.LOCAL,
+          taskId: 'T-9',
+          pid: 1,
+          lockfileHash: null,
+        },
+      ],
+    };
+    // T-9 must be ON the board and In Progress: a lock for a task the board does not list is a
+    // cancellation (the person deleted it), and the sweep would free the slot this test needs busy.
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask(), baseTask({ id: 'T-9', status: TASK_STATUS.IN_PROGRESS })],
+        slots: busy,
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, { kind: 'waiting', reason: 'no-free-slot', taskId: 'T-1' });
+    assert.deepEqual(calls, []);
+  });
+
+  it('records the WORKER pid on the lock as soon as the child exists, not the reconciler pid', async () => {
+    const locks: Array<{ pid: number; workerPid?: number | null }> = [];
+    const ctx = makeRunOnceContext(
+      { tasks: [baseTask()], writeLock: (lock) => locks.push(lock), currentPid: 4242 },
+      [],
+    );
+    await runOnce(ctx);
+
+    assert.deepEqual(
+      locks.map((lock) => [lock.pid, lock.workerPid]),
+      [
+        [4242, null],
+        [4242, 9001],
+      ],
+    );
+  });
+
+  // K11: the second write rebuilt the lock from the in-memory snapshot taken before the spawn, so
+  // anything written to the lock file in between — the attempt sink's first heartbeat refresh —
+  // was reverted to the launch value. A lock whose heartbeat runs BACKWARDS is exactly what the
+  // maintenance sweep reads as stale, and it kills the worker this write was recording.
+  it('merges the worker pid onto the lock ON DISK, never over a fresher heartbeat', async () => {
+    const written: Array<{ heartbeatAt: string; workerPid?: number | null }> = [];
+    const refreshed = new Date(Date.parse('2026-09-06T12:34:56.000Z')).toISOString();
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        writeLock: (lock) => written.push(lock),
+        // What the sink's heartbeat left on disk while the worker was starting.
+        readLock: () => ({ ...written[0], heartbeatAt: refreshed }) as never,
+      },
+      [],
+    );
+    await runOnce(ctx);
+
+    assert.equal(written.length, 2);
+    assert.equal(written[1].workerPid, 9001);
+    assert.equal(
+      written[1].heartbeatAt,
+      refreshed,
+      'the refreshed heartbeat must survive the workerPid write',
+    );
+  });
+
+  it('wires the full happy path in order: model check -> slot -> lock -> in-progress -> single-flight release -> attempt -> spawn -> close', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.deepEqual(calls, [
+      'isLocalModelLoaded',
+      'provisionSlot',
+      'updateSlots',
+      'runGit(reset --hard)',
+      'runGit(clean -fd)',
+      'runGit(fetch origin --prune)',
+      'runGit(checkout -B task/T-1 origin/main)',
+      'writeLock',
+      'setInProgress',
+      'releaseSingleFlight',
+      'resetInjectorCache',
+      'beginAttempt',
+      'spawnWorker',
+      'writeLock', // again, with the worker's own pid — see the workerPid test below
+      'finishAttempt',
+      'boardCheck',
+      'scopeCheck',
+      'formatLintTest',
+      'mirrorRegen',
+      'reviewer',
+      'acCheck',
+      'openPr',
+      'releaseSlot',
+      'recomputeParent',
+      'drain',
+      'stopHeartbeat',
+    ]);
+  });
+
+  // F2 (T-14 fix round, 2026-09-08): the pair below is what would have caught the F1 mutation —
+  // the reviewer deleted `ctx.remoteBranches` from the `evaluateGuards` call this module makes and
+  // the WHOLE suite stayed green at 963/963, because no `runOnce` fixture ever exercised guard 4b in
+  // either direction (every prior task here has no `parentId`). Deleting `ctx.remoteBranches` from
+  // that call now fails BOTH of these — the dispatch one because guard 4b sees no remote list to
+  // pass, the block one because `evaluateGuards` itself would no longer compile (F1 made the
+  // parameter required).
+  it('dispatches a subtask through guard 4b when its parent branch IS on the live remote list', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      { tasks: [baseTask({ parentId: 'T-0' })], remoteBranches: ['main', 'task/T-0'] },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+  });
+
+  // Fix round B3: `tasksById: board.tasksById` in the `prepareSlot` call is the wiring point this
+  // test exists to protect — deleting it is invisible to the type checker (this repo's CI never
+  // runs `tsc` over `scripts/`) and every OTHER fixture here has no parent that declared a branch,
+  // so nothing failed when that line was silently dropped. A parent's DECLARED branch (T-15) must
+  // reach the actual `git checkout`, not just guard 4b's pre-launch check.
+  it("prepares the slot against the parent's DECLARED branch, not the task/<parentId> deduction", async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [
+          // Not QUEUED: the parent is not a dispatch candidate itself here, only a board entry
+          // `board.tasksById` must expose for the subtask's `declaredBranch` lookup.
+          baseTask({
+            id: 'T-0',
+            status: TASK_STATUS.IN_PROGRESS,
+            declaredBranch: 'fix/parent-branch-resolution',
+          }),
+          baseTask({ id: 'T-1', parentId: 'T-0' }),
+        ],
+        remoteBranches: ['main', 'fix/parent-branch-resolution'],
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.ok(
+      calls.includes('runGit(checkout -B task/T-1 origin/fix/parent-branch-resolution)'),
+      `expected a checkout against the declared branch; got: ${calls.join(', ')}`,
+    );
+    assert.ok(
+      !calls.some((call) => call.includes('origin/task/T-0')),
+      'must never fall back to the task/<parentId> deduction when the parent declared a real branch',
+    );
+  });
+
+  it('blocks a subtask on guard 4b when the live remote list carries no parent branch (remoteBranches: [])', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      { tasks: [baseTask({ parentId: 'T-0' })], remoteBranches: [] },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'blocked');
+    if (result.outcome.kind === 'blocked') {
+      assert.equal(result.outcome.reason, 'missing-parent-branch');
+    }
+    assert.deepEqual(calls, ['onBlock']);
+  });
+
+  // Fix round B4: `reloadTasks()` returns the whole `BoardLoad`, `complete` included — this module
+  // used to keep only `.tasks`, so an incomplete read (the parent's own `backlog task view` threw)
+  // was indistinguishable from a complete one where the parent genuinely declares nothing. Guard 4b
+  // must WAIT here, not block: blocking would tell a person to push a branch that likely exists —
+  // the read just failed transiently this pass.
+  it('waits, never blocks, on guard 4b when the board read was incomplete and the parent is unreadable', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask({ parentId: 'T-0' })],
+        remoteBranches: [],
+        // The parent (T-0) is simply ABSENT here — its own `task view` read failed this pass — and
+        // `complete: false` is how a real `loadBoard` reports that, per `BoardLoad.complete`.
+        reloadTasks: () => ({ tasks: [baseTask({ parentId: 'T-0' })], complete: false }),
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'waiting');
+    if (result.outcome.kind === 'waiting') {
+      assert.equal(result.outcome.reason, 'parent-read-incomplete');
+    }
+    assert.deepEqual(calls, [], 'a wait must take no slot and call onBlock for nothing');
+  });
+
+  it('writes the lock with BACKLOG_DISPATCH_ACTIVE carried in the launch env (checked via the recorded launch, not the lock)', async () => {
+    const calls: string[] = [];
+    let capturedLaunchEnv: Record<string, string> | undefined;
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        spawnWorker: async (launch, onLine) => {
+          capturedLaunchEnv = launch.env;
+          calls.push('spawnWorker');
+          onLine('{"type":"result","subtype":"success","is_error":false}');
+        },
+      },
+      calls,
+    );
+    await runOnce(ctx);
+
+    assert.equal(capturedLaunchEnv?.BACKLOG_DISPATCH_ACTIVE, '1');
+  });
+
+  it('diverts to save-work/block/release-slot when the worker stream ends in a crash (no result event)', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        spawnWorker: async (_launch, onLine) => {
+          calls.push('spawnWorker');
+          onLine('{"type":"assistant","message":{"role":"assistant","content":[]}}');
+        },
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.deepEqual(calls.slice(calls.indexOf('spawnWorker')), [
+      'spawnWorker',
+      'finishAttempt',
+      // T-31 round 3: a session-level failure has no `scope-check` step, so `executeClose` asks the
+      // slot itself which files the attempt left behind, and of which kind — the `Blocked` comment
+      // is the only channel that path reaches.
+      'leftoverFiles',
+      'saveWork',
+      'block',
+      'releaseSlot',
+      'stopHeartbeat',
+    ]);
+  });
+
+  // T-6: the Blocked comment used to carry only the reason, the branch and the log path for a
+  // needs-guidance outcome — never the worker's own report. `block`'s `details.question` is where
+  // `entry.ts` must now attach it.
+  it("attaches the worker's final report to the Blocked details on a needs-guidance outcome", async () => {
+    const calls: string[] = [];
+    let blockedQuestion: string | undefined;
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        spawnWorker: async (_launch, onLine) => {
+          calls.push('spawnWorker');
+          onLine(
+            JSON.stringify({
+              type: 'assistant',
+              message: {
+                role: 'assistant',
+                content: [{ type: 'text', text: 'status: needs-guidance' }],
+              },
+            }),
+          );
+          onLine(
+            JSON.stringify({
+              type: 'result',
+              subtype: 'success',
+              is_error: false,
+              result: 'No pude confirmar el alcance exacto.\n\nstatus: needs-guidance',
+            }),
+          );
+        },
+      },
+      calls,
+    );
+    ctx.buildCloseRunners = () => ({
+      boardCheck: () => ({ ok: true }),
+      scopeCheck: () => ({ ok: true, humanReviewFiles: [] }),
+      formatLintTest: () => ({ ok: true }),
+      mirrorRegen: () => ({ ok: true }),
+      reviewer: () => ({ ok: true }),
+      acCheck: () => ({ ok: true }),
+      openPr: () => ({ ok: true }),
+      releaseSlot: () => {},
+      recomputeParent: () => {},
+      drain: () => {},
+      saveWork: () => ({ pushSucceeded: true }),
+      leftoverFiles: () => ({ forbiddenFiles: [], humanReviewFiles: [] }),
+      block: (details) => {
+        blockedQuestion = details.question;
+      },
+      blockKeepSlot: () => {},
+    });
+
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.equal(blockedQuestion, 'No pude confirmar el alcance exacto.\n\nstatus: needs-guidance');
+  });
+
+  // T-8 point 7: `close.ts`'s `checkBranchNotMerged` existed and was tested on its own, but nothing
+  // called it — a green attempt still ran straight into `open-pr`'s own commit-and-push even when
+  // the branch's PR was already merged (T-6.3's measured incident: two late commits pushed to an
+  // already-merged branch, lost silently because they never reached the parent). `runOnce` must ask
+  // BEFORE either push a close plan can make: the success path's `open-pr` step, and the failure
+  // path's `save-work` WIP commit.
+  it('asks checkBranchNotMerged before any push, and skips straight to blockKeepSlot when the PR is already merged', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    ctx.maintenance = { ...ctx.maintenance, gh: { isPrMerged: () => true } };
+
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.deepEqual(calls.slice(calls.indexOf('finishAttempt')), [
+      'finishAttempt',
+      'blockKeepSlot',
+      'stopHeartbeat',
+    ]);
+  });
+
+  it('proceeds through the normal success plan (openPr included) when the branch has no merged PR', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    ctx.maintenance = { ...ctx.maintenance, gh: { isPrMerged: () => false } };
+
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.ok(calls.includes('openPr'));
+    assert.ok(!calls.includes('blockKeepSlot'));
+  });
+});
+
+// ── J9: the close only runs while this pass still owns the task's lock ────────
+
+describe('runOnce — the close re-checks lock ownership before it runs', () => {
+  it('runs the whole close when the lock still names this pass', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()], currentPid: 4242 }, calls);
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.ok(calls.includes('openPr'));
+  });
+
+  // The single-flight lock is dropped as soon as the task is In Progress, so a maintenance sweep in
+  // ANOTHER pass can legitimately declare this worker dead, save its work, release its slot and
+  // hand it to the next task. Closing on top of that writes a PR, a status and a slot release over
+  // work that is no longer ours — against a worktree a different task is already using.
+  it('skips the close entirely when the lock is gone: the slot was swept and reassigned', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()], readLock: () => null }, calls);
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, { kind: 'dispatched', taskId: 'T-1', closeExecuted: [] });
+    for (const step of [
+      'scopeCheck',
+      'openPr',
+      'releaseSlot',
+      'block',
+      'blockKeepSlot',
+      'saveWork',
+    ]) {
+      assert.ok(!calls.includes(step), `${step} must not run once the lock is no longer ours`);
+    }
+  });
+
+  it('skips the close when the lock names a different reconciler pid', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        currentPid: 4242,
+        readLock: () => ({
+          taskId: 'T-1',
+          slot: 'dispatch-a',
+          pid: 9999,
+          startedAt: '2026-09-06T00:00:00.000Z',
+          heartbeatAt: '2026-09-06T00:00:00.000Z',
+          lane: LANE.LOCAL,
+          attempt: 1,
+          branch: 'task/T-1',
+        }),
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, { kind: 'dispatched', taskId: 'T-1', closeExecuted: [] });
+    assert.ok(!calls.includes('scopeCheck'));
+    assert.ok(!calls.includes('releaseSlot'));
+  });
+});
+
+// ── runOnce: single-flight release, the local model gate, and the stream sink ──
+
+describe('runOnce — releasing the single-flight lock before the worker runs', () => {
+  it('releases it right after the task is In Progress, so a second pass can dispatch in parallel', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    await runOnce(ctx);
+
+    assert.equal(calls[calls.indexOf('setInProgress') + 1], 'releaseSingleFlight');
+    assert.ok(
+      calls.indexOf('releaseSingleFlight') < calls.indexOf('spawnWorker'),
+      'holding the single-flight across the worker collapses the frontier cap of 2 to 1',
+    );
+  });
+
+  it('does not release it when a guard blocks the task — that pass owns the lock to its end', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask({ tier: undefined })] }, calls);
+    await runOnce(ctx);
+
+    assert.ok(!calls.includes('releaseSingleFlight'));
+  });
+});
+
+describe('runOnce — local-lane model readiness gate', () => {
+  it('blocks the task without consuming a slot or spawning anything when the model is not loaded', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      { tasks: [baseTask()], isLocalModelLoaded: async () => false },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, {
+      kind: 'blocked',
+      reason: 'local-model-not-loaded',
+      taskId: 'T-1',
+    });
+    assert.deepEqual(calls, ['onLocalModelMissing']);
+  });
+
+  it('dispatches normally when the model IS loaded', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.ok(calls.includes('isLocalModelLoaded'));
+    assert.ok(!calls.includes('onLocalModelMissing'));
+  });
+
+  it('never polls LM Studio for a frontier task — the gate is the local lane only', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      { tasks: [baseTask({ lane: LANE.FRONTIER, tier: TIER.MEDIUM })] },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.ok(!calls.includes('isLocalModelLoaded'));
+  });
+
+  // R2 (round 10): the permission-composition refusal used to be a throw inside `buildLaunch`,
+  // reached only after the slot was acquired, the lock written and the attempt directory opened —
+  // so a conflict a person has to resolve cost a worktree and an attempt. It is now guard 1b, and
+  // the evidence is that nothing was taken: no `updateSlots`, no `writeLock`, no `beginAttempt`.
+  it('blocks a frontier task whose test command a loaded settings rule swallows, taking no slot', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [
+          baseTask({
+            lane: LANE.FRONTIER,
+            tier: TIER.MEDIUM,
+            testCommand: 'pnpm test:hooks scripts/x.test.ts',
+          }),
+        ],
+        loadSettingsAllowRules: () => projectRules('Bash(pnpm test:hooks:*)'),
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, {
+      kind: 'blocked',
+      reason: 'permission-conflict',
+      taskId: 'T-1',
+    });
+    assert.ok(calls.includes('onBlock'));
+    for (const taken of ['updateSlots', 'writeLock', 'beginAttempt', 'spawnWorker']) {
+      assert.ok(!calls.includes(taken), `guard 1b must decide before ${taken}`);
+    }
+  });
+
+  // The same guard on the LOCAL lane, which now loads a settings source too (`--setting-sources
+  // user`). Measured T-5 defect: with no `--setting-sources` the launch got the DEFAULT set, so
+  // the user file, the project file AND the click-approval overlay all reached a `--bare` worker.
+  it('blocks a local task whose test command a loaded USER rule swallows, taking no slot', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask({ testCommand: 'pnpm test:hooks scripts/x.test.ts' })],
+        loadSettingsAllowRules: () => userRules('Bash(pnpm test:hooks:*)'),
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, {
+      kind: 'blocked',
+      reason: 'permission-conflict',
+      taskId: 'T-1',
+    });
+    assert.ok(calls.includes('onBlock'));
+    for (const taken of ['updateSlots', 'writeLock', 'beginAttempt', 'spawnWorker']) {
+      assert.ok(!calls.includes(taken), `guard 1b must decide before ${taken}`);
+    }
+  });
+
+  // And the loaded rules reach the LAUNCH, not just the guard: a click-approval the lane does not
+  // grant must come back out as a deny, or `--allowedTools` merely added to it.
+  it('denies a loaded user rule the local lane does not grant', async () => {
+    const calls: string[] = [];
+    let capturedArgs: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        loadSettingsAllowRules: () => userRules('Bash(python3 -c *)'),
+        spawnWorker: async (launch, onLine) => {
+          capturedArgs = launch.args;
+          calls.push('spawnWorker');
+          onLine('{"type":"result","subtype":"success","is_error":false}');
+        },
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.equal(capturedArgs[capturedArgs.indexOf('--setting-sources') + 1], 'user');
+    assert.ok(
+      capturedArgs[capturedArgs.indexOf('--disallowedTools') + 1].includes('Bash(python3 -c *)'),
+    );
+  });
+
+  it('launches a frontier task whose test command sits inside a rule the lane already grants', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [
+          baseTask({
+            lane: LANE.FRONTIER,
+            tier: TIER.MEDIUM,
+            testCommand: 'pnpm --filter aurora-back test',
+          }),
+        ],
+        loadFrontierSettings: () => ({
+          permissions: { allow: ['Read', 'Edit(./**)', 'Bash(pnpm --filter * test)'] },
+        }),
+        loadSettingsAllowRules: () =>
+          projectRules('Bash(pnpm test:hooks:*)', 'Bash(pnpm --filter aurora-back test:*)'),
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+  });
+
+  // L1: the frontier launch carried no system-prompt file at all. The addendum is rendered PER
+  // ATTEMPT (it names this task's id and its wrapper command), so the pass writes it and hands
+  // `buildLaunch` that path — a static skill file could not carry either.
+  it('renders this attempt frontier addendum and appends it as the worker system prompt', async () => {
+    const calls: string[] = [];
+    let capturedArgs: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask({ lane: LANE.FRONTIER, tier: TIER.MEDIUM })],
+        writeFrontierAddendum: (task, attempt) => {
+          calls.push('writeFrontierAddendum');
+          return `/dispatch/${task.id}/intento-${attempt}/frontier-addendum.md`;
+        },
+        spawnWorker: async (launch, onLine) => {
+          capturedArgs = launch.args;
+          calls.push('spawnWorker');
+          onLine('{"type":"result","subtype":"success","is_error":false}');
+        },
+      },
+      calls,
+    );
+    await runOnce(ctx);
+
+    assert.ok(calls.includes('writeFrontierAddendum'));
+    assert.equal(
+      capturedArgs[capturedArgs.indexOf('--append-system-prompt-file') + 1],
+      '/dispatch/T-1/intento-1/frontier-addendum.md',
+    );
+  });
+
+  it('checks readiness BEFORE the slot is prepared, not after', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    await runOnce(ctx);
+
+    assert.ok(calls.indexOf('isLocalModelLoaded') < calls.indexOf('runGit(reset --hard)'));
+  });
+});
+
+describe('runOnce — the attempt sink is the only line collector', () => {
+  it('opens the attempt directory before the worker starts, so backlog:watch can tail it live', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    await runOnce(ctx);
+
+    assert.ok(calls.indexOf('beginAttempt') < calls.indexOf('spawnWorker'));
+  });
+
+  it('classifies the outcome from the lines the sink collected, not from a separate buffer', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        // A budget-exhausted stream: reaching the close's success path would mean the classifier
+        // never saw the sink's lines at all.
+        spawnWorker: async (_launch, onLine) => {
+          calls.push('spawnWorker');
+          onLine('{"type":"result","subtype":"error_max_budget_usd"}');
+        },
+      },
+      calls,
+    );
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.deepEqual(calls.slice(calls.indexOf('spawnWorker')), [
+      'spawnWorker',
+      'finishAttempt',
+      // T-31 round 3: a session-level failure has no `scope-check` step, so `executeClose` asks the
+      // slot itself which files the attempt left behind, and of which kind — the `Blocked` comment
+      // is the only channel that path reaches.
+      'leftoverFiles',
+      'saveWork',
+      'block',
+      'releaseSlot',
+      'stopHeartbeat',
+    ]);
+  });
+
+  it('passes the sink onLine callback itself to spawnWorker', async () => {
+    const calls: string[] = [];
+    const fed: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        beginAttempt: () => ({
+          onLine: (line: string) => fed.push(line),
+          finish: () => ['{"type":"result","subtype":"success"}'],
+          stopHeartbeat: () => {},
+        }),
+        spawnWorker: async (_launch, onLine) => {
+          onLine('line one');
+          onLine('line two');
+        },
+      },
+      calls,
+    );
+    await runOnce(ctx);
+
+    assert.deepEqual(fed, ['line one', 'line two']);
+  });
+});
+
+describe('runOnce — persisting the acquired slot', () => {
+  it('writes slots.json as soon as the slot is taken, before any git command touches it', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
+    await runOnce(ctx);
+
+    assert.ok(
+      calls.indexOf('updateSlots') < calls.indexOf('runGit(reset --hard)'),
+      'every later collaborator resolves the task to its slot through slots.json',
+    );
+  });
+
+  it('records the task, its lane and this pass PID on the slot it took', async () => {
+    const written: SlotRegistry[] = [];
+    const ctx = recordingUpdates(makeRunOnceContext({ tasks: [baseTask()] }, []), written);
+    await runOnce(ctx);
+
+    assert.deepEqual(written[0].slots, [
+      {
+        name: 'dispatch-a',
+        path: '/slots/dispatch-a',
+        lane: LANE.LOCAL,
+        taskId: 'T-1',
+        pid: 4242,
+        lockfileHash: null,
+      },
+    ]);
+  });
+
+  it('leaves the other slots untouched, so a parallel pass keeps its own', async () => {
+    const written: SlotRegistry[] = [];
+    const twoSlots: SlotRegistry = {
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/dispatch-a',
+          lane: LANE.FRONTIER,
+          taskId: 'T-9',
+          pid: 99,
+          lockfileHash: 'h',
+        },
+        {
+          name: 'dispatch-b',
+          path: '/slots/dispatch-b',
+          lane: null,
+          taskId: null,
+          pid: null,
+          lockfileHash: null,
+        },
+      ],
+    };
+    // T-9 is listed and In Progress: a lock for a task the board does not carry reads as a
+    // cancellation, and the sweep would free the slot this test needs held by the other pass.
+    const ctx = recordingUpdates(
+      makeRunOnceContext(
+        {
+          tasks: [
+            baseTask(),
+            baseTask({ id: 'T-9', lane: LANE.FRONTIER, status: TASK_STATUS.IN_PROGRESS }),
+          ],
+          slots: twoSlots,
+        },
+        [],
+      ),
+      written,
+    );
+    await runOnce(ctx);
+
+    assert.deepEqual(written[0].slots[0], twoSlots.slots[0]);
+    assert.equal(written[0].slots[1].taskId, 'T-1');
+  });
+});
+
+// ── F7: the pass acts on the POST-maintenance registry ────────────────────────
+
+describe('runOnce — the registry maintenance returns', () => {
+  it('dispatches into a slot this very pass released, instead of waiting an interval for it', async () => {
+    // Occupied by a task whose lock is gone: the maintenance orphan sweep frees it. Reading the
+    // pre-maintenance snapshot instead would report `no-free-slot` for a slot that is already free.
+    const orphaned: SlotRegistry = {
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/dispatch-a',
+          lane: LANE.LOCAL,
+          taskId: 'T-9',
+          pid: 1,
+          lockfileHash: null,
+        },
+      ],
+    };
+    const written: SlotRegistry[] = [];
+    const ctx = recordingUpdates(
+      makeRunOnceContext({ tasks: [baseTask()], slots: orphaned }, []),
+      written,
+    );
+    ctx.maintenance.fs.readLocks = () => []; // no lock at all -> the slot is an orphan.
+
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.equal(
+      written[0].slots[0].taskId,
+      'T-1',
+      'the freed slot must be handed to the new task',
+    );
+  });
+
+  it('never resurrects a released slot: the write-back is built on the post-sweep registry', async () => {
+    const twoSlots: SlotRegistry = {
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/dispatch-a',
+          lane: LANE.LOCAL,
+          taskId: 'T-9',
+          pid: 1,
+          lockfileHash: null,
+        },
+        {
+          name: 'dispatch-b',
+          path: '/slots/dispatch-b',
+          lane: null,
+          taskId: null,
+          pid: null,
+          lockfileHash: null,
+        },
+      ],
+    };
+    const written: SlotRegistry[] = [];
+    const ctx = recordingUpdates(
+      makeRunOnceContext({ tasks: [baseTask()], slots: twoSlots }, []),
+      written,
+    );
+    ctx.maintenance.fs.readLocks = () => [];
+
+    await runOnce(ctx);
+
+    const dispatchA = written[0].slots.find((slot) => slot.name === 'dispatch-a');
+    assert.equal(dispatchA?.taskId, 'T-1', 'the released slot is the one the new task took');
+    const dispatchB = written[0].slots.find((slot) => slot.name === 'dispatch-b');
+    assert.equal(dispatchB?.taskId, null);
+  });
+});
+
+// ── F11: a branch another slot still holds ────────────────────────────────────
+
+describe('runOnce — the task branch is checked out in another slot', () => {
+  it('leaves the task Queued and hands the slot back, rather than throwing out of the pass', async () => {
+    const calls: string[] = [];
+    const written: SlotRegistry[] = [];
+    const ctx = recordingUpdates(
+      makeRunOnceContext(
+        { tasks: [baseTask()], branchesCheckedOutElsewhere: ['task/T-1'] },
+        calls,
+      ),
+      written,
+    );
+
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, { kind: 'waiting', reason: 'branch-in-use', taskId: 'T-1' });
+    assert.ok(!calls.includes('spawnWorker'));
+    assert.equal(written.at(-1)?.slots[0].taskId, null, 'the slot must go back to the pool');
+  });
+
+  // H1: a slot handed back while still on `task/T-nn` makes the NEXT dispatch of that task hit
+  // `branch-in-use` too — the very condition this path exists to recover from, now permanent.
+  it('detaches the slot it hands back, so the branch is free for whoever holds it', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      { tasks: [baseTask()], branchesCheckedOutElsewhere: ['task/T-1'] },
+      calls,
+    );
+
+    await runOnce(ctx);
+
+    assert.ok(calls.includes('runGit(checkout --detach)'), 'the handback must detach the slot');
+  });
+});
+
+// ── G5: a step between taking the slot and spawning the worker throws ─────────
+
+describe('runOnce — the acquisition-to-spawn span aborts cleanly', () => {
+  for (const failing of [
+    'provisionSlot',
+    'runGit',
+    'beginAttempt',
+    'buildPrompt',
+    'spawnWorker',
+  ] as const) {
+    it(`releases the slot, removes the lock and blocks the task when ${failing} throws`, async () => {
+      const calls: string[] = [];
+      const written: SlotRegistry[] = [];
+      const boom = (): never => {
+        throw new Error(`${failing} exploded`);
+      };
+      const ctx = recordingUpdates(
+        makeRunOnceContext(
+          {
+            tasks: [baseTask()],
+            ...(failing === 'provisionSlot' ? { provisionSlot: boom } : {}),
+            ...(failing === 'runGit' ? { runGit: boom } : {}),
+            ...(failing === 'beginAttempt' ? { beginAttempt: boom } : {}),
+            ...(failing === 'buildPrompt' ? { buildPrompt: boom } : {}),
+            ...(failing === 'spawnWorker' ? { spawnWorker: boom } : {}),
+          },
+          calls,
+        ),
+        written,
+      );
+
+      const result = await runOnce(ctx);
+
+      assert.deepEqual(result.outcome, {
+        kind: 'blocked',
+        reason: 'dispatch-failed',
+        taskId: 'T-1',
+      });
+      assert.ok(calls.includes('removeLock'), 'the dispatch lock must not outlive the failed span');
+      assert.ok(calls.includes('onDispatchFailure'), 'the task must say why it stopped');
+      assert.equal(written.at(-1)?.slots[0].taskId, null, 'the slot must go back to the pool');
+    });
+  }
+
+  // H1: the abort path released the slot but left it on the task branch, so every later dispatch
+  // of that task refused with `branch-in-use` and the single-task-per-pass queue starved behind it.
+  it('detaches the slot before releasing it, so the aborted task can be dispatched again', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        beginAttempt: () => {
+          throw new Error('the attempt directory could not be opened');
+        },
+      },
+      calls,
+    );
+
+    await runOnce(ctx);
+
+    assert.ok(calls.includes('runGit(checkout --detach)'), 'the abort must detach the slot');
+  });
+
+  it('stops the heartbeat when the span aborts after the attempt sink was opened', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      {
+        tasks: [baseTask()],
+        spawnWorker: () => {
+          throw new Error('claude is not installed');
+        },
+      },
+      calls,
+    );
+
+    await runOnce(ctx);
+
+    assert.ok(
+      calls.includes('stopHeartbeat'),
+      'an aborted span must not leave a timer beating forever',
+    );
+  });
+});
+
+// ── G12: guards see the board AFTER maintenance, not before ──────────────────
+
+describe('runOnce — the board is re-read after maintenance', () => {
+  it('dispatches a task whose dependency this very pass moved to Done', async () => {
+    const calls: string[] = [];
+    const dependency = baseTask({ id: 'T-2', status: TASK_STATUS.IN_PROGRESS });
+    const dependent = baseTask({ id: 'T-3', dependsOn: ['T-2'] });
+
+    // The board as maintenance receives it: T-2 is still In Progress. Its PR is merged, so the
+    // sweep moves it to Done — and only a re-read shows that to guard 3.
+    let swept = false;
+    const ctx = makeRunOnceContext({ tasks: [dependency, dependent] }, calls);
+    ctx.maintenance.gh = {
+      isPrMerged: (branch) => {
+        if (branch === 'task/T-2') {
+          swept = true;
+          return true;
+        }
+        return false;
+      },
+    };
+    ctx.reloadTasks = () => ({
+      tasks: [swept ? { ...dependency, status: TASK_STATUS.DONE } : dependency, dependent],
+      complete: true,
+    });
+
+    const result = await runOnce(ctx);
+
+    assert.equal(result.outcome.kind, 'dispatched');
+    assert.deepEqual(result.maintenance.movedToDone, ['T-2']);
+  });
+
+  it('still waits when the dependency is unfinished after the sweep', async () => {
+    const calls: string[] = [];
+    const dependency = baseTask({ id: 'T-2', status: TASK_STATUS.IN_PROGRESS });
+    const dependent = baseTask({ id: 'T-3', dependsOn: ['T-2'] });
+    const ctx = makeRunOnceContext({ tasks: [dependency, dependent] }, calls);
+
+    const result = await runOnce(ctx);
+
+    assert.deepEqual(result.outcome, {
+      kind: 'waiting',
+      reason: 'dependency-not-done',
+      taskId: 'T-3',
+    });
+  });
+});
+
+// ── T-6.1: the "pass complete" log line must name WHICH task and WHY ─────────
+//
+// Before this, `dispatch.ts` logged only the outcome KIND — every wait and every block collapsed
+// into the same bare word (`outcome=waiting`), so a task stuck behind an undeclared dependency
+// looked identical in the log to one waiting on a free slot, with no task id to even look up.
+describe('formatOutcome', () => {
+  it('names the task and the reason for a waiting outcome', () => {
+    assert.equal(
+      formatOutcome({ kind: 'waiting', reason: 'dependency-not-done', taskId: 'T-6.1' }),
+      'waiting (T-6.1: dependency-not-done)',
+    );
+  });
+
+  it('names the task and the reason for a blocked outcome', () => {
+    assert.equal(
+      formatOutcome({ kind: 'blocked', reason: 'security-path-on-local', taskId: 'T-2' }),
+      'blocked (T-2: security-path-on-local)',
+    );
+  });
+
+  it('names the task for a dispatched outcome', () => {
+    assert.equal(
+      formatOutcome({ kind: 'dispatched', taskId: 'T-1', closeExecuted: [] }),
+      'dispatched (T-1)',
+    );
+  });
+
+  it('reports the bare kind for the two outcomes that carry no task at all', () => {
+    assert.equal(formatOutcome({ kind: 'skipped-by-guard' }), 'skipped-by-guard');
+    assert.equal(formatOutcome({ kind: 'no-queued-task' }), 'no-queued-task');
+  });
+});