@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -13,6 +13,7 @@
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
+import { ambiguousHolderNotice, renderHolderDescription } from './graph.js';
 import {
   buildBoardCommitMessage,
   MAX_RECOVERY_ATTEMPTS,
@@ -89,6 +90,14 @@ interface FakeCollaborators {
   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 }>;
@@ -110,6 +119,8 @@ function makeCollaborators(input: {
   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;
@@ -126,10 +137,30 @@ function makeCollaborators(input: {
   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 }> = [];
@@ -168,11 +199,17 @@ function makeCollaborators(input: {
         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),
-      mergedState: input.mergedState,
+      // 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) => {
@@ -187,9 +224,40 @@ function makeCollaborators(input: {
         }
       },
       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,
@@ -238,6 +306,10 @@ function makeCollaborators(input: {
     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,
@@ -391,6 +463,231 @@ describe('runMaintenance — merged PR moves a task to Done', () => {
   });
 });
 
+// ── 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', () => {
@@ -594,27 +891,6 @@ describe('runMaintenance — branch cleanup on Done', () => {
     ]);
   });
 
-  // T-15: a subtask's base is the parent's REAL branch when it declared one — an interactive
-  // session's parent lives on `fix/…`, never on `task/<id>`.
-  it("compares a subtask against its parent's DECLARED branch when it named one", () => {
-    const collaborators = makeCollaborators({
-      slots: [],
-      locks: [],
-      tasks: [
-        makeTask({ id: 'T-10', declaredBranch: 'fix/parent-branch-resolution' }),
-        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/fix/parent-branch-resolution' },
-    ]);
-  });
-
   // 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({
@@ -701,6 +977,7 @@ describe('runMaintenance — hand-written Done reverted when its PR is not merge
       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);
@@ -865,6 +1142,51 @@ describe('runMaintenance — orphan In Progress detection', () => {
 
     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 ─────────────
@@ -1053,6 +1375,7 @@ describe('runMaintenance — parent recomputation', () => {
         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);
@@ -1096,6 +1419,256 @@ describe('runMaintenance — parent recomputation', () => {
   });
 });
 
+// ── 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', () => {
@@ -1150,12 +1723,34 @@ describe('runMaintenance — board commit', () => {
 // ── recomputeParent, called directly by the close ─────────────────────────────
 
 describe('recomputeParent', () => {
-  /** A bare `hasCloseAttemptBeenEnqueued`/`markCloseAttemptEnqueued` pair, Set-backed. */
+  /**
+   * 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 => {},
     };
   }
 
@@ -1172,8 +1767,8 @@ describe('recomputeParent', () => {
     const result = recomputeParent({
       parentId: 'T-10',
       tasksById: parentAndChild(TASK_STATUS.BLOCKED),
-      gh: { isPrMerged: () => false },
-      backlog: { setStatus: (id, status) => edits.push([id, status]) },
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+      backlog: fakeParentBacklog(edits),
       fs: fakeCloseAttemptFs(),
     });
 
@@ -1190,8 +1785,8 @@ describe('recomputeParent', () => {
     const result = recomputeParent({
       parentId: 'T-10',
       tasksById: parentAndChild(TASK_STATUS.IN_PROGRESS),
-      gh: { isPrMerged: () => false },
-      backlog: { setStatus: (id, status) => edits.push([id, status]) },
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+      backlog: fakeParentBacklog(edits),
       fs: fakeCloseAttemptFs(),
     });
 
@@ -1205,14 +1800,14 @@ describe('recomputeParent', () => {
       parentId: 'T-10',
       tasksById,
       gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
-      backlog: { setStatus: () => {} },
+      backlog: fakeParentBacklog(),
       fs: fakeCloseAttemptFs(),
     });
     const merged = recomputeParent({
       parentId: 'T-10',
       tasksById,
       gh: { isPrMerged: () => true, mergedState: () => 'merged' },
-      backlog: { setStatus: () => {} },
+      backlog: fakeParentBacklog(),
       fs: fakeCloseAttemptFs(),
     });
 
@@ -1220,6 +1815,93 @@ describe('recomputeParent', () => {
     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
@@ -1232,7 +1914,7 @@ describe('recomputeParent', () => {
       parentId: 'T-10',
       tasksById: parentAndChild(TASK_STATUS.DONE, TASK_STATUS.DONE),
       gh: { isPrMerged: () => false, mergedState: () => 'unknown' },
-      backlog: { setStatus: (id, status) => edits.push([id, status]) },
+      backlog: fakeParentBacklog(edits),
       fs: fakeCloseAttemptFs(),
     });
 
@@ -1240,26 +1922,12 @@ describe('recomputeParent', () => {
     assert.deepEqual(edits, [], 'the board Done status must survive an unanswerable gh outage');
   });
 
-  it('an unwired mergedState (caller predates T-8) is treated the same as an outage — derives nothing', () => {
-    const edits: Array<[string, string]> = [];
-    const result = recomputeParent({
-      parentId: 'T-10',
-      tasksById: parentAndChild(TASK_STATUS.DONE, TASK_STATUS.DONE),
-      gh: { isPrMerged: () => false },
-      backlog: { setStatus: (id, status) => edits.push([id, status]) },
-      fs: fakeCloseAttemptFs(),
-    });
-
-    assert.equal(result, null);
-    assert.deepEqual(edits, []);
-  });
-
   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: { setStatus: () => {} },
+      backlog: fakeParentBacklog(),
       fs: fakeCloseAttemptFs(),
     });
     assert.equal(result, null);
@@ -1269,8 +1937,8 @@ describe('recomputeParent', () => {
     const result = recomputeParent({
       parentId: 'T-99',
       tasksById: parentAndChild(TASK_STATUS.BLOCKED),
-      gh: { isPrMerged: () => false },
-      backlog: { setStatus: () => {} },
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+      backlog: fakeParentBacklog(),
       fs: fakeCloseAttemptFs(),
     });
     assert.equal(result, null);
@@ -1295,7 +1963,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
         gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
-        backlog: { setStatus: (id, status) => edits.push([id, status]) },
+        backlog: fakeParentBacklog(edits),
         fs,
       });
 
@@ -1318,7 +1986,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
         gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
-        backlog: { setStatus: (id, status) => edits.push([id, status]) },
+        backlog: fakeParentBacklog(edits),
         fs: fakeCloseAttemptFs(['T-10']),
       });
 
@@ -1332,7 +2000,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: complexParentAndChild(TASK_STATUS.BLOCKED),
         gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
-        backlog: { setStatus: (id, status) => edits.push([id, status]) },
+        backlog: fakeParentBacklog(edits),
         fs: fakeCloseAttemptFs(['T-10']),
       });
 
@@ -1345,7 +2013,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
         gh: { isPrMerged: () => true, mergedState: () => 'merged' },
-        backlog: { setStatus: () => {} },
+        backlog: fakeParentBacklog(),
         fs: fakeCloseAttemptFs(['T-10']),
       });
 
@@ -1369,7 +2037,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: { 'T-10': parent(TASK_STATUS.IN_PROGRESS), 'T-11': child },
         gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
-        backlog: { setStatus: () => {} },
+        backlog: fakeParentBacklog(),
         fs,
       });
       assert.deepEqual(firstPass, {
@@ -1384,7 +2052,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: { 'T-10': parent(TASK_STATUS.BLOCKED), 'T-11': child },
         gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
-        backlog: { setStatus: () => {} },
+        backlog: fakeParentBacklog(),
         fs,
       });
       assert.equal(
@@ -1405,7 +2073,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: complexParentAndChild(TASK_STATUS.IN_PROGRESS),
         gh: { isPrMerged: () => false, mergedState: () => 'unknown' },
-        backlog: { setStatus: (id, status) => edits.push([id, status]) },
+        backlog: fakeParentBacklog(edits),
         fs,
       });
 
@@ -1431,7 +2099,7 @@ describe('recomputeParent', () => {
         parentId: 'T-10',
         tasksById: complexParentAndChild(TASK_STATUS.QUEUED),
         gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
-        backlog: { setStatus: (id, status) => edits.push([id, status]) },
+        backlog: fakeParentBacklog(edits),
         fs,
       });
 
@@ -1540,6 +2208,12 @@ describe('runMaintenance — a dead worker never loses its work', () => {
     );
   });
 
+  // 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)],
@@ -1649,6 +2323,9 @@ describe('runMaintenance — a concurrent per-slot change made mid-pass', () =>
         );
         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);