@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

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

@@ -0,0 +1,1185 @@
+/**
+ * maintenance.ts — the maintenance pass that runs at the start of every reconciler invocation,
+ * before any task is selected for dispatch.
+ *
+ * Implements `specs/backlog-task-dispatcher/spec.md` — "Maintenance pass precedes task selection"
+ * (dead-lock sweep, orphan-slot release, merged-PR-to-Done, recompute every parent, commit pending
+ * `.backlog/**` changes) and "Manual cancellation kills the worker after saving work";
+ * `specs/backlog-task-lifecycle/spec.md` — "Derived parent state" (reused verbatim from
+ * `parent.ts`, never re-derived here).
+ *
+ * `runMaintenance(ctx)` is a single synchronous function; every side effect (reading/writing
+ * `slots.json`, reading/removing lock files, PID liveness, the clock, `gh`, `backlog task edit`,
+ * and git) is injected through `MaintenanceContext` so this module is unit-testable without a real
+ * filesystem, git repository, or process — see design.md's Component design (`maintenance` row).
+ *
+ * Order, fixed (design.md's Tramo 7 diagram, plus the manual-cancellation, board-commit and T-8
+ * steps this task's brief adds): (0) retry the pushes a previous pass could not complete, freeing
+ * the slots they held, bounded by `MAX_RECOVERY_ATTEMPTS` after which the slot is left to a
+ * person; (1) sweep dead/expired locks — kill a hung worker first, SAVE its work, then
+ * release its slot (or hold the slot when the push failed) and block the task; (2) release orphan
+ * slots (occupied but with no lock at all, and not held for recovery); (3) move a merged-PR task to
+ * `Done`, deleting its `task/<id>` branch ONLY once it is confirmed to carry no commit beyond its
+ * base (T-8 point 5 — never on the `Blocked` path; a branch that fails that check is left alone
+ * for a person to rescue, see `MaintenanceGit.branchHasUnmergedCommits`); (3b) revert
+ * a hand-written `Done` whose branch exists but whose PR GitHub does not report merged (T-8 point
+ * 7 — the mirror of step 3, left alone when the task carries no branch at all); (3c) block an
+ * orphan `In Progress` — no lock, no slot, no attempt directory, and an `updated_date` older than
+ * `lanes.json`'s `orphanInProgressThresholdHours` (T-8 point 10); (4) manual cancellation — save
+ * work, THEN kill the worker, THEN release (never any other order, per design.md decision (k));
+ * (5) recompute every parent's derived state via `parent.ts`, writing only on change and deleting
+ * the branch of any parent this step itself closes — skipped whole when `boardComplete` is false.
+ * T-8's last point: for a Complex parent whose children are all Done, this is also where the ONE
+ * automated close attempt gets enqueued (`parent.ts`'s rules 4/5) — the write this step already
+ * makes moves the parent straight to `Queued`, and the pass's own selection phase (later in this
+ * SAME `runOnce`) may dispatch it before the next pass ever runs;
+ * (6) commit any pending `.backlog/**` changes with a Conventional Commit message and `--no-verify`
+ * (design.md decision (l) — Backlog.md's own `auto_commit` stays `false`). `--no-verify` for the
+ * same reason every other dispatcher-authored commit carries it: the hooks a commit would run are
+ * files in a working tree a dispatched worker may have just written, and running them here would
+ * execute that code as the dispatcher.
+ */
+import { taskBaseBranch } from './guards.js';
+import { deriveParentStatus, effectiveStatus, type ParentDerivationNode } from './parent.js';
+import { isLockAlive, releaseSlotEntries } from './slots.js';
+import {
+  TASK_STATUS,
+  type DispatchLock,
+  type SlotInfo,
+  type SlotRegistry,
+  type Task,
+  type TaskStatus,
+} from './types.js';
+
+// ── Injected collaborators ─────────────────────────────────────────────────────
+
+export interface MaintenanceFs {
+  readSlots(): SlotRegistry;
+  /**
+   * `slots.ts`'s single mutation primitive, bound to the real registry: re-reads the file under an
+   * exclusive lock, applies `mutate` to what it finds THERE, and writes the result. The sweep must
+   * never write a whole registry built on the snapshot it read at its start — a second pass
+   * legitimately acquires or releases a slot meanwhile, and that write would be reverted.
+   */
+  updateSlots(mutate: (current: SlotRegistry) => SlotRegistry): SlotRegistry;
+  readLocks(): DispatchLock[];
+  removeLock(taskId: string): void;
+  /**
+   * Whether `.backlog/.dispatch/<taskId>/` exists — one of the four T-8 point 10 orphan checks.
+   * Its presence means the task WAS dispatched at some point, even if no lock or slot survives
+   * today, so it is never an orphan by this definition regardless of `updated_date`.
+   *
+   * OPTIONAL until `dispatch.ts`'s real `fs` collaborator wires it: `runMaintenance`'s step 3c
+   * (the orphan sweep itself) is entirely gated on `MaintenanceContext.orphanInProgressThresholdMs`
+   * being set, so a caller that supplies neither runs exactly as it did before T-8 point 10.
+   */
+  hasAttemptDir?(taskId: string): boolean;
+  /**
+   * Whether this parent's ONE automated close attempt (T-8 rules 4/5 in `parent.ts`) has ever been
+   * ENQUEUED — durable from the moment rule 4 first derives `Queued` for it, not from the moment a
+   * worker actually starts (T-8 defect 3, HIGH, 2026-09-08).
+   *
+   * `own.attempts > 0` (a count of `.backlog/.dispatch/<taskId>/intento-N/` directories) used to be
+   * this signal, and it is not a once-only one: `beginAttempt` creates that directory LATE — after
+   * every guard, after `provisionSlot`, after `prepareSlot`, after `buildLaunch` — so `attempts`
+   * stays `0` forever on any of four reachable paths: (1) a guard blocks the dispatch before a
+   * worker ever starts (e.g. no declared `Test command:` — common for a Complex parent from an
+   * interactive decomposition, since nobody meant to dispatch it directly); (2) `entry.ts`'s
+   * `abortDispatch` fires before `beginAttempt` (a failed `pnpm install`, a `prepareSlot`/
+   * `buildLaunch` throw); (3) the reconciler crashes after `writeLock` but before `beginAttempt` —
+   * the next pass's dead-lock sweep writes `Blocked`, and step 5 in that SAME pass re-derives
+   * `Queued` over it, since `deriveParentStatus` never consults the parent's own current status for
+   * rule 4; (4) the narrow window between `entry.ts` releasing the single-flight lock and
+   * `beginAttempt` running. In every one of those, the SAME "all children Done, PR unmerged" state
+   * re-derives `Queued` on every later pass — a new `Blocked` comment every few minutes, forever.
+   *
+   * `markCloseAttemptEnqueued` is called exactly once, by `recomputeParent`, the INSTANT rule 4
+   * first fires — before any guard, any slot, any lock, any attempt directory exists — which is why
+   * it closes all four paths above: the marker is already durable by the time any of them can run.
+   */
+  hasCloseAttemptBeenEnqueued(taskId: string): boolean;
+  /** Marks it. See `hasCloseAttemptBeenEnqueued`'s own JSDoc. */
+  markCloseAttemptEnqueued(taskId: string): void;
+}
+
+export interface MaintenanceGh {
+  /** True only when the branch has an observed, merged pull request. */
+  isPrMerged(branch: string): boolean;
+  /**
+   * The branch's most recent PR state as GitHub reports it (`OPEN`, `CLOSED`, `MERGED`), or `null`
+   * when the branch carries no PR at all. T-8 point 7's revert comment names this so a person does
+   * not have to open GitHub before deciding whether to re-merge, reopen, or abandon the work.
+   *
+   * OPTIONAL until `dispatch.ts`'s real `gh` collaborator wires it — step 3b only ever calls it
+   * once `MaintenanceGit.branchExists` has already confirmed a branch exists, so an unwired `gh`
+   * never reaches it (see `branchExists`'s own note below).
+   */
+  prState?(branch: string): string | null;
+  /**
+   * The tri-state answer step 3b's DESTRUCTIVE revert needs — and the reason it cannot reuse
+   * `isPrMerged`'s boolean, or `prState`'s `string | null`, for the decision itself (T-8 defect 1,
+   * CRITICAL, 2026-09-08).
+   *
+   * `isPrMerged` collapses FOUR conditions into one `false`: the PR is open but not merged, no PR
+   * was ever opened, the `gh` binary is missing, and the token expired or the network failed. Step
+   * 3 (moving a task TOWARD `Done`) can read that `false` safely — failing closed there means doing
+   * nothing. Step 3b (reverting a hand-written `Done` back to `In Progress`) reads the SAME `false`
+   * as "GitHub confirms this is not merged". Measured failure scenario: the `gh` token expires — a
+   * recurring condition in this repo, which is why a `GITHUB_TOKEN= gh …` workaround exists. One
+   * reconciler pass runs; `branchExists` answers `true` for every task whose local `task/<id>` ref
+   * still exists; `isPrMerged` answers `false` for all of them, indistinguishably from an outage.
+   * Every `Done` task with a surviving local branch gets reverted to `In Progress` with a comment,
+   * and step 6 commits the lot to `main`.
+   *
+   * `prState` was considered for this seam and rejected: it returns `null` from the EXACT SAME
+   * catch block `isPrMerged` shares (see `realGh` in `dispatch.ts`), so a `null` cannot tell "no PR,
+   * confirmed" from "gh is down" any better than `isPrMerged` itself — reusing it would only rename
+   * the ambiguity, not close it. `mergedState` needs a genuinely different mechanism: `realGh` asks
+   * `gh pr list --head <branch> --state all`, not `gh pr view <branch>` — an EMPTY array is a real,
+   * successful answer ("no PR exists for this branch", which IS `not-merged`: a person who pushed a
+   * branch and wrote `Done` by hand with no PR at all is still legitimately reverted), while a
+   * THROWN error is the only thing that becomes `unknown`.
+   *
+   * `unknown` must never read as `not-merged`: step 3b skips a task entirely when it gets `unknown`,
+   * leaving a stale `Done` to be re-checked on the NEXT pass rather than reverting on a question
+   * `gh` could not actually answer.
+   *
+   * OPTIONAL for the same reason `prState` is: an unwired caller must default to `unknown` (never
+   * to a guessed `merged`/`not-merged`) — see step 3b's own use of it.
+   */
+  mergedState?(branch: string): PrMergeState;
+}
+
+/**
+ * The three answers step 3b's tri-state `mergedState` can give, and only three: `MERGED` and
+ * `NOT_MERGED` are both CONFIRMED answers `gh` actually returned — including "no PR was ever opened
+ * for this branch", which is `NOT_MERGED` too, since a hand-written `Done` with a pushed branch and
+ * no PR is still a legitimate revert target. `UNKNOWN` is reserved for when the `gh` CALL ITSELF
+ * failed to produce an answer — the binary is missing, the token expired, or the network is down —
+ * and must never be treated as `NOT_MERGED` (see `MaintenanceGh.mergedState`'s own JSDoc for the
+ * incident this distinction exists to prevent).
+ */
+export const PR_MERGE_STATE = {
+  MERGED: 'merged',
+  NOT_MERGED: 'not-merged',
+  UNKNOWN: 'unknown',
+} as const;
+
+export type PrMergeState = (typeof PR_MERGE_STATE)[keyof typeof PR_MERGE_STATE];
+
+/**
+ * The three answers `MaintenanceGit.deleteRemoteBranch` can give — defect 7 (2026-09-08). A caller
+ * that only knows "did it throw" cannot tell an already-absent ref (GitHub's own "Automatically
+ * delete head branches", enabled 2026-09-08, routinely beats this call to it — the NORMAL case) from
+ * a REAL failure (bad auth, a protected-branch rule, a network timeout) — both used to be swallowed
+ * identically, and `MaintenanceResult.cleanedUpBranches` reported the task either way even though
+ * its own JSDoc promises "this pass deleted" the branch. Only `FAILED` must keep a task OUT of that
+ * field; `DELETED` and `ALREADY_GONE` both mean the remote ref is confirmed gone.
+ */
+export const REMOTE_BRANCH_DELETE_RESULT = {
+  DELETED: 'deleted',
+  ALREADY_GONE: 'already-gone',
+  FAILED: 'failed',
+} as const;
+
+export type RemoteBranchDeleteResult =
+  (typeof REMOTE_BRANCH_DELETE_RESULT)[keyof typeof REMOTE_BRANCH_DELETE_RESULT];
+
+export interface MaintenanceBacklog {
+  setStatus(taskId: string, status: TaskStatus, comment?: string): void;
+  /** Records a comment WITHOUT moving the task — for news a person needs but that decides nothing. */
+  comment(taskId: string, comment: string): void;
+}
+
+export interface SaveWipResult {
+  pushSucceeded: boolean;
+}
+
+export interface MaintenanceGit {
+  /** `git status --porcelain -- .backlog` in the main checkout, collapsed to a boolean. */
+  hasPendingBacklogChanges(): boolean;
+  /** `git add .backlog && git commit -m <message>` in the main checkout. */
+  commitBacklogChanges(message: string): void;
+  /** WIP-commits and pushes the worker's current changes on `branch` (manual-cancellation save). */
+  saveWipAndPush(branch: string): SaveWipResult;
+  /**
+   * Leaves the slot at `slotPath` on a detached HEAD. Every release the sweep performs calls it:
+   * git refuses a branch checked out in two worktrees, so a slot released while still on
+   * `task/T-nn` makes every later dispatch of that task hit `branch-in-use` — and with one task
+   * dispatched per pass, the whole queue starves behind it. Never throws.
+   */
+  detachSlot(slotPath: string): void;
+  /**
+   * Whether `branch` exists at all, local or remote. T-8 point 7's ONLY way to tell "a hand-written
+   * `Done` with legitimately no PR" apart from "a hand-written `Done` whose PR GitHub has not
+   * reported merged": a branch that was never pushed can never have a PR either, so `false` here is
+   * what lets that task through untouched.
+   *
+   * OPTIONAL until `dispatch.ts`'s real `git` collaborator wires it: step 3b treats a missing
+   * `branchExists` as "no branch found", which is the same "leave it alone" outcome an unwired
+   * caller got before T-8 point 7 existed — never a revert nobody asked for.
+   */
+  branchExists?(branch: string): boolean;
+  /**
+   * `git branch -D <branch>` in the main checkout — T-8 point 5, called only once a task reaches
+   * `Done` within this pass. By that point the slot that held it has already released and detached
+   * (this pass's own step 1/2, or the close that finished it earlier), so the local ref has no
+   * worktree holding it and this cannot collide with git's "branch checked out elsewhere" refusal.
+   * Tolerant of an absent local ref — the common case for a task never checked out in the main
+   * checkout at all — never throws.
+   *
+   * OPTIONAL until wired: `cleanupBranchOnDone` calls it through optional chaining, so an unwired
+   * caller still gets the `Done` transition itself (step 3/5's own job) with no branch cleanup —
+   * never a crash on a collaborator method that does not exist yet.
+   */
+  deleteLocalBranch?(branch: string): void;
+  /**
+   * `git push origin --delete <branch>` — T-8 point 5's remote half. Returns the OUTCOME rather
+   * than swallowing it (defect 7, 2026-09-08): `already-gone` when the remote ref was already
+   * absent — GitHub's own "Automatically delete head branches" (enabled 2026-09-08) routinely
+   * beats this call to it, so that is the NORMAL case, not a failure — `deleted` when this call
+   * removed it, and `failed` for anything else (bad auth, a protected-branch rule, a network
+   * timeout): a REAL failure the caller must not silently count as cleanup. Never throws. OPTIONAL
+   * for the same reason as `deleteLocalBranch`; an unwired caller reports the same "cleaned up"
+   * outcome `cleanupBranchOnDone` gave before this outcome-returning contract existed.
+   */
+  deleteRemoteBranch?(branch: string): RemoteBranchDeleteResult;
+  /**
+   * The safety check `cleanupBranchOnDone` runs before EITHER delete — the remaining T-8 point 5
+   * data-loss path (2026-09-08). Two T-8 fixes already on this branch interact to open it: the
+   * recovery retry (step 0) and the dead-worker rescue (step 1) deliberately still push on a `gh`
+   * outage — `unknown` reads as "not confirmed merged" (see `isBranchConfirmedMerged`'s own JSDoc),
+   * because refusing to push on mere uncertainty risks losing the only copy of the work. When `gh`
+   * recovers and later reports the SAME branch's PR as `merged`, this pass used to delete both refs
+   * unconditionally — turning a rescue push that landed AFTER the merge into commits destroyed
+   * outright rather than merely stranded (the T-6.3 incident T-8 point 5 already cites, made
+   * worse instead of better by the branch-deletion it introduced).
+   *
+   * `baseRef` is `origin/<base>` from `guards.ts`'s `taskBaseBranch` — the SAME naming a subtask's
+   * scope check and PR diff already use. Comparing against a hand-rolled `main` would report every
+   * commit a subtask's PARENT branch already carries as this subtask's own extra work and refuse
+   * every subtask cleanup.
+   *
+   * `true` means "confirmed extra commits beyond `baseRef`, OR the comparison itself could not be
+   * trusted" — deletion is destructive, so both collapse to the same refusal; only a comparison
+   * that POSITIVELY confirms zero extra commits returns `false`. A branch with no surviving remote
+   * ref at all (already deleted — GitHub's own auto-delete, or an earlier pass) has nothing left to
+   * lose either way, and the real implementation reads that as `false` too: there is nothing to
+   * refuse.
+   *
+   * OPTIONAL until `dispatch.ts` wires a real implementation — but unlike `deleteLocalBranch`/
+   * `deleteRemoteBranch`, an unwired caller here must NOT silently fall back to the old
+   * unconditional-delete behaviour: `cleanupBranchOnDone` treats an absent method as `true`
+   * (refuse), the fail-safe default.
+   */
+  branchHasUnmergedCommits?(branch: string, baseRef: string): boolean;
+}
+
+export interface MaintenanceContext {
+  now: number;
+  /** Lock TTL in ms — a heartbeat older than this is treated as dead even with a live PID. */
+  ttlMs: number;
+  /**
+   * T-8 point 10's fourth orphan check, in ms — `lanes.json`'s `orphanInProgressThresholdHours`
+   * (default 4h) converted by the caller. It is the ONLY thing standing between this sweep and a
+   * live interactive session: a person working a task by hand leaves the exact same absence of
+   * lock, slot and attempt directory an abandoned task does, and survives only because working the
+   * task (writing notes, a plan, a comment) refreshes `updated_date`.
+   *
+   * `undefined` disables step 3c ENTIRELY rather than falling back to a hidden default: until
+   * `dispatch.ts` reads `lanes.json`'s new field and passes it here, no context in the codebase
+   * supplies one, and guessing a number would start blocking `In Progress` tasks in every OTHER
+   * caller's tests the moment this field shipped — a behaviour change nobody asked those callers
+   * to accept. A caller that wants the sweep MUST pass the real value explicitly.
+   *
+   * `0` is never a legal VALUE of this field (defect 12, 2026-09-08): `launch.ts`'s
+   * `resolveOrphanInProgressThresholdMs` is where a configured `0` hours (an operator's explicit
+   * "turn the sweep off") turns into `undefined` before it ever reaches this context — a bare `0`
+   * here would instead make step 3c the MOST aggressive setting possible (`ageMs <= 0` is false for
+   * any real task age), the opposite of what `0` is supposed to mean.
+   */
+  orphanInProgressThresholdMs?: number;
+  isPidAlive: (pid: number) => boolean;
+  /** A snapshot of every task on the board, as read for this pass. */
+  tasks: Task[];
+  /**
+   * Whether that snapshot is the WHOLE board. False when `backlog task list` failed outright, or
+   * when any single `task view` threw and its id was dropped (`dispatch.ts`'s `loadBoard`).
+   *
+   * It gates every inference this pass would otherwise draw from a task's ABSENCE. "Not on the
+   * board" means "a person deleted it" only when the board was read in full; on a partial read the
+   * same absence is a CLI failure, and step 4 reading it as a cancellation killed every live worker
+   * at once. Step 5 is skipped for the same reason from the other direction: a parent's state is
+   * derived from the full set of its children, and half a set derives a wrong answer confidently.
+   */
+  boardComplete: boolean;
+  fs: MaintenanceFs;
+  gh: MaintenanceGh;
+  backlog: MaintenanceBacklog;
+  git: MaintenanceGit;
+  killProcess: (pid: number) => void;
+  /** Desktop notification. Used only where the sweep gives up and needs a person to look. */
+  notify: (title: string, body: string) => void;
+}
+
+// ── Result ──────────────────────────────────────────────────────────────────────
+
+export interface RecomputedParent {
+  id: string;
+  from: TaskStatus;
+  to: TaskStatus;
+}
+
+export interface MaintenanceResult {
+  releasedLocks: string[];
+  releasedOrphanSlots: string[];
+  movedToDone: string[];
+  cancelledWorkers: string[];
+  recomputedParents: RecomputedParent[];
+  committedBoard: boolean;
+  /** Slots whose pending push finally succeeded this pass, and were then released. */
+  recoveredPushes: string[];
+  /** Slots left held because their work could not be pushed — never reassigned until it is. */
+  heldForRecovery: string[];
+  /** Tasks whose push retries hit `MAX_RECOVERY_ATTEMPTS` this pass: a person must rescue them. */
+  exhaustedRecoveries: string[];
+  /**
+   * T-8 point 5: tasks whose `task/<id>` branch this pass deleted (local, then remote) on reaching
+   * `Done`. Defect 7 (2026-09-08): this now means what it says — a task lands here only when the
+   * REMOTE half is confirmed gone (`deleted` or `already-gone`), never on a `failed` outcome from
+   * `MaintenanceGit.deleteRemoteBranch`. See `cleanupBranchOnDone`'s own JSDoc.
+   */
+  cleanedUpBranches: string[];
+  /**
+   * Tasks whose `task/<id>` branch this pass reached `Done` on but did NOT delete because it
+   * carries at least one commit not reachable from its base (or the check could not confirm
+   * otherwise) — the fourth outcome `MaintenanceGit.branchHasUnmergedCommits` exists for, distinct
+   * from both `cleanedUpBranches` (deleted, or already gone) and a genuine remote-delete FAILURE
+   * (logged via `console.error`, absent from every result array, same as before this check
+   * existed). A task lands here with a comment on the board naming the branch and its base, so a
+   * person can rescue the commits by hand.
+   */
+  branchCleanupRefused: string[];
+  /** T-8 point 7: hand-written `Done` tasks this pass reverted to `In Progress` because GitHub does not report their PR merged. */
+  revertedHandwrittenDone: string[];
+  /** T-8 point 10: orphan `In Progress` tasks this pass moved to `Blocked`. */
+  orphanInProgressBlocked: string[];
+  /**
+   * Defect 8 (2026-09-08): task ids whose recovery retry (step 0) or dead-worker rescue (step 1)
+   * this pass refused to push AT ALL because the branch's PR already reads `merged` — the SAME
+   * push gate `close.ts`'s `checkBranchNotMerged` (T-8 point 4) already applies before the
+   * close's own pushes, extended here to maintenance's two pushers. Pushing anyway would have
+   * landed commits nobody would ever look at (the branch's own PR already merged without them),
+   * and T-8 point 5 now deletes that branch once the task reaches `Done` — so a commit landed
+   * there is not merely stranded, it is destroyed (the T-6.3 incident this task cites). See
+   * `isBranchConfirmedMerged`'s own JSDoc for why `unknown` never lands a task here.
+   */
+  pushRefusedMergedBranches: string[];
+  /**
+   * The registry AFTER every release this pass performed. The caller must use THIS for slot
+   * acquisition: reading `slots.json` again before maintenance ran (or using the snapshot it was
+   * given) sees a slot as busy that this very pass just freed, so the task waits a whole interval
+   * for a slot that is already available.
+   */
+  slots: SlotRegistry;
+}
+
+const branchFor = (taskId: string): string => `task/${taskId}`;
+
+/**
+ * How many times a pending push is retried before the sweep stops and hands the slot to a person.
+ * Three, matching the dispatch attempt cap: a push that failed three times is failing for a reason
+ * no further retry addresses, and retrying forever keeps one of three slots permanently out of the
+ * pool while saying nothing about it.
+ */
+export const MAX_RECOVERY_ATTEMPTS = 3;
+
+/**
+ * Builds the derivation tree `deriveParentStatus` expects, recursing into grandchildren.
+ *
+ * T-8: `tier` and `closeAttempted` are only meaningful for a node that IS a parent (non-empty
+ * `children`), so a leaf gets neither — `deriveParentStatus` never looks at them for a leaf either.
+ * `closeAttempted` is read from `fs.hasCloseAttemptBeenEnqueued` — the durable ENQUEUE-time marker
+ * (T-8 defect 3, 2026-09-08), not from `task.attempts > 0` (a count of `intento-N` directories
+ * `beginAttempt` creates LATE — after every guard, after `provisionSlot`, after `prepareSlot`,
+ * after `buildLaunch` — see `MaintenanceFs.hasCloseAttemptBeenEnqueued`'s own JSDoc for the four
+ * paths that left `attempts` at `0` forever under the old signal).
+ *
+ * Exported (defect 11, 2026-09-08): `dispatch.ts` builds the SAME tree, with the SAME `gh`/`fs`, to
+ * answer `prompt.ts`'s `isParentCloseAttempt` — see `parent.ts`'s `effectiveStatus` for why that
+ * question must go through this recursion rather than a child's literal board status.
+ */
+export function toDerivationNode(
+  taskId: string,
+  tasksById: Record<string, Task>,
+  gh: Pick<MaintenanceGh, 'isPrMerged'>,
+  fs: Pick<MaintenanceFs, 'hasCloseAttemptBeenEnqueued'>,
+): ParentDerivationNode {
+  const children = Object.values(tasksById).filter((task) => task.parentId === taskId);
+  const own = tasksById[taskId];
+  if (children.length === 0) {
+    return { status: own.status };
+  }
+  return {
+    status: own.status,
+    children: children.map((child) => toDerivationNode(child.id, tasksById, gh, fs)),
+    ownPrMerged: gh.isPrMerged(branchFor(taskId)),
+    tier: own.tier,
+    closeAttempted: fs.hasCloseAttemptBeenEnqueued(taskId),
+  };
+}
+
+export interface RecomputeParentInput {
+  parentId: string;
+  /** The board snapshot, keyed by id — children are found by their `parentId`. */
+  tasksById: Record<string, Task>;
+  /**
+   * `isPrMerged` feeds `toDerivationNode`'s recursive tree (nested parents, unaffected by F1
+   * below); `mergedState` is what THIS parent's own merge state is decided from when every child is
+   * Done (F1, 2026-09-08). The two-line claim this JSDoc used to make — "only `isPrMerged` is used,
+   * the derivation never needs the branch's PR state text" — was wrong: `isPrMerged` collapses a
+   * genuine "not merged" and a `gh` outage (missing binary, expired token, network down) into the
+   * SAME `false` (see `MaintenanceGh.mergedState`'s own JSDoc for the identical trap step 3b was
+   * built to avoid), and when every child is Done, THIS parent's own merge state is the one thing
+   * standing between `Done` and a derived `In Progress`/`Queued` that differs from the board and
+   * therefore gets WRITTEN. `mergedState` is optional for the same reason it is everywhere else in
+   * this module: an unwired caller must default to `unknown`, never to a guessed answer.
+   */
+  gh: Pick<MaintenanceGh, 'isPrMerged' | 'mergedState'>;
+  /** Only `setStatus` is used: a derivation either moves the parent or does nothing at all. */
+  backlog: Pick<MaintenanceBacklog, 'setStatus'>;
+  /**
+   * The durable "has rule 4 already fired for this parent, ever" signal (T-8 defect 3) — see
+   * `MaintenanceFs.hasCloseAttemptBeenEnqueued`'s own JSDoc. Required, not optional: unlike
+   * `prState`/`branchExists`/`mergedState` elsewhere in this module, there is no safe "unwired"
+   * default here — defaulting to `false` would silently resurrect the bug this signal exists to
+   * close (every caller re-deriving `Queued` forever for a parent that already ran once).
+   */
+  fs: Pick<MaintenanceFs, 'hasCloseAttemptBeenEnqueued' | 'markCloseAttemptEnqueued'>;
+}
+
+/**
+ * Recomputes ONE parent's derived state and writes it only if it changed. Exported because the
+ * dispatch close's `recompute-parent` step needs it synchronously — a subtask that just finished
+ * must move its parent before anyone looks at the board, not on whatever pass comes next (spec:
+ * "Dispatch close ordering"). `runMaintenance`'s own step 5 is this same function over every
+ * parent, so the derivation has one implementation and one set of tests.
+ *
+ * F1 [BLOCKER], 2026-09-08: when every child is Done, `deriveParentStatus`'s rules 3/4/6 all key
+ * off whether THIS parent's own PR merged — the one case `toDerivationNode`'s `isPrMerged`-sourced
+ * `ownPrMerged` is unsafe for (see `RecomputeParentInput.gh`'s own JSDoc). So this function asks
+ * `mergedState` for THAT one branch, exactly once, only when it would actually be consulted, and
+ * bails entirely — `return null`, deriving nothing this pass, same as step 3b's own `unknown` skip
+ * — rather than let a two-state `false` read as "GitHub confirms not merged" and write a derived
+ * `In Progress` (or, worse, a Complex parent's `Queued`, burning the irreversible one-shot close-
+ * attempt marker) on top of a `Done` board is actually correct about.
+ */
+export function recomputeParent(input: RecomputeParentInput): RecomputedParent | null {
+  const parentTask = input.tasksById[input.parentId];
+  if (!parentTask) {
+    return null; // a declared --parent id absent from this board snapshot: nothing to recompute.
+  }
+
+  const node = toDerivationNode(input.parentId, input.tasksById, input.gh, input.fs);
+  const children = node.children ?? [];
+
+  // Only the all-Done branch of `deriveParentStatus` (rules 3/4/6) ever reads `ownPrMerged` — every
+  // other outcome (Blocked, active, a Done/To-Do mix, all To Do) is decided by the children's
+  // statuses alone. So the merge-state question is asked, and can bail the WHOLE derivation, only
+  // when it would actually matter.
+  const allChildrenDone =
+    children.length > 0 && children.every((child) => effectiveStatus(child) === TASK_STATUS.DONE);
+  let ownPrMerged = node.ownPrMerged ?? false;
+  if (allChildrenDone) {
+    const mergeState = input.gh.mergedState?.(branchFor(input.parentId)) ?? PR_MERGE_STATE.UNKNOWN;
+    if (mergeState === PR_MERGE_STATE.UNKNOWN) {
+      return null; // gh outage: cannot tell "merged" from "not yet" — say nothing this pass.
+    }
+    ownPrMerged = mergeState === PR_MERGE_STATE.MERGED;
+  }
+
+  const newStatus = deriveParentStatus(
+    children,
+    ownPrMerged,
+    node.tier,
+    node.closeAttempted ?? false,
+  );
+
+  // F2 [MEDIUM], 2026-09-08: `TASK_STATUS.QUEUED` is returned by `deriveParentStatus` ONLY when
+  // rule 4 fires (the tri-state `closeAttempted` false-branch — rule 5 answers `null` instead when
+  // it is true), so this condition alone is rule 4 firing, independent of whether the board already
+  // reads `Queued`. The marker must be set THEN, not only when the write below actually happens: a
+  // person can set a Complex parent to `Queued` by hand while children are still running (the
+  // release flow, section 10 of the skill); once the last one finishes, rule 4 derives `Queued`
+  // again — same as the board — and skipping the marker here would leave it `false` even though the
+  // one automated close attempt this pass is ABOUT to consume just started. The next pass, reading
+  // that stale `false`, would then re-derive `Queued` on top of whatever the close attempt left
+  // behind (a live retry, or worse, a human-facing `Blocked` review), clobbering it.
+  if (newStatus === TASK_STATUS.QUEUED) {
+    input.fs.markCloseAttemptEnqueued(input.parentId);
+  }
+
+  if (newStatus === null || newStatus === parentTask.status) {
+    return null;
+  }
+
+  input.backlog.setStatus(input.parentId, newStatus);
+  return { id: input.parentId, from: parentTask.status, to: newStatus };
+}
+
+/**
+ * The `Blocked` comment a swept dead worker leaves behind: what happened, where the work is, and
+ * whether it survived — the three things a person needs before deciding to re-queue.
+ */
+function deadWorkerComment(lock: DispatchLock, workSaved: boolean): string {
+  const pid = lock.workerPid ?? lock.pid;
+  return `el worker murió sin cerrar (pid ${pid}); rama ${lock.branch}; trabajo guardado: ${workSaved ? 'sí' : 'no'}`;
+}
+
+/**
+ * Defect 8 (2026-09-08): the SAME push gate `close.ts`'s `checkBranchNotMerged` (T-8 point 4)
+ * already applies before the close's own pushes, extended to maintenance's two other pushers — the
+ * recovery retry (step 0) and the dead-worker rescue (step 1). Neither consulted it before, so
+ * either could still land commits on a branch whose PR already merged; T-8 point 5 now deletes
+ * that branch once the task reaches `Done`, turning a stranded commit into a destroyed one (the
+ * T-6.3 incident this task cites).
+ *
+ * Reuses the SAME tri-state `mergedState` step 3b relies on (T-8 defect 1) rather than
+ * `isPrMerged`'s boolean, specifically so `unknown` (a `gh` outage — missing binary, expired
+ * token, network down) gets a DELIBERATE answer instead of collapsing into the same `false` a
+ * confirmed "not merged" gets. The answer for `unknown` is still "not confirmed merged" — i.e.
+ * this returns `false`, and the push proceeds — because both callers exist to RESCUE work that
+ * might otherwise be the only copy left: a dead worker's slot about to be released, or a WIP push
+ * that has already failed once. Refusing to push on a mere `gh` hiccup sacrifices that whole
+ * purpose for a maybe; the worst case of pushing under genuine uncertainty is a few commits that
+ * land on an already-merged branch and go unused (recoverable — they still exist, on the remote),
+ * while the worst case of refusing is the ONLY copy of the work never reaching the remote at all.
+ * Only a CONFIRMED `merged` answer blocks the push.
+ */
+function isBranchConfirmedMerged(gh: Pick<MaintenanceGh, 'mergedState'>, branch: string): boolean {
+  return (gh.mergedState?.(branch) ?? PR_MERGE_STATE.UNKNOWN) === PR_MERGE_STATE.MERGED;
+}
+
+/**
+ * Defect 8's `Blocked` comment for the dead-worker rescue (step 1): unlike `deadWorkerComment`,
+ * the push was never attempted — pushing would have landed commits on a branch whose PR already
+ * merged, silently lost the moment T-8 point 5 deletes that branch. Names the branch and the slot
+ * so a person can decide by hand whether the unpushed work still matters.
+ */
+function deadWorkerBranchAlreadyMergedComment(lock: DispatchLock): string {
+  const pid = lock.workerPid ?? lock.pid;
+  return (
+    `el worker murió sin cerrar (pid ${pid}); la PR de ${lock.branch} ya consta como mergeada, así ` +
+    'que el trabajo pendiente en el slot NO se empujó (habría llegado después de la mergeada y se ' +
+    'habría perdido en silencio al borrarse la rama — T-6.3). Revísalo a mano en el slot antes de liberarlo.'
+  );
+}
+
+/**
+ * Defect 8's comment for the recovery retry (step 0) when it stops for the same reason: the held
+ * WIP was never pushed because the branch's PR already merged, so retrying it again next pass would
+ * only repeat the same refusal. Names the branch and the slot path, same as the exhausted-retries
+ * comment just below.
+ */
+function recoveryBranchAlreadyMergedComment(branch: string, slotPath: string): string {
+  return (
+    `recuperación del push detenida: la PR de ${branch} ya consta como mergeada, así que el WIP ` +
+    `pendiente en ${slotPath} no se empujó (habría llegado después de la mergeada y se habría ` +
+    'perdido en silencio al borrarse la rama — T-6.3). Revísalo a mano.'
+  );
+}
+
+/**
+ * The three outcomes `cleanupBranchOnDone` can report — the safety check adds a genuine THIRD
+ * outcome, distinct from both success and a delete failure (see `MaintenanceResult
+ * .branchCleanupRefused`'s own JSDoc for what tells each apart in the result).
+ */
+export const BRANCH_CLEANUP_OUTCOME = {
+  /** Both refs confirmed gone this pass, or already absent — `MaintenanceResult#cleanedUpBranches`. */
+  CLEANED: 'cleaned',
+  /**
+   * The branch carries commits beyond its base (or the check could not confirm otherwise): NEITHER
+   * ref was touched. `MaintenanceResult#branchCleanupRefused`.
+   */
+  REFUSED_UNMERGED_COMMITS: 'refused-unmerged-commits',
+  /**
+   * The safety check passed (the branch is confirmed clean) but the remote delete itself genuinely
+   * failed (bad auth, a protected-branch rule, a network timeout) — logged via `console.error`,
+   * absent from BOTH result arrays, exactly as an unconditional failure read before this check
+   * existed (defect 7, 2026-09-08).
+   */
+  DELETE_FAILED: 'delete-failed',
+} as const;
+
+export type BranchCleanupOutcome =
+  (typeof BRANCH_CLEANUP_OUTCOME)[keyof typeof BRANCH_CLEANUP_OUTCOME];
+
+/**
+ * T-8 point 5: deletes the `task/<id>` branch once a task reaches `Done` WITHIN THIS PASS — local
+ * first, then the remote copy if GitHub's own "Automatically delete head branches" has not already
+ * removed it. Called from exactly two places, both a task's own transition TO `Done` (step 3's
+ * generic merged-PR check, and step 5's parent recomputation): never from a transition to
+ * `Blocked`, which is the whole point — a blocked task's branch is the only copy of the work a
+ * person will come back to.
+ *
+ * BEFORE touching either ref, verifies the branch carries nothing beyond `baseRef` (the remaining
+ * data-loss path this same point still had: a `gh`-outage rescue push landing WIP commits on a
+ * branch whose PR turns out already merged — see `MaintenanceGit.branchHasUnmergedCommits`'s own
+ * JSDoc for the full incident shape). A branch that fails that check is left ENTIRELY alone —
+ * neither `deleteLocalBranch` nor `deleteRemoteBranch` runs — and the caller reports
+ * `REFUSED_UNMERGED_COMMITS` rather than attempting a delete that would destroy the very commits a
+ * person needs to rescue.
+ *
+ * Only once the branch is confirmed clean does this call `deleteLocalBranch`/`deleteRemoteBranch`,
+ * returning whether the remote branch is CONFIRMED gone — `deleted` this pass, or already absent —
+ * so the caller can decide whether this task truly belongs in `cleanedUpBranches` (defect 7,
+ * 2026-09-08). A refused delete (bad auth, a protected-branch rule, a network timeout) used to be
+ * swallowed identically to the harmless "already gone" case and still counted as cleanup — leaving
+ * the remote ref alive with no log line and no way to tell from `MaintenanceResult` alone. An
+ * unwired `deleteRemoteBranch` (or a `deleteLocalBranch`-only collaborator) reports success here,
+ * matching this function's behavior before the outcome-returning contract existed.
+ */
+function cleanupBranchOnDone(
+  taskId: string,
+  git: Pick<
+    MaintenanceGit,
+    'deleteLocalBranch' | 'deleteRemoteBranch' | 'branchHasUnmergedCommits'
+  >,
+  baseRef: string,
+): BranchCleanupOutcome {
+  const branch = branchFor(taskId);
+  // Fail-safe default when unwired (see the method's own JSDoc): `true`, never the old
+  // unconditional-delete behaviour this check exists to replace.
+  const hasUnmergedCommits = git.branchHasUnmergedCommits?.(branch, baseRef) ?? true;
+  if (hasUnmergedCommits) {
+    console.error(
+      `maintenance.ts: task/${taskId} carries commits not reachable from ${baseRef}; leaving both ` +
+        'refs alone for a person to rescue.',
+    );
+    return BRANCH_CLEANUP_OUTCOME.REFUSED_UNMERGED_COMMITS;
+  }
+  // Both methods are optional (see their own JSDoc): an unwired `git` collaborator still gets the
+  // `Done` transition itself, just no branch cleanup, rather than a crash on a missing method.
+  git.deleteLocalBranch?.(branch);
+  const remoteResult = git.deleteRemoteBranch?.(branch);
+  if (remoteResult === REMOTE_BRANCH_DELETE_RESULT.FAILED) {
+    console.error(
+      `maintenance.ts: git push origin --delete task/${taskId} failed; the remote branch is still alive.`,
+    );
+    return BRANCH_CLEANUP_OUTCOME.DELETE_FAILED;
+  }
+  return BRANCH_CLEANUP_OUTCOME.CLEANED;
+}
+
+/**
+ * `branchCleanupRefused`'s board comment: names the branch and the base it was compared against, so
+ * a person can rescue the commits without first working out where the dispatcher measured from.
+ */
+function branchCleanupRefusedComment(branch: string, baseRef: string): string {
+  return (
+    `rama ${branch} NO borrada: conserva commits que no están en ${baseRef} (posible push de ` +
+    'rescate sobre una PR ya mergeada — T-6.3). Revísala a mano antes de borrarla.'
+  );
+}
+
+/**
+ * T-8 point 7's revert comment: names the branch and the PR state GitHub reported, so a person can
+ * decide whether to re-merge, reopen, or abandon the work without opening GitHub first.
+ */
+function revertedHandwrittenDoneComment(branch: string, prState: string | null): string {
+  const state = prState ?? 'sin PR';
+  return `Done escrito a mano revertido a In Progress: la rama ${branch} existe pero GitHub no reporta su PR como mergeada (estado: ${state}).`;
+}
+
+/**
+ * T-8 point 10's `Blocked` comment: names all four checks and their result, so the person releasing
+ * the task can act without investigating — the same reason `deadWorkerComment` above states what it
+ * found rather than just "dead worker".
+ */
+function orphanInProgressComment(taskId: string, ageMs: number, thresholdMs: number): string {
+  const ageHours = (ageMs / 3_600_000).toFixed(1);
+  const thresholdHours = (thresholdMs / 3_600_000).toFixed(1);
+  return (
+    `In Progress huérfano: sin lock en .backlog/.dispatch/locks/, sin slot en slots.json, ` +
+    `sin carpeta de intento .backlog/.dispatch/${taskId}/, y con updated_date de hace ${ageHours}h ` +
+    `(umbral ${thresholdHours}h). Si era una sesión interactiva viva, corrígelo a mano y refresca la tarea.`
+  );
+}
+
+/** Header + body for the board commit. One line per transition in the body, header stays short. */
+export function buildBoardCommitMessage(transitions: readonly string[]): string {
+  if (transitions.length === 0) {
+    return 'chore(backlog): sync board state (housekeeping)';
+  }
+  if (transitions.length === 1) {
+    return `chore(backlog): sync board state (${transitions[0]})`;
+  }
+  // commitlint caps the HEADER at 100 characters, and a pass that moved eight tasks would blow past
+  // it with a comma list — so the header counts, and the body enumerates.
+  return [
+    `chore(backlog): sync board state (${transitions.length} transitions)`,
+    '',
+    ...transitions,
+  ].join('\n');
+}
+
+/**
+ * Runs the maintenance pass. Pure orchestration over injected collaborators — every mutation
+ * (removing a lock, releasing a slot, editing a task's status, committing the board) goes through
+ * `ctx`, so a caller building the real context wires real fs/git/gh/backlog, and a test wires
+ * recording fakes.
+ */
+export function runMaintenance(ctx: MaintenanceContext): MaintenanceResult {
+  const registry = ctx.fs.readSlots();
+  let slots: SlotInfo[] = registry.slots;
+
+  // Every slot change is recorded as a TRANSFORM as well as applied to the local snapshot the rest
+  // of the pass decides on. The snapshot answers "what does this pass still have to do"; the
+  // transforms are replayed against the registry as it is at write time (see the single
+  // `updateSlots` call at the end), so a slot another pass touched meanwhile keeps its change.
+  const pendingTransforms: Array<(slots: SlotInfo[]) => SlotInfo[]> = [];
+  const applySlotChange = (transform: (slots: SlotInfo[]) => SlotInfo[]): void => {
+    pendingTransforms.push(transform);
+    slots = transform(slots);
+  };
+
+  const releaseSlotFor = (taskId: string): void => {
+    // Detach FIRST and eagerly, against the snapshot that still names the slot: the registry write
+    // is replayed at the end of the pass, and by then this entry no longer says where the work is.
+    const slotPath = slots.find((slot) => slot.taskId === taskId)?.path;
+    if (slotPath) {
+      ctx.git.detachSlot(slotPath);
+    }
+    applySlotChange((entries) => releaseSlotEntries(entries, taskId));
+  };
+  const holdForRecovery = (taskId: string): void => {
+    applySlotChange((entries) =>
+      entries.map((slot) => (slot.taskId === taskId ? { ...slot, heldForRecovery: true } : slot)),
+    );
+  };
+  const clearRecoveryHold = (slotName: string): void => {
+    applySlotChange((entries) =>
+      entries.map((slot) =>
+        slot.name === slotName ? { ...slot, heldForRecovery: false, recoveryAttempts: 0 } : slot,
+      ),
+    );
+  };
+  const countRecoveryAttempt = (slotName: string, attempts: number): void => {
+    applySlotChange((entries) =>
+      entries.map((slot) =>
+        slot.name === slotName ? { ...slot, recoveryAttempts: attempts } : slot,
+      ),
+    );
+  };
+
+  // `gh pr view`/`gh pr list` is a network round-trip per branch, and the same branch is asked
+  // about by step 3, step 3b (point 7's revert check) and every parent derivation below. One answer
+  // per branch per pass, for each of the two questions asked here — `prState` is asked at most once
+  // per hand-written `Done`, so it is never worth caching and step 3b calls `ctx.gh.prState`
+  // directly. `mergedState` joined this cache alongside `isPrMerged` for F1 (2026-09-08):
+  // `recomputeParent` (step 5) now asks it for every all-Done parent, on top of whatever step 3/3b
+  // already asked it for the SAME branch this same pass.
+  const prMergedCache = new Map<string, boolean>();
+  const mergeStateCache = new Map<string, PrMergeState>();
+  const gh: Pick<MaintenanceGh, 'isPrMerged' | 'mergedState'> = {
+    isPrMerged: (branch) => {
+      const cached = prMergedCache.get(branch);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const merged = ctx.gh.isPrMerged(branch);
+      prMergedCache.set(branch, merged);
+      return merged;
+    },
+    mergedState: (branch) => {
+      const cached = mergeStateCache.get(branch);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const state = ctx.gh.mergedState?.(branch) ?? PR_MERGE_STATE.UNKNOWN;
+      mergeStateCache.set(branch, state);
+      return state;
+    },
+  };
+
+  const tasksById: Record<string, Task> = Object.fromEntries(
+    ctx.tasks.map((task) => [task.id, task]),
+  );
+  const transitions: string[] = [];
+
+  // ── Step 0: retry the pushes a previous pass could not complete ──
+  // Runs FIRST so a slot whose work finally reached the remote is available to this same pass's
+  // task selection. A slot marked in THIS pass is not retried here — it just failed.
+  const recoveredPushes: string[] = [];
+  const exhaustedRecoveries: string[] = [];
+  const pushRefusedMergedBranches: string[] = [];
+  for (const slot of slots) {
+    if (!slot.heldForRecovery || !slot.taskId) {
+      continue;
+    }
+    const taskId = slot.taskId;
+    const priorAttempts = slot.recoveryAttempts ?? 0;
+    // Already given up on: a person owns this slot now, and retrying would only re-notify them.
+    if (priorAttempts >= MAX_RECOVERY_ATTEMPTS) {
+      continue;
+    }
+    // Defect 8: a branch whose PR already merged never gets retried — see `isBranchConfirmedMerged`
+    // for why `unknown` does not land here, only a CONFIRMED merge. Marked exhausted immediately
+    // (not incremented one attempt at a time) because a merge does not un-merge on the next pass —
+    // reusing the SAME cap the comment/notify above it already guards against renotifying forever.
+    if (isBranchConfirmedMerged(ctx.gh, branchFor(taskId))) {
+      countRecoveryAttempt(slot.name, MAX_RECOVERY_ATTEMPTS);
+      const comment = recoveryBranchAlreadyMergedComment(branchFor(taskId), slot.path);
+      ctx.backlog.comment(taskId, comment);
+      ctx.notify(`${taskId}: rama ya mergeada`, comment);
+      pushRefusedMergedBranches.push(taskId);
+      continue;
+    }
+    if (!ctx.git.saveWipAndPush(branchFor(taskId)).pushSucceeded) {
+      const attempts = priorAttempts + 1;
+      countRecoveryAttempt(slot.name, attempts);
+      if (attempts >= MAX_RECOVERY_ATTEMPTS) {
+        // The comment names the EXACT manual step, because nothing automatic will take this slot
+        // back: the hold is what keeps the only copy of the work safe, and only a person clears it.
+        const rescue =
+          `recuperación del push agotada: rescata a mano la rama ${branchFor(taskId)} en ${slot.path}. ` +
+          `Cuando la rama esté en el remoto, ejecuta \`pnpm backlog:dispatch -- --release-slot ${slot.name}\` ` +
+          '(o borra `heldForRecovery` y `recoveryAttempts` de ese slot en `.backlog/.dispatch/slots.json`).';
+        ctx.backlog.comment(taskId, rescue);
+        ctx.notify(`${taskId}: rescate manual`, rescue);
+        exhaustedRecoveries.push(taskId);
+      }
+      continue;
+    }
+    clearRecoveryHold(slot.name);
+    releaseSlotFor(taskId);
+
+    // The recovered push is NEWS, not a decision. Re-asserting `Blocked` here would drag a task a
+    // person already released (to `Queued`, or to `To Do` to work it by hand) straight back out of
+    // the column they moved it to. Only a task still sitting in `Blocked` gets the status write —
+    // and even then it is the same status, kept so the comment lands the same way it always has.
+    const status = tasksById[taskId]?.status;
+    const recovered = `push recuperado: ${branchFor(taskId)} ya está en el remoto.`;
+    if (status === TASK_STATUS.BLOCKED) {
+      ctx.backlog.setStatus(taskId, TASK_STATUS.BLOCKED, recovered);
+    } else {
+      ctx.backlog.comment(taskId, recovered);
+    }
+    recoveredPushes.push(taskId);
+  }
+
+  // ── Step 1: sweep dead/expired locks, SAVING their work before releasing anything ──
+  const releasedLocks: string[] = [];
+  const heldForRecovery: string[] = [];
+  const aliveLocksByTaskId = new Map<string, DispatchLock>();
+  for (const lock of ctx.fs.readLocks()) {
+    if (isLockAlive(lock, ctx.now, ctx.ttlMs, ctx.isPidAlive)) {
+      aliveLocksByTaskId.set(lock.taskId, lock);
+      continue;
+    }
+
+    // An EXPIRED heartbeat whose worker is still running is a hung worker, not a dead one: kill it
+    // first, or the sweep releases the slot out from under a process that keeps writing to it.
+    const workerPid = lock.workerPid ?? lock.pid;
+    if (ctx.isPidAlive(workerPid)) {
+      ctx.killProcess(workerPid);
+    }
+
+    // Defect 8: never push a dead worker's WIP onto a branch whose PR already merged — those
+    // commits would land after the merge and be lost the moment T-8 point 5 deletes the branch.
+    // The slot still holds the ONLY copy of the unpushed work, so it is held for recovery exactly
+    // like a failed push, just without ever attempting one — see `isBranchConfirmedMerged` for why
+    // `unknown` does not take this branch.
+    if (isBranchConfirmedMerged(ctx.gh, lock.branch)) {
+      ctx.fs.removeLock(lock.taskId);
+      holdForRecovery(lock.taskId);
+      heldForRecovery.push(lock.taskId);
+      ctx.backlog.setStatus(
+        lock.taskId,
+        TASK_STATUS.BLOCKED,
+        deadWorkerBranchAlreadyMergedComment(lock),
+      );
+      transitions.push(`${lock.taskId} -> ${TASK_STATUS.BLOCKED}`);
+      if (tasksById[lock.taskId]) {
+        tasksById[lock.taskId] = { ...tasksById[lock.taskId], status: TASK_STATUS.BLOCKED };
+      }
+      releasedLocks.push(lock.taskId);
+      pushRefusedMergedBranches.push(lock.taskId);
+      continue;
+    }
+
+    // Save BEFORE releasing (design.md decision (k)): the slot is the only copy of this work.
+    const { pushSucceeded } = ctx.git.saveWipAndPush(lock.branch);
+    ctx.fs.removeLock(lock.taskId);
+    if (pushSucceeded) {
+      releaseSlotFor(lock.taskId);
+    } else {
+      holdForRecovery(lock.taskId);
+      heldForRecovery.push(lock.taskId);
+    }
+    ctx.backlog.setStatus(lock.taskId, TASK_STATUS.BLOCKED, deadWorkerComment(lock, pushSucceeded));
+    transitions.push(`${lock.taskId} -> ${TASK_STATUS.BLOCKED}`);
+    if (tasksById[lock.taskId]) {
+      tasksById[lock.taskId] = { ...tasksById[lock.taskId], status: TASK_STATUS.BLOCKED };
+    }
+    releasedLocks.push(lock.taskId);
+  }
+
+  // ── Step 2: release orphan slots (occupied, but no lock survived step 1) ──
+  const releasedOrphanSlots: string[] = [];
+  for (const slot of slots) {
+    // A `heldForRecovery` slot LOOKS orphaned (its lock is gone) but holds the only copy of work
+    // that never reached the remote. Releasing it here would hand it to the next task, whose
+    // `reset --hard` deletes that work.
+    if (slot.taskId !== null && !slot.heldForRecovery && !aliveLocksByTaskId.has(slot.taskId)) {
+      releasedOrphanSlots.push(slot.taskId);
+      releaseSlotFor(slot.taskId);
+    }
+  }
+
+  // ── Step 3: merged PR -> Done ──
+  // A task with an ALIVE lock is a live attempt, and this step is not its judge: a retry runs on the
+  // same branch, so the PREVIOUS attempt's merged PR would declare the task Done mid-run — and step
+  // 4 then reads `Done` as "not cancelled" and leaves the worker running against a closed task. Its
+  // own close decides; the next pass sees the task once the lock is gone.
+  // A partial board needs no guard here: this step iterates the tasks it READ, and each decision
+  // rests on that task's own status plus its own PR — never on another task's absence.
+  const movedToDone: string[] = [];
+  const cleanedUpBranches: string[] = [];
+  const branchCleanupRefused: string[] = [];
+  for (const task of ctx.tasks) {
+    if (aliveLocksByTaskId.has(task.id)) {
+      continue;
+    }
+    if (task.status === TASK_STATUS.IN_PROGRESS && gh.isPrMerged(branchFor(task.id))) {
+      ctx.backlog.setStatus(task.id, TASK_STATUS.DONE, 'PR mergeado: tarea completada.');
+      movedToDone.push(task.id);
+      transitions.push(`${task.id} -> ${TASK_STATUS.DONE}`);
+      tasksById[task.id] = { ...task, status: TASK_STATUS.DONE };
+      // T-8 point 5 — never reached on the Blocked path. Defect 7: only push it when the remote
+      // half is CONFIRMED gone, not merely attempted. `taskBaseBranch` is the subtask's OWN base —
+      // its parent's DECLARED branch when it named one, `task/<parentId>` otherwise, never `main` —
+      // the same naming `close.ts`'s PR diff already uses (T-15).
+      const baseRef = `origin/${taskBaseBranch(task, tasksById)}`;
+      const outcome = cleanupBranchOnDone(task.id, ctx.git, baseRef);
+      if (outcome === BRANCH_CLEANUP_OUTCOME.CLEANED) {
+        cleanedUpBranches.push(task.id);
+      } else if (outcome === BRANCH_CLEANUP_OUTCOME.REFUSED_UNMERGED_COMMITS) {
+        branchCleanupRefused.push(task.id);
+        ctx.backlog.comment(task.id, branchCleanupRefusedComment(branchFor(task.id), baseRef));
+      }
+    }
+  }
+
+  // ── Step 3b: a hand-written Done GitHub does not report merged is reverted ──
+  // T-8 point 7, the mirror of step 3 in the opposite direction: step 3 moves `In Progress` to
+  // `Done` on a merged PR; this catches a `Done` that arrived on the board ALREADY set — a person
+  // wrote it by hand — and whose branch exists but whose PR GitHub does not (yet, or ever) report
+  // merged. A task step 3 itself just moved to `Done` above skips here for free: `gh.isPrMerged`
+  // is what put it there, so it reads `true` again and this loop leaves it alone.
+  // A `Done` with NO branch at all is left untouched — that is a task finished by hand with nothing
+  // for GitHub to report on, the legitimate case this step must never disturb.
+  //
+  // `ctx.git.branchExists` is OPTIONAL until `dispatch.ts` wires a real implementation — treated as
+  // "no branch found" when absent, which is the exact same "leave it alone" outcome an unwired
+  // caller got before this step existed (see the method's own JSDoc on `MaintenanceGit`).
+  //
+  // DESTRUCTIVE, unlike step 3: this is the ONLY place `gh.isPrMerged`'s boolean is unsafe to use
+  // (T-8 defect 1, CRITICAL, 2026-09-08). `mergedState` — the tri-state `merged`/`not-merged`/
+  // `unknown` — is what decides the revert; `unknown` (a `gh` outage: missing binary, expired
+  // token, network failure) SKIPS rather than reverts, because reading it as `not-merged` used to
+  // mass-revert every `Done` task with a surviving local branch on a single bad `gh` call. See
+  // `MaintenanceGh.mergedState`'s own JSDoc for the full incident.
+  const revertedHandwrittenDone: string[] = [];
+  for (const task of Object.values(tasksById)) {
+    if (task.status !== TASK_STATUS.DONE || aliveLocksByTaskId.has(task.id)) {
+      continue;
+    }
+    const branch = branchFor(task.id);
+    if (!(ctx.git.branchExists?.(branch) ?? false)) {
+      continue; // no branch, no PR: legitimately done by hand (or `branchExists` is not wired yet).
+    }
+    const mergeState = ctx.gh.mergedState?.(branch) ?? PR_MERGE_STATE.UNKNOWN;
+    if (mergeState === PR_MERGE_STATE.UNKNOWN) {
+      // `gh` could not actually answer (outage, missing binary, expired token) — the worst case of
+      // skipping here is a stale `Done` re-checked on the NEXT pass, never a revert this pass cannot
+      // actually justify.
+      continue;
+    }
+    if (mergeState === PR_MERGE_STATE.MERGED) {
+      continue; // the branch's PR IS merged — a person wrote Done ahead of step 3, correctly.
+    }
+    const comment = revertedHandwrittenDoneComment(branch, ctx.gh.prState?.(branch) ?? null);
+    ctx.backlog.setStatus(task.id, TASK_STATUS.IN_PROGRESS, comment);
+    transitions.push(`${task.id} -> ${TASK_STATUS.IN_PROGRESS}`);
+    tasksById[task.id] = { ...task, status: TASK_STATUS.IN_PROGRESS };
+    revertedHandwrittenDone.push(task.id);
+  }
+  // Read by step 3c immediately below (T-8 defect 2, HIGH, 2026-09-08): a task this SAME pass just
+  // reverted here is not an orphan by any honest reading of "orphan", but its `updated_date` still
+  // holds whatever value it had BEFORE the revert (Backlog.md stamps that on the NEXT edit, not
+  // retroactively), so step 3c's age check would see it as stale and re-block it in the same pass —
+  // two contradictory comments and a task that ends the pass in the wrong column. See the `Set`'s
+  // one use below for the failure scenario this closes.
+  const revertedThisPass = new Set(revertedHandwrittenDone);
+
+  // ── Step 3c: an orphan In Progress — no dispatch footprint at all — is blocked ──
+  // T-8 point 10, measured against T-8 itself: a task set to `In Progress` BY HAND in an
+  // interactive session that then ended leaves no lock, no slot, and no attempt directory behind —
+  // today's sweep (step 1) iterates LOCKS, so a task like that is invisible to it. The age check
+  // against `updated_date` is the ONLY defence against killing a LIVE interactive session, which
+  // leaves the exact same absence of lock/slot/attempt-dir; it survives this sweep by refreshing
+  // `updated_date` whenever it writes notes, a plan or a comment. All FOUR conditions must hold —
+  // a live lock or a slot still claiming the task (even one held for recovery, whose lock step 1
+  // already removed) is the dead-worker sweep's territory above, not this one's.
+  //
+  // The WHOLE step is gated on `orphanInProgressThresholdMs` being set, rather than falling back to
+  // a hidden default: until `dispatch.ts` reads `lanes.json`'s new field and passes it through, this
+  // sweep must behave EXACTLY as it did before T-8 point 10 existed for every caller that has not
+  // wired it — see that field's own JSDoc on `MaintenanceContext`.
+  const orphanInProgressBlocked: string[] = [];
+  const orphanInProgressThresholdMs = ctx.orphanInProgressThresholdMs;
+  if (orphanInProgressThresholdMs !== undefined) {
+    for (const task of Object.values(tasksById)) {
+      if (task.status !== TASK_STATUS.IN_PROGRESS || aliveLocksByTaskId.has(task.id)) {
+        continue;
+      }
+      if (revertedThisPass.has(task.id)) {
+        // T-8 defect 2: measured failure scenario — a person pushes `task/T-20`, opens a PR, and
+        // marks the task `Done` by hand at 09:00. A pass runs at 14:00. Step 3b reverts it to
+        // `In Progress` (correct — AC7). Without this guard, step 3c then sees no lock, no slot, no
+        // attempt directory and a 5-hour-old `updated_date` against a 4-hour threshold, and moves it
+        // to `Blocked` in the SAME pass — the task ends the pass in the wrong column with two
+        // contradictory comments. A task step 3b touched THIS pass gets one more pass to refresh
+        // `updated_date` on its own (a live worker's heartbeat, or a person resuming it) before the
+        // orphan check ever looks at it again.
+        continue;
+      }
+      if (slots.some((slot) => slot.taskId === task.id)) {
+        continue;
+      }
+      if (ctx.fs.hasAttemptDir?.(task.id) ?? false) {
+        continue;
+      }
+      const ageMs = ctx.now - task.updatedAt;
+      if (ageMs <= orphanInProgressThresholdMs) {
+        continue; // could be a live interactive session refreshing updated_date as it works.
+      }
+
+      const comment = orphanInProgressComment(task.id, ageMs, orphanInProgressThresholdMs);
+      ctx.backlog.setStatus(task.id, TASK_STATUS.BLOCKED, comment);
+      transitions.push(`${task.id} -> ${TASK_STATUS.BLOCKED}`);
+      tasksById[task.id] = { ...task, status: TASK_STATUS.BLOCKED };
+      orphanInProgressBlocked.push(task.id);
+    }
+  }
+
+  // ── Step 4: manual cancellation — save, THEN kill, THEN release ──
+  const cancelledWorkers: string[] = [];
+  for (const [taskId, lock] of aliveLocksByTaskId) {
+    const task = tasksById[taskId];
+    // Cancellation is an EXPLICIT human act: moving the task to `Blocked` or back to `To Do`, or
+    // deleting it outright. Anything else — `Done` written by the merged-PR step above, a `Queued`
+    // this pass has not dispatched yet, an `Unknown` the parser could not read — is not a request
+    // to kill, and treating "not In Progress" as one killed healthy workers on a parse failure.
+    // An ABSENT task is a deletion only on a board that was read in full — see `boardComplete`.
+    const cancelled = task
+      ? task.status === TASK_STATUS.BLOCKED || task.status === TASK_STATUS.TO_DO
+      : ctx.boardComplete;
+    if (!cancelled) {
+      continue;
+    }
+    const { pushSucceeded } = ctx.git.saveWipAndPush(lock.branch);
+    if (!pushSucceeded) {
+      // Leave the worker running and the slot held: the next pass retries the push (design.md
+      // decision (k) — never kill/release before the work is safely saved).
+      continue;
+    }
+    ctx.killProcess(lock.workerPid ?? lock.pid);
+    ctx.fs.removeLock(taskId);
+    releaseSlotFor(taskId);
+    cancelledWorkers.push(taskId);
+  }
+
+  // ── Step 5: recompute every parent ──
+  const recomputedParents: RecomputedParent[] = [];
+  // Skipped WHOLE on a partial board: a derivation over an incomplete child set is not a smaller
+  // answer, it is a wrong one (two children read `Done`, the third dropped and still running →
+  // the parent moves to `Done`). The next pass, with a readable board, derives it correctly.
+  const parentIds = ctx.boardComplete
+    ? Array.from(
+        new Set(ctx.tasks.filter((task) => task.parentId).map((task) => task.parentId as string)),
+      ).sort()
+    : [];
+  if (!ctx.boardComplete) {
+    console.warn(
+      'maintenance.ts: the board came back incomplete; skipping parent derivation and absence-based cancellation.',
+    );
+  }
+  for (const parentId of parentIds) {
+    const recomputed = recomputeParent({
+      parentId,
+      tasksById,
+      gh,
+      backlog: ctx.backlog,
+      fs: ctx.fs,
+    });
+    if (recomputed) {
+      recomputedParents.push(recomputed);
+      transitions.push(`${parentId} -> ${recomputed.to}`);
+      tasksById[parentId] = { ...tasksById[parentId], status: recomputed.to };
+      if (recomputed.to === TASK_STATUS.DONE) {
+        // T-8 point 5 applies here too: a parent that reaches Done because every child did, and
+        // its own PR merged, gets the same branch cleanup a leaf task gets from step 3. Defect 7:
+        // same "confirmed gone" condition as the leaf path above. The base is THIS parent's own
+        // `parentId` (its grandparent's DECLARED branch, `task/<grandparentId>`, or `main`) — a
+        // parent can itself be a subtask.
+        const baseRef = `origin/${taskBaseBranch(tasksById[parentId], tasksById)}`;
+        const outcome = cleanupBranchOnDone(parentId, ctx.git, baseRef);
+        if (outcome === BRANCH_CLEANUP_OUTCOME.CLEANED) {
+          cleanedUpBranches.push(parentId);
+        } else if (outcome === BRANCH_CLEANUP_OUTCOME.REFUSED_UNMERGED_COMMITS) {
+          branchCleanupRefused.push(parentId);
+          ctx.backlog.comment(parentId, branchCleanupRefusedComment(branchFor(parentId), baseRef));
+        }
+      }
+    }
+  }
+
+  // ── Step 6: commit pending .backlog/** changes ──
+  let committedBoard = false;
+  if (ctx.git.hasPendingBacklogChanges()) {
+    try {
+      ctx.git.commitBacklogChanges(buildBoardCommitMessage(transitions));
+      committedBoard = true;
+    } catch (error) {
+      // A rejected or conflicted board commit is a bookkeeping problem, not a reason to abandon the
+      // sweep that already released slots and saved work: the next pass retries it.
+      console.error('maintenance.ts: the board commit failed; continuing the pass:', error);
+    }
+  }
+
+  // One write for the whole pass, replaying this pass's own transforms onto the registry as it is
+  // NOW rather than onto the snapshot read at the start.
+  const finalRegistry = ctx.fs.updateSlots((current) => ({
+    slots: pendingTransforms.reduce((entries, transform) => transform(entries), current.slots),
+  }));
+
+  return {
+    releasedLocks,
+    releasedOrphanSlots,
+    movedToDone,
+    cancelledWorkers,
+    recomputedParents,
+    committedBoard,
+    recoveredPushes,
+    heldForRecovery,
+    exhaustedRecoveries,
+    cleanedUpBranches,
+    branchCleanupRefused,
+    revertedHandwrittenDone,
+    orphanInProgressBlocked,
+    pushRefusedMergedBranches,
+    slots: finalRegistry,
+  };
+}