@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -23,10 +23,16 @@ import {
   buildCloseRunners,
   buildHookRunners,
   describeExecFailure,
+  EXTERNAL_CALL_TIMEOUT_MS,
   findSlotPathForTask,
   ghEnv,
+  isBoardManagedBacklogPath,
   loadBoard,
+  makeGhRunner,
+  parseBacklogStatusPorcelainZ,
   parseReleaseSlotArg,
+  readCliLockfileHash,
+  readLockfileHash,
   realBacklog,
   realGh,
   realGit,
@@ -38,6 +44,7 @@ import {
 } from './dispatch.js';
 import { type SingleFlightResult } from './entry.js';
 import { REMOTE_BRANCH_DELETE_RESULT } from './maintenance.js';
+import { computeLockfileHash } from './slots.js';
 import {
   EXECUTION_PATH,
   LANE,
@@ -177,6 +184,151 @@ describe('findSlotPathForTask', () => {
   });
 });
 
+// T-50: `readLockfileHash` covers ONLY the root `pnpm-lock.yaml`, never `packages/cli`'s own
+// lockfile too. The two installs are
+// decided and persisted at different points in the dispatch sequence (the root's before
+// `prepareSlot`, the CLI's only after its own install succeeds, later in the same pass, past an
+// early `branch-in-use` return), so one digest could not honor either success moment correctly:
+// a slot could read as "CLI installed" the moment the ROOT's lockfile alone moved, or the reverse.
+describe('readLockfileHash', () => {
+  function repoWithRootLockfile(content: string): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-lockfile-repo-'));
+    fs.writeFileSync(path.join(root, 'pnpm-lock.yaml'), content);
+    return root;
+  }
+
+  it('hashes the root pnpm-lock.yaml alone', () => {
+    const root = repoWithRootLockfile('lockfileVersion: 9.0\npackages: {}\n');
+    assert.equal(readLockfileHash(root), computeLockfileHash(path.join(root, 'pnpm-lock.yaml')));
+  });
+
+  it('is unaffected by packages/cli/pnpm-lock.yaml — changing it must not change this hash', () => {
+    const root = repoWithRootLockfile('lockfileVersion: 9.0\npackages: {}\n');
+    const before = readLockfileHash(root);
+
+    fs.mkdirSync(path.join(root, 'packages', 'cli'), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, 'packages', 'cli', 'pnpm-lock.yaml'),
+      'lockfileVersion: 9.0\npackages: { cli: 1 }\n',
+    );
+
+    assert.equal(readLockfileHash(root), before);
+  });
+
+  it('returns null when the root lockfile cannot be read', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-lockfile-repo-'));
+    assert.equal(readLockfileHash(root), null);
+  });
+});
+
+describe('readCliLockfileHash', () => {
+  it("hashes packages/cli's OWN lockfile, independent of the root's", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-cli-lockfile-repo-'));
+    fs.writeFileSync(path.join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9.0\npackages: {}\n');
+    fs.mkdirSync(path.join(root, 'packages', 'cli'), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, 'packages', 'cli', 'pnpm-lock.yaml'),
+      'lockfileVersion: 9.0\npackages: { cli: 1 }\n',
+    );
+
+    assert.equal(
+      readCliLockfileHash(root),
+      computeLockfileHash(path.join(root, 'packages/cli/pnpm-lock.yaml')),
+    );
+  });
+
+  // The generated-monorepo case: callers are expected to gate on `hasCliPackage` before calling
+  // this at all, but the function itself must still degrade gracefully rather than throw.
+  it('returns null — never throws — when packages/cli has no lockfile of its own', () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-cli-lockfile-repo-'));
+    fs.writeFileSync(path.join(root, 'pnpm-lock.yaml'), 'lockfileVersion: 9.0\npackages: {}\n');
+    assert.doesNotThrow(() => readCliLockfileHash(root));
+    assert.equal(readCliLockfileHash(root), null);
+  });
+});
+
+/**
+ * T-97: `dispatch.ts` shelled out to `git`/`gh`/`backlog` with `execFileSync` and no `timeout`, so a
+ * stalled network call blocked the whole pass forever. Measured 2026-09-15: `realGit`'s
+ * `branchExists` — `git ls-remote --exit-code --heads origin <branch>` — hung 2h23m holding
+ * `dispatch.lock`; every later pass logged "another reconciler pass is already running" with no way
+ * out short of killing the child by hand. These two suites exercise the REAL (un-injected) `run`
+ * default of `realGit`/`realGh` against a fake `git`/`gh` on `PATH` that never returns, bounded by a
+ * short `timeoutMs`/runner so the test itself stays fast — the production bound is
+ * `EXTERNAL_CALL_TIMEOUT_MS`, the same seam (`RealGitDeps.timeoutMs`, `makeGhRunner`), never a
+ * separate mechanism.
+ */
+// `sleep 8`, not a near-infinite sleep: BEFORE the timeout exists (red), `execFileSync` waits for the
+// child to actually exit, so the fake binary must terminate on its own in a few seconds — otherwise
+// this suite itself hangs, and so does the close's own `pnpm test:backlog` run if it ever re-executes
+// this file synchronously while the fix is still unimplemented (measured, see this suite's own header
+// comment). The assert window below (5000ms) stays shorter than this sleep, so red fails FAST rather
+// than hanging, and green (the timeout in place) passes in milliseconds either way.
+function withFakeSlowBinaryOnPath<T>(binaryName: string, run: () => T): T {
+  const binDir = fs.mkdtempSync(path.join(os.tmpdir(), `dispatch-fake-${binaryName}-`));
+  fs.writeFileSync(path.join(binDir, binaryName), '#!/bin/sh\nsleep 8\n');
+  fs.chmodSync(path.join(binDir, binaryName), 0o755);
+  const originalPath = process.env.PATH;
+  process.env.PATH = `${binDir}:${originalPath ?? ''}`;
+  try {
+    return run();
+  } finally {
+    process.env.PATH = originalPath;
+  }
+}
+
+describe('realGit — a hanging git call is bounded, not blocked forever (T-97)', () => {
+  it('branchExists fails within the configured timeout, and treats it like any other git failure', () => {
+    withFakeSlowBinaryOnPath('git', () => {
+      const git = realGit(MAIN_CHECKOUT, { timeoutMs: 200, slotPathFor: () => null });
+      const start = Date.now();
+      const exists = git.branchExists('task/T-does-not-exist');
+      const elapsed = Date.now() - start;
+      assert.equal(
+        exists,
+        false,
+        'a timed-out git call must read exactly like any other git failure — branchExists already ' +
+          'returns false on any error, never a new destructive path (AC2)',
+      );
+      assert.ok(
+        elapsed < 5000,
+        `branchExists must not block past the configured timeout, ever (took ${elapsed}ms)`,
+      );
+    });
+  });
+});
+
+describe('realGh — a hanging gh call is bounded, not blocked forever (T-97)', () => {
+  it('isPrMerged fails within the configured timeout, and treats it like "no PR yet / gh unavailable"', () => {
+    withFakeSlowBinaryOnPath('gh', () => {
+      const gh = realGh(MAIN_CHECKOUT, makeGhRunner(200));
+      const start = Date.now();
+      const merged = gh.isPrMerged('task/T-does-not-exist');
+      const elapsed = Date.now() - start;
+      assert.equal(
+        merged,
+        false,
+        'a timed-out gh call must read exactly like any other gh failure — isPrMerged already ' +
+          'returns false on any error (no PR yet, gh unavailable, or not authenticated), never a ' +
+          'new destructive path (AC2)',
+      );
+      assert.ok(
+        elapsed < 5000,
+        `isPrMerged must not block past the configured timeout, ever (took ${elapsed}ms)`,
+      );
+    });
+  });
+});
+
+it('EXTERNAL_CALL_TIMEOUT_MS is a real, positive, well-under-the-lock-TTL bound', () => {
+  assert.ok(EXTERNAL_CALL_TIMEOUT_MS > 0);
+  assert.ok(
+    EXTERNAL_CALL_TIMEOUT_MS < 10 * 60_000,
+    'a single subprocess call must fail well before the 10-minute per-task lock TTL, or a hang ' +
+      'still reads as a live worker to the maintenance sweep',
+  );
+});
+
 /**
  * Measured defect (T-5, 2026-09-07): the reviewer step failed with `El revisor no se pudo
  * ejecutar: Error: Command failed: claude -p …` and nothing else, so `review.md` said only that a
@@ -672,9 +824,10 @@ describe('buildCloseRunners — leftoverFiles', () => {
     });
   }
 
-  // The fixture task is `lane: local`, where `scripts/` is a refused extra: `scripts/backlog/close.ts`
-  // is therefore a forbidden leftover on THIS lane and a soft one on the frontier lane, and the record
-  // says which — it asks the same classifier `checkScope` asks, per lane.
+  // The fixture task is `lane: local`: `scripts/backlog/close.ts` is supervised-only, forbidden on
+  // every lane, and `backend/src/@app/iam/x.ts` is an ordinary file the local lane's own `scripts/`
+  // extra does not reach either way — only `packages/cli/src/index.ts` lands in the soft bucket.
+  // The record asks the same classifier `checkScope` asks, per lane.
   it('classifies the slot diff into the two kinds, reading inside the slot', () => {
     const recorded: RunCall[] = [];
     const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
@@ -699,13 +852,13 @@ describe('buildCloseRunners — leftoverFiles', () => {
 
     const record = runnersReading(
       slotPath,
-      'scripts/backlog/close.ts\0.claude/settings.json\0',
+      'packages/cli/src/generator/emit.ts\0.claude/settings.json\0',
       recorded,
       { lane: LANE.FRONTIER },
     ).leftoverFiles();
 
     assert.deepEqual(record.forbiddenFiles, ['.claude/settings.json']);
-    assert.deepEqual(record.humanReviewFiles, ['scripts/backlog/close.ts']);
+    assert.deepEqual(record.humanReviewFiles, ['packages/cli/src/generator/emit.ts']);
   });
 
   // T-31 round 4: the base ref was asserted nowhere — replacing it with a hardcoded `origin/main`
@@ -791,49 +944,6 @@ describe('buildCloseRunners — a slot holds the task', () => {
     assert.ok(recorded.length > 0);
     assert.deepEqual(new Set(recorded.map((call) => call.cwd)), new Set([slotPath]));
   });
-
-  // Fix round B3: `resolveBaseRef(task, tasksById)` at this module's own `buildCloseRunners` — the
-  // `base` every mechanical step diffs against — is invisible to the type checker (no `tsc` runs
-  // over `scripts/` in CI) and every OTHER fixture in this file uses a top-level task, so deleting
-  // the `tasksById` argument stayed green everywhere else. A subtask's parent DECLARED branch (T-15)
-  // must reach the actual `git diff`, not just `close.ts`'s own unit tests for the pure function.
-  it("diffs the scope check against the parent's DECLARED branch, not task/<parentId>", () => {
-    const recorded: RunCall[] = [];
-    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
-    const runners = buildCloseRunners({
-      mainCheckoutPath: MAIN_CHECKOUT,
-      repoRoot: MAIN_CHECKOUT,
-      task: task({ id: 'T-1.1', parentId: 'T-0' }),
-      attempt: 1,
-      branch: 'task/T-1.1',
-      reviewerModel: 'sonnet',
-      reviewerTimeoutMs: 15 * 60_000,
-      requestDrain: () => {},
-      tasksById: { 'T-0': task({ id: 'T-0', declaredBranch: 'fix/parent-branch-resolution' }) },
-      boardComplete: true,
-      slotPathFor: () => slotPath,
-      run: (command, args, options) => {
-        recorded.push({ command, args, cwd: options.cwd });
-        return '';
-      },
-      runCapturing: () => ({ status: 0, output: '' }),
-    });
-
-    runners.scopeCheck();
-
-    const diffCall = recorded.find(
-      (call) => call.command === 'git' && call.args[0] === 'diff' && call.args[1] === '--name-only',
-    );
-    assert.ok(diffCall, `expected a scoped git diff; got: ${JSON.stringify(recorded)}`);
-    // The whole argv, not `args[2]`: T-31 inserted `-z` ahead of the range, and an index-addressed
-    // assertion followed the wrong element instead of failing on the shift.
-    assert.deepEqual(diffCall.args, [
-      'diff',
-      '--name-only',
-      '-z',
-      'origin/fix/parent-branch-resolution...HEAD',
-    ]);
-  });
 });
 
 // P5 (round 9): the maintenance sweep already refuses to derive a parent from half a board
@@ -936,12 +1046,10 @@ describe('buildCloseRunners — openPr and the PR already on the branch', () =>
     assert.ok(created, 'with no PR to reuse, the close must create one');
   });
 
-  // Fix round B3: `tasksById` threaded into the `buildPrCreateArgs` call this module makes (K3's
-  // `openPr` runner) — invisible to the type checker (no `tsc` runs over `scripts/` in CI), and
-  // every other fixture in this describe block is a top-level task, so deleting that argument
-  // stayed green everywhere else. A subtask's PR must target the parent's DECLARED branch (T-15),
-  // not the `task/<parentId>` deduction.
-  it("opens the PR against the parent's DECLARED branch, not task/<parentId>", () => {
+  // T-52: a subtask's PR targets `task/<parentId>` — the ONLY base a subtask ever resolves to now
+  // that the Worktree Gate mandates `task/T-nn` for any task on the board (the declared-branch
+  // override this used to test is retired).
+  it("opens the PR against the parent's task/<parentId> branch", () => {
     const recorded: RunCall[] = [];
     const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
     const runners = buildCloseRunners({
@@ -953,7 +1061,7 @@ describe('buildCloseRunners — openPr and the PR already on the branch', () =>
       reviewerModel: 'sonnet',
       reviewerTimeoutMs: 15 * 60_000,
       requestDrain: () => {},
-      tasksById: { 'T-0': task({ id: 'T-0', declaredBranch: 'fix/parent-branch-resolution' }) },
+      tasksById: { 'T-0': task({ id: 'T-0' }) },
       boardComplete: true,
       slotPathFor: () => slotPath,
       run: (command, args, options) => {
@@ -974,7 +1082,7 @@ describe('buildCloseRunners — openPr and the PR already on the branch', () =>
     const created = recorded.find((call) => call.command === 'gh' && call.args[1] === 'create');
     assert.ok(created, 'expected a gh pr create call');
     const baseIndex = created ? created.args.indexOf('--base') : -1;
-    assert.equal(created?.args[baseIndex + 1], 'fix/parent-branch-resolution');
+    assert.equal(created?.args[baseIndex + 1], 'task/T-0');
   });
 
   // Measured defect (T-5, 2026-09-07, real e2e): the close's own `gh pr view`/`gh pr create` ran
@@ -1078,6 +1186,205 @@ describe('buildCloseRunners — openPr and the PR already on the branch', () =>
   });
 });
 
+// ── openPr records the PR URL on the task (T-52) ────────────────────────────────
+//
+// A task worked interactively never closed itself: the maintenance sweep deduces `task/<id>` and
+// asks `gh` whether ITS PR merged, but before T-52 the only trace of where that PR even was lived
+// in a macOS notification (`notify`) nobody was necessarily watching. The close now writes that URL
+// as a board comment too, through `realBacklog` — the dispatcher-owned write channel every other
+// board mutation in this module goes through (`BACKLOG_DISPATCH_ACTIVE='1'` in its env, retried
+// over Backlog.md's per-task lock) — never a raw `backlog` invocation. Both `openPr` branches reach
+// it: creating a PR, and reusing one already open on a retry.
+
+interface RunCallWithEnv extends RunCall {
+  env?: Record<string, string | undefined>;
+}
+
+/** The `backlog task edit <id> --comment <text>` call among everything `openPr` ran, or undefined. */
+function findCommentCall(recorded: readonly RunCallWithEnv[]): RunCallWithEnv | undefined {
+  return recorded.find(
+    (call) => call.command === 'backlog' && call.args[0] === 'task' && call.args[1] === 'edit',
+  );
+}
+
+describe('buildCloseRunners — openPr records the PR URL on the task', () => {
+  it('comments the CREATED PR URL on the task, through the dispatcher-owned write channel', () => {
+    const recorded: RunCallWithEnv[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const result = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd, env: options.env });
+        if (command === 'gh' && args[1] === 'view') {
+          throw new Error('no pull requests found for branch "task/T-1"');
+        }
+        return command === 'gh' ? 'https://github.com/o/r/pull/8\n' : '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    }).openPr();
+
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/8' });
+    const commentCall = findCommentCall(recorded);
+    assert.ok(
+      commentCall,
+      `expected a "backlog task edit --comment" call; got: ${JSON.stringify(recorded)}`,
+    );
+    assert.equal(commentCall!.args[2], 'T-1');
+    const commentIndex = commentCall!.args.indexOf('--comment');
+    assert.notEqual(commentIndex, -1);
+    assert.match(commentCall!.args[commentIndex + 1], /https:\/\/github\.com\/o\/r\/pull\/8/);
+    // Proves the write went through `realBacklog`, not a raw `backlog` invocation bypassing the
+    // dispatcher-owned-write sentinel every other board mutation in this module carries.
+    assert.equal(commentCall!.env?.BACKLOG_DISPATCH_ACTIVE, '1');
+    // The MAIN checkout's board, never the slot's own `.backlog/` copy (design.md decision (l)) — a
+    // mutation that changed the write's `cwd` to the slot would pass every assertion above.
+    assert.equal(commentCall!.cwd, MAIN_CHECKOUT);
+  });
+
+  // B1 (adversarial review, second round): the comment is a TRAIL, never part of the close's
+  // contract — `gh pr create` already returned the URL by the time this runs, so a board write that
+  // fails afterward must never turn a good attempt into `open-pr-failed`. Mutation this catches:
+  // letting the write's error propagate out of `openPr` instead of being swallowed the way
+  // `tickOwnedDod` swallows its own.
+  it('does not fail openPr when the comment write itself fails — it is a trail, not part of the contract', () => {
+    const recorded: RunCallWithEnv[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const result = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 1,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd, env: options.env });
+        if (command === 'backlog') {
+          // Deliberately NOT `BOARD_BUSY_PATTERN`-shaped ("being modified by another process") —
+          // this must fail once and stay failed, not retry for real (blocking) seconds in a test.
+          throw new Error('backlog: permission denied');
+        }
+        if (command === 'gh' && args[1] === 'view') {
+          throw new Error('no pull requests found for branch "task/T-1"');
+        }
+        return command === 'gh' ? 'https://github.com/o/r/pull/8\n' : '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    }).openPr();
+
+    assert.deepEqual(
+      result,
+      { ok: true, compareUrl: 'https://github.com/o/r/pull/8' },
+      'a failed board comment must never turn a successful PR creation into open-pr-failed',
+    );
+    const commentAttempt = recorded.find((call) => call.command === 'backlog');
+    assert.ok(
+      commentAttempt,
+      `expected the comment write to have been attempted (and swallowed); got: ${JSON.stringify(recorded)}`,
+    );
+  });
+
+  it('comments the REUSED PR URL on the task too, not only when it creates one', () => {
+    const recorded: RunCallWithEnv[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const result = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 2,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd, env: options.env });
+        if (command === 'gh' && args[1] === 'view') {
+          return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+        }
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    }).openPr();
+
+    assert.deepEqual(result, { ok: true, compareUrl: 'https://github.com/o/r/pull/7' });
+    assert.ok(
+      !recorded.some((call) => call.command === 'gh' && call.args[1] === 'create'),
+      'the reuse path must never call gh pr create',
+    );
+    const commentCall = findCommentCall(recorded);
+    assert.ok(
+      commentCall,
+      `expected a "backlog task edit --comment" call on the reuse path too; got: ${JSON.stringify(recorded)}`,
+    );
+    assert.equal(commentCall!.args[2], 'T-1');
+    const commentIndex = commentCall!.args.indexOf('--comment');
+    assert.notEqual(commentIndex, -1);
+    assert.match(commentCall!.args[commentIndex + 1], /https:\/\/github\.com\/o\/r\/pull\/7/);
+    assert.equal(commentCall!.env?.BACKLOG_DISPATCH_ACTIVE, '1');
+    assert.equal(commentCall!.cwd, MAIN_CHECKOUT);
+  });
+
+  it('does not fail openPr when the comment write fails on the REUSED-PR path either', () => {
+    const recorded: RunCallWithEnv[] = [];
+    const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
+    const result = buildCloseRunners({
+      mainCheckoutPath: MAIN_CHECKOUT,
+      repoRoot: MAIN_CHECKOUT,
+      task: task(),
+      attempt: 2,
+      branch: 'task/T-1',
+      reviewerModel: 'sonnet',
+      reviewerTimeoutMs: 15 * 60_000,
+      requestDrain: () => {},
+      tasksById: {},
+      boardComplete: true,
+      slotPathFor: () => slotPath,
+      run: (command, args, options) => {
+        recorded.push({ command, args, cwd: options.cwd, env: options.env });
+        if (command === 'backlog') {
+          throw new Error('backlog: permission denied');
+        }
+        if (command === 'gh' && args[1] === 'view') {
+          return JSON.stringify({ url: 'https://github.com/o/r/pull/7', state: 'OPEN' });
+        }
+        return '';
+      },
+      runCapturing: () => ({ status: 0, output: '' }),
+      viewTask: () => boardView(),
+      runOsascript: () => {},
+    }).openPr();
+
+    assert.deepEqual(
+      result,
+      { ok: true, compareUrl: 'https://github.com/o/r/pull/7' },
+      'a failed board comment must never turn a reused PR into open-pr-failed',
+    );
+  });
+});
+
 // ── openPr marks the PR for human review (T-31) ────────────────────────────────
 //
 // `scopeCheck` captures the soft-list files in a closure variable `openPr` reads (design.md
