@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

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

@@ -0,0 +1,734 @@
+/**
+ * entry.ts — the reconciler's 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 → slot
+ * acquisition → launch → close into one pass (`runOnce`). `dispatch.ts` is the thin executable
+ * that builds the real collaborators and calls it.
+ *
+ * Implements `specs/backlog-task-dispatcher/spec.md` — "Anti-loop guard on status transitions",
+ * "Task selection ordering", "Reconciler operates only on the main checkout". Every collaborator
+ * is injected (design.md's Component design, `entry` row: "Triggers and env, resolve
+ * `BACKLOG_CWD`, single-flight file lock, orchestrate the pass") so this module unit-tests without
+ * a real filesystem, git repository, or `claude` process — see `entry.test.ts`.
+ */
+import { type AttemptSink } from './attempt.js';
+import {
+  checkBranchNotMerged,
+  executeClose,
+  needsGuidanceQuestion,
+  planClose,
+  type CloseRunners,
+} from './close.js';
+import { evaluateGuards, type GuardBlockReason, type GuardWaitReason } from './guards.js';
+import {
+  buildLaunch,
+  composeGrantedAllow,
+  dispatchLimitsFrom,
+  resolveLane,
+  type FrontierLaneProfile,
+  type FrontierLaneSettings,
+  type LanesConfig,
+  type Launch,
+  type LocalLaneProfile,
+  type LocalLaneSettings,
+} from './launch.js';
+import { runMaintenance, type MaintenanceContext, type MaintenanceResult } from './maintenance.js';
+import {
+  classifyStreamOutcome,
+  extractResultText,
+  planKindForOutcome,
+  STREAM_OUTCOME,
+} from './render.js';
+import { acquireSlot, prepareSlot, releaseSlotAndDetach } from './slots.js';
+import {
+  LANE,
+  TASK_STATUS,
+  type Board,
+  type BoardLoad,
+  type DispatchLock,
+  type Lane,
+  type SettingsAllowRule,
+  type SlotInfo,
+  type SlotRegistry,
+  type Task,
+} from './types.js';
+
+// ── resolveContext ──────────────────────────────────────────────────────────────
+
+export interface ResolvedContext {
+  mainCheckoutPath: string;
+}
+
+/**
+ * Resolves the main checkout path the reconciler must read and write backlog state in — never a
+ * worktree slot's own copy (spec: "Reconciler operates only on the main checkout"). An explicit
+ * `BACKLOG_CWD` in `env` wins outright (same override Backlog.md's own CLI honors — see
+ * `backlog init --help`'s "in the current directory (or BACKLOG_CWD when set)"), letting a
+ * manual/CI run point the whole reconciler at an isolated project without ever calling
+ * `findRepoRoot`; otherwise `findRepoRoot(cwd)` resolves it (the production path: every real
+ * trigger already runs from the main checkout, with no `BACKLOG_CWD` override set). Both
+ * `findRepoRoot` and `cwd` are injected so this is testable without walking a real directory tree.
+ */
+export function resolveContext(input: {
+  cwd: string;
+  env: { BACKLOG_CWD?: string };
+  findRepoRoot: (startDir: string) => string;
+}): ResolvedContext {
+  if (input.env.BACKLOG_CWD) {
+    return { mainCheckoutPath: input.env.BACKLOG_CWD };
+  }
+  return { mainCheckoutPath: input.findRepoRoot(input.cwd) };
+}
+
+// ── Single-flight file lock ─────────────────────────────────────────────────────
+
+export interface SingleFlightFs {
+  readLockPid(): number | null;
+  writeLockPid(pid: number): void;
+  removeLock(): void;
+}
+
+export type SingleFlightResult = { kind: 'acquired' } | { kind: 'already-running'; pid: number };
+
+/**
+ * Refuses a concurrent second reconciler invocation: if the recorded PID is still alive, this
+ * process backs off. A stale lock (dead PID — a prior run that crashed without cleaning up) is
+ * replaced rather than treated as a live invocation.
+ *
+ * Best-effort, and deliberately so: read-then-write is not atomic, so two passes starting in the
+ * same instant can both acquire. It serializes SELECTION, nothing more — the real mutex over the
+ * shared state is `slots.ts`'s registry lock, which re-reads `slots.json` under an exclusive file
+ * lock on every write, so a double acquisition here cannot hand the same slot to two tasks.
+ */
+export function acquireSingleFlight(
+  fs: SingleFlightFs,
+  currentPid: number,
+  isPidAlive: (pid: number) => boolean,
+): SingleFlightResult {
+  const existing = fs.readLockPid();
+  if (existing !== null && isPidAlive(existing)) {
+    return { kind: 'already-running', pid: existing };
+  }
+  fs.writeLockPid(currentPid);
+  return { kind: 'acquired' };
+}
+
+/**
+ * Releases the single-flight lock. `ownerPid` makes it safe to call twice, which matters because
+ * the lock is now released mid-pass (as soon as the slot is taken) and the caller's `finally` still
+ * runs afterwards: by then a SECOND pass may legitimately hold the lock, and deleting its file
+ * would let a third pass start alongside it.
+ */
+export function releaseSingleFlight(fs: SingleFlightFs, ownerPid?: number): void {
+  if (ownerPid !== undefined && fs.readLockPid() !== ownerPid) {
+    return;
+  }
+  fs.removeLock();
+}
+
+// ── Anti-loop guard on the status-change trigger ───────────────────────────────
+
+export interface DispatchTriggerEnv {
+  NEW_STATUS?: string;
+  OLD_STATUS?: string;
+  BACKLOG_DISPATCH_ACTIVE?: string;
+}
+
+/**
+ * Implements the anti-loop guard: a status-change trigger only warrants task selection when the
+ * new status is `Queued`, the old status was not already `Queued`, and this is not a worker's own
+ * write (`BACKLOG_DISPATCH_ACTIVE` set — the per-task lock is the second barrier, held elsewhere).
+ *
+ * The sentinel is checked FIRST and wins regardless of the transition fields: a worker inherits
+ * `BACKLOG_DISPATCH_ACTIVE=1` in its whole process tree, so anything it spawns — a `backlog` write
+ * that fires `onStatusChange`, or a bare re-invocation with no status vars at all — is a loop this
+ * process must not close.
+ *
+ * `NEW_STATUS` absent, with no sentinel, means this invocation did not come from `onStatusChange`
+ * at all — the launchd timer or a `gh`-poll trigger, neither of which carries a status transition
+ * to guard against — so this returns `true`: nothing here could re-trigger a loop, and the timer's
+ * whole purpose is recovering a `Queued` task a missed callback never dispatched.
+ */
+export function shouldDispatchFromCallback(env: DispatchTriggerEnv): boolean {
+  if (env.BACKLOG_DISPATCH_ACTIVE) {
+    return false;
+  }
+  if (env.NEW_STATUS === undefined) {
+    return true;
+  }
+  return env.NEW_STATUS === TASK_STATUS.QUEUED && env.OLD_STATUS !== TASK_STATUS.QUEUED;
+}
+
+export interface CallbackTriggerEnv {
+  TASK_ID?: string;
+  NEW_STATUS?: string;
+  BACKLOG_DISPATCH_ACTIVE?: string;
+}
+
+/**
+ * Whether this invocation is the `onStatusChange` callback fired by a write the DISPATCHER ITSELF
+ * made — a stronger question than `shouldDispatchFromCallback`'s, which only decides whether to
+ * SELECT a task: maintenance runs unconditionally before that check (spec: "Maintenance pass
+ * precedes task selection"), so a dispatcher-owned write's callback used to run a full maintenance
+ * sweep — including a `.backlog` git commit — concurrently with the pass that made the write and
+ * was still mid-dispatch in the SAME checkout. `dispatch.ts`'s `realBacklog`/`tickOwnedDod` now run
+ * every write with `BACKLOG_DISPATCH_ACTIVE='1'` in their env, so the callback they trigger
+ * inherits it — `main()` checks this predicate BEFORE resolving context or running maintenance at
+ * all, and skips the whole pass when it is true.
+ *
+ * `TASK_ID` is required alongside the sentinel, not just the sentinel alone: it is what tells this
+ * apart from the launchd timer / `gh`-poll trigger, neither of which is an `onStatusChange`
+ * callback at all and both of which must still run their normal recovery pass regardless of
+ * whatever the invoking shell's own environment happens to carry.
+ */
+export function isDispatcherOwnedCallback(env: CallbackTriggerEnv): boolean {
+  return (
+    env.BACKLOG_DISPATCH_ACTIVE === '1' && Boolean(env.TASK_ID) && env.NEW_STATUS !== undefined
+  );
+}
+
+// ── Task selection: priority, then age ─────────────────────────────────────────
+
+/**
+ * Selects the next task to dispatch from the `Queued` set: highest `priority` first, earliest
+ * `createdAt` breaking a tie (spec: "Task selection ordering"). Never mutates the input.
+ */
+export function selectNextTask(queued: readonly Task[]): Task | null {
+  if (queued.length === 0) {
+    return null;
+  }
+  return [...queued].sort((a, b) => b.priority - a.priority || a.createdAt - b.createdAt)[0];
+}
+
+// ── runOnce: the whole pass, one collaborator per phase ────────────────────────
+
+export interface RunOnceContext {
+  /** Resolved by the caller from `shouldDispatchFromCallback(env)` before calling `runOnce`. */
+  shouldSelect: boolean;
+  maintenance: MaintenanceContext;
+  /**
+   * Re-reads the whole board. Called AFTER `runMaintenance`, never before: the sweep moves tasks
+   * (a merged PR to `Done`, a dead worker to `Blocked`, a parent recomputed), and guards evaluated
+   * against the pre-sweep snapshot answered questions the sweep had already changed — a dependency
+   * this very pass moved to `Done` still read as unmet.
+   *
+   * It returns the WHOLE `BoardLoad`, `complete` included, not just the tasks: the close's parent
+   * derivation must know whether the re-read saw every child (`BuildCloseRunnersInput.boardComplete`
+   * in `dispatch.ts`), and a signature that returned only the array dropped that on the floor.
+   */
+  reloadTasks: () => BoardLoad;
+  /**
+   * `slots.ts`'s single mutation primitive, bound to the real registry. Every write re-reads the
+   * file under an exclusive lock and applies a targeted transform, so a slot a CONCURRENT pass
+   * acquired or held is never reverted by this one.
+   */
+  updateSlots: (mutate: (current: SlotRegistry) => SlotRegistry) => SlotRegistry;
+  /** Removes this task's dispatch lock — the abort path's counterpart to `writeLock`. */
+  removeLock: (taskId: string) => void;
+  /**
+   * Moves the task to `Blocked` with the error that aborted its dispatch, and notifies. Called only
+   * from the acquisition→spawn abort path, where nothing downstream ever ran to report it.
+   */
+  onDispatchFailure: (task: Task, error: unknown) => void;
+  mainCheckoutPath: string;
+  currentPid: number;
+  attempt: (task: Task) => number;
+  /** Sets the task `Blocked` with the guard's comment, and notifies. */
+  onBlock: (task: Task, guardResult: { reason: GuardBlockReason; comment: string }) => void;
+  /**
+   * The live `git branch -r` list. Read by guard 4b (`checkParentBranchOnRemote`, via
+   * `evaluateGuards`) to refuse a subtask whose parent branch is not there BEFORE a slot is ever
+   * taken, and by `prepareSlot` just below to resolve the branch to check the slot out onto — the
+   * SAME list for both, so a guard that passed and the checkout that follows it can never disagree.
+   */
+  remoteBranches: string[];
+  /** Branch names other worktrees already have checked out (`git worktree list --porcelain`). */
+  branchesCheckedOutElsewhere: string[];
+  runGit: (args: string[], cwd: string) => void;
+  /**
+   * Brings the slot's worktree into existence and installs it if the lockfile moved, returning the
+   * slot with its refreshed `lockfileHash`. Injected because it shells out to `git worktree add`,
+   * `scripts/worktree-link.sh` and `pnpm install`.
+   */
+  provisionSlot: (slot: SlotInfo) => SlotInfo;
+  writeLock: (lock: DispatchLock) => void;
+  /**
+   * Reads this task's dispatch lock back from disk, or `null` when there is none. The close checks
+   * it before running: this pass drops the single-flight lock as soon as the worker starts, so a
+   * concurrent maintenance sweep can legitimately declare the worker dead and hand the slot away
+   * while it is still streaming.
+   */
+  readLock: (taskId: string) => DispatchLock | null;
+  setInProgress: (taskId: string) => void;
+  /**
+   * Drops the reconciler's single-flight lock. Called as soon as the slot is taken and the task is
+   * `In Progress`, NOT when the pass returns: this process then lives on for the worker's whole
+   * run (up to the frontier lane's 90-minute timeout), and holding the lock that long would make
+   * the frontier cap of 2 unreachable, stall `drain`, and starve the maintenance pass — including
+   * the manual-cancellation step that is supposed to be able to kill this very worker. The
+   * per-task lock, written just above, is what keeps a second pass off THIS task.
+   */
+  releaseSingleFlight: () => void;
+  resetInjectorCache: (slotDir: string) => void;
+  /** Bound by the caller to the local lane's `healthCheckUrl` and its settings `model`. */
+  isLocalModelLoaded: () => Promise<boolean>;
+  /** Moves the task to `Blocked` with the "servidor local sin el modelo" cause, and notifies. */
+  onLocalModelMissing: (task: Task) => void;
+  /** Opens this attempt's `.backlog/.dispatch/<id>/intento-<N>/` and returns its stream sink. */
+  beginAttempt: (task: Task, attempt: number) => AttemptSink;
+  buildPrompt: (task: Task, attempt: number) => string;
+  /** The static `worker-system-prompt.md` the local lane's `--bare` executor is launched with. */
+  workerSystemPromptPath: string;
+  /**
+   * Renders THIS attempt's frontier system-prompt addendum into the attempt directory and returns
+   * its path. Per attempt rather than a static file because it names the task id and the wrapper
+   * command bound to it; injected because it writes to disk.
+   */
+  writeFrontierAddendum: (task: Task, attempt: number) => string;
+  laneConfig: LanesConfig;
+  loadLocalSettings: () => LocalLaneSettings;
+  loadFrontierSettings: () => FrontierLaneSettings;
+  /**
+   * Every `permissions.allow` rule the settings sources load into a worker on the GIVEN lane: the
+   * USER file alone on the local lane (`--setting-sources user`), the user file plus the PROJECT
+   * file on the frontier one (`--setting-sources user,project`). The click-approval overlay
+   * (`.claude/settings.local.json`) is deliberately not among them on either lane, so it
+   * contributes nothing here either. `--allowedTools` ADDS to what a loaded source grants, so the
+   * launch turns every rule the lane does not grant into a deny — see `settingsAllowRulesToDeny` —
+   * and guard 1b refuses the launch outright when one of them is broader than a rule it grants.
+   * Injected because it reads files. Lane-keyed rather than fixed: `--bare` does NOT stop settings
+   * loading (measured, T-5), so the local lane loads a source too, just a narrower one.
+   */
+  loadSettingsAllowRules: (lane: Lane) => SettingsAllowRule[];
+  /**
+   * Spawns the worker and resolves when it exits, feeding every stdout line to `onLine`. `onSpawn`
+   * receives the CHILD's pid the moment it exists, so the lock can name the process a cancellation
+   * has to kill.
+   */
+  spawnWorker: (
+    launch: Launch,
+    onLine: (line: string) => void,
+    hooks: { onSpawn?: (pid: number) => void },
+  ) => Promise<void>;
+  logPathFor: (taskId: string, attempt: number) => string;
+  buildCloseRunners: (task: Task, attempt: number, branch: string) => CloseRunners;
+}
+
+/**
+ * Guard blocks, plus the two blocks that are not guards: the local lane's model-readiness gate
+ * (design.md's lane profiles), and an acquisition-to-spawn step that threw.
+ */
+export type BlockReason = GuardBlockReason | 'local-model-not-loaded' | 'dispatch-failed';
+
+/** A wait this pass decided for itself, on top of the guards' own reasons. */
+export type WaitReason = GuardWaitReason | 'branch-in-use';
+
+export type RunOnceOutcome =
+  | { kind: 'skipped-by-guard' }
+  | { kind: 'no-queued-task' }
+  | { kind: 'blocked'; reason: BlockReason; taskId: string }
+  | { kind: 'waiting'; reason: WaitReason; taskId: string }
+  | { kind: 'dispatched'; taskId: string; closeExecuted: string[] };
+
+/**
+ * The `dispatch.ts: pass N complete — outcome=…` log line used to print only the outcome KIND
+ * (`waiting`, `blocked`), which is useless on its own: every guard that waits or blocks a task
+ * collapses into the same word, so a task stuck `Queued` behind an undeclared dependency (T-6.1,
+ * 2026-09-07) looked identical in the log to one waiting on a free slot. Pure and exported so
+ * `dispatch.ts` can log it without re-deriving the task id or reason itself, and so the format is
+ * unit-tested here rather than eyeballed in a launchd log file.
+ */
+export function formatOutcome(outcome: RunOnceOutcome): string {
+  switch (outcome.kind) {
+    case 'blocked':
+    case 'waiting':
+      return `${outcome.kind} (${outcome.taskId}: ${outcome.reason})`;
+    case 'dispatched':
+      return `${outcome.kind} (${outcome.taskId})`;
+    case 'skipped-by-guard':
+    case 'no-queued-task':
+      return outcome.kind;
+  }
+}
+
+export interface RunOnceResult {
+  maintenance: MaintenanceResult;
+  outcome: RunOnceOutcome;
+}
+
+/**
+ * Runs one full reconciler pass. Maintenance always runs first, unconditionally (spec:
+ * "Maintenance pass precedes task selection"); everything after that is skipped when
+ * `ctx.shouldSelect` is false (the anti-loop guard already decided this status-change trigger
+ * carries no genuine work). Otherwise: select → guard → resolve the lane (and, on the local lane,
+ * verify the model is loaded BEFORE a slot is consumed) → acquire a slot → prepare the branch →
+ * write the lock → mark `In Progress` → drop the single-flight lock → reset the per-attempt
+ * injector cache → open the attempt directory → spawn the worker and await it → classify the
+ * stream → close. Every step's collaborator is injected, so the recorded call order in
+ * `entry.test.ts` IS this function's contract.
+ *
+ * Async because the worker is awaited rather than blocked on: the pass owns the single-flight lock
+ * only up to `releaseSingleFlight`, so a concurrent invocation can run its own maintenance and
+ * dispatch a second frontier task while this one's worker is still streaming.
+ */
+export async function runOnce(ctx: RunOnceContext): Promise<RunOnceResult> {
+  const maintenanceResult = runMaintenance(ctx.maintenance);
+  // The POST-maintenance registry, never `ctx.slots`: this pass may have just released the very
+  // slot the selected task needs, and reading the pre-sweep snapshot would make it wait a whole
+  // interval for a slot that is already free — or, worse, write that stale snapshot back and
+  // resurrect a released slot as busy.
+  const slots = maintenanceResult.slots;
+
+  if (!ctx.shouldSelect) {
+    return { maintenance: maintenanceResult, outcome: { kind: 'skipped-by-guard' } };
+  }
+
+  // Re-read AFTER the sweep, never the snapshot maintenance was given: this pass may have just
+  // moved a dependency to `Done` or blocked a dead worker, and guarding against the older board
+  // makes the pass answer questions its own maintenance step already resolved.
+  const boardLoad = ctx.reloadTasks();
+  const tasks = boardLoad.tasks;
+  // `complete` travels onto `board` too, not just `tasks` — fix round B4: guard 4b
+  // (`checkParentBranchOnRemote`) reads it to tell "this pass's parent read failed transiently"
+  // apart from "the parent genuinely declares nothing", and dropping it here made both look
+  // identical to that guard.
+  const board: Board = {
+    tasksById: Object.fromEntries(tasks.map((task) => [task.id, task])),
+    complete: boardLoad.complete,
+  };
+  const queued = tasks.filter((task) => task.status === TASK_STATUS.QUEUED);
+  const selected = selectNextTask(queued);
+  if (!selected) {
+    return { maintenance: maintenanceResult, outcome: { kind: 'no-queued-task' } };
+  }
+
+  // The caps come from the loaded `lanes.json`, never from a module constant: guard 5's attempt
+  // ceiling, guard 6's per-lane capacity and the acquisition below must all read the same file.
+  const limits = dispatchLimitsFrom(ctx.laneConfig);
+
+  // Loaded HERE, before the guards, and reused by the launch below: guard 1b compares the two lists
+  // (what this worker's settings sources grant vs. what this launch would grant it) and a conflict
+  // between them has no safe automatic answer. Deciding it at launch time meant deciding it after
+  // the slot, the lock and the attempt directory already existed.
+  //
+  // BOTH lanes load a source, so both compose it. The local lane's `--bare` was read as "no
+  // settings load here" until the T-5 run measured otherwise — see `launch.ts`'s settings-source
+  // section. `null` only when the task carries no lane, which guard 1 blocks below anyway.
+  const laneLaunch =
+    selected.lane === LANE.FRONTIER
+      ? ({
+          lane: LANE.FRONTIER,
+          settings: ctx.loadFrontierSettings(),
+          settingsAllow: ctx.loadSettingsAllowRules(LANE.FRONTIER),
+        } as const)
+      : selected.lane === LANE.LOCAL
+        ? ({
+            lane: LANE.LOCAL,
+            settings: ctx.loadLocalSettings(),
+            settingsAllow: ctx.loadSettingsAllowRules(LANE.LOCAL),
+          } as const)
+        : null;
+  const guardResult = evaluateGuards(
+    selected,
+    board,
+    slots,
+    limits,
+    laneLaunch === null
+      ? null
+      : {
+          settingsAllow: laneLaunch.settingsAllow,
+          // The same composition `buildLaunch` writes into `--allowedTools`, from the same
+          // function: the guard has to compare the surface the launch actually grants, and two
+          // hand-rolled spellings of "the lane list plus the per-task grants" can drift apart.
+          grantedAllow: composeGrantedAllow(
+            selected,
+            laneLaunch.lane === LANE.FRONTIER
+              ? (laneLaunch.settings.permissions?.allow ?? [])
+              : laneLaunch.settings.permissions.allow,
+            ctx.mainCheckoutPath,
+          ),
+        },
+    ctx.remoteBranches,
+  );
+  if (guardResult.kind === 'block') {
+    ctx.onBlock(selected, guardResult);
+    return {
+      maintenance: maintenanceResult,
+      outcome: { kind: 'blocked', reason: guardResult.reason, taskId: selected.id },
+    };
+  }
+  if (guardResult.kind === 'wait') {
+    return {
+      maintenance: maintenanceResult,
+      outcome: { kind: 'waiting', reason: guardResult.reason, taskId: selected.id },
+    };
+  }
+
+  // guardResult.kind === 'launch': tier/lane/path are present (guard 1 already confirmed it).
+  const lane = selected.lane as Lane;
+  const resolved = resolveLane(selected);
+
+  // The readiness check runs BEFORE slot acquisition on purpose: a local server without its model
+  // loaded is not the task's fault, so it must not burn a worktree slot or an attempt directory
+  // (spec: "Local-lane model readiness check" — "no worker process starts").
+  if (resolved.kind === 'local' && !(await ctx.isLocalModelLoaded())) {
+    ctx.onLocalModelMissing(selected);
+    return {
+      maintenance: maintenanceResult,
+      outcome: { kind: 'blocked', reason: 'local-model-not-loaded', taskId: selected.id },
+    };
+  }
+
+  const acquireResult = acquireSlot(lane, selected.id, slots, limits.capacity);
+  if (acquireResult.kind !== 'acquired') {
+    // Guard 6 already checked capacity against the SAME registry, so this is unreachable in
+    // practice; kept as a defensive requeue rather than a thrown error.
+    return {
+      maintenance: maintenanceResult,
+      outcome: { kind: 'waiting', reason: 'no-free-slot', taskId: selected.id },
+    };
+  }
+  const attempt = ctx.attempt(selected);
+
+  // Persist the allocation BEFORE anything else runs against the slot: `slots.json` is the mutex a
+  // concurrent pass reads (lane capacity) and the map every close runner uses to answer "which
+  // directory is this task's work in". Leaving it unwritten leaves every close runner with no slot
+  // to work in at all. Only THIS slot's entry is touched — the rest is whatever the file holds now.
+  const persistSlot = (entry: SlotInfo): void => {
+    ctx.updateSlots((current) => ({
+      slots: current.slots.map((existing) => (existing.name === entry.name ? entry : existing)),
+    }));
+  };
+
+  /**
+   * The pass's own hand-back, through the SAME release procedure the close uses: detach, then clear
+   * the entry. Releasing without detaching left the slot sitting on `task/T-nn`, and git refuses
+   * that branch in any other worktree — so every later dispatch of the task refused with
+   * `branch-in-use`, and with one task selected per pass the whole queue starved behind it.
+   */
+  const releaseTheSlot = (): void => {
+    releaseSlotAndDetach({
+      taskId: selected.id,
+      slotPath: acquireResult.slot.path,
+      runGit: ctx.runGit,
+      updateSlots: ctx.updateSlots,
+    });
+  };
+
+  /**
+   * Everything between taking the slot and the worker exiting can throw for reasons that have
+   * nothing to do with the task: a `pnpm install` that fails, a `git checkout` against a ref that
+   * vanished, a hook subprocess that dies while the prompt is assembled. Without this, the throw
+   * escaped 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.
+   */
+  const abortDispatch = (error: unknown, sink: AttemptSink | null): RunOnceResult => {
+    console.error(`entry.ts: ${selected.id} could not be dispatched:`, error);
+    sink?.stopHeartbeat();
+    releaseTheSlot();
+    ctx.removeLock(selected.id);
+    ctx.onDispatchFailure(selected, error);
+    return {
+      maintenance: maintenanceResult,
+      outcome: { kind: 'blocked', reason: 'dispatch-failed', taskId: selected.id },
+    };
+  };
+
+  let openSink: AttemptSink | null = null;
+  let span: { sink: AttemptSink; branch: string } | null = null;
+
+  try {
+    // The worktree may not exist yet (a fresh checkout, or someone pruned `.claude/worktrees/`):
+    // create and install it before anything runs against it. Returns the slot with the lockfile
+    // hash this install used, so the next task on this slot skips a redundant `pnpm install`.
+    const slot = { ...ctx.provisionSlot(acquireResult.slot), pid: ctx.currentPid };
+    persistSlot(slot);
+
+    const prepared = prepareSlot({
+      slotPath: slot.path,
+      taskId: selected.id,
+      parentId: selected.parentId,
+      tasksById: board.tasksById,
+      remoteBranches: ctx.remoteBranches,
+      branchesCheckedOutElsewhere: ctx.branchesCheckedOutElsewhere,
+      runGit: ctx.runGit,
+    });
+
+    if (prepared.kind === 'branch-in-use') {
+      // Another slot still has this task's branch checked out (a close that has not released yet).
+      // Hand the slot back and leave the task `Queued`: git would refuse the checkout anyway, and
+      // failing the whole pass over it would starve every other queued task.
+      console.warn(
+        `entry.ts: ${selected.id} waits — ${prepared.ref} is checked out in another slot.`,
+      );
+      releaseTheSlot();
+      return {
+        maintenance: maintenanceResult,
+        outcome: { kind: 'waiting', reason: 'branch-in-use', taskId: selected.id },
+      };
+    }
+
+    const nowIso = new Date().toISOString();
+    const lock: DispatchLock = {
+      taskId: selected.id,
+      slot: slot.name,
+      pid: ctx.currentPid,
+      workerPid: null,
+      startedAt: nowIso,
+      heartbeatAt: nowIso,
+      lane,
+      attempt,
+      branch: prepared.ref,
+    };
+    ctx.writeLock(lock);
+    ctx.setInProgress(selected.id);
+    ctx.releaseSingleFlight();
+    ctx.resetInjectorCache(slot.path);
+
+    openSink = ctx.beginAttempt(selected, attempt);
+    const prompt = ctx.buildPrompt(selected, attempt);
+    const launch =
+      resolved.kind === 'local' && laneLaunch?.lane === LANE.LOCAL
+        ? buildLaunch({
+            task: selected,
+            lane: 'local',
+            slot,
+            attempt,
+            prompt,
+            laneProfile: ctx.laneConfig.lanes.local as LocalLaneProfile,
+            // The SAME two lists guard 1b compared, never a second read — see the frontier branch.
+            settings: laneLaunch.settings,
+            settingsAllow: laneLaunch.settingsAllow,
+            mainCheckoutPath: ctx.mainCheckoutPath,
+            workerSystemPromptPath: ctx.workerSystemPromptPath,
+          })
+        : resolved.kind === 'frontier' && laneLaunch?.lane === LANE.FRONTIER
+          ? buildLaunch({
+              task: selected,
+              lane: 'frontier',
+              slot,
+              attempt,
+              prompt,
+              workerSystemPromptPath: ctx.writeFrontierAddendum(selected, attempt),
+              laneProfile: ctx.laneConfig.lanes.frontier as FrontierLaneProfile,
+              // The SAME two lists guard 1b compared, never a second read: re-reading them here
+              // would let a file edited between the guard and the launch decide the surface, with
+              // the conflict check already spent on the previous contents.
+              settings: laneLaunch.settings,
+              settingsAllow: laneLaunch.settingsAllow,
+              mainCheckoutPath: ctx.mainCheckoutPath,
+              model: resolved.model,
+            })
+          : null;
+
+    if (!launch) {
+      // Unreachable: guards.ts's checkTriage/checkComplexOnLocal already guarantee resolveLane
+      // cannot refuse a task that just passed evaluateGuards, and `resolveLane` answers a lane only
+      // for the very `lane` value that composed `laneLaunch` above.
+      throw new Error(
+        `entry.ts: no launch shape for a task that already passed evaluateGuards (${selected.id}, lane ${lane})`,
+      );
+    }
+
+    await ctx.spawnWorker(launch, openSink.onLine, {
+      // Recorded the moment the child exists: the lock's `pid` is this reconciler, and a
+      // cancellation that killed THAT would leave the worker orphaned in the slot.
+      //
+      // Merged onto what is ON DISK, not onto the snapshot above: the attempt sink has already
+      // started refreshing the heartbeat, and rewriting the launch-time value over it makes the
+      // heartbeat run backwards — which is precisely what the maintenance sweep reads as stale,
+      // killing the worker this write exists to record.
+      onSpawn: (workerPid) => ctx.writeLock({ ...(ctx.readLock(selected.id) ?? lock), workerPid }),
+    });
+
+    span = { sink: openSink, branch: prepared.ref };
+  } catch (error) {
+    return abortDispatch(error, openSink);
+  }
+
+  try {
+    // `finish` renders `run.log` and hands back every raw line it persisted — the sink is the ONLY
+    // collector, so what the classifier sees and what `stream.jsonl` holds can never disagree. The
+    // HEARTBEAT keeps running past it, all the way to the `finally` below: the close's own steps
+    // (scoped tests, the reviewer subprocess, the PR) routinely outlast the lock's TTL, and the
+    // single-flight lock is already released — a frozen heartbeat gets this live close swept.
+    const streamLines = span.sink.finish();
+    const streamOutcome = classifyStreamOutcome(streamLines);
+
+    // Nothing in the close is safe once this pass stopped owning the task. The single-flight lock
+    // was dropped the moment the worker started, so a maintenance sweep in ANOTHER pass may 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 from
+    // someone else's branch, re-statuses a task a person already moved, and releases a slot that
+    // is live work. Skipping is the whole remedy: the sweep already saved and blocked.
+    const currentLock = ctx.readLock(selected.id);
+    if (currentLock === null || currentLock.pid !== ctx.currentPid) {
+      console.error(
+        `entry.ts: ${selected.id} is no longer locked by this pass (pid ${ctx.currentPid}); skipping its close.`,
+      );
+      return {
+        maintenance: maintenanceResult,
+        outcome: { kind: 'dispatched', taskId: selected.id, closeExecuted: [] },
+      };
+    }
+
+    const logPath = ctx.logPathFor(selected.id, attempt);
+    const closeRunners = ctx.buildCloseRunners(selected, attempt, span.branch);
+
+    // T-8 point 4/7: never push to a branch whose PR GitHub already reports merged — measured
+    // incident (T-6.3), two late commits pushed to an already-merged branch never reached the
+    // parent and were lost silently. This runs BEFORE either push a close plan can make: the
+    // success path's `open-pr` step (its own commit-and-push) and the failure path's `save-work`
+    // WIP commit both push, so the check must gate the plan itself, not one branch of it. Reuses
+    // the SAME `isPrMerged` seam the maintenance sweep already asks GitHub with, rather than a
+    // second way to ask the same question.
+    const branchAlreadyMergedPlan = checkBranchNotMerged({
+      branch: span.branch,
+      isPrMerged: ctx.maintenance.gh.isPrMerged,
+      logPath,
+      attempt,
+      maxAttempts: limits.maxAttempts,
+    });
+
+    const plan =
+      branchAlreadyMergedPlan ??
+      (planKindForOutcome(streamOutcome) === 'success'
+        ? planClose({ outcome: 'success', lane })
+        : planClose({
+            outcome: 'failure',
+            lane,
+            reason: streamOutcome,
+            // T-6 measured a `Blocked` comment with no trace of the worker's own report — only
+            // the outcome, the branch and the log path. `needs-guidance` is the one outcome where
+            // that report IS the actionable content (a person reads it to answer the question), so
+            // it alone gets the terminal `result` event's text; a crash/budget/turns failure has no
+            // such report to carry.
+            question:
+              streamOutcome === STREAM_OUTCOME.NEEDS_GUIDANCE
+                ? needsGuidanceQuestion(extractResultText(streamLines))
+                : undefined,
+            branch: span.branch,
+            logPath,
+            attempt,
+            // The real push result is only known once `saveWork` actually runs — `executeClose`
+            // recomputes it from the runner's real return value; this is a placeholder plan input.
+            pushSucceeded: true,
+            maxAttempts: limits.maxAttempts,
+          }));
+
+    const executed = executeClose(plan, closeRunners, {
+      lane,
+      attempt,
+      branch: span.branch,
+      logPath,
+      maxAttempts: limits.maxAttempts,
+    });
+
+    return {
+      maintenance: maintenanceResult,
+      outcome: { kind: 'dispatched', taskId: selected.id, closeExecuted: executed },
+    };
+  } finally {
+    span.sink.stopHeartbeat();
+  }
+}