@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

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

@@ -0,0 +1,1483 @@
+/**
+ * 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, refresh the
+ * graph-holder task, 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); `specs/backlog-dependency-graph/spec.md`
+ * — "Graph-holder task mirrors the view" (the write half; `graph.ts` owns the render/decide logic
+ * this step only calls).
+ *
+ * `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;
+ * (5b) refresh the graph-holder task (`backlog-dependency-graph` capability) — re-renders the
+ * dependency view over the board AS STEP 5 LEFT IT and replaces the holder's description only when
+ * the text differs, so the refresh rides in the SAME board commit (step 6) as whatever change
+ * caused it. Skipped when `boardComplete` is false (same reason as step 5: a view derived from part
+ * of the board would show a waiting task as ready) or when zero tasks carry `board:graph` (reported
+ * on `MaintenanceResult`, nothing written). When MORE than one task carries the label, each one
+ * that does not already show it gets an ambiguity notice instead of the view (also reported on
+ * `MaintenanceResult`) — one holder's write failing never costs the other its notice. A throw from
+ * reading or writing a description is caught and recorded on `MaintenanceResult` — this step can
+ * never fail the pass it rides along in;
+ * (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 {
+  buildExecutionRecordBlock,
+  hasExecutionRecordBlock,
+  sanitizeCommentBody,
+} from './close.js';
+import { decideGraphWrite } from './graph.js';
+import { taskBaseBranch } from './guards.js';
+import { deriveParentStatus, effectiveStatus, type ParentDerivationNode } from './parent.js';
+import { isLockAlive, releaseSlotEntries } from './slots.js';
+import {
+  TASK_STATUS,
+  type Board,
+  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;
+  /**
+   * The classified terminal outcome of one attempt's `stream.jsonl` (`render.ts`'s
+   * `classifyStreamOutcome`) — T-68's ONE structurally-detectable environment failure (a budget
+   * cutoff, `STREAM_OUTCOME.BUDGET`, feeds the «Registro de ejecución» block's "Fallos de entorno").
+   * `null` when the attempt directory or its stream file does not exist — never thrown, since a
+   * missing attempt is a legitimate "no data" answer for the close-record composer, not a fault.
+   */
+  attemptStreamOutcome(taskId: string, attempt: number): string | null;
+  /**
+   * One attempt's `review.md` verdict (`reviewer.ts`'s `parseReviewerVerdict`, reused rather than
+   * reimplemented) — feeds the «Registro de ejecución» block's "Rondas de corrección"/"revisor"
+   * (T-68 fix 2: a retry count alone cannot tell a correction round from a quota-cutoff retry, and
+   * the lane label cannot tell "the reviewer ran and passed" from "this lane has no reviewer at
+   * all"). `null` when the attempt has no `review.md` — never thrown: only the local lane's close
+   * ever writes one, so `null` is the ordinary answer for every frontier-lane attempt.
+   */
+  attemptReviewVerdict(taskId: string, attempt: number): string | null;
+}
+
+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.
+   *
+   * REQUIRED, unlike `prState` — T-20 point 4 (2026-09-11): this answer also gates two pushers
+   * (the recovery retry and the dead-worker rescue) that must never land a commit on an
+   * already-merged branch. A caller free to omit the collaborator entirely made "cannot confirm"
+   * indistinguishable from "confirmed not merged" at those two sites — a missing CAPABILITY
+   * silently switching a safety gate off, not a legitimate `unknown` answer. Making it required
+   * moves that failure to the type checker: a `MaintenanceGh` built with no `mergedState` no longer
+   * compiles, so there is no runtime branch left to fail open. A collaborator that genuinely cannot
+   * answer (the `gh` outage this whole tri-state exists for) still returns `PR_MERGE_STATE.UNKNOWN`
+   * itself — that is the legitimate use of the third state, not an excuse to omit the function.
+   */
+  mergedState(branch: string): PrMergeState;
+  /**
+   * The branch's PR number, or `null` when `gh` reports no PR at all (or is unavailable/
+   * unauthenticated — the same fail-closed reading `prState`/`isPrMerged` give). T-68's «Registro de
+   * ejecución» block reads this for a task with `attempts === 0` (never dispatched — a supervisada
+   * session closed by step 3/`recomputeParent`, whose Worktree Gate forces it onto the same
+   * `task/T-nn` branch): with no attempt directory to point `Fuente` at, the merged PR is the only
+   * trace left.
+   *
+   * OPTIONAL, same as `prState` — until `dispatch.ts`'s real `gh` collaborator wires it, an unwired
+   * caller here reads exactly like a failed read (see the call site's own handling): the PR is
+   * confirmed to exist (both call sites only ever reach this with a CONFIRMED merged PR), only its
+   * number could not be obtained.
+   */
+  prNumber?(branch: string): number | null;
+}
+
+/**
+ * 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;
+  /**
+   * Appends to the task's notes (`backlog task edit --append-notes`) — the one field the `Queued`
+   * scope freeze (`catalyst-backlog/SKILL.md` §11) leaves open on a `Queued`/`In Progress`/`Done`
+   * task. T-68's only writer: the «Registro de ejecución» block (§12), appended once at the `Done`
+   * transition step 3 makes.
+   */
+  appendNotes(taskId: string, notes: string): void;
+  /**
+   * The task's current notes text, or `null` when it could not be read. T-68's ONLY reader: §12.3's
+   * idempotence check, which only needs to know whether `close.ts`'s `EXECUTION_RECORD_HEADING`
+   * occurs anywhere in it — the full `backlog task view --plain` output is fine to pass through
+   * as-is. `null` reads as "not yet written": a pass that cannot confirm the block is already there
+   * appends it rather than silently skipping, so the heading itself stays the durable guard, never
+   * this read.
+   */
+  readNotes(taskId: string): string | null;
+  /**
+   * Replaces a task's description outright (`backlog task edit --desc`) — the graph-holder
+   * refresh's (step 5b) only writer. `graph.ts`'s `pnpm backlog:graph --write` uses the same
+   * `decideGraphWrite` decision this step calls, so both paths write through one function.
+   */
+  setDescription(taskId: string, description: string): void;
+  /**
+   * The task's current description text (`task-view.ts`'s `parseDescription`, over a fresh
+   * `backlog task view --plain`) — step 5b's reader, called for the single holder task it found, or
+   * once per holder when more than one carries the label (never for zero holders, which need no
+   * comparison at all). `null` when it could not be read.
+   */
+  readDescription(taskId: string): string | null;
+}
+
+export interface SaveWipResult {
+  pushSucceeded: boolean;
+}
+
+export interface MaintenanceGit {
+  /** `git status --porcelain -- .backlog` in the main checkout, collapsed to a boolean. */
+  hasPendingBacklogChanges(): boolean;
+  /**
+   * `git add` of only the `.backlog` paths that belong to Backlog.md's own managed schema
+   * (tasks/milestones/archive/completed/config.yml, or an ID-prefixed `docs/` entry), then `git
+   * commit` — a dirty path outside that schema is excluded and logged (T-78), never silently
+   * swallowed nor blindly included alongside the board's own output.
+   */
+  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 graph-holder task (step 5b) this pass WROTE a fresh dependency view to, or `null` when
+   * nothing needed writing: no holder on the board, the rendered view already matched the holder's
+   * description, the board read was incomplete, more than one task carries the label (see
+   * `graphHolderAmbiguous`), or the step itself threw (see `graphHolderRefreshError` to tell that
+   * last case apart from the rest).
+   */
+  graphHolderRefreshed: string | null;
+  /**
+   * Step 5b: ids of every task carrying `board:graph` when more than one did. Each one that does
+   * not already show the ambiguity notice gets it written — see `graph.ts`'s
+   * `ambiguousHolderNotice` — so this is populated even though `graphHolderRefreshed` stays `null`.
+   */
+  graphHolderAmbiguous: string[];
+  /**
+   * Set when step 5b's read or write collaborator threw. The pass still closes merged tasks,
+   * recomputes parents, commits pending board changes and selects a task regardless — a
+   * dependency-view refresh is never allowed to block the pass it rides along in.
+   */
+  graphHolderRefreshError: string | null;
+  /**
+   * 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 REQUIRED on `MaintenanceGh` (T-20 point 4): a caller
+   * with no way to answer it no longer type-checks, so the only `unknown` this function can ever
+   * see is a WIRED collaborator's honest answer to a real `gh` outage, never an omitted function.
+   */
+  /** `prNumber` (optional, like on `MaintenanceGh` itself) is T-68's addition — see `backlog`'s own JSDoc just below for why. */
+  gh: Pick<MaintenanceGh, 'isPrMerged' | 'mergedState' | 'prNumber'>;
+  /**
+   * `setStatus` moves the parent; `appendNotes`/`readNotes` are T-68's addition — a parent that
+   * reaches `Done` THROUGH this derivation (every child Done, own PR merged) carries the «Registro
+   * de ejecución» block exactly like a leaf task does (§12: "every task"), and this is the only
+   * place that transition is written, so it is the only place that can write it. `comment` is what
+   * a FAILED write falls back to (`writeExecutionRecordOnce` never blocks the transition) — the
+   * same port every other Blocked cause already posts through.
+   */
+  backlog: Pick<MaintenanceBacklog, 'setStatus' | 'appendNotes' | 'readNotes' | 'comment'>;
+  /**
+   * The durable "has rule 4 already fired for this parent, ever" signal (T-8 defect 3) — see
+   * `MaintenanceFs.hasCloseAttemptBeenEnqueued`'s own JSDoc. Required for the same reason
+   * `mergedState` now is: 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).
+   *
+   * `attemptStreamOutcome`/`attemptReviewVerdict` are T-68 fix 3's addition, read only when this
+   * derivation is about to write `Done` — see `backlog`'s own JSDoc just above.
+   */
+  fs: Pick<
+    MaintenanceFs,
+    | 'hasCloseAttemptBeenEnqueued'
+    | 'markCloseAttemptEnqueued'
+    | 'attemptStreamOutcome'
+    | 'attemptReviewVerdict'
+  >;
+}
+
+/**
+ * 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));
+    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;
+  }
+
+  // T-68: a parent that reaches `Done` through THIS derivation gets the same «Registro de
+  // ejecución» block a leaf task gets from step 3 — before the transition, same as there. Also same
+  // as there: a failed write never blocks it (`writeExecutionRecordOnce`'s own JSDoc) — a parent
+  // withheld from `Done` here would re-derive the SAME "all children Done, PR merged" state every
+  // later pass with no way to fix it (this function's own no-op-on-no-change guard just above means
+  // a genuine retry never even reaches this line again), so the write is best-effort and the
+  // transition proceeds regardless.
+  if (newStatus === TASK_STATUS.DONE) {
+    writeExecutionRecordOnce(input, parentTask);
+  }
+
+  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. `mergedState` is REQUIRED on `MaintenanceGh`
+ * (T-20 point 4, 2026-09-11): a caller with no way to answer this question no longer type-checks,
+ * so the only `unknown` this function can ever see is a WIRED collaborator's honest answer to a
+ * real outage — never an omitted function silently read as "not merged".
+ */
+function isBranchConfirmedMerged(gh: Pick<MaintenanceGh, 'mergedState'>, branch: string): boolean {
+  return gh.mergedState(branch) === 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');
+}
+
+/** The narrow slice `writeExecutionRecordOnce` needs — satisfied by a full `MaintenanceContext`, and by `RecomputeParentInput`'s own narrowed `backlog`/`fs`/`gh` once widened below. */
+interface ExecutionRecordDeps {
+  backlog: Pick<MaintenanceBacklog, 'appendNotes' | 'readNotes' | 'comment'>;
+  fs: Pick<MaintenanceFs, 'attemptStreamOutcome' | 'attemptReviewVerdict'>;
+  gh: Pick<MaintenanceGh, 'prNumber'>;
+}
+
+/**
+ * The `Blocked`-comment-style message a person reads on the task when the record itself could not
+ * be written — the ONE signal a failed write leaves on the board. Names the skill's
+ * own manual template (§12) so the person filling it in by hand does not have to go hunting for it.
+ */
+const executionRecordWriteFailureComment = (message: string): string =>
+  `No se pudo escribir el «Registro de ejecución» al pasar a Done: ${message}. Añádelo a mano con ` +
+  'la plantilla de la sección 12 de .claude/skills/catalyst-backlog/SKILL.md.';
+
+/**
+ * Writes the «Registro de ejecución» block (`close.ts`'s `buildExecutionRecordBlock`) once, BEFORE
+ * the caller's `setStatus(..., DONE, ...)` — so a SUCCESSFUL write lands on the board before the
+ * transition does. But this function NEVER throws, and a failed write never blocks the transition.
+ * Skipping the transition to retry later is a silent, permanent stall: `appendNotes` already retries
+ * through `withBoardWriteRetry` (6 tries, backoff), so a throw here is not transient, and a task kept
+ * out of `Done` keeps its attempt directory (the orphan sweep ignores it) and never reaches
+ * `cleanupBranchOnDone`. A confirmed merge is never held hostage to bookkeeping.
+ *
+ * On failure: logs, then posts EXACTLY ONE board comment through the same `comment`
+ * port every other Blocked cause already uses — sanitized through `close.ts`'s
+ * `sanitizeCommentBody` so a long error cannot blow the comment up — naming the gap and pointing at
+ * the skill's own manual template. If `comment` ITSELF throws, that is caught and logged too: this
+ * function's whole contract is "never throw", not "never fail".
+ *
+ * Reads the task's current notes first (§12.3's sentinel, enforced here via
+ * `hasExecutionRecordBlock` over `task-view.ts`'s `notesRegion`-scoped text) so a task an earlier
+ * pass already recorded — or this same task, were this ever called twice — is left untouched:
+ * idempotence lives in the heading itself, not in a second, parallel marker file. A task the write
+ * failed for is never revisited either, but for a DIFFERENT reason: it already left `In Progress`
+ * in the SAME pass (the caller proceeds to `setStatus` regardless), so step 3's own `status ===
+ * IN_PROGRESS` guard is what keeps the next pass from trying again — not anything in here.
+ */
+function writeExecutionRecordOnce(deps: ExecutionRecordDeps, task: Task): void {
+  try {
+    if (hasExecutionRecordBlock(deps.backlog.readNotes(task.id))) {
+      return;
+    }
+    const attemptOutcomes: Array<string | null> = [];
+    const reviewVerdicts: Array<string | null> = [];
+    for (let attempt = 1; attempt <= task.attempts; attempt += 1) {
+      attemptOutcomes.push(deps.fs.attemptStreamOutcome(task.id, attempt));
+      reviewVerdicts.push(deps.fs.attemptReviewVerdict(task.id, attempt));
+    }
+    const sourcePath =
+      task.attempts > 0 ? `.backlog/.dispatch/${task.id}/intento-${task.attempts}` : null;
+    // Only asked when `attempts === 0` (never dispatched — a supervisada task closed by the SAME
+    // merged-PR path a headless one is) — an ordinary dispatched close has no use for it, so this
+    // skips the extra `gh` round-trip entirely for the common case. Both real call sites (step 3,
+    // `recomputeParent`) only ever reach this with a CONFIRMED merged PR, so a non-number answer
+    // here means "exists, but its number could not be read" — `'read-failed'`, never `null`
+    // (`close.ts`'s own `sourceLine` reads that as `desconocido`, not `sin evidencia`).
+    let prNumber: number | 'read-failed' | undefined;
+    if (task.attempts === 0) {
+      const prNumberResult = deps.gh.prNumber?.(branchFor(task.id)) ?? null;
+      prNumber = typeof prNumberResult === 'number' ? prNumberResult : 'read-failed';
+    }
+    deps.backlog.appendNotes(
+      task.id,
+      buildExecutionRecordBlock({
+        lane: task.lane,
+        attempts: task.attempts,
+        attemptOutcomes,
+        reviewVerdicts,
+        sourcePath,
+        prNumber,
+      }),
+    );
+  } catch (error) {
+    console.error(
+      `maintenance.ts: could not write the «Registro de ejecución» block for ${task.id}; the transition proceeds anyway, and a board comment records the gap:`,
+      error,
+    );
+    try {
+      deps.backlog.comment(
+        task.id,
+        sanitizeCommentBody(executionRecordWriteFailureComment(String(error))),
+      );
+    } catch (commentError) {
+      console.error(
+        `maintenance.ts: could not even POST the «Registro de ejecución» failure comment for ${task.id}:`,
+        commentError,
+      );
+    }
+  }
+}
+
+/**
+ * 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' | 'prNumber'> = {
+    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);
+      mergeStateCache.set(branch, state);
+      return state;
+    },
+    // Uncached, unlike the two above: `writeExecutionRecordOnce` is the ONLY caller, at most once
+    // per parent per pass (a supervisada parent, `attempts === 0`), so memoizing it would add a map
+    // this pass almost never fills.
+    prNumber: (branch) => ctx.gh.prNumber?.(branch) ?? null,
+  };
+
+  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))) {
+      // T-68: the record is written BEFORE the transition, so a successful block is on the board
+      // before `Done` is — but the write NEVER blocks the transition itself (see
+      // `writeExecutionRecordOnce`'s own JSDoc): a merged PR is a confirmed fact, and a task
+      // withheld here would leave `In Progress` forever, invisible to the orphan sweep and to
+      // `cleanupBranchOnDone` below. A failed write instead leaves ONE board comment and the pass
+      // proceeds exactly as it would on a clean write.
+      writeExecutionRecordOnce(ctx, task);
+      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 —
+      // `task/<parentId>`, never `main` — the same naming `close.ts`'s PR diff already uses (T-14,
+      // T-52).
+      const baseRef = `origin/${taskBaseBranch(task)}`;
+      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);
+    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;
+      }
+      // A parent's status is DERIVED from its children (parent.ts), never written by hand, so it
+      // can never be an orphan by this step's own definition — it will never carry a lock, a slot
+      // or an attempt directory of its own. Without this guard, a Complex parent sitting `In
+      // Progress` with a Done/To Do child mix (correct per parent.ts) gets blocked here on every
+      // pass once its `updated_date` goes stale, since nothing about it ever refreshes that field.
+      const hasChildren = Object.values(tasksById).some((candidate) => candidate.parentId === task.id);
+      if (hasChildren) {
+        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` (`task/<grandparentId>`, or `main`) — a parent can itself be a subtask.
+        const baseRef = `origin/${taskBaseBranch(tasksById[parentId])}`;
+        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 5b: refresh the graph-holder task ──
+  // Placed AFTER step 5 (parent recompute) and BEFORE step 6 (board commit): rendering over
+  // `tasksById` as step 5 left it means a parent that just became Done stops being an open
+  // dependency in the SAME pass that closed it, and writing before the commit means the refresh
+  // rides in the SAME `chore(backlog): sync board state` commit as whatever change caused it.
+  let graphHolderRefreshed: string | null = null;
+  let graphHolderAmbiguous: string[] = [];
+  let graphHolderRefreshError: string | null = null;
+  try {
+    const board: Board = { tasksById, complete: ctx.boardComplete };
+    const decision = decideGraphWrite(board, (id) => ctx.backlog.readDescription(id) ?? '');
+    if (decision.kind === 'write') {
+      ctx.backlog.setDescription(decision.id, decision.description);
+      graphHolderRefreshed = decision.id;
+    } else if (decision.kind === 'ambiguous') {
+      graphHolderAmbiguous = decision.ids;
+      // Each holder's write is independent: one throwing must not cost the other its notice, and
+      // must not fail the whole step (`graphHolderRefreshError` stays reserved for a failure that
+      // aborts step 5b entirely, not a single holder's write).
+      for (const holderWrite of decision.writes) {
+        try {
+          ctx.backlog.setDescription(holderWrite.id, holderWrite.description);
+        } catch (error) {
+          console.error(
+            `maintenance.ts: could not write the ambiguity notice to ${holderWrite.id}; continuing the pass:`,
+            error,
+          );
+        }
+      }
+      console.warn(
+        `maintenance.ts: more than one board:graph holder (${decision.ids.join(', ')}); the dependency view was not refreshed.`,
+      );
+    }
+    // 'no-holder', 'unchanged' and 'incomplete' all mean nothing to write — the board that did
+    // not change (design.md decision 5's own framing) costs nothing: no edit, no commit.
+  } catch (error) {
+    graphHolderRefreshError = error instanceof Error ? error.message : String(error);
+    console.error('maintenance.ts: the graph-holder refresh failed; continuing the pass:', error);
+  }
+
+  // ── 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,
+    graphHolderRefreshed,
+    graphHolderAmbiguous,
+    graphHolderRefreshError,
+    slots: finalRegistry,
+  };
+}