@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

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

@@ -0,0 +1,2642 @@
+/**
+ * TDD spec for `scripts/backlog/maintenance.ts` (tasks 3.15/3.16).
+ *
+ * Runner: `node --import tsx --test scripts/backlog/maintenance.test.ts`
+ *
+ * Implements `specs/backlog-task-dispatcher/spec.md` — "Maintenance pass precedes task selection"
+ * (dead-lock sweep, orphan-slot release, merged-PR-to-Done, the "Pending board changes are
+ * committed during maintenance" scenario) and "Manual cancellation kills the worker after saving
+ * work"; `specs/backlog-task-lifecycle/spec.md` — "Derived parent state". Every collaborator (fs
+ * over `.backlog/.dispatch/`, `isPidAlive`, `now`, `gh`, `backlog`, `git`, `killProcess`) is
+ * injected through `MaintenanceContext`, recorded by an in-memory fake, so this suite never touches
+ * a real filesystem, git repo, or process.
+ */
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { ambiguousHolderNotice, renderHolderDescription } from './graph.js';
+import {
+  buildBoardCommitMessage,
+  MAX_RECOVERY_ATTEMPTS,
+  recomputeParent,
+  REMOTE_BRANCH_DELETE_RESULT,
+  runMaintenance,
+  type MaintenanceContext,
+  type RemoteBranchDeleteResult,
+} from './maintenance.js';
+import { releaseSlot } from './slots.js';
+import {
+  LANE,
+  TASK_STATUS,
+  TIER,
+  type DispatchLock,
+  type SlotInfo,
+  type SlotRegistry,
+  type Task,
+} from './types.js';
+
+const NOW = Date.parse('2026-09-06T12:00:00.000Z');
+const TTL_MS = 5 * 60_000;
+
+function freeSlot(name: string): SlotInfo {
+  return { name, path: `/slots/${name}`, lane: null, taskId: null, pid: null, lockfileHash: null };
+}
+
+function busySlot(name: string, lane: 'local' | 'frontier', taskId: string, pid: number): SlotInfo {
+  return { name, path: `/slots/${name}`, lane, taskId, pid, lockfileHash: 'abc' };
+}
+
+function makeLock(overrides: Partial<DispatchLock> & { taskId: string }): DispatchLock {
+  return {
+    slot: 'dispatch-a',
+    pid: 111,
+    startedAt: new Date(NOW - 60_000).toISOString(),
+    heartbeatAt: new Date(NOW - 1_000).toISOString(),
+    lane: LANE.LOCAL,
+    attempt: 1,
+    branch: `task/${overrides.taskId}`,
+    ...overrides,
+  };
+}
+
+function makeTask(overrides: Partial<Task> & { id: string }): Task {
+  return {
+    status: TASK_STATUS.IN_PROGRESS,
+    filesToTouch: [],
+    testCommand: null,
+    acceptanceCriteria: [],
+    definitionOfDone: [],
+    dependsOn: [],
+    attempts: 1,
+    priority: 0,
+    // Both fresh by default (T-8 defect 4, 2026-09-08): `task-view.ts`'s real parser now falls
+    // back `updatedAt` to `createdAt` when a task carries no `Updated:` line, so a fixture with a
+    // sane, non-zero `createdAt` needs no separate compensation for the point-10 orphan check any
+    // more — a mismatched `createdAt: 0` / `updatedAt: NOW` pair here would just re-hide the same
+    // hazard the parser now closes for real. A test for the orphan sweep itself overrides
+    // `updatedAt` to something older than the threshold.
+    createdAt: NOW,
+    updatedAt: NOW,
+    ...overrides,
+  };
+}
+
+/** The default point-10 threshold every test gets unless it overrides `orphanInProgressThresholdMs`. */
+const DEFAULT_ORPHAN_THRESHOLD_MS = 4 * 60 * 60_000;
+
+interface FakeCollaborators {
+  ctx: MaintenanceContext;
+  calls: string[];
+  slotsAfter: () => SlotRegistry;
+  lockRemovals: () => string[];
+  statusEdits: () => Array<{ id: string; status: string }>;
+  comments: () => Array<{ id: string; comment: string }>;
+  /** T-68: every `--append-notes` call this pass made, in call order. */
+  appendedNotes: () => Array<{ id: string; notes: string }>;
+  /** T-68: the CURRENT notes text for one task, after every write this pass made. */
+  notesFor: (taskId: string) => string | null;
+  /** T-113: the CURRENT description text for one task, after every write this pass made. */
+  descriptionFor: (taskId: string) => string | null;
+  /** T-113: every `setDescription` call this pass made, in call order. */
+  descriptionEdits: () => Array<{ id: string; description: string }>;
+  boardCommits: () => string[];
+  detachedSlots: () => string[];
+  notifications: () => Array<{ title: string; body: string }>;
+  deletedLocalBranches: () => string[];
+  deletedRemoteBranches: () => string[];
+  /** Every `(branch, baseRef)` pair `branchHasUnmergedCommits` was asked about, in call order. */
+  branchCleanupChecks: () => Array<{ branch: string; baseRef: string }>;
+  /** Simulates another pass writing the registry between this pass's read and its write. */
+  mutateRegistryConcurrently: (mutate: (slots: SlotInfo[]) => SlotInfo[]) => void;
+}
+
+function makeCollaborators(input: {
+  slots: SlotInfo[];
+  locks: DispatchLock[];
+  tasks: Task[];
+  /** Defaults to a fully-read board — the case every pre-N3 test was written against. */
+  boardComplete?: boolean;
+  isPidAlive?: (pid: number) => boolean;
+  isPrMerged?: (branch: string) => boolean;
+  prState?: (branch: string) => string | null;
+  mergedState?: (branch: string) => 'merged' | 'not-merged' | 'unknown';
+  /** T-68 latest: `taskId`'s branch -> its PR number, for the «Registro de ejecución» block's `Fuente` on a never-dispatched (`attempts: 0`) task. Defaults to unwired (`undefined`), which reads as a failed read. */
+  prNumber?: (branch: string) => number | null;
+  hasPendingBacklogChanges?: boolean;
+  saveWipAndPush?: (branch: string) => { pushSucceeded: boolean };
+  commitBacklogChanges?: (message: string) => void;
+  branchExists?: (branch: string) => boolean;
+  /** Defaults to `REMOTE_BRANCH_DELETE_RESULT.DELETED` — a defect-7 test overrides it. */
+  deleteRemoteBranchResult?: (branch: string) => RemoteBranchDeleteResult;
+  /**
+   * Defaults to `false` (no commit beyond the base — the branch is confirmed clean) so every
+   * pre-existing branch-cleanup test keeps deleting exactly as it did before this safety check
+   * existed. A test for the check itself overrides it to `true`.
+   */
+  branchHasUnmergedCommits?: (branch: string, baseRef: string) => boolean;
+  hasAttemptDir?: (taskId: string) => boolean;
+  orphanInProgressThresholdMs?: number;
+  /** Task ids whose close-attempt marker (T-8 defect 3) already exists before this pass runs. */
+  closeAttemptAlreadyEnqueued?: string[];
+  /** T-68: `taskId` + `attempt` -> the classified stream outcome. Defaults to `null` (unread). */
+  attemptStreamOutcome?: (taskId: string, attempt: number) => string | null;
+  /** T-68 fix 2: `taskId` + `attempt` -> the `review.md` verdict. Defaults to `null` (no review.md). */
+  attemptReviewVerdict?: (taskId: string, attempt: number) => string | null;
+  /** T-68: a task's notes BEFORE this pass runs — the §12.3 idempotence check reads these first. */
+  notesBefore?: Record<string, string>;
+  /** T-68 fix 1: `appendNotes` throws for a task id this returns `true` for — simulates a board write failure. */
+  appendNotesShouldThrow?: (taskId: string) => boolean;
+  /** T-68: `comment` throws for a task id this returns `true` for — simulates a SECOND board write failure, on top of `appendNotesShouldThrow`. */
+  commentShouldThrow?: (taskId: string) => boolean;
+  /** T-113: a task's description BEFORE this pass runs — step 5b's `readDescription` reads these first. */
+  descriptionsBefore?: Record<string, string>;
+  /** T-113: `setDescription` throws for a task id this returns `true` for — simulates a board write failure. */
+  setDescriptionShouldThrow?: (taskId: string) => boolean;
+  /** T-113: `readDescription` throws for a task id this returns `true` for — simulates a board read failure. */
+  readDescriptionShouldThrow?: (taskId: string) => boolean;
+}): FakeCollaborators {
+  const calls: string[] = [];
+  let slots: SlotInfo[] = input.slots;
+  const closeAttemptEnqueued = new Set<string>(input.closeAttemptAlreadyEnqueued ?? []);
+  const notes: Record<string, string> = { ...(input.notesBefore ?? {}) };
+  const appendedNotes: Array<{ id: string; notes: string }> = [];
+  const descriptions: Record<string, string> = { ...(input.descriptionsBefore ?? {}) };
+  const descriptionEdits: Array<{ id: string; description: string }> = [];
+  const removedLocks: string[] = [];
+  const detachedSlots: string[] = [];
+  const notifications: Array<{ title: string; body: string }> = [];
+  const statusEdits: Array<{ id: string; status: string }> = [];
+  const comments: Array<{ id: string; comment: string }> = [];
+  const boardCommits: string[] = [];
+  const deletedLocalBranches: string[] = [];
+  const deletedRemoteBranches: string[] = [];
+  const branchCleanupChecks: Array<{ branch: string; baseRef: string }> = [];
+
+  const ctx: MaintenanceContext = {
+    now: NOW,
+    ttlMs: TTL_MS,
+    orphanInProgressThresholdMs: input.orphanInProgressThresholdMs ?? DEFAULT_ORPHAN_THRESHOLD_MS,
+    isPidAlive: input.isPidAlive ?? (() => true),
+    tasks: input.tasks,
+    boardComplete: input.boardComplete ?? true,
+    fs: {
+      readSlots: () => ({ slots }),
+      // Mirrors the real primitive: the mutation is applied to the registry as it is AT WRITE TIME,
+      // not to the snapshot the pass read at its start.
+      updateSlots: (mutate) => {
+        const next = mutate({ slots });
+        slots = next.slots;
+        calls.push('updateSlots');
+        return next;
+      },
+      readLocks: () => input.locks,
+      removeLock: (taskId) => {
+        removedLocks.push(taskId);
+        calls.push(`removeLock(${taskId})`);
+      },
+      hasAttemptDir: (taskId) => input.hasAttemptDir?.(taskId) ?? false,
+      hasCloseAttemptBeenEnqueued: (taskId) => closeAttemptEnqueued.has(taskId),
+      markCloseAttemptEnqueued: (taskId) => {
+        closeAttemptEnqueued.add(taskId);
+        calls.push(`markCloseAttemptEnqueued(${taskId})`);
+      },
+      attemptStreamOutcome: (taskId, attempt) => input.attemptStreamOutcome?.(taskId, attempt) ?? null,
+      attemptReviewVerdict: (taskId, attempt) => input.attemptReviewVerdict?.(taskId, attempt) ?? null,
+    },
+    gh: {
+      isPrMerged: input.isPrMerged ?? (() => false),
+      prState: input.prState ?? (() => null),
+      // Defaults to a WIRED fake answering "not merged" — `MaintenanceGh.mergedState` is required
+      // (T-20 point 4, 2026-09-11), so every real `gh` collaborator answers it; a test silent on
+      // this feature should see a normal answer rather than have to think about it.
+      mergedState: input.mergedState ?? (() => 'not-merged'),
+      prNumber: input.prNumber,
+    },
+    backlog: {
+      setStatus: (id, status, comment) => {
+        statusEdits.push({ id, status });
+        calls.push(`setStatus(${id},${status})`);
+        // The real `MaintenanceBacklog.setStatus` carries an optional comment (a `--comment` on the
+        // same `backlog task edit`), and several T-8 tests assert its TEXT — recorded into the same
+        // `comments` list a bare `ctx.backlog.comment()` call fills, so a test can read either kind
+        // of comment through one accessor without caring which call produced it.
+        if (comment) {
+          comments.push({ id, comment });
+        }
+      },
+      comment: (id, comment) => {
+        if (input.commentShouldThrow?.(id)) {
+          calls.push(`comment(${id}) THREW`);
+          throw new Error(`simulated comment failure for ${id}`);
+        }
+        comments.push({ id, comment });
+        calls.push(`comment(${id})`);
+      },
+      appendNotes: (id, appended) => {
+        if (input.appendNotesShouldThrow?.(id)) {
+          calls.push(`appendNotes(${id}) THREW`);
+          throw new Error(`simulated appendNotes failure for ${id}`);
+        }
+        notes[id] = `${notes[id] ?? ''}\n\n${appended}`;
+        appendedNotes.push({ id, notes: appended });
+        calls.push(`appendNotes(${id})`);
+      },
+      readNotes: (id) => notes[id] ?? null,
+      setDescription: (id, description) => {
+        if (input.setDescriptionShouldThrow?.(id)) {
+          calls.push(`setDescription(${id}) THREW`);
+          throw new Error(`simulated setDescription failure for ${id}`);
+        }
+        descriptions[id] = description;
+        descriptionEdits.push({ id, description });
+        calls.push(`setDescription(${id})`);
+      },
+      readDescription: (id) => {
+        if (input.readDescriptionShouldThrow?.(id)) {
+          calls.push(`readDescription(${id}) THREW`);
+          throw new Error(`simulated readDescription failure for ${id}`);
+        }
+        calls.push(`readDescription(${id})`);
+        return descriptions[id] ?? null;
+      },
+    },
+    git: {
+      hasPendingBacklogChanges: () => input.hasPendingBacklogChanges ?? false,
+      commitBacklogChanges: (message) => {
+        boardCommits.push(message);
+        calls.push('commitBacklogChanges');
+        input.commitBacklogChanges?.(message);
+      },
+      saveWipAndPush: (branch) => {
+        calls.push(`saveWipAndPush(${branch})`);
+        return input.saveWipAndPush ? input.saveWipAndPush(branch) : { pushSucceeded: true };
+      },
+      detachSlot: (slotPath) => {
+        detachedSlots.push(slotPath);
+        calls.push(`detachSlot(${slotPath})`);
+      },
+      branchExists: (branch) => input.branchExists?.(branch) ?? false,
+      deleteLocalBranch: (branch) => {
+        deletedLocalBranches.push(branch);
+        calls.push(`deleteLocalBranch(${branch})`);
+      },
+      deleteRemoteBranch: (branch) => {
+        deletedRemoteBranches.push(branch);
+        calls.push(`deleteRemoteBranch(${branch})`);
+        return input.deleteRemoteBranchResult?.(branch) ?? REMOTE_BRANCH_DELETE_RESULT.DELETED;
+      },
+      branchHasUnmergedCommits: (branch, baseRef) => {
+        branchCleanupChecks.push({ branch, baseRef });
+        calls.push(`branchHasUnmergedCommits(${branch},${baseRef})`);
+        return input.branchHasUnmergedCommits?.(branch, baseRef) ?? false;
+      },
+    },
+    killProcess: (pid) => {
+      calls.push(`killProcess(${pid})`);
+    },
+    notify: (title, body) => {
+      notifications.push({ title, body });
+      calls.push('notify');
+    },
+  };
+
+  return {
+    ctx,
+    calls,
+    slotsAfter: () => ({ slots }),
+    lockRemovals: () => removedLocks,
+    statusEdits: () => statusEdits,
+    comments: () => comments,
+    appendedNotes: () => appendedNotes,
+    notesFor: (taskId) => notes[taskId] ?? null,
+    descriptionFor: (taskId) => descriptions[taskId] ?? null,
+    descriptionEdits: () => descriptionEdits,
+    boardCommits: () => boardCommits,
+    detachedSlots: () => detachedSlots,
+    notifications: () => notifications,
+    deletedLocalBranches: () => deletedLocalBranches,
+    deletedRemoteBranches: () => deletedRemoteBranches,
+    branchCleanupChecks: () => branchCleanupChecks,
+    mutateRegistryConcurrently: (mutate) => {
+      slots = mutate(slots);
+    },
+  };
+}
+
+// ── Step 1: dead-PID / expired-TTL locks ───────────────────────────────────────
+
+describe('runMaintenance — dead lock sweep', () => {
+  it('releases a lock whose PID is dead, and releases its slot', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999 })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.releasedLocks, ['T-1']);
+    assert.deepEqual(collaborators.lockRemovals(), ['T-1']);
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, null);
+  });
+
+  it('releases a lock whose heartbeat exceeded the TTL, even with a live PID', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 111)],
+      locks: [
+        makeLock({ taskId: 'T-1', heartbeatAt: new Date(NOW - TTL_MS - 1_000).toISOString() }),
+      ],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.releasedLocks, ['T-1']);
+  });
+
+  // J15: the release is a TRANSFORM replayed against the registry at the end of the pass, so by
+  // then the entry no longer says where the work is. The detach has to happen eagerly, against the
+  // snapshot that still names the slot — asserting only that both happened would pass either way.
+  it('detaches the worktree BEFORE the slot entry stops naming it', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999 })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    const detachIndex = collaborators.calls.findIndex((call) => call.startsWith('detachSlot('));
+    const updateIndex = collaborators.calls.indexOf('updateSlots');
+    assert.notEqual(detachIndex, -1, 'the swept slot must be detached');
+    assert.notEqual(updateIndex, -1, 'the registry must be written');
+    assert.ok(
+      detachIndex < updateIndex,
+      'detaching after the registry write leaves nothing to detach',
+    );
+  });
+
+  it('keeps a lock alive when the PID lives and the heartbeat is within the TTL', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 111)],
+      locks: [makeLock({ taskId: 'T-1' })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.releasedLocks, []);
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, 'T-1');
+  });
+});
+
+// ── Step 2: orphan slots (no live process) ─────────────────────────────────────
+
+describe('runMaintenance — orphan slot release', () => {
+  it('releases a slot that is occupied but has no lock at all', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-b', 'frontier', 'T-2', 222)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-2' })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.releasedOrphanSlots, ['T-2']);
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, null);
+  });
+});
+
+// ── Step 3: merged PR -> Done ───────────────────────────────────────────────────
+
+describe('runMaintenance — merged PR moves a task to Done', () => {
+  it('moves an In Progress task to Done when gh reports its branch merged', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3']);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-3', status: TASK_STATUS.DONE }]);
+  });
+
+  // K9: a retry runs on the SAME branch, and the previous attempt's PR may already be merged. This
+  // step then declared the task Done while its worker was mid-run — the close that followed found a
+  // task nobody was waiting for, and step 4 read `Done` as "not cancelled" and left the worker
+  // running against a closed task. An alive lock means a live attempt: this step is not its judge.
+  it('leaves a task with a LIVE worker alone, even when a previous attempt PR is merged', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-3', 111)],
+      locks: [makeLock({ taskId: 'T-3' })],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPidAlive: () => true,
+      isPrMerged: (branch) => branch === 'task/T-3',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, []);
+    assert.ok(
+      !collaborators.statusEdits().some((edit) => edit.status === TASK_STATUS.DONE),
+      'a live attempt must not be closed out from under its own worker',
+    );
+  });
+
+  it('leaves an In Progress task alone when its PR is not merged', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, []);
+  });
+});
+
+// ── T-68: the «Registro de ejecución» block, written at the SAME Done transition ────────────
+
+describe('runMaintenance — the «Registro de ejecución» block at the Done transition', () => {
+  it('appends the block once the task reaches Done, built from its own attempts data', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, lane: LANE.LOCAL, attempts: 1 }),
+      ],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      attemptStreamOutcome: (taskId, attempt) =>
+        taskId === 'T-3' && attempt === 1 ? 'completed' : null,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3']);
+    const appended = collaborators.appendedNotes();
+    assert.equal(appended.length, 1, 'the block is appended exactly once for this task');
+    assert.equal(appended[0]?.id, 'T-3');
+    assert.match(appended[0]?.notes ?? '', /^## Registro de ejecución/);
+    assert.match(appended[0]?.notes ?? '', /\*\*Resultado del intento 1:\*\* Done/);
+    assert.match(appended[0]?.notes ?? '', /\*\*Fuente:\*\* \.backlog\/\.dispatch\/T-3\/intento-1/);
+  });
+
+  it('does not duplicate the block on a pass that finds the heading already in the notes (§12.3)', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, attempts: 1 })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      // Simulates a task whose record was already written (by an earlier pass, or this same one
+      // re-entering step 3 before its own board snapshot caught up) — the sentinel must stop a
+      // second append regardless of how the notes got there.
+      notesBefore: { 'T-3': 'Some earlier note.\n\n## Registro de ejecución\n\n- **Modo:** headless' },
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3'], 'the task still reaches Done on its own merit');
+    assert.deepEqual(collaborators.appendedNotes(), []);
+  });
+
+  // ── T-68: the record write is attempted BEFORE the transition, but a failed write NEVER blocks
+  // it — a merged PR is a confirmed fact. A task kept out of `Done` would be invisible to the orphan
+  // sweep AND to `cleanupBranchOnDone`, and no later pass would revisit it.
+
+  it('appendNotes throws: the task still reaches Done in the SAME pass, branch cleanup still runs, one comment', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, lane: LANE.LOCAL, attempts: 1 }),
+      ],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      attemptStreamOutcome: (taskId, attempt) =>
+        taskId === 'T-3' && attempt === 1 ? 'completed' : null,
+      appendNotesShouldThrow: (taskId) => taskId === 'T-3',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(
+      result.movedToDone,
+      ['T-3'],
+      'a failed record write must never hold the merged-PR transition hostage',
+    );
+    assert.deepEqual(
+      result.cleanedUpBranches,
+      ['T-3'],
+      'the transition proceeded for real — branch cleanup ran exactly as it would on a clean write',
+    );
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-3', status: TASK_STATUS.DONE }]);
+    assert.deepEqual(collaborators.appendedNotes(), [], 'the block itself never landed on the board');
+    // `collaborators.comments()` also carries the ORDINARY "PR mergeado" comment `setStatus` posts
+    // on every Done transition (fixture design: both kinds land in one list) — filtering by content
+    // isolates the ONE comment this failure itself produced, apart from that unrelated one.
+    const failureComments = collaborators
+      .comments()
+      .filter((entry) => entry.id === 'T-3' && entry.comment.includes('Registro de ejecución'));
+    assert.equal(failureComments.length, 1, 'exactly one comment records the gap');
+
+    // Item 4: "no spam" — proved, not assumed. A FRESH pass whose board read already shows this
+    // task `Done` (the real shape a later `loadBoard` would report, now that `setStatus` landed for
+    // real above) must never revisit it: step 3's own `status === IN_PROGRESS` guard is what stops
+    // a second appendNotes/comment attempt, not any bookkeeping this write introduces.
+    const nextPassCollaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.DONE, lane: LANE.LOCAL, attempts: 1 })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      appendNotesShouldThrow: (taskId) => taskId === 'T-3',
+    });
+    const nextPass = runMaintenance(nextPassCollaborators.ctx);
+    assert.deepEqual(nextPass.movedToDone, []);
+    assert.deepEqual(nextPassCollaborators.comments(), [], 'a Done task is never revisited at all');
+  });
+
+  it('comment ALSO throws: the pass itself never throws, and the task still reaches Done', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, lane: LANE.LOCAL, attempts: 1 }),
+      ],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      appendNotesShouldThrow: (taskId) => taskId === 'T-3',
+      commentShouldThrow: (taskId) => taskId === 'T-3',
+    });
+
+    let result: ReturnType<typeof runMaintenance> | undefined;
+    assert.doesNotThrow(() => {
+      result = runMaintenance(collaborators.ctx);
+    });
+    assert.deepEqual(result?.movedToDone, ['T-3']);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-3', status: TASK_STATUS.DONE }]);
+  });
+
+  it('a field the attempts hold no data for is written as desconocido, never guessed (AC3)', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, lane: LANE.FRONTIER, attempts: 1 })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      // No fake wired for `attemptStreamOutcome` at all — every attempt reads as unknown, exactly
+      // the "no attempt data" case AC3 exercises.
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    const notes = collaborators.notesFor('T-3') ?? '';
+    assert.match(notes, /\*\*Fallos de entorno:\*\* desconocido/);
+    assert.match(notes, /\*\*Tiempo de ciclo:\*\* desconocido/);
+  });
+
+  it('carries a real Blocked cause from a retried attempt into the record, not just the retry count', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, lane: LANE.LOCAL, attempts: 2 }),
+      ],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      attemptStreamOutcome: (taskId, attempt) => {
+        if (taskId !== 'T-3') return null;
+        return attempt === 1 ? 'needs-guidance' : attempt === 2 ? 'completed' : null;
+      },
+      // Attempt 1 never reached the reviewer step (it hit `needs-guidance` before the close's own
+      // steps ran) — no `review.md`. Attempt 2 completed and its close reviewer passed it.
+      attemptReviewVerdict: (taskId, attempt) => {
+        if (taskId !== 'T-3') return null;
+        return attempt === 2 ? 'pass' : null;
+      },
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    const notes = collaborators.notesFor('T-3') ?? '';
+    assert.match(notes, /\*\*Resultado del intento 1:\*\* Blocked \(needs-guidance\)/);
+    // Fix 2: "Rondas de corrección" comes from `review.md` FAIL verdicts, not the retry count — one
+    // review.md exists (attempt 2, PASS), zero FAILs, so 0 rounds, never `attempts - 1` (which
+    // would wrongly say 1: a needs-guidance retry is not a correction round).
+    assert.match(notes, /\*\*Rondas de corrección:\*\* 0 — revisor: code-review/);
+    assert.match(notes, /\*\*Intervenciones humanas:\*\* 1 — tipo: respuesta a Blocked/);
+  });
+
+  // ── T-68 latest: a merged-PR task never dispatched at all (attempts: 0) is a SUPERVISADA task —
+  // the Worktree Gate forces even an interactive session onto `task/T-nn`, so step 3 closes it out
+  // exactly like a headless one the instant its PR merges. ────────────────────────────────────────
+
+  it('a never-dispatched (attempts: 0) merged-PR task gets the supervisada block, with its PR number as Fuente', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, attempts: 0 })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      prNumber: (branch) => (branch === 'task/T-3' ? 188 : null),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3']);
+    const notes = collaborators.notesFor('T-3') ?? '';
+    assert.match(notes, /\*\*Modo:\*\* supervisada — desconocido/);
+    assert.match(notes, /\*\*Intervenciones humanas:\*\* desconocido — tipo: desconocido/);
+    assert.match(notes, /\*\*Fuente:\*\* PR #188/);
+  });
+
+  it('a never-dispatched task whose notes ALREADY carry the heading (orchestrator-written) gets no append', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS, attempts: 0 })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      prNumber: () => 188,
+      // The orchestrator (a person, in the supervisada session itself) already appended its OWN
+      // block by hand before the reconciler's next pass ever sees the merged PR.
+      notesBefore: {
+        'T-3': 'Some earlier note.\n\n## Registro de ejecución\n\n- **Modo:** supervisada — el humano lo escribió',
+      },
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3'], 'the task still reaches Done on its own merit');
+    assert.deepEqual(collaborators.appendedNotes(), []);
+  });
+
+  it('never appends the block for step 3b\'s revert — that moves a task AWAY from Done', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.DONE, attempts: 1 })],
+      branchExists: (branch) => branch === 'task/T-3',
+      mergedState: () => 'not-merged',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.revertedHandwrittenDone, ['T-3']);
+    assert.deepEqual(collaborators.appendedNotes(), []);
+  });
+});
+
+// ── T-8 point 5: branch cleanup once a task reaches Done ─────────────────────
+
+describe('runMaintenance — branch cleanup on Done', () => {
+  it('deletes the local and remote task/<id> branch once the merged-PR check moves the task to Done', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3']);
+    assert.deepEqual(result.cleanedUpBranches, ['T-3']);
+    assert.deepEqual(collaborators.deletedLocalBranches(), ['task/T-3']);
+    assert.deepEqual(collaborators.deletedRemoteBranches(), ['task/T-3']);
+  });
+
+  // Defect 7 (2026-09-08): a failed remote delete used to be swallowed identically to an
+  // already-absent ref, and the task was reported in `cleanedUpBranches` either way — a field whose
+  // own JSDoc promises "this pass deleted" the branch. A REAL failure (bad auth, a protected-branch
+  // rule, a network timeout) must be distinguishable and must keep the task OUT of that field.
+  it('does not report the branch as cleaned up when the remote delete genuinely fails', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      deleteRemoteBranchResult: () => REMOTE_BRANCH_DELETE_RESULT.FAILED,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3'], 'the task still reaches Done on its own merit');
+    assert.deepEqual(
+      result.cleanedUpBranches,
+      [],
+      'a failed remote delete must not read as cleaned up',
+    );
+    // The local ref is still removed — only the REMOTE outcome gates the result.
+    assert.deepEqual(collaborators.deletedLocalBranches(), ['task/T-3']);
+    assert.deepEqual(collaborators.deletedRemoteBranches(), ['task/T-3']);
+  });
+
+  // The mirror case: an ALREADY-ABSENT remote ref (GitHub's own auto-delete beat this pass to it)
+  // is the legitimate, common outcome and must still count as cleaned up.
+  it('still reports the branch as cleaned up when the remote ref was already gone', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      deleteRemoteBranchResult: () => REMOTE_BRANCH_DELETE_RESULT.ALREADY_GONE,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cleanedUpBranches, ['T-3']);
+  });
+
+  it('deletes the branch of a PARENT the recompute step itself closes', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-10', status: TASK_STATUS.IN_PROGRESS }),
+        makeTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE }),
+      ],
+      isPrMerged: (branch) => branch === 'task/T-10',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    // Step 3's generic merged-PR check catches T-10 directly (it is In Progress with its own
+    // merged PR) — the SAME path a leaf task takes. `recomputeParent` never runs a second
+    // transition on top of it (see the "never double-transitions" test above), so the branch
+    // cleanup fires exactly once, from step 3, not from the parent-recompute step.
+    assert.deepEqual(result.movedToDone, ['T-10']);
+    assert.deepEqual(result.cleanedUpBranches, ['T-10']);
+    assert.deepEqual(collaborators.deletedLocalBranches(), ['task/T-10']);
+  });
+
+  // The task's own wording: "Nunca en Blocked" — a task the dead-worker sweep blocks is the one
+  // case the cleanup must never reach, because that branch is the only copy of the work a person
+  // will come back to.
+  it('never deletes a branch when a task moves to Blocked', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999 })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.releasedLocks, ['T-1']);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-1', status: TASK_STATUS.BLOCKED }]);
+    assert.deepEqual(result.cleanedUpBranches, []);
+    assert.deepEqual(collaborators.deletedLocalBranches(), []);
+    assert.deepEqual(collaborators.deletedRemoteBranches(), []);
+  });
+
+  it('leaves an In Progress task with an unmerged PR untouched — no branch deleted', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: () => false,
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(collaborators.deletedLocalBranches(), []);
+    assert.deepEqual(collaborators.deletedRemoteBranches(), []);
+  });
+
+  // The remaining T-8 point 5 data-loss path (2026-09-08), the exact T-6.3 shape: a `gh` outage
+  // makes the dead-worker rescue (step 1) push WIP commits onto task/T-20, whose PR was in fact
+  // already merged (defect 8's deliberate `unknown` → still-push behaviour, which must stay). `gh`
+  // then recovers, step 3 reads `merged`, and — before this fix — deleted both refs unconditionally,
+  // destroying those commits outright rather than merely stranding them. Before this fix,
+  // `branchHasUnmergedCommits` did not exist at all and `cleanupBranchOnDone` always deleted once
+  // the PR read merged, so this assertion FAILS against that code: `cleanedUpBranches` held `T-20`
+  // and both branches were deleted.
+  it('refuses to delete a Done task branch that carries commits not reachable from its base', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-20', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-20',
+      // Simulates the rescue push having landed a WIP commit after the merge: git confirms the
+      // branch is NOT fully contained in its base.
+      branchHasUnmergedCommits: (branch) => branch === 'task/T-20',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-20'], 'the task still reaches Done on its own merit');
+    assert.deepEqual(
+      result.cleanedUpBranches,
+      [],
+      'a branch with unmerged commits must never read as cleaned up',
+    );
+    assert.deepEqual(
+      result.branchCleanupRefused,
+      ['T-20'],
+      'the refusal must be reported, distinct from cleanedUpBranches and from a delete failure',
+    );
+    assert.deepEqual(
+      collaborators.deletedLocalBranches(),
+      [],
+      'neither ref may be touched once the branch fails the safety check',
+    );
+    assert.deepEqual(collaborators.deletedRemoteBranches(), []);
+    // Two comments land on T-20: the setStatus one from moving it to Done, and this refusal's
+    // own — matched by its content, not just the id, since `.find` on id alone would silently pick
+    // whichever comment happens to come first.
+    const comment =
+      collaborators
+        .comments()
+        .find((entry) => entry.id === 'T-20' && /NO borrada/.test(entry.comment))?.comment ?? '';
+    assert.match(comment, /task\/T-20/, 'the comment must name the branch');
+    assert.match(comment, /origin\/main/, 'the comment must name the base it was compared against');
+  });
+
+  it('deletes the branch normally once the safety check confirms it carries nothing beyond base', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-20', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-20',
+      branchHasUnmergedCommits: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cleanedUpBranches, ['T-20']);
+    assert.deepEqual(result.branchCleanupRefused, []);
+    assert.deepEqual(collaborators.deletedLocalBranches(), ['task/T-20']);
+    assert.deepEqual(collaborators.deletedRemoteBranches(), ['task/T-20']);
+  });
+
+  // A subtask's base is its PARENT's branch, never `main` — comparing against `main` would report
+  // every commit the parent branch already carries as this subtask's own and refuse every subtask
+  // cleanup. Uses `resolveTaskBase`'s naming (`guards.ts`'s `taskBaseBranch`), the SAME base the
+  // scope check and the PR diff already use.
+  it('compares a subtask against its PARENT branch, never main', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-21', parentId: 'T-10', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-21',
+      branchHasUnmergedCommits: () => false,
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(collaborators.branchCleanupChecks(), [
+      { branch: 'task/T-21', baseRef: 'origin/task/T-10' },
+    ]);
+  });
+
+  // Refusal on the PARENT-recomputation path (step 5), not just the leaf path (step 3).
+  it('also refuses branch cleanup on the parent-recomputation path when unmerged commits remain', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-30', status: TASK_STATUS.TO_DO }),
+        makeTask({ id: 'T-31', parentId: 'T-30', status: TASK_STATUS.DONE }),
+      ],
+      isPrMerged: (branch) => branch === 'task/T-30',
+      mergedState: (branch) => (branch === 'task/T-30' ? 'merged' : 'not-merged'),
+      branchHasUnmergedCommits: (branch) => branch === 'task/T-30',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recomputedParents, [
+      { id: 'T-30', from: TASK_STATUS.TO_DO, to: TASK_STATUS.DONE },
+    ]);
+    assert.deepEqual(result.cleanedUpBranches, []);
+    assert.deepEqual(result.branchCleanupRefused, ['T-30']);
+    assert.deepEqual(collaborators.deletedLocalBranches(), []);
+    assert.deepEqual(collaborators.deletedRemoteBranches(), []);
+  });
+});
+
+// ── T-8 point 7: a hand-written Done never merged is reverted ────────────────
+
+describe('runMaintenance — hand-written Done reverted when its PR is not merged', () => {
+  it('reverts a Done task to In Progress when its branch exists but GitHub does not report the PR merged', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-9', status: TASK_STATUS.DONE })],
+      branchExists: (branch) => branch === 'task/T-9',
+      mergedState: () => 'not-merged',
+      prState: () => 'OPEN',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.revertedHandwrittenDone, ['T-9']);
+    assert.deepEqual(collaborators.statusEdits(), [
+      { id: 'T-9', status: TASK_STATUS.IN_PROGRESS },
+    ]);
+    const comment = collaborators.comments().find((entry) => entry.id === 'T-9')?.comment ?? '';
+    assert.match(comment, /task\/T-9/, 'the comment must name the branch');
+    assert.match(comment, /OPEN/, 'the comment must name the PR state GitHub reported');
+  });
+
+  it('leaves a Done task with no branch and no PR untouched — legitimately finished by hand', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-9', status: TASK_STATUS.DONE })],
+      branchExists: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.revertedHandwrittenDone, []);
+    assert.deepEqual(collaborators.statusEdits(), []);
+  });
+
+  it('leaves a Done task alone when its branch exists and its PR IS merged', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-9', status: TASK_STATUS.DONE })],
+      branchExists: (branch) => branch === 'task/T-9',
+      mergedState: (branch) => (branch === 'task/T-9' ? 'merged' : 'unknown'),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.revertedHandwrittenDone, []);
+    assert.deepEqual(collaborators.statusEdits(), []);
+  });
+
+  it('does not revert a Done task this SAME pass just produced via the merged-PR check', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      branchExists: (branch) => branch === 'task/T-3',
+      mergedState: (branch) => (branch === 'task/T-3' ? 'merged' : 'not-merged'),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-3']);
+    assert.deepEqual(result.revertedHandwrittenDone, []);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-3', status: TASK_STATUS.DONE }]);
+  });
+
+  // T-8 defect 1 [CRITICAL]: a `gh` outage (missing binary, expired token, network failure) used
+  // to answer `isPrMerged` with the SAME `false` a genuinely-unmerged PR gets. Step 3b read that
+  // `false` as "GitHub confirms this is not merged" and reverted EVERY `Done` task whose local
+  // `task/<id>` ref still existed — a whole reconciler pass mass-reverting the `Done` column,
+  // including tasks that merged perfectly correctly. `mergedState` must answer `unknown` for an
+  // outage, never `not-merged`, and step 3b must SKIP (never revert) on `unknown`.
+  it('does not revert any hand-written Done when gh is unavailable — unknown is not "not merged"', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-9', status: TASK_STATUS.DONE }),
+        makeTask({ id: 'T-20', status: TASK_STATUS.DONE }),
+      ],
+      // Every task's local `task/<id>` ref still exists — the exact fan-out that turned a single
+      // `gh` outage into a mass-revert.
+      branchExists: () => true,
+      mergedState: () => 'unknown',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.revertedHandwrittenDone, []);
+    assert.deepEqual(collaborators.statusEdits(), []);
+  });
+});
+
+// ── T-8 defect 2 [HIGH]: step 3b's revert must not cascade into step 3c the SAME pass ────────
+
+describe('runMaintenance — a step 3b revert is never re-blocked as an orphan in the same pass', () => {
+  it('does not orphan-block a task step 3b just reverted, even though updated_date is stale', () => {
+    const FIVE_HOURS_MS = 5 * 3_600_000; // > the 4h default orphan threshold (DEFAULT_ORPHAN_THRESHOLD_MS)
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      // Measured scenario: a person pushes task/T-20, opens a PR, and marks the task Done by hand
+      // at 09:00. This pass runs at 14:00 — updated_date is still stamped at 09:00, five hours old.
+      tasks: [makeTask({ id: 'T-20', status: TASK_STATUS.DONE, updatedAt: NOW - FIVE_HOURS_MS })],
+      branchExists: (branch) => branch === 'task/T-20',
+      mergedState: () => 'not-merged', // the PR is still open — step 3b correctly reverts it (AC7).
+      hasAttemptDir: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.revertedHandwrittenDone, ['T-20']);
+    assert.deepEqual(
+      result.orphanInProgressBlocked,
+      [],
+      'a task step 3b just reverted to In Progress must not be re-blocked as an orphan in the SAME pass',
+    );
+    assert.deepEqual(collaborators.statusEdits(), [
+      { id: 'T-20', status: TASK_STATUS.IN_PROGRESS },
+    ]);
+  });
+});
+
+// ── T-8 point 10: an orphan In Progress is blocked ────────────────────────────
+
+describe('runMaintenance — orphan In Progress detection', () => {
+  const OLD_ENOUGH = NOW - DEFAULT_ORPHAN_THRESHOLD_MS - 60_000;
+
+  it('blocks an In Progress task with no lock, no slot, no attempt dir and a stale updated_date', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-8', status: TASK_STATUS.IN_PROGRESS, updatedAt: OLD_ENOUGH })],
+      hasAttemptDir: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, ['T-8']);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-8', status: TASK_STATUS.BLOCKED }]);
+    const comment = collaborators.comments().find((entry) => entry.id === 'T-8')?.comment ?? '';
+    assert.match(comment, /lock/i);
+    assert.match(comment, /slot/i);
+    assert.match(comment, /intento/i);
+    assert.match(comment, /updated_date|actualizaci/i);
+  });
+
+  it('leaves it alone when updated_date is within the threshold — a live interactive session', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-8', status: TASK_STATUS.IN_PROGRESS, updatedAt: NOW - 60_000 })],
+      hasAttemptDir: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, []);
+    assert.deepEqual(collaborators.statusEdits(), []);
+  });
+
+  it('leaves it alone when a live lock still holds it — the dead-worker sweep territory', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-8', 111)],
+      locks: [makeLock({ taskId: 'T-8' })],
+      tasks: [makeTask({ id: 'T-8', status: TASK_STATUS.IN_PROGRESS, updatedAt: OLD_ENOUGH })],
+      isPidAlive: () => true,
+      hasAttemptDir: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, []);
+  });
+
+  it('leaves it alone when a slot still claims the task even with no live lock (held for recovery)', () => {
+    const held: SlotInfo = {
+      ...busySlot('dispatch-a', 'local', 'T-8', 999),
+      heldForRecovery: true,
+    };
+    const collaborators = makeCollaborators({
+      slots: [held],
+      locks: [],
+      tasks: [makeTask({ id: 'T-8', status: TASK_STATUS.IN_PROGRESS, updatedAt: OLD_ENOUGH })],
+      hasAttemptDir: () => false,
+      // Step 0 retries a held-for-recovery slot's push FIRST and releases it on success — pinning
+      // the push as still-failing is what keeps the slot claiming T-8 through to step 3c, which is
+      // the scenario this test means to exercise.
+      saveWipAndPush: () => ({ pushSucceeded: false }),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, []);
+  });
+
+  it('leaves it alone when an attempt directory exists — it WAS dispatched at some point', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-8', status: TASK_STATUS.IN_PROGRESS, updatedAt: OLD_ENOUGH })],
+      hasAttemptDir: (taskId) => taskId === 'T-8',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, []);
+  });
+
+  it('never touches a task in any status other than In Progress', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-8', status: TASK_STATUS.TO_DO, updatedAt: OLD_ENOUGH })],
+      hasAttemptDir: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, []);
+  });
+
+  // Measured incident: a Complex parent whose children are (Done, Done, To Do, To Do) derives
+  // `In Progress` (parent.ts) with no lock/slot/attempt-dir of its own, since a parent's status is
+  // never written by hand. Step 3c saw the same absence a real orphan leaves and blocked it,
+  // writing a false "orphan" comment on every pass since it was set to `In Progress`.
+  it('does not block a parent In Progress whose status is derived from its children', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-4', status: TASK_STATUS.IN_PROGRESS, updatedAt: OLD_ENOUGH }),
+        makeTask({ id: 'T-4.1', status: TASK_STATUS.DONE, parentId: 'T-4' }),
+        makeTask({ id: 'T-4.2', status: TASK_STATUS.DONE, parentId: 'T-4' }),
+        makeTask({ id: 'T-4.3', status: TASK_STATUS.TO_DO, parentId: 'T-4' }),
+        makeTask({ id: 'T-4.4', status: TASK_STATUS.TO_DO, parentId: 'T-4' }),
+      ],
+      hasAttemptDir: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, []);
+    assert.deepEqual(
+      collaborators.statusEdits().filter((edit) => edit.id === 'T-4'),
+      [],
+      'a parent must never be moved to Blocked by the orphan sweep — its status is derived, never orphaned',
+    );
+  });
+
+  // Sibling of the test above: a CHILDLESS In Progress task in the exact same state (no lock, no
+  // slot, no attempt dir, stale updated_date) is still a real orphan and must still be blocked —
+  // the parent exemption must not become a blanket exemption.
+  it('still blocks a childless In Progress task in the same state — no regression', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-9', status: TASK_STATUS.IN_PROGRESS, updatedAt: OLD_ENOUGH })],
+      hasAttemptDir: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.orphanInProgressBlocked, ['T-9']);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-9', status: TASK_STATUS.BLOCKED }]);
+  });
+});
+
+// ── Step 4: manual cancellation — save before kill before release ─────────────
+
+describe('runMaintenance — manual cancellation ordering', () => {
+  it('saves work, THEN kills the worker, THEN releases the lock/slot — never any other order', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+      locks: [makeLock({ taskId: 'T-4', pid: 444 })],
+      // The person moved it back to Blocked by hand; the lock is still alive.
+      tasks: [makeTask({ id: 'T-4', status: TASK_STATUS.BLOCKED })],
+      isPidAlive: () => true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cancelledWorkers, ['T-4']);
+    const relevant = collaborators.calls.filter(
+      (call) =>
+        call.startsWith('saveWipAndPush') ||
+        call.startsWith('killProcess') ||
+        call.startsWith('removeLock'),
+    );
+    assert.deepEqual(relevant, [
+      'saveWipAndPush(task/T-4)',
+      'killProcess(444)',
+      'removeLock(T-4)',
+    ]);
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, null);
+  });
+
+  it('does not kill or release when the WIP push fails — retried on the next pass', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+      locks: [makeLock({ taskId: 'T-4', pid: 444 })],
+      tasks: [makeTask({ id: 'T-4', status: TASK_STATUS.TO_DO })],
+      isPidAlive: () => true,
+      saveWipAndPush: () => ({ pushSucceeded: false }),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cancelledWorkers, []);
+    assert.ok(!collaborators.calls.some((call) => call.startsWith('killProcess')));
+    assert.ok(!collaborators.calls.some((call) => call.startsWith('removeLock')));
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, 'T-4');
+  });
+
+  it('does not touch a lock whose task is still legitimately In Progress', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+      locks: [makeLock({ taskId: 'T-4', pid: 444 })],
+      tasks: [makeTask({ id: 'T-4', status: TASK_STATUS.IN_PROGRESS })],
+      isPidAlive: () => true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cancelledWorkers, []);
+    assert.ok(!collaborators.calls.some((call) => call.startsWith('saveWipAndPush')));
+  });
+
+  // G13: cancellation is an explicit human act — moving the task to Blocked or To Do. Any OTHER
+  // status is a state this pass does not understand, and killing on it kills a healthy worker.
+  for (const status of [TASK_STATUS.DONE, TASK_STATUS.QUEUED, TASK_STATUS.UNKNOWN] as const) {
+    it(`never cancels on ${status}: only an explicit Blocked or To Do is a cancellation`, () => {
+      const collaborators = makeCollaborators({
+        slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+        locks: [makeLock({ taskId: 'T-4', pid: 444 })],
+        tasks: [makeTask({ id: 'T-4', status })],
+        isPidAlive: () => true,
+      });
+
+      const result = runMaintenance(collaborators.ctx);
+
+      assert.deepEqual(result.cancelledWorkers, []);
+      assert.ok(!collaborators.calls.some((call) => call.startsWith('killProcess')));
+    });
+  }
+
+  it('still cancels a lock whose task no longer exists on the board at all', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+      locks: [makeLock({ taskId: 'T-4', pid: 444 })],
+      tasks: [],
+      isPidAlive: () => true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cancelledWorkers, ['T-4']);
+  });
+
+  // N3: "the task is not on the board" means "a person deleted it" ONLY when the board was read in
+  // full. `backlog task list` failing, or one `task view` throwing, produces the same absence — and
+  // reading it as a deletion killed EVERY live worker at once, the one failure mode a maintenance
+  // sweep must not have.
+  it('never reads an absent task as a cancellation when the board came back incomplete', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+      locks: [makeLock({ taskId: 'T-4', pid: 444 })],
+      tasks: [],
+      boardComplete: false,
+      isPidAlive: () => true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cancelledWorkers, []);
+    assert.ok(!collaborators.calls.some((call) => call.startsWith('killProcess')));
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, 'T-4');
+  });
+
+  // The status-based half still runs: a task this pass DID read as `Blocked` is an explicit human
+  // act, and a partial board says nothing about it.
+  it('still cancels on an explicit Blocked that WAS read, even on an incomplete board', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+      locks: [makeLock({ taskId: 'T-4', pid: 444 })],
+      tasks: [makeTask({ id: 'T-4', status: TASK_STATUS.BLOCKED })],
+      boardComplete: false,
+      isPidAlive: () => true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cancelledWorkers, ['T-4']);
+  });
+});
+
+// ── Step 5: recompute every parent ──────────────────────────────────────────────
+
+describe('runMaintenance — parent recomputation', () => {
+  // N3: a parent's state is DERIVED from the full set of its children. Half a child set derives a
+  // parent status that is simply wrong — two children read as `Done` while the third, dropped by a
+  // failed `task view`, is still `In Progress`, and the parent moves to `Done`. The derivation is
+  // skipped entirely rather than run on a partial board.
+  it('writes no parent status at all when the board came back incomplete', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+        makeTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE }),
+        makeTask({ id: 'T-12', parentId: 'T-10', status: TASK_STATUS.DONE }),
+      ],
+      boardComplete: false,
+      isPrMerged: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recomputedParents, []);
+    assert.deepEqual(collaborators.statusEdits(), []);
+  });
+
+  it('recomputes a parent whose children are all Done as In Progress (own PR not merged)', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+        makeTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE }),
+        makeTask({ id: 'T-12', parentId: 'T-10', status: TASK_STATUS.DONE }),
+      ],
+      isPrMerged: () => false,
+      mergedState: () => 'not-merged',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recomputedParents, [
+      { id: 'T-10', from: TASK_STATUS.TO_DO, to: TASK_STATUS.IN_PROGRESS },
+    ]);
+  });
+
+  it('recomputes a parent whose own PR just merged and every child is Done, via the generic merged-PR check', () => {
+    // A parent is itself a normal task: when it is In Progress and its own branch's PR merges,
+    // step 3's generic check already moves it to Done — the recompute step then finds no further
+    // change needed (never double-transitions the same task).
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-10', status: TASK_STATUS.IN_PROGRESS }),
+        makeTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.DONE }),
+      ],
+      isPrMerged: (branch) => branch === 'task/T-10',
+      mergedState: (branch) => (branch === 'task/T-10' ? 'merged' : 'not-merged'),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.movedToDone, ['T-10']);
+    assert.deepEqual(result.recomputedParents, []);
+  });
+
+  it('recomputes recursively: a Blocked grandchild bubbles Blocked up through every ancestor', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-10', status: TASK_STATUS.IN_PROGRESS }),
+        makeTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.IN_PROGRESS }),
+        makeTask({ id: 'T-12', parentId: 'T-11', status: TASK_STATUS.BLOCKED }),
+      ],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recomputedParents, [
+      { id: 'T-10', from: TASK_STATUS.IN_PROGRESS, to: TASK_STATUS.BLOCKED },
+      { id: 'T-11', from: TASK_STATUS.IN_PROGRESS, to: TASK_STATUS.BLOCKED },
+    ]);
+  });
+
+  it('leaves the parent alone when the derived status matches its current status', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-10', status: TASK_STATUS.TO_DO }),
+        makeTask({ id: 'T-11', parentId: 'T-10', status: TASK_STATUS.TO_DO }),
+      ],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recomputedParents, []);
+  });
+});
+
+// ── Step 5b: refresh the graph-holder task ──────────────────────────────────────
+
+describe('runMaintenance — graph-holder refresh (step 5b)', () => {
+  const holder = (): Task => makeTask({ id: 'T-112', status: TASK_STATUS.TO_DO, isGraphHolder: true });
+  const openTask = (): Task => makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO });
+  const boardFrom = (tasks: Task[]): { tasksById: Record<string, Task> } => ({
+    tasksById: Object.fromEntries(tasks.map((task) => [task.id, task])),
+  });
+
+  it('does not call setDescription when the rendered view already matches the holder description', () => {
+    const tasks = [holder(), openTask()];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': renderHolderDescription(boardFrom(tasks)) },
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(collaborators.descriptionEdits().length, 0);
+    assert.equal(result.graphHolderRefreshed, null);
+  });
+
+  it('calls setDescription once with the fresh text, before the board commit', () => {
+    const tasks = [holder(), openTask()];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': 'stale text' },
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    const expected = renderHolderDescription(boardFrom(tasks));
+    assert.deepEqual(collaborators.descriptionEdits(), [{ id: 'T-112', description: expected }]);
+    assert.equal(result.graphHolderRefreshed, 'T-112');
+    const setIndex = collaborators.calls.indexOf('setDescription(T-112)');
+    const commitIndex = collaborators.calls.indexOf('commitBacklogChanges');
+    assert.ok(setIndex >= 0, 'setDescription must have been called');
+    assert.ok(commitIndex >= 0, 'commitBacklogChanges must have been called');
+    assert.ok(setIndex < commitIndex, 'the holder refresh must land before the board commit');
+  });
+
+  // Step 5b must render over `tasksById` AS STEP 5 (parent recompute) LEFT IT, not the board the
+  // pass started with — the module comment's own justification for the ordering. Asserts on the
+  // WRITTEN DESCRIPTION's content, not merely a call-index comparison, so a regression that renders
+  // from a stale snapshot (right index, wrong data) would still be caught.
+  it('renders the view AFTER parent recomputation: a parent this pass just closed is not an open wait', () => {
+    const tasks = [
+      holder(),
+      makeTask({ id: 'T-1', status: TASK_STATUS.TO_DO, dependsOn: ['T-30'] }),
+      makeTask({ id: 'T-30', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-31', parentId: 'T-30', status: TASK_STATUS.DONE }),
+    ];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': 'stale text' },
+      // T-30's only child is Done and its own PR is merged: step 5 (parent recompute) moves T-30
+      // from To Do to Done in THIS pass.
+      isPrMerged: (branch) => branch === 'task/T-30',
+      mergedState: (branch) => (branch === 'task/T-30' ? 'merged' : 'not-merged'),
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recomputedParents, [
+      { id: 'T-30', from: TASK_STATUS.TO_DO, to: TASK_STATUS.DONE },
+    ]);
+    assert.equal(result.graphHolderRefreshed, 'T-112');
+    const written = collaborators.descriptionFor('T-112');
+    assert.ok(written, 'the holder must have a description after this pass');
+    assert.doesNotMatch(
+      written!,
+      /T-30/,
+      'T-30 is Done by the time step 5b runs, so it must not appear at all — neither as an open task nor as something T-1 waits for',
+    );
+    assert.match(written!, /T-1 \[To Do\]/, 'T-1 must render as READY once T-30 is Done');
+  });
+
+  it('skips the refresh over an incomplete board read, never calling readDescription', () => {
+    const tasks = [holder(), openTask()];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      boardComplete: false,
+      descriptionsBefore: { 'T-112': 'stale text' },
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.graphHolderRefreshed, null);
+    assert.ok(!collaborators.calls.some((call) => call.startsWith('readDescription')));
+    assert.ok(!collaborators.calls.some((call) => call.startsWith('setDescription')));
+  });
+
+  it('writes nothing when no task carries board:graph', () => {
+    const tasks = [openTask()];
+    const collaborators = makeCollaborators({ slots: [], locks: [], tasks });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.graphHolderRefreshed, null);
+    assert.deepEqual(result.graphHolderAmbiguous, []);
+    assert.equal(collaborators.descriptionEdits().length, 0);
+  });
+
+  it('writes the ambiguity notice to BOTH holders and reports every id when two or more carry board:graph', () => {
+    const tasks = [
+      holder(),
+      makeTask({ id: 'T-113', status: TASK_STATUS.TO_DO, isGraphHolder: true }),
+      openTask(),
+    ];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': 'stale text', 'T-113': 'other stale text' },
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.graphHolderRefreshed, null);
+    assert.deepEqual(result.graphHolderAmbiguous, ['T-112', 'T-113']);
+    const notice = ambiguousHolderNotice(['T-112', 'T-113']);
+    assert.deepEqual(
+      collaborators.descriptionEdits().map((edit) => edit.id).sort(),
+      ['T-112', 'T-113'],
+      'both holders receive the notice',
+    );
+    for (const edit of collaborators.descriptionEdits()) {
+      assert.equal(edit.description, notice);
+    }
+    // The commit still happens: the ambiguity notice is a legitimate board change like any other.
+    assert.equal(result.committedBoard, true);
+  });
+
+  it('does not rewrite a holder that already shows the ambiguity notice', () => {
+    const tasks = [
+      holder(),
+      makeTask({ id: 'T-113', status: TASK_STATUS.TO_DO, isGraphHolder: true }),
+      openTask(),
+    ];
+    const notice = ambiguousHolderNotice(['T-112', 'T-113']);
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': notice, 'T-113': 'stale text' },
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.graphHolderAmbiguous, ['T-112', 'T-113']);
+    assert.deepEqual(collaborators.descriptionEdits(), [{ id: 'T-113', description: notice }]);
+  });
+
+  it('a throw writing the notice to one holder does not prevent the other, and the pass still commits', () => {
+    const tasks = [
+      holder(),
+      makeTask({ id: 'T-113', status: TASK_STATUS.TO_DO, isGraphHolder: true }),
+      openTask(),
+    ];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': 'stale text', 'T-113': 'other stale text' },
+      setDescriptionShouldThrow: (id) => id === 'T-112',
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.graphHolderAmbiguous, ['T-112', 'T-113']);
+    assert.deepEqual(collaborators.descriptionEdits().map((edit) => edit.id), ['T-113']);
+    assert.equal(result.graphHolderRefreshError, null, 'a single holder write failure is not a step failure');
+    assert.equal(result.committedBoard, true);
+  });
+
+  it('records the failure and still closes merged tasks, recomputes parents and commits when the write throws', () => {
+    const tasks = [
+      holder(),
+      openTask(),
+      makeTask({ id: 'T-20', status: TASK_STATUS.IN_PROGRESS }),
+      makeTask({ id: 'T-30', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-31', parentId: 'T-30', status: TASK_STATUS.DONE }),
+    ];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': 'stale text' },
+      setDescriptionShouldThrow: (id) => id === 'T-112',
+      isPrMerged: (branch) => branch === 'task/T-20',
+      mergedState: (branch) => (branch === 'task/T-20' ? 'merged' : 'not-merged'),
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.ok(result.graphHolderRefreshError, 'the failure must be recorded on the result');
+    assert.equal(result.graphHolderRefreshed, null);
+    assert.deepEqual(result.movedToDone, ['T-20']);
+    assert.deepEqual(result.recomputedParents, [
+      { id: 'T-30', from: TASK_STATUS.TO_DO, to: TASK_STATUS.IN_PROGRESS },
+    ]);
+    assert.equal(result.committedBoard, true);
+  });
+
+  it('records the failure and still closes merged tasks, recomputes parents and commits when the read throws', () => {
+    const tasks = [
+      holder(),
+      openTask(),
+      makeTask({ id: 'T-20', status: TASK_STATUS.IN_PROGRESS }),
+      makeTask({ id: 'T-30', status: TASK_STATUS.TO_DO }),
+      makeTask({ id: 'T-31', parentId: 'T-30', status: TASK_STATUS.DONE }),
+    ];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks,
+      descriptionsBefore: { 'T-112': 'stale text' },
+      readDescriptionShouldThrow: (id) => id === 'T-112',
+      isPrMerged: (branch) => branch === 'task/T-20',
+      mergedState: (branch) => (branch === 'task/T-20' ? 'merged' : 'not-merged'),
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.ok(result.graphHolderRefreshError, 'the failure must be recorded on the result');
+    assert.equal(result.graphHolderRefreshed, null);
+    assert.equal(collaborators.descriptionEdits().length, 0, 'a read failure must never reach the writer');
+    assert.deepEqual(result.movedToDone, ['T-20']);
+    assert.deepEqual(result.recomputedParents, [
+      { id: 'T-30', from: TASK_STATUS.TO_DO, to: TASK_STATUS.IN_PROGRESS },
+    ]);
+    assert.equal(result.committedBoard, true);
+  });
+});
+
+// ── Step 6: commit pending .backlog/** changes ─────────────────────────────────
+
+describe('runMaintenance — board commit', () => {
+  it('commits pending .backlog changes with a conventional chore(backlog) message summarizing transitions', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.IN_PROGRESS })],
+      isPrMerged: (branch) => branch === 'task/T-3',
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.committedBoard, true);
+    assert.equal(collaborators.boardCommits().length, 1);
+    assert.match(
+      collaborators.boardCommits()[0],
+      /^chore\(backlog\): sync board state \(.*T-3.*\)$/,
+    );
+  });
+
+  it('does not commit when there is nothing pending under .backlog', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [],
+      hasPendingBacklogChanges: false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.committedBoard, false);
+    assert.deepEqual(collaborators.boardCommits(), []);
+  });
+
+  it('still commits with a generic message when changes are pending but nothing transitioned this pass', () => {
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [],
+      hasPendingBacklogChanges: true,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.committedBoard, true);
+    assert.match(collaborators.boardCommits()[0], /^chore\(backlog\): sync board state/);
+  });
+});
+
+// ── recomputeParent, called directly by the close ─────────────────────────────
+
+describe('recomputeParent', () => {
+  /**
+   * A bare `hasCloseAttemptBeenEnqueued`/`markCloseAttemptEnqueued` pair, Set-backed, plus T-68's
+   * two read-only attempt probes — both default to "no data", the ordinary answer every fixture in
+   * THIS describe block needs: it asserts the DERIVED STATUS, never the execution record's own
+   * content (that is `runMaintenance — the «Registro de ejecución» block...`, above).
+   */
+  function fakeCloseAttemptFs(alreadyEnqueued: string[] = []) {
+    const enqueued = new Set(alreadyEnqueued);
+    return {
+      hasCloseAttemptBeenEnqueued: (taskId: string) => enqueued.has(taskId),
+      markCloseAttemptEnqueued: (taskId: string) => enqueued.add(taskId),
+      attemptStreamOutcome: (): string | null => null,
+      attemptReviewVerdict: (): string | null => null,
+    };
+  }
+
+  /**
+   * A `setStatus` recorder (into the caller's own `edits` array, when given one) plus T-68's
+   * `appendNotes`/`readNotes`/`comment` no-ops — a parent this suite derives to `Done` still goes
+   * through `writeExecutionRecordOnce`, and a silent no-op is the right default for a suite that is
+   * not asserting the record's content.
+   */
+  function fakeParentBacklog(edits: Array<[string, string]> = []) {
+    return {
+      setStatus: (id: string, status: string) => edits.push([id, status]),
+      appendNotes: (): void => {},
+      readNotes: (): string | null => null,
+      comment: (): void => {},
+    };
+  }
+
+  const parentAndChild = (
+    childStatus: Task['status'],
+    parentStatus: Task['status'] = TASK_STATUS.IN_PROGRESS,
+  ) => ({
+    'T-10': makeTask({ id: 'T-10', status: parentStatus }),
+    'T-11': makeTask({ id: 'T-11', status: childStatus, parentId: 'T-10' }),
+  });
+
+  it('writes the derived status when it differs from what the board says', () => {
+    const edits: Array<[string, string]> = [];
+    const result = recomputeParent({
+      parentId: 'T-10',
+      tasksById: parentAndChild(TASK_STATUS.BLOCKED),
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+      backlog: fakeParentBacklog(edits),
+      fs: fakeCloseAttemptFs(),
+    });
+
+    assert.deepEqual(result, {
+      id: 'T-10',
+      from: TASK_STATUS.IN_PROGRESS,
+      to: TASK_STATUS.BLOCKED,
+    });
+    assert.deepEqual(edits, [['T-10', TASK_STATUS.BLOCKED]]);
+  });
+
+  it('writes nothing when the derived status already matches (no churn on the board)', () => {
+    const edits: Array<[string, string]> = [];
+    const result = recomputeParent({
+      parentId: 'T-10',
+      tasksById: parentAndChild(TASK_STATUS.IN_PROGRESS),
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+      backlog: fakeParentBacklog(edits),
+      fs: fakeCloseAttemptFs(),
+    });
+
+    assert.equal(result, null);
+    assert.deepEqual(edits, []);
+  });
+
+  it('closes the parent only when its children are Done AND its own PR merged', () => {
+    const tasksById = parentAndChild(TASK_STATUS.DONE);
+    const unmerged = recomputeParent({
+      parentId: 'T-10',
+      tasksById,
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+      backlog: fakeParentBacklog(),
+      fs: fakeCloseAttemptFs(),
+    });
+    const merged = recomputeParent({
+      parentId: 'T-10',
+      tasksById,
+      gh: { isPrMerged: () => true, mergedState: () => 'merged' },
+      backlog: fakeParentBacklog(),
+      fs: fakeCloseAttemptFs(),
+    });
+
+    assert.equal(unmerged, null, 'children Done but the parent PR unmerged stays In Progress');
+    assert.deepEqual(merged, { id: 'T-10', from: TASK_STATUS.IN_PROGRESS, to: TASK_STATUS.DONE });
+  });
+
+  // ── T-68 fix 3: a parent reaching Done through THIS derivation gets the block too (§12: "every
+  // task") — `runMaintenance`'s step 3 is not the only place `Done` is written. ──────────────────
+
+  it('a parent that reaches Done through this derivation gets its OWN «Registro de ejecución» block', () => {
+    const tasksById = parentAndChild(TASK_STATUS.DONE);
+    const appended: Array<{ id: string; notes: string }> = [];
+    const edits: Array<[string, string]> = [];
+    const result = recomputeParent({
+      parentId: 'T-10',
+      tasksById,
+      gh: { isPrMerged: () => true, mergedState: () => 'merged' },
+      backlog: {
+        setStatus: (id, status) => edits.push([id, status]),
+        appendNotes: (id, notes) => appended.push({ id, notes }),
+        readNotes: () => null,
+        comment: () => {},
+      },
+      fs: fakeCloseAttemptFs(),
+    });
+
+    assert.deepEqual(result, { id: 'T-10', from: TASK_STATUS.IN_PROGRESS, to: TASK_STATUS.DONE });
+    assert.equal(appended.length, 1, 'the parent gets its own record, exactly once');
+    assert.equal(appended[0]?.id, 'T-10');
+    assert.match(appended[0]?.notes ?? '', /^## Registro de ejecución/);
+    // Written BEFORE `setStatus` — the same ordering fix 1 established for a leaf task, and for the
+    // identical reason: a `Done` parent never re-enters this derivation with a status to correct.
+    assert.deepEqual(edits, [['T-10', TASK_STATUS.DONE]]);
+  });
+
+  it('appendNotes throws: the parent still moves to Done, with exactly one comment', () => {
+    const tasksById = parentAndChild(TASK_STATUS.DONE);
+    const edits: Array<[string, string]> = [];
+    const appended: Array<{ id: string; notes: string }> = [];
+    const comments: Array<{ id: string; comment: string }> = [];
+    const result = recomputeParent({
+      parentId: 'T-10',
+      tasksById,
+      gh: { isPrMerged: () => true, mergedState: () => 'merged' },
+      backlog: {
+        setStatus: (id, status) => edits.push([id, status]),
+        appendNotes: (id, notes) => {
+          appended.push({ id, notes });
+          throw new Error('simulated appendNotes failure');
+        },
+        readNotes: () => null,
+        comment: (id, comment) => comments.push({ id, comment }),
+      },
+      fs: fakeCloseAttemptFs(),
+    });
+
+    assert.deepEqual(
+      result,
+      { id: 'T-10', from: TASK_STATUS.IN_PROGRESS, to: TASK_STATUS.DONE },
+      'a failed record write must never hold the parent Done transition hostage',
+    );
+    assert.deepEqual(edits, [['T-10', TASK_STATUS.DONE]]);
+    assert.equal(comments.length, 1, 'exactly one comment records the gap');
+    assert.match(comments[0]?.comment ?? '', /Registro de ejecución/);
+  });
+
+  it('comment ALSO throws: recomputeParent itself never throws, and the parent still moves to Done', () => {
+    const tasksById = parentAndChild(TASK_STATUS.DONE);
+    const edits: Array<[string, string]> = [];
+    let result: ReturnType<typeof recomputeParent> | undefined;
+    assert.doesNotThrow(() => {
+      result = recomputeParent({
+        parentId: 'T-10',
+        tasksById,
+        gh: { isPrMerged: () => true, mergedState: () => 'merged' },
+        backlog: {
+          setStatus: (id, status) => edits.push([id, status]),
+          appendNotes: () => {
+            throw new Error('simulated appendNotes failure');
+          },
+          readNotes: () => null,
+          comment: () => {
+            throw new Error('simulated comment failure too');
+          },
+        },
+        fs: fakeCloseAttemptFs(),
+      });
+    });
+
+    assert.deepEqual(result, { id: 'T-10', from: TASK_STATUS.IN_PROGRESS, to: TASK_STATUS.DONE });
+    assert.deepEqual(edits, [['T-10', TASK_STATUS.DONE]]);
+  });
+
+  // F1 [BLOCKER] (2026-09-08): `isPrMerged` collapses "confirmed not merged" and "gh outage" into
+  // the SAME `false` — see `MaintenanceGh.mergedState`'s own JSDoc for the identical trap step 3b
+  // was built to avoid. Before this fix, an all-Done parent whose own merge state is genuinely
+  // UNKNOWN (a `gh` outage) read that `false` as "confirmed not merged", derived `In Progress` (or,
+  // for a Complex parent, `Queued` — burning the one-shot close-attempt marker), and wrote it
+  // because the derived status differs from the board's actual `Done`.
+  it('derives nothing when a gh outage hides whether the all-Done parent is really merged (F1)', () => {
+    const edits: Array<[string, string]> = [];
+    const result = recomputeParent({
+      parentId: 'T-10',
+      tasksById: parentAndChild(TASK_STATUS.DONE, TASK_STATUS.DONE),
+      gh: { isPrMerged: () => false, mergedState: () => 'unknown' },
+      backlog: fakeParentBacklog(edits),
+      fs: fakeCloseAttemptFs(),
+    });
+
+    assert.equal(result, null, 'a gh outage must never be read as a confirmed not-merged answer');
+    assert.deepEqual(edits, [], 'the board Done status must survive an unanswerable gh outage');
+  });
+
+  it('is a no-op for a task with no children — a leaf has nothing to derive from', () => {
+    const result = recomputeParent({
+      parentId: 'T-10',
+      tasksById: { 'T-10': makeTask({ id: 'T-10', status: TASK_STATUS.IN_PROGRESS }) },
+      gh: { isPrMerged: () => true, mergedState: () => 'merged' },
+      backlog: fakeParentBacklog(),
+      fs: fakeCloseAttemptFs(),
+    });
+    assert.equal(result, null);
+  });
+
+  it('is a no-op for a parent id absent from the board snapshot', () => {
+    const result = recomputeParent({
+      parentId: 'T-99',
+      tasksById: parentAndChild(TASK_STATUS.BLOCKED),
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+      backlog: fakeParentBacklog(),
+      fs: fakeCloseAttemptFs(),
+    });
+    assert.equal(result, null);
+  });
+
+  // ── T-8, last point: the Complex parent's one automated close attempt ──────
+  // T-8 defect 3, HIGH, 2026-09-08: rewritten from `attempts > 0` to the durable enqueue-time
+  // marker (`hasCloseAttemptBeenEnqueued`/`markCloseAttemptEnqueued`) — see `MaintenanceFs
+  // .hasCloseAttemptBeenEnqueued`'s own JSDoc for why `attempts` (an `intento-N` directory count
+  // `beginAttempt` creates LATE) could stay `0` forever while the SAME "all Done, unmerged" state
+  // kept re-deriving `Queued` on every later pass.
+  describe('a Complex parent, all children Done', () => {
+    const complexParentAndChild = (parentStatus: Task['status']) => ({
+      'T-10': makeTask({ id: 'T-10', status: parentStatus, tier: TIER.COMPLEX }),
+      'T-11': makeTask({ id: 'T-11', status: TASK_STATUS.DONE, parentId: 'T-10' }),
+    });
+
+    it('enqueues it for a close attempt the first time, and MARKS it enqueued durably', () => {
+      const edits: Array<[string, string]> = [];
+      const fs = fakeCloseAttemptFs();
+      const result = recomputeParent({
+        parentId: 'T-10',
+        tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
+        gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+        backlog: fakeParentBacklog(edits),
+        fs,
+      });
+
+      assert.deepEqual(result, {
+        id: 'T-10',
+        from: TASK_STATUS.IN_PROGRESS,
+        to: TASK_STATUS.QUEUED,
+      });
+      assert.deepEqual(edits, [['T-10', TASK_STATUS.QUEUED]]);
+      assert.equal(
+        fs.hasCloseAttemptBeenEnqueued('T-10'),
+        true,
+        'rule 4 firing must mark the parent enqueued the instant it fires, not wait for a worker to start',
+      );
+    });
+
+    it('does NOT re-enqueue a close attempt already marked enqueued (a live retry running)', () => {
+      const edits: Array<[string, string]> = [];
+      const result = recomputeParent({
+        parentId: 'T-10',
+        tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
+        gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+        backlog: fakeParentBacklog(edits),
+        fs: fakeCloseAttemptFs(['T-10']),
+      });
+
+      assert.equal(result, null, 'a live close attempt must not be clobbered back to Queued');
+      assert.deepEqual(edits, []);
+    });
+
+    it('does NOT clear a Blocked close attempt back to Queued (that is section 10, a human decision)', () => {
+      const edits: Array<[string, string]> = [];
+      const result = recomputeParent({
+        parentId: 'T-10',
+        tasksById: complexParentAndChild(TASK_STATUS.BLOCKED),
+        gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+        backlog: fakeParentBacklog(edits),
+        fs: fakeCloseAttemptFs(['T-10']),
+      });
+
+      assert.equal(result, null, 'a Blocked close attempt report must survive an untouched pass');
+      assert.deepEqual(edits, []);
+    });
+
+    it('still reaches Done once the close attempt PR merges', () => {
+      const result = recomputeParent({
+        parentId: 'T-10',
+        tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
+        gh: { isPrMerged: () => true, mergedState: () => 'merged' },
+        backlog: fakeParentBacklog(),
+        fs: fakeCloseAttemptFs(['T-10']),
+      });
+
+      assert.deepEqual(result, {
+        id: 'T-10',
+        from: TASK_STATUS.IN_PROGRESS,
+        to: TASK_STATUS.DONE,
+      });
+    });
+
+    // The reproducing test for T-8 defect 3 itself: a guard blocks the dispatch BEFORE any worker
+    // starts (e.g. no declared `Test command:`), so `attempts` NEVER moves off `0` — exactly the
+    // condition that used to fool `own.attempts > 0` into re-deriving `Queued` forever.
+    it('does not re-derive Queued on the next pass when a guard blocked the dispatch before any attempt directory existed', () => {
+      const fs = fakeCloseAttemptFs();
+      const child = makeTask({ id: 'T-11', status: TASK_STATUS.DONE, parentId: 'T-10' });
+      const parent = (status: Task['status']) =>
+        makeTask({ id: 'T-10', status, tier: TIER.COMPLEX, attempts: 0 });
+
+      const firstPass = recomputeParent({
+        parentId: 'T-10',
+        tasksById: { 'T-10': parent(TASK_STATUS.IN_PROGRESS), 'T-11': child },
+        gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+        backlog: fakeParentBacklog(),
+        fs,
+      });
+      assert.deepEqual(firstPass, {
+        id: 'T-10',
+        from: TASK_STATUS.IN_PROGRESS,
+        to: TASK_STATUS.QUEUED,
+      });
+
+      // Guard 1 blocks it (no declared "Test command:") before `beginAttempt` ever runs — `attempts`
+      // stays 0, exactly as it does in the real dispatch pipeline for this path.
+      const secondPass = recomputeParent({
+        parentId: 'T-10',
+        tasksById: { 'T-10': parent(TASK_STATUS.BLOCKED), 'T-11': child },
+        gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+        backlog: fakeParentBacklog(),
+        fs,
+      });
+      assert.equal(
+        secondPass,
+        null,
+        'the durable enqueue marker set on the first pass must survive a dispatch that never created an attempt directory',
+      );
+    });
+
+    // F1 [BLOCKER] (2026-09-08): the worse half of the same gh-outage bug — for a Complex parent
+    // this path is rule 4 (`Queued`), which also burns the one-shot `markCloseAttemptEnqueued`
+    // marker. A `gh` outage must never be able to consume that marker: it must derive nothing at
+    // all, exactly like the non-Complex case above.
+    it('does not enqueue a close attempt, and does not burn the one-shot marker, on a gh outage (F1)', () => {
+      const edits: Array<[string, string]> = [];
+      const fs = fakeCloseAttemptFs();
+      const result = recomputeParent({
+        parentId: 'T-10',
+        tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
+        gh: { isPrMerged: () => false, mergedState: () => 'unknown' },
+        backlog: fakeParentBacklog(edits),
+        fs,
+      });
+
+      assert.equal(result, null, 'an unanswerable gh outage must not enqueue a close attempt');
+      assert.deepEqual(edits, []);
+      assert.equal(
+        fs.hasCloseAttemptBeenEnqueued('T-10'),
+        false,
+        'the irreversible one-shot marker must survive an outage untouched — a merged parent must still get its automated close later',
+      );
+    });
+
+    // F2 [MEDIUM] (2026-09-08): the marker must be written the instant rule 4's derivation fires,
+    // not only when that derivation also CHANGES the board. A person can set a Complex parent to
+    // `Queued` by hand (the release flow, section 10) while children are still running; once the
+    // last one finishes, rule 4 derives `Queued` again — same as the board already reads — and the
+    // early "nothing changed" return must not skip the marker, or a later `Blocked` close-attempt
+    // report gets silently re-queued on the NEXT pass (the marker would still read `false`).
+    it('marks the close attempt enqueued even when the board already reads Queued (F2)', () => {
+      const edits: Array<[string, string]> = [];
+      const fs = fakeCloseAttemptFs();
+      const result = recomputeParent({
+        parentId: 'T-10',
+        tasksById: complexParentAndChild(TASK_STATUS.QUEUED),
+        gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+        backlog: fakeParentBacklog(edits),
+        fs,
+      });
+
+      assert.equal(result, null, 'no board write: the derived status already matches Queued');
+      assert.deepEqual(edits, []);
+      assert.equal(
+        fs.hasCloseAttemptBeenEnqueued('T-10'),
+        true,
+        'rule 4 fired even though the status did not change, so the marker must still be recorded — otherwise a later Blocked close-attempt report gets clobbered back to Queued on the next pass',
+      );
+    });
+  });
+});
+
+// ── F8: sweep semantics, recovery holds, and the board commit header ──────────
+
+describe('runMaintenance — a dead worker never loses its work', () => {
+  it('saves the branch BEFORE releasing the slot, then blocks the task saying the work survived', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999, workerPid: 4242 })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    const saveIndex = collaborators.calls.indexOf('saveWipAndPush(task/T-1)');
+    const writeIndex = collaborators.calls.indexOf('updateSlots');
+    assert.ok(
+      saveIndex > -1 && saveIndex < writeIndex,
+      'the WIP save must precede the slot write-back',
+    );
+    assert.deepEqual(result.releasedLocks, ['T-1']);
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, null);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-1', status: TASK_STATUS.BLOCKED }]);
+  });
+
+  it('kills a HUNG worker (expired heartbeat, live pid) before treating its lock as dead', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 111)],
+      locks: [
+        makeLock({
+          taskId: 'T-1',
+          pid: 111,
+          workerPid: 4242,
+          heartbeatAt: new Date(NOW - TTL_MS - 1_000).toISOString(),
+        }),
+      ],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => true,
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(collaborators.calls.slice(0, 2), [
+      'killProcess(4242)',
+      'saveWipAndPush(task/T-1)',
+    ]);
+  });
+
+  it('holds the slot instead of releasing it when the rescue push fails', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999 })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+      saveWipAndPush: () => ({ pushSucceeded: false }),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.heldForRecovery, ['T-1']);
+    const slot = collaborators.slotsAfter().slots[0];
+    assert.equal(slot.taskId, 'T-1', 'the slot still holds the only copy of the work');
+    assert.equal(slot.heldForRecovery, true);
+    assert.deepEqual(result.releasedOrphanSlots, [], 'the orphan sweep must not release it either');
+  });
+
+  // Defect 8 (2026-09-08): the dead-worker rescue is the SECOND pusher T-8 point 4's gate never
+  // reached — it could push a dead worker's WIP onto a branch whose PR already merged, and T-8
+  // point 5 now deletes that branch on `Done`, destroying the commit instead of merely stranding it.
+  it('never pushes a dead worker WIP onto a branch that already reads confirmed merged', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999, workerPid: 4242, branch: 'task/T-1' })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+      mergedState: (branch) => (branch === 'task/T-1' ? 'merged' : 'unknown'),
+      saveWipAndPush: () => assert.fail('a confirmed-merged branch must never be pushed to'),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.pushRefusedMergedBranches, ['T-1']);
+    // Still held for recovery — the WIP is unpushed and the slot is the only copy — but the
+    // comment must say WHY, distinctly from the generic dead-worker one (no push was even tried).
+    assert.deepEqual(result.heldForRecovery, ['T-1']);
+    const comment = collaborators.comments().find((entry) => entry.id === 'T-1')?.comment ?? '';
+    assert.match(comment, /ya consta como mergeada/);
+    assert.match(comment, /task\/T-1/);
+    assert.doesNotMatch(
+      comment,
+      /trabajo guardado/,
+      'must not reuse the generic push-attempt wording',
+    );
+  });
+
+  // T-20 point 4 (2026-09-11, hardened): `mergedState` is now REQUIRED on `MaintenanceGh`, so a
+  // caller with no way to answer this question no longer type-checks — the fail-closed behaviour
+  // moved from a runtime guard here to the compiler. What stays a runtime concern is the legitimate
+  // third answer a WIRED collaborator can still give: `unknown`, from a real `gh` outage, which
+  // must keep pushing through (rescue reasoning unchanged) rather than being read as a confirmed
+  // merge.
+  it('still saves a dead worker WIP when mergedState is unknown — refusing risks the only copy', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999, workerPid: 4242, branch: 'task/T-1' })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+      mergedState: () => 'unknown',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.pushRefusedMergedBranches, []);
+    assert.ok(collaborators.calls.includes('saveWipAndPush(task/T-1)'));
+  });
+});
+
+describe('runMaintenance — pending push retry', () => {
+  it('retries a held slot, releases it on success, and says so on the task', () => {
+    const held: SlotInfo = {
+      ...busySlot('dispatch-a', 'local', 'T-1', 999),
+      heldForRecovery: true,
+    };
+    const collaborators = makeCollaborators({
+      slots: [held],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recoveredPushes, ['T-1']);
+    const slot = collaborators.slotsAfter().slots[0];
+    assert.equal(slot.taskId, null);
+    assert.equal(slot.heldForRecovery, false);
+    assert.deepEqual(collaborators.statusEdits(), [{ id: 'T-1', status: TASK_STATUS.BLOCKED }]);
+  });
+
+  // G9: a person may already have released the task while the push was pending. Re-writing
+  // `Blocked` then drags it back out of the queue it was deliberately put into.
+  it('leaves a re-queued task in Queued, commenting the recovery instead of blocking it again', () => {
+    const held: SlotInfo = {
+      ...busySlot('dispatch-a', 'local', 'T-1', 999),
+      heldForRecovery: true,
+    };
+    const collaborators = makeCollaborators({
+      slots: [held],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.QUEUED })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recoveredPushes, ['T-1']);
+    assert.deepEqual(
+      collaborators.statusEdits(),
+      [],
+      'a Queued task must not be moved by a push retry',
+    );
+    assert.equal(collaborators.comments().length, 1);
+    assert.equal(collaborators.comments()[0].id, 'T-1');
+    assert.match(collaborators.comments()[0].comment, /push recuperado/);
+    const slot = collaborators.slotsAfter().slots[0];
+    assert.equal(slot.taskId, null);
+    assert.equal(slot.heldForRecovery, false);
+  });
+
+  it('keeps holding the slot when the retry fails again', () => {
+    const held: SlotInfo = {
+      ...busySlot('dispatch-a', 'local', 'T-1', 999),
+      heldForRecovery: true,
+    };
+    const collaborators = makeCollaborators({
+      slots: [held],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+      saveWipAndPush: () => ({ pushSucceeded: false }),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recoveredPushes, []);
+    assert.equal(collaborators.slotsAfter().slots[0].heldForRecovery, true);
+  });
+});
+
+// G2: the pass drops the single-flight lock as soon as a slot is taken, so a SECOND pass writes
+// `slots.json` while this one is still sweeping. A whole-registry write built on the snapshot read
+// at the start silently reverted that write.
+describe('runMaintenance — a concurrent per-slot change made mid-pass', () => {
+  it('keeps a slot another pass acquired while this sweep was running', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999), freeSlot('dispatch-b')],
+      locks: [makeLock({ taskId: 'T-1', pid: 999 })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+    });
+
+    // Another pass takes dispatch-b after this pass has already read the registry.
+    collaborators.ctx.gh = {
+      isPrMerged: () => {
+        collaborators.mutateRegistryConcurrently((slots) =>
+          slots.map((slot) =>
+            slot.name === 'dispatch-b'
+              ? { ...slot, lane: LANE.LOCAL, taskId: 'T-2', pid: 7 }
+              : slot,
+          ),
+        );
+        return false;
+      },
+      // Wired, answering "not merged" — this test is about the registry race, not the merged-branch
+      // gate, so it must NOT trip T-20 point 4's fail-closed refusal for an unwired collaborator.
+      mergedState: () => 'not-merged',
+    };
+
+    runMaintenance(collaborators.ctx);
+
+    const after = collaborators.slotsAfter().slots;
+    assert.equal(after[0].taskId, null, 'this pass own release still lands');
+    assert.equal(after[1].taskId, 'T-2', 'the other pass acquisition must survive this write');
+  });
+});
+
+describe('runMaintenance — the post-maintenance registry is returned', () => {
+  it('hands back the registry AFTER its releases, so the same pass can use the freed slot', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1' })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.slots.slots[0].taskId, null);
+  });
+});
+
+describe('runMaintenance — manual cancellation kills the WORKER', () => {
+  it('kills the worker pid, not the reconciler pid that owns the lock', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-4', 444)],
+      locks: [makeLock({ taskId: 'T-4', pid: 444, workerPid: 5150 })],
+      tasks: [makeTask({ id: 'T-4', status: TASK_STATUS.BLOCKED })],
+      isPidAlive: () => true,
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    assert.ok(collaborators.calls.includes('killProcess(5150)'));
+    assert.ok(!collaborators.calls.includes('killProcess(444)'));
+  });
+});
+
+describe('buildBoardCommitMessage', () => {
+  it('names the single transition inline', () => {
+    assert.equal(
+      buildBoardCommitMessage(['T-12 -> Done']),
+      'chore(backlog): sync board state (T-12 -> Done)',
+    );
+  });
+
+  it('counts several transitions in the header and enumerates them in the body', () => {
+    const message = buildBoardCommitMessage([
+      'T-1 -> Done',
+      'T-2 -> Blocked',
+      'T-3 -> Done',
+      'T-4 -> Done',
+    ]);
+    const [header, blank, ...body] = message.split('\n');
+    assert.equal(header, 'chore(backlog): sync board state (4 transitions)');
+    assert.equal(blank, '');
+    assert.deepEqual(body, ['T-1 -> Done', 'T-2 -> Blocked', 'T-3 -> Done', 'T-4 -> Done']);
+    assert.ok(header.length <= 100);
+    assert.ok(body.every((line) => line.length < 100));
+  });
+
+  it('falls back to housekeeping when nothing moved', () => {
+    assert.equal(buildBoardCommitMessage([]), 'chore(backlog): sync board state (housekeeping)');
+  });
+});
+
+describe('runMaintenance — a failing board commit', () => {
+  it('does not abort the pass: the sweep it already did still stands', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1' })],
+      hasPendingBacklogChanges: true,
+      commitBacklogChanges: () => {
+        throw new Error('commit-msg hook rejected the message');
+      },
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.equal(result.committedBoard, false);
+    assert.deepEqual(result.releasedOrphanSlots, ['T-1']);
+  });
+});
+
+describe('runMaintenance — gh polling', () => {
+  it('asks gh about each branch at most once per pass', () => {
+    const asked: string[] = [];
+    const collaborators = makeCollaborators({
+      slots: [],
+      locks: [],
+      tasks: [
+        makeTask({ id: 'T-10', status: TASK_STATUS.IN_PROGRESS }),
+        makeTask({ id: 'T-10.1', status: TASK_STATUS.IN_PROGRESS, parentId: 'T-10' }),
+        makeTask({ id: 'T-10.2', status: TASK_STATUS.IN_PROGRESS, parentId: 'T-10' }),
+      ],
+      isPrMerged: (branch) => {
+        asked.push(branch);
+        return false;
+      },
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(
+      asked,
+      [...new Set(asked)],
+      `gh was polled twice for the same branch: ${asked.join(', ')}`,
+    );
+  });
+});
+
+// ── H1/H4/H7: release means the same thing on every path, and recovery is bounded ─────────────
+
+describe('runMaintenance — every release detaches the slot', () => {
+  const detachOf = (name: string): string => `/slots/${name}`;
+
+  it('detaches the slot it releases after sweeping a dead lock', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-a', 'local', 'T-1', 999)],
+      locks: [makeLock({ taskId: 'T-1', pid: 999 })],
+      tasks: [makeTask({ id: 'T-1' })],
+      isPidAlive: () => false,
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(collaborators.detachedSlots(), [detachOf('dispatch-a')]);
+  });
+
+  it('detaches the slot it releases as an orphan', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-b', 'local', 'T-2', 999)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-2' })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.releasedOrphanSlots, ['T-2']);
+    assert.deepEqual(collaborators.detachedSlots(), [detachOf('dispatch-b')]);
+  });
+
+  it('detaches the slot it releases on a manual cancellation', () => {
+    const collaborators = makeCollaborators({
+      slots: [busySlot('dispatch-c', 'local', 'T-3', 111)],
+      locks: [makeLock({ taskId: 'T-3', slot: 'dispatch-c' })],
+      tasks: [makeTask({ id: 'T-3', status: TASK_STATUS.BLOCKED })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.cancelledWorkers, ['T-3']);
+    assert.deepEqual(collaborators.detachedSlots(), [detachOf('dispatch-c')]);
+  });
+
+  it('detaches the slot it releases after a recovered push', () => {
+    const held: SlotInfo = {
+      ...busySlot('dispatch-a', 'local', 'T-4', 999),
+      heldForRecovery: true,
+    };
+    const collaborators = makeCollaborators({
+      slots: [held],
+      locks: [],
+      tasks: [makeTask({ id: 'T-4', status: TASK_STATUS.BLOCKED })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recoveredPushes, ['T-4']);
+    assert.deepEqual(collaborators.detachedSlots(), [detachOf('dispatch-a')]);
+  });
+
+  // H4: the sweep used to carry its own copy of the release transform. Comparing against the real
+  // one is what keeps "released" from meaning two different things on two paths.
+  it('releases exactly what slots.ts releaseSlot releases, field for field', () => {
+    const busy = busySlot('dispatch-a', 'local', 'T-5', 999);
+    const collaborators = makeCollaborators({
+      slots: [busy],
+      locks: [],
+      tasks: [makeTask({ id: 'T-5' })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.slots, releaseSlot('T-5', { slots: [busy] }));
+  });
+});
+
+describe('runMaintenance — the push recovery retry is bounded', () => {
+  const heldSlot = (attempts: number | undefined): SlotInfo => ({
+    ...busySlot('dispatch-a', 'local', 'T-1', 999),
+    heldForRecovery: true,
+    ...(attempts === undefined ? {} : { recoveryAttempts: attempts }),
+  });
+
+  it('counts a failed retry on the slot instead of retrying forever', () => {
+    const collaborators = makeCollaborators({
+      slots: [heldSlot(undefined)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+      saveWipAndPush: () => ({ pushSucceeded: false }),
+    });
+
+    runMaintenance(collaborators.ctx);
+
+    assert.equal(collaborators.slotsAfter().slots[0].recoveryAttempts, 1);
+    assert.equal(collaborators.slotsAfter().slots[0].heldForRecovery, true);
+  });
+
+  it('gives up at the cap: notifies, says so on the task, and keeps the slot for a person', () => {
+    const collaborators = makeCollaborators({
+      slots: [heldSlot(MAX_RECOVERY_ATTEMPTS - 1)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+      saveWipAndPush: () => ({ pushSucceeded: false }),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.exhaustedRecoveries, ['T-1']);
+    assert.equal(collaborators.notifications().length, 1);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /recuperaci\u00f3n del push agotada/);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /task\/T-1/);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /\/slots\/dispatch-a/);
+    // N5: "rescue it by hand" named no hand to use. The slot stays out of the pool until somebody
+    // clears the hold, so the comment must name the command that does it and the file behind it.
+    assert.match(collaborators.comments()[0]?.comment ?? '', /--release-slot dispatch-a/);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /heldForRecovery/);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /recoveryAttempts/);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /slots\.json/);
+    assert.equal(
+      collaborators.slotsAfter().slots[0].heldForRecovery,
+      true,
+      'the work is still only here',
+    );
+    assert.equal(collaborators.slotsAfter().slots[0].taskId, 'T-1');
+  });
+
+  it('stops retrying once the cap is reached — no further push, no repeated comment', () => {
+    const collaborators = makeCollaborators({
+      slots: [heldSlot(MAX_RECOVERY_ATTEMPTS)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+      saveWipAndPush: () => assert.fail('an exhausted recovery must not push again'),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.exhaustedRecoveries, []);
+    assert.deepEqual(collaborators.comments(), []);
+    assert.deepEqual(collaborators.notifications(), []);
+  });
+
+  it('clears the counter when the push finally lands, so a later hold starts from zero', () => {
+    const collaborators = makeCollaborators({
+      slots: [heldSlot(2)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.recoveredPushes, ['T-1']);
+    assert.equal(collaborators.slotsAfter().slots[0].recoveryAttempts, 0);
+  });
+
+  // Defect 8 (2026-09-08): T-8 point 4 stops the CLOSE from pushing to an already-merged branch
+  // (`checkBranchNotMerged`), but the recovery retry never consulted it — it could still push a
+  // held WIP commit onto a branch whose PR already merged, and T-8 point 5 now deletes that
+  // branch once the task reaches `Done`, destroying the commit rather than merely stranding it.
+  it('never retries the push once the branch reads confirmed merged, and stops future retries', () => {
+    const collaborators = makeCollaborators({
+      slots: [heldSlot(undefined)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+      mergedState: (branch) => (branch === 'task/T-1' ? 'merged' : 'unknown'),
+      saveWipAndPush: () => assert.fail('a confirmed-merged branch must never be pushed to'),
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.pushRefusedMergedBranches, ['T-1']);
+    assert.deepEqual(result.recoveredPushes, []);
+    // Marked exhausted immediately, the same cap the notify-once-and-stop path uses below — a
+    // merge does not un-merge on the next pass, so retrying it again would only repeat the refusal.
+    assert.equal(collaborators.slotsAfter().slots[0].recoveryAttempts, MAX_RECOVERY_ATTEMPTS);
+    assert.equal(collaborators.slotsAfter().slots[0].heldForRecovery, true);
+    assert.equal(collaborators.notifications().length, 1);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /ya consta como mergeada/);
+    assert.match(collaborators.comments()[0]?.comment ?? '', /task\/T-1/);
+  });
+
+  // `unknown` (a `gh` outage) must not be read as "safe to push" EITHER — but for a rescue path,
+  // the safe DECISION under genuine uncertainty is still to push: refusing risks losing the only
+  // unpushed copy of the work, while pushing under uncertainty only risks a few commits landing on
+  // a branch that might already be merged (recoverable — they still exist on the remote).
+  it('still retries the push when mergedState is unknown — refusing risks the only unpushed copy', () => {
+    const collaborators = makeCollaborators({
+      slots: [heldSlot(undefined)],
+      locks: [],
+      tasks: [makeTask({ id: 'T-1', status: TASK_STATUS.BLOCKED })],
+      mergedState: () => 'unknown',
+    });
+
+    const result = runMaintenance(collaborators.ctx);
+
+    assert.deepEqual(result.pushRefusedMergedBranches, []);
+    assert.deepEqual(result.recoveredPushes, ['T-1']);
+    assert.ok(collaborators.calls.includes('saveWipAndPush(task/T-1)'));
+  });
+});