@@ -1096,7 +1403,7 @@ describe('buildCloseRunners — openPr marks the PR for human review', () => {
   ) {
     const slotPath = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-slot-'));
     const softListFile =
-      options.softListFile === undefined ? 'scripts/backlog/dispatch.ts' : options.softListFile;
+      options.softListFile === undefined ? 'packages/cli/src/generator/emit.ts' : options.softListFile;
     return buildCloseRunners({
       mainCheckoutPath: MAIN_CHECKOUT,
       repoRoot: MAIN_CHECKOUT,
@@ -1301,7 +1608,7 @@ describe('buildCloseRunners — openPr marks the PR for human review', () => {
     assert.deepEqual(bodyCall!.args.slice(0, 3), ['pr', 'edit', 'task/T-1']);
     const body = bodyCall!.args[bodyCall!.args.indexOf('--body') + 1];
     assert.match(body, /## Revisión humana requerida/);
-    assert.match(body, /scripts\/backlog\/dispatch\.ts/);
+    assert.match(body, /packages\/cli\/src\/generator\/emit\.ts/);
 
     assert.ok(
       recorded.some((call) => call.command === 'gh' && call.args.includes('--add-label')),
@@ -1341,7 +1648,7 @@ describe('buildCloseRunners — openPr marks the PR for human review', () => {
     const body = bodyCall!.args[bodyCall!.args.indexOf('--body') + 1];
     assert.ok(body.includes(humanNote), "a reviewer's own note must not be destroyed by the mark");
     assert.match(body, /## Revisión humana requerida/);
-    assert.match(body, /scripts\/backlog\/dispatch\.ts/);
+    assert.match(body, /packages\/cli\/src\/generator\/emit\.ts/);
   });
 
   // Failing to READ the body is not a licence to overwrite it: with no idea what is there, the
@@ -1861,22 +2168,291 @@ describe('ghEnv', () => {
 // not narrow what the commit takes, so anything a person already had in the index of the main
 // checkout — a half-finished refactor mid `add -p` — rode along inside an unattended machine
 // commit. The trailing pathspec is what makes the commit take the board and nothing else.
+//
+// T-78 round 2: the filter below is STRUCTURAL (what a path IS), not temporal (when it appeared).
+// A first attempt excluded whatever was already dirty before the pass started, but
+// `.backlog/config.yml` has `auto_commit: false`, so a legitimate interactive/MCP board write
+// routinely sits dirty until a LATER dispatcher pass sweeps it — that write was "dirty before
+// THAT pass" too, and a temporal filter would have excluded it forever, silently. See
+// `isBoardManagedBacklogPath` in dispatch.ts.
 describe('realGit — the board commit', () => {
-  it('commits with a trailing `.backlog` pathspec, so nothing a person had staged rides along', () => {
+  it('commits with a trailing pathspec bounding the commit to what it just staged', () => {
     const recorded: RunCall[] = [];
     realGit(MAIN_CHECKOUT, {
       run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+      readBacklogStatus: () => 'A  .backlog/tasks/t-1.md\0',
     }).commitBacklogChanges('chore(backlog): reconcile');
 
     assert.deepEqual(recorded, [
-      { command: 'git', args: ['add', '.backlog'], cwd: MAIN_CHECKOUT },
+      { command: 'git', args: ['add', '--', '.backlog/tasks'], cwd: MAIN_CHECKOUT },
       {
         command: 'git',
-        args: ['commit', '-m', 'chore(backlog): reconcile', '--no-verify', '--', '.backlog'],
+        args: [
+          'commit',
+          '-m',
+          'chore(backlog): reconcile',
+          '--no-verify',
+          '--',
+          '.backlog/tasks',
+        ],
         cwd: MAIN_CHECKOUT,
       },
     ]);
   });
+
+  // AC #2 (T-78): a genuinely new board output (a new task, a new milestone) is still committed
+  // in full, exactly as before this change.
+  it('still commits every structural entry that is dirty, with no foreign path involved', () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+      readBacklogStatus: () => '?? .backlog/tasks/t-99.md\0?? .backlog/milestones/m-3.md\0',
+    }).commitBacklogChanges('chore(backlog): reconcile');
+
+    assert.deepEqual(recorded[0], {
+      command: 'git',
+      args: ['add', '--', '.backlog/tasks', '.backlog/milestones'],
+      cwd: MAIN_CHECKOUT,
+    });
+    assert.equal(recorded.length, 2);
+  });
+
+  // AC #4 (T-78): reproduces the 2026-09-14 incident — a stray README and a 180KB .xlsx left under
+  // `.backlog/docs/biller-dataset/` (no ID prefix, hand-created) must never reach `git add`, even
+  // though a genuine board file (a task edit) is dirty alongside them.
+  it("excludes a docs/ folder with no ID prefix, keeping only the board's own output", () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+      readBacklogStatus: () =>
+        '?? .backlog/docs/biller-dataset/README.md\0' +
+        '?? .backlog/docs/biller-dataset/Excel_datos_anonimizado_avvale.xlsx\0' +
+        'M  .backlog/tasks/t-74.md\0',
+    }).commitBacklogChanges('chore(backlog): reconcile');
+
+    assert.deepEqual(recorded[0], {
+      command: 'git',
+      args: ['add', '--', '.backlog/tasks'],
+      cwd: MAIN_CHECKOUT,
+    });
+    for (const call of recorded) {
+      assert.equal(
+        call.args.includes('.backlog/docs/biller-dataset/README.md'),
+        false,
+        'the foreign README must never appear in any git argument',
+      );
+      assert.equal(
+        call.args.includes('.backlog/docs/biller-dataset/Excel_datos_anonimizado_avvale.xlsx'),
+        false,
+        'the foreign .xlsx must never appear in any git argument',
+      );
+      assert.equal(
+        call.args.includes('.backlog/docs/biller-dataset'),
+        false,
+        'the foreign directory itself must never appear in any git argument',
+      );
+    }
+  });
+
+  // A legitimate `backlog doc create` output (`doc-<N> - <title>.md`) and a task's own
+  // `docs/t-<N>/` support folder are both board-owned and must be added individually, alongside
+  // the foreign `biller-dataset/` folder being excluded.
+  it('adds ID-prefixed docs/ entries (doc-N and t-N) while excluding an unprefixed one', () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+      readBacklogStatus: () =>
+        '?? .backlog/docs/doc-6 - Informe.md\0' +
+        '?? .backlog/docs/t-21/notas.md\0' +
+        '?? .backlog/docs/biller-dataset/README.md\0',
+    }).commitBacklogChanges('chore(backlog): reconcile');
+
+    assert.deepEqual(recorded[0], {
+      command: 'git',
+      args: ['add', '--', '.backlog/docs/doc-6 - Informe.md', '.backlog/docs/t-21/notas.md'],
+      cwd: MAIN_CHECKOUT,
+    });
+  });
+
+  // T-78 D3, measured against a real git repo: an entirely-untracked directory is reported as ONE
+  // collapsed line for the whole directory (`?? path/`), never one line per file inside it — this
+  // is the exact shape `biller-dataset/` would take on disk (a hand-created folder git has never
+  // seen at all), so the filter must exclude it from that single collapsed line alone, with no
+  // enumeration of what is inside it.
+  it('excludes an entirely-untracked foreign docs/ directory reported as one collapsed line (D3)', () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+      readBacklogStatus: () =>
+        '?? .backlog/docs/biller-dataset/\0M  .backlog/tasks/t-74.md\0',
+    }).commitBacklogChanges('chore(backlog): reconcile');
+
+    assert.deepEqual(recorded[0], {
+      command: 'git',
+      args: ['add', '--', '.backlog/tasks'],
+      cwd: MAIN_CHECKOUT,
+    });
+    for (const call of recorded) {
+      assert.equal(
+        call.args.includes('.backlog/docs/biller-dataset/'),
+        false,
+        'the collapsed foreign directory line must never appear in any git argument',
+      );
+    }
+  });
+
+  // If EVERY dirty path is foreign (nothing in the board's structural schema, nor an ID-prefixed
+  // docs/ entry), the pass produced nothing of its own — a foreign file alone must never trigger a
+  // commit.
+  it('never calls `run` at all when every dirty path is foreign', () => {
+    const recorded: RunCall[] = [];
+    realGit(MAIN_CHECKOUT, {
+      run: (command, args, cwd) => recorded.push({ command, args, cwd }),
+      readBacklogStatus: () => '?? .backlog/docs/biller-dataset/README.md\0',
+    }).commitBacklogChanges('chore(backlog): reconcile');
+
+    assert.deepEqual(recorded, []);
+  });
+
+  // AC #3 (T-78): excluding a foreign path is never silent — it must be logged, and the log must
+  // name the excluded path so a human can go find out why it was there.
+  it('logs the excluded foreign path(s) via console.error', () => {
+    const errors: unknown[] = [];
+    const originalConsoleError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args);
+    };
+    try {
+      realGit(MAIN_CHECKOUT, {
+        run: () => {},
+        readBacklogStatus: () =>
+          '?? .backlog/docs/biller-dataset/README.md\0M  .backlog/tasks/t-74.md\0',
+      }).commitBacklogChanges('chore(backlog): reconcile');
+    } finally {
+      console.error = originalConsoleError;
+    }
+
+    assert.equal(errors.length, 1);
+    assert.match(String(errors[0]), /biller-dataset\/README\.md/);
+  });
+
+  // D7: `hasPendingBacklogChanges` and `commitBacklogChanges` share the one status read for a
+  // given `realGit()` instance — verified by an injected reader that COUNTS its own calls; calling
+  // both methods on the same instance must only read status once.
+  it('reads `.backlog` status only once per instance across both methods (D7)', () => {
+    let readCount = 0;
+    const git = realGit(MAIN_CHECKOUT, {
+      run: () => {},
+      readBacklogStatus: () => {
+        readCount++;
+        return 'M  .backlog/tasks/t-74.md\0';
+      },
+    });
+
+    git.hasPendingBacklogChanges();
+    git.commitBacklogChanges('chore(backlog): reconcile');
+
+    assert.equal(readCount, 1);
+  });
+});
+
+// ── isBoardManagedBacklogPath (T-78) ─────────────────────────────────────────────────────────
+describe('isBoardManagedBacklogPath', () => {
+  it('accepts a task file', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/tasks/t-78 - foo.md'), true);
+  });
+
+  it('accepts a milestone file', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/milestones/m-9 - foo.md'), true);
+  });
+
+  it('accepts an archive entry', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/archive/tasks/t-1.md'), true);
+  });
+
+  it('accepts a completed entry', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/completed/tasks/t-1.md'), true);
+  });
+
+  it("accepts the tool's own config file", () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/config.yml'), true);
+  });
+
+  it('accepts a `backlog doc create` output (doc-N)', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/docs/doc-6 - Título.md'), true);
+  });
+
+  it("accepts a task's own docs/ support folder (t-N)", () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/docs/t-21/notas.md'), true);
+  });
+
+  it('rejects a hand-created docs/ folder with no ID prefix (the 2026-09-14 incident)', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/docs/biller-dataset/README.md'), false);
+  });
+
+  it('rejects a docs/ file with no ID prefix', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/docs/PRD-sin-id.md'), false);
+  });
+
+  it('rejects a random top-level .backlog file outside the structural schema', () => {
+    assert.equal(isBoardManagedBacklogPath('.backlog/random.txt'), false);
+  });
+});
+
+// ── parseBacklogStatusPorcelainZ (T-78) ──────────────────────────────────────────────────────
+describe('parseBacklogStatusPorcelainZ', () => {
+  it('extracts the path from an untracked (`??`) record', () => {
+    assert.deepEqual(parseBacklogStatusPorcelainZ('?? .backlog/tasks/t-1.md\0'), [
+      '.backlog/tasks/t-1.md',
+    ]);
+  });
+
+  it('extracts the path from a modified (`M `) record', () => {
+    assert.deepEqual(parseBacklogStatusPorcelainZ('M  .backlog/tasks/t-1.md\0'), [
+      '.backlog/tasks/t-1.md',
+    ]);
+  });
+
+  it('extracts the path from an added (`A `) record', () => {
+    assert.deepEqual(parseBacklogStatusPorcelainZ('A  .backlog/tasks/t-1.md\0'), [
+      '.backlog/tasks/t-1.md',
+    ]);
+  });
+
+  // Measured against a real git repo (T-78): the default (newline) porcelain format double-quotes
+  // and octal-escapes a non-ASCII byte (`"scripts/backlog/tmp-café.md"` became
+  // `"scripts/backlog/tmp-caf\303\251.md"`); `-z` prints the raw UTF-8 bytes unescaped instead —
+  // this is the whole reason the parser reads `-z` output rather than the newline format.
+  it('passes an accented filename through unescaped, unlike the default (non -z) format', () => {
+    assert.deepEqual(parseBacklogStatusPorcelainZ('?? .backlog/tasks/t-1 - café.md\0'), [
+      '.backlog/tasks/t-1 - café.md',
+    ]);
+  });
+
+  // A rename/copy record (`R`/`C` in the status code) emits the CURRENT path first, then the
+  // ORIGINAL path as a second NUL-terminated field with no status prefix of its own — never the
+  // ` -> ` arrow syntax the newline format uses. Only the current path is a target for `git add`.
+  it('extracts only the CURRENT path from a rename record, discarding the original', () => {
+    assert.deepEqual(
+      parseBacklogStatusPorcelainZ('R  .backlog/tasks/t-2.md\0.backlog/tasks/t-1.md\0'),
+      ['.backlog/tasks/t-2.md'],
+    );
+  });
+
+  it('handles multiple mixed records together, including a rename in the middle', () => {
+    assert.deepEqual(
+      parseBacklogStatusPorcelainZ(
+        '?? .backlog/tasks/t-1.md\0' +
+          'R  .backlog/b.md\0.backlog/a.md\0' +
+          'M  .backlog/tasks/t-2.md\0',
+      ),
+      ['.backlog/tasks/t-1.md', '.backlog/b.md', '.backlog/tasks/t-2.md'],
+    );
+  });
+
+  it('returns an empty array for empty input', () => {
+    assert.deepEqual(parseBacklogStatusPorcelainZ(''), []);
+  });
 });
 
 // ── realGit — branchExists (T-8 point 7's ONLY way to tell "no PR because no branch" apart from
