@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

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

@@ -0,0 +1,1125 @@
+/**
+ * launch.ts — per-lane launch preparation: lane/model resolution, the exact `claude` command for
+ * each lane, the async line-streamed spawn of that command, and the LM Studio readiness check
+ * (design.md — Component design, `launch` row: "Build the per-lane command, env and prompt; spawn;
+ * stream `stream-json` to disk").
+ *
+ * Implements `specs/backlog-task-dispatcher/spec.md` — "Per-lane launch preparation",
+ * "Local-lane model readiness check"; `specs/headless-harness-execution/spec.md` — "Sub-agent
+ * model resolution inside a worker" (the model alias the frontier lane resolves to is exactly the
+ * one `catalyst-delegation`'s per-task table would use for `path:direct`/`path:sdd`).
+ *
+ * Every function here is pure or takes its side effects injected (`fetchImpl`, `onLine`), so the
+ * module is unit-testable without a real LM Studio server, a real `claude` process, or a real
+ * filesystem beyond the temp dirs the tests create — `spawnWorker` is driven against a short-lived
+ * `node` process instead — see design.md's Component design (`launch` row) and its
+ * Executor prompt contract / lane profile examples.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import {
+  describePermissionConflict,
+  findPermissionConflict,
+  grantCovers,
+  isDeadBashRule,
+  normalizeRule,
+  resolveTestCommand,
+} from './guards.js';
+import {
+  EXECUTION_PATH,
+  LANE,
+  TIER,
+  type DispatchLimits,
+  type Lane,
+  type SettingsAllowRule,
+  type SettingsAllowSource,
+  type SlotInfo,
+  type Task,
+} from './types.js';
+import { TASK_ID_ENV, workerEditCommand } from './worker-edit.js';
+
+// ── lanes.json (native JSON.parse — no hand-rolled parser to own, unlike the retired lanes.yaml) ──
+//
+// A private YAML parser was unowned complexity: JSON needs none, since `JSON.parse` is a native,
+// already-owned primitive. The shape-validation helpers below stay — `JSON.parse` guarantees valid
+// syntax, not the right field types — but there is no tokenizer/parser left to maintain or test.
+
+function asRecord(value: unknown, path_: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`lanes.json: expected an object at "${path_}"`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, path_: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`lanes.json: expected a string at "${path_}"`);
+  }
+  return value;
+}
+
+function asNumber(value: unknown, path_: string): number {
+  if (typeof value !== 'number') {
+    throw new Error(`lanes.json: expected a number at "${path_}"`);
+  }
+  return value;
+}
+
+/**
+ * `maxBudgetUsd` is the one lane field that is OPTIONAL: on a claude.ai subscription login
+ * nothing is billed per token, so Claude Code's cost ESTIMATE is not a real dollar figure and the
+ * cap only truncates legitimate work (measured: a free local-lane run printed `cost=$2.40`). A
+ * machine authenticating with an API key still wants a hard stop, so the field stays supported —
+ * absent → `undefined` (no flag emitted), present → must be a positive number, same as every other
+ * declared field (zero or negative would silently make `--max-budget-usd` abort the very first
+ * turn).
+ */
+function asOptionalPositiveNumber(value: unknown, path_: string): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const parsed = asNumber(value, path_);
+  if (parsed <= 0) {
+    throw new Error(`lanes.json: expected a positive number at "${path_}"`);
+  }
+  return parsed;
+}
+
+/**
+ * A GitHub user login: 1-39 characters, alphanumerics and single interior hyphens, never leading or
+ * trailing. This is GitHub's own rule, not a guess.
+ */
+const GITHUB_LOGIN = /^[A-Za-z\d](?:[A-Za-z\d]|-(?=[A-Za-z\d])){0,38}$/;
+
+/** A team slug, the second half of the `org/team` form `gh --add-reviewer` also accepts. */
+const GITHUB_TEAM_SLUG = /^[A-Za-z\d][A-Za-z\d._-]{0,99}$/;
+
+/**
+ * `harnessReviewer` is the one top-level field that is OPTIONAL, same reasoning as `maxBudgetUsd`
+ * (design.md decision 8, T-31): the dispatcher opens every pull request as the same account, so
+ * `gh pr create --reviewer <self>` — and the equivalent `pr edit` — fails when the reviewer named IS
+ * the author. Absent → `undefined` (no reviewer call attempted, recorded once instead).
+ *
+ * Present → validated for its SHAPE, not merely for being a string. The value becomes an argv TOKEN
+ * in `gh pr edit <branch> --add-reviewer <value>` (`close.ts`'s `buildPrReviewerArgs`). No shell is
+ * involved, so this is not injection — but `gh` parses a token starting with `-` as a FLAG, so a
+ * handle like `--add-label` or `-R owner/other` would silently become a second option on the
+ * dispatcher's own command line. `resolveTestCommand` validates the other operator-supplied string
+ * this process spawns for exactly the same reason, with the same anchored, non-dash first character
+ * (`guards.ts`'s `PACKAGE_NAME`); this is that discipline applied here.
+ *
+ * Two accepted shapes, both of them things `--add-reviewer` really takes: a user login, and an
+ * `org/team-slug`.
+ */
+function asOptionalGitHubHandle(value: unknown, path_: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const handle = asString(value, path_);
+  const [login, teamSlug, ...rest] = handle.split('/');
+  const isUserLogin = rest.length === 0 && teamSlug === undefined && GITHUB_LOGIN.test(login);
+  const isTeamHandle =
+    rest.length === 0 &&
+    teamSlug !== undefined &&
+    GITHUB_LOGIN.test(login) &&
+    GITHUB_TEAM_SLUG.test(teamSlug);
+  if (!isUserLogin && !isTeamHandle) {
+    throw new Error(
+      `lanes.json: expected a GitHub handle ("octocat" or "org/team-slug") at "${path_}", got ${JSON.stringify(handle)}`,
+    );
+  }
+  return handle;
+}
+
+function asStringArray(value: unknown, path_: string): string[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`lanes.json: expected an array at "${path_}"`);
+  }
+  return value.map((item, index) => asString(item, `${path_}[${index}]`));
+}
+
+/**
+ * `orphanInProgressThresholdHours` accepts `0` on purpose (defect 12, 2026-09-08) — see that
+ * field's own JSDoc on `LanesConfig`. A NEGATIVE value has no sane reading as a duration: silently
+ * treating it as "even more aggressive than 0" is not a threshold an operator would configure on
+ * purpose, so it is rejected here, at load time, same as every other malformed field.
+ */
+function asNonNegativeNumber(value: unknown, path_: string): number {
+  const parsed = asNumber(value, path_);
+  if (parsed < 0) {
+    throw new Error(`lanes.json: expected a non-negative number at "${path_}"`);
+  }
+  return parsed;
+}
+
+export interface LocalLaneProfile {
+  settings: string;
+  /** This lane's concurrency cap — `dispatchLimitsFrom` turns it into guard 6's capacity. */
+  maxParallel: number;
+  effort: string;
+  maxTurns: number;
+  timeoutMinutes: number;
+  /**
+   * LM Studio's BASE url — `checkLocalModelLoaded` appends `/api/v0/models` itself. It lives here
+   * rather than in `local.settings.json` because it is dispatcher machinery Claude Code knows
+   * nothing about (the same split the README documents: settings hold what Claude Code parses,
+   * `lanes.json` holds what only the reconciler reads). The MODEL to look for is not duplicated
+   * here — it is read from `local.settings.json`'s `model`, which stays the single source of truth.
+   */
+  healthCheckUrl: string;
+  /**
+   * The model that reviews a finished local-lane attempt in the close. It runs on the logged-in
+   * account, NOT on LM Studio: the reviewer subprocess is spawned without the lane's `ANTHROPIC_*`
+   * env, so a weak local executor is never its own reviewer (design.md's close diagram, `SR`).
+   */
+  reviewerModel: string;
+  /**
+   * Wall-clock bound on that reviewer subprocess. It is spawned AFTER the worker exits, while this
+   * process still owns the slot — so a reviewer that never returns holds one of three worktrees
+   * indefinitely, and no sweep can take it back while the heartbeat keeps beating. Defaults to 15
+   * minutes when `lanes.json` omits it.
+   */
+  reviewerTimeoutMinutes: number;
+}
+
+export interface FrontierLaneProfile {
+  settings: string;
+  /** This lane's concurrency cap — `dispatchLimitsFrom` turns it into guard 6's capacity. */
+  maxParallel: number;
+  model: { direct: string; sdd: string };
+  maxTurns: number;
+  /**
+   * A hard dollar stop on Claude Code's cost ESTIMATE, or `undefined` to omit it. Set a number when
+   * the machine authenticates with an API key and a real dollar cap matters; 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 regardless.
+   */
+  maxBudgetUsd?: number;
+  timeoutMinutes: number;
+}
+
+export interface LanesConfig {
+  slotsRoot: string;
+  slots: string[];
+  /** The dispatch attempt ceiling — `dispatchLimitsFrom` turns it into guard 5's cap. */
+  attempts: number;
+  /**
+   * T-8 point 10's threshold, in hours: how long an `In Progress` task may carry no lock, no slot
+   * and no attempt directory before the maintenance sweep's step 3c blocks it as an orphan.
+   * `dispatch.ts` converts this to ms via `resolveOrphanInProgressThresholdMs` and passes it as
+   * `MaintenanceContext.orphanInProgressThresholdMs` — see that field's own JSDoc for why the
+   * sweep step it gates is a no-op until this is wired. Defaults to 4h when `lanes.json` omits it,
+   * the same "declared value wins, absence gets a real bound" pattern `reviewerTimeoutMinutes`
+   * uses just above.
+   *
+   * `0` is a legal, DELIBERATE value (defect 12, 2026-09-08): it is what an operator writes to turn
+   * the whole sweep off, and `resolveOrphanInProgressThresholdMs` is where that reads as "disabled"
+   * rather than as a 0 ms threshold — the most aggressive setting a config could produce, which a
+   * bare multiplication used to make it instead. `loadLaneConfig` rejects a NEGATIVE value outright:
+   * a duration cannot be negative, and silently treating one as "even more aggressive than 0" is not
+   * a threshold anyone would configure on purpose.
+   */
+  orphanInProgressThresholdHours: number;
+  /**
+   * The human-review mark's optional reviewer handle (T-31, design.md decision 8) — see
+   * `asOptionalGitHubHandle`'s own doc comment for why it ships unset, and for the shape it must
+   * take. `dispatch.ts` threads it into
+   * `buildCloseRunners`, whose `openPr` runner reads it.
+   */
+  harnessReviewer?: string;
+  lanes: { local: LocalLaneProfile; frontier: FrontierLaneProfile };
+}
+
+/** The bound applied when `lanes.json` declares no `reviewerTimeoutMinutes` — never "unbounded". */
+const DEFAULT_REVIEWER_TIMEOUT_MINUTES = 15;
+
+/**
+ * The bound applied when `lanes.json` declares no `orphanInProgressThresholdHours` — a task set
+ * `In Progress` by hand and then abandoned would otherwise sit there forever with nothing to catch
+ * it (T-8 point 10's whole reason to exist).
+ */
+const DEFAULT_ORPHAN_IN_PROGRESS_THRESHOLD_HOURS = 4;
+
+/** Reads and parses `lanes.json` into a typed `LanesConfig`, per design.md's Component design. */
+export function loadLaneConfig(lanesJsonPath: string): LanesConfig {
+  const parsed = JSON.parse(fs.readFileSync(lanesJsonPath, 'utf8')) as Record<string, unknown>;
+  const lanes = asRecord(parsed.lanes, 'lanes');
+  const local = asRecord(lanes.local, 'lanes.local');
+  const frontier = asRecord(lanes.frontier, 'lanes.frontier');
+  const frontierModel = asRecord(frontier.model, 'lanes.frontier.model');
+
+  return {
+    slotsRoot: asString(parsed.slotsRoot, 'slotsRoot'),
+    slots: asStringArray(parsed.slots, 'slots'),
+    attempts: asNumber(parsed.attempts, 'attempts'),
+    orphanInProgressThresholdHours:
+      parsed.orphanInProgressThresholdHours === undefined
+        ? DEFAULT_ORPHAN_IN_PROGRESS_THRESHOLD_HOURS
+        : asNonNegativeNumber(
+            parsed.orphanInProgressThresholdHours,
+            'orphanInProgressThresholdHours',
+          ),
+    harnessReviewer: asOptionalGitHubHandle(parsed.harnessReviewer, 'harnessReviewer'),
+    lanes: {
+      local: {
+        settings: asString(local.settings, 'lanes.local.settings'),
+        maxParallel: asNumber(local.maxParallel, 'lanes.local.maxParallel'),
+        effort: asString(local.effort, 'lanes.local.effort'),
+        maxTurns: asNumber(local.maxTurns, 'lanes.local.maxTurns'),
+        timeoutMinutes: asNumber(local.timeoutMinutes, 'lanes.local.timeoutMinutes'),
+        healthCheckUrl: asString(local.healthCheckUrl, 'lanes.local.healthCheckUrl'),
+        reviewerModel: asString(local.reviewerModel, 'lanes.local.reviewerModel'),
+        reviewerTimeoutMinutes:
+          local.reviewerTimeoutMinutes === undefined
+            ? DEFAULT_REVIEWER_TIMEOUT_MINUTES
+            : asNumber(local.reviewerTimeoutMinutes, 'lanes.local.reviewerTimeoutMinutes'),
+      },
+      frontier: {
+        settings: asString(frontier.settings, 'lanes.frontier.settings'),
+        maxParallel: asNumber(frontier.maxParallel, 'lanes.frontier.maxParallel'),
+        model: {
+          direct: asString(frontierModel.direct, 'lanes.frontier.model.direct'),
+          sdd: asString(frontierModel.sdd, 'lanes.frontier.model.sdd'),
+        },
+        maxTurns: asNumber(frontier.maxTurns, 'lanes.frontier.maxTurns'),
+        maxBudgetUsd: asOptionalPositiveNumber(
+          frontier.maxBudgetUsd,
+          'lanes.frontier.maxBudgetUsd',
+        ),
+        timeoutMinutes: asNumber(frontier.timeoutMinutes, 'lanes.frontier.timeoutMinutes'),
+      },
+    },
+  };
+}
+
+/**
+ * Converts `LanesConfig.orphanInProgressThresholdHours` into what
+ * `MaintenanceContext.orphanInProgressThresholdMs` expects. Defect 12 (2026-09-08): `0` — already
+ * validated non-negative by `loadLaneConfig` — is the value an operator reaches for to turn the
+ * whole orphan sweep OFF, and `dispatch.ts` used to convert it with a bare multiplication, landing
+ * `0` ms as the threshold instead: the MOST aggressive setting a config could produce (`ageMs <= 0`
+ * is false for any real task age, so step 3c blocked every orphan candidate on its very first
+ * pass), not the least. `0` here maps to `undefined` — step 3c's own "disabled entirely" signal
+ * (see that field's JSDoc on `MaintenanceContext`). Any other value (already non-negative) converts
+ * to ms as-is; `undefined` is never a legal input to this function — the field itself always
+ * carries a real number once `loadLaneConfig` has run (default or declared).
+ */
+export function resolveOrphanInProgressThresholdMs(hours: number): number | undefined {
+  return hours === 0 ? undefined : hours * 3_600_000;
+}
+
+/**
+ * The dispatch caps, read off the loaded config. Guard 5 (`attempts`), guard 6 and `acquireSlot`
+ * (`maxParallel`) all take their numbers from here, so editing `lanes.json` actually changes what
+ * the dispatcher does — the three used to read module constants, which made those fields decoration.
+ */
+export function dispatchLimitsFrom(config: LanesConfig): DispatchLimits {
+  return {
+    capacity: {
+      [LANE.LOCAL]: config.lanes.local.maxParallel,
+      [LANE.FRONTIER]: config.lanes.frontier.maxParallel,
+    },
+    maxAttempts: config.attempts,
+  };
+}
+
+// ── resolveLane ────────────────────────────────────────────────────────────────
+
+export const RESOLVE_LANE_REFUSAL = {
+  MISSING_TRIAGE: 'missing-triage',
+  COMPLEX_ON_LOCAL: 'complex-on-local',
+  NON_MINOR_ON_LOCAL: 'non-minor-on-local',
+} as const;
+
+export type ResolveLaneRefusal = (typeof RESOLVE_LANE_REFUSAL)[keyof typeof RESOLVE_LANE_REFUSAL];
+
+export type ResolveLaneResult =
+  | { kind: 'refused'; reason: ResolveLaneRefusal }
+  | { kind: 'local' }
+  | { kind: 'frontier'; model: 'sonnet' | 'opus' };
+
+/**
+ * Resolves a triaged task to its lane's launch shape: `tier:complex` is refused on `lane:local`
+ * (design.md decision (n): the local lane takes `tier:minor` only, for now — Phase 0 measured one
+ * Minor task, not a Medium), and the frontier lane's orchestrator model follows `path` per
+ * design.md decision (g), matching the `catalyst-delegation` per-task model table (Sonnet for
+ * direct work, Opus for propose/design/verify-shaped SDD work).
+ */
+export function resolveLane(task: Task): ResolveLaneResult {
+  if (!task.tier || !task.lane || !task.path) {
+    return { kind: 'refused', reason: RESOLVE_LANE_REFUSAL.MISSING_TRIAGE };
+  }
+
+  if (task.lane === LANE.LOCAL) {
+    if (task.tier === TIER.COMPLEX) {
+      return { kind: 'refused', reason: RESOLVE_LANE_REFUSAL.COMPLEX_ON_LOCAL };
+    }
+    if (task.tier !== TIER.MINOR) {
+      return { kind: 'refused', reason: RESOLVE_LANE_REFUSAL.NON_MINOR_ON_LOCAL };
+    }
+    return { kind: 'local' };
+  }
+
+  const model = task.path === EXECUTION_PATH.SDD ? 'opus' : 'sonnet';
+  return { kind: 'frontier', model };
+}
+
+// ── buildLaunch ────────────────────────────────────────────────────────────────
+
+export interface LocalLaneSettings {
+  model: string;
+  env?: Record<string, string>;
+  permissions: { allow: string[]; deny?: string[] };
+}
+
+/**
+ * The frontier lane's settings file. It declares NO `model`: `resolveLane` derives the model from
+ * the task's `path:` label (design.md decision (g)) and passes it as `--model`, so a `model` here
+ * would be a second source of truth that never wins. Everything else Claude Code understands is
+ * honoured: `permissions` become `--allowedTools`/`--disallowedTools`, `env` is injected into the
+ * spawn (the documented cost knob — set `ANTHROPIC_DEFAULT_OPUS_MODEL` to redirect Opus-priced work).
+ */
+export interface FrontierLaneSettings {
+  env?: Record<string, string>;
+  permissions?: { allow?: string[]; deny?: string[] };
+}
+
+export interface Launch {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+  cwd: string;
+  timeoutMs: number;
+}
+
+/**
+ * The `backlog` access a worker gets: ONE command, the dispatcher-owned wrapper
+ * (`worker-edit.ts`), bound to its own task id — it both reads the task (`--view`) and writes to
+ * it, never the CLI directly.
+ *
+ * The raw write was granted here 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 <id> --notes:*)`) fixed the id and the
+ *     first flag — but a rule matches a PREFIX and cannot narrow what comes AFTER it, so
+ *     `--notes x --status Done` matched: the worker could still set its own task to `Done` and
+ *     rewrite the very acceptance criteria the pre-PR gate and the reviewer judge it against.
+ *
+ * The READ was a second rule for the same reason it is now a wrapper flag: `Bash(backlog task view
+ * <id>:*)` is a prefix too, and a command line that merely STARTS with it matched — so the narrow
+ * write channel sat next to an open-ended one.
+ *
+ * The wrapper is the barrier because it reads the WHOLE argv before anything reaches the CLI; the
+ * close's `checkBoardIntegrity` is the detector behind it. The granted path is the MAIN checkout's
+ * copy: the slot's `scripts/` is a directory the worker could write to if a deny rule ever failed
+ * to match.
+ */
+export function backlogRulesForTask(taskId: string, mainCheckoutPath: string): string[] {
+  return [`Bash(${workerEditCommand(mainCheckoutPath, taskId)}:*)`];
+}
+
+/**
+ * The Bash rule for the task's OWN test command, or nothing when it declared none — or one the
+ * close would refuse to run anyway (`resolveTestCommand` is the single allowlist; granting a rule
+ * for a command the close then refuses would be a permission nobody can use).
+ *
+ * Granted per launch rather than as a standing `Bash(pnpm --filter * test*)` in the lane settings:
+ * that trailing glob matched every pnpm subcommand whose words happened to line up, while TDD is
+ * mandatory for a dispatched task and the executor needs exactly one command to run.
+ */
+export function testCommandRuleForTask(declared: string | null): string[] {
+  const resolved = resolveTestCommand(declared);
+  return resolved.kind === 'ok'
+    ? [`Bash(${[resolved.command, ...resolved.args.map(requoteIfSpaced)].join(' ')}:*)`]
+    : [];
+}
+
+/**
+ * Puts back the quotes `resolveTestCommand`'s tokenizer removed. A declared
+ * `pnpm --filter backend test "my file.spec.ts"` comes back as an argv whose last entry carries a
+ * space, and re-joining that on a bare space produces a rule for a command line nobody will ever
+ * run — the worker is told to run one string and granted a different one.
+ */
+function requoteIfSpaced(arg: string): string {
+  return /\s/.test(arg) ? `"${arg}"` : arg;
+}
+
+// ── The allow list a worker also loads from its settings sources ──────────────
+//
+// BOTH lanes name their settings sources explicitly, and the local lane's `--bare` is not a
+// substitute for doing so. 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. Launching a `--bare` worker
+// with no `--setting-sources` therefore got the DEFAULT set (user + project + the local overlay),
+// and the T-5 executor duly ran `python3 -c` — writing a file in the MAIN checkout, outside its
+// slot — plus `npx prettier` and `pnpm exec prettier`, through rules its lane grants nowhere.
+//
+// What neither lane may inherit is `.claude/settings.local.json`, the file a person's
+// click-approvals accumulate in: measured on this machine it holds 61 rules, `Bash(git *)`,
+// `Bash(pnpm *)` and `Bash(python3 -c *)` among them — every git and every pnpm subcommand,
+// including the ones the lanes deliberately withhold — and since Claude Code 2.1.211 a worktree
+// reads the MAIN checkout's copy, so a slot would inherit it whole. Excluded at the source: not
+// loaded, therefore nothing to subtract, and no dilemma between revoking a reviewed lane grant and
+// refusing the launch.
+//
+// The frontier lane loads two sources because it 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 anyway). The local
+// executor needs none of that, so it loads the narrowest value the flag accepts: `user` (an empty
+// one is not in the grammar, and it is the same value the close's reviewer passes).
+//
+// Whatever DOES load still brings its `permissions.allow` with it, and `--allowedTools` ADDS to
+// what that grants rather than replacing it. So writing a lane's allowance out explicitly bounds
+// only what the LAUNCH grants. A deny is the only thing that takes an allow away — Claude Code
+// evaluates deny rules before allow rules from ANY source — so each launch composes one deny per
+// rule its sources contribute and its lane does not grant.
+
+/** `.claude/settings.json`, relative to a checkout root or to a home directory. */
+export const SETTINGS_RELATIVE_PATH = '.claude/settings.json';
+
+/**
+ * The settings sources each lane loads, in the order Claude Code reads them. ONE list per lane,
+ * used twice: `settingSourcesFlag` joins it into the `--setting-sources` value the launch passes,
+ * and `settingsSourcePaths` turns it into the files the deny list is subtracted from — so the flag
+ * and the subtraction cannot describe different sets. The click-approval overlay (`local`) is
+ * absent from both lanes on purpose.
+ */
+export const LANE_SETTING_SOURCES = {
+  [LANE.LOCAL]: ['user'],
+  [LANE.FRONTIER]: ['user', 'project'],
+} as const satisfies Record<Lane, readonly SettingsAllowSource[]>;
+
+/** The exact `--setting-sources` value this lane's launch passes. */
+export function settingSourcesFlag(lane: Lane): string {
+  return LANE_SETTING_SOURCES[lane].join(',');
+}
+
+/** One loadable settings file, tagged with WHICH of the two sources it is. */
+export interface SettingsSource {
+  source: SettingsAllowSource;
+  path: string;
+}
+
+/** Where each settings source lives: the user file in the home directory, the project file in a checkout. */
+const SETTINGS_SOURCE_FILE: Record<
+  SettingsAllowSource,
+  (checkoutPath: string, homeDir: string) => string
+> = {
+  user: (_checkoutPath, homeDir) => path.join(homeDir, SETTINGS_RELATIVE_PATH),
+  project: (checkoutPath) => path.join(checkoutPath, SETTINGS_RELATIVE_PATH),
+};
+
+/**
+ * The settings files this lane's worker loads, in the order Claude Code reads them, matching the
+ * `--setting-sources` value rule for rule. The checkout is the DISPATCHER's own, never the slot:
+ * the list that bounds a worker cannot be a file that worker edits, and both operands of the
+ * subtraction must come from the same place.
+ */
+export function settingsSourcePaths(
+  lane: Lane,
+  checkoutPath: string,
+  homeDir: string,
+): SettingsSource[] {
+  return LANE_SETTING_SOURCES[lane].map((source) => ({
+    source,
+    path: SETTINGS_SOURCE_FILE[source](checkoutPath, homeDir),
+  }));
+}
+
+/**
+ * The union of `permissions.allow` across the given settings sources, in load order and without
+ * duplicates: what the loaded files grant this worker, as one list to subtract from.
+ *
+ * Each rule keeps the source it came from, because a path glob means different things in the two
+ * files: `Edit(**)` in the project file is the checkout the worker runs in, and in the USER file it
+ * is the whole home directory. A rule two sources both declare keeps the FIRST — the user file, the
+ * wider reading of the two, which is the one guard 1b must not lose.
+ */
+export function loadSettingsAllowRules(sources: readonly SettingsSource[]): SettingsAllowRule[] {
+  const byRule = new Map<string, SettingsAllowRule>();
+  for (const { source, path: settingsPath } of sources) {
+    for (const rule of readAllowRules(settingsPath)) {
+      if (!byRule.has(rule)) {
+        byRule.set(rule, { rule, source });
+      }
+    }
+  }
+  return [...byRule.values()];
+}
+
+/**
+ * Reads `permissions.allow` out of ONE settings file. Missing file → no rules, because there is
+ * then nothing for the harness to load either. Unreadable or wrong-shaped → throws: "I cannot parse
+ * it" is not "it grants nothing", and treating it as empty would hand the worker every rule the
+ * file holds with no deny to cancel them.
+ */
+function readAllowRules(settingsPath: string): string[] {
+  if (!fs.existsSync(settingsPath)) {
+    return [];
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `launch.ts: cannot parse ${settingsPath}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const allow = (parsed as { permissions?: { allow?: unknown } } | null)?.permissions?.allow;
+  if (allow === undefined || allow === null) {
+    return [];
+  }
+  if (!Array.isArray(allow) || allow.some((rule) => typeof rule !== 'string')) {
+    throw new Error(
+      `launch.ts: ${settingsPath} declares a permissions.allow that is not a list of strings`,
+    );
+  }
+  return (allow as string[]).map(normalizeRule);
+}
+
+/**
+ * The deny rules that cancel the loaded allow list for a worker that loads it: every rule those
+ * settings sources contribute and the launch does not grant itself.
+ *
+ * "Does not grant" is not string inequality. A deny is COARSE — it outranks every allow — so
+ * denying `Bash(openspec status:*)` because it is not spelled like the lane's `Bash(openspec:*)`
+ * would revoke the lane's own grant, and with it the SDD flow this lane exists to run. A project
+ * rule the granted list already covers more broadly grants nothing new and is skipped.
+ *
+ * The overlaps with no safe answer are `guards.ts`'s `findPermissionConflict`, and guard 1b decides
+ * them BEFORE a slot is acquired: a rule broader than one this launch grants (the project's
+ * `Bash(pnpm test:hooks:*)` over a task whose 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. The throw here is the last-resort invariant behind that
+ * guard, for a caller that composed a launch without evaluating it.
+ *
+ * `grantedAllow` is the WHOLE granted surface — the lane's allow list plus the per-task grants —
+ * for exactly that reason: the per-task test rule is a grant a project rule can swallow.
+ */
+export function settingsAllowRulesToDeny(
+  settingsAllow: readonly SettingsAllowRule[],
+  grantedAllow: readonly string[],
+): string[] {
+  const conflict = findPermissionConflict(settingsAllow, grantedAllow);
+  if (conflict !== null) {
+    throw new Error(`launch.ts: ${describePermissionConflict(conflict)}`);
+  }
+  const granted = grantedAllow.map(normalizeRule);
+  const deny = new Set<string>();
+  for (const rule of settingsAllow.map((entry) => normalizeRule(entry.rule))) {
+    if (!granted.some((grant) => grantCovers(grant, rule))) {
+      deny.add(rule);
+    }
+  }
+  return [...deny];
+}
+
+/**
+ * The WHOLE surface a launch grants this task: the lane's own allow list plus the two per-task
+ * grants — the `worker-edit.ts` wrapper bound to the task id, and the task's validated test command.
+ *
+ * One function because the list is needed twice, in two different modules: guard 1b compares it
+ * against the loaded settings rules BEFORE a slot is taken, and `buildLaunch` writes it into
+ * `--allowedTools`. Composed separately, the two could disagree — and then the guard would have
+ * approved a surface the launch does not grant, or the launch would grant one nobody compared.
+ */
+export function composeGrantedAllow(
+  task: Task,
+  laneAllow: readonly string[],
+  mainCheckoutPath: string,
+): string[] {
+  return [
+    ...new Set([
+      ...laneAllow,
+      ...backlogRulesForTask(task.id, mainCheckoutPath),
+      ...testCommandRuleForTask(task.testCommand),
+    ]),
+  ];
+}
+
+/** A rule granting the `Read` tool — bare, or path-scoped as `Read(<glob>)`. */
+const READ_RULE = /^Read(?:\(|$)/;
+/** A rule granting a file WRITE — `Edit`/`Write`, bare or path-scoped. */
+const WRITE_RULE = /^(?:Edit|Write)(?:\(|$)/;
+
+/**
+ * Asserts the lane's allow list — minus the per-task rules every launch adds on top — actually
+ * grants the two capabilities a coding worker cannot work without.
+ *
+ * "The list is non-empty" was the wrong question. Under `--permission-mode dontAsk` a tool with no
+ * allow rule is DENIED, and a list of `Bash(...)`/`mcp__*` rules is non-empty while holding not one
+ * file tool: a lane like that passed the old check and then had no way to open a file, let alone
+ * change one — an attempt that burns its whole budget being denied. So the check names the
+ * capabilities: at least one read rule and at least one write rule, or the caller blocks the task
+ * with this reason instead of dispatching a worker that cannot do the job.
+ */
+function assertLaneGrantsFileAccess(lane: Lane, laneRules: readonly string[]): void {
+  const missing = [
+    laneRules.some((rule) => READ_RULE.test(rule)) ? null : 'lectura (Read)',
+    laneRules.some((rule) => WRITE_RULE.test(rule)) ? null : 'escritura (Edit/Write)',
+  ].filter((capability): capability is string => capability !== null);
+
+  if (missing.length > 0) {
+    throw new Error(
+      `launch.ts: the ${lane} lane's allow list grants no ${missing.join(' nor ')}; refusing to dispatch. ` +
+        'Check the lane settings file and .claude/settings.json.',
+    );
+  }
+}
+
+/**
+ * Refuses to build a launch whose lane settings carry a dead Bash rule — a mid-rule `*` combined
+ * with a trailing `:*` (`isDeadBashRule`, guards.ts). Measured (T-7, 2026-09-07): that shape
+ * matches nothing at all, so a rule spelled that way is not a narrow grant a reviewer approved, it
+ * is a silent hole — the lane file reads as if it grants a scoped command and actually grants
+ * nothing, with no visible symptom until the declared command is refused at runtime for a reason
+ * nobody can see in the settings file. Checked over BOTH the allow and the deny list of the lane's
+ * OWN settings file, before either becomes part of the launch — a project/user rule loaded through
+ * `--setting-sources` is a different file this dispatcher does not own and is out of scope here.
+ */
+function assertNoDeadBashRules(lane: Lane, rules: readonly string[]): void {
+  const dead = rules.filter(isDeadBashRule);
+  if (dead.length > 0) {
+    throw new Error(
+      `launch.ts: the ${lane} lane's settings carry a dead Bash rule (a mid-rule "*" combined with a trailing ` +
+        `":*" matches nothing — measured 2026-09-07): ${dead.join(', ')}. Rewrite it as an exact-form/` +
+        'with-arguments glob pair instead (e.g. `Bash(cmd * sub)` + `Bash(cmd * sub *)`).',
+    );
+  }
+}
+
+/**
+ * The worker's own system prompt must be an ABSOLUTE path (T-31 round 4). `cwd` below is the SLOT, so
+ * a relative `--append-system-prompt-file` is read FROM the slot: the attempt supplies the brief that
+ * binds it, through a channel `--bare` does not close, because the flag is explicit on the command
+ * line.
+ *
+ * Asserted HERE, where the argv is built, rather than in either producer — the two lanes reach this
+ * value differently (the local lane resolves a static skill file against the repository root with
+ * `dispatch.ts`'s `resolveWorkerSystemPromptPath`; the frontier lane renders the addendum per attempt
+ * and hands back the path it wrote), and the property that matters belongs to the flag, not to one of
+ * the two ways of computing it. Round 3 resolved the local one and asserted nothing at the point of
+ * use, which left the whole suite green when the call site went back to the relative constant.
+ *
+ * A throw aborts the launch: the abort path releases the slot and blocks the task, which is the right
+ * outcome for a worker whose brief cannot be trusted — the same discipline as the dead-Bash-rule and
+ * file-access assertions below.
+ */
+function assertAbsoluteWorkerSystemPrompt(lane: Lane, promptPath: string): void {
+  if (!path.isAbsolute(promptPath)) {
+    throw new Error(
+      `launch.ts: the ${lane} lane's --append-system-prompt-file must be an ABSOLUTE path; got ` +
+        `"${promptPath}". The worker runs with cwd = the slot, so a relative path would read its own ` +
+        'system prompt out of the tree it is writing.',
+    );
+  }
+}
+
+interface BuildLaunchCommonInput {
+  task: Task;
+  slot: SlotInfo;
+  attempt: number;
+  prompt: string;
+  mainCheckoutPath: string;
+  /**
+   * The file appended to the worker's system prompt (`--append-system-prompt-file`), on BOTH lanes.
+   *
+   * On the local lane it is the static `worker-system-prompt.md` (the whole context a `--bare`
+   * executor gets). On the frontier lane it is this attempt's RENDERED addendum
+   * (`prompt.ts`'s `buildFrontierAddendum`, written under the attempt directory): the harness gives
+   * that worker `CLAUDE.md`, which describes an interactive session and knows nothing about the
+   * `worker-edit.ts` wrapper — so without it the worker reached for `backlog task edit`, was denied,
+   * and left every acceptance criterion unticked for the close's gate to fail.
+   */
+  workerSystemPromptPath: string;
+}
+
+export interface BuildLocalLaunchInput extends BuildLaunchCommonInput {
+  lane: 'local';
+  laneProfile: LocalLaneProfile;
+  settings: LocalLaneSettings;
+  /**
+   * Every `permissions.allow` rule the USER settings file contributes to this worker — the one
+   * source `--setting-sources user` loads on this lane (`loadSettingsAllowRules` over
+   * `settingsSourcePaths(LANE.LOCAL, …)`).
+   *
+   * Required, not optional, for the reason the T-5 run measured: `--allowedTools` ADDS to whatever
+   * a loaded source grants, so a launch that forgets this list silently reopens every rule that
+   * file holds — with no deny to cancel it.
+   */
+  settingsAllow: readonly SettingsAllowRule[];
+}
+
+export interface BuildFrontierLaunchInput extends BuildLaunchCommonInput {
+  lane: 'frontier';
+  laneProfile: FrontierLaneProfile;
+  settings: FrontierLaneSettings;
+  /**
+   * Every `permissions.allow` rule the loaded settings sources contribute to THIS worker — the
+   * union of the user and project files (`loadSettingsAllowRules` over `settingsSourcePaths`, the
+   * same two `LANE_SETTING_SOURCES` names). Required rather than optional: a launch that forgets
+   * it silently reopens every rule those files hold, which is the whole reason the deny list below
+   * is computed.
+   *
+   * Read from the dispatcher's own checkout, never from the slot — the worker cannot be the source
+   * of the list that bounds it. `.claude/settings.json` is in `guards.ts`'s hard list
+   * (`SLOT_EXECUTED_PATHS`, `close.ts` reads it) 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.
+   */
+  settingsAllow: readonly SettingsAllowRule[];
+  /** Resolved by `resolveLane` — sonnet for `path:direct`, opus for `path:sdd`. */
+  model: 'sonnet' | 'opus';
+}
+
+export type BuildLaunchInput = BuildLocalLaunchInput | BuildFrontierLaunchInput;
+
+/**
+ * Builds the exact per-lane `claude` command: flags in the design-mandated order (design.md's
+ * Executor prompt contract), env carrying the dispatcher's own sentinel vars plus the lane
+ * profile's env (Phase 1 spike 1.1's finding: spawn-env is the default injection mechanism, NOT
+ * `--settings`, which stays a validated fallback), `cwd` set to the slot, and `timeoutMs` from the
+ * lane's `timeoutMinutes`. Pure — no filesystem or process access.
+ */
+export function buildLaunch(input: BuildLaunchInput): Launch {
+  assertAbsoluteWorkerSystemPrompt(input.lane, input.workerSystemPromptPath);
+  const baseEnv: Record<string, string> = {
+    BACKLOG_DISPATCH_ACTIVE: '1',
+    BACKLOG_CWD: input.mainCheckoutPath,
+    // Read back by `worker-edit.ts` as the id every board write must name — through the constant
+    // that module owns, so the two cannot drift. The permission rule pins the id too, but a wrapper
+    // taking the expected id from its own argv would compare it to itself.
+    [TASK_ID_ENV]: input.task.id,
+    CLAUDE_PROJECT_DIR: input.slot.path,
+  };
+
+  if (input.lane === 'local') {
+    const laneAllow = [...new Set(input.settings.permissions.allow)];
+    assertNoDeadBashRules(LANE.LOCAL, [...laneAllow, ...(input.settings.permissions.deny ?? [])]);
+    assertLaneGrantsFileAccess(LANE.LOCAL, laneAllow);
+    const allow = composeGrantedAllow(input.task, laneAllow, input.mainCheckoutPath);
+    // The lane's static deny list PLUS one deny per rule the USER file contributes and this launch
+    // does not grant — composed exactly as the frontier lane composes it, because the two lanes
+    // differ in WHICH sources they load, not in whether a loaded rule needs cancelling.
+    const deny = [
+      ...new Set([
+        ...(input.settings.permissions.deny ?? []).map(normalizeRule),
+        ...settingsAllowRulesToDeny(input.settingsAllow, allow),
+      ]),
+    ];
+    const args = [
+      '-p',
+      input.prompt,
+      '--bare',
+      '--strict-mcp-config',
+      // Named explicitly, because `--bare` does NOT stop settings loading (see the section comment
+      // above): with the flag absent the DEFAULT set loaded, and the project file plus a person's
+      // 61 click-approvals reached the executor. `user` is the narrowest value the flag accepts.
+      '--setting-sources',
+      settingSourcesFlag(LANE.LOCAL),
+      '--disable-slash-commands',
+      '--append-system-prompt-file',
+      input.workerSystemPromptPath,
+      '--permission-mode',
+      'dontAsk',
+      '--allowedTools',
+      allow.join(' '),
+      // The deny list is NOT the complement of the allowlist: `--allowedTools` gates tool NAMES,
+      // while a `Bash(git push:*)` deny rule narrows a tool the allowlist already opened. Emitted
+      // unconditionally, empty list included, so "both flags are always emitted" holds on BOTH
+      // lanes — a reader who sees the flag on one launch and not the next cannot tell a deliberate
+      // empty list from a dropped one.
+      '--disallowedTools',
+      deny.join(' '),
+      '--effort',
+      input.laneProfile.effort,
+      '--max-turns',
+      String(input.laneProfile.maxTurns),
+      '--output-format',
+      'stream-json',
+      '--verbose',
+      '--model',
+      input.settings.model,
+    ];
+    return {
+      command: 'claude',
+      args,
+      env: { ...baseEnv, ...(input.settings.env ?? {}) },
+      cwd: input.slot.path,
+      timeoutMs: input.laneProfile.timeoutMinutes * 60_000,
+    };
+  }
+
+  const permissions = input.settings.permissions;
+  // ALWAYS both flags, even when either list is empty. `--permission-mode dontAsk` with no
+  // `--allowedTools` is not "the defaults" — it is unrestricted, and a frontier worker running with
+  // every tool available is exactly what the deny list exists to prevent.
+  // The LANE FILE and nothing else. This list used to be the repo's own `.claude/settings.json`
+  // allowlist minus a deny-by-prefix filter, on the theory that the rules people maintain should
+  // stay one list — but a subtraction over a list somebody else maintains reopens with every rule
+  // they add: the filter had to be right about commands that did not exist when it was written, and
+  // was silently wrong the moment one did. The frontier lane's allowance is now written out in
+  // `frontier.settings.json`, where what SURVIVES review is the list itself.
+  const laneRules = [...new Set(permissions?.allow ?? [])];
+  assertNoDeadBashRules(LANE.FRONTIER, [...laneRules, ...(permissions?.deny ?? [])]);
+  assertLaneGrantsFileAccess(LANE.FRONTIER, laneRules);
+  const allow = composeGrantedAllow(input.task, laneRules, input.mainCheckoutPath);
+  // The lane's static deny list PLUS one deny per rule the loaded settings sources contribute and
+  // this launch does not grant. `--allowedTools` adds to the settings files this lane loads on
+  // purpose; a deny is what removes an allow from any source, so the explicit allow list above only
+  // becomes the whole surface once the rest of those sources is denied out.
+  const deny = [
+    ...new Set([
+      ...(permissions?.deny ?? []).map(normalizeRule),
+      ...settingsAllowRulesToDeny(input.settingsAllow, allow),
+    ]),
+  ];
+  const args = [
+    '-p',
+    input.prompt,
+    // The settings sources this worker inherits, named rather than defaulted. The default loads
+    // `.claude/settings.local.json` too — a person's click-approvals, which on this machine grant
+    // `Bash(git *)` and `Bash(pnpm *)`, and which a worktree reads from the MAIN checkout since
+    // Claude Code 2.1.211. A headless worker must never inherit that file; `user,project` keeps what
+    // it does need (the project hooks; the user file's own hooks/mcpServers/model — see the
+    // section comment above) and stops there.
+    '--setting-sources',
+    settingSourcesFlag(LANE.FRONTIER),
+    // Measured 2026-09-09 (`claude -p "ok" --output-format stream-json --verbose --max-turns 1
+    // --model haiku`, reading the `system`/`init` event): without this 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. `frontier.settings.json`'s 26 allow rules grant none of those 68 tools, so they were
+    // loaded only to be denied by omission under `--permission-mode dontAsk` — the flag removes
+    // that dead weight at the source instead of leaving the allowlist as the only barrier, the same
+    // reasoning the local lane and `reviewer.ts` already apply.
+    '--strict-mcp-config',
+    '--append-system-prompt-file',
+    input.workerSystemPromptPath,
+    '--permission-mode',
+    'dontAsk',
+    '--allowedTools',
+    allow.join(' '),
+    '--disallowedTools',
+    deny.join(' '),
+    '--max-turns',
+    String(input.laneProfile.maxTurns),
+    // Omitted entirely when the profile carries no value (a subscription login, where the estimate
+    // is not billed) — never emitted as `--max-budget-usd undefined`, which is not a flag Claude
+    // Code parses as "no cap".
+    ...(input.laneProfile.maxBudgetUsd === undefined
+      ? []
+      : ['--max-budget-usd', String(input.laneProfile.maxBudgetUsd)]),
+    '--output-format',
+    'stream-json',
+    '--verbose',
+    '--model',
+    input.model,
+  ];
+  return {
+    command: 'claude',
+    args,
+    env: { ...baseEnv, ...(input.settings.env ?? {}) },
+    cwd: input.slot.path,
+    timeoutMs: input.laneProfile.timeoutMinutes * 60_000,
+  };
+}
+
+// ── spawnWorker: async, line-streamed ─────────────────────────────────────────
+
+/**
+ * Every environment key the dispatcher must NOT hand a child. The reconciler is itself launched
+ * from a Claude Code session, so its own process env carries the account's `ANTHROPIC_*`
+ * credentials and `CLAUDE_CODE_*` state. Inheriting them means a local-lane worker whose lane
+ * settings only override `ANTHROPIC_BASE_URL` still holds a live API key for anything the lane
+ * settings forgot to shadow — and `CLAUDE_CODE_*` leaks the PARENT session's identity into a
+ * headless child. The lane's own `env` is layered back on top afterwards, so LM Studio still works.
+ */
+const INHERITED_ENV_DENY = /^(ANTHROPIC_|CLAUDE_CODE_)/;
+
+/**
+ * Every OTHER credential a worker must not inherit. The reconciler runs from a developer's session
+ * or from launchd, so its env is whatever that shell exports — and a worker holding one of these
+ * reaches straight past the lane's deny list: `GITHUB_TOKEN`/`GH_TOKEN` push and open PRs through
+ * the API with no `gh` binary involved, `NPM_TOKEN`/`NODE_AUTH_TOKEN` publish, and the SOPS and
+ * cloud keys decrypt this repo's own secrets. Prefix-matched by vendor, plus a suffix rule for the
+ * names that only their ENDING identifies (`*_TOKEN`, `*_SECRET`, `*_PASSWORD`, `*_API_KEY`,
+ * `*_PRIVATE_KEY`) — anchored at the end so an ordinary `TOKEN_BUDGET` still travels.
+ */
+const CREDENTIAL_ENV_PREFIX_DENY =
+  /^(GH_|GITHUB_|NPM_|NODE_AUTH_|SOPS_|AWS_|AZURE_|GOOGLE_|OPENAI_)/;
+const CREDENTIAL_ENV_SUFFIX_DENY = /(TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY)$/i;
+
+/**
+ * Whether an env key names a credential no dispatched child needs. Exported because the close's
+ * REVIEWER subprocess (`reviewer.ts`) inherits the parent env under its own, different rule for the
+ * `ANTHROPIC_*` half and must still apply this one.
+ */
+export function isCredentialEnvKey(key: string): boolean {
+  return CREDENTIAL_ENV_PREFIX_DENY.test(key) || CREDENTIAL_ENV_SUFFIX_DENY.test(key);
+}
+
+/** `process.env` minus every key the dispatcher must not pass on. Pure, so it is testable. */
+export function sanitizeInheritedEnv(
+  parentEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const sanitized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(parentEnv)) {
+    if (value !== undefined && !INHERITED_ENV_DENY.test(key) && !isCredentialEnvKey(key)) {
+      sanitized[key] = value;
+    }
+  }
+  return sanitized;
+}
+
+export interface SpawnWorkerHooks {
+  /**
+   * Called with the CHILD's pid the moment it exists. The dispatch lock records this as
+   * `workerPid`: without it, cancelling a task kills the reconciler process itself and leaves the
+   * `claude` worker orphaned, still writing to the slot nobody is watching any more.
+   */
+  onSpawn?: (pid: number) => void;
+}
+
+/**
+ * Spawns the worker described by `launch` and resolves when it exits, feeding every stdout LINE to
+ * `onLine` as it arrives.
+ *
+ * `detached: true` puts the worker in its OWN process group. A `claude` worker spawns children of
+ * its own (hooks, `pnpm test`, sub-agents); killing only its pid leaves those running and holding
+ * the slot. With a group, one `process.kill(-pid)` reaches the whole tree.
+ *
+ * Async, not `spawnSync`, and that is the point: the reconciler drops its single-flight lock as
+ * soon as the slot is taken, so a blocking wait here would still pin the whole dispatcher to one
+ * worker for up to the lane's timeout — making the frontier cap of 2 unreachable, stalling the
+ * close's `drain`, and starving the maintenance pass that is supposed to be able to cancel this
+ * very worker. Line-oriented via `readline` rather than raw chunks, because a `stream-json` event
+ * routinely exceeds a pipe chunk and half a JSON object is not an event.
+ *
+ * Never rejects: a non-zero exit, a missing binary, or the wall-clock timeout all resolve with
+ * whatever lines were emitted, and the close classifies that partial stream (a stream with no
+ * terminal `result` event is a crash — `render.ts`'s `classifyStreamOutcome`). A rejection here
+ * would skip the save-work-before-release path entirely, which is the one thing design.md decision
+ * (k) forbids.
+ */
+export function spawnWorker(
+  launch: Launch,
+  onLine: (line: string) => void,
+  hooks: SpawnWorkerHooks = {},
+): Promise<void> {
+  return new Promise((resolve) => {
+    const child = spawn(launch.command, launch.args, {
+      cwd: launch.cwd,
+      env: { ...sanitizeInheritedEnv(), ...launch.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: true,
+    });
+
+    if (child.pid !== undefined) {
+      hooks.onSpawn?.(child.pid);
+    }
+
+    const timer = setTimeout(() => killProcessTree(child.pid), launch.timeoutMs);
+    readline.createInterface({ input: child.stdout }).on('line', onLine);
+    child.stderr.on('data', (chunk: Buffer) => process.stderr.write(chunk));
+
+    const finish = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    child.on('close', finish);
+    child.on('error', (error) => {
+      console.error(`launch.ts: worker spawn failed (${launch.command}):`, error.message);
+      finish();
+    });
+  });
+}
+
+/**
+ * SIGTERMs a worker's whole process GROUP, falling back to the single pid when the group is gone
+ * (or was never created — a child that failed to spawn has no pid at all). Exported so the
+ * maintenance pass's cancellation step kills exactly what `spawnWorker` created.
+ */
+export function killProcessTree(
+  pid: number | undefined,
+  kill: (target: number) => void = defaultKill,
+): void {
+  if (pid === undefined) {
+    return;
+  }
+  try {
+    kill(-pid); // negative pid = the whole process group (see `detached: true` above).
+  } catch {
+    try {
+      kill(pid);
+    } catch {
+      // Already gone — nothing to do.
+    }
+  }
+}
+
+function defaultKill(target: number): void {
+  process.kill(target, 'SIGTERM');
+}
+
+// ── LM Studio readiness check (Phase 1 spike 1.6) ─────────────────────────────
+
+interface LmStudioModelsResponse {
+  data?: Array<{ id: string; state: string }>;
+}
+
+function isLmStudioModelsResponse(value: unknown): value is LmStudioModelsResponse {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Verifies the local lane's configured model is loaded, per Phase 1 spike 1.6's confirmed shape:
+ * `GET /api/v0/models` returns `data[].{id, state}`, and the loaded model shows
+ * `"state":"loaded"`. `fetchImpl` is injected so tests never hit a real LM Studio server.
+ *
+ * Never rejects. "LM Studio is not running" is the most common way for the model not to be loaded,
+ * and a rejection would abort the entire reconciler pass — the maintenance sweep and every other
+ * queued task with it — instead of blocking the one task that needed the local lane.
+ */
+export async function checkLocalModelLoaded(
+  fetchImpl: typeof fetch,
+  baseUrl: string,
+  model: string,
+): Promise<boolean> {
+  try {
+    const response = await fetchImpl(`${baseUrl}/api/v0/models`);
+    if (!response.ok) {
+      return false;
+    }
+    const body: unknown = await response.json();
+    if (!isLmStudioModelsResponse(body)) {
+      return false;
+    }
+    return (body.data ?? []).some((entry) => entry.id === model && entry.state === 'loaded');
+  } catch {
+    return false;
+  }
+}
+
+// ── Per-attempt injector cache reset (Phase 1 spike 1.3 finding) ──────────────
+
+/**
+ * `business-rules-injector.ts` writes `.claude/.cache/br-injected.json`, a running set of
+ * already-injected rule ids that persists across invocations outside a real session (no
+ * SessionStart hook to wipe it in a dispatched worker). Without resetting it before each dispatch
+ * attempt, a rule injected for a previous task on this slot silently fails to surface again.
+ */
+export function resetInjectorCache(slotDir: string): void {
+  const cacheFile = path.join(slotDir, '.claude', '.cache', 'br-injected.json');
+  if (fs.existsSync(cacheFile)) {
+    fs.rmSync(cacheFile);
+  }
+}