@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

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

@@ -0,0 +1,2304 @@
+/**
+ * dispatch.ts — the reconciler's executable entry point. Every trigger (`onStatusChange`, the
+ * launchd timer, a `gh`-poll) invokes exactly this script (spec: "Three dispatch triggers").
+ *
+ * Builds the REAL collaborators (real fs under `.backlog/.dispatch/`, real `git`/`gh`/`backlog`
+ * CLI shell-outs, a real `claude` spawn) and calls `runOnce` from `entry.ts` — every actual
+ * decision (maintenance order, the anti-loop guard, task selection, the six guards, the model
+ * readiness gate, the close ordering, the scope diff, the reviewer verdict, the AC/DoD gate) lives
+ * in the pure/injectable modules this file only wires together. See those modules' own tests for
+ * the decisions themselves; this file has no test of its own beyond the manual smoke run recorded
+ * in tasks.md 9.
+ *
+ * Process model (design.md's Tramo 7, README's "process model"): the pass holds the single-flight
+ * lock only until the slot is taken and the task is `In Progress` — `entry.ts` then calls
+ * `releaseSingleFlight`, and this process lives on, detached by the callback's `nohup`, until its
+ * worker exits. `launch.ts`'s `spawnWorker` runs the worker ASYNCHRONOUSLY and streams its stdout
+ * line by line into the attempt's `stream.jsonl`, which is also what refreshes the task lock's
+ * heartbeat. A concurrent invocation can therefore run its own maintenance pass and dispatch a
+ * second frontier task while this one is still streaming.
+ *
+ * Remaining simplification, deliberate: `ctx.tasks` is fetched once per pass, before maintenance's
+ * edits, so a maintenance-driven status change is only visible to task selection on the NEXT pass.
+ * Every trigger re-invokes this script, so it self-heals within one interval — never permanent
+ * staleness.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isSkillTriggerIndex, loadJsonIndex } from '../_catalog-runtime/index.js';
+import { findRepoRoot } from '../_catalog-runtime/repo-root.js';
+import {
+  countAttempts,
+  createAttemptDir,
+  createAttemptSink,
+  hasCloseAttemptBeenEnqueued,
+  markCloseAttemptEnqueued,
+} from './attempt.js';
+import {
+  buildAttemptCommitMessage,
+  buildPrBodyArgs,
+  buildPrCreateArgs,
+  buildPrLabelArgs,
+  buildPrReviewerArgs,
+  buildPrTitle,
+  buildWipCommitMessage,
+  checkBoardIntegrity,
+  collectAttemptDiff,
+  collectChangedFiles,
+  collectLeftoverFiles,
+  DOD_SCOPED_TESTS,
+  evaluateAcceptanceGate,
+  findOpenPrUrl,
+  formatBlockComment,
+  HARNESS_REVIEW_LABEL,
+  planMechanicalChecks,
+  readPrBody,
+  resolveBaseRef,
+  runMirrorRegen,
+  runScopeCheck,
+  upsertHumanReviewSection,
+  type CloseRunners,
+} from './close.js';
+import {
+  acquireSingleFlight,
+  formatOutcome,
+  isDispatcherOwnedCallback,
+  releaseSingleFlight,
+  resolveContext,
+  runOnce,
+  shouldDispatchFromCallback,
+  type RunOnceContext,
+  type SingleFlightFs,
+  type SingleFlightResult,
+} from './entry.js';
+import { SECURITY_PATH_PATTERNS } from './guards.js';
+import {
+  checkLocalModelLoaded,
+  killProcessTree,
+  loadLaneConfig,
+  loadSettingsAllowRules,
+  resetInjectorCache,
+  resolveOrphanInProgressThresholdMs,
+  settingsSourcePaths,
+  spawnWorker,
+  type FrontierLaneSettings,
+  type LocalLaneSettings,
+} from './launch.js';
+import {
+  PR_MERGE_STATE,
+  recomputeParent,
+  REMOTE_BRANCH_DELETE_RESULT,
+  toDerivationNode,
+  type MaintenanceContext,
+  type MaintenanceGit,
+  type PrMergeState,
+  type RemoteBranchDeleteResult,
+} from './maintenance.js';
+import { notify, type OsascriptRunner } from './notify.js';
+import { effectiveStatus } from './parent.js';
+import {
+  assembleExecutorPrompt,
+  buildFrontierAddendum,
+  buildFrontierPrompt,
+  buildParentCloseAttemptPrompt,
+  computeHookOutputs,
+  extractDelegationContract,
+  isParentCloseAttempt,
+  matchSkillPaths,
+  parseAcceptanceCriteria,
+  parseDefinitionOfDone,
+  parseIndexedAcceptanceCriteria,
+  parseLastComment,
+  type HookRunners,
+  type OperatingEnvelope,
+} from './prompt.js';
+import { reviewerEnv, runReviewer } from './reviewer.js';
+import {
+  computeLockfileHash,
+  createRegistryLock,
+  detachSlot,
+  isLockAlive,
+  isProcessAlive,
+  needsInstall,
+  provisionSlot,
+  readLock,
+  refreshHeartbeat,
+  releaseHeldSlotEntries,
+  releaseLock,
+  releaseSlotAndDetach,
+  slotPathForTask,
+  updateSlots,
+  type SlotRegistryStore,
+} from './slots.js';
+import {
+  findOwnedDefinitionOfDone,
+  parseBoardTaskIds,
+  parseTaskStatus,
+  parseTaskTitle,
+  parseTaskView,
+} from './task-view.js';
+import {
+  LANE,
+  TASK_STATUS,
+  type BoardLoad,
+  type DispatchLock,
+  type SlotRegistry,
+  type Task,
+  type TaskStatus,
+} from './types.js';
+import { workerEditCommand } from './worker-edit.js';
+
+const DISPATCH_SUBDIR = '.backlog/.dispatch';
+const SKILL_TRIGGERS_INDEX_FILE = '.claude/skills-triggers-index.json';
+const DELEGATION_CONTRACT_FILE = '.claude/skills/catalyst-delegation/SKILL.md';
+const WORKER_SYSTEM_PROMPT_FILE = '.claude/skills/catalyst-backlog/worker-system-prompt.md';
+/**
+ * The local lane's `--append-system-prompt-file`, resolved ABSOLUTELY against the repository root
+ * the dispatcher itself runs from — never left relative (T-31 round 3).
+ *
+ * `launch.ts` spawns the executor with `cwd` = the SLOT, so a relative path made the worker's own
+ * system prompt a file read FROM the slot: an instruction channel the attempt can write to, and one
+ * `--bare` does not close, because the flag is explicit on the command line. The frontier lane
+ * already does it this way (`writeFrontierAddendum` hands back an absolute path under the main
+ * checkout), and this is the same class of asset as the lane settings files and the addendum
+ * template — code, not board data, so it hangs off `repoRoot`.
+ *
+ * Two other mechanisms bound the same hole today (the local lane denies `.claude/**` outright, and
+ * `.claude/` is in `LOCAL_FORBIDDEN_PATHS`), which is exactly the "one mechanism is not enough"
+ * situation the hard list exists for: resolving the path closes the channel instead of watching it.
+ */
+export function resolveWorkerSystemPromptPath(repoRoot: string): string {
+  return path.join(repoRoot, WORKER_SYSTEM_PROMPT_FILE);
+}
+
+/** The frontier addendum's TEMPLATE — rendered per attempt by `prompt.ts`'s `buildFrontierAddendum`. */
+const FRONTIER_ADDENDUM_TEMPLATE_PATH =
+  '.claude/skills/catalyst-backlog/frontier-worker-addendum.md';
+const LINT_BARRELS_SCRIPT = 'hr:lint-barrels';
+/**
+ * How long a lock may go without a heartbeat before it counts as dead. Read by the maintenance
+ * sweep AND by the manual `--release-slot` guard: two different answers to "is this worker alive"
+ * is how a rescue releases a slot the sweep still considers busy.
+ */
+const LOCK_TTL_MS = 10 * 60_000;
+
+/**
+ * The dispatcher-owned Definition-of-Done items, and the close step that PROVES each one. The close
+ * ticks them itself once that step passed — see `task-view.ts`'s `DISPATCHER_OWNED_DOD_PATTERNS`.
+ * `DOD_SCOPED_TESTS` comes from `close.ts` instead of being redeclared here: the pre-PR gate FAILS
+ * on that item still being unticked, so the tick and the check must read one pattern.
+ */
+const DOD_PRETTIER_BARRELS = /prettier and barrels lint/i;
+const DOD_EVERY_AC = /every acceptance criterion is checked/i;
+const DOD_PR_OPENED = /pr opened to main/i;
+
+// ── Board loader: `backlog task list/view --plain` → `Task[]` ─────────────────
+
+function viewTask(mainCheckoutPath: string, taskId: string): string {
+  return execFileSync('backlog', ['task', 'view', taskId, '--plain'], {
+    cwd: mainCheckoutPath,
+    encoding: 'utf8',
+  });
+}
+
+/** The board reads `loadBoard` needs, injected so the loader is testable without a real CLI. */
+export interface BoardReader {
+  /** `backlog task list --plain`. */
+  list: () => string;
+  /** `backlog task view <id> --plain`. */
+  view: (taskId: string) => string;
+  /** How many attempt directories this task already has. */
+  attempts: (taskId: string) => number;
+}
+
+/**
+ * The board, plus whether reading it succeeded in full. Pure over the injected reader.
+ *
+ * An id whose `task view` fails is DROPPED, never stubbed: a stub carries `To Do`, no labels and no
+ * declared files, which reads on the board as a real untriaged task and makes every dependency on it
+ * look unmet. What the drop must NOT do is stay silent — hence `complete`.
+ */
+export function loadBoard(reader: BoardReader): BoardLoad {
+  let listOutput: string;
+  try {
+    listOutput = reader.list();
+  } catch (error) {
+    console.error(
+      'dispatch.ts: backlog task list failed; reporting an INCOMPLETE empty board:',
+      error,
+    );
+    return { tasks: [], complete: false };
+  }
+
+  let complete = true;
+  const tasks = parseBoardTaskIds(listOutput).flatMap((id) => {
+    try {
+      return [parseTaskView({ id, output: reader.view(id), attempts: reader.attempts(id) })];
+    } catch (error) {
+      console.error(
+        `dispatch.ts: backlog task view ${id} failed; dropping it from this pass:`,
+        error,
+      );
+      complete = false;
+      return [];
+    }
+  });
+  return { tasks, complete };
+}
+
+function loadAllTasks(mainCheckoutPath: string): BoardLoad {
+  const dispatchRoot = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
+  return loadBoard({
+    list: () =>
+      execFileSync('backlog', ['task', 'list', '--plain'], {
+        cwd: mainCheckoutPath,
+        encoding: 'utf8',
+      }),
+    view: (taskId) => viewTask(mainCheckoutPath, taskId),
+    attempts: (taskId) => countAttempts(dispatchRoot, taskId),
+  });
+}
+
+// ── Real collaborators ─────────────────────────────────────────────────────────
+
+/**
+ * `mainCheckoutPath` (possibly `BACKLOG_CWD`-overridden) is where BOARD DATA lives — `backlog` CLI
+ * calls, dispatch locks, `slots.json`. `repoRoot` (never overridden — always this machine's
+ * aurora-catalyst checkout, via `findRepoRoot`) is where the CODE assets `lanes.json` describes
+ * live: `scripts/backlog/lanes.json` itself, the lane settings files, and every worktree slot
+ * (`.claude/worktrees/dispatch-*`) is a checkout of THIS repo, not of whatever `BACKLOG_CWD`
+ * points at. These two axes coincide in real production (the reconciler always runs from the main
+ * checkout with no `BACKLOG_CWD` override) and only diverge for an isolated test run.
+ */
+export function realMaintenanceFs(mainCheckoutPath: string, repoRoot: string) {
+  const dispatchDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
+  const slotsPath = path.join(dispatchDir, 'slots.json');
+  const locksDir = path.join(dispatchDir, 'locks');
+
+  const readSlots = (): SlotRegistry => {
+    if (!fs.existsSync(slotsPath)) {
+      const laneConfig = loadLaneConfig(path.join(repoRoot, 'scripts/backlog/lanes.json'));
+      return {
+        slots: laneConfig.slots.map((name) => ({
+          name,
+          path: path.join(repoRoot, laneConfig.slotsRoot, name),
+          lane: null,
+          taskId: null,
+          pid: null,
+          lockfileHash: null,
+        })),
+      };
+    }
+    return JSON.parse(fs.readFileSync(slotsPath, 'utf8')) as SlotRegistry;
+  };
+
+  // ONE store, so every writer in this process goes through the same lock file. The lock lives
+  // beside the registry it guards; `updateSlots` re-reads inside it, so two concurrent passes can
+  // never overwrite each other's slot.
+  const store: SlotRegistryStore = {
+    readSlots,
+    writeSlots: (registry) => {
+      fs.mkdirSync(dispatchDir, { recursive: true });
+      fs.writeFileSync(slotsPath, JSON.stringify(registry, null, 2));
+    },
+    withLock: createRegistryLock(path.join(dispatchDir, 'slots.lock')),
+  };
+
+  return {
+    readSlots,
+    updateSlots: (mutate: (current: SlotRegistry) => SlotRegistry): SlotRegistry =>
+      updateSlots(store, mutate),
+    readLocks: (): DispatchLock[] => {
+      if (!fs.existsSync(locksDir)) {
+        return [];
+      }
+      return fs
+        .readdirSync(locksDir)
+        .filter((name) => name.endsWith('.json'))
+        .map(
+          (name) => JSON.parse(fs.readFileSync(path.join(locksDir, name), 'utf8')) as DispatchLock,
+        );
+    },
+    removeLock: (taskId: string): void => releaseLock(dispatchDir, taskId),
+    /**
+     * T-8 point 10's fourth orphan check: whether `.backlog/.dispatch/<taskId>/` exists at all —
+     * the same directory `createAttemptDir` opens BEFORE a worker starts. A task the dispatcher has
+     * ever touched keeps this directory forever (it is gitignored, not cleaned up), so its presence
+     * means "this task WAS dispatched", independent of whether any lock or slot survives today.
+     */
+    hasAttemptDir: (taskId: string): boolean => fs.existsSync(path.join(dispatchDir, taskId)),
+    // T-8 defect 3: the durable enqueue-time marker, filesystem-backed like everything else under
+    // `.backlog/.dispatch/` — see `attempt.ts`'s own JSDoc on both functions.
+    hasCloseAttemptBeenEnqueued: (taskId: string): boolean =>
+      hasCloseAttemptBeenEnqueued(dispatchDir, taskId),
+    markCloseAttemptEnqueued: (taskId: string): void =>
+      markCloseAttemptEnqueued(dispatchDir, taskId),
+  };
+}
+
+/** The `gh` runner shape, injected so `realGh` is testable without a real `gh` or a real repo. */
+type GhRunner = (
+  command: string,
+  args: string[],
+  options: { cwd: string; env?: Record<string, string> },
+) => string;
+
+const defaultGhRunner: GhRunner = (command, args, options) =>
+  execFileSync(command, args, {
+    cwd: options.cwd,
+    env: options.env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+
+/** The four env keys `gh` itself prefers over its own keyring login, in that order of precedence
+ * (measured against `gh`'s own auth resolution: an enterprise token wins for an enterprise host,
+ * `GH_TOKEN`/`GITHUB_TOKEN` otherwise). `ghEnv` does not need to reproduce that order — it only
+ * needs every one of them gone. */
+const GH_ENV_DENY = new Set([
+  'GITHUB_TOKEN',
+  'GH_TOKEN',
+  'GH_ENTERPRISE_TOKEN',
+  'GITHUB_ENTERPRISE_TOKEN',
+]);
+
+/**
+ * The parent environment minus the four keys `gh` prefers over its own keyring login.
+ *
+ * Measured defect (T-5, 2026-09-07, real e2e, close attempt 2): the dispatcher's own `gh pr view
+ * task/T-5` failed with `HTTP 401: Bad credentials`. The reconciler process inherits the developer
+ * shell's `GITHUB_TOKEN`, which is stale on this machine, and `gh` prefers an env token over its
+ * keyring login even when that login is valid (`GITHUB_TOKEN= gh auth status` on the same machine
+ * showed "Logged in to github.com account … (keyring)" throughout). Workers already run with every
+ * credential stripped (`launch.ts`'s `sanitizeInheritedEnv`); this is the same fix for the
+ * dispatcher's OWN `gh` calls, deliberately narrower: unlike `reviewerEnv` — which the reviewer
+ * subprocess can afford, since it never touches `gh` — this keeps every OTHER key (HOME, for `gh`'s
+ * own config; any unrelated token another tool in the same shell happens to export) so a dispatcher
+ * `gh` call loses nothing it did not need to lose.
+ */
+export function ghEnv(parentEnv: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parentEnv)) {
+    if (value === undefined || GH_ENV_DENY.has(key)) {
+      continue;
+    }
+    env[key] = value;
+  }
+  return env;
+}
+
+/**
+ * `gh` resolves the repository from the CWD it runs in, so `cwd` is not optional here: without it
+ * the call inherited whatever directory launched the reconciler — under launchd, `/` — and `gh pr
+ * view` then answered about no repository at all (or, from a nested checkout, about the wrong one).
+ * `false` is the answer either way, so the failure is silent: a merged subtask never moves to `Done`
+ * and its parent never derives.
+ */
+export function realGh(repoRoot: string, run: GhRunner = defaultGhRunner) {
+  return {
+    isPrMerged: (branch: string): boolean => {
+      try {
+        const output = run('gh', ['pr', 'view', branch, '--json', 'state,mergedAt'], {
+          cwd: repoRoot,
+          env: ghEnv(),
+        });
+        const parsed = JSON.parse(output) as { state?: string; mergedAt?: string | null };
+        return parsed.state === 'MERGED' && Boolean(parsed.mergedAt);
+      } catch {
+        return false; // no PR yet, gh unavailable, or not authenticated — fail closed.
+      }
+    },
+    /**
+     * T-8 point 3: the branch's most recent PR state (`OPEN`, `CLOSED`, `MERGED`), or `null` when
+     * `gh` reports no PR at all (or is unavailable/unauthenticated — the same fail-closed reading
+     * `isPrMerged` gives). Feeds `maintenance.ts`'s step 3b revert comment, so a person can tell a
+     * merged PR the sweep has not yet caught up to apart from one GitHub genuinely never merged.
+     */
+    prState: (branch: string): string | null => {
+      try {
+        const output = run('gh', ['pr', 'view', branch, '--json', 'state'], {
+          cwd: repoRoot,
+          env: ghEnv(),
+        });
+        const parsed = JSON.parse(output) as { state?: string };
+        return parsed.state ?? null;
+      } catch {
+        return null;
+      }
+    },
+    /**
+     * T-8 defect 1's tri-state answer — see `MaintenanceGh.mergedState`'s own JSDoc for why this
+     * cannot reuse `isPrMerged`'s boolean or `prState`'s `string | null` for the decision.
+     *
+     * Deliberately asks `gh pr list --head <branch> --state all`, NOT `gh pr view <branch>`: `pr
+     * view` throws identically whether there is no PR for the branch, the `gh` binary is missing,
+     * the token expired, or the network is down — the exact ambiguity `isPrMerged` inherits. `pr
+     * list` instead SUCCEEDS with an empty array when a branch genuinely has no PR — a real,
+     * confirmed answer (`not-merged`) — and only THROWS when the call itself could not run to
+     * completion, which is the only thing that becomes `unknown`.
+     */
+    mergedState: (branch: string): PrMergeState => {
+      try {
+        const output = run(
+          'gh',
+          [
+            'pr',
+            'list',
+            '--head',
+            branch,
+            '--state',
+            'all',
+            '--json',
+            'state,mergedAt',
+            '--limit',
+            '1',
+          ],
+          { cwd: repoRoot, env: ghEnv() },
+        );
+        const pulls = JSON.parse(output) as Array<{ state?: string; mergedAt?: string | null }>;
+        if (pulls.length === 0) {
+          return PR_MERGE_STATE.NOT_MERGED; // confirmed: no PR was ever opened for this branch.
+        }
+        const [pr] = pulls;
+        return pr.state === 'MERGED' && Boolean(pr.mergedAt)
+          ? PR_MERGE_STATE.MERGED
+          : PR_MERGE_STATE.NOT_MERGED;
+      } catch {
+        // gh binary missing, auth expired, network down — an unanswerable question, never "not merged".
+        return PR_MERGE_STATE.UNKNOWN;
+      }
+    },
+  };
+}
+
+/**
+ * Renders a failed `execFileSync` into a message that carries the child's actual stderr, not just
+ * the generic "Command failed: <cmd>" `error.message` gives on its own.
+ *
+ * Measured defect (T-5, 2026-09-07): every dispatcher-owned `backlog`/`git` write ran with stderr
+ * explicitly silenced (`stdio: 'ignore'`, or `['ignore', 'pipe', 'ignore']`), so a failed
+ * `-s In Progress` edit surfaced as exit 1 with `stderr: null` — the one piece of text that would
+ * have named the real cause (a second reconciler pass already touching the same task) was thrown
+ * away before it ever reached a `Blocked` comment or a log line. Capped at 500 chars: a comment or
+ * a log line is not the place for a multi-KB stack dump.
+ */
+export function describeExecFailure(error: unknown): string {
+  const failure = error as { message?: string; stderr?: Buffer | string | null } | null;
+  const message = failure?.message ?? String(error);
+  const stderrText = Buffer.isBuffer(failure?.stderr)
+    ? failure.stderr.toString('utf8')
+    : typeof failure?.stderr === 'string'
+      ? failure.stderr
+      : '';
+  const trimmed = stderrText.trim();
+  return trimmed ? `${message} — stderr: ${trimmed.slice(0, 500)}` : message;
+}
+
+/**
+ * Backlog.md's own wording for "another process holds this task's lock right now" (verified
+ * against the real CLI's stderr, T-5's measured e2e run). Matched case-insensitively against the
+ * FULL failure message — `describeExecFailure` folds stderr into it — never against a raw
+ * `error.message` alone, which for a silenced `execFileSync` carries only "Command failed: …".
+ */
+const BOARD_BUSY_PATTERN = /being modified by another process/i;
+
+/**
+ * Git's own wording for "the remote ref this push tried to delete does not exist" (verified against
+ * the real CLI's stderr — the existing `realGit — deleteRemoteBranch` test fixture below). Matched
+ * against the failure's `.message` — real `execFileSync` failures fold stderr into that string via
+ * `describeExecFailure`'s wrapping `run`, and an injected test `run` throws the raw string directly,
+ * so one pattern covers both.
+ */
+const REMOTE_REF_ALREADY_GONE_PATTERN = /remote ref does not exist/i;
+
+/**
+ * Git's own FIXED wording for "this ref does not resolve to anything" (`git rev-parse --verify
+ * <ref>`, deliberately without `--quiet` — see `branchHasUnmergedCommits`'s own comment for why).
+ * Measured directly (2026-09-08): a genuinely absent ref fails with exactly this text, exit 128; a
+ * missing `git` binary fails with `spawnSync git ENOENT` (no such text, no `Command failed:`
+ * prefix at all); a broken checkout (`fatal: not a git repository…`) fails with DIFFERENT text.
+ * Matched so `branchHasUnmergedCommits`'s first check can tell a confirmed-absent remote-tracking
+ * ref (safe: nothing survives on the remote to lose) apart from any OTHER failure of the same
+ * call (S2, 2026-09-08: the previous version read every failure of this call the same way,
+ * silently authorising a delete on a question it never actually answered).
+ */
+const BRANCH_REF_NOT_FOUND_PATTERN = /needed a single revision/i;
+
+export interface BoardWriteRetryOptions {
+  /** Total tries, including the first one. Real callers pass 6. */
+  attempts: number;
+  /** Linear backoff step: the Nth failed attempt sleeps `baseDelayMs * N` before the next try. */
+  baseDelayMs: number;
+  /** Injected by tests so a retry never blocks on a real timer. Defaults to a blocking real sleep. */
+  sleep?: (ms: number) => void;
+}
+
+export const BOARD_WRITE_RETRY_DEFAULTS: BoardWriteRetryOptions = { attempts: 6, baseDelayMs: 250 };
+
+/** Blocks the calling thread — the same pattern `slots.ts`'s registry lock retry uses, and for the
+ * same reason: the reconciler has nothing useful to do while Backlog.md's own lock is held, and the
+ * alternative is making every dispatcher-owned write asynchronous. */
+function defaultBlockingSleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Retries a dispatcher-owned `backlog` WRITE when Backlog.md's per-task lock is held by someone
+ * else at that exact instant — a person editing the same task, or a second reconciler pass.
+ *
+ * Measured defect (T-5, 2026-09-07, real e2e): the dispatcher's own `task edit T-5 -s In Progress`
+ * collided with the lock `onStatusChange` holds for the length of its callback and failed outright
+ * 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 the dispatcher must still tolerate the
+ * instant a person or a second reconciler holds it — hence this bounded, linear-backoff retry.
+ *
+ * `command` names the call for the retry log line ONLY; it never reaches a shell. Any failure whose
+ * message does NOT match Backlog.md's own busy wording is not a contention symptom and rethrows at
+ * once — retrying it would only delay the real error behind a fixed backoff. After the last attempt
+ * the ORIGINAL error is rethrown untouched, so a caller (or a human reading the comment/log it
+ * produced) still sees the real cause, not a synthetic "gave up" wrapper.
+ */
+export function withBoardWriteRetry<T>(
+  command: string,
+  run: () => T,
+  options: BoardWriteRetryOptions = BOARD_WRITE_RETRY_DEFAULTS,
+): T {
+  const sleep = options.sleep ?? defaultBlockingSleep;
+  // A non-positive `attempts` made the loop 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. Guaranteed
+  // at least one real attempt runs, the same way every other bounded-retry helper in this file does.
+  const attempts = Math.max(1, options.attempts);
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return run();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!BOARD_BUSY_PATTERN.test(message)) {
+        throw error;
+      }
+      lastError = error;
+      if (attempt === attempts) {
+        break;
+      }
+      console.error(`dispatch.ts: board busy, retry ${attempt}/${attempts} for ${command}`);
+      sleep(options.baseDelayMs * attempt);
+    }
+  }
+  throw lastError;
+}
+
+export interface RealBacklogDeps {
+  /**
+   * Injected by tests so no `backlog` CLI ever runs; the default wraps a real, stderr-capturing
+   * `execFileSync` and is what tests assert `env.BACKLOG_DISPATCH_ACTIVE` against.
+   */
+  run?: (args: string[], options: { cwd: string; env: NodeJS.ProcessEnv }) => void;
+  /** Overrides `withBoardWriteRetry`'s defaults — tests inject a synchronous, instant `sleep`. */
+  retry?: Partial<BoardWriteRetryOptions>;
+}
+
+const defaultBacklogRun: NonNullable<RealBacklogDeps['run']> = (args, options) => {
+  try {
+    execFileSync('backlog', args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    throw new Error(`dispatch.ts: backlog ${args.join(' ')} failed: ${describeExecFailure(error)}`);
+  }
+};
+
+/**
+ * Every write here is a DISPATCHER-OWNED status/comment edit, and every one of them now runs with
+ * `BACKLOG_DISPATCH_ACTIVE='1'` in its env — not because this process itself must recognize its own
+ * writes (it already tracks that via the per-task lock and the single-flight lock), but because the
+ * `onStatusChange` callback THIS EDIT FIRES inherits whatever env the `backlog` CLI child ran with.
+ * Without the sentinel, that nested invocation had no way to tell a dispatcher-owned write apart
+ * from a genuine human one — see `entry.ts`'s `isDispatcherOwnedCallback`, and the measured T-5
+ * defect in `dispatch.test.ts`'s "the dispatcher-owned write sentinel" suite.
+ *
+ * Every write also goes through `withBoardWriteRetry`: Backlog.md holds the SAME per-task lock a
+ * person or a second reconciler pass can be holding at this exact instant — see that function's own
+ * header for the measured T-5 defect this closes.
+ */
+export function realBacklog(mainCheckoutPath: string, deps: RealBacklogDeps = {}) {
+  const run = deps.run ?? defaultBacklogRun;
+  const retryOptions: BoardWriteRetryOptions = { ...BOARD_WRITE_RETRY_DEFAULTS, ...deps.retry };
+  const ownedWrite = (args: string[]): void =>
+    withBoardWriteRetry(
+      `backlog ${args.join(' ')}`,
+      () =>
+        run(args, { cwd: mainCheckoutPath, env: { ...process.env, BACKLOG_DISPATCH_ACTIVE: '1' } }),
+      retryOptions,
+    );
+
+  return {
+    setStatus: (taskId: string, status: TaskStatus, comment?: string): void => {
+      const args = ['task', 'edit', taskId, '-s', status];
+      if (comment) {
+        args.push('--comment', comment);
+      }
+      ownedWrite(args);
+    },
+    comment: (taskId: string, comment: string): void => {
+      ownedWrite(['task', 'edit', taskId, '--comment', comment]);
+    },
+  };
+}
+
+/**
+ * The worktree slot currently assigned to `taskId`, or `null` when no slot holds it.
+ *
+ * `null` is a real answer the caller MUST handle, never a directory to fall back to. Falling back
+ * to the main checkout pointed every close runner at the developer's own working tree: a `git add
+ * -A` + WIP commit over whatever was in progress there, a scope diff of somebody else's changes,
+ * and a `gh pr create` off the main checkout's branch.
+ */
+export function findSlotPathForTask(mainCheckoutPath: string, taskId: string): string | null {
+  const slotsPath = path.join(mainCheckoutPath, DISPATCH_SUBDIR, 'slots.json');
+  if (!fs.existsSync(slotsPath)) {
+    return null;
+  }
+  return slotPathForTask(JSON.parse(fs.readFileSync(slotsPath, 'utf8')) as SlotRegistry, taskId);
+}
+
+export interface RealGitDeps {
+  /** Injected by tests so no lookup ever reaches the real `slots.json` of a live checkout. */
+  slotPathFor?: (taskId: string) => string | null;
+  /** Injected by tests so no `git` ever runs; the default is a real, output-silenced `execFileSync`. */
+  run?: (command: string, args: string[], cwd: string) => void;
+}
+
+/**
+ * The dispatcher's own git side effects. Every `git commit` here runs `--no-verify`, and that is a
+ * safety property, not a convenience: a slot's `.husky/` hooks are FILES IN THE WORKING TREE the
+ * worker just wrote in, so committing its work through them would execute code the model under
+ * dispatch authored — with the dispatcher's own privileges. The board commit takes the same flag
+ * because it runs unattended in the main checkout, where a hook that stashes (lint-staged does)
+ * would reach into whatever a person has in progress there. Nothing is lost by it: both messages
+ * are machine-built and `close.test.ts` runs them through the repo's real commitlint.
+ */
+export function realGit(mainCheckoutPath: string, deps: RealGitDeps = {}): MaintenanceGit {
+  const slotPathFor =
+    deps.slotPathFor ??
+    ((taskId: string): string | null => findSlotPathForTask(mainCheckoutPath, taskId));
+  const resolveSlotPath = (branch: string): string | null =>
+    slotPathFor(branch.replace(/^task\//, ''));
+  const run =
+    deps.run ??
+    ((command, args, cwd) => {
+      try {
+        execFileSync(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (error) {
+        throw new Error(
+          `dispatch.ts: ${command} ${args.join(' ')} failed: ${describeExecFailure(error)}`,
+        );
+      }
+    });
+
+  return {
+    hasPendingBacklogChanges: (): boolean => {
+      try {
+        const output = execFileSync('git', ['status', '--porcelain', '--', '.backlog'], {
+          cwd: mainCheckoutPath,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'], // a non-git BACKLOG_CWD (e.g. an isolated test project) fails loudly on stderr otherwise, even though the catch below already handles it silently.
+        });
+        return output.trim().length > 0;
+      } catch {
+        return false; // not a git repo (e.g. a scratch smoke-test project) — nothing to commit.
+      }
+    },
+    commitBacklogChanges: (message: string): void => {
+      run('git', ['add', '.backlog'], mainCheckoutPath);
+      // The trailing pathspec, not the `add`, is what bounds this commit: staging adds to the index
+      // but does not narrow what a commit takes, so a person's own already-staged work in the main
+      // checkout would otherwise ride along inside an unattended machine commit.
+      run('git', ['commit', '-m', message, '--no-verify', '--', '.backlog'], mainCheckoutPath);
+    },
+    saveWipAndPush: (branch: string) => {
+      const cwd = resolveSlotPath(branch);
+      if (cwd === null) {
+        // No slot holds this task, so there is no work to save — and running `git add -A` in the
+        // main checkout would commit whatever a person has in progress there.
+        console.error(`dispatch.ts: no slot holds ${branch}; nothing to save.`);
+        return { pushSucceeded: false };
+      }
+      const taskId = branch.replace(/^task\//, '');
+      try {
+        run('git', ['add', '-A'], cwd);
+        run(
+          'git',
+          ['commit', '-m', buildWipCommitMessage(taskId), '--allow-empty', '--no-verify'],
+          cwd,
+        );
+        run('git', ['push', 'origin', branch], cwd);
+        return { pushSucceeded: true };
+      } catch {
+        return { pushSucceeded: false };
+      }
+    },
+    detachSlot: (slotPath: string): void =>
+      detachSlot(slotPath, (args, at) => run('git', args, at)),
+    branchExists: (branch: string): boolean => {
+      // The local ref first — cheap, no network. `--quiet` suppresses the "not a valid ref" noise
+      // `run`'s error wrapper would otherwise carry, and a throw here means only "no such local
+      // ref", never a reason to stop looking: the remote is checked next.
+      try {
+        run('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], mainCheckoutPath);
+        return true;
+      } catch {
+        // fall through to the remote check below.
+      }
+      try {
+        run('git', ['ls-remote', '--exit-code', '--heads', 'origin', branch], mainCheckoutPath);
+        return true;
+      } catch {
+        return false; // absent on both — the legitimate "never pushed" case T-8 point 7 relies on.
+      }
+    },
+    deleteLocalBranch: (branch: string): void => {
+      try {
+        run('git', ['branch', '-D', branch], mainCheckoutPath);
+      } catch {
+        // Tolerant by design (see this method's JSDoc on `MaintenanceGit`): the common case is a
+        // task never checked out in the main checkout at all, and this cleanup step must never
+        // fail the `Done` transition it runs alongside.
+      }
+    },
+    deleteRemoteBranch: (branch: string): RemoteBranchDeleteResult => {
+      try {
+        run('git', ['push', 'origin', '--delete', branch], mainCheckoutPath);
+        return REMOTE_BRANCH_DELETE_RESULT.DELETED;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (REMOTE_REF_ALREADY_GONE_PATTERN.test(message)) {
+          // GitHub's own "Automatically delete head branches" (enabled 2026-09-08) routinely beats
+          // this call to it — the NORMAL outcome, not a failure to report.
+          return REMOTE_BRANCH_DELETE_RESULT.ALREADY_GONE;
+        }
+        // A REAL failure (bad auth, a protected-branch rule, a network timeout) — defect 7,
+        // 2026-09-08: this used to be swallowed identically to the "already gone" case above, so
+        // the remote ref stayed alive with no log line and no honest signal in the result. See
+        // `maintenance.ts`'s `cleanupBranchOnDone` for what this outcome now does with it.
+        console.error(`dispatch.ts: git push origin --delete ${branch} failed:`, message);
+        return REMOTE_BRANCH_DELETE_RESULT.FAILED;
+      }
+    },
+    branchHasUnmergedCommits: (branch: string, baseRef: string): boolean => {
+      // The remote-tracking ref, not the local one: the rescue push (`saveWipAndPush`) lands its
+      // commits on `origin/<branch>` from inside a SLOT, and this runs in the main checkout, which
+      // never checks the branch out itself. `entry.ts` runs `git fetch origin --prune` at the top
+      // of every pass, before maintenance ever executes, so this remote-tracking ref is fresh for
+      // the SAME pass that is about to compare it — no extra fetch needed here.
+      //
+      // Deliberately WITHOUT `--quiet`: that flag suppresses git's own diagnostic on the exact
+      // failure this check needs to recognise, collapsing it into the SAME silent, empty-stderr
+      // failure a missing `git` binary or a broken checkout also produces through this `run` seam
+      // (which only ever surfaces a thrown Error's `.message`, never the raw exit code). Keeping
+      // the diagnostic is what lets `BRANCH_REF_NOT_FOUND_PATTERN` tell them apart.
+      try {
+        run('git', ['rev-parse', '--verify', `refs/remotes/origin/${branch}`], mainCheckoutPath);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (BRANCH_REF_NOT_FOUND_PATTERN.test(message)) {
+          // No remote-tracking ref at all (already deleted — GitHub's own auto-delete, or an
+          // earlier pass — or never pushed): nothing survives on the remote to lose, so there is
+          // nothing to refuse either.
+          return false;
+        }
+        // S2 [LOW], 2026-09-08: any OTHER failure of this call (the `git` binary missing, a
+        // corrupted checkout, a permissions error) is NOT a confirmed-absent answer — it is an
+        // unanswerable question, and `deleteLocalBranch` runs right after this on a `true` result,
+        // so misreading it as "nothing to lose" destroys the only copy of the branch on a mere
+        // inability to check. Fail in the SAME safe direction as the merge-base check below.
+        return true;
+      }
+      // `git merge-base --is-ancestor A B` exits 0 iff A is reachable from B — i.e. the branch's
+      // tip is fully contained in the base, so it carries nothing beyond it. Reuses the SAME `run`
+      // seam every other method here does (no new collaborator, no stdout to capture): any other
+      // outcome — genuinely not an ancestor, or an unreachable/unresolvable ref — throws through
+      // `run`'s wrapper, and both collapse to the SAME fail-safe refusal, since deletion is
+      // destructive and only a CONFIRMED-clean answer authorises it.
+      //
+      // S1 (2026-09-08): this check has an UNDECLARED dependency on the GitHub merge strategy. It
+      // is correct as shipped because this repo merges PRs with merge commits, so the branch tip
+      // stays a real ancestor of `baseRef` once merged. A squash or a rebase merge REWRITES the
+      // commits onto the base under a new SHA, so the original branch tip is no longer reachable
+      // from it — `--is-ancestor` would then answer "false" for EVERY genuinely-merged branch, and
+      // this refuses every delete, leaving `branchCleanupRefused` (and its PR comment) fire on
+      // every single `Done` task. Flipping the repo's merge strategy is what would break this, not
+      // a code change here — the next reader who considers that flip must re-derive this check.
+      try {
+        run('git', ['merge-base', '--is-ancestor', `origin/${branch}`, baseRef], mainCheckoutPath);
+        return false;
+      } catch {
+        return true;
+      }
+    },
+  };
+}
+
+function runOsascript(args: string[]): void {
+  try {
+    execFileSync('osascript', args, { stdio: 'ignore' });
+  } catch {
+    // Best-effort: a missing osascript (non-Mac, sandboxed CI) must never fail the pass.
+  }
+}
+
+// ── Close runners ──────────────────────────────────────────────────────────────
+
+export interface BuildCloseRunnersInput {
+  mainCheckoutPath: string;
+  repoRoot: string;
+  task: Task;
+  attempt: number;
+  branch: string;
+  reviewerModel: string;
+  /** Wall-clock bound on the reviewer subprocess (`lanes.json`'s `reviewerTimeoutMinutes`). */
+  reviewerTimeoutMs: number;
+  /** Set by the close's `drain` step: main runs one more pass when the slot frees up. */
+  requestDrain: () => void;
+  /** The board snapshot this pass read, for the parent recomputation. */
+  tasksById: Record<string, Task>;
+  /**
+   * Whether that snapshot is the WHOLE board (`BoardLoad.complete` of the post-sweep re-read). The
+   * parent recomputation is SKIPPED when it is false: a derivation over some of the children
+   * produces a confident wrong answer — the same reason the maintenance sweep refuses it — and
+   * `reloadTasks` used to drop the flag, so the close derived from a partial board unaware.
+   */
+  boardComplete: boolean;
+  /**
+   * `lanes.json`'s `attempts` cap (T-8 point 6) — threaded into `openPr`'s composed PR body
+   * alongside the attempt number, so a reviewer reading the PR sees "intento 2 de 3" rather than a
+   * bare count with no ceiling to judge it against. Optional so a caller with no lane config in
+   * hand (every existing test fixture) still gets `buildPrCreateArgs`'s own fallback.
+   */
+  maxAttempts?: number;
+  /**
+   * `lanes.json`'s optional top-level `harnessReviewer` handle (T-31, design.md decision 8). Ships
+   * UNSET: `gh pr create --reviewer <self>` (and the equivalent edit) fails when the reviewer is the
+   * pull request's own author, and the dispatcher opens every PR as the same account. When absent,
+   * `openPr` records that once rather than attempting a call doomed to fail.
+   */
+  harnessReviewer?: string;
+  /** Injected by tests; defaults to the real `slots.json` lookup. `null` = no slot holds the task. */
+  slotPathFor?: (taskId: string) => string | null;
+  /** Injected by tests; defaults to a real `execFileSync` returning stdout. */
+  run?: RunInSlot;
+  /** Injected by tests; defaults to `spawnCapture` — never throws, reports the exit status. */
+  runCapturing?: (
+    command: string,
+    args: string[],
+    cwd: string,
+  ) => { status: number; output: string };
+  /**
+   * Reads `backlog task view <id> --plain`. Injected so the board reads every runner makes — the
+   * integrity gate, the pre-PR gate, the PR title, the DoD ticks, the parent recomputation — are
+   * driven in tests without spawning `backlog`, which is what lets the "no runner ever operates on
+   * the main checkout" suite actually exercise them instead of stopping at the four that shell out.
+   */
+  viewTask?: (taskId: string) => string;
+  /** Injected by tests; defaults to the real `osascript` call, which would pop a real notification. */
+  runOsascript?: OsascriptRunner;
+}
+
+type RunInSlot = (
+  command: string,
+  args: string[],
+  options: { cwd: string; env?: Record<string, string>; timeout?: number },
+) => string;
+
+/**
+ * A whole attempt diff routinely runs into megabytes, and `execFileSync`'s 1 MB default turns that
+ * into a THROWN ENOBUFS rather than a big string — silently, on exactly the large changes most
+ * worth reviewing. Same reason on the reviewer: its transcript carries the diff back.
+ */
+const LARGE_OUTPUT_MAX_BUFFER = 50 * 1024 * 1024;
+
+/** Why every runner fails when no slot holds the task — see `findSlotPathForTask`. */
+const NO_SLOT_QUESTION =
+  'la tarea no tiene slot asignado en slots.json: no hay directorio donde verificar ni guardar su trabajo.';
+
+export function buildCloseRunners(input: BuildCloseRunnersInput): CloseRunners {
+  const { mainCheckoutPath, repoRoot, task, attempt, branch, tasksById } = input;
+  const slotPath =
+    input.slotPathFor ??
+    ((taskId: string): string | null => findSlotPathForTask(mainCheckoutPath, taskId));
+  const runIn: RunInSlot =
+    input.run ??
+    ((command, args, options) =>
+      execFileSync(command, args, {
+        cwd: options.cwd,
+        encoding: 'utf8',
+        env: options.env,
+        timeout: options.timeout,
+        maxBuffer: LARGE_OUTPUT_MAX_BUFFER,
+      }));
+  const runCapturing = input.runCapturing ?? spawnCapture;
+  const osascript = input.runOsascript ?? runOsascript;
+  const readTask = (): string => {
+    try {
+      return (input.viewTask ?? ((taskId: string) => viewTask(mainCheckoutPath, taskId)))(task.id);
+    } catch (error) {
+      console.error(`dispatch.ts: backlog task view ${task.id} failed:`, error);
+      return '';
+    }
+  };
+  const attemptDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR, task.id, `intento-${attempt}`);
+  const base = resolveBaseRef(task, tasksById);
+  // Set by `scopeCheck` below, read by `openPr`'s human-review mark — never recomputed at PR time
+  // (design.md decision 8, T-31): by then `mirrorRegen` has written into
+  // `packages/cli/src/templates/`, and a recomputation would match `packages/cli/` and mark EVERY
+  // attempt that touched any mirrored root, which is a mark that fires always and says nothing.
+  let humanReviewFiles: readonly string[] = [];
+
+  return {
+    // Re-read the board and compare it against the launch snapshot BEFORE any step trusts it. The
+    // worker held a `backlog task edit` grant on this task for its whole run.
+    boardCheck: () => checkBoardIntegrity({ taskText: readTask(), task }),
+    // An absent lane is unreachable here (guard 1 blocks it), so the fallback only decides which
+    // way to be wrong: LOCAL is the stricter check of the two.
+    scopeCheck: () => {
+      const cwd = slotPath(task.id);
+      if (cwd === null) {
+        return {
+          ok: false,
+          reason: 'scope-check-failed',
+          question: NO_SLOT_QUESTION,
+          humanReviewFiles: [],
+        };
+      }
+      const result = runScopeCheck({
+        lane: task.lane ?? LANE.LOCAL,
+        declaredFiles: task.filesToTouch,
+        base,
+        runGit: (args) => runIn('git', args, { cwd }),
+      });
+      if (result.ok) {
+        humanReviewFiles = result.humanReviewFiles;
+      }
+      return result;
+    },
+    formatLintTest: () => {
+      const cwd = slotPath(task.id);
+      if (cwd === null) {
+        return { ok: false, reason: 'format-lint-test-failed', question: NO_SLOT_QUESTION };
+      }
+      // The command SNAPSHOTTED at launch, never re-read here: the worker had `backlog task edit`
+      // on its own task all run, so a close that re-reads the board runs whatever the thing under
+      // test decided it should be verified with.
+      //
+      // `task.testCommand` is non-null on every REAL dispatch: guard 1 blocks a task that declares
+      // no `Test command:` line before a worker ever starts, so this close only ever sees one that
+      // passed that guard. `planMechanicalChecks` still handles the null (it is a pure planner with
+      // its own tests) — there is simply no branch to take here.
+
+      let changedFiles: string[];
+      try {
+        changedFiles = collectChangedFiles({ base, runGit: (args) => runIn('git', args, { cwd }) });
+      } catch (error) {
+        return {
+          ok: false,
+          reason: 'format-lint-test-failed',
+          question: `git no se pudo ejecutar: ${describeExecFailure(error)}`,
+        };
+      }
+
+      const plan = planMechanicalChecks({
+        testCommand: task.testCommand,
+        lintBarrels: hasLintBarrelsScript(repoRoot),
+        changedFiles,
+        exists: (file) => fs.existsSync(path.join(cwd, file)),
+      });
+      if (plan.skippedPrettierFiles.length > 0) {
+        // Prettier is not a root dependency, so a file outside `backend/`, `frontier/` or the two
+        // core packages has no formatter to run — reported, not silently treated as formatted.
+        console.warn(
+          `dispatch.ts: ${task.id} — no prettier workspace covers: ${plan.skippedPrettierFiles.join(', ')}`,
+        );
+      }
+      if (plan.refusal) {
+        return { ok: false, reason: 'format-lint-test-failed', question: plan.refusal };
+      }
+
+      for (const check of plan.checks) {
+        const result = runCapturing(check.command, check.args, cwd);
+        fs.appendFileSync(
+          path.join(attemptDir, 'test.log'),
+          `$ ${check.command} ${check.args.join(' ')}\n${result.output}\n`,
+        );
+        if (result.status !== 0) {
+          return {
+            ok: false,
+            reason: 'format-lint-test-failed',
+            question: `Falló "${check.label}"; mira test.log.`,
+          };
+        }
+      }
+
+      // The triad just proved these; ticking them here is what keeps the pre-PR gate from failing
+      // a green attempt on bookkeeping the worker was never asked to do. "Scoped tests pass" is
+      // ticked ONLY when a test check actually ran: ticking it because the step as a whole returned
+      // green would assert a test that never existed, and the gate that follows is what turns that
+      // silence into a failed attempt rather than into a PR.
+      const taskText = readTask();
+      if (plan.checks.some((check) => check.label === 'test')) {
+        tickOwnedDod(mainCheckoutPath, task.id, taskText, DOD_SCOPED_TESTS);
+      }
+      tickOwnedDod(mainCheckoutPath, task.id, taskText, DOD_PRETTIER_BARRELS);
+      return { ok: true };
+    },
+    // Regenerates the CLI scaffold mirror when the attempt touched a root the packager reads, so the
+    // PR passes CI's `Check mirror <-> source drift`. It runs AFTER the triad on purpose: that step
+    // rewrites the attempt's own files with `prettier --write`, and a mirror copied before it would
+    // be stale the moment it did. See `runMirrorRegen` for the rest of the reasoning.
+    mirrorRegen: () => {
+      const cwd = slotPath(task.id);
+      if (cwd === null) {
+        return { ok: false, reason: 'mirror-regen-failed', question: NO_SLOT_QUESTION };
+      }
+
+      // Both callbacks re-throw through `describeExecFailure`: an `execFileSync` throw carries only
+      // "Command failed: node scripts/packager/publish.mjs" in its `message`, and the packager's
+      // real complaint (a missing source directory, an fs-extra error) is in the stderr nobody
+      // prints. The `Blocked` comment is the only channel telling a person why the attempt stopped.
+      const result = runMirrorRegen({
+        base,
+        runGit: (args) => {
+          try {
+            return runIn('git', args, { cwd });
+          } catch (error) {
+            throw new Error(describeExecFailure(error));
+          }
+        },
+        driftCheckWorkflow: readDriftCheckWorkflow(cwd),
+        runPackager: () => {
+          try {
+            runIn('node', [MIRROR_PACKAGER_SCRIPT], { cwd });
+          } catch (error) {
+            throw new Error(describeExecFailure(error));
+          }
+        },
+      });
+
+      if (result.regenerated) {
+        console.error(
+          `dispatch.ts: ${task.id} — espejo del scaffold regenerado (${result.mirrorFiles.length} ficheros bajo ` +
+            'packages/cli/src/templates/); viajan en el commit del intento.',
+        );
+      }
+      return result;
+    },
+    reviewer: () => {
+      const cwd = slotPath(task.id);
+      if (cwd === null) {
+        return { ok: false, reason: 'reviewer-failed', question: NO_SLOT_QUESTION };
+      }
+
+      // An uncollectable diff FAILS the step. Handing the reviewer a note saying git blew up reads
+      // to it as an empty change set, and it duly approves code it never saw.
+      let diff: string;
+      try {
+        diff = collectAttemptDiff({ base, runGit: (args) => runIn('git', args, { cwd }) });
+      } catch (error) {
+        return {
+          ok: false,
+          reason: 'reviewer-failed',
+          question: `no se pudo obtener el diff: ${describeExecFailure(error)}`,
+        };
+      }
+
+      return runReviewer({
+        taskId: task.id,
+        model: input.reviewerModel,
+        diff,
+        acceptanceCriteria: parseAcceptanceCriteria(readTask()),
+        // The reviewer runs on the ACCOUNT, never on LM Studio. `reviewerEnv` drops every
+        // `ANTHROPIC_*` key — the lane's LM Studio overlay so a weak local executor can never end up
+        // reviewing itself (design.md's close diagram, `SR`), and the API key with it, because a
+        // stale one in the dispatcher's shell takes precedence over the account's claude.ai login
+        // and left the reviewer unable to start at all. Bounded, because it runs while this process
+        // still owns the slot.
+        //
+        // The failure is rendered with the child's stderr: `execFileSync`'s own `error.message` is
+        // "Command failed: claude -p …", and the T-5 run's `review.md` said exactly that and
+        // nothing more — the auth error that explained it was in the stderr nobody printed.
+        run: (command, args) => {
+          try {
+            return runIn(command, args, {
+              cwd,
+              env: reviewerEnv(),
+              timeout: input.reviewerTimeoutMs,
+            });
+          } catch (error) {
+            throw new Error(describeExecFailure(error));
+          }
+        },
+        writeReview: (content) => fs.writeFileSync(path.join(attemptDir, 'review.md'), content),
+      });
+    },
+    acCheck: () => {
+      // Re-read the task: the worker ticked its acceptance criteria through the `backlog` CLI while
+      // it worked, so the snapshot this pass started with is stale by definition here.
+      const result = evaluateAcceptanceGate(readTask());
+      if (result.ok) {
+        tickOwnedDod(mainCheckoutPath, task.id, readTask(), DOD_EVERY_AC);
+      }
+      return result;
+    },
+    openPr: () => {
+      const cwd = slotPath(task.id);
+      if (cwd === null) {
+        return { ok: false, reason: 'open-pr-failed', question: NO_SLOT_QUESTION };
+      }
+      // Applies the human-review mark's two best-effort halves — a SEPARATE `gh pr edit` call each
+      // (design.md decision 8, T-31): a rejected reviewer must not take the label down with it, and
+      // a label the repository does not have must not fail the close at all. Each failure is
+      // RECORDED (never propagated) with `describeExecFailure`, same as every other best-effort gh
+      // call in this runner. No-op when the scope check reported no soft-list file.
+      // The mark's BODY half, for the REUSE branch only: a newly created pull request already
+      // carries it inside `gh pr create --body` (`buildPrCreateArgs`), which is what makes that half
+      // unfailable. A retry has no create call at all, so without this the reused pull request names
+      // no soft-list file and the whole mark rests on the two `gh pr edit` calls the design allows to
+      // fail.
+      //
+      // It READS the body first and edits only its own delimited section
+      // (`upsertHumanReviewSection`). `gh pr edit --body` is a full replacement, and these are by
+      // construction the pull requests a person was asked to read and annotate — recomposing the
+      // body from the board erased every word that person had added (T-31 round 2). A body that
+      // cannot be read is not overwritten at all: with no idea what is there, the mark is skipped
+      // and recorded, like every other best-effort half.
+      const applyHumanReviewBody = (): void => {
+        if (humanReviewFiles.length === 0) {
+          return;
+        }
+        let currentBody: string;
+        try {
+          currentBody = readPrBody(branch, (args) => runIn('gh', args, { cwd, env: ghEnv() }));
+        } catch (error) {
+          console.error(
+            `dispatch.ts: ${task.id} — no se pudo leer el cuerpo de la PR reutilizada, así que no se reescribe (se perdería el texto humano): ${describeExecFailure(error)}`,
+          );
+          return;
+        }
+        try {
+          runIn(
+            'gh',
+            buildPrBodyArgs(branch, upsertHumanReviewSection(currentBody, humanReviewFiles)),
+            { cwd, env: ghEnv() },
+          );
+        } catch (error) {
+          console.error(
+            `dispatch.ts: ${task.id} — no se pudo reescribir el cuerpo de la PR reutilizada con la sección de revisión humana: ${describeExecFailure(error)}`,
+          );
+        }
+      };
+
+      const markForHumanReview = (): void => {
+        if (humanReviewFiles.length === 0) {
+          return;
+        }
+        try {
+          runIn('gh', buildPrLabelArgs(branch), { cwd, env: ghEnv() });
+        } catch (error) {
+          console.error(
+            `dispatch.ts: ${task.id} — no se pudo aplicar la etiqueta ${HARNESS_REVIEW_LABEL}: ${describeExecFailure(error)}`,
+          );
+        }
+        if (input.harnessReviewer) {
+          try {
+            runIn('gh', buildPrReviewerArgs(branch, input.harnessReviewer), { cwd, env: ghEnv() });
+          } catch (error) {
+            console.error(
+              `dispatch.ts: ${task.id} — no se pudo asignar el revisor ${input.harnessReviewer}: ${describeExecFailure(error)}`,
+            );
+          }
+        } else {
+          console.error(
+            `dispatch.ts: ${task.id} — PR marcada con ${HARNESS_REVIEW_LABEL}; sin revisor configurado.`,
+          );
+        }
+      };
+
+      try {
+        // Commit and push FIRST: `gh pr create --head <branch>` needs the branch on the remote, and
+        // the executor is forbidden from running `git` itself, so on a green attempt everything it
+        // wrote is still an uncommitted working tree at this point (design.md's close diagram:
+        // "commit on task branch, push, PR to main or to the parent branch" is ONE step).
+        runIn('git', ['add', '-A'], { cwd });
+        // `--no-verify` for the same reason the WIP auto-save carries it: the hooks that would run
+        // here live in the slot's working tree, which is where the worker has been writing.
+        runIn(
+          'git',
+          [
+            'commit',
+            '-m',
+            buildAttemptCommitMessage(task.id, attempt),
+            '--allow-empty',
+            '--no-verify',
+          ],
+          {
+            cwd,
+          },
+        );
+        runIn('git', ['push', '-u', 'origin', branch], { cwd });
+
+        // A retry pushes to the same branch, so the PR from the previous attempt is still open and
+        // the push above already updated it. Creating a second one is impossible (`gh` refuses) —
+        // asking first is what turns that refusal into the reuse it should always have been.
+        // `env: ghEnv()` on every gh call below: see `ghEnv`'s own header for the measured 401 this
+        // closes (T-5, 2026-09-07) — without it, a stale `GITHUB_TOKEN` in the dispatcher's shell
+        // outranks `gh`'s own keyring login.
+        const existing = findOpenPrUrl({
+          branch,
+          runGh: (args) => runIn('gh', args, { cwd, env: ghEnv() }),
+        });
+        if (existing !== null) {
+          console.error(`dispatch.ts: PR existente reutilizada para ${branch}: ${existing}`);
+          notify(`${task.id}: PR existente reutilizada`, existing, osascript);
+          tickOwnedDod(mainCheckoutPath, task.id, readTask(), DOD_PR_OPENED);
+          applyHumanReviewBody();
+          markForHumanReview();
+          return { ok: true, compareUrl: existing };
+        }
+
+        const title = buildPrTitle(task.id, parseTaskTitle(readTask()));
+        // T-8 point 6: the board text re-read right here (never the launch-time snapshot, which a
+        // worker's own notes/plan have moved past) becomes the PR's composed body via
+        // `buildPrCreateArgs`'s `taskText` — omitting it falls back to the legacy one-line body,
+        // which is exactly the gap this call site is closing.
+        const output = runIn(
+          'gh',
+          buildPrCreateArgs({
+            task,
+            branch,
+            attempt,
+            title,
+            taskText: readTask(),
+            tasksById,
+            maxAttempts: input.maxAttempts,
+            humanReviewFiles,
+          }),
+          { cwd, env: ghEnv() },
+        );
+        notify(`${task.id}: PR abierta`, output.trim(), osascript);
+        tickOwnedDod(mainCheckoutPath, task.id, readTask(), DOD_PR_OPENED);
+        markForHumanReview();
+        return { ok: true, compareUrl: output.trim() };
+      } catch (error) {
+        return { ok: false, reason: 'open-pr-failed', question: describeExecFailure(error) };
+      }
+    },
+    releaseSlot: () => {
+      // The one release procedure every path shares (`slots.ts`): detach, then clear the entry.
+      releaseSlotAndDetach({
+        taskId: task.id,
+        slotPath: slotPath(task.id),
+        runGit: (args, at) => runIn('git', args, { cwd: at }),
+        updateSlots: realMaintenanceFs(mainCheckoutPath, repoRoot).updateSlots,
+      });
+      releaseLock(path.join(mainCheckoutPath, DISPATCH_SUBDIR), task.id);
+    },
+    recomputeParent: () => {
+      if (!task.parentId) {
+        return;
+      }
+      if (!input.boardComplete) {
+        console.error(
+          `dispatch.ts: the post-sweep board read was incomplete; skipping ${task.parentId}'s recomputation. ` +
+            'A parent derived from half its children is a confident wrong answer — the next pass, with a readable board, does it.',
+        );
+        return;
+      }
+      const recomputed = recomputeParent({
+        parentId: task.parentId,
+        // The child just finished, so its snapshot status (`In Progress`) is stale; the parent's
+        // derivation must see what the board now says, not what this pass read at its start.
+        tasksById: {
+          ...input.tasksById,
+          [task.id]: { ...task, status: parseTaskStatus(readTask()) },
+        },
+        gh: realGh(repoRoot),
+        backlog: realBacklog(mainCheckoutPath),
+        fs: realMaintenanceFs(mainCheckoutPath, repoRoot),
+      });
+      if (recomputed) {
+        console.log(
+          `dispatch.ts: parent ${recomputed.id} recomputed ${recomputed.from} -> ${recomputed.to}`,
+        );
+      }
+    },
+    drain: () => input.requestDrain(),
+    saveWork: () =>
+      realGit(mainCheckoutPath, {
+        slotPathFor: slotPath,
+        run: (command, args, cwd) => void runIn(command, args, { cwd }),
+      }).saveWipAndPush(branch),
+    // The record for a failure that no `scope-check` preceded (T-31 rounds 3 and 4): a session-level
+    // failure, or a `board-check` that diverted before it. Classified by LANE, from the same function
+    // the scope check reads, so the record and the verdict cannot disagree about a path. `base` is
+    // this task's own base ref — `origin/task/<parentId>` for a subtask, where diffing against
+    // `origin/main` would report the parent's whole accumulated diff as this attempt's leftovers.
+    // `executeClose` treats a throw as "none found": a close that already failed must not fail harder
+    // over a marking concern.
+    leftoverFiles: () => {
+      const cwd = slotPath(task.id);
+      if (cwd === null) {
+        return { forbiddenFiles: [], humanReviewFiles: [] };
+      }
+      return collectLeftoverFiles({
+        lane: task.lane ?? LANE.LOCAL,
+        base,
+        runGit: (args) => runIn('git', args, { cwd }),
+      });
+    },
+    block: (details) => {
+      // Blocked FIRST, released after: a task whose slot is already free but whose status still
+      // says `In Progress` looks to the maintenance sweep like a worker that vanished. The reverse
+      // window is the accepted one — for the few milliseconds between these two lines the task is
+      // `Blocked` while its slot still names it, and step 4's manual-cancellation branch could act
+      // on it. All that branch does is save work already saved and release a slot about to be
+      // released, so the cost of the race is a redundant no-op, not a lost attempt.
+      realBacklog(mainCheckoutPath).setStatus(
+        task.id,
+        TASK_STATUS.BLOCKED,
+        formatBlockComment(details),
+      );
+      notify(`${task.id} blocked: ${details.reason}`, details.logPath, osascript);
+    },
+    blockKeepSlot: (details) => {
+      // The push failed, so this slot holds the ONLY copy of the work: mark it so the next
+      // maintenance pass retries the push, and so no acquisition ever reuses it meanwhile. The lock
+      // goes, though — this reconciler process is about to exit, and its pid would be swept anyway.
+      // Only the `heldForRecovery` flag is touched, so a concurrent pass's own slot survives.
+      realMaintenanceFs(mainCheckoutPath, repoRoot).updateSlots((current) => ({
+        slots: current.slots.map((slot) =>
+          slot.taskId === task.id ? { ...slot, heldForRecovery: true } : slot,
+        ),
+      }));
+      releaseLock(path.join(mainCheckoutPath, DISPATCH_SUBDIR), task.id);
+      realBacklog(mainCheckoutPath).setStatus(
+        task.id,
+        TASK_STATUS.BLOCKED,
+        formatBlockComment(details),
+      );
+      notify(`${task.id} blocked: ${details.reason}`, details.logPath, osascript);
+    },
+  };
+}
+
+function spawnCapture(
+  command: string,
+  args: string[],
+  cwd: string,
+): { status: number; output: string } {
+  try {
+    const output = execFileSync(command, args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { status: 0, output };
+  } catch (error) {
+    const failure = error as { status?: number; stdout?: string; stderr?: string };
+    return {
+      status: failure.status ?? 1,
+      output: `${failure.stdout ?? ''}${failure.stderr ?? ''}`,
+    };
+  }
+}
+
+/** What `mirrorRegen` spawns, relative to the slot it runs in. */
+const MIRROR_PACKAGER_SCRIPT = 'scripts/packager/publish.mjs';
+
+/** The CI gate whose `paths:` filter IS the mirrored-root list `runMirrorRegen` reads. */
+const DRIFT_CHECK_WORKFLOW_PATH = path.join('.github', 'workflows', 'cli-template-drift-check.yml');
+
+/**
+ * The drift-check workflow as it stands IN THE SLOT, or `null` when the repo has none — a generated
+ * project, where `copyMonorepo()` ships `scripts/backlog/**` but neither `.github/**` nor
+ * `scripts/packager/**`. Read from the slot rather than from the main checkout for the same reason
+ * every other close read is: the attempt may legitimately have changed that file, and the roots the
+ * mirror needs are the ones the PR will be judged against.
+ */
+function readDriftCheckWorkflow(slotPath: string): string | null {
+  try {
+    return fs.readFileSync(path.join(slotPath, DRIFT_CHECK_WORKFLOW_PATH), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function hasLintBarrelsScript(repoRoot: string): boolean {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) as {
+      scripts?: Record<string, string>;
+    };
+    return Boolean(pkg.scripts?.[LINT_BARRELS_SCRIPT]);
+  } catch {
+    return false;
+  }
+}
+
+function readTaskText(mainCheckoutPath: string, taskId: string): string {
+  try {
+    return viewTask(mainCheckoutPath, taskId);
+  } catch (error) {
+    console.error(`dispatch.ts: backlog task view ${taskId} failed:`, error);
+    return '';
+  }
+}
+
+export interface TickOwnedDodDeps {
+  /** Injected by tests so no `backlog` CLI ever runs; the default wraps a real, stderr-capturing `execFileSync`. */
+  run?: (taskId: string, index: number) => void;
+  /** Overrides `withBoardWriteRetry`'s defaults — tests inject a synchronous, instant `sleep`. */
+  retry?: Partial<BoardWriteRetryOptions>;
+}
+
+/**
+ * Ticks the dispatcher-owned Definition-of-Done items matching `pattern` in `taskText`, by TEXT
+ * rather than by a guessed index: `--check-dod` takes the `#N` the CLI prints, and that number shifts as soon as a
+ * task adds a DoD item of its own. Best-effort — a failed tick is a bookkeeping loss, never a
+ * reason to fail a close that already proved the thing.
+ *
+ * Goes through `withBoardWriteRetry` like every other dispatcher-owned write: a `--check-dod` tick
+ * can race the SAME per-task lock a status edit or a person's own edit just took (measured T-5
+ * defect, see that function's header). A failure that survives every retry still only logs — this
+ * tick was always best-effort, and that does not change because the failure now took longer to
+ * surface.
+ */
+export function tickOwnedDod(
+  mainCheckoutPath: string,
+  taskId: string,
+  taskText: string,
+  pattern: RegExp,
+  deps: TickOwnedDodDeps = {},
+): void {
+  const run =
+    deps.run ??
+    ((id: string, index: number): void => {
+      try {
+        execFileSync('backlog', ['task', 'edit', id, '--check-dod', String(index)], {
+          cwd: mainCheckoutPath,
+          env: { ...process.env, BACKLOG_DISPATCH_ACTIVE: '1' },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        });
+      } catch (error) {
+        throw new Error(
+          `dispatch.ts: backlog task edit ${id} --check-dod ${index} failed: ${describeExecFailure(error)}`,
+        );
+      }
+    });
+  const retryOptions: BoardWriteRetryOptions = { ...BOARD_WRITE_RETRY_DEFAULTS, ...deps.retry };
+
+  for (const item of findOwnedDefinitionOfDone(taskText, pattern)) {
+    try {
+      // A `task edit`, so it runs with the same dispatcher-owned-write sentinel `realBacklog` uses —
+      // see `isDispatcherOwnedCallback` (entry.ts) and the measured T-5 defect this closes.
+      withBoardWriteRetry(
+        `backlog task edit ${taskId} --check-dod ${item.index}`,
+        () => run(taskId, item.index),
+        retryOptions,
+      );
+    } catch (error) {
+      console.error(
+        `dispatch.ts: could not tick DoD #${item.index} on ${taskId}:`,
+        describeExecFailure(error),
+      );
+    }
+  }
+}
+
+function readTaskStatus(mainCheckoutPath: string, taskId: string): TaskStatus {
+  return parseTaskView({ id: taskId, output: readTaskText(mainCheckoutPath, taskId), attempts: 0 })
+    .status;
+}
+
+// ── Executor prompt assembly (tasks.md 4.2/4.3) ───────────────────────────────
+//
+// Runs the two hooks the SAME way the harness itself does (`npx --loglevel=error tsx <hook>`,
+// see `.claude/settings.json`), just fed synthetic stdin instead of a live UserPromptSubmit/
+// PreToolUse event — Phase 1 spike 1.3's confirmed approach. `cwd` is always the task's own
+// worktree slot, so both hooks resolve their repo root (and, for the BR injector, its per-slot
+// `.claude/.cache/br-injected.json`) against that checkout, not the main one — while `BACKLOG_CWD`
+// in their env points the BOARD read at the main checkout, the only place tasks live.
+
+/**
+ * Injected so `buildHookRunners`'s environment contract is testable without spawning a hook.
+ * `repoRoot` is bound by the caller; `env` is layered over the inherited one.
+ */
+export type HookScriptRunner = (
+  hookRelativePath: string,
+  cwd: string,
+  env: Record<string, string>,
+  stdinPayload: unknown,
+) => string;
+
+function runHookScript(
+  repoRoot: string,
+  hookRelativePath: string,
+  cwd: string,
+  env: Record<string, string>,
+  stdinPayload: unknown,
+): string {
+  try {
+    const result = execFileSync(
+      'npx',
+      ['--loglevel=error', 'tsx', path.join(repoRoot, hookRelativePath)],
+      {
+        input: JSON.stringify(stdinPayload),
+        cwd,
+        env: { ...process.env, ...env },
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'ignore'],
+      },
+    );
+    return result;
+  } catch {
+    return ''; // Fail open — an unavailable/erroring hook must never block prompt assembly.
+  }
+}
+
+/**
+ * The two hook subprocesses `prompt.ts`'s precompute drives. They run with the SLOT as cwd (so they
+ * resolve rules and the injector cache against the checkout the work happens in), but with
+ * `BACKLOG_CWD` naming the MAIN checkout: the board lives only there, and a slot's own `.backlog/`
+ * copy has no tasks in it. `BACKLOG_DISPATCH_ACTIVE` is what makes the hook state the dispatched
+ * fact ("the dispatcher already set it In Progress") instead of pointing at the interactive Task
+ * Gate.
+ *
+ * Both still travel even though the LOCAL precompute no longer asks the hook for a task block
+ * (`prompt.ts`'s `buildHookPromptText` names no id, since block 1 already carries the task text):
+ * they are the environment the hook is entitled to, and the moment anything here names an id again
+ * the block must resolve against the real board and read as dispatched, not as a Task Gate.
+ */
+export function buildHookRunners(
+  repoRoot: string,
+  cwd: string,
+  mainCheckoutPath: string,
+  runHook: HookScriptRunner = (hookRelativePath, hookCwd, env, payload) =>
+    runHookScript(repoRoot, hookRelativePath, hookCwd, env, payload),
+): HookRunners {
+  const env = { BACKLOG_CWD: mainCheckoutPath, BACKLOG_DISPATCH_ACTIVE: '1' };
+  return {
+    resetInjectorCache: () => resetInjectorCache(cwd),
+    runInjectPromptContext: (prompt) =>
+      runHook('.claude/hooks/inject-prompt-context.ts', cwd, env, { prompt, cwd }),
+    runBusinessRulesInjector: (filePath) => {
+      const raw = runHook('.claude/hooks/business-rules-injector.ts', cwd, env, {
+        tool_name: 'Edit',
+        tool_input: { file_path: filePath },
+        cwd,
+      });
+      try {
+        const parsed = JSON.parse(raw) as { hookSpecificOutput?: { additionalContext?: string } };
+        return parsed.hookSpecificOutput?.additionalContext ?? '';
+      } catch {
+        return ''; // No JSON on stdout — the hook found nothing to inject for this file.
+      }
+    },
+  };
+}
+
+/**
+ * Builds the local lane's full six-block executor prompt (design.md's "Executor prompt
+ * contract"; `prompt.ts`'s `assembleExecutorPrompt`). `taskText` is the same
+ * `backlog task view --plain` output the board loader already knows how to fetch; the operating
+ * envelope's acceptance criteria, Definition of Done, and test command are parsed back out of that
+ * same text (there is no structured CLI field for any of the three — see prompt.ts's own header),
+ * and a retry (`attempt > 1`) carries the task's most recent comment plus the prior attempt's
+ * `review.md`, when one was written.
+ */
+function buildLocalExecutorPrompt(
+  mainCheckoutPath: string,
+  repoRoot: string,
+  task: Task,
+  attempt: number,
+): string {
+  const taskText =
+    readTaskText(mainCheckoutPath, task.id) || `Task ${task.id} (backlog task view failed)`;
+
+  const declaredFiles = task.filesToTouch;
+  const slotDir = findSlotPathForTask(mainCheckoutPath, task.id);
+  if (slotDir === null) {
+    // Unreachable in the real flow (`runOnce` writes the registry before it builds the prompt), and
+    // a throw is the right answer anyway: the abort path releases the slot and blocks the task,
+    // rather than running the hooks against the main checkout.
+    throw new Error(
+      `dispatch.ts: ${task.id} has no slot assigned; cannot assemble its executor prompt.`,
+    );
+  }
+  const hookOutputs = computeHookOutputs(
+    buildHookRunners(repoRoot, slotDir, mainCheckoutPath),
+    task,
+    declaredFiles,
+  );
+  const triggersIndex = loadJsonIndex(repoRoot, SKILL_TRIGGERS_INDEX_FILE, isSkillTriggerIndex) ?? {
+    skills: [],
+  };
+  const skillPaths = matchSkillPaths(declaredFiles, triggersIndex);
+  const contract = extractDelegationContract(
+    fs.readFileSync(path.join(repoRoot, DELEGATION_CONTRACT_FILE), 'utf8'),
+  );
+
+  const envelope: OperatingEnvelope = {
+    allowedFiles: declaredFiles,
+    forbiddenPaths: SECURITY_PATH_PATTERNS,
+    testCommand:
+      task.testCommand ?? 'No test command declared on the task — stop and return needs-guidance.',
+    taskId: task.id,
+    // The same string `backlogRulesForTask` turned into the launch's `Bash(...)` rule, so the
+    // command the prompt prints is the command the worker is actually allowed to run.
+    editCommand: workerEditCommand(mainCheckoutPath, task.id),
+    acceptanceCriteria: parseIndexedAcceptanceCriteria(taskText),
+    dod: parseDefinitionOfDone(taskText),
+  };
+
+  return assembleExecutorPrompt({
+    task: taskText,
+    // Named in the prompt because the worker cannot infer it: the task text carries the BOARD
+    // file's path, which lives in the main checkout — and the T-5 executor read that as its
+    // repository root and aimed its first `Edit` there.
+    slotPath: slotDir,
+    mainCheckoutPath,
+    hookOutputs,
+    skillPaths,
+    contract,
+    envelope,
+    retry: readRetryContext(mainCheckoutPath, task.id, attempt),
+  });
+}
+
+/**
+ * The prior attempt's `Blocked` comment and reviewer findings, or `undefined` on a first attempt.
+ * Shared by both lanes: the frontier orchestrator gets the same context appended to its
+ * `trabajemos <id>` entry, since nothing on the board tells it a previous attempt failed.
+ */
+function readRetryContext(
+  mainCheckoutPath: string,
+  taskId: string,
+  attempt: number,
+): { blockedComment: string; reviewerFindings?: string } | undefined {
+  if (attempt <= 1) {
+    return undefined;
+  }
+  const blockedComment = parseLastComment(readTaskText(mainCheckoutPath, taskId));
+  if (!blockedComment) {
+    return undefined;
+  }
+  const reviewPath = path.join(
+    mainCheckoutPath,
+    DISPATCH_SUBDIR,
+    taskId,
+    `intento-${attempt - 1}`,
+    'review.md',
+  );
+  return {
+    blockedComment,
+    reviewerFindings: fs.existsSync(reviewPath) ? fs.readFileSync(reviewPath, 'utf8') : undefined,
+  };
+}
+
+/**
+ * Branch names currently checked out in ANY worktree of this repo. git refuses to check the same
+ * branch out twice, so a task whose branch is still held by a slot that has not released yet has to
+ * wait rather than fail.
+ */
+function readCheckedOutBranches(repoRoot: string): string[] {
+  try {
+    const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    });
+    return output
+      .split('\n')
+      .filter((line) => line.startsWith('branch '))
+      .map((line) =>
+        line
+          .slice('branch '.length)
+          .trim()
+          .replace(/^refs\/heads\//, ''),
+      )
+      .filter(Boolean);
+  } catch (error) {
+    console.error(
+      'dispatch.ts: git worktree list failed; assuming no branch is checked out:',
+      error,
+    );
+    return [];
+  }
+}
+
+/** `null` when the lockfile cannot be read — the install check then never fires spuriously. */
+function readLockfileHash(repoRoot: string): string | null {
+  try {
+    return computeLockfileHash(path.join(repoRoot, 'pnpm-lock.yaml'));
+  } catch (error) {
+    console.error(
+      'dispatch.ts: could not hash pnpm-lock.yaml; skipping the slot install check:',
+      error,
+    );
+    return null;
+  }
+}
+
+// ── main ────────────────────────────────────────────────────────────────────────
+
+/** A drained pass may itself drain; two is the cap, so one trigger can never loop the queue. */
+const MAX_PASSES_PER_INVOCATION = 2;
+
+/** The one flag this script takes: the manual rescue of a slot held for push recovery. */
+const RELEASE_SLOT_FLAG = '--release-slot';
+/** The override for a slot the release guard refuses — see `releaseSlotByName`. */
+const FORCE_FLAG = '--force';
+
+export interface ReleaseSlotRequest {
+  slot: string;
+  force: boolean;
+}
+
+/**
+ * The `--release-slot` request, or `null` when the flag is absent. Refuses a missing or flag-shaped
+ * value rather than releasing something unnamed — which is how a rescue turns into a second
+ * incident. `--force` is read from anywhere in the argv; the slot NAME must follow its own flag.
+ */
+export function parseReleaseSlotArg(argv: readonly string[]): ReleaseSlotRequest | null {
+  const index = argv.indexOf(RELEASE_SLOT_FLAG);
+  if (index === -1) {
+    return null;
+  }
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith('-')) {
+    throw new Error(
+      `dispatch.ts: ${RELEASE_SLOT_FLAG} needs a slot name (e.g. ${RELEASE_SLOT_FLAG} dispatch-1).`,
+    );
+  }
+  return { slot: value, force: argv.includes(FORCE_FLAG) };
+}
+
+/** Every side effect the manual release performs, injected so the guard below is testable. */
+export interface ReleaseSlotDeps {
+  readSlots: () => SlotRegistry;
+  readLock: (taskId: string) => DispatchLock | null;
+  isPidAlive: (pid: number) => boolean;
+  now: number;
+  ttlMs: number;
+  detach: (slotPath: string) => void;
+  removeLock: (taskId: string) => void;
+  updateSlots: (mutate: (current: SlotRegistry) => SlotRegistry) => void;
+  log: (message: string) => void;
+  /**
+   * The same single-flight lock a reconciler pass runs its selection under. The rescue is a
+   * read→decide→detach over the very state a pass mutates, so without it the two interleave: a pass
+   * that acquired this slot between the read and the detach loses its worktree under a worker that
+   * is just starting.
+   */
+  acquireSingleFlight: () => SingleFlightResult;
+  releaseSingleFlight: () => void;
+}
+
+export type ReleaseSlotOutcome = { kind: 'released' } | { kind: 'refused'; reason: string };
+
+/**
+ * The manual counterpart to an exhausted push recovery (`maintenance.ts`'s `MAX_RECOVERY_ATTEMPTS`,
+ * README's "Releasing a `Blocked` task"): clears the hold and the task binding, and detaches the
+ * worktree so the branch is free for a later dispatch. A pass does NOT run — this is a person
+ * rescuing a slot, not a trigger.
+ *
+ * It REFUSES a slot that is genuinely busy, because "release this slot" and "kill what is running in
+ * it" are different requests and the flag only ever advertised the first. Detaching a worktree under
+ * a live `claude` loses its uncommitted work, drops the lock the close re-reads before it runs, and
+ * hands the directory to the next dispatch. A slot may be released when it is flagged
+ * `heldForRecovery` (the documented case: the work is already committed, only the push failed) or
+ * when its task lock is absent or dead — no such process, or a heartbeat past the TTL — which is
+ * exactly the liveness question the maintenance sweep asks. `--force` is the override for a person
+ * who has looked and decided.
+ */
+export function releaseSlotByName(
+  slotName: string,
+  force: boolean,
+  deps: ReleaseSlotDeps,
+): ReleaseSlotOutcome {
+  const singleFlight = deps.acquireSingleFlight();
+  if (singleFlight.kind === 'already-running' && !force) {
+    return {
+      kind: 'refused',
+      reason:
+        `a reconciler pass is already running (pid ${singleFlight.pid}); releasing a slot underneath it would ` +
+        `detach a worktree it is about to write in. Wait for the pass, or re-run with ${FORCE_FLAG} if you have ` +
+        'looked and decided.',
+    };
+  }
+  try {
+    return releaseSlotUnderSingleFlight(slotName, force, deps);
+  } finally {
+    // Only a lock this call actually took: with `--force` past a running pass there is nothing of
+    // ours to release, and removing that pass's lock would let a third one start alongside it.
+    if (singleFlight.kind === 'acquired') {
+      deps.releaseSingleFlight();
+    }
+  }
+}
+
+function releaseSlotUnderSingleFlight(
+  slotName: string,
+  force: boolean,
+  deps: ReleaseSlotDeps,
+): ReleaseSlotOutcome {
+  const slot = deps.readSlots().slots.find((entry) => entry.name === slotName);
+  if (!slot) {
+    return { kind: 'refused', reason: `no slot named ${slotName} in the registry.` };
+  }
+
+  const lock = slot.taskId ? deps.readLock(slot.taskId) : null;
+  const busy = lock !== null && isLockAlive(lock, deps.now, deps.ttlMs, deps.isPidAlive);
+  if (busy && !slot.heldForRecovery && !force) {
+    return {
+      kind: 'refused',
+      reason:
+        `${slotName} is running ${slot.taskId} (pid ${lock.workerPid ?? lock.pid}) and is not held for push recovery. ` +
+        `Releasing it would detach the worktree under a live worker and lose its uncommitted work. ` +
+        `Wait for the attempt, cancel the task on the board, or re-run with ${FORCE_FLAG} if you have looked and decided.`,
+    };
+  }
+
+  deps.detach(slot.path);
+  if (slot.taskId) {
+    deps.removeLock(slot.taskId);
+  }
+  deps.updateSlots((current) => ({ slots: releaseHeldSlotEntries(current.slots, slotName) }));
+  deps.log(
+    `dispatch.ts: ${slotName} released (was holding ${slot.taskId ?? 'nothing'}); it is back in the pool.`,
+  );
+  return { kind: 'released' };
+}
+
+/**
+ * The single-flight lock file, as one PID a process writes and reads back. Built here rather than
+ * inline in `main` because the `--release-slot` rescue serializes on the SAME file: two callers of
+ * one lock must not be two spellings of its path.
+ */
+function realSingleFlightFs(dispatchDir: string): SingleFlightFs {
+  const singleFlightFile = path.join(dispatchDir, 'dispatch.lock');
+  return {
+    readLockPid: () => {
+      if (!fs.existsSync(singleFlightFile)) {
+        return null;
+      }
+      const raw = fs.readFileSync(singleFlightFile, 'utf8').trim();
+      const pid = Number(raw);
+      return Number.isFinite(pid) ? pid : null;
+    },
+    writeLockPid: (pid) => fs.writeFileSync(singleFlightFile, String(pid)),
+    removeLock: () => {
+      if (fs.existsSync(singleFlightFile)) {
+        fs.rmSync(singleFlightFile);
+      }
+    },
+  };
+}
+
+/** The real collaborators for `releaseSlotByName`, wired the way every other real runner is. */
+function realReleaseSlotDeps(mainCheckoutPath: string, repoRoot: string): ReleaseSlotDeps {
+  const slotsFs = realMaintenanceFs(mainCheckoutPath, repoRoot);
+  const dispatchDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
+  const singleFlightFs = realSingleFlightFs(dispatchDir);
+  return {
+    acquireSingleFlight: (): SingleFlightResult =>
+      acquireSingleFlight(singleFlightFs, process.pid, isProcessAlive),
+    releaseSingleFlight: () => releaseSingleFlight(singleFlightFs, process.pid),
+    readSlots: () => slotsFs.readSlots(),
+    readLock: (taskId) => readLock(dispatchDir, taskId),
+    isPidAlive: isProcessAlive,
+    now: Date.now(),
+    ttlMs: LOCK_TTL_MS,
+    detach: (slotPath) =>
+      detachSlot(
+        slotPath,
+        (args, at) => void execFileSync('git', args, { cwd: at, stdio: 'ignore' }),
+      ),
+    removeLock: (taskId) => releaseLock(dispatchDir, taskId),
+    updateSlots: (mutate) => void slotsFs.updateSlots(mutate),
+    log: (message) => console.log(message),
+  };
+}
+
+async function main(): Promise<void> {
+  // Checked FIRST, before resolving context or running any maintenance at all: a dispatcher-owned
+  // write (`realBacklog`, `tickOwnedDod`) now runs with `BACKLOG_DISPATCH_ACTIVE='1'` in its env, so
+  // the `onStatusChange` callback it fires inherits the sentinel alongside the `TASK_ID`/`NEW_STATUS`
+  // Backlog.md sets. `shouldDispatchFromCallback` only ever suppressed task SELECTION — maintenance
+  // ran unconditionally underneath it — so this nested invocation used to run its own maintenance
+  // sweep (a `.backlog` git commit among other things) concurrently with the pass that made the
+  // write and was still mid-dispatch in the SAME checkout. That race is the measured T-5 defect:
+  // two passes committing `.backlog` in the same checkout failed with git exit 128, and the
+  // dispatcher-owned edits that followed then failed too, with no visible cause. This exits before
+  // any of that runs — a genuine human callback (no sentinel) and the launchd timer / `gh`-poll
+  // trigger (no `TASK_ID` at all) are unaffected and still run their normal pass.
+  if (
+    isDispatcherOwnedCallback({
+      TASK_ID: process.env.TASK_ID,
+      NEW_STATUS: process.env.NEW_STATUS,
+      BACKLOG_DISPATCH_ACTIVE: process.env.BACKLOG_DISPATCH_ACTIVE,
+    })
+  ) {
+    console.log(
+      `dispatch.ts: callback from a dispatcher-owned write (${process.env.TASK_ID} → ${process.env.NEW_STATUS}); no pass`,
+    );
+    return;
+  }
+
+  const { mainCheckoutPath } = resolveContext({
+    cwd: process.cwd(),
+    env: { BACKLOG_CWD: process.env.BACKLOG_CWD },
+    findRepoRoot,
+  });
+  // Never BACKLOG_CWD-overridden: the code assets lanes.json describes (settings files, worktree
+  // slots) belong to THIS machine's aurora-catalyst checkout, regardless of which backlog project
+  // BACKLOG_CWD points board data at (see realMaintenanceFs's doc comment).
+  const repoRoot = findRepoRoot(process.cwd());
+  const dispatchDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
+  fs.mkdirSync(dispatchDir, { recursive: true });
+
+  const releaseRequest = parseReleaseSlotArg(process.argv.slice(2));
+  if (releaseRequest !== null) {
+    const outcome = releaseSlotByName(
+      releaseRequest.slot,
+      releaseRequest.force,
+      realReleaseSlotDeps(mainCheckoutPath, repoRoot),
+    );
+    if (outcome.kind === 'refused') {
+      // Exit 2, not 1: a refusal is this script declining a request, not a run that broke — the
+      // same distinction `worker-edit.ts` draws against the `backlog` CLI's own 1.
+      console.error(`dispatch.ts: ${outcome.reason}`);
+      process.exit(2);
+    }
+    return;
+  }
+
+  const singleFlightFs = realSingleFlightFs(dispatchDir);
+
+  const laneConfig = loadLaneConfig(path.join(repoRoot, 'scripts/backlog/lanes.json'));
+
+  for (let pass = 1; pass <= MAX_PASSES_PER_INVOCATION; pass += 1) {
+    const acquireResult = acquireSingleFlight(singleFlightFs, process.pid, isProcessAlive);
+    if (acquireResult.kind === 'already-running') {
+      console.error(
+        `dispatch.ts: another reconciler pass is already running (pid ${acquireResult.pid}); exiting.`,
+      );
+      return;
+    }
+
+    let drainRequested = false;
+    try {
+      const result = await runPass({
+        mainCheckoutPath,
+        repoRoot,
+        dispatchDir,
+        laneConfig,
+        releaseSingleFlight: () => releaseSingleFlight(singleFlightFs, process.pid),
+        requestDrain: () => {
+          drainRequested = true;
+        },
+      });
+      console.log(`dispatch.ts: pass ${pass} complete — outcome=${formatOutcome(result.outcome)}`);
+    } finally {
+      releaseSingleFlight(singleFlightFs, process.pid);
+    }
+
+    if (!drainRequested) {
+      return;
+    }
+    console.log('dispatch.ts: draining — re-running one pass for the next Queued task.');
+  }
+}
+
+interface RunPassInput {
+  mainCheckoutPath: string;
+  repoRoot: string;
+  dispatchDir: string;
+  laneConfig: ReturnType<typeof loadLaneConfig>;
+  releaseSingleFlight: () => void;
+  requestDrain: () => void;
+}
+
+async function runPass(input: RunPassInput) {
+  const { mainCheckoutPath, repoRoot, dispatchDir, laneConfig } = input;
+  // The snapshot maintenance sweeps over. `reloadTasks` below re-reads AFTER that sweep and keeps
+  // `tasksById` current, so the close's parent recomputation never derives from a pre-sweep board.
+  const board = loadAllTasks(mainCheckoutPath);
+  let tasksById = Object.fromEntries(board.tasks.map((task) => [task.id, task]));
+  // Tracked alongside `tasksById` and from the SAME read: the close's parent derivation must know
+  // whether the snapshot it derives from is the whole board (see `BuildCloseRunnersInput`).
+  let boardComplete = board.complete;
+  const localSettings = (): LocalLaneSettings =>
+    JSON.parse(
+      fs.readFileSync(path.join(repoRoot, laneConfig.lanes.local.settings), 'utf8'),
+    ) as LocalLaneSettings;
+
+  const maintenance: MaintenanceContext = {
+    now: Date.now(),
+    ttlMs: LOCK_TTL_MS,
+    // T-8 point 5/10: `lanes.json`'s `orphanInProgressThresholdHours` converted to ms — the sweep's
+    // step 3c (an orphan `In Progress` task) is gated on this being SET, so without this line the
+    // step never runs at all (see `MaintenanceContext.orphanInProgressThresholdMs`'s own JSDoc).
+    // Defect 12 (2026-09-08): the conversion goes through `resolveOrphanInProgressThresholdMs`
+    // rather than a bare multiplication, so a configured `0` disables the sweep instead of becoming
+    // the most aggressive possible threshold.
+    orphanInProgressThresholdMs: resolveOrphanInProgressThresholdMs(
+      laneConfig.orphanInProgressThresholdHours,
+    ),
+    isPidAlive: isProcessAlive,
+    tasks: board.tasks,
+    // A partial read must not let the sweep infer a deletion (see `MaintenanceContext`).
+    boardComplete: board.complete,
+    fs: realMaintenanceFs(mainCheckoutPath, repoRoot),
+    gh: realGh(repoRoot),
+    backlog: realBacklog(mainCheckoutPath),
+    git: realGit(mainCheckoutPath),
+    // The whole GROUP, not the pid: a `claude` worker spawns hooks, `pnpm test` and sub-agents, and
+    // killing only its own pid leaves those running in the slot the sweep is about to release.
+    killProcess: (pid) => killProcessTree(pid),
+    notify: (title, body) => notify(title, body, runOsascript),
+  };
+
+  const env = {
+    NEW_STATUS: process.env.NEW_STATUS,
+    OLD_STATUS: process.env.OLD_STATUS,
+    BACKLOG_DISPATCH_ACTIVE: process.env.BACKLOG_DISPATCH_ACTIVE,
+  };
+  const slotsFs = realMaintenanceFs(mainCheckoutPath, repoRoot);
+
+  // Fetch before reading the remote branch list: a stale list makes a retry look like a first
+  // dispatch, which branches fresh off `origin/main` and abandons the previous attempt's work.
+  //
+  // This list now decides more than a base ref (T-14, 2026-09-08): `guards.ts`'s guard 4b reads it
+  // to refuse a subtask whose parent branch is missing, BEFORE anything else runs. A stale list can
+  // therefore produce a false BLOCK (a branch that IS on the remote reads as missing here) as much
+  // as it can a false PASS (a branch pruned on the remote is still present in a stale local
+  // remote-tracking copy — `--prune` above is what is supposed to prevent that, so its own failure
+  // is exactly the case where it cannot). Measured, not hypothetical: this machine's reconciler log
+  // carries `ssh: connect to host github.com port 22: Operation timed out` from a fetch that failed
+  // on 2026-09-08, the same day this guard shipped.
+  try {
+    execFileSync('git', ['fetch', 'origin', '--prune'], {
+      cwd: repoRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    console.error(
+      'dispatch.ts: git fetch failed; the remote branch list may be stale, which can now produce ' +
+        'a false Blocked (guard 4b) as well as a stale base ref:',
+      describeExecFailure(error),
+    );
+  }
+
+  let remoteBranches: string[] = [];
+  try {
+    const output = execFileSync('git', ['branch', '-r', '--format=%(refname:short)'], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    });
+    remoteBranches = output
+      .split('\n')
+      .map((line) => line.trim().replace(/^origin\//, ''))
+      .filter(Boolean);
+  } catch (error) {
+    // Silent before T-14: an empty list used to mean "branch off origin/main", a fallback the
+    // pass just ran with. Now it means EVERY subtask on the board is refused by guard 4b with a
+    // cause that names a branch which may well already be on the remote — so a swallowed failure
+    // here left nobody able to tell a genuine missing branch from `git branch -r` itself failing.
+    console.error(
+      'dispatch.ts: git branch -r failed; treating the remote branch list as empty, which now ' +
+        'blocks EVERY subtask on the board (guard 4b) with a cause that may not be true:',
+      describeExecFailure(error),
+    );
+    remoteBranches = [];
+  }
+
+  const branchesCheckedOutElsewhere = readCheckedOutBranches(repoRoot);
+  const lockfileHash = readLockfileHash(repoRoot);
+
+  const ctx: RunOnceContext = {
+    shouldSelect: shouldDispatchFromCallback(env),
+    maintenance,
+    reloadTasks: () => {
+      const current = loadAllTasks(mainCheckoutPath);
+      tasksById = Object.fromEntries(current.tasks.map((task) => [task.id, task]));
+      boardComplete = current.complete;
+      return current;
+    },
+    updateSlots: (mutate) => slotsFs.updateSlots(mutate),
+    removeLock: (taskId) => releaseLock(dispatchDir, taskId),
+    onDispatchFailure: (task, error) => {
+      const comment = `Bloqueado: el dispatch falló antes de que el worker terminara: ${String(error)}`;
+      realBacklog(mainCheckoutPath).setStatus(task.id, TASK_STATUS.BLOCKED, comment);
+      notify(`${task.id} blocked: dispatch-failed`, comment, runOsascript);
+    },
+    mainCheckoutPath,
+    currentPid: process.pid,
+    attempt: (task) => task.attempts + 1,
+    onBlock: (task, guardResult) => {
+      realBacklog(mainCheckoutPath).setStatus(task.id, TASK_STATUS.BLOCKED, guardResult.comment);
+      notify(`${task.id} blocked: ${guardResult.reason}`, guardResult.comment, runOsascript);
+    },
+    remoteBranches,
+    branchesCheckedOutElsewhere,
+    provisionSlot: (slot) => {
+      const install = lockfileHash !== null && needsInstall(slot, lockfileHash);
+      provisionSlot({
+        slotPath: slot.path,
+        repoRoot,
+        slotExists: fs.existsSync(slot.path),
+        needsInstall: install,
+        run: (command, args, cwd) => {
+          console.log(`dispatch.ts: provisioning ${slot.name} — ${command} ${args.join(' ')}`);
+          execFileSync(command, args, { cwd, stdio: 'inherit' });
+        },
+      });
+      return install && lockfileHash !== null ? { ...slot, lockfileHash } : slot;
+    },
+    runGit: (args, cwd) => {
+      try {
+        execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (error) {
+        throw new Error(`dispatch.ts: git ${args.join(' ')} failed: ${describeExecFailure(error)}`);
+      }
+    },
+    writeLock: (lock) => {
+      const file = path.join(dispatchDir, 'locks', `${lock.taskId}.json`);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, JSON.stringify(lock, null, 2));
+    },
+    readLock: (taskId) => readLock(dispatchDir, taskId),
+    setInProgress: (taskId) =>
+      realBacklog(mainCheckoutPath).setStatus(taskId, TASK_STATUS.IN_PROGRESS),
+    releaseSingleFlight: input.releaseSingleFlight,
+    resetInjectorCache,
+    isLocalModelLoaded: () =>
+      checkLocalModelLoaded(fetch, laneConfig.lanes.local.healthCheckUrl, localSettings().model),
+    onLocalModelMissing: (task) => {
+      const comment = `Bloqueado: servidor local sin el modelo ${localSettings().model} cargado en ${laneConfig.lanes.local.healthCheckUrl}. Cárgalo en LM Studio y vuelve a poner la tarea en Queued.`;
+      realBacklog(mainCheckoutPath).setStatus(task.id, TASK_STATUS.BLOCKED, comment);
+      notify(`${task.id} blocked: servidor local sin el modelo`, comment, runOsascript);
+    },
+    beginAttempt: (task, attempt) => {
+      const dir = createAttemptDir(dispatchDir, task.id, attempt);
+      return createAttemptSink({
+        appendStreamLine: (line) => fs.appendFileSync(path.join(dir, 'stream.jsonl'), `${line}\n`),
+        writeRunLog: (lines) =>
+          fs.writeFileSync(
+            path.join(dir, 'run.log'),
+            lines.length > 0 ? `${lines.join('\n')}\n` : '',
+          ),
+        refreshHeartbeat: (isoNow) => refreshHeartbeat(dispatchDir, task.id, isoNow),
+        now: () => Date.now(),
+      });
+    },
+    buildPrompt: (task, attempt) => {
+      if (task.lane === LANE.LOCAL) {
+        return buildLocalExecutorPrompt(mainCheckoutPath, repoRoot, task, attempt);
+      }
+      const retry = readRetryContext(mainCheckoutPath, task.id, attempt);
+      // T-8, last point: a Complex parent whose children are all Done gets the FIXED close-attempt
+      // brief instead of the task-derived entry below — read against `tasksById` as it stands at
+      // THIS call (kept current by `reloadTasks` above, never the snapshot `runPass` started with),
+      // since `runOnce` calls `buildPrompt` only after its own post-maintenance reload. See
+      // `prompt.ts`'s `isParentCloseAttempt` for why this is re-derived here rather than threaded
+      // through as a flag from the maintenance pass that enqueued it.
+      //
+      // Defect 11 (2026-09-08): "is this child Done" for a child that is ITSELF a parent must use
+      // the SAME derivation `recomputeParent` used to decide `task` was ready to dispatch —
+      // `parent.ts`'s `effectiveStatus` over `maintenance.ts`'s `toDerivationNode`, with the SAME
+      // `gh`/`fs` this pass's own maintenance context already wires — never that child's literal
+      // board status, which a single pass can leave one write behind for a three-level tree.
+      const isChildDone = (child: Task): boolean =>
+        effectiveStatus(toDerivationNode(child.id, tasksById, maintenance.gh, maintenance.fs)) ===
+        TASK_STATUS.DONE;
+      return isParentCloseAttempt(task, { tasksById }, isChildDone)
+        ? buildParentCloseAttemptPrompt(task.id, retry)
+        : // frontier, ordinary work: the same deterministic entry an interactive session uses, plus
+          // the prior attempt's failure on a retry — the orchestrator reads the task itself, but
+          // nothing on the board tells it that a previous attempt was blocked or why.
+          buildFrontierPrompt(task.id, retry);
+    },
+    workerSystemPromptPath: resolveWorkerSystemPromptPath(repoRoot),
+    // Rendered into the attempt directory rather than handed over as the static skill file: it names
+    // this task's id and the wrapper command bound to it, neither of which a shared file can carry.
+    writeFrontierAddendum: (task, attempt) => {
+      const target = path.join(dispatchDir, task.id, `intento-${attempt}`, 'frontier-addendum.md');
+      const slotDir = findSlotPathForTask(mainCheckoutPath, task.id);
+      if (slotDir === null) {
+        // Unreachable in the real flow (the slot registry is written before the launch is built),
+        // and a throw is the right answer anyway: the abort path releases the slot and blocks the
+        // task, rather than telling a worker its working directory is the main checkout.
+        throw new Error(
+          `dispatch.ts: ${task.id} has no slot assigned; cannot render its frontier addendum.`,
+        );
+      }
+      fs.writeFileSync(
+        target,
+        buildFrontierAddendum({
+          template: fs.readFileSync(path.join(repoRoot, FRONTIER_ADDENDUM_TEMPLATE_PATH), 'utf8'),
+          taskId: task.id,
+          mainCheckoutPath,
+          slotPath: slotDir,
+        }),
+      );
+      return target;
+    },
+    laneConfig,
+    loadLocalSettings: localSettings,
+    loadFrontierSettings: (): FrontierLaneSettings =>
+      JSON.parse(
+        fs.readFileSync(path.join(repoRoot, laneConfig.lanes.frontier.settings), 'utf8'),
+      ) as FrontierLaneSettings,
+    // The settings sources THIS LANE loads — the user file alone on the local lane, the user and
+    // project files on the frontier one — read from `repoRoot`, the DISPATCHER's own checkout (the
+    // one every slot is a worktree of) and never from the slot, for the same reason the lane
+    // settings above come from there: the list that bounds a worker cannot be a file that worker
+    // can edit, and both operands of the subtraction must come from the same source or the
+    // comparison is between two different files.
+    loadSettingsAllowRules: (lane) =>
+      loadSettingsAllowRules(settingsSourcePaths(lane, repoRoot, os.homedir())),
+    spawnWorker,
+    logPathFor: (taskId, attempt) =>
+      path.join(DISPATCH_SUBDIR, taskId, `intento-${attempt}`, 'run.log'),
+    buildCloseRunners: (task, attempt, branch) =>
+      buildCloseRunners({
+        mainCheckoutPath,
+        repoRoot,
+        task,
+        attempt,
+        branch,
+        reviewerModel: laneConfig.lanes.local.reviewerModel,
+        reviewerTimeoutMs: laneConfig.lanes.local.reviewerTimeoutMinutes * 60_000,
+        requestDrain: input.requestDrain,
+        tasksById,
+        boardComplete,
+        maxAttempts: laneConfig.attempts,
+        harnessReviewer: laneConfig.harnessReviewer,
+      }),
+  };
+
+  return runOnce(ctx);
+}
+
+// Guarda de entry-point: el fichero se importa desde entry.ts y otros módulos, que no deben
+// disparar un pase real del reconciliador. `fileURLToPath`, no `new URL(...).pathname` — ver
+// release-cli.ts para el mismo razonamiento (un espacio en la ruta rompería la comparación).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}