@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

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

@@ -0,0 +1,2607 @@
+/**
+ * TDD spec for the close runners `scripts/backlog/dispatch.ts` wires (G3).
+ *
+ * Runner: `node --import tsx --test scripts/backlog/dispatch.test.ts`
+ *
+ * `dispatch.ts` is otherwise the wiring file its own header describes — every decision lives in the
+ * pure modules it composes, tested there. What IS tested here is the one invariant that only exists
+ * at the wiring level: the runners must resolve their working directory to the task's WORKTREE
+ * SLOT, and must fail the step when no slot holds the task rather than falling back to the main
+ * checkout. That fallback made every runner operate on the developer's own working tree — a
+ * `git add -A` + WIP commit over work in progress, a scope diff of somebody else's changes, and a
+ * `gh pr create` off whatever branch happened to be checked out.
+ *
+ * The slot lookup and the command runner are injected, so this suite spawns nothing.
+ */
+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 {
+  BOARD_WRITE_RETRY_DEFAULTS,
+  buildCloseRunners,
+  buildHookRunners,
+  describeExecFailure,
+  findSlotPathForTask,
+  ghEnv,
+  loadBoard,
+  parseReleaseSlotArg,
+  realBacklog,
+  realGh,
+  realGit,
+  realMaintenanceFs,
+  releaseSlotByName,
+  resolveWorkerSystemPromptPath,
+  tickOwnedDod,
+  withBoardWriteRetry,
+} from './dispatch.js';
+import { type SingleFlightResult } from './entry.js';
+import { REMOTE_BRANCH_DELETE_RESULT } from './maintenance.js';
+import {
+  EXECUTION_PATH,
+  LANE,
+  TASK_STATUS,
+  TIER,
+  type DispatchLock,
+  type SlotRegistry,
+  type Task,
+} from './types.js';
+
+/**
+ * H9: a hard-coded path to the developer's REAL checkout. `saveWork` resolved its slot by reading
+ * that checkout's `slots.json` and then shelled out to a real `git` — so on a machine where the
+ * dispatcher had ever run, the suite could `git add -A` in a live worktree. Every path this suite
+ * uses is a temp directory, and every command runner is injected.
+ */
+const MAIN_CHECKOUT = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-main-'));
+
+const task = (overrides: Partial<Task> = {}): Task => ({
+  id: 'T-1',
+  status: TASK_STATUS.IN_PROGRESS,
+  title: 'A task',
+  tier: TIER.MINOR,
+  lane: LANE.LOCAL,
+  path: EXECUTION_PATH.DIRECT,
+  filesToTouch: ['scripts/backlog/dispatch.ts'],
+  testCommand: 'pnpm test:backlog',
+  acceptanceCriteria: [],
+  definitionOfDone: [],
+  dependsOn: [],
+  attempts: 1,
+  priority: 0,
+  createdAt: 0,
+  updatedAt: 0,
+  ...overrides,
+});
+
+/**
+ * The board text the injected `viewTask` returns — it must MATCH the fixture task above, since the
+ * close's integrity gate compares the view against the launch snapshot (status, checklists, title,
+ * declared files and test command). A view that drifts from the snapshot short-circuits every step
+ * this suite is actually about.
+ */
+const boardView = (status = 'In Progress'): string =>
+  [
+    'Task T-1 - A task',
+    '',
+    `Status: ${status}`,
+    '',
+    'Files to touch: scripts/backlog/dispatch.ts',
+    'Test command: pnpm test:backlog',
+    '',
+  ].join('\n');
+
+interface RunCall {
+  command: string;
+  args: string[];
+  cwd: string;
+}
+
+function runnersWithoutSlot(recorded: RunCall[]) {
+  return buildCloseRunners({
+    mainCheckoutPath: MAIN_CHECKOUT,
+    repoRoot: MAIN_CHECKOUT,
+    task: task(),
+    attempt: 1,
+    branch: 'task/T-1',
+    reviewerModel: 'sonnet',
+    reviewerTimeoutMs: 15 * 60_000,
+    requestDrain: () => {},
+    tasksById: {},
+    boardComplete: true,
+    slotPathFor: () => null,
+    run: (command, args, options) => {
+      recorded.push({ command, args, cwd: options.cwd });
+      return '';
+    },
+    runCapturing: (command, args, cwd) => {
+      recorded.push({ command, args, cwd });
+      return { status: 0, output: '' };
+    },
+    // The board reads are injected too, so the runners that only touch the board can be driven here
+    // instead of being left out of the sweep below. `In Progress` with the same (empty) checklists
+    // the fixture task carries is what the integrity gate expects, so it passes rather than
+    // short-circuiting the steps this suite is about.
+    viewTask: () => boardView(),
+  });
+}
+
+describe('findSlotPathForTask', () => {
+  function checkoutWithRegistry(registry: SlotRegistry | null): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-checkout-'));
+    if (registry) {
+      fs.mkdirSync(path.join(root, '.backlog', '.dispatch'), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, '.backlog', '.dispatch', 'slots.json'),
+        JSON.stringify(registry),
+      );
+    }
+    return root;
+  }
+
+  it('returns the slot path recorded for the task', () => {
+    const root = checkoutWithRegistry({
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/a',
+          lane: LANE.LOCAL,
+          taskId: 'T-1',
+          pid: 1,
+          lockfileHash: null,
+        },
+      ],
+    });
+    assert.equal(findSlotPathForTask(root, 'T-1'), '/slots/a');
+  });
+
+  it('returns null — never the main checkout — when the registry holds no slot for the task', () => {
+    const root = checkoutWithRegistry({
+      slots: [
+        {
+          name: 'dispatch-a',
+          path: '/slots/a',
+          lane: null,
+          taskId: null,
+          pid: null,
+          lockfileHash: null,
+        },
+      ],
+    });
+    assert.equal(findSlotPathForTask(root, 'T-1'), null);
+  });
+
+  it('returns null — never the main checkout — when slots.json does not exist yet', () => {
+    assert.equal(findSlotPathForTask(checkoutWithRegistry(null), 'T-1'), null);
+  });
+});
+
+/**
+ * Measured defect (T-5, 2026-09-07): the reviewer step failed with `El revisor no se pudo
+ * ejecutar: Error: Command failed: claude -p …` and nothing else, so `review.md` said only that a
+ * subprocess died. The reason was in the child's stderr, which nobody rendered — the same defect
+ * `describeExecFailure` was written for, applied to the one runner that spawns `claude`.
+ */
+describe('buildCloseRunners — the reviewer failure carries the child stderr', () => {
+  it('renders the reviewer subprocess stderr into the step question and into review.md', () => {
+    const slot = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const attemptDir = path.join(MAIN_CHECKOUT, '.backlog', '.dispatch', 'T-1', 'intento-1');
+    fs.mkdirSync(attemptDir, { recursive: true });
+
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slot,
+      // `git` answers (the diff collection), `claude` throws the way `execFileSync` does: an Error
+      // whose `message` is generic and whose `stderr` holds the only useful text.
+      run: (command) => {
+        if (command === 'claude') {
+          throw Object.assign(new Error('Command failed: claude -p …'), {
+            stderr:
+              'claude.ai connectors are disabled because ANTHROPIC_API_KEY or another auth source is set',
+          });
+        }
+        return 'diff --git a/x.ts b/x.ts\n+const a = 1;';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+    });
+
+    const result = runners.reviewer();
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'reviewer-failed');
+    assert.match(result.question ?? '', /ANTHROPIC_API_KEY or another auth source is set/);
+    assert.match(
+      fs.readFileSync(path.join(attemptDir, 'review.md'), 'utf8'),
+      /another auth source is set/,
+    );
+  });
+});
+
+// R3: `formatLintTest`'s `collectChangedFiles` catch, the reviewer's `collectAttemptDiff` catch,
+// and `openPr`'s catch-all rendered a failing git/gh call through bare `String(error)` — a plain
+// `execFileSync` throw whose `message` is generic ("Command failed: git …") and whose `stderr`
+// holds the only useful text, exactly the defect `describeExecFailure` was written to fix
+// elsewhere (the reviewer's own subprocess, see above). None of these three call sites folded
+// stderr in, so the same silent-cause failure could still reach a `Blocked` comment.
+describe('buildCloseRunners — R3: git/gh stderr reaches the step question', () => {
+  it('formatLintTest renders the failing git call stderr into the question', () => {
+    const slot = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slot,
+      run: () => {
+        throw Object.assign(new Error('Command failed: git diff --name-only'), {
+          stderr: 'fatal: no se pudo leer el arbol de trabajo',
+        });
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+    });
+
+    const result = runners.formatLintTest();
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'format-lint-test-failed');
+    assert.match(result.question ?? '', /no se pudo leer el arbol de trabajo/);
+  });
+
+  it('reviewer renders the failing diff-collection git call stderr into the question', () => {
+    const slot = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slot,
+      run: (command) => {
+        if (command === 'git') {
+          throw Object.assign(new Error('Command failed: git add -N -A -- .'), {
+            stderr: 'fatal: index file corrupt',
+          });
+        }
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+    });
+
+    const result = runners.reviewer();
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'reviewer-failed');
+    assert.match(result.question ?? '', /index file corrupt/);
+  });
+
+  it('openPr puts the failing command stderr in the question, not just its bare message', () => {
+    const slot = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slot,
+      run: (command, args) => {
+        if (command === 'git' && args[0] === 'push') {
+          throw Object.assign(new Error('Command failed: git push'), {
+            stderr: '! [rejected] task/T-1 -> task/T-1 (non-fast-forward)',
+          });
+        }
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    });
+
+    const result = runners.openPr();
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'open-pr-failed');
+    assert.match(result.question ?? '', /non-fast-forward/);
+  });
+});
+
+/**
+ * The `mirror-regen` wiring. Measured defect (PR #96, dispatched task T-3): a worker edited
+ * `backend/src/@app/iam/**` and `frontend/.../iam/**`, both packager-mirrored roots, and the PR
+ * failed CI's `Check mirror <-> source drift`. The worker could not fix it — `packages/cli/` is
+ * forbidden to it — and no close step regenerated the mirror, so the task could never pass CI.
+ *
+ * The decision itself (which roots, when to run) is `close.ts`'s and is tested there; what is wired
+ * HERE is the slot resolution, the workflow read from the slot, the packager invocation and the
+ * stderr rendering.
+ */
+describe('buildCloseRunners — mirrorRegen', () => {
+  function slotWithDriftCheck(paths: readonly string[]): string {
+    const slot = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    fs.mkdirSync(path.join(slot, '.github', 'workflows'), { recursive: true });
+    fs.writeFileSync(
+      path.join(slot, '.github', 'workflows', 'cli-template-drift-check.yml'),
+      [
+        'on:',
+        '  pull_request:',
+        '    paths:',
+        ...paths.map((entry) => `      - '${entry}'`),
+        '',
+      ].join('\n'),
+    );
+    return slot;
+  }
+
+  function runnersFor(slot: string, run: (command: string, args: string[], cwd: string) => string) {
+    return buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slot,
+      run: (command, args, options) => run(command, args, options.cwd),
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+    });
+  }
+
+  it('runs the packager IN THE SLOT when the attempt touched a mirrored root', () => {
+    const slot = slotWithDriftCheck(['backend/**', 'frontend/**']);
+    const recorded: RunCall[] = [];
+    const runners = runnersFor(slot, (command, args, cwd) => {
+      recorded.push({ command, args, cwd });
+      return command === 'git' && args[0] === 'diff' ? 'backend/src/@app/iam/x.ts\0' : '';
+    });
+
+    const result = runners.mirrorRegen();
+
+    assert.equal(result.ok, true);
+    const packagerCalls = recorded.filter((call) => call.command === 'node');
+    assert.deepEqual(
+      packagerCalls,
+      [{ command: 'node', args: ['scripts/packager/publish.mjs'], cwd: slot }],
+      'the mirror is regenerated exactly once, in the slot — never in the main checkout',
+    );
+  });
+
+  it('never runs the packager when the attempt touched nothing mirrored', () => {
+    const slot = slotWithDriftCheck(['backend/**', 'frontend/**']);
+    const recorded: RunCall[] = [];
+    const runners = runnersFor(slot, (command, args, cwd) => {
+      recorded.push({ command, args, cwd });
+      return command === 'git' && args[0] === 'diff' ? 'openspec/changes/x/design.md\0' : '';
+    });
+
+    assert.equal(runners.mirrorRegen().ok, true);
+    assert.deepEqual(
+      recorded.filter((call) => call.command === 'node'),
+      [],
+    );
+  });
+
+  it('blocks with the packager own stderr when the regen fails', () => {
+    const slot = slotWithDriftCheck(['backend/**']);
+    const runners = runnersFor(slot, (command, args) => {
+      if (command === 'node') {
+        throw Object.assign(new Error('Command failed: node scripts/packager/publish.mjs'), {
+          stderr: "Error: ENOENT: no such file or directory, scandir 'frontend/src'",
+        });
+      }
+      return args[0] === 'diff' ? 'backend/src/@app/iam/x.ts\0' : '';
+    });
+
+    const result = runners.mirrorRegen();
+
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'mirror-regen-failed');
+    assert.match(result.question ?? '', /ENOENT: no such file or directory/);
+  });
+
+  // A generated project ships `scripts/backlog/**` but neither `.github/**` nor the packager, so
+  // there is no mirror there and no gate to satisfy. Failing every close in a scaffolded project
+  // would be this repository's CI ringing an alarm in someone else's.
+  it('skips silently in a repo with no drift-check workflow', () => {
+    const slot = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const recorded: RunCall[] = [];
+    const runners = runnersFor(slot, (command, args, cwd) => {
+      recorded.push({ command, args, cwd });
+      return '';
+    });
+
+    assert.equal(runners.mirrorRegen().ok, true);
+    assert.deepEqual(recorded, [], 'no gate, nothing to ask git about and nothing to regenerate');
+  });
+});
+
+describe('buildCloseRunners — no slot holds the task', () => {
+  for (const step of [
+    'scopeCheck',
+    'formatLintTest',
+    'mirrorRegen',
+    'reviewer',
+    'openPr',
+  ] as const) {
+    it(`fails ${step} instead of running it against the main checkout`, () => {
+      const recorded: RunCall[] = [];
+      const result = runnersWithoutSlot(recorded)[step]();
+
+      assert.equal(result.ok, false, `${step} must not report success with no slot`);
+      assert.match(result.question ?? '', /slot/i, 'the block comment must say why');
+      assert.deepEqual(recorded, [], `${step} must run no command at all`);
+    });
+  }
+
+  // J15: the four steps above are the ones that shell out to the slot, but the claim in this
+  // suite's header is about EVERY runner. `boardCheck`, `acCheck` and `recomputeParent` read the
+  // board rather than the slot, and were simply never called here — so "across every runner" was
+  // asserted over a subset. With `viewTask` injected they run for real and are covered.
+  it('never runs a command whose cwd is the main checkout, across every runner', () => {
+    const recorded: RunCall[] = [];
+    const runners = runnersWithoutSlot(recorded);
+
+    runners.boardCheck();
+    runners.scopeCheck();
+    runners.formatLintTest();
+    runners.mirrorRegen();
+    runners.reviewer();
+    runners.acCheck();
+    runners.openPr();
+    runners.recomputeParent();
+    const saved = runners.saveWork();
+
+    assert.equal(
+      saved.pushSucceeded,
+      false,
+      'there is no work to save, and saving would commit the main checkout',
+    );
+    assert.deepEqual(
+      recorded.filter((call) => call.cwd === MAIN_CHECKOUT),
+      [],
+    );
+  });
+
+  // The PR title comes off the board too. `openPr` fails on the missing slot before it gets there,
+  // which is the point: no board read can put the dispatcher back in the main checkout.
+  it('reads the board through the injected view, never by spawning backlog itself', () => {
+    const views: string[] = [];
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => null,
+      run: () => '',
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: (taskId) => {
+        views.push(taskId);
+        return boardView();
+      },
+    });
+
+    assert.deepEqual(runners.boardCheck(), { ok: true });
+    assert.deepEqual(views, ['T-1']);
+  });
+
+  // J5(c): the integrity gate is what stands between a self-promoted task and its PR.
+  it('fails boardCheck when the board no longer says In Progress', () => {
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => null,
+      run: () => '',
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView('Done'),
+    });
+
+    const result = runners.boardCheck();
+    assert.equal(result.ok, false);
+    assert.equal(result.reason, 'status-changed-by-worker');
+  });
+});
+
+// H5/H9: `saveWork` is the one runner that used to build its own collaborators instead of taking
+// the injected ones. Both properties are asserted through the SAME injected runner, so a revert to
+// `realGit(mainCheckoutPath)` records nothing and fails here rather than running git for real.
+describe('buildCloseRunners — saving work', () => {
+  function runnersWithSlot(slotPath: string, recorded: RunCall[], run?: (call: RunCall) => void) {
+    return buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        const call = { command, args, cwd: options.cwd };
+        recorded.push(call);
+        run?.(call);
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+    });
+  }
+
+  it('commits and pushes through the INJECTED runner, inside the slot', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+
+    const result = runnersWithSlot(slotPath, recorded).saveWork();
+
+    assert.equal(result.pushSucceeded, true);
+    assert.deepEqual(
+      recorded.map((call) => [call.command, call.args[0]]),
+      [
+        ['git', 'add'],
+        ['git', 'commit'],
+        ['git', 'push'],
+      ],
+      'saveWork must run every git command through the injected runner, never its own execFileSync',
+    );
+    assert.deepEqual(new Set(recorded.map((call) => call.cwd)), new Set([slotPath]));
+  });
+
+  // H5: the hooks a commit would run are files in the SLOT's working tree — the very tree the
+  // worker has been writing in. `--no-verify` is what keeps the dispatcher from executing them.
+  it('commits with --no-verify, so a worker-authored hook never runs as the dispatcher', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+
+    runnersWithSlot(slotPath, recorded).saveWork();
+
+    const commit = recorded.find((call) => call.args[0] === 'commit');
+    assert.ok(
+      commit?.args.includes('--no-verify'),
+      'the WIP auto-save commit must bypass the slot hooks',
+    );
+  });
+
+  // H5: the green path commits in the slot too, so it carries the same flag. The `gh` call is made
+  // to throw so the assertion stops at the commit — nothing notifies, nothing shells out further.
+  it('opens the PR with a --no-verify commit, for the same reason', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+
+    const result = runnersWithSlot(slotPath, recorded, (call) => {
+      if (call.command === 'gh') {
+        throw new Error('gh: not reached in this test');
+      }
+    }).openPr();
+
+    assert.equal(result.ok, false, 'the injected gh failure is what stops this test short');
+    const commit = recorded.find((call) => call.args[0] === 'commit');
+    assert.ok(
+      commit?.args.includes('--no-verify'),
+      'the attempt commit must bypass the slot hooks',
+    );
+  });
+
+  it('reports a failed push instead of throwing out of the close', () => {
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const result = runnersWithSlot(slotPath, [], (call) => {
+      if (call.args[0] === 'push') {
+        throw new Error('failed to push some refs');
+      }
+    }).saveWork();
+
+    assert.equal(result.pushSucceeded, false);
+  });
+});
+
+// T-31 round 3: the record for a failure no `scope-check` preceded. `needs-guidance`, a timeout, an
+// exhausted budget and a crash all plan straight to `save-work` (and `board-check` diverts before the
+// scope check), so nothing reports the leftover files — while the tree those failures leave behind IS
+// pushed to `task/<id>` and restored into the slot by the retry. This runner is where `executeClose`
+// gets them from on those paths.
+describe('buildCloseRunners — leftoverFiles', () => {
+  function runnersReading(
+    slotPath: string | null,
+    gitOutput: string,
+    recorded: RunCall[],
+    overrides: Partial<Task> = {},
+  ) {
+    return buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(overrides),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd });
+        return command === 'git' && args[0] === 'diff' ? gitOutput : '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+    });
+  }
+
+  // The fixture task is `lane: local`, where `scripts/` is a refused extra: `scripts/backlog/close.ts`
+  // is therefore a forbidden leftover on THIS lane and a soft one on the frontier lane, and the record
+  // says which — it asks the same classifier `checkScope` asks, per lane.
+  it('classifies the slot diff into the two kinds, reading inside the slot', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+
+    const record = runnersReading(
+      slotPath,
+      'scripts/backlog/close.ts\0backend/src/@app/iam/x.ts\0packages/cli/src/index.ts\0',
+      recorded,
+    ).leftoverFiles();
+
+    assert.deepEqual(record.forbiddenFiles, [
+      'scripts/backlog/close.ts',
+      'backend/src/@app/iam/x.ts',
+    ]);
+    assert.deepEqual(record.humanReviewFiles, ['packages/cli/src/index.ts']);
+    assert.deepEqual(new Set(recorded.map((call) => call.cwd)), new Set([slotPath]));
+  });
+
+  it('reports the same diff on the frontier lane by that lane own criteria', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+
+    const record = runnersReading(
+      slotPath,
+      'scripts/backlog/close.ts\0.claude/settings.json\0',
+      recorded,
+      { lane: LANE.FRONTIER },
+    ).leftoverFiles();
+
+    assert.deepEqual(record.forbiddenFiles, ['.claude/settings.json']);
+    assert.deepEqual(record.humanReviewFiles, ['scripts/backlog/close.ts']);
+  });
+
+  // T-31 round 4: the base ref was asserted nowhere — replacing it with a hardcoded `origin/main`
+  // left the suite green. For a SUBTASK the base is the parent's branch, and `origin/main` would
+  // report every file the parent already changed as this attempt's leftovers.
+  it('diffs against the task own base ref, the parent branch for a subtask', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+
+    runnersReading(slotPath, '', recorded, { parentId: 'T-10' }).leftoverFiles();
+
+    assert.deepEqual(recorded[0].args, [
+      'diff',
+      '--name-only',
+      '-z',
+      'origin/task/T-10...HEAD',
+    ]);
+    assert.deepEqual(recorded[1].args, ['status', '--porcelain', '-z', '--untracked-files=all']);
+  });
+
+  it('diffs a top-level task against origin/main', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+
+    runnersReading(slotPath, '', recorded).leftoverFiles();
+
+    assert.deepEqual(recorded[0].args, ['diff', '--name-only', '-z', 'origin/main...HEAD']);
+  });
+
+  it('reports none when no slot holds the task, running no command at all', () => {
+    const recorded: RunCall[] = [];
+    assert.deepEqual(
+      runnersReading(null, 'scripts/backlog/close.ts\0', recorded).leftoverFiles(),
+      { forbiddenFiles: [], humanReviewFiles: [] },
+    );
+    assert.deepEqual(recorded, []);
+  });
+});
+
+// T-31 round 3: the executor's own system prompt is an INSTRUCTION channel, and `launch.ts` spawns
+// the worker with `cwd` = the slot. A relative `--append-system-prompt-file` therefore read the
+// worker's brief FROM the slot — a file the attempt can write, and one `--bare` does not close,
+// because the flag is explicit. The frontier lane already hands over an absolute path.
+describe('resolveWorkerSystemPromptPath', () => {
+  it('resolves the worker system prompt against the repo root, so the slot cannot supply it', () => {
+    const resolved = resolveWorkerSystemPromptPath('/repos/aurora-catalyst');
+    assert.ok(path.isAbsolute(resolved), 'a relative path would be read from the slot');
+    assert.equal(
+      resolved,
+      path.join('/repos/aurora-catalyst', '.claude/skills/catalyst-backlog/worker-system-prompt.md'),
+    );
+    assert.ok(
+      !resolved.includes('.claude/worktrees'),
+      'it must never resolve inside a dispatch slot',
+    );
+  });
+});
+
+describe('buildCloseRunners — a slot holds the task', () => {
+  it('runs the scope check inside the slot, never in the main checkout', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd });
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+    });
+
+    assert.deepEqual(runners.scopeCheck(), { ok: true, humanReviewFiles: [] });
+    assert.ok(recorded.length > 0);
+    assert.deepEqual(new Set(recorded.map((call) => call.cwd)), new Set([slotPath]));
+  });
+
+  // Fix round B3: `resolveBaseRef(task, tasksById)` at this module's own `buildCloseRunners` — the
+  // `base` every mechanical step diffs against — is invisible to the type checker (no `tsc` runs
+  // over `scripts/` in CI) and every OTHER fixture in this file uses a top-level task, so deleting
+  // the `tasksById` argument stayed green everywhere else. A subtask's parent DECLARED branch (T-15)
+  // must reach the actual `git diff`, not just `close.ts`'s own unit tests for the pure function.
+  it("diffs the scope check against the parent's DECLARED branch, not task/<parentId>", () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task({ id: 'T-1.1', parentId: 'T-0' }),
+      attempt: 1,
+      branch: 'task/T-1.1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: { 'T-0': task({ id: 'T-0', declaredBranch: 'fix/parent-branch-resolution' }) },
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd });
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+    });
+
+    runners.scopeCheck();
+
+    const diffCall = recorded.find(
+      (call) => call.command === 'git' && call.args[0] === 'diff' && call.args[1] === '--name-only',
+    );
+    assert.ok(diffCall, `expected a scoped git diff; got: ${JSON.stringify(recorded)}`);
+    // The whole argv, not `args[2]`: T-31 inserted `-z` ahead of the range, and an index-addressed
+    // assertion followed the wrong element instead of failing on the shift.
+    assert.deepEqual(diffCall.args, [
+      'diff',
+      '--name-only',
+      '-z',
+      'origin/fix/parent-branch-resolution...HEAD',
+    ]);
+  });
+});
+
+// P5 (round 9): the maintenance sweep already refuses to derive a parent from half a board
+// (`boardComplete`), because a derivation over some of the children produces a confident wrong
+// answer — a parent moved to `Done` while an unread child is still running. The CLOSE derives the
+// same parent from the same kind of read, and `reloadTasks` was dropping the `complete` flag the
+// re-read came with, so the close derived from a partial board with nothing to stop it.
+describe('buildCloseRunners — recomputeParent and a partially read board', () => {
+  function runnersWithBoardComplete(boardComplete: boolean, views: string[]) {
+    return buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task({ parentId: 'T-0' }),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete,
+      slotPathFor: () => null,
+      run: () => '',
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: (taskId) => {
+        views.push(taskId);
+        return boardView();
+      },
+    });
+  }
+
+  // The child's status is re-read from the board before the derivation, so an untouched `viewTask`
+  // is the observable proof the step never started.
+  it('skips the derivation entirely when the post-sweep board read was incomplete', () => {
+    const views: string[] = [];
+    runnersWithBoardComplete(false, views).recomputeParent();
+    assert.deepEqual(views, [], 'a partial board must not be derived from at all');
+  });
+
+  it('derives as usual when the board read was complete', () => {
+    const views: string[] = [];
+    runnersWithBoardComplete(true, views).recomputeParent();
+    assert.deepEqual(views, ['T-1'], 'the child status must be re-read before deriving the parent');
+  });
+});
+
+// K3: `openPr` went straight to `pr create`, which on a retry hit "a pull request for branch …
+// already exists" and failed the close — with the code pushed and a usable PR already open. It now
+// asks first, and only creates when there is nothing to reuse.
+describe('buildCloseRunners — openPr and the PR already on the branch', () => {
+  function openPrWith(recorded: RunCall[], gh: (args: string[]) => string) {
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    return buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 2,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd });
+        return command === 'gh' ? gh(args) : '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      // Otherwise the success path pops a real macOS notification for every run of this suite.
+      runOsascript: () => {},
+    }).openPr();
+  }
+
+  it('reuses the open PR instead of failing on a duplicate create', () => {
+    const recorded: RunCall[] = [];
+    const result = openPrWith(recorded, (args) => {
+      assert.deepEqual(args, ['pr', 'view', 'task/T-1', '--json', 'url,state']);
+      return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+    });
+
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/7' });
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args[1] === 'create'),
+      'a branch that already has an open PR must not be asked to create a second one',
+    );
+  });
+
+  it('creates the PR when gh reports none on the branch', () => {
+    const recorded: RunCall[] = [];
+    const result = openPrWith(recorded, (args) => {
+      if (args[1] === 'view') {
+        throw new Error('no pull requests found for branch "task/T-1"');
+      }
+      return 'https://github.com/o/r/pull/8\n';
+    });
+
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/8' });
+    const created = recorded.find((call) => call.command === 'gh' && call.args[1] === 'create');
+    assert.ok(created, 'with no PR to reuse, the close must create one');
+  });
+
+  // Fix round B3: `tasksById` threaded into the `buildPrCreateArgs` call this module makes (K3's
+  // `openPr` runner) — invisible to the type checker (no `tsc` runs over `scripts/` in CI), and
+  // every other fixture in this describe block is a top-level task, so deleting that argument
+  // stayed green everywhere else. A subtask's PR must target the parent's DECLARED branch (T-15),
+  // not the `task/<parentId>` deduction.
+  it("opens the PR against the parent's DECLARED branch, not task/<parentId>", () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task({ id: 'T-1.1', parentId: 'T-0' }),
+      attempt: 2,
+      branch: 'task/T-1.1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: { 'T-0': task({ id: 'T-0', declaredBranch: 'fix/parent-branch-resolution' }) },
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd });
+        if (command === 'gh' && args[1] === 'view') {
+          throw new Error('no pull requests found for branch "task/T-1.1"');
+        }
+        return command === 'gh' ? 'https://github.com/o/r/pull/9\n' : '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    });
+
+    const result = runners.openPr();
+
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/9' });
+    const created = recorded.find((call) => call.command === 'gh' && call.args[1] === 'create');
+    assert.ok(created, 'expected a gh pr create call');
+    const baseIndex = created ? created.args.indexOf('--base') : -1;
+    assert.equal(created?.args[baseIndex + 1], 'fix/parent-branch-resolution');
+  });
+
+  // Measured defect (T-5, 2026-09-07, real e2e): the close's own `gh pr view`/`gh pr create` ran
+  // with the dispatcher's inherited env, so a stale `GITHUB_TOKEN` in the developer shell took
+  // precedence over `gh`'s keyring login and the close failed at `open-pr` with `HTTP 401: Bad
+  // credentials`. Every `gh` call this step makes (the reuse check AND the create) must run with
+  // an env stripped of it.
+  it('runs every gh call (the reuse check and the create) without GITHUB_TOKEN', () => {
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const ghEnvs: Array<Record<string, string> | undefined> = [];
+    const result = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 2,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        if (command === 'gh') {
+          ghEnvs.push(options.env);
+          if (args[1] === 'view') {
+            throw new Error('no pull requests found for branch "task/T-1"');
+          }
+          return 'https://github.com/o/r/pull/8\n';
+        }
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    }).openPr();
+
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/8' });
+    assert.equal(ghEnvs.length, 2, 'both the reuse check and the create must have run gh');
+    for (const env of ghEnvs) {
+      assert.ok(env, 'every gh call must receive an explicit env');
+      assert.equal(env?.GITHUB_TOKEN, undefined);
+    }
+  });
+
+  // T-8 point 6: `buildPrCreateArgs` already composes a rich body from `taskText`/`maxAttempts`
+  // when a caller passes them (tested on its own in `close.test.ts`), but the real `openPr` call
+  // site never did — every real PR still opened with the legacy one-line
+  // `Dispatched attempt N for <id>.` body regardless of what the task declared. The board text this
+  // runner already re-reads for the PR title (`readTask`/`viewTask`) is what must reach the body
+  // too, plus `laneConfig.attempts` as `maxAttempts`.
+  it('opens the PR with the composed body from the re-read board text, not the legacy one-liner', () => {
+    const recorded: RunCall[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const result = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 2,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      maxAttempts: 3,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd });
+        if (command === 'gh' && args[1] === 'view') {
+          throw new Error('no pull requests found for branch "task/T-1"');
+        }
+        return command === 'gh' ? 'https://github.com/o/r/pull/9\n' : '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () =>
+        [
+          'Task T-1 - A task',
+          '',
+          'Status: In Progress',
+          '',
+          'Description:',
+          '--------------------------------------------------',
+          'Why this task exists.',
+          '',
+          'Files to touch: scripts/backlog/dispatch.ts',
+          'Test command: pnpm test:backlog',
+          '',
+        ].join('\n'),
+      runOsascript: () => {},
+    }).openPr();
+
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/9' });
+    const created = recorded.find((call) => call.command === 'gh' && call.args[1] === 'create');
+    assert.ok(created, 'the close must have created a PR');
+    const body = created!.args[created!.args.indexOf('--body') + 1];
+    assert.match(body, /## Resumen/);
+    assert.match(body, /Why this task exists\./);
+    assert.match(body, /Intento 2 de 3\./);
+    assert.doesNotMatch(body, /^Dispatched attempt/);
+  });
+});
+
+// ── openPr marks the PR for human review (T-31) ────────────────────────────────
+//
+// `scopeCheck` captures the soft-list files in a closure variable `openPr` reads (design.md
+// decision 8: never recomputed at PR time, since `mirrorRegen` by then has written into
+// `packages/cli/src/templates/`). Every test here calls `scopeCheck()` BEFORE `openPr()` for
+// exactly that reason.
+
+describe('buildCloseRunners — openPr marks the PR for human review', () => {
+  function runnersForMark(
+    recorded: RunCall[],
+    options: {
+      harnessReviewer?: string;
+      softListFile?: string | null;
+      ghAnswer?: (args: string[]) => string;
+    } = {},
+  ) {
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const softListFile =
+      options.softListFile === undefined ? 'scripts/backlog/dispatch.ts' : options.softListFile;
+    return buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      // FRONTIER: no declared-files allowlist to satisfy, so the soft-list file above needs no
+      // `Files to touch:` entry to be admitted.
+      task: task({ lane: LANE.FRONTIER }),
+      attempt: 2,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      harnessReviewer: options.harnessReviewer,
+      slotPathFor: () => slotPath,
+      run: (command, args, runOptions) => {
+        recorded.push({ command, args, cwd: runOptions.cwd });
+        if (command === 'git' && args[0] === 'diff') {
+          return softListFile ? `${softListFile}\0` : '';
+        }
+        if (command === 'git') {
+          return '';
+        }
+        if (command === 'gh') {
+          return options.ghAnswer
+            ? options.ghAnswer(args)
+            : args[1] === 'view'
+              ? (() => {
+                  throw new Error('no pull requests found for branch "task/T-1"');
+                })()
+              : 'https://github.com/o/r/pull/10\n';
+        }
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    });
+  }
+
+  it('applies the label and the configured reviewer AFTER the pull request exists', () => {
+    const recorded: RunCall[] = [];
+    const runners = runnersForMark(recorded, { harnessReviewer: 'octocat' });
+    assert.equal(runners.scopeCheck().ok, true);
+    const result = runners.openPr();
+    assert.equal(result.ok, true);
+
+    const ghCalls = recorded.filter((call) => call.command === 'gh');
+    const createIndex = ghCalls.findIndex((call) => call.args[1] === 'create');
+    const labelIndex = ghCalls.findIndex((call) => call.args.includes('--add-label'));
+    const reviewerIndex = ghCalls.findIndex((call) => call.args.includes('--add-reviewer'));
+    assert.ok(createIndex !== -1, 'the PR must have been created');
+    assert.ok(labelIndex > createIndex, 'the label is applied after the PR exists');
+    assert.ok(reviewerIndex > createIndex, 'the reviewer is applied after the PR exists');
+    assert.deepEqual(ghCalls[labelIndex].args, [
+      'pr',
+      'edit',
+      'task/T-1',
+      '--add-label',
+      'harness-review',
+    ]);
+    assert.deepEqual(ghCalls[reviewerIndex].args, [
+      'pr',
+      'edit',
+      'task/T-1',
+      '--add-reviewer',
+      'octocat',
+    ]);
+  });
+
+  it('a gh pr edit that throws leaves openPr ok:true with its compare URL, and records the reason', () => {
+    const recorded: RunCall[] = [];
+    const errors: unknown[] = [];
+    const originalConsoleError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args);
+    };
+    let result: unknown;
+    try {
+      const runners = runnersForMark(recorded, {
+        harnessReviewer: 'octocat',
+        ghAnswer: (args) => {
+          if (args[1] === 'view') {
+            throw new Error('no pull requests found for branch "task/T-1"');
+          }
+          if (args[1] === 'edit') {
+            throw new Error('HTTP 404: Label not found');
+          }
+          return 'https://github.com/o/r/pull/10\n';
+        },
+      });
+      assert.equal(runners.scopeCheck().ok, true);
+      result = runners.openPr();
+    } finally {
+      console.error = originalConsoleError;
+    }
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/10' });
+    assert.ok(
+      errors.some((call) => String(call).includes('404') || JSON.stringify(call).includes('404')),
+      'the gh pr edit failure must be recorded, not silently swallowed',
+    );
+  });
+
+  it('a rejected reviewer does not prevent the label', () => {
+    const recorded: RunCall[] = [];
+    const originalConsoleError = console.error;
+    console.error = () => {};
+    let result: unknown;
+    try {
+      const runners = runnersForMark(recorded, {
+        harnessReviewer: 'octocat',
+        ghAnswer: (args) => {
+          if (args[1] === 'view') {
+            throw new Error('no pull requests found for branch "task/T-1"');
+          }
+          if (args.includes('--add-reviewer')) {
+            throw new Error('HTTP 422: Reviewer cannot be requested (author)');
+          }
+          return 'https://github.com/o/r/pull/10\n';
+        },
+      });
+      assert.equal(runners.scopeCheck().ok, true);
+      result = runners.openPr();
+    } finally {
+      console.error = originalConsoleError;
+    }
+    assert.equal((result as { ok: boolean }).ok, true);
+    const labelCall = recorded.find(
+      (call) => call.command === 'gh' && call.args.includes('--add-label'),
+    );
+    assert.ok(labelCall, 'the label must still be applied even though the reviewer was rejected');
+  });
+
+  it('an unset harnessReviewer is recorded once, and no reviewer call is attempted', () => {
+    const recorded: RunCall[] = [];
+    const errors: unknown[] = [];
+    const originalConsoleError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args);
+    };
+    try {
+      const runners = runnersForMark(recorded);
+      assert.equal(runners.scopeCheck().ok, true);
+      runners.openPr();
+    } finally {
+      console.error = originalConsoleError;
+    }
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args.includes('--add-reviewer')),
+      'no reviewer handle configured means no reviewer call at all',
+    );
+    assert.ok(
+      errors.some((call) => JSON.stringify(call).includes('sin revisor configurado')),
+      'the absence of a configured reviewer must be recorded once',
+    );
+  });
+
+  it('with no soft-list files, neither gh pr edit runs at all', () => {
+    const recorded: RunCall[] = [];
+    const runners = runnersForMark(recorded, {
+      harnessReviewer: 'octocat',
+      softListFile: null,
+    });
+    const scope = runners.scopeCheck();
+    assert.deepEqual(scope.humanReviewFiles, []);
+    runners.openPr();
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args[1] === 'edit'),
+      'nothing to mark means no gh pr edit call at all',
+    );
+  });
+
+  // All THREE halves of the mark, the body included. The body is the half design.md decision 8
+  // calls unfailable, and on the create branch it is: it travels inside `gh pr create --body`. The
+  // reuse branch never calls create, so without its own `gh pr edit --body` the reused pull request
+  // would name no soft-list file at all and the whole mark would rest on the two calls the design
+  // explicitly allows to fail. Reachable shape: attempt 1 green with no soft file opens the PR,
+  // attempt 2 touches `packages/cli/**` and reuses it.
+  it('the reused-PR branch of openPr applies the same mark — body, label and reviewer', () => {
+    const recorded: RunCall[] = [];
+    const runners = runnersForMark(recorded, {
+      harnessReviewer: 'octocat',
+      ghAnswer: (args) => {
+        if (args[1] === 'view') {
+          return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+        }
+        return '';
+      },
+    });
+    assert.equal(runners.scopeCheck().ok, true);
+    const result = runners.openPr();
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/7' });
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args[1] === 'create'),
+      'a branch with an open PR must not be asked to create a second one',
+    );
+
+    const bodyCall = recorded.find(
+      (call) => call.command === 'gh' && call.args.includes('--body'),
+    );
+    assert.ok(bodyCall, 'the reused PR must have its body rewritten with the review section');
+    assert.deepEqual(bodyCall!.args.slice(0, 3), ['pr', 'edit', 'task/T-1']);
+    const body = bodyCall!.args[bodyCall!.args.indexOf('--body') + 1];
+    assert.match(body, /## Revisión humana requerida/);
+    assert.match(body, /scripts\/backlog\/dispatch\.ts/);
+
+    assert.ok(
+      recorded.some((call) => call.command === 'gh' && call.args.includes('--add-label')),
+      'the reused PR must still get the label',
+    );
+    assert.ok(
+      recorded.some((call) => call.command === 'gh' && call.args.includes('--add-reviewer')),
+      'the reused PR must still get the reviewer',
+    );
+  });
+
+  // T-31 round 2. `gh pr edit --body` REPLACES the body, and these are by construction the pull
+  // requests a person was asked to read and annotate — the retry flow reuses the same branch. The
+  // rewrite therefore reads the body that is actually there and edits only its own delimited
+  // section, so a reviewer's own notes survive it.
+  it('preserves the human text already in the reused PR body, editing only its own section', () => {
+    const recorded: RunCall[] = [];
+    const humanNote = 'Ojo: esto rompe el seed de permisos, hablar con Ana antes de fusionar.';
+    const runners = runnersForMark(recorded, {
+      ghAnswer: (args) => {
+        if (args[1] === 'view' && args.includes('body')) {
+          return JSON.stringify({ body: `# T-1\n\n## Resumen\n\nlo que hace.\n\n${humanNote}` });
+        }
+        if (args[1] === 'view') {
+          return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+        }
+        return '';
+      },
+    });
+    assert.equal(runners.scopeCheck().ok, true);
+    runners.openPr();
+
+    const bodyCall = recorded.find(
+      (call) => call.command === 'gh' && call.args.includes('--body'),
+    );
+    assert.ok(bodyCall, 'the reused PR must still have its body updated');
+    const body = bodyCall!.args[bodyCall!.args.indexOf('--body') + 1];
+    assert.ok(body.includes(humanNote), "a reviewer's own note must not be destroyed by the mark");
+    assert.match(body, /## Revisión humana requerida/);
+    assert.match(body, /scripts\/backlog\/dispatch\.ts/);
+  });
+
+  // Failing to READ the body is not a licence to overwrite it: with no idea what is there, the
+  // rewrite is skipped and recorded. The label and the reviewer still land.
+  it('skips the body rewrite (recording it) when the current body cannot be read', () => {
+    const recorded: RunCall[] = [];
+    const errors: unknown[] = [];
+    const originalConsoleError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args);
+    };
+    let result: unknown;
+    try {
+      const runners = runnersForMark(recorded, {
+        harnessReviewer: 'octocat',
+        ghAnswer: (args) => {
+          if (args[1] === 'view' && args.includes('body')) {
+            throw new Error('HTTP 502: Bad gateway');
+          }
+          if (args[1] === 'view') {
+            return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+          }
+          return '';
+        },
+      });
+      assert.equal(runners.scopeCheck().ok, true);
+      result = runners.openPr();
+    } finally {
+      console.error = originalConsoleError;
+    }
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/7' });
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args.includes('--body')),
+      'an unreadable body must never be overwritten with a recomposed one',
+    );
+    assert.ok(
+      errors.some((call) => JSON.stringify(call).includes('502')),
+      'the failed read must be recorded',
+    );
+    assert.ok(
+      recorded.some((call) => call.command === 'gh' && call.args.includes('--add-label')),
+      'the label still lands',
+    );
+  });
+
+  // The body rewrite is best-effort like the other two `gh pr edit` calls: it happens after the
+  // push has already updated the reused pull request, so losing it must not lose the attempt.
+  it('a body rewrite that throws on the reused branch is recorded, not fatal, and the label still lands', () => {
+    const recorded: RunCall[] = [];
+    const errors: unknown[] = [];
+    const originalConsoleError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args);
+    };
+    let result: unknown;
+    try {
+      const runners = runnersForMark(recorded, {
+        harnessReviewer: 'octocat',
+        ghAnswer: (args) => {
+          if (args[1] === 'view') {
+            return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+          }
+          if (args.includes('--body')) {
+            throw new Error('HTTP 422: body too long');
+          }
+          return '';
+        },
+      });
+      assert.equal(runners.scopeCheck().ok, true);
+      result = runners.openPr();
+    } finally {
+      console.error = originalConsoleError;
+    }
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/7' });
+    assert.ok(
+      errors.some((call) => JSON.stringify(call).includes('422')),
+      'the body rewrite failure must be recorded, not silently swallowed',
+    );
+    assert.ok(
+      recorded.some((call) => call.command === 'gh' && call.args.includes('--add-label')),
+      'a failed body rewrite must not take the label down with it',
+    );
+  });
+
+  // Spec scenario "The mirror regeneration does not mark the pull request by itself". The verdict is
+  // taken at `scope-check`, BEFORE `mirrorRegen` writes anything, and stored in a closure variable
+  // (design.md decision 8). This test drives the three runners in their real order with a git
+  // fixture that starts reporting the regenerated mirror files only AFTER the packager ran — so a
+  // re-reading at PR time would see `packages/cli/src/templates/…`, match the soft `packages/cli/`
+  // pattern, and mark an attempt whose own diff never left `backend/`.
+  it('the mirror regeneration does not mark the pull request by itself', () => {
+    const slot = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    fs.mkdirSync(path.join(slot, '.github', 'workflows'), { recursive: true });
+    fs.writeFileSync(
+      path.join(slot, '.github', 'workflows', 'cli-template-drift-check.yml'),
+      ['on:', '  pull_request:', '    paths:', "      - 'backend/**'", ''].join('\n'),
+    );
+
+    const recorded: RunCall[] = [];
+    let packagerRan = false;
+    const runners = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task({ lane: LANE.FRONTIER }),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      harnessReviewer: 'octocat',
+      slotPathFor: () => slot,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd });
+        if (command === 'node') {
+          packagerRan = true;
+          return '';
+        }
+        if (command === 'git' && args[0] === 'diff') {
+          return packagerRan
+            ? 'backend/src/@app/iam/x.ts\0packages/cli/src/templates/monorepo/backend/src/@app/iam/x.ts\0'
+            : 'backend/src/@app/iam/x.ts\0';
+        }
+        if (command === 'gh') {
+          if (args[1] === 'view') {
+            throw new Error('no pull requests found for branch "task/T-1"');
+          }
+          return 'https://github.com/o/r/pull/11\n';
+        }
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    });
+
+    const scope = runners.scopeCheck();
+    assert.equal(scope.ok, true);
+    assert.deepEqual(
+      scope.humanReviewFiles,
+      [],
+      'the pre-regen diff touched only backend/, which is on neither list',
+    );
+
+    const regen = runners.mirrorRegen();
+    assert.equal(regen.ok, true);
+    assert.ok(
+      recorded.some((call) => call.command === 'node'),
+      'the packager must actually have run, or this test proves nothing',
+    );
+
+    assert.equal(runners.openPr().ok, true);
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args[1] === 'edit'),
+      'the mirror the close itself wrote must not mark the pull request',
+    );
+    const created = recorded.find((call) => call.command === 'gh' && call.args[1] === 'create');
+    assert.ok(created, 'the PR must have been created');
+    const body = created!.args[created!.args.indexOf('--body') + 1];
+    assert.doesNotMatch(body, /Revisión humana requerida/);
+  });
+
+  // The body rewrite belongs to the MARK, not to the reuse: an attempt that reached no soft-list
+  // file must leave the reused pull request's body exactly as the attempt that opened it wrote it.
+  it('does not rewrite the reused PR body when there is no soft-list file to name', () => {
+    const recorded: RunCall[] = [];
+    const runners = runnersForMark(recorded, {
+      harnessReviewer: 'octocat',
+      softListFile: null,
+      ghAnswer: (args) => {
+        if (args[1] === 'view') {
+          return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+        }
+        return '';
+      },
+    });
+    assert.deepEqual(runners.scopeCheck().humanReviewFiles, []);
+    runners.openPr();
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args[1] === 'edit'),
+      'nothing to mark means no gh pr edit call at all, the body included',
+    );
+  });
+});
+
+// ── N3: the board load reports whether what it returned is the WHOLE board ────────────────────
+
+describe('loadBoard', () => {
+  const listOutput = 'T-1 - Queued - first\nT-2 - Queued - second\n';
+  const view = (id: string): string => `## ${id} — a task\nStatus: Queued\nCreated: 2026-09-06\n`;
+
+  it('reports a complete board when the list and every view succeeded', () => {
+    const result = loadBoard({ list: () => listOutput, view, attempts: () => 0 });
+
+    assert.equal(result.complete, true);
+    assert.deepEqual(
+      result.tasks.map((task) => task.id),
+      ['T-1', 'T-2'],
+    );
+  });
+
+  // The pre-N3 shape returned a bare `[]` here, which the maintenance sweep then read as "every
+  // task was deleted" and cancelled every live worker on.
+  it('reports an INCOMPLETE, empty board when the list itself failed', () => {
+    const result = loadBoard({
+      list: () => {
+        throw new Error('backlog exited 1');
+      },
+      view,
+      attempts: () => 0,
+    });
+
+    assert.deepEqual(result, { tasks: [], complete: false });
+  });
+
+  it('reports incomplete when one view threw, keeping the tasks it could read', () => {
+    const result = loadBoard({
+      list: () => listOutput,
+      view: (id) => {
+        if (id === 'T-2') {
+          throw new Error('backlog task view exited 1');
+        }
+        return view(id);
+      },
+      attempts: () => 0,
+    });
+
+    assert.equal(result.complete, false);
+    assert.deepEqual(
+      result.tasks.map((task) => task.id),
+      ['T-1'],
+    );
+  });
+});
+
+// ── N5: `--release-slot` is the documented way back into the pool ─────────────────────────────
+
+describe('parseReleaseSlotArg', () => {
+  it('returns null for an ordinary pass, which takes no flags at all', () => {
+    assert.equal(parseReleaseSlotArg([]), null);
+  });
+
+  it('reads the slot name after the flag', () => {
+    assert.deepEqual(parseReleaseSlotArg(['--release-slot', 'dispatch-1']), {
+      slot: 'dispatch-1',
+      force: false,
+    });
+  });
+
+  it('reads --force alongside it — the override for a slot the guard refuses', () => {
+    assert.deepEqual(parseReleaseSlotArg(['--release-slot', 'dispatch-1', '--force']), {
+      slot: 'dispatch-1',
+      force: true,
+    });
+  });
+
+  // Releasing "whatever came next" is how a rescue turns into a second incident: the value is
+  // required, and a flag is not a slot name.
+  it('refuses a missing or flag-shaped value rather than releasing something unnamed', () => {
+    assert.throws(() => parseReleaseSlotArg(['--release-slot']), /needs a slot name/);
+    assert.throws(() => parseReleaseSlotArg(['--release-slot', '--verbose']), /needs a slot name/);
+  });
+});
+
+// P3 (round 9): the flag is documented as the rescue for a slot held for push recovery, but it
+// released ANY named slot unconditionally — including one with a live worker in it. A person typing
+// the wrong slot name (or the right one a pass had already recovered) detached the worktree under a
+// running `claude`, dropped its lock, and handed the directory to the next dispatch: the work is
+// gone and the close, if it survives at all, opens a PR off someone else's branch.
+describe('releaseSlotByName — the guard over a live slot', () => {
+  const heldSlot = (overrides: Partial<SlotRegistry['slots'][number]> = {}) => ({
+    name: 'dispatch-a',
+    path: '/slots/a',
+    lane: LANE.LOCAL,
+    taskId: 'T-1',
+    pid: 4242,
+    lockfileHash: null,
+    ...overrides,
+  });
+
+  const lockFor = (pid: number): DispatchLock => ({
+    taskId: 'T-1',
+    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-1',
+  });
+
+  function depsWith(
+    slot: SlotRegistry['slots'][number],
+    lock: DispatchLock | null,
+    alive: boolean,
+    passRunningPid: number | null = null,
+  ) {
+    const actions: string[] = [];
+    // Recorded apart from `actions`, whose exact contents the release assertions below compare: the
+    // single-flight lifecycle brackets every one of them.
+    const singleFlight: string[] = [];
+    return {
+      actions,
+      singleFlight,
+      deps: {
+        readSlots: () => ({ slots: [slot] }),
+        readLock: () => lock,
+        isPidAlive: () => alive,
+        now: Date.parse('2026-09-06T09:01:00.000Z'),
+        ttlMs: 10 * 60_000,
+        detach: (slotPath: string) => actions.push(`detach ${slotPath}`),
+        removeLock: (taskId: string) => actions.push(`removeLock ${taskId}`),
+        updateSlots: () => actions.push('updateSlots'),
+        log: () => {},
+        acquireSingleFlight: (): SingleFlightResult => {
+          singleFlight.push('acquire');
+          return passRunningPid === null
+            ? { kind: 'acquired' }
+            : { kind: 'already-running', pid: passRunningPid };
+        },
+        releaseSingleFlight: () => singleFlight.push('release'),
+      },
+    };
+  }
+
+  it('refuses a slot whose worker is alive and its lock inside the TTL, touching nothing', () => {
+    const { actions, deps } = depsWith(heldSlot(), lockFor(4242), true);
+
+    const outcome = releaseSlotByName('dispatch-a', false, deps);
+
+    assert.equal(outcome.kind, 'refused');
+    assert.match(outcome.reason ?? '', /T-1/, 'the refusal must name what the slot is holding');
+    assert.deepEqual(actions, [], 'a refusal must not detach, unlock or rewrite the registry');
+  });
+
+  it('releases a slot flagged heldForRecovery — the case the flag exists for', () => {
+    const { actions, deps } = depsWith(heldSlot({ heldForRecovery: true }), lockFor(4242), true);
+
+    assert.equal(releaseSlotByName('dispatch-a', false, deps).kind, 'released');
+    assert.deepEqual(actions, ['detach /slots/a', 'removeLock T-1', 'updateSlots']);
+  });
+
+  it('releases a slot whose lock names a dead pid — nothing is running in there', () => {
+    const { actions, deps } = depsWith(heldSlot(), lockFor(4242), false);
+
+    assert.equal(releaseSlotByName('dispatch-a', false, deps).kind, 'released');
+    assert.deepEqual(actions, ['detach /slots/a', 'removeLock T-1', 'updateSlots']);
+  });
+
+  it('releases a slot with no lock at all — an orphan binding, not a live worker', () => {
+    const { actions, deps } = depsWith(heldSlot(), null, true);
+
+    assert.equal(releaseSlotByName('dispatch-a', false, deps).kind, 'released');
+    assert.deepEqual(actions, ['detach /slots/a', 'removeLock T-1', 'updateSlots']);
+  });
+
+  it('releases a slot whose heartbeat expired even with a live pid', () => {
+    const { actions, deps } = depsWith(heldSlot(), lockFor(4242), true);
+    deps.now = Date.parse('2026-09-06T09:30:00.000Z');
+
+    assert.equal(releaseSlotByName('dispatch-a', false, deps).kind, 'released');
+    assert.deepEqual(actions, ['detach /slots/a', 'removeLock T-1', 'updateSlots']);
+  });
+
+  it('--force overrides the guard — the person looked and decided', () => {
+    const { actions, deps } = depsWith(heldSlot(), lockFor(4242), true);
+
+    assert.equal(releaseSlotByName('dispatch-a', true, deps).kind, 'released');
+    assert.deepEqual(actions, ['detach /slots/a', 'removeLock T-1', 'updateSlots']);
+  });
+
+  // R6 (round 10): the rescue read `slots.json`, decided, and detached the worktree with nothing
+  // serializing it against a reconciler pass. A pass that acquired this very slot between the read
+  // and the detach lost its worktree under a starting worker. The rescue now takes the same
+  // single-flight lock the pass's selection runs under, so the two cannot interleave.
+  it('refuses while a reconciler pass holds the single-flight lock, touching nothing', () => {
+    const { actions, singleFlight, deps } = depsWith(
+      heldSlot({ heldForRecovery: true }),
+      null,
+      false,
+      9191,
+    );
+
+    const outcome = releaseSlotByName('dispatch-a', false, deps);
+
+    assert.equal(outcome.kind, 'refused');
+    assert.match(outcome.reason ?? '', /9191/, 'the refusal must name the pass that is running');
+    assert.deepEqual(actions, [], 'a refusal must not detach, unlock or rewrite the registry');
+    assert.deepEqual(singleFlight, ['acquire'], 'a lock it never took must not be released');
+  });
+
+  it('--force releases even while a pass is running — the person looked and decided', () => {
+    const { actions, singleFlight, deps } = depsWith(
+      heldSlot({ heldForRecovery: true }),
+      null,
+      false,
+      9191,
+    );
+
+    assert.equal(releaseSlotByName('dispatch-a', true, deps).kind, 'released');
+    assert.deepEqual(actions, ['detach /slots/a', 'removeLock T-1', 'updateSlots']);
+    // And the running pass keeps its lock: `--force` releases the SLOT, not the single-flight lock
+    // this call never took. Removing it would let a third pass start alongside the live one.
+    assert.deepEqual(singleFlight, ['acquire'], 'a lock it never took must not be released');
+  });
+
+  it('releases the single-flight lock it took, on both the released and the refused path', () => {
+    const released = depsWith(heldSlot({ heldForRecovery: true }), null, false);
+    releaseSlotByName('dispatch-a', false, released.deps);
+    assert.deepEqual(released.singleFlight, ['acquire', 'release']);
+
+    const refused = depsWith(heldSlot(), lockFor(4242), true);
+    releaseSlotByName('dispatch-a', false, refused.deps);
+    assert.deepEqual(refused.singleFlight, ['acquire', 'release']);
+  });
+
+  it('refuses a name no slot carries rather than reporting a release that never happened', () => {
+    const { actions, deps } = depsWith(heldSlot(), null, false);
+
+    const outcome = releaseSlotByName('dispatch-z', true, deps);
+
+    assert.equal(outcome.kind, 'refused');
+    assert.deepEqual(actions, []);
+  });
+});
+
+// ── N6: every `gh` call names the repository it is asking about ────────────────────────────────
+
+describe('realGh — isPrMerged', () => {
+  it('runs gh pr view in the repo root, so it never asks about whatever cwd it inherited', () => {
+    const recorded: RunCall[] = [];
+    const merged = realGh('/repo', (command, args, options) => {
+      recorded.push({ command, args, cwd: options.cwd });
+      return JSON.stringify({ state: 'MERGED', mergedAt: '2026-09-06T10:00:00Z' });
+    }).isPrMerged('task/T-1');
+
+    assert.equal(merged, true);
+    assert.deepEqual(recorded, [
+      {
+        command: 'gh',
+        args: ['pr', 'view', 'task/T-1', '--json', 'state,mergedAt'],
+        cwd: '/repo',
+      },
+    ]);
+  });
+
+  it('fails closed when gh throws — no PR, no auth, no gh binary', () => {
+    const merged = realGh('/repo', () => {
+      throw new Error('gh: command not found');
+    }).isPrMerged('task/T-1');
+
+    assert.equal(merged, false);
+  });
+
+  // Measured defect (T-5, 2026-09-07, real e2e, close attempt 2): `gh pr view task/T-5` returned
+  // `HTTP 401: Bad credentials`. `gh` prefers an env `GITHUB_TOKEN` over its own keyring login, and
+  // the dispatcher process inherits a STALE one from the developer shell it was launched from
+  // (`GITHUB_TOKEN= gh auth status` on the same machine showed a valid keyring login all along).
+  // The real collaborator must therefore hand `gh` an env with that key stripped, never the bare
+  // `process.env` a caller who forgot could pass through unfiltered.
+  it('runs gh with an env stripped of GITHUB_TOKEN, so a stale token never outranks the keyring login', () => {
+    let capturedEnv: Record<string, string> | undefined;
+    realGh('/repo', (command, args, options) => {
+      capturedEnv = options.env;
+      return JSON.stringify({ state: 'MERGED', mergedAt: '2026-09-06T10:00:00Z' });
+    }).isPrMerged('task/T-1');
+
+    assert.ok(capturedEnv, 'the real collaborator must receive an explicit env');
+    assert.equal(capturedEnv?.GITHUB_TOKEN, undefined);
+  });
+});
+
+// ── ghEnv (T-5 fix) ────────────────────────────────────────────────────────────
+
+describe('ghEnv', () => {
+  it('drops GITHUB_TOKEN, keeping the rest of the environment', () => {
+    const env = ghEnv({ PATH: '/usr/bin', GITHUB_TOKEN: 'ghp_stale' });
+    assert.deepEqual(env, { PATH: '/usr/bin' });
+  });
+
+  it('drops every gh-preferred token key: GH_TOKEN, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN', () => {
+    const env = ghEnv({
+      PATH: '/usr/bin',
+      GITHUB_TOKEN: 'a',
+      GH_TOKEN: 'b',
+      GH_ENTERPRISE_TOKEN: 'c',
+      GITHUB_ENTERPRISE_TOKEN: 'd',
+    });
+    assert.deepEqual(env, { PATH: '/usr/bin' });
+  });
+
+  it('drops undefined values rather than passing them through as "undefined"', () => {
+    assert.deepEqual(ghEnv({ A: undefined, B: 'b' }), { B: 'b' });
+  });
+
+  // Unlike `reviewerEnv`, `ghEnv` must NOT strip every credential-shaped key: the dispatcher's own
+  // `gh` calls still need whatever else the shell carries (HOME for `gh`'s own config, and any
+  // other token an unrelated tool in the same shell happens to export).
+  it('leaves every other key alone, including other credential-shaped ones and HOME', () => {
+    const env = ghEnv({
+      PATH: '/usr/bin',
+      HOME: '/Users/x',
+      NPM_TOKEN: 'npm_x',
+      AWS_SECRET_ACCESS_KEY: 'aws_x',
+    });
+    assert.deepEqual(env, {
+      PATH: '/usr/bin',
+      HOME: '/Users/x',
+      NPM_TOKEN: 'npm_x',
+      AWS_SECRET_ACCESS_KEY: 'aws_x',
+    });
+  });
+});
+
+// K2: the board commit staged `.backlog` and then ran a BARE commit. Staging only adds; it does
+// not narrow what the commit takes, so anything a person already had in the index of the main
+// checkout — a half-finished refactor mid `add -p` — rode along inside an unattended machine
+// commit. The trailing pathspec is what makes the commit take the board and nothing else.
+describe('realGit — the board commit', () => {
+  it('commits with a trailing `.backlog` pathspec, so nothing a person had staged rides along', () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+    }).commitBacklogChanges('chore(backlog): reconcile');
+
+    assert.deepEqual(recorded, [
+      { command: 'git', args: ['add', '.backlog'], cwd: MAIN_CHECKOUT },
+      {
+        command: 'git',
+        args: ['commit', '-m', 'chore(backlog): reconcile', '--no-verify', '--', '.backlog'],
+        cwd: MAIN_CHECKOUT,
+      },
+    ]);
+  });
+});
+
+// ── realGit — branchExists (T-8 point 7's ONLY way to tell "no PR because no branch" apart from
+// "no PR because GitHub has not reported the merge yet") ───────────────────────────────────────
+describe('realGit — branchExists', () => {
+  it('reports a branch as existing when the LOCAL ref resolves, asking git nothing else', () => {
+    const recorded: RunCall[] = [];
+    const exists = realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+    }).branchExists?.('task/T-1');
+
+    assert.equal(exists, true);
+    assert.deepEqual(recorded, [
+      {
+        command: 'git',
+        args: ['rev-parse', '--verify', '--quiet', 'refs/heads/task/T-1'],
+        cwd: MAIN_CHECKOUT,
+      },
+    ]);
+  });
+
+  it('falls back to a REMOTE check when the local ref is absent, and reports true when that one has it', () => {
+    const recorded: RunCall[] = [];
+    const exists = realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => {
+        recorded.push({ command, args, cwd });
+        if (args[0] === 'rev-parse') {
+          throw new Error('fatal: Needed a single revision');
+        }
+      },
+    }).branchExists?.('task/T-1');
+
+    assert.equal(exists, true);
+    assert.deepEqual(
+      recorded.map((call) => call.args),
+      [
+        ['rev-parse', '--verify', '--quiet', 'refs/heads/task/T-1'],
+        ['ls-remote', '--exit-code', '--heads', 'origin', 'task/T-1'],
+      ],
+    );
+  });
+
+  it('reports false when neither the local nor the remote ref exists', () => {
+    const exists = realGit(MAIN_CHECKOUT, {
+      run: () => {
+        throw new Error('not found');
+      },
+    }).branchExists?.('task/T-1');
+
+    assert.equal(exists, false);
+  });
+});
+
+// ── realGit — deleteLocalBranch / deleteRemoteBranch (T-8 point 5) ───────────────────────────
+describe('realGit — deleteLocalBranch', () => {
+  it('runs git branch -D in the main checkout', () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+    }).deleteLocalBranch?.('task/T-12');
+
+    assert.deepEqual(recorded, [
+      { command: 'git', args: ['branch', '-D', 'task/T-12'], cwd: MAIN_CHECKOUT },
+    ]);
+  });
+
+  it('never throws when the local ref is already absent — the common case, no worktree ever named it', () => {
+    assert.doesNotThrow(() =>
+      realGit(MAIN_CHECKOUT, {
+        run: () => {
+          throw new Error("error: branch 'task/T-12' not found.");
+        },
+      }).deleteLocalBranch?.('task/T-12'),
+    );
+  });
+});
+
+describe('realGit — deleteRemoteBranch', () => {
+  it('runs git push origin --delete in the main checkout and reports it deleted', () => {
+    const recorded: RunCall[] = [];
+    const result = realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+    }).deleteRemoteBranch?.('task/T-12');
+
+    assert.deepEqual(recorded, [
+      { command: 'git', args: ['push', 'origin', '--delete', 'task/T-12'], cwd: MAIN_CHECKOUT },
+    ]);
+    assert.equal(result, REMOTE_BRANCH_DELETE_RESULT.DELETED);
+  });
+
+  // GitHub's "Automatically delete head branches" (enabled 2026-09-08) routinely beats this call
+  // to it — a missing remote ref is the NORMAL outcome here, never a failure to report.
+  it('never throws, and reports "already-gone", when the remote ref is already gone', () => {
+    let result: unknown;
+    assert.doesNotThrow(() => {
+      result = realGit(MAIN_CHECKOUT, {
+        run: () => {
+          throw new Error("error: unable to delete 'task/T-12': remote ref does not exist");
+        },
+      }).deleteRemoteBranch?.('task/T-12');
+    });
+    assert.equal(result, REMOTE_BRANCH_DELETE_RESULT.ALREADY_GONE);
+  });
+
+  // Defect 7 (2026-09-08): a REAL failure (bad auth, a protected-branch rule, a network timeout)
+  // must be distinguishable from the "already gone" case above — swallowing both identically left
+  // the remote ref alive with no log line and no honest signal for `MaintenanceResult`.
+  it('never throws, but reports "failed" and logs it, on a genuine push failure', () => {
+    const errors: unknown[] = [];
+    const originalConsoleError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args);
+    };
+    let result: unknown;
+    try {
+      assert.doesNotThrow(() => {
+        result = realGit(MAIN_CHECKOUT, {
+          run: () => {
+            throw new Error('error: failed to push some refs (permission denied)');
+          },
+        }).deleteRemoteBranch?.('task/T-12');
+      });
+    } finally {
+      console.error = originalConsoleError;
+    }
+    assert.equal(result, REMOTE_BRANCH_DELETE_RESULT.FAILED);
+    assert.equal(errors.length, 1);
+  });
+});
+
+// ── realGit — branchHasUnmergedCommits (the T-8 point 5 safety check) ───────────────────────
+describe('realGit — branchHasUnmergedCommits', () => {
+  it('reports false (safe to delete) when the branch is an ancestor of its base', () => {
+    const recorded: RunCall[] = [];
+    const result = realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+    }).branchHasUnmergedCommits?.('task/T-20', 'origin/main');
+
+    assert.equal(result, false);
+    assert.deepEqual(
+      recorded.map((call) => call.args),
+      [
+        ['rev-parse', '--verify', 'refs/remotes/origin/task/T-20'],
+        ['merge-base', '--is-ancestor', 'origin/task/T-20', 'origin/main'],
+      ],
+    );
+  });
+
+  // The measured T-6.3 shape: a `gh`-outage rescue push lands a WIP commit on a branch AFTER its
+  // PR already merged. The branch is no longer an ancestor of its base, and `merge-base
+  // --is-ancestor` exits non-zero — refuse, never delete.
+  it('reports true (refuse) when the branch carries a commit not reachable from its base', () => {
+    const result = realGit(MAIN_CHECKOUT, {
+      run: (command, args) => {
+        if (args[0] === 'merge-base') {
+          throw new Error('fatal: exit status 1'); // not an ancestor
+        }
+      },
+    }).branchHasUnmergedCommits?.('task/T-20', 'origin/main');
+
+    assert.equal(result, true);
+  });
+
+  // Measured (2026-09-08): `git rev-parse --verify <ref>` (no `--quiet`) fails a genuinely absent
+  // ref with EXACTLY this wording — a fixed git message, not a guess — so it is the one signal safe
+  // to read as "confirmed absent, nothing to lose".
+  it('reports false when the remote-tracking ref does not exist at all — nothing left to lose', () => {
+    const result = realGit(MAIN_CHECKOUT, {
+      run: () => {
+        throw new Error(
+          'Command failed: git rev-parse --verify refs/remotes/origin/task/T-20\nfatal: Needed a single revision\n',
+        );
+      },
+    }).branchHasUnmergedCommits?.('task/T-20', 'origin/main');
+
+    assert.equal(result, false);
+  });
+
+  // S2 [LOW] (2026-09-08): the previous version read ANY `rev-parse` failure the same way as a
+  // confirmed-absent ref — a missing `git` binary, a broken checkout, a corrupted repo all
+  // silently AUTHORISED the delete on a question they never actually answered. Only the fixed
+  // "Needed a single revision" wording above may say "nothing to lose"; everything else must fail
+  // in the SAME safe direction as the merge-base check below (refuse).
+  it('refuses (fails safe) when rev-parse fails for a reason OTHER than a confirmed-absent ref (S2)', () => {
+    const result = realGit(MAIN_CHECKOUT, {
+      run: () => {
+        throw new Error('spawnSync git ENOENT');
+      },
+    }).branchHasUnmergedCommits?.('task/T-20', 'origin/main');
+
+    assert.equal(
+      result,
+      true,
+      'a git-binary-missing failure must never be read as "nothing to lose"',
+    );
+  });
+
+  it('also refuses when rev-parse fails on a broken checkout, not merely a missing git binary (S2)', () => {
+    const result = realGit(MAIN_CHECKOUT, {
+      run: () => {
+        throw new Error(
+          'Command failed: git rev-parse --verify refs/remotes/origin/task/T-20\nfatal: not a git repository (or any of the parent directories): .git\n',
+        );
+      },
+    }).branchHasUnmergedCommits?.('task/T-20', 'origin/main');
+
+    assert.equal(result, true);
+  });
+
+  it('refuses (fails safe) when the comparison itself cannot be run — a bad or missing base ref', () => {
+    const result = realGit(MAIN_CHECKOUT, {
+      run: (command, args) => {
+        if (args[0] === 'rev-parse') {
+          return; // the branch's remote-tracking ref exists.
+        }
+        throw new Error("fatal: ambiguous argument 'origin/task/T-10': unknown revision");
+      },
+    }).branchHasUnmergedCommits?.('task/T-20', 'origin/task/T-10');
+
+    assert.equal(result, true);
+  });
+
+  it('resolves the base a SUBTASK compares against to its parent branch, never main', () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+    }).branchHasUnmergedCommits?.('task/T-20', 'origin/task/T-10');
+
+    assert.deepEqual(recorded[1].args, [
+      'merge-base',
+      '--is-ancestor',
+      'origin/task/T-20',
+      'origin/task/T-10',
+    ]);
+  });
+});
+
+// ── realGh — prState (T-8 point 3) ─────────────────────────────────────────────
+describe('realGh — prState', () => {
+  it("returns the branch's PR state exactly as GitHub reports it", () => {
+    const recorded: RunCall[] = [];
+    const state = realGh('/repo', (command, args, options) => {
+      recorded.push({ command, args, cwd: options.cwd });
+      return JSON.stringify({ state: 'CLOSED' });
+    }).prState?.('task/T-1');
+
+    assert.equal(state, 'CLOSED');
+    assert.deepEqual(recorded, [
+      { command: 'gh', args: ['pr', 'view', 'task/T-1', '--json', 'state'], cwd: '/repo' },
+    ]);
+  });
+
+  it('returns null when gh throws — no PR on the branch, no auth, no gh binary', () => {
+    const state = realGh('/repo', () => {
+      throw new Error('no pull requests found for branch "task/T-1"');
+    }).prState?.('task/T-1');
+
+    assert.equal(state, null);
+  });
+
+  it('runs with an env stripped of GITHUB_TOKEN, same as isPrMerged', () => {
+    let capturedEnv: Record<string, string> | undefined;
+    realGh('/repo', (command, args, options) => {
+      capturedEnv = options.env;
+      return JSON.stringify({ state: 'OPEN' });
+    }).prState?.('task/T-1');
+
+    assert.ok(capturedEnv, 'prState must receive an explicit env, same as isPrMerged');
+    assert.equal(capturedEnv?.GITHUB_TOKEN, undefined);
+  });
+});
+
+// ── realGh — mergedState (T-8 defect 1, F3 gap: this adapter had no tests at all) ──────────────
+//
+// `mergedState` is the load-bearing tri-state seam `maintenance.ts`'s step 3b — and now
+// `recomputeParent` (F1) — decide a DESTRUCTIVE revert / a bailed derivation from. Its whole
+// behaviour was unverified: rewriting it back to `gh pr view` today would have kept the suite
+// green, because nothing exercised it before this task.
+describe('realGh — mergedState (T-8 defect 1)', () => {
+  it('asks gh pr list --head <branch> --state all, never gh pr view — the argv this seam depends on', () => {
+    const recorded: RunCall[] = [];
+    const state = realGh('/repo', (command, args, options) => {
+      recorded.push({ command, args, cwd: options.cwd });
+      return JSON.stringify([{ state: 'MERGED', mergedAt: '2026-09-06T10:00:00Z' }]);
+    }).mergedState?.('task/T-1');
+
+    assert.equal(state, 'merged');
+    assert.deepEqual(recorded, [
+      {
+        command: 'gh',
+        args: [
+          'pr',
+          'list',
+          '--head',
+          'task/T-1',
+          '--state',
+          'all',
+          '--json',
+          'state,mergedAt',
+          '--limit',
+          '1',
+        ],
+        cwd: '/repo',
+      },
+    ]);
+  });
+
+  it('reads an EMPTY array as a CONFIRMED not-merged — no PR was ever opened for this branch', () => {
+    const state = realGh('/repo', () => JSON.stringify([])).mergedState?.('task/T-1');
+    assert.equal(state, 'not-merged');
+  });
+
+  it('reads an OPEN (unmerged) PR as not-merged, not unknown', () => {
+    const state = realGh('/repo', () =>
+      JSON.stringify([{ state: 'OPEN', mergedAt: null }]),
+    ).mergedState?.('task/T-1');
+    assert.equal(state, 'not-merged');
+  });
+
+  it('reads a CLOSED-without-merging PR as not-merged too', () => {
+    const state = realGh('/repo', () =>
+      JSON.stringify([{ state: 'CLOSED', mergedAt: null }]),
+    ).mergedState?.('task/T-1');
+    assert.equal(state, 'not-merged');
+  });
+
+  // Only a THROW — the call itself could not run to completion — becomes unknown. This is the
+  // entire point of asking `pr list` instead of `pr view`: `pr view` throws identically whether
+  // there is no PR, the binary is missing, the token expired, or the network is down.
+  it('only a THROW becomes unknown — gh missing, auth expired, network down', () => {
+    const state = realGh('/repo', () => {
+      throw new Error('gh: command not found');
+    }).mergedState?.('task/T-1');
+    assert.equal(state, 'unknown');
+  });
+
+  it('runs with an env stripped of GITHUB_TOKEN, same as isPrMerged and prState', () => {
+    let capturedEnv: Record<string, string> | undefined;
+    realGh('/repo', (command, args, options) => {
+      capturedEnv = options.env;
+      return JSON.stringify([]);
+    }).mergedState?.('task/T-1');
+
+    assert.ok(capturedEnv, 'mergedState must receive an explicit env, same as its siblings');
+    assert.equal(capturedEnv?.GITHUB_TOKEN, undefined);
+  });
+});
+
+// ── realMaintenanceFs — hasAttemptDir (T-8 point 10's fourth orphan check) ────────────────────
+describe('realMaintenanceFs — hasAttemptDir', () => {
+  it('reports true when .backlog/.dispatch/<taskId>/ exists in the main checkout', () => {
+    const checkout = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-main-'));
+    fs.mkdirSync(path.join(checkout, '.backlog', '.dispatch', 'T-9', 'intento-1'), {
+      recursive: true,
+    });
+
+    const hasAttemptDir = realMaintenanceFs(checkout, checkout).hasAttemptDir;
+    assert.equal(hasAttemptDir?.('T-9'), true);
+  });
+
+  it('reports false when the task was never dispatched at all', () => {
+    const checkout = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-main-'));
+    const hasAttemptDir = realMaintenanceFs(checkout, checkout).hasAttemptDir;
+    assert.equal(hasAttemptDir?.('T-9'), false);
+  });
+});
+
+// Measured defect (T-5, 2026-09-07): the dispatcher's own `backlog task edit -s ...` calls carried
+// no env override at all, so the `onStatusChange` callback THEY fired never saw
+// `BACKLOG_DISPATCH_ACTIVE` — only a worker's writes (via `worker-edit.ts`) did. A dispatcher-owned
+// write must carry the same sentinel, so the nested pass its own callback spawns can recognize
+// itself (`isDispatcherOwnedCallback`, entry.ts) and skip outright instead of racing the pass that
+// made the write over the same `.backlog` git commit.
+describe('realBacklog — the dispatcher-owned write sentinel', () => {
+  it('passes BACKLOG_DISPATCH_ACTIVE=1 on setStatus, so its own onStatusChange callback can recognize itself', () => {
+    const recorded: Array<{ args: string[]; env: NodeJS.ProcessEnv | undefined }> = [];
+    realBacklog(MAIN_CHECKOUT, {
+      run: (args, options) => recorded.push({ args, env: options.env }),
+    }).setStatus('T-5', TASK_STATUS.IN_PROGRESS);
+
+    assert.equal(recorded.length, 1);
+    assert.deepEqual(recorded[0].args, ['task', 'edit', 'T-5', '-s', 'In Progress']);
+    assert.equal(recorded[0].env?.BACKLOG_DISPATCH_ACTIVE, '1');
+  });
+
+  it('passes BACKLOG_DISPATCH_ACTIVE=1 on comment too', () => {
+    const recorded: Array<{ args: string[]; env: NodeJS.ProcessEnv | undefined }> = [];
+    realBacklog(MAIN_CHECKOUT, {
+      run: (args, options) => recorded.push({ args, env: options.env }),
+    }).comment('T-5', 'hola');
+
+    assert.equal(recorded.length, 1);
+    assert.deepEqual(recorded[0].args, ['task', 'edit', 'T-5', '--comment', 'hola']);
+    assert.equal(recorded[0].env?.BACKLOG_DISPATCH_ACTIVE, '1');
+  });
+
+  it('still appends --comment on setStatus when a comment is given, sentinel included', () => {
+    const recorded: Array<{ args: string[]; env: NodeJS.ProcessEnv | undefined }> = [];
+    realBacklog(MAIN_CHECKOUT, {
+      run: (args, options) => recorded.push({ args, env: options.env }),
+    }).setStatus('T-5', TASK_STATUS.BLOCKED, 'no se pudo empujar la rama');
+
+    assert.deepEqual(recorded[0].args, [
+      'task',
+      'edit',
+      'T-5',
+      '-s',
+      'Blocked',
+      '--comment',
+      'no se pudo empujar la rama',
+    ]);
+    assert.equal(recorded[0].env?.BACKLOG_DISPATCH_ACTIVE, '1');
+  });
+});
+
+// Measured defect (T-5, 2026-09-07, real e2e): Backlog.md holds a per-task lock while
+// `onStatusChange` runs AND while it waits for the callback's stdio to close — the dispatcher's own
+// `-s In Progress` edit collided with it and failed with `T-5 is being modified by another
+// process; retry if appropriate.` The callback line is now fixed to detach its stdio (so the hold is
+// brief), but a person or a second reconciler can still hold that lock for a moment at any time —
+// hence a bounded retry with linear backoff on the busy symptom specifically, never on anything else.
+describe('withBoardWriteRetry', () => {
+  const busyError = (): Error =>
+    new Error(
+      'dispatch.ts: backlog task edit T-5 -s In Progress failed: Command failed — stderr: Error: T-5 is being ' +
+        'modified by another process; retry if appropriate.',
+    );
+
+  it('retries a busy write and returns once it succeeds', () => {
+    let calls = 0;
+    const sleeps: number[] = [];
+    const result = withBoardWriteRetry(
+      'backlog task edit T-5 -s In Progress',
+      () => {
+        calls += 1;
+        if (calls < 3) {
+          throw busyError();
+        }
+        return 'ok';
+      },
+      { attempts: 6, baseDelayMs: 250, sleep: (ms) => sleeps.push(ms) },
+    );
+
+    assert.equal(result, 'ok');
+    assert.equal(calls, 3);
+    assert.deepEqual(sleeps, [250, 500]);
+  });
+
+  it('gives up after the last attempt and rethrows the original error untouched', () => {
+    let calls = 0;
+    const sleeps: number[] = [];
+    const original = busyError();
+
+    assert.throws(
+      () =>
+        withBoardWriteRetry(
+          'backlog task edit T-5 -s In Progress',
+          () => {
+            calls += 1;
+            throw original;
+          },
+          { attempts: 6, baseDelayMs: 250, sleep: (ms) => sleeps.push(ms) },
+        ),
+      (error: unknown) => error === original,
+    );
+
+    assert.equal(calls, 6);
+    assert.deepEqual(sleeps, [250, 500, 750, 1000, 1250]);
+  });
+
+  it('does not retry a failure that is not lock contention', () => {
+    let calls = 0;
+    const sleeps: number[] = [];
+    const notBusy = new Error(
+      'dispatch.ts: backlog task edit T-5 -s In Progress failed: Command failed — stderr: boom',
+    );
+
+    assert.throws(
+      () =>
+        withBoardWriteRetry(
+          'backlog task edit T-5 -s In Progress',
+          () => {
+            calls += 1;
+            throw notBusy;
+          },
+          { attempts: 6, baseDelayMs: 250, sleep: (ms) => sleeps.push(ms) },
+        ),
+      (error: unknown) => error === notBusy,
+    );
+
+    assert.equal(calls, 1);
+    assert.deepEqual(sleeps, []);
+  });
+
+  it('runs the default linear backoff sequence 250/500/750/1000/1250 across six attempts', () => {
+    const sleeps: number[] = [];
+
+    assert.throws(() =>
+      withBoardWriteRetry(
+        'backlog task edit T-5 -s In Progress',
+        () => {
+          throw busyError();
+        },
+        { ...BOARD_WRITE_RETRY_DEFAULTS, sleep: (ms) => sleeps.push(ms) },
+      ),
+    );
+
+    assert.deepEqual(sleeps, [250, 500, 750, 1000, 1250]);
+  });
+
+  // R4: `attempts: 0` (or negative) made the loop's condition false on iteration 1 — `run()` never
+  // executed, `lastError` stayed `undefined`, and `throw lastError` threw `undefined` instead of a
+  // real error, hiding whatever misconfiguration produced the bad count behind a useless stack
+  // trace with no message at all.
+  it('runs at least once even when attempts is 0 or negative', () => {
+    let calls = 0;
+    const result = withBoardWriteRetry(
+      'backlog task edit T-5 -s In Progress',
+      () => {
+        calls += 1;
+        return 'ok';
+      },
+      { attempts: 0, baseDelayMs: 250 },
+    );
+
+    assert.equal(result, 'ok');
+    assert.equal(calls, 1);
+  });
+
+  it('rethrows the real busy error, not undefined, when attempts is non-positive', () => {
+    const original = busyError();
+    assert.throws(
+      () =>
+        withBoardWriteRetry(
+          'backlog task edit T-5 -s In Progress',
+          () => {
+            throw original;
+          },
+          { attempts: -1, baseDelayMs: 250, sleep: () => {} },
+        ),
+      (error: unknown) => error === original,
+    );
+  });
+});
+
+describe('realBacklog — retries a busy board write', () => {
+  it('retries setStatus through the shared helper and succeeds without throwing', () => {
+    let calls = 0;
+    const sleeps: number[] = [];
+    realBacklog(MAIN_CHECKOUT, {
+      run: () => {
+        calls += 1;
+        if (calls < 2) {
+          throw new Error(
+            'dispatch.ts: backlog task edit T-5 -s In Progress failed: Command failed — stderr: Error: T-5 is ' +
+              'being modified by another process; retry if appropriate.',
+          );
+        }
+      },
+      retry: { attempts: 6, baseDelayMs: 250, sleep: (ms) => sleeps.push(ms) },
+    }).setStatus('T-5', TASK_STATUS.IN_PROGRESS);
+
+    assert.equal(calls, 2);
+    assert.deepEqual(sleeps, [250]);
+  });
+
+  it('does not retry a non-contention failure from setStatus', () => {
+    let calls = 0;
+    assert.throws(() =>
+      realBacklog(MAIN_CHECKOUT, {
+        run: () => {
+          calls += 1;
+          throw new Error(
+            'dispatch.ts: backlog task edit T-5 -s In Progress failed: Command failed — stderr: boom',
+          );
+        },
+        retry: { attempts: 6, baseDelayMs: 250, sleep: () => {} },
+      }).setStatus('T-5', TASK_STATUS.IN_PROGRESS),
+    );
+    assert.equal(calls, 1);
+  });
+});
+
+// `tickOwnedDod`'s default write also shells out to `backlog task edit --check-dod`, so it needs the
+// same retry: a `--check-dod` tick racing the same lock a status edit just released is the same
+// symptom, not a different one.
+describe('tickOwnedDod — retries a busy --check-dod write', () => {
+  const dodTaskText = [
+    'Task T-5 - A task',
+    '',
+    'Status: In Progress',
+    '',
+    'Definition of Done:',
+    '--------------------------------------------------',
+    '- [ ] #1 every acceptance criterion is checked',
+    '',
+  ].join('\n');
+  const pattern = /every acceptance criterion is checked/i;
+
+  it('retries the write and never throws once it succeeds', () => {
+    let calls = 0;
+    const sleeps: number[] = [];
+    assert.doesNotThrow(() =>
+      tickOwnedDod(MAIN_CHECKOUT, 'T-5', dodTaskText, pattern, {
+        run: () => {
+          calls += 1;
+          if (calls < 2) {
+            throw new Error(
+              'dispatch.ts: backlog task edit T-5 --check-dod 1 failed: Command failed — stderr: Error: T-5 is ' +
+                'being modified by another process; retry if appropriate.',
+            );
+          }
+        },
+        retry: { attempts: 6, baseDelayMs: 250, sleep: (ms) => sleeps.push(ms) },
+      }),
+    );
+
+    assert.equal(calls, 2);
+    assert.deepEqual(sleeps, [250]);
+  });
+
+  it('gives up after 6 attempts and swallows the failure — best-effort, never blocks the close', () => {
+    let calls = 0;
+    assert.doesNotThrow(() =>
+      tickOwnedDod(MAIN_CHECKOUT, 'T-5', dodTaskText, pattern, {
+        run: () => {
+          calls += 1;
+          throw new Error(
+            'dispatch.ts: backlog task edit T-5 --check-dod 1 failed: Command failed — stderr: Error: T-5 is ' +
+              'being modified by another process; retry if appropriate.',
+          );
+        },
+        retry: { attempts: 6, baseDelayMs: 1, sleep: () => {} },
+      }),
+    );
+
+    assert.equal(calls, 6);
+  });
+});
+
+// Measured defect (T-5, 2026-09-07): the `-s In Progress` edit failed with exit 1 and
+// `stderr: null` — the call ran with stderr silenced (`stdio: 'ignore'`), so the real cause (a
+// second reconciler pass touching the same task) never reached the `Blocked` comment or the log.
+describe('describeExecFailure', () => {
+  it('appends the captured stderr, trimmed, to the bare exec message', () => {
+    const error = Object.assign(new Error('Command failed: backlog task edit T-5 -s In Progress'), {
+      stderr: Buffer.from('Error: T-5 is already In Progress\n'),
+    });
+
+    assert.equal(
+      describeExecFailure(error),
+      'Command failed: backlog task edit T-5 -s In Progress — stderr: Error: T-5 is already In Progress',
+    );
+  });
+
+  it("falls back to the bare message when stderr was never captured (null, as `stdio: 'ignore'` used to leave it)", () => {
+    const error = Object.assign(new Error('Command failed: git add .backlog'), { stderr: null });
+
+    assert.equal(describeExecFailure(error), 'Command failed: git add .backlog');
+  });
+
+  it('truncates stderr to the first 500 chars', () => {
+    const error = Object.assign(new Error('Command failed: git commit'), {
+      stderr: Buffer.from('x'.repeat(600)),
+    });
+
+    assert.equal(
+      describeExecFailure(error),
+      `Command failed: git commit — stderr: ${'x'.repeat(500)}`,
+    );
+  });
+
+  it('handles a stderr already given as a string, not a Buffer', () => {
+    const error = Object.assign(new Error('Command failed: gh pr view'), {
+      stderr: '  not found  ',
+    });
+
+    assert.equal(describeExecFailure(error), 'Command failed: gh pr view — stderr: not found');
+  });
+
+  it('falls back to String(error) when the thrown value carries no message at all', () => {
+    assert.equal(describeExecFailure('boom'), 'boom');
+  });
+});
+
+// ── L3: the hooks the prompt precompute drives run against the SLOT, but read the BOARD ──────
+
+describe('buildHookRunners — the hook subprocess environment', () => {
+  it('passes BACKLOG_CWD so the hook reads the board from the main checkout, not the slot', () => {
+    const seen: Array<{ hook: string; cwd: string; env: Record<string, string> }> = [];
+    const runners = buildHookRunners(
+      '/repo',
+      '/slots/dispatch-a',
+      MAIN_CHECKOUT,
+      (hook, cwd, env) => {
+        seen.push({ hook, cwd, env });
+        return '';
+      },
+    );
+
+    runners.runInjectPromptContext('T-1 o-auth');
+
+    assert.equal(seen.length, 1);
+    // The slot has its own `.backlog/` copy and no board; the task block would come back empty (or,
+    // worse, from a stale copy) if the hook resolved the board against the cwd it runs in.
+    assert.equal(seen[0].cwd, '/slots/dispatch-a');
+    assert.equal(seen[0].env.BACKLOG_CWD, MAIN_CHECKOUT);
+  });
+
+  // The hook's own headless branch reads this: with it set, the injected task block states the
+  // dispatcher already moved the task to In Progress instead of pointing at the Task Gate.
+  it('marks the hook run as a dispatched one', () => {
+    const seen: Array<Record<string, string>> = [];
+    const runners = buildHookRunners(
+      '/repo',
+      '/slots/dispatch-a',
+      MAIN_CHECKOUT,
+      (_hook, _cwd, env) => {
+        seen.push(env);
+        return '';
+      },
+    );
+
+    runners.runBusinessRulesInjector('backend/src/x.ts');
+
+    assert.equal(seen[0].BACKLOG_DISPATCH_ACTIVE, '1');
+  });
+});