@@ -2244,6 +2820,32 @@ describe('realMaintenanceFs — hasAttemptDir', () => {
   });
 });
 
+// ── T-68 fix 2: realMaintenanceFs — attemptReviewVerdict reuses reviewer.ts's OWN parser ─────
+describe('realMaintenanceFs — attemptReviewVerdict', () => {
+  it('parses a real review.md the way the close reviewer itself would', () => {
+    const checkout = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-main-'));
+    const attemptDir = path.join(checkout, '.backlog', '.dispatch', 'T-9', 'intento-1');
+    fs.mkdirSync(attemptDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(attemptDir, 'review.md'),
+      'Some findings.\n\nREVIEW COMPLETE\nVERDICT: fail\n',
+    );
+
+    const verdict = realMaintenanceFs(checkout, checkout).attemptReviewVerdict('T-9', 1);
+    assert.equal(verdict, 'fail');
+  });
+
+  it('returns null when the attempt has no review.md at all — the ordinary frontier-lane case', () => {
+    const checkout = fs.mkdtempSync(path.join(os.tmpdir(), 'dispatch-main-'));
+    fs.mkdirSync(path.join(checkout, '.backlog', '.dispatch', 'T-9', 'intento-1'), {
+      recursive: true,
+    });
+
+    const verdict = realMaintenanceFs(checkout, checkout).attemptReviewVerdict('T-9', 1);
+    assert.equal(verdict, null);
+  });
+});
+
 // Measured defect (T-5, 2026-09-07): the dispatcher's own `backlog task edit -s ...` calls carried
 // no env override at all, so the `onStatusChange` callback THEY fired never saw
 // `BACKLOG_DISPATCH_ACTIVE` — only a worker's writes (via `worker-edit.ts`) did. A dispatcher-owned
