@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

package/dist/templates/monorepo/scripts/backlog/README.md

@@ -0,0 +1,1601 @@
+# `backlog` dispatcher
+
+The reconciler that turns a `Queued` Backlog.md task into a running headless worker and, on
+completion, into a merge-ready PR. It is triggered three ways (a `onStatusChange` callback, a
+`launchd` timer, and — inside the maintenance pass — a `gh` poll for merged PRs), but every trigger
+runs the exact same idempotent pass over observable state: sweep dead locks and orphan slots,
+close out merged PRs, recompute every parent's derived status, pick the next `Queued` task by
+priority then age, run it through six guards, verify the local model is loaded when the task needs
+it, acquire a worktree slot, launch the right lane (`local`, a curated LM Studio executor, or
+`frontier`, a headless Claude Code orchestrator), and close — board integrity, mechanical scope
+check, format/barrels/test, the reviewer on the local lane, the AC/DoD check on both, then a PR —
+or, on any failure, save the work before ever releasing the slot. See
+`openspec/changes/add-backlog-task-dispatch/design.md` for the full rationale and decision log;
+this file documents how the pieces fit together operationally.
+
+## Module table
+
+| Module | Responsibility |
+| --- | --- |
+| `entry.ts` | Orchestration root: resolves `BACKLOG_CWD`, serializes concurrent invocations with a single-flight file lock, applies the anti-loop guard to a status-change trigger, selects the next `Queued` task, and wires maintenance → selection → guards → model readiness → slot acquisition → launch → close into one pass (`runOnce`, async). It also RELEASES the single-flight lock mid-pass — see "Process model" below |
+| `maintenance.ts` | Runs first on every pass, and RETURNS the post-sweep slot registry the rest of the pass acts on, in a fixed order — step 0: retries a push a previous pass could not complete, refusing (never retrying) once the branch's PR reads confirmed `merged` rather than landing commits nobody will ever look at (defect 8, 2026-09-08 — the same push gate `close.ts`'s `checkBranchNotMerged` applies before the close's own pushes); step 1: sweeps locks with a dead PID or an expired heartbeat, killing a hung worker first, then saving its work before releasing anything — same confirmed-merged refusal as step 0 rather than pushing a dead worker's WIP onto an already-merged branch; step 2: releases slots with no live process; step 3: moves a task with a merged PR to `Done` (via `gh`, one poll per branch per pass) — skipping any task with an ALIVE lock, since a retry runs on the same branch and the PREVIOUS attempt's merged PR would otherwise declare the task `Done` mid-run, which the cancellation sweep then reads as "not cancelled" and leaves the worker running against a closed task — deleting the task's `task/<id>` branch (local, then remote) once it reaches `Done` this way, but ONLY when the branch is first confirmed to carry no commit unreachable from its base (`MaintenanceGit.branchHasUnmergedCommits`, compared against `guards.ts`'s `taskBaseBranch` — never a hand-rolled `main`, which would block every subtask) — a branch that fails that check is left ENTIRELY alone, reported in `MaintenanceResult.branchCleanupRefused` rather than `cleanedUpBranches`, so the fail-safe `unknown`-still-pushes decision in steps 0/1 below can never again turn a rescue push landed on an already-merged branch into commits destroyed outright (the remaining T-8 point 5 hole, closed 2026-09-08) — and even once that check passes, deletion still counts as done ONLY when the remote half is CONFIRMED gone (deleted this pass, or already absent) rather than merely attempted (defect 7, 2026-09-08); step 3b: reverts a hand-written `Done` back to `In Progress` when its branch exists but GitHub does not report its PR merged; step 3c: blocks an orphan `In Progress` task (no lock, no slot, no attempt directory, and an `updated_date` older than `lanes.json`'s `orphanInProgressThresholdHours`) — entirely OFF when that threshold is `0`, the operator's explicit way to disable this step, rather than the most aggressive setting a bare millisecond conversion used to make it (defect 12, 2026-09-08); step 4: kills a manually-cancelled task's WORKER after its work is saved — a cancellation being an EXPLICIT `Blocked`/`To Do`, or a task gone from a board that was read in FULL (`boardComplete`), never merely "not `In Progress`"; step 5: recomputes every parent's derived state, deleting the branch of any parent this step itself closes (same unmerged-commits check and confirmed-gone condition as step 3); step 6: commits any pending `.backlog/**` changes with a conventional message |
+| `guards.ts` | `evaluateGuards(task, board, slots, limits, permissions, remoteBranches)` — the dispatch guards over the selected task, in fixed order (missing triage — **also, `tier:medium` + `lane:local` (`tier-lane-mismatch`; `tier:complex` + `lane:local` is guard 2's own `complex-on-local`, unchanged), on `lane:local` no declared `Files to touch:`, and on EITHER lane no declared `Test command:`, or one the allowlist refuses** — then **guard 1c, on BOTH lanes: a task whose declared `Files to touch:` reach the HARD path list (`slot-executed-path`; T-31 — evaluated immediately after guard 1, because a task declaring a file that can never be admitted has nothing a later guard could make actionable), which does NOT fire on a soft-list declaration** — then **guard 1b, on BOTH lanes: a loaded settings allow rule with no safe deny** — Complex on local, unmet dependency, security path on local, **guard 4b: a subtask's parent branch missing from the remote (`missing-parent-branch`; T-14, 2026-09-08 — see `resolveTaskBase` below — placed AFTER security so that refusal is never masked by an actionable-looking "push a branch" message)**, attempts exhausted, no free slot), returning `launch` / `wait` (stays `Queued`, as `dependency-not-done`, `no-free-slot` or `push-pending`) / `block` (moves to `Blocked` with a Spanish cause). `limits`, `permissions` and `remoteBranches` are all REQUIRED (no defaults, T-14 fix round) — a caller that drops `remoteBranches` used to silently block every subtask on the board with a false cause, undetected by the suite because no test fixture had ever exercised a subtask through `evaluateGuards`. The two caps arrive as `limits`, derived from `lanes.json` by `launch.ts`'s `dispatchLimitsFrom` rather than from a module constant; `permissions` (the loaded settings allow list and the whole surface the launch would grant) is composed by `entry.ts`, so this module keeps taking no filesystem access. The board it reads is the one re-read AFTER the maintenance sweep, so a dependency this very pass moved to `Done` unblocks its dependent immediately. Also owns `resolveTestCommand`, the single allowlist for a declared `Test command:` line — read by guard 1 here, by `launch.ts` for the per-task Bash grant, and by `close.ts` for the triad — `grantCovers`/`denyWouldRevoke`/`findPermissionConflict`, the permission-rule comparison guard 1b decides with and `launch.ts` composes its deny list from, in that dependency direction — two predicates because the two directions are different questions: coverage ("already granted, skip it") is stricter than the real matcher, revocation ("would a deny for this kill that grant?") is exactly as coarse as it — and `taskBaseBranch`/`resolveTaskBase`, the ONE place a task's base branch is named (`task/<parentId>`, or `main`) and, for `resolveTaskBase`, checked against the remote: guard 4b blocks on it, `slots.ts`'s `resolveBranch` consults it (and throws rather than falling back if it is ever violated post-guard), and `close.ts`'s `resolveBaseBranch`/`resolveBaseRef` consult the naming half — T-4.1 measured what two independent answers to "what is this task's base?" costs (a whole frontier worker run, blocked on `scope-check-failed` after finishing correctly) |
+| `slots.ts` | Acquires and releases one of the three reusable worktrees, provisions one on demand (`git worktree add --detach origin/main` → `scripts/worktree-link.sh` → `pnpm install`), the dispatch-lock lifecycle (PID + heartbeat — `writeLock`, `releaseLock` and `refreshHeartbeat` all run under the SAME per-task exclusive lock, since a mutex only one participant enters is not a mutex), the lockfile-hash install check, branch resolution (reuse the existing `task/T-nn` branch on retry, otherwise `guards.ts`'s `resolveTaskBase` names the base — `origin/task/<parent>` for a subtask, `origin/main` otherwise — and `resolveBranch` THROWS if that base is missing from the remote, rather than the silent `origin/main` substitution it used to make: T-14, 2026-09-08 — see `guards.ts`'s guard 4b, which now refuses that dispatch before a slot is ever taken, making the case a programming error here rather than a fallback to route around), `slotPathForTask` (the directory holding a task's work, or `null`), `releaseSlotAndDetach` — the ONE release procedure every path uses — `releaseHeldSlotEntries` (the MANUAL rescue behind `--release-slot`, the only release that clears `heldForRecovery`), and `updateSlots`/`createRegistryLock`, the ONE mutation primitive every `slots.json` write goes through |
+| `launch.ts` | Per-lane launch preparation: lane/model resolution from task labels, the exact `claude` command for each lane (the lane settings' `permissions.allow`/`deny` become `--allowedTools`/`--disallowedTools`, merged on both lanes with `backlogRulesForTask`'s ONE rule — the dispatcher-owned `worker-edit.ts` wrapper bound to that task id, which both reads (`--view`) and writes — plus `testCommandRuleForTask`'s rule for the task's own declared test, with an argument containing whitespace re-quoted so the granted string is the one the close spawns), `settingsSourcePaths` + `loadSettingsAllowRules` (each loaded rule tagged with the source file it came from, since a path glob is relative to that file) + `settingsAllowRulesToDeny` + `composeGrantedAllow` (the one composition of the whole granted surface — lane list plus the per-task grants — that guard 1b compares and `buildLaunch` writes into `--allowedTools`) (BOTH lanes load a settings source on purpose and name it — `--setting-sources user` locally, `user,project` on the frontier lane, never the click-approval overlay, with `LANE_SETTING_SOURCES` the one list the flag value and the loaded files both derive from — so every allow rule those sources contribute and the lane does not grant is emitted as a deny; coverage-aware through `guards.ts`'s `findPermissionConflict`, whose no-safe-deny verdict guard 1b already turned into a block before this ran — the throw here is the invariant behind that guard), `assertLaneGrantsFileAccess` (refuses to launch unless the merged allow list actually grants a read AND a write rule — a lane holding only `Bash` rules is not a restricted worker, it is a worker that cannot open a file), `dispatchLimitsFrom` (the `maxParallel`/`attempts` caps the guards and the slot acquisition read), `sanitizeInheritedEnv` (drops every inherited `ANTHROPIC_*`/`CLAUDE_CODE_*` key and every other credential-shaped one — `isCredentialEnvKey`), the async line-streamed `spawnWorker` (detached, reporting the child pid through `onSpawn`), `killProcessTree`, and the LM Studio `/api/v0/models` readiness check before a local-lane launch |
+| `close.ts` | The dispatch close: `checkBoardIntegrity` (the board still says `In Progress`, and the acceptance/DoD texts, the title, the parent, the declared files and the declared test command still read as they did at launch), `checkScope` (the mirror-output prefix first — refused on both lanes regardless of the two lists — then `guards.ts`'s hard list `SLOT_EXECUTED_PATHS`/`SLOT_EXECUTED_BASENAMES` (on local, `LOCAL_FORBIDDEN_PATHS` — the hard list plus three local-only path extras — and the security paths as well), then, once nothing violated, the soft list `HUMAN_REVIEW_PATHS` — admitted and reported in `humanReviewFiles`, never a violation; see "Forbidden paths, split by mechanism" below) and `runScopeCheck`/`collectChangedFiles` over the slot's real changes (plus `collectLeftoverFiles`, the same read CLASSIFIED the same way and with no verdict attached — refused paths and soft-list paths in separate buckets — for the failure paths that never run the scope check: a session-level failure and a `board-check` divert), `resolveBaseBranch` (the PR's `--base`, delegating to `guards.ts`'s `taskBaseBranch` — the SAME naming `slots.ts`'s branch resolution consults, since T-4.1 measured the two disagreeing when each computed its own answer) and `resolveBaseRef` (the `origin/…` ref the work is diffed against and branched from), `planMechanicalChecks` (Prettier `--write` then `--check` per workspace → barrels lint → the task's declared test — validated by `guards.ts`'s `resolveTestCommand`, which this module READS rather than owns — all scoped to the attempt's own changed files), `evaluateAcceptanceGate` (the pre-PR gate), `buildWipCommitMessage`/`buildAttemptCommitMessage`/`buildPrTitle`, `formatBlockComment`/`sanitizeCommentBody`, `buildPrCreateArgs`/`buildPrLabelArgs`/`buildPrReviewerArgs`/`buildPrBodyArgs` (the human-review mark), `collectAttemptDiff`, `planClose` (a pure planner over the ordered steps), and `executeClose` (walks the plan through injected runners, always saving work before releasing a slot on any failure) |
+| `parent.ts` | `deriveParentStatus(children, ownPrMerged, tier?, closeAttempted?)` — the parent-state precedence table (any child `Blocked` wins; any child `Queued`/`In Progress`, or a `Done`+`To Do` mix, means `In Progress`; all children `Done` plus the parent's own PR merged means `Done`; all children `Done`, the PR NOT merged, `tier:complex` and never yet attempted means `Queued` — the ONE automated close attempt, T-8; the same shape once already attempted (`closeAttempted`) returns `null` — defers to whoever owns it now, a live retry or a human's `Blocked` review, rather than re-deriving on top of it; all children `Done`, the PR not merged, any OTHER tier means `In Progress` (pre-T-8 behavior); all `To Do` means `To Do`), applied recursively to grandchildren through the exported `effectiveStatus` (a node with `children` recomputes itself from THEM rather than trusting its own possibly-stale literal `status` — also how `dispatch.ts`'s `isParentCloseAttempt` asks the same question for one node without re-deriving); `tier`/`closeAttempted` are optional and default to "not Complex" / "never attempted", the exact pre-T-8 behavior, for a caller that predates it. Parent state is NEVER written by hand — `maintenance.ts`'s `recomputeParent` is the only writer, and it additionally gates the all-Done branch on the parent's OWN branch `mergedState` (never a caller-supplied `ownPrMerged` alone) so a `gh` outage derives nothing rather than misreading an unanswerable question as "not merged" (F1) |
+| `render.ts` | Maps one `stream-json` event to a human-readable log line (`renderEvent`) and replays a whole recorded session (`renderStream`); shared by the close's `run.log` writer and `watch.ts`'s live tail |
+| `watch.ts` | `pnpm backlog:watch <id>` tails that attempt's rendered `run.log`; with no id, lists busy slots from `slots.json`. Stops on its own once the task's lock file disappears — the close removes it as its very last step, so "the lock is gone" means "there is nothing left to tail" — flushing whatever `run.log` holds at that final tick before exiting, rather than polling forever (T-8 point 1: two watchers were measured six hours orphaned under the old bare-`setInterval` version). A missing `run.log` (a dispatch that aborted before the worker ever streamed a line) reads as "no growth yet", not as a reason to skip checking the lock, so that case still stops too (T-8 defect 9, 2026-09-08). Read-only — never writes board state, a lock, or a slot |
+| `notify.ts` | Fires a macOS notification (`osascript`) on `Blocked` and on PR-opened; a no-op on any non-`darwin` platform so unit tests and non-Mac runs never fail on a missing `osascript` binary |
+| `attempt.ts` | The per-attempt record under `.backlog/.dispatch/<TASK_ID>/intento-<N>/`: `countAttempts` (what `lanes.json`'s `attempts` cap counts), `createAttemptDir` (opened BEFORE the worker starts, so `backlog:watch` can tail it live) and `createAttemptSink` (appends `stream.jsonl` line by line, renders `run.log` on `finish`, and refreshes the lock heartbeat on a 30 s TIMER until `stopHeartbeat` — which the close calls at its very end, not when the worker exits) |
+| `reviewer.ts` | The local lane's close reviewer: the isolated, read-only `claude` argv (`--setting-sources user --strict-mcp-config --disable-slash-commands`, no write tool — deliberately NOT `--bare`, see below) and `reviewerEnv` (drops every `ANTHROPIC_*` key, so the account's claude.ai login authenticates), the dual-verdict prompt (defects, conformity per acceptance criterion, and "would this test fail if its logic broke?") with the diff fenced as untrusted data, and the `REVIEW COMPLETE` + `VERDICT: pass|fail` parse. Fails closed — no verdict blocks the task |
+| `task-view.ts` | The single parser for the `backlog` CLI's plain output, with every reader bounded to the region that can legitimately answer for it. Section readers see the DECLARATION REGION — everything above the first `Implementation Plan:`/`Implementation Notes:`/`Notes:`/`Comments:` heading (heading meaning label line PLUS its dashed underline, so a description with a `Notes:` line of its own does not truncate the contract), since those are the sections a worker's own `--plan`/`--append-notes` writes into and a first-match parser read a heading it forged there as if the CLI had rendered it. Header readers (`Status:`, `Priority:`, `Created:`, `Labels:`, `Parent:`, the title heading) see the HEADER REGION — everything above the first rendered section — because those fields exist nowhere else, and a `Parent:` forged in the notes was the first match on a top-level task and rerouted the PR's base branch: `parseBoardTaskIds` (one id per `task list` row, never an id merely mentioned in a title), the `Task` shape (its `tier`/`lane`/`path` resolved against the real label values, so a typo reads as no triage rather than as a lane nothing matches), the `Files to touch:` and `Test command:` description conventions, the acceptance/DoD TEXTS snapshotted at launch for the close's integrity gate, and the AC/DoD checklists with their checked state and CLI index |
+| `worker-edit.ts` | The ONLY board channel a dispatched worker is granted, read included: `validateWorkerEditArgs` reads the whole argv (exactly the dispatched id, then `--check-ac`/`--notes`/`--append-notes`/`--plan`, each at most once, no value that is itself a flag — or `--view` alone) and forwards to `backlog task edit`, or to `backlog task view … --plain`, in the main checkout — which it requires `BACKLOG_CWD` to name, since `execFileSync` with no `cwd` would run in the SLOT, whose `.backlog/` copy holds no tasks; anything else exits 2 explaining the refusal. It exists because a permission rule matches a PREFIX and cannot narrow what follows it — the four per-flag grants it replaced all admitted a trailing `--status Done`, and the separate `Bash(backlog task view <id>:*)` read grant admitted any longer command line beginning with those words. Its SECOND mode, `--subtask` (mutually exclusive with the four edit flags and `--view`), is the headless way a Complex task's SDD design phase creates the subtasks a split produces — `--title`/`--labels` required, plus exactly one of `--desc` or `--desc-file <path>` (mutually exclusive; the file variant reads UTF-8 text from a path that must stay relative and inside the worker's own cwd — no leading `/`/`~`, no `..` segment — the robust way to pass multi-line text without the `$'…\n…'` ANSI-C quoting a Bash permission rule reads as a `$` expansion and denies, T-6 measured, four attempts out of five), `--labels` validated against the SAME `tier:`/`lane:`/`path:`/`bc:` taxonomy (`tier:complex` forcing `lane:frontier`, and — T-6 — `lane:local` forcing `tier:minor`, the same restriction `guards.ts`'s own guard 1 now enforces on the board), the resolved description validated against `resolveTestCommand` and, on `lane:local`, `parseFilesToTouch` — and never accepts `--parent`: the parent is `BACKLOG_TASK_ID` itself. Forwards to `backlog task create <title> -p <parentId> --desc … -l … [--ac …]... [--priority …] [--type …] [--depends-on …]` |
+| `dispatch.ts` | The executable entry point every trigger invokes: wires the REAL collaborators (real `fs` under `.backlog/.dispatch/`, real `git`/`gh`/`backlog` shell-outs, a real `claude` spawn) and calls `entry.ts`'s `runOnce`. It also owns the one flag the script takes — `releaseSlotByName`, the `--release-slot` rescue, which runs its read→decide→detach under the SAME single-flight lock a reconciler pass holds for its selection (a rescue that interleaved with a pass could detach the very worktree that pass had just acquired) and REFUSES (exit 2) both a pass already running and a slot whose task lock is still alive, unless the slot is `heldForRecovery` or `--force` is passed |
+
+`types.ts` holds the shared shapes (task labels, `slots.json`, `locks/<TASK_ID>.json`) every other
+module imports from, so the on-disk contract has one source of truth; `prompt.ts` assembles the
+local-lane executor's five-block user prompt and, with `buildFrontierAddendum`, renders the frontier
+lane's per-attempt system-prompt addendum from its skill-file template (see
+`.claude/skills/catalyst-backlog/SKILL.md` for the worker-facing side of that contract).
+
+## On-disk data layout
+
+Everything the dispatcher writes at runtime lives under `.backlog/.dispatch/`, which is
+gitignored (unlike `.backlog/` itself, which IS tracked — see "Where board state lives" below):
+
+```
+.backlog/.dispatch/
+  <TASK_ID>.log                 # nohup redirect of every reconciler run this task's status
+                                # transitions started — APPENDED to, so a re-queue after Blocked
+                                # does not erase the run that blocked it
+  launchd.log                   # StandardOutPath/StandardErrorPath of the launchd timer — the
+                                # LAUNCHER's own output (a failing `mkdir` or `nohup`), nothing else
+  reconciler.log                # nohup redirect of the reconciler the launchd timer detached. Its
+                                # own file on purpose: a pass runs for tens of minutes, and
+                                # interleaving it with the launcher's lines made neither readable
+  slots.json                    # [{ name, path, lane, taskId|null, pid|null, lockfileHash, heldForRecovery? }]
+  slots.lock                    # exclusive lock guarding every slots.json write (see below)
+  locks/<TASK_ID>.json           # { taskId, slot, pid, workerPid, startedAt, heartbeatAt, lane, attempt, branch }
+  <TASK_ID>/intento-<N>/
+    stream.jsonl                 # raw stream-json, appended line by line while the worker runs
+    run.log                      # human-rendered, written ONCE when the worker exits (this is
+                                 # what `pnpm backlog:watch` tails)
+    test.log                     # transcript of the close's mechanical checks, one block per check
+    review.md                    # the close reviewer's findings (local lane); read back on a retry
+    meta.json                    # NOT YET WRITTEN — design.md reserves it for sessionId, lane,
+                                 # model, branch, startedAt, endedAt, exitReason
+```
+
+A lock is dead when `process.kill(pid, 0)` throws (no such process) or when `heartbeatAt` is older
+than the TTL (10 minutes, `dispatch.ts`'s `ttlMs: 10 * 60_000`) even with a live PID. `attempt.ts`
+refreshes `heartbeatAt` every 30 s on a TIMER — deliberately not from the stream events, which would
+make "alive" mean "emitting output" and sweep a worker that is merely thinking, waiting on a long
+test run, or streaming one very large event.
+
+**The heartbeat covers the CLOSE too, not just the worker.** `sink.finish()` renders `run.log` and
+stops reading; `sink.stopHeartbeat()` is called at the very end of the close, once the slot has been
+released or held. That split is load-bearing: the close's own steps (the scoped test run, the
+reviewer subprocess, `git push` + `gh pr create`) routinely take longer than the 10-minute TTL, and
+the single-flight lock was already dropped when the slot was taken — so a heartbeat frozen at the
+worker's exit made the next pass read a live close as a dead worker, kill it, and release its slot
+mid-PR. The reviewer subprocess is separately bounded by `lanes.json`'s `reviewerTimeoutMinutes`
+(default 15), because a reviewer that never returns would otherwise hold a slot forever.
+
+`slots.json` is written through ONE primitive, `slots.ts`'s `updateSlots(store, mutate)`: it takes an
+exclusive lock (`.backlog/.dispatch/slots.lock`, broken when older than 30 s), RE-READS the file, and
+applies the caller's transform to what it finds there. Nothing writes a whole registry built on an
+older snapshot. Two passes legitimately run at once — the single-flight lock is released as soon as a
+slot is taken — so a snapshot-based write silently reverted the other pass's acquisition, its
+release, or its `heldForRecovery` flag, and losing that last one means losing the only marker saying
+a slot still holds unpushed work. Every writer (the maintenance sweep, the acquisition write-back,
+`releaseSlot`, `blockKeepSlot`) mutates only the fields it owns.
+
+The lock carries TWO pids and they are not interchangeable: `pid` is the RECONCILER (what the
+liveness probe checks), `workerPid` is the spawned `claude` process (what a cancellation kills, as a
+whole process group — the worker spawns hooks, `pnpm` and sub-agents of its own).
+
+`locks/<TASK_ID>.json` has its own exclusive lock (`locks/<TASK_ID>.json.lock`, the same
+`createRegistryLock` primitive `slots.json` uses), and **every** mutation of the file goes through
+it: the launch write, the heartbeat refresh, and the sweep's removal. A one-sided mutex is not a
+mutex — moving the heartbeat's READ inside a critical section that nothing else entered only excluded
+a second heartbeat, and a `releaseLock` taking no lock still landed between that read and its write,
+after which the write resurrected a lock for a slot already handed to another task.
+
+`slots.json` is the allocation mutex (which of the three worktrees — named `dispatch-a`,
+`dispatch-b`, `dispatch-c` — is occupied, by which task, for which lane); `locks/<TASK_ID>.json` is
+the liveness detail for whoever currently holds that task. A slot flagged `heldForRecovery` is
+neither free nor reassignable: its work never reached the remote, so it holds the only copy (see
+"Failure path" below). `slots.ts` owns the pure operations on both shapes (acquire, release,
+provision, lock lifecycle, heartbeat); `dispatch.ts` owns the only real reads and writes of the two
+files.
+
+**The worktree slots are created on demand.** There is no bootstrap step: the first time a task
+acquires `dispatch-a`, the dispatcher runs `git worktree add .claude/worktrees/dispatch-a --detach
+origin/main`, then `bash scripts/worktree-link.sh` from inside it (linking the gitignored
+`backend/.keys` and `backend/.env` a worktree does not inherit), then `pnpm install`. That first
+acquisition therefore costs a full install — minutes, not seconds. Every later acquisition reuses the
+worktree and skips the install unless `pnpm-lock.yaml` moved (`slots.json`'s `lockfileHash`).
+
+`run.log` is written by `attempt.ts`'s sink — but only ONCE, inside `finish()`, as a single
+`writeFileSync` of the WHOLE session rendered through `render.ts` at that point; `appendStreamLine`
+is what grows the raw `stream.jsonl` line by line while the worker runs, not `run.log`. `finish()`
+itself runs as soon as the worker process exits, before the close's own steps (the scope check, the
+scoped test, the reviewer, the PR) — so `run.log` appears in full moments after the worker is done,
+not incrementally while it works, and not only once the whole close has finished either. `review.md`
+is written by the close's reviewer step, on every branch including a crashed reviewer, because a
+retry's prompt reads it back.
+
+`.backlog/.dispatch/` is created by the `onStatusChange` callback itself (it is prefixed with
+`mkdir -p .backlog/.dispatch;` — see "Trigger wiring"), and by `dispatch.ts` on every run. Nothing
+has to be created by hand in a fresh clone.
+
+## Process model
+
+One reconciler process handles at most one dispatch, but it does NOT hold the single-flight lock
+for the worker's lifetime. The sequence is:
+
+1. Acquire the single-flight lock (`.backlog/.dispatch/dispatch.lock`, PID-based) and run the whole
+   maintenance → selection → guards → readiness → slot acquisition sequence under it.
+2. Once the slot is taken, the lock file is written and the task is `In Progress`, **release the
+   single-flight lock**. The per-task lock is what keeps a second pass off THIS task; the
+   single-flight lock only serializes selection.
+3. Spawn the worker asynchronously (`launch.ts`'s `spawnWorker`), in its OWN process group and with
+   a sanitized environment: every `ANTHROPIC_*` and `CLAUDE_CODE_*` key this process inherited is
+   dropped before the lane's own `env` is layered on, so a worker can never fall back to the
+   account's credentials — and so is every OTHER credential-shaped key (`isCredentialEnvKey`:
+   `GH_`/`GITHUB_`/`NPM_`/`NODE_AUTH_`/`SOPS_`/`AWS_`/`AZURE_`/`GOOGLE_`/`OPENAI_` by prefix, plus
+   anything ending in `TOKEN`, `SECRET`, `PASSWORD`, `API_KEY` or `PRIVATE_KEY`). The reconciler runs
+   from a developer's session or from launchd, so its env is whatever that shell exports; a worker
+   holding `GITHUB_TOKEN` pushes and opens PRs through the API with no `gh` binary involved, past
+   every deny rule the lane spent its effort on. Its pid is written to the lock as `workerPid` the moment it exists. Its
+   stdout streams line by line into `stream.jsonl`, and a 30 s timer refreshes `heartbeatAt`.
+4. When the worker exits, render `run.log`, classify the stream and run the close. The heartbeat
+   keeps beating through all of it, and only stops once the slot has been released or held.
+
+Before step 4 does anything, the pass **re-reads its own per-task lock**. The single-flight lock is
+long gone by then, so a maintenance sweep in another pass may legitimately have declared this worker
+dead (a heartbeat that fell behind is enough), saved its work, released its slot and handed that
+worktree to the next task. Closing on top of that opens a PR off someone else's branch, re-statuses
+a task a person already moved, and releases a slot holding live work. A lock that is gone, or that
+names another pid, skips the close entirely: the sweep already saved and blocked.
+
+The dispatcher process therefore stays alive for the worker's whole run — which is fine, because
+BOTH triggers detach it with `nohup` and return: the `onStatusChange` callback, and the launchd
+launcher (which must, or launchd would refuse to fire its own timer again while this pass lived —
+see "Installing the launchd recovery timer"). Holding the single-flight lock across that run instead
+would make the frontier cap of 2 unreachable, stall the close's `drain`, prevent the maintenance
+pass from cancelling a running worker, and leave a 10-minute-TTL lock stale while its worker is
+demonstrably alive.
+
+Everything from taking the slot to the worker exiting runs inside one try/catch. A failing
+`pnpm install`, a `git checkout` against a ref that vanished, a hook subprocess that dies while the
+prompt is assembled — any of them used to escape the pass with the slot taken, the lock written and
+the task sitting in `In Progress`, recoverable only by the next sweep ten TTL minutes later. Now the
+slot goes back to the pool, the lock is removed, and the task moves to `Blocked` carrying the error.
+
+A close that ends in `drain` sets a flag; `dispatch.ts` then re-acquires the single-flight lock and
+runs ONE more pass for the next `Queued` task. Two passes per invocation is the cap — a trigger can
+never loop the whole queue in one process.
+
+## Lane profiles (`lanes.json`)
+
+`scripts/backlog/lanes.json` holds only what Claude Code itself cannot already express (slot
+pool, `maxParallel`, `attempts`, `effort`, the direct/sdd model split, the LM Studio health-check
+URL, and the close reviewer's model and timeout).
+
+`lanes.frontier.maxBudgetUsd` is OPTIONAL — set a number when the machine authenticates with an
+API key and you want a hard dollar stop; omit it on a subscription login, where the estimate is not
+billed and the cap only truncates work; `maxTurns` and `timeoutMinutes` are the guards that always
+apply. `loadLaneConfig` still validates a DECLARED value — non-numeric or zero throws, same as
+every other field — it is absence, not presence, that is unchecked.
+
+`harnessReviewer` (top-level, T-31) is OPTIONAL too — the human-review mark's reviewer handle (see
+"Forbidden paths, split by mechanism" below). It ships UNSET: `gh pr create --reviewer <self>` (and
+the equivalent `pr edit`) fails when the reviewer is the pull request's own author, and the
+dispatcher opens every PR as the same account. Set it to a second account's handle to actually get a
+reviewer assigned; the absence is recorded once on a marked PR rather than treated as an error. A
+DECLARED value is validated for its SHAPE, not merely for being a string: a GitHub login (1-39
+characters, alphanumerics and single interior hyphens) or an `org/team-slug`. The value becomes an
+argv TOKEN in `gh pr edit … --add-reviewer <value>`, and `gh` reads a token starting with `-` as a
+FLAG — the same reason `resolveTestCommand` anchors its `--filter`/`--dir` values on a non-dash first
+character.
+
+`maxParallel` (per lane) and `attempts` (global) are the dispatcher's two caps, and they are LIVE:
+`launch.ts`'s `dispatchLimitsFrom` turns the loaded config into the object guard 5, guard 6 and
+`acquireSlot` all read. Editing either number in this file changes what the dispatcher does on the
+next pass. There is no `bare` field: the local lane is always `--bare` and the frontier lane never
+is — that is a property of what each lane IS, not a knob, and a knob that could not be turned only
+told its reader a lie.
+Everything Claude Code DOES already understand — `model`, `env`, `permissions` — lives in a
+standard settings file per lane (`scripts/backlog/lanes/local.settings.json`,
+`scripts/backlog/lanes/frontier.settings.json`), which `launch.ts` READS and translates into the
+launch itself — `model` becomes `--model`, `permissions.allow`/`deny` become
+`--allowedTools`/`--disallowedTools`, and `env` is injected into the spawn environment. The files
+keep Claude Code's own settings shape so they stay readable and reusable, but they are NOT passed
+with `--settings`: Phase 1 spike 1.1 measured spawn-env as the injection mechanism that actually
+takes effect, with `--settings` kept only as a validated fallback. This split means
+**changing the local model is editing one field**: swap `local.settings.json`'s `model` (and the
+matching `ANTHROPIC_*` env values) to point at a different LM Studio model id, nothing in
+`lanes.json` or any `.ts` module needs to change — the readiness check reads the model id from
+`local.settings.json` too, so there is exactly one place to edit. Using Sonnet locally instead of an LM Studio
+model is deleting `local.settings.json`'s `env` block entirely.
+
+`local.settings.json` sets every `ANTHROPIC_DEFAULT_{SONNET,OPUS,HAIKU}_MODEL` to the SAME LM
+Studio model id — the local lane only ever runs `tier:minor`, so there is no direct/sdd split to
+alias differently, but a sub-agent spawned inside the local worker that happens to ask for "opus"
+must still resolve to the one model actually loaded. `frontier.settings.json` carries `env: {}` —
+the cost knob, empty because the lane runs on the account — plus the lane's whole explicit `allow`
+list and its `deny` list; it declares no `model`, because `launch.ts`
+resolves that from the task's `path:` label (`path:direct` → Sonnet, `path:sdd` → Opus, matching
+`catalyst-delegation`'s model table) and passes it as `--model`, which would always beat a value in
+the file.
+
+**`--bare` does NOT stop settings loading, so the local lane names its source too.** Measured
+(T-5, 2026-09-07): `claude --help` lists what `--bare` skips — hooks, LSP, plugin sync, attribution,
+auto-memory, background prefetches, keychain reads, `CLAUDE.md` auto-discovery — and settings files
+are not on that list. The launch used to pass `--bare` and no `--setting-sources` at all, on the
+reading that the flag covered it; what it actually got was the DEFAULT set, so the USER file, the
+PROJECT file and `.claude/settings.local.json` all loaded into the executor. The consequence is in
+that attempt's `stream.jsonl`: the worker ran `python3 -c` (writing a file in the MAIN checkout,
+outside its slot, and reverting it by hand afterwards), `npx prettier` and `pnpm exec prettier`
+through `Bash` — this machine's overlay carries `Bash(python3 -c *)`, `Bash(git *)`, `Bash(pnpm *)`
+and ~60 more click-approvals, and the lane grants no such rule anywhere. The launch now passes
+`--setting-sources user`, the narrowest value the flag accepts (an empty one is not in the grammar —
+the same value the close's reviewer passes), and composes its deny list from that one loaded source
+exactly as the frontier lane does: `loadSettingsAllowRules` over the USER file, then
+`settingsAllowRulesToDeny` against the whole granted surface, with guard 1b deciding the overlaps
+that have no safe answer. `--bare` and `--strict-mcp-config` stay: the prefill cost and the MCP
+servers are what they are for. The flag does not cost the lane its credential — measured in the same
+probe below, a `--bare --setting-sources user` run authenticated against LM Studio through the lane's
+own `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` and completed normally.
+
+Two things follow, and both are load-bearing. **The `--setting-sources` value and the subtraction
+come from one list**, `launch.ts`'s `LANE_SETTING_SOURCES` (`local: user`, `frontier: user,project`):
+`settingSourcesFlag` joins it into the flag, `settingsSourcePaths` turns it into the files, so the
+flag and the deny list cannot describe different sets. And **guard 1b now runs on BOTH lanes** — it
+was frontier-only precisely because of the `--bare` misreading above.
+
+**A read-only `Bash` command needs no allow rule at all.** Measured with the free local model, from
+a temp git repo, `--bare --strict-mcp-config --setting-sources user --permission-mode dontAsk
+--allowedTools 'Read'`: a bare `ls` through `Bash` was ALLOWED, with `permission_denials: []`, while
+a compound `ls -la; cat a.txt; echo …` was DENIED in the same conditions. So Claude Code auto-approves
+a Bash command it can statically read as read-only, whatever the allow list says — which is where the
+T-5 run's `find`, `ls`, `pwd` and `grep` came from, not from the overlay. The lane's `--allowedTools`
+therefore bounds every WRITE and every non-trivial command, not literally every `Bash` invocation.
+
+Beyond that, the local lane's `--allowedTools` is its permission surface. It is path-scoped:
+`Edit(./**)`/`Write(./**)` rather than bare `Edit`/`Write` (the cwd is the slot), and
+the `deny` half additionally refuses `Edit`/`Write` on `.husky/**`, `.claude/**`, `scripts/**`,
+`package.json`, `pnpm-lock.yaml`, `node_modules/**` and `.git/**` — everything that GOVERNS or RUNS
+the dispatcher itself. The close's `SLOT_EXECUTED_PATHS`/`LOCAL_FORBIDDEN_PATHS` re-check the same paths
+against the real diff, because a permission rule that silently fails to match must not be the only
+barrier.
+
+**The `Edit(./**)` spelling is measured, not assumed.** Spike 1.2 had measured a bare relative glob
+(`Edit(allowed/**)`) working under `--allowedTools`; whether the `./` prefix matches was left
+untested until now. Same probe as above (free local model, temp git repo, `Read` plus the rule under
+test, prompt "append the line hello to a.txt using the Edit tool"):
+
+| Rule under test | Edit allowed? | Evidence |
+| --- | --- | --- |
+| `Edit(./**)` | yes | tool_result "has been updated successfully", `permission_denials: []`, `a.txt` appended |
+| `Edit(**)` | yes | same, `permission_denials: []` |
+| `Edit(a.txt)` | yes | same; the run ended `error_max_turns` for an unrelated denied compound `Bash` |
+
+All three admit an Edit whose `file_path` argument is the ABSOLUTE path inside the cwd, so the
+shipped `Edit(./**)`/`Write(./**)` spelling stays — it is the one that also states the intent (the
+scoping is the slot), and `grantCovers` already normalises a leading `./` on both sides when
+comparing it against a loaded rule.
+
+**A task that must change a dependency cannot be dispatched.** `package.json` (root and every
+workspace one — the patterns are matched as substrings, so `backend/package.json` is a hit),
+`pnpm-lock.yaml` and `node_modules/` are in `SLOT_EXECUTED_PATHS`, so they are refused on BOTH lanes,
+declared or not. They are the environment this close runs its own Prettier, barrels lint and
+`pnpm test` in: a rewritten `test` script or lockfile is code the dispatcher executes moments later.
+The cost is accepted deliberately — adding a dependency is a change a person makes in an
+interactive session, where the install and its diff are read, not one a headless attempt slips in.
+
+**The task's own test command is granted per launch, not by a standing rule.** `launch.ts` turns the
+task's SNAPSHOTTED `Test command:` — the same line `resolveTestCommand` validates for the close —
+into one `Bash(<command>:*)` rule and appends it, on both lanes. A task that declared none, or one
+the allowlist refuses, gets no rule. The rule it replaced (`Bash(pnpm --filter * test*)`) was a
+trailing glob that matched any pnpm subcommand whose words happened to line up.
+
+The local lane carries no standing `pnpm` rule at all, so that grant is its only one. The frontier
+lane carries five COMMANDS, and each is shipped as a PAIR of rules rather than one colon-terminated
+rule: `Bash(pnpm --filter * test)` + `Bash(pnpm --filter * test *)`,
+`Bash(pnpm --filter * exec prettier --check)` + `Bash(pnpm --filter * exec prettier --check *)`,
+`Bash(pnpm --filter * exec tsc --noEmit)` + `Bash(pnpm --filter * exec tsc --noEmit *)`,
+`Bash(pnpm --filter * db:generate)` + `Bash(pnpm --filter * db:generate *)`, and
+`Bash(pnpm --filter * db:check)` + `Bash(pnpm --filter * db:check *)` — a frontier orchestrator
+writes tests and type-checks across workspaces as it works, and a worker that can only run the one
+line its task declared cannot do that. **Why a pair, and never the single `Bash(pnpm --filter *
+test:*)` rule this used to be:** measured (T-7, 2026-09-07, Claude Code 2.1.263) — a Bash rule that
+combines a mid-rule `*` with a trailing `:*` matches NOTHING. `Bash(pnpm --filter * test:*)` never
+matched `pnpm --filter aurora-back test`, on either lane, ever; it looked like a working scoped
+grant in review and was actually five silent holes. The exact-form half (`Bash(pnpm --filter * test)`)
+matches the command with no extra argument; the with-arguments half (`Bash(pnpm --filter * test *)`)
+matches it with one or more. See "A mid-rule `*` is a wildcard" further down in this section for the
+full measurement. The last two commands are BOTH offline (`catalyst-schema-migrations`): `db:generate` diffs a
+workspace's `*.schema.ts` files against its last `snapshot.json`, and `db:check` runs the same
+comparison — neither ever reaches a real database, so granting them widens no boundary the other
+three did not already assume. Each names a `--filter`ed workspace and a fixed verb: no
+`pnpm add`/`install`/`dlx`, no bare `pnpm run`, and no `pnpm test:<script>` (the root scripts,
+which execute `scripts/**`).
+
+**Every board access goes through a dispatcher-owned wrapper, never through the `backlog` CLI.**
+Under `--permission-mode dontAsk` anything unlisted is denied, so `launch.ts` appends exactly ONE
+board rule to `--allowedTools`, on BOTH lanes:
+`Bash(npx --loglevel=error tsx <main checkout>/scripts/backlog/worker-edit.ts T-nn:*)`. The read
+goes through it too (`--view`, accepted only on its own): a separate `Bash(backlog task view T-nn:*)`
+was a prefix like any other, so a command line that merely STARTED with those words matched whatever
+followed — a narrow write channel standing next to an open-ended one.
+
+The raw write was granted in two earlier shapes, and both were wider than they read:
+
+- a bare `Bash(backlog task edit:*)` let a worker edit, comment on and re-status ANY task on the
+  board, including moving another one to `Queued` for the dispatcher to pick up;
+- one rule per allowed flag (`Bash(backlog task edit T-nn --notes:*)`) fixed the id and the FIRST
+  flag — but **a permission rule matches a PREFIX and cannot narrow what comes after it**, so
+  `--notes x --status Done` matched too: the worker could still set its own task to `Done` (the
+  maintenance sweep then reads a finished task nobody verified) and rewrite the very acceptance
+  criteria the pre-PR gate and the reviewer judge it against. "Anything else is denied" was never
+  true of a rule with a trailing wildcard, and the prompt and this README both used to say it was.
+
+`worker-edit.ts` is the barrier that does not depend on a rule matching, because it reads the WHOLE
+argv before anything reaches the CLI: exactly the dispatched task id (taken from `BACKLOG_TASK_ID`
+in the worker env, not from the command line — comparing an argument against itself proves nothing),
+then one or more of `--check-ac`, `--notes`, `--append-notes` and `--plan`, each at most once, each
+with a value that is not itself a flag, and `--check-ac` only with the `#N` the CLI prints — or
+`--view` on its own, which forwards to `backlog task view <id> --plain`. Anything
+else exits **2** — distinct from the CLI's own 1, so a refusal never reads as a CLI error — with a
+message naming what it refused, and writes nothing. On success it forwards to
+`backlog task edit <id> <args…>` in the main checkout (`BACKLOG_CWD`).
+
+The grant names the **main checkout's** copy of the script, never the slot's: the slot's `scripts/`
+is a directory the worker could write to if a deny rule ever failed to match, and a barrier the
+thing under test can edit is not a barrier. The close's board-integrity gate is the DETECTOR behind
+it, for the case where a permission rule silently fails to match anyway.
+
+**The slot's own `.backlog/` copy is denied outright.** Both lane settings deny
+`Edit(.backlog/**)`/`Write(.backlog/**)`, and the close's scope check reports a change there as a
+violation on both lanes. Editing the board file directly would reach the criteria the close judges
+the attempt against, going around the wrapper entirely.
+
+**The frontier lane's allowlist is EXPLICIT, written out in `frontier.settings.json`.** It is not
+derived from anything: `launch.ts` reads that file's `permissions.allow` and emits it, plus the two
+grants the dispatcher itself decides on (the `worker-edit.ts` wrapper and the validated test
+command). As shipped:
+
+```
+Read  Grep  Glob  Edit(./**)  Write(./**)  Agent  Skill  TodoWrite
+Bash(git status:*)  Bash(git diff:*)  Bash(git log:*)  Bash(git show:*)
+Bash(git rev-parse:*)  Bash(git symbolic-ref:*)
+Bash(openspec:*)  Bash(catalyst:*)
+Bash(pnpm --filter * test)  Bash(pnpm --filter * test *)
+Bash(pnpm --filter * exec prettier --check)  Bash(pnpm --filter * exec prettier --check *)
+Bash(pnpm --filter * exec tsc --noEmit)  Bash(pnpm --filter * exec tsc --noEmit *)
+Bash(pnpm --filter * db:generate)  Bash(pnpm --filter * db:generate *)
+Bash(pnpm --filter * db:check)  Bash(pnpm --filter * db:check *)
+```
+
+The file tools are path-scoped to the slot like the local lane's, plus the two tools an orchestrator
+needs to BE one (it delegates to sub-agents and reads skills by path) — under
+`--permission-mode dontAsk` a tool with no allow rule is DENIED, and a lane holding only `Bash` rules
+is not a restricted worker, it is a worker that cannot open a file. The commands are what a frontier
+orchestrator's job actually needs: inspect the tree it works in (read-only `git` verbs — none of them
+stages, commits, moves a branch or discards a file), run the SDD flow (`openspec`), run the generator
+(`catalyst`), verify its own work in a workspace (a scoped test, Prettier's `--check`,
+`tsc --noEmit`), and evolve a workspace's Drizzle schema OFFLINE (`db:generate`/`db:check` — both diff
+`*.schema.ts` against the last `snapshot.json`; neither touches a database, per
+`catalyst-schema-migrations`). **No granted command runs a script out of the tree the worker can write to** — no
+`node`, `tsx`, `npx`, bare `pnpm run` or `pnpm test:` rule — which is the property that makes the
+`Edit`/`Write` allowance over `scripts/**` safe (see the deny section below). `launch.test.ts` holds
+that as an assertion over the shipped file, not as a comment.
+
+It used to be the project's own list, subtracted from: `launch.ts` read `.claude/settings.json`'s 43
+`permissions.allow` rules at launch and dropped the dangerous ones by command prefix. The reasoning
+was that the rules people maintain should stay one list rather than being copied into a second one
+that drifts — but an inherited list is a moving target, and a SUBTRACTION over it reopens with every
+rule somebody adds. The filter had to be right about commands that did not exist when it was written,
+in a file whose whole purpose is a person approving a command for their OWN interactive session. The
+evidence is that file as it stands: `Bash(fd:*)`, `Bash(git restore:*)`, `Bash(git branch:*)`,
+`Bash(eslint:*)`, `Bash(npm test:*)` and `Bash(pnpm test:hooks:*)` are all in it, and no prefix in
+that filter covered one of them — a finder that reaches `--exec`, two git verbs that discard work and
+move branches, and three runners that execute files out of a tree the worker can write to, every one
+of them reaching the headless worker past a filter written before they existed. What survives review
+now is the list itself, and every rule in it was read once and stays read.
+
+Both `--allowedTools` and `--disallowedTools` are always emitted on BOTH lanes, even when a list is
+empty: `--permission-mode dontAsk` with no `--allowedTools` is unrestricted, not restricted. And the
+launch guard asks for CAPABILITIES, not for a non-empty list: `assertLaneGrantsFileAccess` throws
+unless the merged allow list carries at least one read rule (`Read`) and at least one write rule
+(`Edit`/`Write`, bare or path-scoped), and the task is blocked with that reason rather than burning
+an attempt on a worker that discovers mid-run it cannot write. "Non-empty" was the wrong
+question — 43 `Bash` rules satisfy it.
+
+**But the launch is not the only source of `allow`.** The frontier lane passes
+`--setting-sources user,project`: this worker runs the FULL harness and needs the project's hooks.
+The user file also loads; measured on this machine its `enabledPlugins` merely duplicates what the
+project file already turns on for every plugin `check-required-setup.ts` requires, so that alone
+would not justify loading it. What it uniquely contributes here is its own `hooks`, its
+`mcpServers` entry, its `model` override, and the enablement of plugins the project file does not
+require (`.mcp.json` is not a settings source and loads regardless). The local lane passes
+`--setting-sources user`, because `--bare` does not stop settings loading (see the local-lane section
+above) and one source is the least the flag can name. **The click-approval overlay is NOT among them,
+on either lane.** `.claude/settings.local.json` is where a person's ad-hoc "yes, allow that" answers
+pile up — 61 rules on this machine, `Bash(git *)`, `Bash(pnpm *)` and `Bash(python3 -c *)` among them,
+which is every git and every pnpm subcommand including the ones the lane's list deliberately withholds
+— and since Claude Code 2.1.211 a worktree reads the MAIN checkout's copy, so a slot would inherit the
+lot. A headless worker must never inherit a person's click-approvals, so the file is excluded at the
+source: not loaded, therefore nothing to subtract, and no dilemma between revoking a reviewed lane
+grant and blocking the task.
+
+Whatever DOES load still brings its `permissions.allow`, and `--allowedTools` ADDS to what that grants
+rather than replacing it. Writing a lane's list out therefore bounds only what the LAUNCH grants; on
+the frontier lane the project file's 42 approved rules load with the hooks, and on the local lane the
+user file loads alone (it contributes none on this machine — an empty `permissions.allow`). The
+layering, in order, on EITHER lane:
+
+1. the lane's settings sources load — user, then project on the frontier lane — bringing the project
+   hooks AND their `permissions.allow`;
+2. the launch adds the lane allow list plus the two per-task grants (the `worker-edit.ts` wrapper,
+   the validated test command);
+3. the launch denies its static deny list PLUS **every allow rule those loaded sources contribute
+   and the lane does not grant**;
+4. a deny outranks every allow, whatever its source — so step 3 is what makes step 2 the whole
+   surface.
+
+Step 3 is `launch.ts`'s `settingsSourcePaths` + `loadSettingsAllowRules` (the union of the lane's
+sources, in load order, deduped) + `settingsAllowRulesToDeny`. Both `settingsSourcePaths` and the
+`--setting-sources` value are derived from one per-lane list (`LANE_SETTING_SOURCES`), so the flag and
+the subtraction cannot describe different sets. They are read from the DISPATCHER's own checkout — the one every slot is a worktree
+of, and the same place the lane settings file comes from — never from the slot. `.claude/settings.json`
+is in the close's `SLOT_EXECUTED_PATHS` and the lane denies writing it, but "the file it edited decides
+what it may do" is not a property to rest on two other mechanisms holding; and comparing a list from
+the slot against a lane list from the checkout would be comparing two different files.
+
+**"Does not grant" is decided by COVERAGE, not by string inequality**, because a deny is coarse. The
+project file's `Bash(openspec status:*)` is already covered by the lane's `Bash(openspec:*)`, so
+denying it by spelling would revoke the lane's own grant — and with it the SDD flow this lane exists
+to run; `Bash(pnpm --filter aurora-back test:*)` sits inside `Bash(pnpm --filter * test)` the same
+way, with the `*` read as a wildcard. A loaded rule the granted list already covers grants nothing new
+and is skipped. The reverse overlap has no safe answer: a loaded rule BROADER than a rule the launch
+grants — the project file's `Bash(pnpm test:hooks:*)` over a task whose declared test command is
+`pnpm test:hooks <file>` — is either denied, revoking the task's own test grant, or kept, handing the
+worker a runner that executes files out of a tree it can write to. So the task is BLOCKED
+(`permission-conflict`) with both rules in the comment, for a person to resolve: narrow the settings
+rule, or the task's test command. That visibility is the point — a permission conflict nobody sees is
+the failure mode this whole section exists for.
+
+**That refusal is guard 1b, not a launch failure.** It is a property of the task and of the settings
+files in the dispatcher's own checkout, so it is knowable before anything is taken: `guards.ts`'s
+`checkPermissionComposition` runs right after the triage checks, on BOTH lanes (it was frontier-only
+while the local lane was believed to load no settings source at all), and the task never reaches slot
+acquisition. Deciding it inside `buildLaunch` — as it did until round 10 —
+cost a worktree slot, a lock, an attempt directory and a `dispatch-failed` block to report a
+conflict that no attempt could have resolved. `settingsAllowRulesToDeny` still throws on it, as the
+last-resort invariant behind the guard for a caller that composes a launch without evaluating it, and
+both read the same `findPermissionConflict`.
+
+**The comparison has TWO directions, and they are different questions.** "Is this loaded rule
+already granted, so skip it?" is `grantCovers`, and it is deliberately STRICTER than the real matcher:
+a false "not covered" only costs a deny for a rule the launch grants anyway, while a false "covered"
+hands the worker surface nobody reviewed. "Would a deny for this rule revoke that grant?" is
+`denyWouldRevoke`, and it must be exactly as coarse as Claude Code itself — a RAW prefix, `*` as
+wildcard, no token boundary, no opinion about shell operators. Asking the strict predicate in the deny
+direction was a live bug: the project's `Bash(pnpm test:hooks:*)` over a task declaring
+`pnpm test:hooks-extra` read as unrelated, so the launch emitted the deny — and the deny killed the
+task's own test grant. A rule that MIGHT revoke a grant is reported as a conflict, never denied.
+
+Four details of `grantCovers` are load-bearing, because a permission rule is a PREFIX and a prefix
+match is not the same question as coverage:
+
+- **A command candidate must resume at a token boundary and carry no shell operator.**
+  `Bash(git status:*)` prefix-matches the string `git statusfoo`, which is a different command, and
+  `git status && fd .`, which is two — the second of them a binary this lane spends deny rules
+  refusing. Both read as UNCOVERED, so they are denied rather than waved through as "the lane already
+  grants that".
+- **A boundary is a space OR a `:`, and a granted base can supply its own.** `:` separates a pnpm
+  script from its subcommand, so `Bash(pnpm --filter * test)` covers
+  `Bash(pnpm --filter aurora-back test:extra:*)`; and a granted base whose trailing boundary was
+  consumed by its own wildcard (`Bash(git *)` → `git `) has already matched at one, so
+  `Bash(git status:*)` is covered by it.
+- **A path scoping is compared with a leading `./` stripped on both sides.** The lane spells its file
+  grants `Edit(./**)`/`Write(./**)` because the cwd is the slot, so without that normalization a
+  loaded `Edit(frontend/**)` read as uncovered — and the deny composed for it would have taken the
+  worker's write access to `frontend/` away.
+- **A scoping that LEAVES the working directory is never covered by one that stays inside it.**
+  `Edit(/etc/**)` and `Edit(~/notes/**)` are the obvious cases; `Edit(../**)` is the one the `./`
+  normalization hid, since `..` reads as an ordinary relative glob to a prefix match.
+
+**A non-covered FILE-tool scoping (`Read`/`Edit`/`Write`) blocks the task only when its deny would
+reach inside the slot** — a bare rule (`Edit`), an unscoped glob (`Edit(**)`, `Edit(./**)`), or a
+relative one (`Edit(frontend/**)`). A deny on those does not narrow the worker, it stops it opening
+files there at all, so the task is blocked for a person instead. A scoping that only reaches OUTSIDE
+the slot (`Edit(/etc/**)`, `Edit(~/x/**)`, `Edit(../**)`) is denied like any other rule, which is
+precisely what the subtraction is for.
+
+**A rule's SOURCE is part of the rule, because a path glob is relative to the file that declares it.**
+`Edit(**)` in the project file scopes the checkout the worker runs in; the same rule in the USER file
+scopes the whole home directory, which the lane has no way to grant — its own `Edit(./**)` is the
+slot. So `loadSettingsAllowRules` tags each rule with the source it came from (`user` or `project`,
+the first of the two winning when both declare it), and a USER-file path rule with no scoping of its
+own (`Edit`, `Edit(**)`, `Edit(./**)`) blocks the task unless the lane grants that tool BARE — the
+one grant that does reach outside the slot. Without the tag it read as covered by `Edit(./**)`, an
+artefact of the `./` normalization, and the worker got `$HOME` silently.
+
+What that denies out, measured against the shipped project file — 42 rules loaded, 30 denied, 12
+already covered by the lane: `Bash(fd:*)`, `Bash(find:*)`,
+`Bash(grep:*)`, the staging/committing/discarding git verbs, `Bash(gh auth:*)`/`Bash(gh pr:*)`,
+`Bash(npm run format:*)`, `Bash(npm test:*)`, the three `npx` rules, `Bash(eslint:*)`, the
+`pnpm exec` pair, every `Bash(pnpm test:…)` / `Bash(pnpm cli:test:*)` / `Bash(pnpm br:validate:*)` /
+`Bash(pnpm hr:lint-barrels:*)` / `Bash(pnpm peers check:*)` runner, `Bash(aurora load:*)`,
+`Bash(shasum:*)` and the two `mcp__claude-in-chrome__*` tools. Bash `grep` and `find` go with them:
+the `Grep`/`Glob` tools are what this worker reads with, and the read-only Bash hook cannot hand a
+denied command back. `launch.test.ts` asserts that outcome over the SHIPPED `.claude/settings.json`
+and the shipped lane file — the only loaded source that lives in the repo — so a rule somebody adds to
+the project list tomorrow is denied on the next launch with nobody editing `launch.ts`.
+
+### Test commands that conflict with the project allow list
+
+**Over the two loaded sources as they stand, no launch refuses on the LANE list**: nothing in the 42
+rules is broader than a lane rule. What remains is per-task, and it is one shape — a declared
+`Test command:` that is a NARROWER form of one of the project file's script rules. Five rules in that
+file can swallow a task's own test grant, so a task whose test command is `pnpm test:hooks`,
+`pnpm test:contracts`, `pnpm test:packager`, `pnpm test:catalyst-regen` or `pnpm cli:test` WITH AN
+ARGUMENT is blocked with `permission-conflict` before a slot is taken:
+
+| Project rule | A declared test command it swallows |
+| --- | --- |
+| `Bash(pnpm test:hooks:*)` | `pnpm test:hooks scripts/x.test.ts` |
+| `Bash(pnpm test:contracts:*)` | `pnpm test:contracts <file>` |
+| `Bash(pnpm test:packager:*)` | `pnpm test:packager <file>` |
+| `Bash(pnpm test:catalyst-regen:*)` | `pnpm test:catalyst-regen <file>` |
+| `Bash(pnpm cli:test:*)` | `pnpm cli:test <file>` |
+
+Both rules are named in the block comment. **The resolution is per-task: declare a command the
+project list does not cover** — the repo's own convention, `pnpm --filter <pkg> test <file>`, which
+the lane's `Bash(pnpm --filter * test)` covers outright. Declaring the command exactly as the
+project rule spells it (no argument) also clears it, since an identical rule is covered rather than
+broader. **Never widen the lane's allow list to clear one of these**: the lane list is the reviewed
+surface of EVERY frontier task, and widening it to unblock one task grants that runner to all of
+them — a task-shaped problem paid for by every task that follows. (Excluding the overlay is what removed the lane-wide case:
+`Bash(git *)` and `Bash(pnpm *)` in it are broader than `Bash(git status:*)` and
+`Bash(pnpm --filter * test)`, so while that file was a source, every single frontier launch
+refused.)
+
+**Three assumptions under all of this were documented Claude Code behaviour; one of them has since
+been MEASURED, and the measurement corrected it.** The phase-9 end-to-end run (tasks.md 9.7) must
+still confirm the other two from `stream.jsonl` on a dispatched frontier task:
+
+1. **Deny beats allow from any source.** A command the project list allows and the lane does not
+   (`fd .`) is refused, and a command the lane grants under a rule broader than the project's
+   (`openspec list`) still runs. Everything in this section rests on it.
+2. **A mid-rule `*` is a wildcard — but ONLY in glob form, never combined with a trailing `:*`.**
+   Measured (T-7, 2026-09-07, Claude Code 2.1.263, `claude -p` probes with `--setting-sources user`
+   and 0 allow rules, `--permission-mode dontAsk`): `Bash(pnpm --filter * test:*)` does **not** allow
+   `pnpm --filter aurora-back test` — that combination of a mid-rule `*` with a trailing `:*` matches
+   NOTHING at all, on any command line. The coverage comparison (`grantCovers`) still treats a
+   mid-rule `*` as a wildcard, and that stays correct for the shape the frontier lane ships instead
+   of the retired rule: `Bash(pnpm --filter * test)` (exact form, no trailing glob) and
+   `Bash(pnpm --filter * test *)` (with one or more arguments) — see "The task's own test command is
+   granted per launch" above. The "12 rules already covered" result below rests on the EXACT-FORM
+   half of that pair.
+3. **Commands are split before matching.** A compound line (`git status && fd .`) is refused rather
+   than admitted by its allowed prefix. The comparison assumes this and refuses coverage for a
+   compound candidate; if the real matcher were to admit one, that assumption is the barrier that
+   moved.
+
+**`Bash(catalyst:*)` is a broad grant, and it is a deliberate one.** It is the generator: one
+`catalyst generate <bc> <module> --force` rewrites every emitted file of a whole bounded context —
+far more than the task's own subject, and with no `.origin` reconciliation on this lane. The lane
+grants it because a frontier task that changes a schema cannot do its job without it. Nothing narrows
+it at launch: the review is the close's scope check over the real diff, which still stops the
+generator from reaching `.claude/settings*.json` or `.backlog/` (the hard list, `SLOT_EXECUTED_PATHS`)
+and, regardless of the two lists, the mirror output `packages/cli/src/templates/` — `packages/cli/`
+itself and `scripts/backlog/` are the soft list now, so a regen that reaches them is ADMITTED and
+marks the pull request instead of failing (see "Forbidden paths, split by mechanism" below) — and
+then the PR itself, which is the human gate either way. If a regen's blast radius on a
+slot ever needs bounding tighter than that, it is a rule change to argue for with evidence, not a
+comment to add here.
+
+**The effective permission surface on the frontier lane is: the lane allow list, plus the read-only
+commands a project hook vets, minus the deny list — where the deny list also cancels the project
+allow rules the lane does not grant.** The lane runs the full harness, and the
+project's `PreToolUse` hook on `Bash` — `.claude/hooks/auto-allow-readonly-bash.ts` — answers
+`permissionDecision: "allow"` for a vetted read-only table (`grep`, `sed -n`, `git log`, `find`
+without `-exec`/`-delete`, and the rest of `READ_ONLY_COMMANDS`, refusing redirections, command
+substitution, heredocs, path-invoked commands and every write-capable mode). That is deliberate and
+kept: an orchestrator needs to READ the repo, and the alternative is one allow rule per binary, which
+is the moving target this lane just stopped inheriting. So a read-only Bash command may run here even
+though no lane rule names it — and nothing that WRITES or EXECUTES may, because the hook refuses
+those and the deny list refuses them again.
+
+The hook is not the only reason that happens. Measured on the local lane (which loads no hook at all
+under `--bare`): with `--allowedTools 'Read'` and nothing else, a bare `ls` through `Bash` was
+allowed with `permission_denials: []`, while a compound `ls -la; cat a.txt; echo …` was denied. Claude
+Code itself auto-approves a Bash command it can statically read as read-only. The hook's value is that
+it is the vetted table we OWN — but "no allow rule names it, therefore it cannot run" was never true
+of a read-only command on either lane.
+
+**A deny rule is what holds regardless of source.** A deny outranks any allow rule, from the lane
+file, from whatever settings the harness loads, or from a hook answering `allow` — which is why the
+list below keeps rules the lane's own allowlist no longer contains.
+
+**The frontier deny list is the local one minus two documented allowances.** Both lanes deny
+`Bash(git push:*)`/`Bash(git push*)` and `Bash(gh:*)`/`Bash(gh *)` (each in both spellings, because
+they match different command shapes and a rule that fails to match denies nothing), `WebFetch`,
+`WebSearch`, and `Edit`/`Write` on `.backlog/**`, `.husky/**`, `node_modules/**`, `package.json`,
+`pnpm-lock.yaml` and `.git/**` — the board, and everything that governs or runs the dispatcher
+itself. The frontier list adds the git verbs that stage, commit, move a branch or throw work away
+(`git add`, `git commit`, `git restore`, `git branch`, `git clean` — the close is what commits and
+pushes, and `restore`/`clean` destroy the very work it is about to save) and the two file finders
+that can execute what they find (`find`, `fd`), each in both spellings.
+
+`Edit`/`Write` on `.claude/**` and `scripts/**` are the two allowances: a frontier task may
+legitimately edit a skill or the tooling, which is part of why it runs on the wider lane at all —
+and the lane's narrowed denials below carve the dangerous corners back out, with the close's hard
+list (`SLOT_EXECUTED_PATHS`) re-checking both `.claude/settings*.json` against the real diff
+regardless of what the permission rule matched. `scripts/backlog/` is SOFT now (T-31) — admitted, and
+marking the pull request for human review, rather than re-checked as a violation.
+`scripts/**` stays writable, and it is safe BECAUSE no granted command
+executes it: the allow list carries no `node`, `tsx`, `npx`, `pnpm test:` or bare `pnpm run` rule, so
+the pair is a permission to EDIT a script, never to run one — with two exceptions the CLOSE creates,
+not the worker: `scripts/packager/` (spawned by the mirror regeneration) and `scripts/harness-rules/`
+(run by the barrels lint), which is why both are on the close's hard list. `launch.test.ts` compares
+the FULL deny lists against that allowance set, so the wider lane can never again be guarded less by
+omission.
+
+Those allowances are NARROWED, not blanket. The frontier lane replaces the local lane's `.claude/**`
+deny with the executable corners of that directory plus BOTH settings files and the instruction
+files: `Edit`/`Write` on `.claude/hooks/**`, `.claude/scripts/**`, `.claude/settings.json`,
+`.claude/settings.local.json`,
+`CLAUDE.md` and `**/CLAUDE.md` (and the `Claude.md`/`claude.md` casings, since macOS is
+case-insensitive while a permission glob compares the spelling it was given). The reason is that the
+harness EXECUTES the first two inside the slot: the project's `PostToolUse` hook runs
+`$CLAUDE_PROJECT_DIR/.claude/hooks/format-with-prettier.ts` after every Write/Edit, and
+`CLAUDE_PROJECT_DIR` is the slot the worker is writing to — so a hook written there runs as the
+worker on its very next edit, past every other rule; `.claude/scripts/` runs the same way from
+`SessionStart`. `.claude/settings.json` is the file this very launch READS to compose its deny list,
+and the project settings source the worker itself loads — the one place where "the file it edited
+decides what it may do" would be literally true; `.claude/settings.local.json` is the same surface —
+hooks and permissions — and the file Claude Code reads LAST, so a rule written there outranks the one
+it overlays. `.claude/hooks/**`, `.claude/scripts/**` and both settings files are in the close's HARD
+list (`SLOT_EXECUTED_PATHS`) too, so the real diff is checked on BOTH lanes even if a permission rule
+fails to match — and `.claude/settings.local.json` needed its own entry there, because the matcher
+compares substrings and `.claude/settings.local.json` does not contain `.claude/settings.json`.
+`CLAUDE.md` is what the next reader (the next dispatched worker on this slot included) treats as law,
+and it is the one entry on the hard list the harness READS rather than executes: it is in
+`SLOT_EXECUTED_BASENAMES`, refused at close on BOTH lanes and blocked in the queue by guard 1c — see
+the list section for the two measured mechanisms (the local lane's AI reviewer reads it, and a failed
+attempt's copy is restored into the slot for the retry's executor to read). A skill under
+`.claude/skills/` and a tool under `scripts/` (outside `scripts/backlog/`) stay editable — that is
+the allowance the wider lane exists for, and `.claude/` read as INSTRUCTIONS is the gap the list
+section records by name.
+
+The frontier lane additionally denies the raw board write on BOTH surfaces it could reach —
+`Bash(backlog task edit:*)` / `Bash(backlog task edit *)` and the
+`mcp__backlog__task_{edit,create,complete,archive}` tools. The launch also passes
+`--strict-mcp-config` (T-24), the same flag the local lane and `reviewer.ts` already pass. Measured
+2026-09-09 (`claude -p "ok" --output-format stream-json --verbose --max-turns 1 --model haiku`,
+reading the `system`/`init` event): without the flag, the frontier worker's init event listed 101
+tools, 68 of them `mcp__*`. `mcp_servers` declared six entries (chrome-devtools, context7, backlog,
+spartan-ng-mcp, angular-cli, thesvg), but only four actually supplied a tool — chrome-devtools 29,
+backlog 20, spartan-ng-mcp 14, angular-cli 5, summing to the 68 — while context7 was `status:
+"failed"` and thesvg `status: "pending"`, neither contributing one. With the flag: 30 tools, 0 of
+them `mcp__*`, no declared servers at all. No rule in `frontier.settings.json` grants any `mcp__*`
+tool, so those 68 tools were loaded only to be denied by omission under `--permission-mode dontAsk`
+— the flag removes that dead weight at the source. The `mcp__backlog__task_*` deny rules above stay
+regardless: with the MCP servers no longer loaded at all, they are defence in depth rather than the
+active barrier, so the protection does not depend on a single flag. A write reachable by either
+route re-statuses the task or rewrites the criteria the close judges it against.
+
+**The frontier lane also denies eleven personal claude.ai connector servers.** At the time (T-3,
+2026-09-07), the frontier worker's init event had listed 152 tools, including
+`mcp__claude_ai_Gmail__*`, `mcp__claude_ai_Notion__*`, `mcp__claude_ai_Linear__*`,
+`mcp__claude_ai_Asana__*`, `mcp__claude_ai_Atlassian__*`, `mcp__claude_ai_Box__*`,
+`mcp__claude_ai_Canva__*`, `mcp__claude_ai_Figma__*`, `mcp__claude_ai_HubSpot__*`,
+`mcp__claude_ai_Intercom__*` and `mcp__claude_ai_monday_com__*` — loaded through the account login
+rather than through any settings file this launch reads, the same way `.mcp.json` "is not a settings
+source and loads regardless" (see Lane profiles above). That is a historical record of that one
+measurement, not a description of what loads today — a headless worker must never reach a person's
+mail or project-management tools regardless of what any given flag happens to load, so each
+connector's whole server is denied by name using the shape Claude Code documents for an MCP
+server-level spec (`mcp__<server>`, `mcp__<server>__*` or `mcp__*` remove every tool from the named
+server, or from all servers) — there is no glob that spans multiple distinct server names, which is
+why the eleven are spelled out rather than matched by a shared `claude_ai_` prefix. A deny rule
+holds regardless of source (see above), so it denies the connectors whichever mechanism loaded
+them.
+
+These eleven deny rules stay even now that the launch also passes `--strict-mcp-config` (T-24):
+they are deliberate defence in depth, so the protection does not depend on a single flag. Whether
+`--strict-mcp-config` would ALSO have kept these specific connectors from loading is UNVERIFIED —
+the T-24 probe measured above ran in a shell where an auth source (`ANTHROPIC_API_KEY` or another)
+had already disabled claude.ai connectors, taking precedence over the claude.ai login T-3 used, so
+T-24's probe could not observe these eleven loading or not loading either way; T-3 above is the
+only probe that ever observed them load. Do not read the T-24 measurement above (six declared
+servers, four of which supplied tools, none of them a personal connector) as evidence on this
+question; it ran in a different shell than T-3's.
+
+**The frontier worker gets a system prompt of its own.** It runs the harness, so it reads `CLAUDE.md`
+— which describes an INTERACTIVE session and says nothing about `worker-edit.ts`. Launched without
+one, the worker reached for `backlog task edit`, was denied, and finished with every acceptance
+criterion unticked, which the close's AC gate then failed it for, every time. `prompt.ts`'s
+`buildFrontierAddendum` renders `.claude/skills/catalyst-backlog/frontier-worker-addendum.md` — the
+template — into `.backlog/.dispatch/<id>/intento-N/frontier-addendum.md`, filling in the task id and
+the wrapper command bound to it, and the launch passes THAT path to
+`--append-system-prompt-file`. It carries only the facts `CLAUDE.md` cannot, because it describes an
+INTERACTIVE session: which directory it works in (its slot, named in full, with the main checkout
+named as the tree it must never touch — `{{SLOT_PATH}}`/`{{MAIN_CHECKOUT_PATH}}`, rendered per
+attempt like the wrapper command);
+
+**Both lanes' `--append-system-prompt-file` path is ABSOLUTE, under the main checkout.** The frontier
+lane's rendered addendum always was (it is written into `.backlog/.dispatch/…`); the local lane's
+static `worker-system-prompt.md` was a RELATIVE path until T-31 round 3, and `launch.ts` spawns the
+executor with `cwd` = the SLOT — so the worker's own brief was read from the tree the worker writes.
+`resolveWorkerSystemPromptPath` (`dispatch.ts`) resolves it against `repoRoot` instead, which closes
+the channel rather than watching it: `--bare` does not close it (the flag is explicit on the command
+line), and the two mechanisms that happened to bound it — the local lane's `.claude/**` deny and the
+`.claude/` entry in `LOCAL_FORBIDDEN_PATHS` — are exactly the "one mechanism is not enough" shape the
+hard list exists for.
+
+The invariant is ASSERTED where the argv is built (`buildLaunch`, round 4): a relative value throws and
+aborts the launch, which releases the slot and blocks the task. Resolving it in one of the two producers
+and asserting nothing at the point of use left the property untested — the two lanes compute the value
+differently, and the property belongs to the flag, not to either computation.
+
+The addendum also covers: running its test command EXACTLY as declared, with no pipes,
+`&&`, redirections or `cd` (T-3: a worker piped one through `grep`/`tail` and was denied — Claude
+Code evaluates each segment of a compound line separately, and the close runs the same bare command
+again anyway); the dispatcher already set the task `In Progress` and the worker never writes the
+status; the four wrapper flags and the fact that an unchecked criterion blocks the attempt; that the
+task's `path:` label is BINDING, not a recommendation — `path:sdd` runs the SDD flow
+(`/opsx:propose` then `/opsx:apply`, Automatic mode) before any code change, `path:direct` takes the
+direct path with the tier's gates, and `CLAUDE.md`'s interactive "recommend SDD and let the user
+choose" rule cannot apply headless, because there is no user to choose (T-3 measured a worker read
+that rule and implemented directly under `path:sdd` anyway, with no `openspec/changes/<name>` ever
+created); that a diff touching the security surface (`o-auth/`, `iam/`, a guard, `@Auth`, secrets or
+env config, a new public endpoint, an upload, a raw query, crypto/token/session handling) still gets
+a `/security-review` pass before finishing, reported in the task notes, exactly as the root
+`CLAUDE.md`'s security gate requires (the same T-3 run edited `backend/src/@app/iam/**` with no
+such pass — that gate has no person to trigger it headless either); a gate needing a person ends the
+run as `needs-guidance` (the close is what moves the task to `Blocked`); and no `git`, `gh`, or
+install.
+
+**Both prompts name the working directory, because the worker cannot infer it.** Measured (T-5,
+2026-09-07): the local executor's FIRST `Edit` targeted the MAIN checkout's copy of the file it had to
+change, not its slot's. It had taken the repository root off the `File: …/.backlog/tasks/t-5 …` line
+of the task block — the board lives in the main checkout — and nothing in the envelope said where it
+actually was. `Edit(./**)` denied it, correctly (the cwd is the slot), so the attempt spent turns
+being refused a path nobody had told it about. The local envelope now opens, immediately after the
+task text, with the slot path, "every path in this task is relative to it", the main checkout named as
+a tree it must never read, edit or run anything in, and the reason the confusion arose ("the board
+file path shown in the task block lives in the main checkout; do not treat its directory as your
+repository root"). The frontier addendum carries the same block. A permission rule is the barrier;
+this is what stops a worker walking into it.
+
+**Cost knob:** `ANTHROPIC_DEFAULT_OPUS_MODEL` is the value to change if Opus-priced frontier work
+gets too expensive — set it in `frontier.settings.json`'s `env` (currently empty) to redirect
+every internal "opus" alias to a cheaper model without touching `launch.ts`'s path-to-alias logic
+at all. On the local lane this same key is already set (to the local model id) for the reason
+above.
+
+## The close: what actually gates a PR
+
+**The first step is not mechanical at all: the board still has to describe the task that was
+launched** (`checkBoardIntegrity`). The worker can write to its own task for its whole run — it
+must, since the wrapper is its only channel for ticking criteria — so the close re-reads the task and
+compares it against the snapshot taken at launch. The wrapper is the BARRIER; this gate is the
+DETECTOR behind it, for the case where a permission rule silently fails to match anyway:
+
+- the status must still be `In Progress`. A worker that set itself to `Done` gets a maintenance
+  sweep reading a finished task nobody verified; one that set itself to `Queued` gets dispatched
+  again by the next pass while this close is still running. Anything else fails the attempt with
+  `status-changed-by-worker`.
+- the acceptance-criteria and Definition-of-Done TEXTS must be unchanged (`ac-tampered` otherwise).
+  Only the texts: the CHECKED state is exactly what the worker is supposed to change. The pre-PR
+  gate and the reviewer both judge the attempt against those criteria, so a criterion rewritten
+  into something the attempt can meet is a gate the thing under test authored itself.
+- the **title**, the declared **`Files to touch:`** and the declared **`Test command:`** must be
+  unchanged too, same `ac-tampered` reason. They are the rest of the contract the attempt is judged
+  against — the title names the PR, the declared files are the allowlist the scope check runs, and
+  the test command is what the triad executes — and all three are description text a board write can
+  reach. The message attributes the drift to "worker o persona" and lists the differences: a person
+  editing the board mid-attempt produces exactly the same drift, and the remedy is the same either
+  way (re-queueing re-takes the snapshot).
+
+It runs FIRST because every step after it trusts the board: the scope check reads the declared
+files, the triad the test command, the gate and the reviewer the criteria.
+
+### Forbidden paths, split by mechanism (T-31)
+
+The scope check (`checkScope`, `guards.ts`/`close.ts`) reads two path lists, split by ONE mechanical
+question: **does this file execute inside the slot during the attempt or the close?**
+
+- **`SLOT_EXECUTED_PATHS`** (hard, `guards.ts`) — the harness's own settings and its local overlay
+  (`.claude/settings.json`, `.claude/settings.local.json`), the hook and script directories the
+  harness runs after every edit (`.claude/hooks/`, `.claude/scripts/`), the version-control hooks the
+  close's own commit runs (`.husky/`), the package manifest, the lockfile and the installed
+  dependency tree the close runs Prettier, the barrels lint and the task's own test command with
+  (`package.json`, `pnpm-lock.yaml`, `node_modules/`), the board directory holding the criteria the
+  attempt is judged against (`.backlog/`), and the two script directories the close SPAWNS from
+  inside the slot: `scripts/packager/` (the `mirrorRegen` step runs `node
+  scripts/packager/publish.mjs` there, and that script GLOBS `monorepo.mjs`, `backend/*.mjs` and
+  `frontend/*.mjs` inside its OWN directory — derived from `import.meta.url`, so the slot's copy —
+  and spawns every match with the dispatcher's inherited environment) and `scripts/harness-rules/`
+  (the triad runs `pnpm hr:lint-barrels`, which the root `package.json` maps to `tsx
+  scripts/harness-rules/lint-barrels.ts`; the manifest being hard protects the script NAME, not the
+  file it points at). Refused on BOTH lanes, whether or not the task declared it — and blocked in the
+  QUEUE before a slot is ever taken, by guard 1c (`checkDeclaredSlotExecutedPath`), when a task
+  DECLARES one, including when it declares a DIRECTORY whose subtree contains one.
+
+  A declaration is read as reaching the list both when it lies UNDER a listed path and when it is a
+  DIRECTORY that contains one, with or without the trailing slash: `- .claude` and `- .claude/` both
+  reach `.claude/settings.json`. The containment direction matches on a segment boundary, so a bare
+  textual prefix is not a declaration of what it prefixes (`- package` names `package/`, not
+  `package.json`).
+
+  **Four** things the close reaches inside the slot are deliberately NOT on this list, recorded in
+  `openspec/changes/split-dispatcher-forbidden-paths/design.md` decision 1 rather than left silent:
+
+  - the slot's own `.git/` directory — its hooks really do run, but no `diff`/`status` output ever
+    reports a path inside it, so a list entry could never be enforced;
+  - `.claude/` read as INSTRUCTIONS on the frontier lane — `skills/`, `rules/`, `agents/`,
+    `commands/`. The executor reads them; no close step executes them. They are on neither list, so
+    a frontier attempt can rewrite its own skills and neither the pull request nor the `Blocked`
+    comment says so. This is the gap with a live self-instruction consequence, and it is wider than
+    it looks: a failed attempt's tree is pushed to `task/<id>` and RESTORED by the retry's
+    `checkout -B` (see the soft list below), so what attempt 1 writes there is what attempt 2's
+    executor boots reading. Widening the criteria into a soft PATH list for `.claude/` is a
+    follow-up;
+  - the drift-check workflow the mirror step parses — a worker can only cost itself the attempt with
+    it, never gain privilege;
+  - the task's declared `Test command:` — the standing hole this dispatcher has always had, and the
+    mechanism that makes "inert during the attempt" untrue of ANY path (below).
+- **`SLOT_EXECUTED_BASENAMES`** (hard, `guards.ts`) is the basename half of the hard list, and holds
+  one entry: `CLAUDE.md`, matched by file name at any depth and case-insensitively. Refused at close
+  on BOTH lanes and blocked in the queue by guard 1c, for two measured reasons. First, the local
+  close runs an AI reviewer over the attempt's own diff, spawned with `cwd` = the slot, and
+  `buildReviewerCommand` (`reviewer.ts`) does NOT pass `--bare` — the one flag that turns
+  instruction-file auto-discovery off, and one the reviewer cannot take, because under `--bare`
+  authentication is strictly `ANTHROPIC_API_KEY`/`apiKeyHelper` and `reviewerEnv()` strips every
+  `ANTHROPIC_*` key: an instruction file the local executor writes is read as instructions by the
+  judge of that same attempt. Second, on EITHER lane an instruction file written by attempt N is read
+  by attempt N+1's executor — the failure plan opens no pull request at all, so no PR mark is applied,
+  yet `saveWipAndPush` commits the whole slot tree to `task/<id>` and the retry's `prepareSlot` runs
+  `checkout -B task/<id> origin/task/<id>` and restores it. A mark that only exists on the green path
+  is not a control over a file that survives the failing one. Nothing else covers this file: the lane
+  settings grant `Write(./**)` with no `CLAUDE.md` deny, and `.claude/` is not a substring of
+  `claude.md`.
+- **`HUMAN_REVIEW_PATHS`** (soft, `guards.ts`) — the dispatcher's own sources (`scripts/backlog/`)
+  and the generator package (`packages/cli/`). A soft path is ADMITTED, not refused, and marks the
+  resulting pull request for human review (see "open-pr reuses the PR" below) instead of failing the
+  close. On the local lane a soft path still has to be DECLARED to pass — the undeclared-file check
+  is unchanged — and `scripts/backlog/` stays refused there regardless, because the local lane's
+  wider `scripts/` extra (below) still catches it.
+
+  **Soft does NOT mean inert**, and the two mechanisms that make it not mean that were measured
+  directly, so nobody has to rediscover them:
+
+  - a soft-list file CAN be executed inside the slot during the CLOSE. Admitting the diff at
+    `scope-check` is precisely what unlocks the rest of the success plan, and the triad's last step
+    spawns the task's own declared `Test command:` with `cwd` = the slot and the dispatcher's
+    inherited environment. `ALLOWED_TEST_SCRIPT` admits `test:backlog`, which the root manifest maps
+    to a runner over `scripts/backlog/**` — the SLOT's copies. This is not a privilege the soft list
+    grants: every dispatched task's test command already runs worker-written code in the slot the
+    same way (the fourth gap above). It is the reason the classification cannot rest on "nothing
+    runs it";
+  - a soft-list edit SURVIVES a failed attempt. `saveWipAndPush` commits and pushes the whole slot
+    tree to `task/<id>`, and the retry's `prepareSlot` runs `checkout -B task/<id>
+    origin/task/<id>`, which restores it into the slot. "The slot is hard-reset, so nothing survives
+    the attempt" holds only for a branch with no such push behind it.
+
+  What justifies the classification is narrower, and does hold: neither entry is read as INSTRUCTIONS
+  by any process (that is the difference from `SLOT_EXECUTED_BASENAMES` above), and neither is on the
+  path the dispatcher itself runs from — it runs from the MAIN checkout, the worker's board wrapper
+  and the board itself live only there, and the generator is never invoked by the close. So the
+  reachable outcome of editing either one is a test run that behaves differently, which costs the
+  attempt and is exactly what the mark sends a person to read.
+
+  The mark is not the only record. A FAILED close opens no pull request, so on that path the
+  `Blocked` comment names the soft-list files (`BlockDetails.humanReviewFiles`) — otherwise an
+  attempt that touched the dispatcher's own sources and then failed would leave no trace of having
+  done so. That holds for EVERY failure shape, and the common ones are the ones with no scope check
+  behind them: a MECHANICAL step's failure diverts a plan that already ran `scope-check`, so the files
+  are already known, while a SESSION-level failure (`needs-guidance`, a timeout, an exhausted budget,
+  a crash) plans straight to `save-work` and runs no mechanical step at all — and `board-check`, the
+  one mechanical step ordered BEFORE the scope check, diverts without one too. On any of those
+  `executeClose` asks the slot itself through the `leftoverFiles` runner (`collectLeftoverFiles`)
+  BEFORE the WIP commit rewrites the tree; the probe is keyed on "has anything classified this tree
+  yet", not on the plan's shape, so no future step ordering can reintroduce a divert that records
+  nothing.
+
+  That probe carries no verdict, but it does CLASSIFY — with `classifyChangedPaths`, the same function
+  `checkScope` reads, per lane. It returns two buckets, and the `Blocked` comment renders them as two
+  separate lines because they ask a person for opposite things: a soft-list leftover has to be READ,
+  and a refused one (a hard-list path, or the mirror output) has to be REMOVED before the retry
+  restores it. T-31 round 3 filtered the tree through the soft list alone, which reported a
+  `packages/cli/src/templates/…` path as a soft-list file the close admits — the one prefix refused on
+  both lanes — and said nothing at all about `.claude/settings.json`. A `git` failure in the probe is
+  logged rather than allowed to fail an already-failed close.
+- **The mirror output** (`packages/cli/src/templates/`, `MIRROR_OUTPUT_PREFIX` in `close.ts`) stays
+  refused on BOTH lanes regardless of the split — see "the CLI scaffold mirror is regenerated" below.
+  It is dispatcher-owned output the close itself writes, not a worker's writing surface, and it is
+  checked FIRST, before the two lists above: `packages/cli/src/templates/monorepo/scripts/backlog/
+  close.ts` matches both the mirror prefix and the soft `packages/cli/` pattern, and the mirror
+  prefix must win or a hand-written mirror edit would silently become a marked PR instead of a
+  violation.
+- **`LOCAL_FORBIDDEN_PATHS`** (`guards.ts`) is `SLOT_EXECUTED_PATHS` plus the local lane's own three
+  path extras — `.claude/`, `scripts/` and `.git/` — unchanged by the split. They are matched as
+  substrings, so `scripts/` also catches `scripts/backlog/dispatch.ts` even though that entry is soft
+  everywhere else: a soft path is not automatically admissible on the local lane, and being declared
+  was never sufficient for a local-lane extra either.
+
+A pull request marked for human review carries FOUR halves, deliberately unequal (design.md
+decision 8), and exactly ONE of them cannot fail:
+
+1. **the body section on a NEW pull request** — part of the `gh pr create` argv, so it either creates
+   the PR with the section or creates no PR at all. This is the unfailable half, and the reason the
+   mark does not rest on the three below;
+2. **the body section on a REUSED pull request** (a retry pushing to a branch that already has an
+   open PR): there is no `gh pr create` on that path to carry it, so the close applies it with its
+   own `gh pr edit --body` — best-effort;
+3. **the `harness-review` label**, a separate `gh pr edit` after the PR exists — best-effort;
+4. **the reviewer handle**, when `lanes.json` configures one, another separate `gh pr edit` —
+   best-effort.
+
+Best-effort means exactly this: the failure is logged with its reason and never fails the close,
+blocks the task, or discards the pull request. Halves 2-4 are best-effort; half 1 is not, because
+there is nothing left to fail once the PR exists with the body it was created with.
+
+The rewrite walks the body once and drops each dispatcher-authored region — every full marker pair,
+a trailing START with no END (a section a failed write truncated), and any stray END — writing the new
+section where the FIRST one was and keeping every byte between the regions. Round 3 spliced from the
+first START to the LAST END, which on a body holding TWO full pairs swallowed everything between them,
+a person's note included; that is the shape the pre-round-3 code produced on every retry, so open pull
+requests already hold it. The result always holds exactly one well-ordered pair, which makes the next
+rewrite the ordinary case again.
+
+The reuse rewrite READS the body first (`readPrBody`) and replaces only
+its own delimited section (`upsertHumanReviewSection`, marked with
+`<!-- dispatcher:human-review:start -->`/`…:end -->` HTML comments): `gh pr edit --body` is a full
+replacement, and these are by construction the pull requests a person was asked to read and
+annotate, so recomposing the body from the board destroyed every word that person had added. A body
+that cannot be READ is not overwritten at all — the rewrite is skipped and recorded, since with no
+idea what is there the safe move is to leave it. The file list any mark renders is capped on TWO
+budgets — the entry count (`MAX_MARKED_FILES`) and the total characters (`MAX_MARKED_LIST_CHARS`,
+with each path capped at `MAX_MARKED_PATH_CHARS`) — with a count of what it dropped, the same
+discipline `sanitizeCommentBody` carries for the worker-authored notes section beside it: the list
+comes from the attempt's own diff, and a wide refactor produces hundreds of entries in a public body
+and in the `gh` argv. Each path is also RENDERED rather than spliced verbatim (`renderMarkedPath`):
+paths reach the close straight out of `git diff -z`, so `<`/`>` are escaped — a filename spelling the
+section's own end marker would otherwise put a second marker inside the list and send the next
+rewrite's `indexOf` to the wrong offset — and control characters become `?`, so one changed file
+always renders as one entry. ONE rendering serves both channels, deliberately: the escapes render back
+as `<`/`>` on GitHub and show up literally (`&lt;`) in a `Blocked` comment read through
+`backlog task view --plain`, and a second channel-aware renderer would mean two code paths over
+worker-supplied bytes for a cosmetic gain — the escaped spelling still identifies the file. The
+label is a SEPARATE call from `pr create` on purpose — a label the repository does not have would
+otherwise fail the PR creation itself — and separate from the reviewer call too, so a rejected
+reviewer never takes the label down with it. The reviewer's rejection is the EXPECTED case, not the
+exception: `gh` refuses a reviewer that is the pull request's own author, and the dispatcher opens
+every PR as the same account — so `harnessReviewer` ships unset in `lanes.json`, and its absence is
+recorded once rather than treated as an error.
+
+The mechanical triad is **scoped to the attempt's own changed files** — the union of
+`git diff --name-only -z <base>...HEAD` and
+`git status --porcelain -z --untracked-files=all` — `-z` on BOTH halves, because either line format
+otherwise quotes and C-escapes a path holding a space, a quote, a backslash, a newline or a
+non-ASCII byte, and the string then compared against the path lists is not the path on disk. The
+measured consequence: a quoted `packages/cli/src/templates/…` misses the anchored mirror prefix while
+still matching the unanchored soft `packages/cli/` pattern, so a hand-written mirror edit would be
+admitted and merely marked — the mirror-first precedence inverted. `-c core.quotepath=false` was the
+first fix and it is not enough: that option governs only the non-ASCII half of the class. On the
+status side a rename is one entry carrying two NUL-separated paths, and only the new one is a file
+the attempt produced. The mirror prefix itself is matched case-insensitively, like every sibling
+matcher, since a casing variant names the same file on this repo's filesystem:
+
+- **Prettier**, two runs per workspace that ships it (`backend/`, `frontend/`, `packages/core-back/`,
+  `packages/core-front/`): `pnpm --filter <pkg> exec prettier --write --ignore-unknown <files>`, then
+  the same with `--check`. design.md decision (h) puts the format hook in the close "where a
+  deterministic script ENFORCES them" — a bare `--check` only reports, and the executor is never
+  asked to run Prettier, so an indentation nit failed a whole attempt over something the close can
+  fix in place. The `--check` after the write is not redundant: it is what proves the write actually
+  took (a syntax error makes Prettier rewrite nothing). Prettier is NOT a root dependency here — `npx
+  prettier` at the repo root exits 127 — so a repo-wide run was a check that could never pass. A
+  changed file outside those four workspaces (`scripts/`, `.claude/`) has no formatter to run and is
+  reported in the log, not silently treated as formatted. `--ignore-unknown` is measured (T-6.1,
+  first real frontier dispatch): a `.sql` file with no inferrable parser otherwise exits Prettier 2
+  ("No parser could be inferred"), failing the whole triad over a file Prettier was never going to
+  format. A drizzle-kit migration folder
+  (`backend/src/database/migrations/drizzle/<folder>/{migration.sql,snapshot.json}`) is excluded
+  from BOTH runs entirely rather than merely ignored: it is tool OUTPUT, not hand-written code, the
+  repo's shipped `snapshot.json` files are not Prettier-formatted (measured: `--check` warns on every
+  one, 432 KB each), and a `--write` would turn a generated artifact into a huge noise-only diff.
+- **Barrels lint**, `pnpm hr:lint-barrels <files>`, over the changed `.ts` files under the roots
+  HR-BARRELS actually governs. Scoped for the same reason: `pnpm hr:lint-barrels` with no arguments
+  sweeps the whole repo, which is red on `main` today for pre-existing violations in generated
+  frontend code — an unscoped run would blame every attempt for someone else's diff.
+- **The task's own `Test command:`**, which is MANDATORY — guard 1 refuses to dispatch a task that
+  declares none, on either lane, and the pre-PR gate refuses to pass one whose "scoped tests pass"
+  item is still unticked (the triad ticks it only when a test actually ran and passed). The accepted
+  grammar is the repo's own convention and nothing else:
+
+  ```
+  pnpm [--filter <pkg> | --dir <relative-path>] [run] <test | cli:test | test:*> [args…]
+  ```
+
+  Naming `pnpm` was never the permission: `pnpm dlx <package>` is the same fetch-and-execute `npx`
+  is refused for, and `pnpm add`/`install`/`exec`/`-C` reach just as far outside this repository. So
+  the SCRIPT is allowlisted too, a `--filter` value must be a plain package name (never another
+  flag), and the line may contain no shell metacharacter. `--dir` is the alternative selector, for
+  `packages/cli` — deliberately NOT a workspace member (root `CLAUDE.md`, D8), so `--filter` matches
+  nothing there; its value must be a RELATIVE path with no `..` segment, because a test command may
+  only reach inside the slot it runs in. The command is spawned directly, never through a shell.
+
+  A line that breaks any rule is refused **before dispatch**: guard 1 runs the same
+  `resolveTestCommand` the triad does and blocks the task with the refusal and the offending line,
+  so nothing is spawned at all. The validator lives in `guards.ts` for that reason — pre-launch
+  validation is upstream of the close, which already reads that module for its security-path list.
+  Reaching the close with a refused line means the board changed after launch, and the triad fails
+  it there with `test command no permitido`.
+
+The command that runs is the one SNAPSHOTTED at launch (`Task.testCommand`, parsed alongside
+`Files to touch:`), never re-read from the board at close time — the worker can write to its own
+task for its whole run, so a close that re-read the board would run whatever the thing under test
+decided it should be verified with.
+
+Prettier and the barrels linter are both run only over files that still EXIST in the slot. A file the
+attempt deleted is still a changed file, and neither tool can read a path that is correctly gone.
+Both receive their file list after a `--` separator, so a changed path beginning with a dash is read
+as a file and not as a flag.
+
+**Then the CLI scaffold mirror is regenerated, when — and only when — the attempt touched a root the
+packager reads.** `scripts/packager/publish.mjs` mirrors `backend/`, `frontend/` and much of the
+monorepo root into `packages/cli/src/templates/{backend,frontend,monorepo}`, and CI's
+`Check mirror <-> source drift` fails any PR whose committed mirror no longer matches its sources.
+A dispatched worker cannot satisfy that gate itself: the MIRROR OUTPUT
+(`packages/cli/src/templates/`) stays refused on both lanes regardless of the split (T-31) —
+`packages/cli/` itself is soft now, so a worker may legitimately edit the generator, but never its
+own generated mirror — so before this step existed, **any dispatched task touching a mirrored root
+could never pass CI on its own** (measured: PR #96, task T-3, which edited
+`backend/src/@app/iam/**` and `frontend/src/app/domains/admin/apps/iam/**` and failed the gate with
+"The committed CLI scaffold mirror is out of date").
+
+- **Which roots count** is read at close time from the slot's own
+  `.github/workflows/cli-template-drift-check.yml` — its `paths:` filter, minus `packages/cli/**`
+  (packager OUTPUT, not a source root). That list is not copied into the dispatcher, because
+  `scripts/packager/drift-check-paths.test.mjs` already fails when a `copyMonorepo()` glob is
+  missing from it: reading the file that is kept in lockstep is one source of truth, a second
+  hardcoded copy would be a third thing to drift.
+- **It is conditional.** `publish.mjs` is a repo-wide copy; running it on an attempt that changed
+  only a `cliter/*.aurora.yaml` would spend that cost and put a several-thousand-file mirror diff in
+  front of the reviewer for nothing.
+- **Where it sits is the whole design.** AFTER the triad, because `prettier --write` rewrites the
+  attempt's own source files — a mirror copied before it would be a byte-copy of the unformatted
+  source and stale the moment the triad ran. BEFORE the reviewer and the pre-PR gate, because the
+  reviewer judges the diff that will actually be pushed. And AFTER the scope check, which is what
+  keeps the MIRROR OUTPUT forbidden **to the worker**: the scope verdict is taken over the pre-regen
+  file set, so a mirror path the worker wrote by hand is still a scope violation, and the
+  dispatcher-owned output only appears once the judging is done. There is no exemption in
+  `checkScope` at all — the ordering is the exemption.
+- The regenerated files stay in the working tree and travel in the attempt's own commit
+  (`open-pr` already runs `git add -A`).
+- **A failing packager fails the attempt** (`mirror-regen-failed`, work saved then `Blocked` like
+  any other step), with the child's stderr folded in through `describeExecFailure` — an
+  `execFileSync` throw says only "Command failed: node scripts/packager/publish.mjs" on its own.
+- **A repo with no drift-check workflow skips the step entirely.** A generated project is that case:
+  `copyMonorepo()` ships `scripts/backlog/**` but neither `.github/**` nor `scripts/packager/**`, so
+  there is no mirror to keep and no gate to satisfy. A workflow that IS there but whose `paths:`
+  list does not parse fails instead — unknown roots make the question unanswerable, and an
+  unverifiable answer is the one thing this close refuses to trust.
+
+The reviewer step (local lane) is spawned isolated from the harness — `--strict-mcp-config` keeps
+every MCP server out, `--disable-slash-commands` removes the command surface, `--setting-sources
+user` keeps the project's 42 allow rules out — plus an explicit deny list covering `Edit`, `Write`,
+`NotebookEdit`, the push and PR commands, `WebFetch` and `WebSearch`: it judges, it never writes.
+
+It is the one dispatched process that does NOT get `--bare`, and that is a correctness fix rather
+than a relaxation. Measured on `claude --help`: under `--bare`, "Anthropic auth is strictly
+ANTHROPIC_API_KEY or apiKeyHelper via --settings (OAuth and keychain are never read)". The executor
+authenticates against LM Studio through the lane's own `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN`;
+the reviewer runs on the ACCOUNT with all of that stripped, so under `--bare` it had no credential
+left at all — and a reviewer that cannot start fails closed, blocking every local-lane attempt.
+`--setting-sources user` is the narrowest value the flag accepts (it takes a comma-separated list of
+`user`, `project`, `local`; an empty one is not in the grammar), and it is also where an
+`apiKeyHelper` lives.
+
+Its environment is `reviewerEnv`, not `sanitizeInheritedEnv`: it drops every `ANTHROPIC_*` key plus
+`CLAUDE_CODE_SUBAGENT_MODEL`, and applies the same `isCredentialEnvKey` filter the worker env
+applies, with NO exception — the reviewer reads a diff and writes a verdict, so `GITHUB_TOKEN`,
+`NPM_TOKEN` and the SOPS/cloud keys are reach it has no use for. **The reviewer authenticates with
+the machine's claude.ai login; a stale `ANTHROPIC_API_KEY` in the dispatcher's shell would otherwise
+take precedence and break it.** That key used to be kept, on the reading that it is the account
+credential rather than a lane knob. Measured wrong (T-5, 2026-09-07): the reviewer failed to start
+at all (`El revisor no se pudo ejecutar: … claude -p …`), and a probe with the reviewer's own flags
+returned `terminal_reason: api_error`, 0 tokens, and stderr "claude.ai connectors are disabled
+because ANTHROPIC_API_KEY or another auth source is set and takes precedence over your claude.ai
+login". An inherited key can only ever REPLACE the credential this process needs, never supply one:
+a machine that really authenticates by API key declares it in the settings source the reviewer loads
+(`--setting-sources user`, where an `apiKeyHelper` lives), not in the shell the dispatcher happens to
+be started from. The overlay half of the sweep is unchanged in effect — `ANTHROPIC_BASE_URL`,
+`ANTHROPIC_AUTH_TOKEN` and the model aliases still go, so a weak local executor can never review
+itself.
+
+**A failed reviewer subprocess reports its stderr.** `execFileSync`'s own `error.message` is
+"Command failed: claude -p …" and nothing else, so the T-5 `review.md` recorded exactly that while
+the auth error above sat in the stderr nobody rendered. The runner now wraps the spawn in
+`describeExecFailure` (the same renderer the dispatcher's `backlog`/`git` writes use), so the step's
+`Blocked` comment and `review.md` both carry the child's own message. The diff it judges is collected with an intent-to-add first (`git add -N -A -- .`), then
+`diff <base>...HEAD` plus `diff HEAD`. The intent-to-add is what makes the second half honest: no
+`git diff` under any flags renders an UNTRACKED file, and on a dispatched attempt every created file
+is untracked — the executor may not run git, so nothing ever staged them. Without it the reviewer
+was handed a diff with every new file silently missing and approved code it never saw. (Side effect,
+harmless: the slot's index is left carrying those entries, and every path that continues from there
+runs `git add -A` over the whole tree anyway.) It is then fenced between randomized
+`===== BEGIN/END UNTRUSTED DIFF <nonce> =====` sentinels and declared data, because that text was
+written by the model under review and can address the reviewer directly. The verdict is only read AFTER a `REVIEW COMPLETE` line the
+reviewer emits itself — a `VERDICT: pass` quoted from the diff is not a verdict — and a reply with
+no marker, or no verdict after it, fails closed.
+
+The **pre-PR gate** (`evaluateAcceptanceGate`) judges ACCEPTANCE CRITERIA: every one must be checked,
+and a task that declares none at all fails ("la tarea no declara criterios de aceptación" — there
+would be nothing to verify the work against). Definition-of-Done items split in two: the four project
+defaults in `.backlog/config.yml` are dispatcher-owned and the close ticks them itself once the step
+that PROVES each one has passed (the triad ticks "scoped tests pass" and "Prettier and barrels lint
+pass", the gate ticks "every acceptance criterion is checked", `open-pr` ticks "PR opened to main or
+to the parent branch"); any OTHER unchecked DoD item is a human duty and fails the gate. Ticking is by
+item TEXT, never by a guessed index — the `#N` the CLI prints shifts as soon as a task adds one item
+of its own.
+
+One dispatcher-owned item the gate still judges: **"scoped tests pass"**. The triad ticks it ONLY
+when a test check actually ran and passed, so an unticked one at the gate means nothing tested this
+attempt — and excluding it as "dispatcher-owned" let exactly that reach a PR with the box ticked by
+nobody and verified by nothing. The gate now fails with `la tarea no declara Test command`.
+
+Nothing used to TELL the worker to tick anything, either. The operating envelope now renders each
+criterion with its `#N` and the exact wrapper command (`<worker-edit> --check-ac <N>`, the same
+string the permission rule was built from — passed in rather than composed twice, so the command the
+prompt prints cannot drift from the one that is granted), requires the evidence in `--append-notes`,
+and says that leaving one unchecked blocks the attempt — the same instructions the worker system
+prompt carries.
+
+**`open-pr` reuses the PR already on the branch.** A retry pushes to the same `task/T-nn`, so the
+previous attempt's PR is still open and that push already updated it — and creating a second one is
+impossible (`gh` refuses with "a pull request for branch … already exists"), which failed a close
+whose code was on the remote with a perfectly good PR to point at. The step asks first
+(`gh pr view <branch> --json url,state`) and reuses an `OPEN` one, logging "PR existente
+reutilizada". Only "no pull requests found" counts as absence: a `CLOSED`/`MERGED` PR is not
+reusable (pushing again would leave the attempt with no open PR and the DoD item a lie), and any
+other `gh` failure — a revoked token, no network — propagates instead of being read as an absent PR,
+because swallowing it would create a duplicate the moment `gh` recovered.
+
+The dispatcher's own `gh` calls — this `gh pr view`/`gh pr create` pair, and `maintenance.ts`'s
+merged-PR poll — run with an env stripped of `GITHUB_TOKEN`/`GH_TOKEN`/`GH_ENTERPRISE_TOKEN`/
+`GITHUB_ENTERPRISE_TOKEN` (`dispatch.ts`'s `ghEnv`), so `gh`'s own keyring login (`gh auth login`)
+is what authenticates. Without it, a stale token in the dispatcher's shell would otherwise take
+precedence over that login and return `HTTP 401: Bad credentials` right here at `open-pr` — measured
+(T-5, 2026-09-07): the reconciler process inherits whatever `GITHUB_TOKEN` the developer shell that
+launched it exports, and `gh` prefers an env token over the keyring even when the keyring login is
+valid.
+
+**`open-pr` marks the pull request when the scope check reported soft-list files** (T-31) — the
+`humanReviewFiles` `scopeCheck` captured earlier in the run, never recomputed here (see "Forbidden
+paths, split by mechanism" above for why). Applies on BOTH branches above, the reuse and the create:
+a `gh pr edit <branch> --add-label harness-review`, then, when `lanes.json` configures a handle, a
+second `gh pr edit <branch> --add-reviewer <handle>`. Each is its own call, wrapped so a failure is
+logged with `describeExecFailure` and never fails the close. On the REUSE branch it also applies the
+mark's BODY half with a third call, `gh pr edit <branch> --body <body>`: the create branch carries
+that section inside `gh pr create --body`, and the reuse branch has no create call to carry it, so
+without this the reused pull request would name no soft-list file at all and the whole mark would
+rest on the two calls that are allowed to fail. That body is the CURRENT one, read back with
+`readPrBody` and passed through `upsertHumanReviewSection` so only the delimited review section
+changes — a recomposition from the board would replace the whole body and take a reviewer's own notes
+with it. An unreadable body is left alone and the skip is recorded.
+
+A close that FAILS never reaches this step at all (the failure plan is `save-work` then `block`), so
+there the leftover files are named in the `Blocked` comment instead — `formatBlockComment` renders
+`BlockDetails.humanReviewFiles` and `BlockDetails.forbiddenFiles` as two lines, which `executeClose`
+carries over from the scope-check result when a mechanical step failed, and reads from the slot itself
+(the `leftoverFiles` runner) on every divert with no scope check behind it: a plan that started at
+`save-work`, and a `board-check` failure.
+
+That comment is composed under an explicit priority, because `sanitizeCommentBody` truncates from the
+END and the last line is the only actionable one: the reason, the branch/compare/log pointers and the
+`whatToDo` line are never budgeted; the two leftover lines are capped against the room those leave
+(and by `MAX_MARKED_FILES`/`MAX_MARKED_LIST_CHARS`); the worker's own report is capped against what
+remains, since it is the longest part and survives in full in the `run.log` the comment names two
+lines above. Round 3 gave the list a fixed 2000-char budget — half the comment's own 4000 — and
+measured a comment of exactly 4000 chars with `whatToDo` cut off.
+
+## Failure path: work is saved before anything is released
+
+On any failure the close saves first (`git add -A` + a `chore(<task-id>): wip dispatcher auto-save`
+commit + push) and only then blocks and releases.
+
+**Every dispatcher-owned commit runs `--no-verify`**, and that is a safety property rather than a
+convenience: a slot's `.husky/` hooks are files in the working tree the WORKER has been writing in,
+so committing its work through them would execute code the model under dispatch authored, with the
+dispatcher's 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, in the same lowercase-scope
+Conventional Commit shape, and `close.test.ts` runs them through this repo's real commitlint.
+
+If that push FAILS, the slot is not released. It is flagged `heldForRecovery` in `slots.json`, which
+means:
+
+- no acquisition will ever pick it (its `reset --hard` would delete the only copy of the work);
+- the dead-PID sweep and the orphan sweep both skip it;
+- every later maintenance pass retries the push, and on success clears the flag, releases the slot
+  and appends "push recuperado" to the task. That last note is a COMMENT, not a status write, unless
+  the task is still sitting in `Blocked`: a person may have released it to `Queued` (or to `To Do`)
+  while the push was pending, and re-asserting `Blocked` would drag it straight back out.
+
+That retry is bounded at **three attempts** (`MAX_RECOVERY_ATTEMPTS`, counted on the slot as
+`recoveryAttempts`). A push that failed three times is failing for a reason no further retry
+addresses — no remote, a rejected non-fast-forward, a broken worktree — and retrying forever keeps
+one of three slots out of the pool while saying nothing about it. At the cap the pass notifies,
+comments `recuperación del push agotada: rescata a mano la rama task/<id> en <slot path>` — naming
+the exact command that gives the slot back, `pnpm backlog:dispatch -- --release-slot <slot name>`,
+since nothing automatic will take it back — keeps the slot held, and stops retrying: a person
+decides from there. See "Releasing a `Blocked` task" for that step.
+
+While a slot is held for THIS task's recovery, guard 6 reports `push-pending` rather than
+`no-free-slot` — only the first says why re-queueing changes nothing until the retry succeeds.
+
+The same rule governs a worker that died without closing: the sweep kills it (its whole process
+group) if it is still running, saves its branch, and only then releases — leaving a `Blocked` comment
+that says which pid died, on which branch, and whether the work survived.
+
+`Blocked` comments are sanitized before they are posted: `backlog task edit --comment` rejects a body
+containing a standalone `---` line outright (exit 1, nothing written), and a reviewer verdict embeds
+exactly that. The body is also capped at 4000 characters, with the rest left in `review.md`.
+
+## Where board state lives (`BACKLOG_CWD`, `auto_commit: false`)
+
+The board (`.backlog/tasks/`, `.backlog/config.yml`) lives ONLY in the main checkout, never in a
+slot. Every dispatcher process — the reconciler itself and every `backlog` CLI invocation it
+makes — is pointed there via `BACKLOG_CWD=<main checkout>`, resolved with
+`findRepoRoot`/`scripts/_catalog-runtime/repo-root.ts`. A slot never touches its own `.backlog/`
+copy — and that is now ENFORCED rather than assumed: both lane settings deny `Edit`/`Write` on
+`.backlog/**`, and `checkScope` reports a change there as a violation on both lanes. It used to
+strip `.backlog/`-prefixed paths from the diff instead, so a worker that did write there rewrote
+the criteria the close judges it against, invisibly.
+
+Keeping the board in one place is deliberate, not an oversight — three worktrees
+independently writing the same task files would be a merge-conflict generator, which is why
+`check_active_branches: false` in `.backlog/config.yml` too (cross-branch resolution would read
+stale copies out of three slots that never see each other's writes).
+
+`.backlog/config.yml` sets `auto_commit: false`, which is the opposite of what you might expect
+from a tool that manages its own state file. Backlog.md's own auto-commit writes messages like
+"Create task T-2" — not a Conventional Commit — and this repo's `commit-msg` hook (husky +
+commitlint) rejects them; worse, with `bypass_git_hooks: false` the rejection is not a loud
+failure, the task file is never persisted at all (silently losing the write). So instead, the
+reconciler's maintenance pass (`maintenance.ts`, `commitBacklogChanges`) commits any pending
+`.backlog/**` change itself, in the main checkout, with a Conventional Commit message —
+`chore(backlog): sync board state (T-12 -> Done)` for a single transition,
+`chore(backlog): sync board state (4 transitions)` with the list in the commit BODY for several
+(commitlint caps the header at 100 characters). Like every other dispatcher-owned commit it runs
+`--no-verify` (see "Failure path" above), and it carries a trailing `-- .backlog` **pathspec**:
+staging adds to the index but does not narrow what a commit takes, so without it anything a person
+already had staged in the main checkout rode along inside an unattended machine commit. The message
+shape is held by `buildBoardCommitMessage`'s own tests instead of by the hook. A rejected board commit is logged and the pass continues: the slots it already released and the work it already saved
+must not be undone by a bookkeeping failure.
+
+## Trigger wiring
+
+`.backlog/config.yml`'s `onStatusChange` (single-quoted so YAML preserves `$TASK_ID` literally,
+letting the shell expand it):
+
+```yaml
+onStatusChange: 'mkdir -p .backlog/.dispatch; nohup npx --loglevel=error tsx scripts/backlog/dispatch.ts >> ".backlog/.dispatch/$TASK_ID.log" 2>&1 < /dev/null &'
+```
+
+The redirect APPENDS (`>>`), like the launchd launcher's. One task's log is written by every
+reconciler run that task's status transitions start — `Queued`, then the close's move out, then a
+release after `Blocked` — and a truncating `>` threw away the previous run's output each time,
+which is the output someone reading a failed dispatch needs.
+
+The `mkdir -p` is what makes a FRESH CLONE work: `.backlog/.dispatch/` is gitignored, so it does not
+exist until something creates it, and `>> "..."` cannot create its own target directory — a
+redirection resolves its target BEFORE anything after it runs. That ordering is also why the
+`mkdir` is joined to `nohup` with a **semicolon, not `&&`**: `&&` makes the two commands one list,
+and `&` backgrounds the WHOLE list — its subshell then holds the caller's own stdio open for as
+long as the reconciler runs, because the shell that opened the log file for the redirection is the
+same one `&` puts in the background. A bare `;` runs `mkdir` in the FOREGROUND (near-instant, no
+redirection to open early) and only backgrounds the `nohup npx ...` command that follows —
+so `&` detaches exactly the long-running part. Measured: the `&&` shape returns in ~3s (however
+long the dispatched run takes to get its own stdio open); the `;` shape returns in ~0.01s. The
+`< /dev/null` alongside the nohup command's own `>>`/`2>&1` is what lets Backlog.md see every one
+of its pipes close AT ONCE — it holds the task lock until then — rather than waiting on stdin to be
+inherited from a caller that never closes it.
+
+The `nohup ... &` is REQUIRED, not an optional optimization: Backlog.md runs this callback
+**synchronously** and blocks the caller (CLI, MCP, or web UI) until it returns. Measured: a
+detached callback returns control in ~0.13s regardless of a 30s background job; a non-detached
+one blocks for the job's full duration. Without `nohup ... &`, moving a task to `Queued` would
+freeze whoever moved it for the entire dispatched run.
+
+`onStatusChange` never fires on task creation and never fires on a merge — it is a hint, not a
+guarantee. Two things cover what it misses: the `launchd` timer below (a missed or crashed
+callback), and the maintenance pass's `gh` poll (a merge that happened outside any callback).
+Every trigger runs through the identical idempotent pass, so a missed or duplicated event
+self-heals on the next one.
+
+### Anti-loop: a dispatcher-owned write must not spawn its own pass
+
+Every `backlog task edit` this reconciler runs against ITSELF — `dispatch.ts`'s `realBacklog`
+(`setStatus`, `comment`) and `tickOwnedDod`'s `--check-dod` — carries `BACKLOG_DISPATCH_ACTIVE='1'`
+in its `env`, exactly like a worker's own writes through `worker-edit.ts` already do. That edit's
+`onStatusChange` callback inherits the sentinel from the `backlog` CLI child it fires from, so the
+nested `dispatch.ts` invocation it spawns can tell a dispatcher-owned write apart from a genuine
+human one.
+
+`main()` checks this BEFORE resolving `BACKLOG_CWD` or running any maintenance at all
+(`entry.ts`'s `isDispatcherOwnedCallback`: `TASK_ID` and `NEW_STATUS` present, and
+`BACKLOG_DISPATCH_ACTIVE === '1'`) — logs one line and exits 0, no pass at all. This is a stronger
+guard than `shouldDispatchFromCallback`'s: that one only ever suppressed task SELECTION, while
+maintenance (including a `.backlog` git commit) ran unconditionally underneath it regardless. A
+callback with no sentinel (a human moving a task) and the launchd timer / `gh`-poll trigger (no
+`TASK_ID` at all) are unaffected and still run their normal pass.
+
+Measured (2026-09-07, T-5's first real e2e run): the reconciler's own `-s In Progress` edit fired
+a nested pass with no sentinel at the time, which ran its OWN maintenance sweep — including its own
+`.backlog` git commit — concurrently with the pass that made the write and was still mid-dispatch
+in the SAME checkout; that race is what failed `git add .backlog` with exit 128, and the
+dispatcher's own edits that followed failed too. Every `backlog`/`git` collaborator this file owns
+also now captures stderr (`stdio: ['ignore', 'pipe', 'pipe']`, previously silenced) and renders it
+through `describeExecFailure` before throwing or logging — the same run left every one of those
+failures as exit 1 with `stderr: null`, so the actual cause never reached the `Blocked` comment or
+the log at all.
+
+Backlog.md holds the task lock while `onStatusChange` runs; the callback detaches its stdio so it
+returns at once, and the dispatcher retries a busy-board write six times with linear backoff.
+
+The sentinel is not pid-bound by design: it is an env var, not a lock tied to the process that set
+it. A human shell that exported `BACKLOG_DISPATCH_ACTIVE=1` (to silence the callback while
+debugging, say) would have every subsequent `backlog task edit` it runs — including a genuine
+status change a person made — ignored by the callback exactly like a dispatcher-owned one, with
+only one log line in that task's `<id>.log` to say why nothing dispatched.
+
+## npm scripts
+
+| Script | Command | Use |
+| --- | --- | --- |
+| `backlog:dispatch` | `tsx scripts/backlog/dispatch.ts` | Run one reconciler pass manually (what every trigger ultimately invokes) |
+| `backlog:dispatch -- --release-slot <name> [--force]` | same script, one flag | Rescue a slot held for push recovery: detach it, drop its lock and clear the hold. Runs NO pass, takes the reconciler's single-flight lock while it works, and REFUSES (exit 2) a running pass or a slot with a live worker unless `--force` — see "Releasing a `Blocked` task" |
+| `backlog:watch` | `tsx scripts/backlog/watch.ts` | Tail a running attempt's log, or list busy slots — see below |
+| `test:backlog` | `node --import tsx --test "scripts/backlog/**/*.test.ts"` | Run every dispatcher unit/contract test |
+
+## Observability: `pnpm backlog:watch`
+
+```bash
+pnpm backlog:watch T-12   # tails the human-rendered run.log of T-12's current attempt
+pnpm backlog:watch         # no id: lists busy slots (name, lane, taskId, pid) from slots.json
+```
+
+`watch.ts` only reads — it never writes board state, a lock, or a slot. The log it tails is the
+SAME `run.log` `attempt.ts`'s sink writes per attempt
+(`.backlog/.dispatch/<TASK_ID>/intento-<N>/run.log`), rendered through the shared `render.ts` so a
+live tail and a post-hoc read of the same file show identical lines. The attempt directory is
+created before the worker starts, so `backlog:watch` works from the first second of a run.
+
+## Installing the launchd recovery timer
+
+The `onStatusChange` callback in `.backlog/config.yml` is the primary trigger; the launchd agent
+below is the recovery path for a trigger that never fires (a missed status change, a crash before
+the callback ran). Both invoke the same `scripts/backlog/dispatch.ts` entry point.
+
+1. Copy the template and replace the **three absolute paths** in the copy — the template ships this
+   machine's, and launchd does not expand `~` or source a login shell's `PATH` (so no nvm shim):
+
+   | Where | What to put there |
+   | --- | --- |
+   | inside the `ProgramArguments` `/bin/sh -c` string | your `which npx` |
+   | `WorkingDirectory` | your main checkout |
+   | `StandardOutPath` / `StandardErrorPath` | `<your main checkout>/.backlog/.dispatch/launchd.log` |
+
+   Two log files, and they are not interchangeable: `launchd.log` holds the LAUNCHER's own output
+   (a failing `mkdir`, a failing `nohup`), and `reconciler.log` — the `>>` redirect inside the
+   `sh -c` string — holds the detached reconciler's. A single file mixed a tens-of-minutes pass into
+   the launcher's one-line runs and made neither readable.
+
+   ```bash
+   cp scripts/backlog/dev.aurora.backlog-dispatch.plist \
+     ~/Library/LaunchAgents/dev.aurora.backlog-dispatch.plist
+   ```
+
+   The command itself is `sh -c 'mkdir -p .backlog/.dispatch; nohup <npx> --loglevel=error tsx
+   scripts/backlog/dispatch.ts >> .backlog/.dispatch/reconciler.log 2>&1 < /dev/null &'` — a short
+   LAUNCHER that detaches the reconciler and **exits**, not the reconciler itself.
+
+   That is the load-bearing part. launchd tracks the pid of what it starts and will not start a
+   second instance while that process is alive, and the reconciler lives as long as its worker —
+   tens of minutes. Running it directly (or under `exec`, which keeps its pid as the tracked one)
+   silenced the timer for the whole length of every dispatch, exactly when a `StartInterval`
+   recovery pass matters most. Backgrounded, launchd sees a process that exited in milliseconds and
+   is free to fire again on the next interval — the same way the `onStatusChange` callback detaches
+   its own invocation.
+
+   Two consequences of detaching, both handled in the template: the log directory is gitignored and
+   therefore absent on a fresh clone, and launchd opens `StandardOutPath` itself without creating
+   missing parents — so the first run on a new machine produced no log at all, including no record
+   of why, hence the `mkdir -p`; and the detached process is no longer launchd's child, so its own
+   output is redirected into that same log explicitly rather than inherited. That `mkdir -p` runs
+   BEFORE the `>>` opens `reconciler.log`, and is joined to `nohup` with a **semicolon, not `&&`** —
+   `&&` would make `mkdir; nohup ...` one list, and `&` backgrounds the WHOLE list, so the shell that
+   opened the log file stays foregrounded for as long as the reconciler runs (measured ~3s vs the
+   `;` shape's ~0.01s). The `< /dev/null` alongside the nohup command's own `>>`/`2>&1` is what lets
+   whoever is waiting on this callback (Backlog.md holds the task lock until then) see every one of
+   its pipes close at once, instead of blocking on a stdin nothing ever closes.
+2. The one manual prerequisite: `gh auth login` on the machine that runs the dispatcher, once. The
+   dispatcher's own `gh` calls (`open-pr`'s reuse check and create, the maintenance sweep's merged-PR
+   poll) deliberately run without an inherited `GITHUB_TOKEN`/`GH_TOKEN` — see "`open-pr` reuses the
+   PR already on the branch" above — so that keyring login is the only credential they ever get.
+   Otherwise there is no other manual setup. `.backlog/.dispatch/` is created by the `onStatusChange` callback
+   and by `dispatch.ts` itself, and the three worktree slots are provisioned on demand the first time
+   a task acquires one (`fetch origin --prune`, `worktree prune`, `worktree add --detach
+   origin/main`, `scripts/worktree-link.sh`, `pnpm install`) — so the first dispatch into a fresh
+   slot takes as long as a full install and every later one does not. The `worktree prune` is what
+   makes that recovery actually work: a slot directory deleted by hand leaves git's administrative
+   record of it behind, and `worktree add` then refuses the path as already registered — so the very
+   state provisioning exists to recover from would otherwise block every later dispatch.
+3. Load it:
+   ```bash
+   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/dev.aurora.backlog-dispatch.plist
+   ```
+4. To stop and remove it:
+   ```bash
+   launchctl bootout gui/$(id -u)/dev.aurora.backlog-dispatch
+   rm ~/Library/LaunchAgents/dev.aurora.backlog-dispatch.plist
+   ```
+
+Validate any edit to the plist before loading it: `plutil -lint dev.aurora.backlog-dispatch.plist`.
+
+## Releasing a `Blocked` task
+
+`Blocked` is the only human column — the reconciler never takes a task out of it on its own. To
+release one:
+
+1. Read the `Blocked` comment: it always carries the cause and, per design.md decision (m), the
+   open question written in plain language (an ambiguity, an undeclared artifact, a
+   `judgment-day` ESCALATED verdict, an unanswered `needs-guidance`, a failed push, an
+   exhausted attempt budget, or a permission conflict between a settings rule and one the launch
+   grants — that last one names both rules and is resolved by editing one of them, not by re-queueing
+   as it stands).
+2. Answer the question in the task itself (a comment, or an edit to the task body/AC).
+3. Move it:
+   - to `Queued` — the dispatcher retries on the SAME `task/T-nn` branch, with the prior
+     `Blocked` comment and any reviewer findings included in the retry's prompt on BOTH lanes (the
+     frontier lane appends them to its `trabajemos <id>` entry; fresh context, same code). This is
+     the right choice for a fixable failure (a red test, a scope violation, a push that failed to
+     save).
+   - to `To Do` — a human works it in an interactive session instead of redispatching it. Choose
+     this when the question needs a person's judgment call the worker cannot make on retry (e.g.
+     a genuine scope/requirement change).
+
+**A slot held for push recovery needs one more step: releasing it.** When a close or a sweep could
+not PUSH the work a slot holds, the slot is marked `heldForRecovery` and kept out of the pool —
+it holds the only copy of that work, so no acquisition may reuse it. The maintenance pass retries the
+push up to `MAX_RECOVERY_ATTEMPTS` (3) times; past that it stops and hands the slot to a person, and
+the task's comment names the command that gives it back:
+
+```bash
+# After you have the branch safely on the remote
+pnpm backlog:dispatch -- --release-slot dispatch-1
+```
+
+That flag runs no dispatch pass. It detaches the slot's worktree, removes any dispatch lock the slot
+still carried, and clears `heldForRecovery`, `recoveryAttempts` and the task binding — the one
+release that clears the hold, which the ordinary release deliberately does not
+(`slots.ts`'s `releaseHeldSlotEntries`). The hand-edit it replaces is still the same thing: deleting
+`heldForRecovery` and `recoveryAttempts` from that slot in `.backlog/.dispatch/slots.json`.
+
+**It runs under the reconciler's single-flight lock**, and exits **2** when a pass already holds it.
+The rescue is a read of `slots.json`, a decision, and a `git worktree detach` — the exact sequence a
+pass mutates while it selects a task and acquires a slot. Unserialized, a pass that took this slot
+between the read and the detach lost its worktree under a worker that was just starting. Waiting for
+the pass (they are short, and the lock is dropped as soon as the worker spawns) or `--force` are the
+two ways past it; `--force` proceeds without holding the lock, so it never removes the running pass's.
+
+**It also refuses a slot that is genuinely busy**, and exits **2** saying so — "release this slot" and
+"kill what is running in it" are different requests, and only the first is what the flag advertises.
+A release is allowed when the slot is flagged `heldForRecovery` (the case above: the work is committed
+and only the push failed) or when the slot's task lock is absent or DEAD — no such process, or a
+heartbeat past the 10-minute TTL, the same liveness question the maintenance sweep asks. Otherwise
+detaching the worktree under a live `claude` would lose its uncommitted work, drop the lock the close
+re-reads before it runs, and hand the directory to the next dispatch. To take a running slot anyway,
+cancel the task on the board (the next maintenance pass kills the worker after saving its work), or
+pass `--force` once you have looked:
+
+```bash
+pnpm backlog:dispatch -- --release-slot dispatch-1 --force
+```
+
+Starting over from scratch (rather than retrying) means deleting the remote `task/T-nn` branch
+before moving the task back to `Queued` — otherwise the next dispatch reuses it. The attempt cap is
+`lanes.json`'s `attempts` (3 as shipped), read by guard 5 and by the close's terminal-block flag
+alike; a task `Blocked` on its last failed attempt has no automatic path back to dispatch and needs
+the human decision above regardless.
+
+## Known gotchas
+
+- **A board read that half-failed is not an empty board.** `loadBoard` returns
+  `{ tasks, complete }`, and `complete` is `false` when `backlog task list` failed outright or when
+  any single `task view` threw and its id was dropped. The maintenance sweep infers a MANUAL
+  CANCELLATION from a task's absence, so a bare empty list used to read as "a person deleted every
+  task" and killed every live worker at once. With `boardComplete: false` the sweep skips the
+  absence-based cancellation (a task it DID read as `Blocked`/`To Do` is still cancelled — that
+  decision rests on the task's own status) and skips the parent derivation entirely, since deriving a
+  parent from half its children produces a confident wrong answer. The next pass, with a readable
+  board, does both. The flag survives the POST-SWEEP re-read too: `entry.ts`'s `reloadTasks` returns
+  the whole `BoardLoad`, and the close's own parent derivation is skipped with a log when `complete`
+  is false — it derives the same parent from the same kind of read, and a signature that returned
+  only the array dropped the flag on the floor.
+- **A slot is the only place a close may touch.** `slotPathForTask` returns `null` when no slot
+  holds the task, and every runner FAILS its step on that — it never falls back to the main
+  checkout. It used to, and that pointed the whole close at the developer's own working tree: a
+  `git add -A` plus WIP commit over work in progress, a scope diff of somebody else's changes, and a
+  `gh pr create` off whatever branch happened to be checked out there.
+- **The precomputed hooks run in the SLOT but read the board from the main checkout.**
+  `dispatch.ts`'s `buildHookRunners` spawns both hook scripts with the slot as `cwd` — that is where
+  their rule catalogs and the injector cache belong — and with `BACKLOG_CWD=<main checkout>` plus
+  `BACKLOG_DISPATCH_ACTIVE=1` in their env. `inject-prompt-context.ts` reads `BACKLOG_CWD` as its
+  BOARD root (`resolveBoardRoot`): a slot's own `.backlog/` copy holds no tasks, so without it the
+  hook would find no `task_prefix` and match nothing. The sentinel switches the task block's footer
+  from "follow the Task Gate" to "the dispatcher already set it `In Progress`; do not change its
+  state" — pointing a headless worker at an interactive gate invites exactly the status write the
+  close then fails it for. **That block is a FRONTIER-lane thing**, and only there: the frontier
+  worker's real prompt is `trabajemos <id>`, so the hook matches it and the block is the task text
+  that worker gets. The local lane's precompute deliberately names NO id
+  (`prompt.ts`'s `buildHookPromptText` passes the bounded context and the declared files, which is
+  all the BR/HR/skill blocks need to resolve): block 1 of the executor envelope already carries the
+  whole task view verbatim, so an injected second copy meant the weakest executor read its task
+  twice, in two formats, one of them describing a gate it has no business walking. The env pair
+  still travels on both lanes — it is what the hook is entitled to, and the moment anything names an
+  id again the block must resolve against the real board and read as dispatched.
+- **`.claude/.cache/br-injected.json` must be reset per dispatched attempt.** The
+  `business-rules-injector.ts` PreToolUse hook tracks already-injected rule IDs across
+  invocations outside a real interactive session (there is no `SessionStart` to wipe it for a
+  headless run). Without resetting this file before each dispatched attempt, a rule injected for
+  a PREVIOUS task on the same lockfile-shared slot silently fails to surface for the next one —
+  the hook prompt-precompute step (`prompt.ts`) deletes/resets it before assembling a fresh
+  prompt.
+- **`--max-budget-usd` stops at turn boundaries, not mid-generation.** It is a hard stop
+  (`is_error:true`, `subtype:"error_max_budget_usd"`), never a warning, but the turn already in
+  flight always completes first — real spend can overshoot the configured cap, sometimes on the
+  very first turn. Treat it as a coarse safety net layered on top of `--max-turns`, never as a
+  precise or sole stop mechanism.
+- **`maxBudgetUsd` compares an ESTIMATE against a cap, and on a subscription login nothing is
+  billed per token.** `--max-budget-usd` cuts a worker off when Claude Code's own cost ESTIMATE
+  crosses the configured number — measured (T-3, 2026-09-07): this machine's local-lane run
+  printed `cost=$2.40` for a run nothing actually billed. `lanes.json`'s `maxBudgetUsd` is
+  therefore OPTIONAL on the frontier lane: set a number when the machine authenticates with an API
+  key and you want a hard dollar stop; omit it on a subscription login, where the estimate is not
+  billed and the cap only truncates legitimate work. `maxTurns` and `timeoutMinutes` are the guards
+  that always apply, on either kind of login.
+- **A slot never keeps a task branch checked out.** EVERY release goes through
+  `slots.ts`'s `releaseSlotAndDetach` (or, in the maintenance sweep, its `git.detachSlot`
+  collaborator), which runs `git checkout --detach` before clearing the registry entry: the close's
+  own release, the abort path, the branch-in-use handback, the dead-lock sweep, the orphan sweep,
+  the cancellation, the recovered push. Git refuses to check the same branch out in two worktrees,
+  so a slot released while still sitting on `task/T-12` made EVERY later dispatch of T-12 refuse
+  with `branch-in-use` — and since a pass dispatches one task at a time, the whole queue starved
+  behind it. `prepareSlot` also checks out with `-B` rather than `-b`, so a leftover local branch
+  cannot fail the checkout either. If a branch IS still held elsewhere when a task is selected, the
+  pass hands the slot back (detaching it) and leaves the task `Queued` rather than failing — the
+  next pass retries.
+- **Work is branched and diffed against `origin/…`, never a local ref.** A reusable slot's local
+  `main` is whatever its last fetch left behind. Branching new work off it silently reintroduces
+  days-old code, and diffing an attempt against it reports files nobody in this task touched.
+- **`Write(<glob>)` path-scoped permission rules are unverified.** `Edit(<glob>)` (e.g.
+  `Edit(allowed/**)`) is confirmed to scope correctly — a denied edit outside the glob is recorded
+  in `permission_denials` with the file path. The equivalent `Write(<glob>)` rule was never
+  exercised in the Phase 1 spike (the local model never attempted a `Write` tool call at all under
+  that rule), so it is unverified, not confirmed broken — re-verify with a stronger model before
+  relying on it to gate new-file creation. It now carries the frontier lane too, whose `allow`
+  grants the same `Write(./**)`; the close's scope check and `SLOT_EXECUTED_PATHS` are the barriers
+  that do not depend on it.