@@ -2290,6 +2892,67 @@ describe('realBacklog — the dispatcher-owned write sentinel', () => {
     ]);
     assert.equal(recorded[0].env?.BACKLOG_DISPATCH_ACTIVE, '1');
   });
+
+  // T-113: the graph-holder refresh's (maintenance.ts step 5b) only writer — same `ownedWrite`
+  // channel and sentinel every other dispatcher-owned write goes through.
+  it('passes BACKLOG_DISPATCH_ACTIVE=1 on setDescription too', () => {
+    const recorded: Array<{ args: string[]; env: NodeJS.ProcessEnv | undefined }> = [];
+    realBacklog(MAIN_CHECKOUT, {
+      run: (args, options) => recorded.push({ args, env: options.env }),
+    }).setDescription('T-112', 'LISTAS — sin dependencias abiertas\n  T-1 [To Do]');
+
+    assert.equal(recorded.length, 1);
+    assert.deepEqual(recorded[0].args, [
+      'task',
+      'edit',
+      'T-112',
+      '--desc',
+      'LISTAS — sin dependencias abiertas\n  T-1 [To Do]',
+    ]);
+    assert.equal(recorded[0].env?.BACKLOG_DISPATCH_ACTIVE, '1');
+  });
+});
+
+// A failed board read must be distinguishable from an empty description — maintenance step 5b and
+// `graph.ts`'s `runGraphCli` both treat a `null` `readDescription` as "genuinely empty, safe to
+// overwrite". `view` is injected the same way `run` already is, so the real failure mode (the CLI
+// call throwing) is reachable from a test without a live `backlog` binary.
+describe('realBacklog — readDescription tells a failed read apart from an empty one', () => {
+  it('throws when the underlying task view fails, instead of swallowing it into null', () => {
+    const backlog = realBacklog(MAIN_CHECKOUT, {
+      view: () => {
+        throw new Error('simulated backlog task view failure');
+      },
+    });
+
+    assert.throws(() => backlog.readDescription('T-112'), /simulated backlog task view failure/);
+  });
+
+  it('returns null for a genuinely empty description, once the view succeeds', () => {
+    const backlog = realBacklog(MAIN_CHECKOUT, {
+      view: () => 'Task T-112 - Holder\n\nStatus: To Do\n',
+    });
+
+    assert.equal(backlog.readDescription('T-112'), null);
+  });
+
+  it('returns the description text when the view succeeds with one', () => {
+    const backlog = realBacklog(MAIN_CHECKOUT, {
+      view: () =>
+        [
+          'Task T-112 - Holder',
+          '==================================================',
+          '',
+          'Status: ○ To Do',
+          '',
+          'Description:',
+          '--------------------------------------------------',
+          'LISTAS — sin dependencias abiertas',
+        ].join('\n'),
+    });
+
+    assert.match(backlog.readDescription('T-112') ?? '', /LISTAS/);
+  });
 });
 
 // Measured defect (T-5, 2026-09-07, real e2e): Backlog.md holds a per-task lock while