@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -29,7 +29,6 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isSkillTriggerIndex, loadJsonIndex } from '../_catalog-runtime/index.js';
-import { findRepoRoot } from '../_catalog-runtime/repo-root.js';
 import {
   countAttempts,
   createAttemptDir,
@@ -51,6 +50,7 @@ import {
   collectLeftoverFiles,
   DOD_SCOPED_TESTS,
   evaluateAcceptanceGate,
+  evaluateMechanicalCheckResult,
   findOpenPrUrl,
   formatBlockComment,
   HARNESS_REVIEW_LABEL,
@@ -68,6 +68,7 @@ import {
   isDispatcherOwnedCallback,
   releaseSingleFlight,
   resolveContext,
+  resolveMainCheckout,
   runOnce,
   shouldDispatchFromCallback,
   type RunOnceContext,
@@ -99,6 +100,7 @@ import {
 } from './maintenance.js';
 import { notify, type OsascriptRunner } from './notify.js';
 import { effectiveStatus } from './parent.js';
+import { classifyStreamOutcome } from './render.js';
 import {
   assembleExecutorPrompt,
   buildFrontierAddendum,
@@ -115,14 +117,16 @@ import {
   type HookRunners,
   type OperatingEnvelope,
 } from './prompt.js';
-import { reviewerEnv, runReviewer } from './reviewer.js';
+import { parseReviewerVerdict, reviewerEnv, runReviewer } from './reviewer.js';
 import {
   computeLockfileHash,
   createRegistryLock,
   detachSlot,
   isLockAlive,
   isProcessAlive,
+  needsCliInstall,
   needsInstall,
+  provisionCliDependencies,
   provisionSlot,
   readLock,
   refreshHeartbeat,
@@ -135,7 +139,9 @@ import {
 } from './slots.js';
 import {
   findOwnedDefinitionOfDone,
+  notesRegion,
   parseBoardTaskIds,
+  parseDescription,
   parseTaskStatus,
   parseTaskTitle,
   parseTaskView,
@@ -185,6 +191,30 @@ const LINT_BARRELS_SCRIPT = 'hr:lint-barrels';
  */
 const LOCK_TTL_MS = 10 * 60_000;
 
+/**
+ * T-97: how long a single external CLI call (git/gh/backlog/node) may block before it fails like
+ * any other failure of that call — never a new destructive path (AC2).
+ *
+ * Measured defect (2026-09-15): `git ls-remote --exit-code --heads origin <branch>`'s child `ssh` to
+ * github.com hung 2h23m holding the per-task lock. Nothing refreshes a lock's heartbeat while a
+ * synchronous subprocess blocks (see this file's own header on the process model), so a hang here
+ * only ever surfaces once the WHOLE `LOCK_TTL_MS` has elapsed and the maintenance sweep gives up on
+ * the pass — every other Queued task starves meanwhile. Bounded well UNDER `LOCK_TTL_MS`, on
+ * purpose: a call that took the full lock TTL to time out would already read as a dead worker by the
+ * time it failed, which is exactly the failure mode this bound exists to close.
+ */
+export const EXTERNAL_CALL_TIMEOUT_MS = 60_000;
+
+/**
+ * The close's own mechanical checks — prettier, the barrels lint, and the task's declared Test
+ * command — legitimately run for minutes, so they need a longer leash than
+ * `EXTERNAL_CALL_TIMEOUT_MS`. The same invariant still applies: a hang here must fail well before
+ * `LOCK_TTL_MS`, or the exact incident that produced this task's retry (a re-run of this suite's own
+ * `pnpm test:backlog`, synchronous, with no bound, exhausting the lock's heartbeat) recurs on the
+ * next hang instead of failing fast.
+ */
+const MECHANICAL_CHECK_TIMEOUT_MS = 8 * 60_000;
+
 /**
  * The dispatcher-owned Definition-of-Done items, and the close step that PROVES each one. The close
  * ticks them itself once that step passed — see `task-view.ts`'s `DISPATCHER_OWNED_DOD_PATTERNS`.
@@ -201,6 +231,7 @@ function viewTask(mainCheckoutPath: string, taskId: string): string {
   return execFileSync('backlog', ['task', 'view', taskId, '--plain'], {
     cwd: mainCheckoutPath,
     encoding: 'utf8',
+    timeout: EXTERNAL_CALL_TIMEOUT_MS,
   });
 }
 
@@ -249,13 +280,15 @@ export function loadBoard(reader: BoardReader): BoardLoad {
   return { tasks, complete };
 }
 
-function loadAllTasks(mainCheckoutPath: string): BoardLoad {
+/** Exported for `graph.ts`'s `backlog:graph` CLI, which reuses this reader rather than a second one. */
+export function loadAllTasks(mainCheckoutPath: string): BoardLoad {
   const dispatchRoot = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
   return loadBoard({
     list: () =>
       execFileSync('backlog', ['task', 'list', '--plain'], {
         cwd: mainCheckoutPath,
         encoding: 'utf8',
+        timeout: EXTERNAL_CALL_TIMEOUT_MS,
       }),
     view: (taskId) => viewTask(mainCheckoutPath, taskId),
     attempts: (taskId) => countAttempts(dispatchRoot, taskId),
@@ -267,11 +300,13 @@ function loadAllTasks(mainCheckoutPath: string): BoardLoad {
 /**
  * `mainCheckoutPath` (possibly `BACKLOG_CWD`-overridden) is where BOARD DATA lives — `backlog` CLI
  * calls, dispatch locks, `slots.json`. `repoRoot` (never overridden — always this machine's
- * aurora-catalyst checkout, via `findRepoRoot`) is where the CODE assets `lanes.json` describes
- * live: `scripts/backlog/lanes.json` itself, the lane settings files, and every worktree slot
- * (`.claude/worktrees/dispatch-*`) is a checkout of THIS repo, not of whatever `BACKLOG_CWD`
- * points at. These two axes coincide in real production (the reconciler always runs from the main
- * checkout with no `BACKLOG_CWD` override) and only diverge for an isolated test run.
+ * aurora-catalyst checkout, via `resolveMainCheckout`) is where the CODE assets `lanes.json`
+ * describes live: `scripts/backlog/lanes.json` itself, the lane settings files, and every worktree
+ * slot (`.claude/worktrees/dispatch-*`) is a checkout of THIS repo, not of whatever `BACKLOG_CWD`
+ * points at. Both resolve the same git topology (`resolveMainCheckout`, unaffected by whether `cwd`
+ * is the main checkout or one of its worktrees), so these two axes coincide in real production —
+ * where no `BACKLOG_CWD` override is set — and diverge only when one is: an isolated test run, or a
+ * manual/CI invocation pointing board data at a different project.
  */
 export function realMaintenanceFs(mainCheckoutPath: string, repoRoot: string) {
   const dispatchDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
@@ -336,6 +371,30 @@ export function realMaintenanceFs(mainCheckoutPath: string, repoRoot: string) {
       hasCloseAttemptBeenEnqueued(dispatchDir, taskId),
     markCloseAttemptEnqueued: (taskId: string): void =>
       markCloseAttemptEnqueued(dispatchDir, taskId),
+    // T-68: feeds the «Registro de ejecución» block's "Fallos de entorno" and "Resultado del
+    // intento 1" fields — `classifyStreamOutcome` is the SAME classifier `entry.ts` already runs
+    // live on this same file right after the worker exits (render.ts), read back here after the
+    // fact rather than re-implemented.
+    attemptStreamOutcome: (taskId: string, attempt: number): string | null => {
+      const streamPath = path.join(dispatchDir, taskId, `intento-${attempt}`, 'stream.jsonl');
+      if (!fs.existsSync(streamPath)) {
+        return null;
+      }
+      const lines = fs
+        .readFileSync(streamPath, 'utf8')
+        .split('\n')
+        .filter((line) => line.length > 0);
+      return classifyStreamOutcome(lines);
+    },
+    // T-68 fix 2: reuses `reviewer.ts`'s OWN parser rather than a second implementation — the exact
+    // same text `runReviewer`'s `writeReview` callback already persisted to this file.
+    attemptReviewVerdict: (taskId: string, attempt: number): string | null => {
+      const reviewPath = path.join(dispatchDir, taskId, `intento-${attempt}`, 'review.md');
+      if (!fs.existsSync(reviewPath)) {
+        return null;
+      }
+      return parseReviewerVerdict(fs.readFileSync(reviewPath, 'utf8'));
+    },
   };
 }
 
@@ -346,13 +405,23 @@ type GhRunner = (
   options: { cwd: string; env?: Record<string, string> },
 ) => string;
 
-const defaultGhRunner: GhRunner = (command, args, options) =>
-  execFileSync(command, args, {
-    cwd: options.cwd,
-    env: options.env,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'ignore'],
-  });
+/**
+ * Builds a `GhRunner` bounded at `timeoutMs` — the same injection seam `realGit`'s
+ * `RealGitDeps.timeoutMs` uses, so a test binds a short bound without touching the production
+ * default (T-97).
+ */
+export function makeGhRunner(timeoutMs: number): GhRunner {
+  return (command, args, options) =>
+    execFileSync(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: timeoutMs,
+    });
+}
+
+const defaultGhRunner: GhRunner = makeGhRunner(EXTERNAL_CALL_TIMEOUT_MS);
 
 /** The four env keys `gh` itself prefers over its own keyring login, in that order of precedence
  * (measured against `gh`'s own auth resolution: an enterprise token wins for an enterprise host,
@@ -390,6 +459,22 @@ export function ghEnv(parentEnv: NodeJS.ProcessEnv = process.env): Record<string
   return env;
 }
 
+/**
+ * Strips the `undefined` values `NodeJS.ProcessEnv` allows, so an env built from it (like
+ * `realBacklog`'s `{...process.env, BACKLOG_DISPATCH_ACTIVE: '1'}`) satisfies `RunInSlot`'s
+ * stricter `Record<string, string>` — unlike `ghEnv`, nothing here is DENIED, since a board write
+ * carries none of `gh`'s credential concerns.
+ */
+function definedEnv(env: NodeJS.ProcessEnv): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 /**
  * `gh` resolves the repository from the CWD it runs in, so `cwd` is not optional here: without it
  * the call inherited whatever directory launched the reconciler — under launchd, `/` — and `gh pr
@@ -429,6 +514,23 @@ export function realGh(repoRoot: string, run: GhRunner = defaultGhRunner) {
         return null;
       }
     },
+    /**
+     * T-68: the branch's PR number, or `null` on the same fail-closed conditions `prState` reads
+     * (no PR, `gh` unavailable/unauthenticated) — see `MaintenanceGh.prNumber`'s own JSDoc for who
+     * reads this and why.
+     */
+    prNumber: (branch: string): number | null => {
+      try {
+        const output = run('gh', ['pr', 'view', branch, '--json', 'number'], {
+          cwd: repoRoot,
+          env: ghEnv(),
+        });
+        const parsed = JSON.parse(output) as { number?: number };
+        return typeof parsed.number === 'number' ? parsed.number : null;
+      } catch {
+        return null;
+      }
+    },
     /**
      * T-8 defect 1's tri-state answer — see `MaintenanceGh.mergedState`'s own JSDoc for why this
      * cannot reuse `isPrMerged`'s boolean or `prState`'s `string | null` for the decision.
@@ -598,6 +700,14 @@ export interface RealBacklogDeps {
    * `execFileSync` and is what tests assert `env.BACKLOG_DISPATCH_ACTIVE` against.
    */
   run?: (args: string[], options: { cwd: string; env: NodeJS.ProcessEnv }) => void;
+  /**
+   * Injected by tests so `readDescription` is testable without a real `backlog` CLI. The default
+   * wraps `viewTask` — the same `backlog task view --plain` every other reader here goes through —
+   * and, unlike `readTaskText`, is NEVER wrapped in a try/catch: `readDescription` needs a failed
+   * read to be a THROW, not a swallowed `''`, so a maintenance pass or the graph CLI can tell "the
+   * board could not be read" apart from "this task's description is genuinely empty".
+   */
+  view?: (taskId: string) => string;
   /** Overrides `withBoardWriteRetry`'s defaults — tests inject a synchronous, instant `sleep`. */
   retry?: Partial<BoardWriteRetryOptions>;
 }
@@ -608,6 +718,7 @@ const defaultBacklogRun: NonNullable<RealBacklogDeps['run']> = (args, options) =
       cwd: options.cwd,
       env: options.env,
       stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: EXTERNAL_CALL_TIMEOUT_MS,
     });
   } catch (error) {
     throw new Error(`dispatch.ts: backlog ${args.join(' ')} failed: ${describeExecFailure(error)}`);
@@ -629,6 +740,7 @@ const defaultBacklogRun: NonNullable<RealBacklogDeps['run']> = (args, options) =
  */
 export function realBacklog(mainCheckoutPath: string, deps: RealBacklogDeps = {}) {
   const run = deps.run ?? defaultBacklogRun;
+  const view = deps.view ?? ((taskId: string) => viewTask(mainCheckoutPath, taskId));
   const retryOptions: BoardWriteRetryOptions = { ...BOARD_WRITE_RETRY_DEFAULTS, ...deps.retry };
   const ownedWrite = (args: string[]): void =>
     withBoardWriteRetry(
@@ -649,6 +761,33 @@ export function realBacklog(mainCheckoutPath: string, deps: RealBacklogDeps = {}
     comment: (taskId: string, comment: string): void => {
       ownedWrite(['task', 'edit', taskId, '--comment', comment]);
     },
+    // T-68: the «Registro de ejecución» block's only writer — `--append-notes` is the one field
+    // the `Queued` scope freeze (`catalyst-backlog/SKILL.md` §11) leaves open on a `Done` task.
+    appendNotes: (taskId: string, notes: string): void => {
+      ownedWrite(['task', 'edit', taskId, '--append-notes', notes]);
+    },
+    // T-68 fix 4: reuses the SAME `backlog task view --plain` reader every other close-time text
+    // read already goes through (`readTaskText`, hoisted below), but returns ONLY the notes
+    // section (`task-view.ts`'s `notesRegion`) — the whole view's DESCRIPTION, AC or a COMMENT can
+    // legitimately contain text that reads like the heading (a worker quoting the skill, a person
+    // pasting an example), and `close.ts`'s `hasExecutionRecordBlock` has no way to tell that apart
+    // from the real block once handed the whole text.
+    readNotes: (taskId: string): string | null => {
+      const notes = notesRegion(readTaskText(mainCheckoutPath, taskId));
+      return notes.length > 0 ? notes : null;
+    },
+    // T-113: the graph-holder refresh's (maintenance.ts step 5b) only writer/reader — the same
+    // `decideGraphWrite` decision `graph.ts`'s `pnpm backlog:graph --write` uses.
+    setDescription: (taskId: string, description: string): void => {
+      ownedWrite(['task', 'edit', taskId, '--desc', description]);
+    },
+    // Deliberately reads through `view` directly, never through `readTaskText`: a failed board read
+    // must THROW here — see `RealBacklogDeps.view`'s doc comment — so step 5b's try/catch (and the
+    // graph CLI's own) can tell a failed read apart from a description that is genuinely empty.
+    readDescription: (taskId: string): string | null => {
+      const description = parseDescription(view(taskId));
+      return description.length > 0 ? description : null;
+    },
   };
 }
 
@@ -673,6 +812,103 @@ export interface RealGitDeps {
   slotPathFor?: (taskId: string) => string | null;
   /** Injected by tests so no `git` ever runs; the default is a real, output-silenced `execFileSync`. */
   run?: (command: string, args: string[], cwd: string) => void;
+  /** Bounds the default `run`'s `execFileSync` calls (T-97). Defaults to `EXTERNAL_CALL_TIMEOUT_MS`. */
+  timeoutMs?: number;
+  /**
+   * Injected by tests so no real `git status` runs when reading the `.backlog` dirt. Returns the
+   * SAME raw text `readBacklogStatusPorcelainZ` would (NUL-terminated records, `git status
+   * --porcelain=v1 -z` shape) — a test builds it with literal `\0` characters.
+   */
+  readBacklogStatus?: (cwd: string) => string;
+}
+
+/**
+ * The closed set of top-level `.backlog` entries Backlog.md's own CLI manages outright (verified
+ * against a real `.backlog/` tree, T-78): every task, milestone, archived/completed record, and
+ * the tool's own config file. A path under one of these is the board's own output BY WHAT IT IS,
+ * never by when it appeared — see `isBoardManagedBacklogPath`.
+ */
+const STRUCTURAL_BACKLOG_ENTRIES = [
+  '.backlog/tasks',
+  '.backlog/milestones',
+  '.backlog/archive',
+  '.backlog/completed',
+  '.backlog/config.yml',
+] as const;
+
+/**
+ * `backlog doc create` (see `.claude/skills/catalyst-backlog/SKILL.md`) names its own output
+ * `doc-<N> - <title>.md` directly under `.backlog/docs/`; a task also gets a `.backlog/docs/t-<N>/`
+ * support folder, and likewise for a milestone's `m-<N>`. Matched against the FIRST path segment
+ * inside `docs/` only — a `docs/` entry with no such prefix (the 2026-09-14 incident's
+ * `biller-dataset/` folder, hand-created, no ID) is never the board's.
+ */
+const BACKLOG_DOC_ID_PATTERN = /^(doc|t|m)-\d+/;
+
+/**
+ * True for a `.backlog` path Backlog.md's own schema produces — the closed set of entity
+ * directories it manages outright, plus a `docs/` entry named like the tool's own `doc-N`/`t-N`/
+ * `m-N` convention. Anything else under `.backlog` is content a human or another process put
+ * there, not the board — see T-78. Deliberately STRUCTURAL, not temporal: unlike a "was this dirty
+ * before the pass started" check, this never mistakes a board write left uncommitted by an earlier
+ * pass (`.backlog/config.yml` has `auto_commit: false`, so an interactive/MCP write routinely sits
+ * dirty until a LATER dispatcher pass sweeps it up) for something foreign.
+ */
+export function isBoardManagedBacklogPath(relPath: string): boolean {
+  if (
+    STRUCTURAL_BACKLOG_ENTRIES.some(
+      (entry) => relPath === entry || relPath.startsWith(`${entry}/`),
+    )
+  ) {
+    return true;
+  }
+  const docsMatch = relPath.match(/^\.backlog\/docs\/([^/]+)/);
+  return docsMatch !== null && BACKLOG_DOC_ID_PATTERN.test(docsMatch[1]);
+}
+
+/**
+ * Parses `git status --porcelain=v1 -z -- .backlog` output (NUL-terminated records) into the paths
+ * it reports dirty. `-z` is not a cosmetic choice: the default (newline) format double-quotes and
+ * octal-escapes any non-ASCII byte in a path (measured against a real accented filename in this
+ * repo, T-78 D2) — several real task files here carry accents or an em-dash, and a later `git add`
+ * of a hand-reconstructed escaped path fails with "pathspec did not match any files", losing the
+ * WHOLE commit, not just that one file. `-z` prints raw, unescaped UTF-8 bytes instead.
+ *
+ * A rename or copy record (status code containing `R`/`C`) emits TWO consecutive NUL-terminated
+ * fields — the current path, then the original path it was renamed/copied from — instead of the
+ * `OLD -> NEW` arrow syntax the newline format uses. The second field carries no `XY ` status
+ * prefix of its own; it is discarded here since only the current path is ever a target for `git
+ * add`.
+ */
+export function parseBacklogStatusPorcelainZ(porcelain: string): string[] {
+  const fields = porcelain.split('\0').filter((field) => field.length > 0);
+  const paths: string[] = [];
+  for (let i = 0; i < fields.length; i++) {
+    const field = fields[i];
+    const statusCode = field.slice(0, 2);
+    paths.push(field.slice(3));
+    if (/[RC]/.test(statusCode)) {
+      i++; // consume and discard the ORIG_PATH field a rename/copy record appends.
+    }
+  }
+  return paths;
+}
+
+/**
+ * Real `git status --porcelain=v1 -z -- .backlog` in `cwd` — safe on a non-git directory (returns
+ * '').
+ */
+export function readBacklogStatusPorcelainZ(cwd: string): string {
+  try {
+    return execFileSync('git', ['status', '--porcelain=v1', '-z', '--', '.backlog'], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: EXTERNAL_CALL_TIMEOUT_MS,
+    });
+  } catch {
+    return '';
+  }
 }
 
 /**
@@ -694,33 +930,72 @@ export function realGit(mainCheckoutPath: string, deps: RealGitDeps = {}): Maint
     deps.run ??
     ((command, args, cwd) => {
       try {
-        execFileSync(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        execFileSync(command, args, {
+          cwd,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: deps.timeoutMs ?? EXTERNAL_CALL_TIMEOUT_MS,
+        });
       } catch (error) {
         throw new Error(
           `dispatch.ts: ${command} ${args.join(' ')} failed: ${describeExecFailure(error)}`,
         );
       }
     });
+  // Shared by `hasPendingBacklogChanges` and `commitBacklogChanges` (D7): the two are only ever
+  // called back-to-back, immediately, for the SAME pass's single board-commit step (see
+  // `maintenance.ts` step 6) — nothing mutates `.backlog` between them — so caching the one read
+  // for this `realGit()` instance's lifetime removes a redundant `git status` without risking
+  // staleness. A fresh instance (and therefore a fresh cache) is built once per pass.
+  let cachedStatus: string | null = null;
+  const readStatus = (): string => {
+    if (cachedStatus === null) {
+      cachedStatus = (deps.readBacklogStatus ?? readBacklogStatusPorcelainZ)(mainCheckoutPath);
+    }
+    return cachedStatus;
+  };
 
   return {
     hasPendingBacklogChanges: (): boolean => {
-      try {
-        const output = execFileSync('git', ['status', '--porcelain', '--', '.backlog'], {
-          cwd: mainCheckoutPath,
-          encoding: 'utf8',
-          stdio: ['ignore', 'pipe', 'ignore'], // a non-git BACKLOG_CWD (e.g. an isolated test project) fails loudly on stderr otherwise, even though the catch below already handles it silently.
-        });
-        return output.trim().length > 0;
-      } catch {
-        return false; // not a git repo (e.g. a scratch smoke-test project) — nothing to commit.
-      }
+      // A cheap gate, deliberately unfiltered: "something is dirty under .backlog, ours or
+      // foreign" is all this answers. The filtering that tells the two apart lives only in
+      // `commitBacklogChanges` below, which is the one place that actually stages and commits.
+      return readStatus().trim().length > 0;
     },
     commitBacklogChanges: (message: string): void => {
-      run('git', ['add', '.backlog'], mainCheckoutPath);
-      // The trailing pathspec, not the `add`, is what bounds this commit: staging adds to the index
-      // but does not narrow what a commit takes, so a person's own already-staged work in the main
-      // checkout would otherwise ride along inside an unattended machine commit.
-      run('git', ['commit', '-m', message, '--no-verify', '--', '.backlog'], mainCheckoutPath);
+      const current = parseBacklogStatusPorcelainZ(readStatus());
+      const foreignPaths = current.filter((p) => !isBoardManagedBacklogPath(p));
+      if (foreignPaths.length > 0) {
+        // Design decision (T-78): ignore + log, never fail the pass — a stray file under .backlog
+        // must not park the whole board. Never silent either: this is the one place that decides,
+        // and it always says so.
+        console.error(
+          `dispatch.ts: ${foreignPaths.length} file(s) under .backlog are not part of the board's ` +
+            `own schema (tasks/milestones/archive/completed/config.yml, or an ID-prefixed docs/ ` +
+            `entry); excluding them from the sync commit: ${foreignPaths.join(', ')}`,
+        );
+      }
+      // Structural entries are added WHOLE (by directory/file, never a reconstructed individual
+      // filename): git resolves the pathspec itself, so a name with an accent or an em-dash never
+      // has to survive a round trip through our own parsing (T-78 D2), and an entirely-untracked
+      // directory — which `git status` collapses to ONE line for the whole directory, never one
+      // per file inside it (T-78 D3) — is still named correctly by its directory entry.
+      const dirtyStructural = STRUCTURAL_BACKLOG_ENTRIES.filter((entry) =>
+        current.some((p) => p === entry || p.startsWith(`${entry}/`)),
+      );
+      // `docs/` is not added wholesale — real board docs and foreign content share that directory
+      // (T-78), so only the individual ID-prefixed entries dirty right now are named.
+      const dirtyOwnDocs = current.filter(
+        (p) => p.startsWith('.backlog/docs/') && isBoardManagedBacklogPath(p),
+      );
+      const addTargets = [...dirtyStructural, ...dirtyOwnDocs];
+      if (addTargets.length === 0) {
+        return; // nothing the board's own schema produced — a foreign file alone never triggers a commit.
+      }
+      run('git', ['add', '--', ...addTargets], mainCheckoutPath);
+      // The trailing pathspec bounds the commit to exactly what was just staged above, so nothing
+      // a person had ALREADY staged in the main checkout (this runs unattended, in a shared
+      // checkout) rides along inside this machine-built commit.
+      run('git', ['commit', '-m', message, '--no-verify', '--', ...addTargets], mainCheckoutPath);
     },
     saveWipAndPush: (branch: string) => {
       const cwd = resolveSlotPath(branch);
@@ -847,7 +1122,7 @@ export function realGit(mainCheckoutPath: string, deps: RealGitDeps = {}): Maint
 
 function runOsascript(args: string[]): void {
   try {
-    execFileSync('osascript', args, { stdio: 'ignore' });
+    execFileSync('osascript', args, { stdio: 'ignore', timeout: EXTERNAL_CALL_TIMEOUT_MS });
   } catch {
     // Best-effort: a missing osascript (non-Mac, sandboxed CI) must never fail the pass.
   }
@@ -928,7 +1203,7 @@ const NO_SLOT_QUESTION =
   'la tarea no tiene slot asignado en slots.json: no hay directorio donde verificar ni guardar su trabajo.';
 
 export function buildCloseRunners(input: BuildCloseRunnersInput): CloseRunners {
-  const { mainCheckoutPath, repoRoot, task, attempt, branch, tasksById } = input;
+  const { mainCheckoutPath, repoRoot, task, attempt, branch } = input;
   const slotPath =
     input.slotPathFor ??
     ((taskId: string): string | null => findSlotPathForTask(mainCheckoutPath, taskId));
@@ -939,7 +1214,11 @@ export function buildCloseRunners(input: BuildCloseRunnersInput): CloseRunners {
         cwd: options.cwd,
         encoding: 'utf8',
         env: options.env,
-        timeout: options.timeout,
+        // T-97: every call site through this seam used to pass no `timeout` at all — only the
+        // reviewer step (below) ever set one explicitly. Falling back here, rather than at each call
+        // site, is what closes the gap for git/gh/backlog/node calls the close makes without
+        // duplicating the same bound at a dozen call sites.
+        timeout: options.timeout ?? EXTERNAL_CALL_TIMEOUT_MS,
         maxBuffer: LARGE_OUTPUT_MAX_BUFFER,
       }));
   const runCapturing = input.runCapturing ?? spawnCapture;
@@ -952,8 +1231,30 @@ export function buildCloseRunners(input: BuildCloseRunnersInput): CloseRunners {
       return '';
     }
   };
+  // The dispatcher-owned board-write channel (`BACKLOG_DISPATCH_ACTIVE='1'`, retried over
+  // Backlog.md's per-task lock) — routed through the same injected `runIn` every git/gh call in
+  // this closure uses, so a test observes it exactly like any other recorded call, never through a
+  // raw `backlog` invocation `entry.ts`'s dispatcher-owned-write sentinel would fail to recognize.
+  const boardBacklog = realBacklog(mainCheckoutPath, {
+    run: (args, options) => {
+      runIn('backlog', args, { cwd: options.cwd, env: definedEnv(options.env) });
+    },
+  });
+  /**
+   * A TRAIL, not part of the close's contract: `realBacklog` throws on a write it could not
+   * complete after its own retries, and `openPr` must never let that decide whether the attempt
+   * itself was good — the PR already exists by the time this runs. Swallowed the same way
+   * `tickOwnedDod` swallows its own failures (`console.error`, keep going), never rethrown.
+   */
+  const recordPrUrl = (text: string): void => {
+    try {
+      boardBacklog.comment(task.id, text);
+    } catch (error) {
+      console.error(`dispatch.ts: could not comment the PR URL on ${task.id}:`, error);
+    }
+  };
   const attemptDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR, task.id, `intento-${attempt}`);
-  const base = resolveBaseRef(task, tasksById);
+  const base = resolveBaseRef(task);
   // Set by `scopeCheck` below, read by `openPr`'s human-review mark — never recomputed at PR time
   // (design.md decision 8, T-31): by then `mirrorRegen` has written into
   // `packages/cli/src/templates/`, and a recomputation would match `packages/cli/` and mark EVERY
@@ -1031,11 +1332,15 @@ export function buildCloseRunners(input: BuildCloseRunnersInput): CloseRunners {
 
       for (const check of plan.checks) {
         const result = runCapturing(check.command, check.args, cwd);
+        const outcome = evaluateMechanicalCheckResult(check, result.status);
+        const advisoryNote = outcome.advisory
+          ? `[advisory] "${check.label}" exited ${result.status}; not failing the attempt.\n`
+          : '';
         fs.appendFileSync(
           path.join(attemptDir, 'test.log'),
-          `$ ${check.command} ${check.args.join(' ')}\n${result.output}\n`,
+          `$ ${check.command} ${check.args.join(' ')}\n${result.output}\n${advisoryNote}`,
         );
-        if (result.status !== 0) {
+        if (!outcome.ok) {
           return {
             ok: false,
             reason: 'format-lint-test-failed',
@@ -1264,6 +1569,7 @@ export function buildCloseRunners(input: BuildCloseRunnersInput): CloseRunners {
         if (existing !== null) {
           console.error(`dispatch.ts: PR existente reutilizada para ${branch}: ${existing}`);
           notify(`${task.id}: PR existente reutilizada`, existing, osascript);
+          recordPrUrl(`PR existente reutilizada: ${existing}`);
           tickOwnedDod(mainCheckoutPath, task.id, readTask(), DOD_PR_OPENED);
           applyHumanReviewBody();
           markForHumanReview();
@@ -1283,16 +1589,17 @@ export function buildCloseRunners(input: BuildCloseRunnersInput): CloseRunners {
             attempt,
             title,
             taskText: readTask(),
-            tasksById,
             maxAttempts: input.maxAttempts,
             humanReviewFiles,
           }),
           { cwd, env: ghEnv() },
         );
-        notify(`${task.id}: PR abierta`, output.trim(), osascript);
+        const prUrl = output.trim();
+        notify(`${task.id}: PR abierta`, prUrl, osascript);
+        recordPrUrl(`PR abierta: ${prUrl}`);
         tickOwnedDod(mainCheckoutPath, task.id, readTask(), DOD_PR_OPENED);
         markForHumanReview();
-        return { ok: true, compareUrl: output.trim() };
+        return { ok: true, compareUrl: prUrl };
       } catch (error) {
         return { ok: false, reason: 'open-pr-failed', question: describeExecFailure(error) };
       }
@@ -1405,6 +1712,11 @@ function spawnCapture(
       cwd,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
+      // T-97: the declared Test command (and prettier/lint before it) runs through here, unbounded
+      // until now. `MECHANICAL_CHECK_TIMEOUT_MS`, not `EXTERNAL_CALL_TIMEOUT_MS`: a real test suite
+      // legitimately runs for minutes, but a hang must still fail well before `LOCK_TTL_MS` — see
+      // that constant's own header for the measured incident this closes.
+      timeout: MECHANICAL_CHECK_TIMEOUT_MS,
     });
     return { status: 0, output };
   } catch (error) {
@@ -1491,6 +1803,7 @@ export function tickOwnedDod(
           cwd: mainCheckoutPath,
           env: { ...process.env, BACKLOG_DISPATCH_ACTIVE: '1' },
           stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: EXTERNAL_CALL_TIMEOUT_MS,
         });
       } catch (error) {
         throw new Error(
@@ -1560,6 +1873,7 @@ function runHookScript(
         env: { ...process.env, ...env },
         encoding: 'utf8',
         stdio: ['pipe', 'pipe', 'ignore'],
+        timeout: EXTERNAL_CALL_TIMEOUT_MS,
       },
     );
     return result;
@@ -1718,6 +2032,7 @@ function readCheckedOutBranches(repoRoot: string): string[] {
     const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
       cwd: repoRoot,
       encoding: 'utf8',
+      timeout: EXTERNAL_CALL_TIMEOUT_MS,
     });
     return output
       .split('\n')
@@ -1739,7 +2054,7 @@ function readCheckedOutBranches(repoRoot: string): string[] {
 }
 
 /** `null` when the lockfile cannot be read — the install check then never fires spuriously. */
-function readLockfileHash(repoRoot: string): string | null {
+export function readLockfileHash(repoRoot: string): string | null {
   try {
     return computeLockfileHash(path.join(repoRoot, 'pnpm-lock.yaml'));
   } catch (error) {
@@ -1751,6 +2066,35 @@ function readLockfileHash(repoRoot: string): string | null {
   }
 }
 
+/**
+ * `packages/cli`'s OWN lockfile hash, read separately from the root's (T-50): `packages/cli` is
+ * deliberately not a pnpm workspace member (root `CLAUDE.md`, D8), so it carries its own
+ * `pnpm-lock.yaml` outside the root's. Kept in its own function, and its own `SlotInfo` field
+ * (`cliLockfileHash`), rather than folded into `readLockfileHash`'s digest: 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), so one
+ * combined hash could not honor either success moment on its own — a single field could go stale
+ * for the CLI's half while reading as current for the root's, or vice-versa, with no way to tell
+ * from the outside which install a mismatch was actually about.
+ *
+ * Callers must check `hasCliPackage` FIRST: called on a repo with no `packages/cli` of its own (the
+ * monorepo THIS CLI generates — `packages/cli/src/templates/monorepo/` has no `packages/`
+ * directory at all), this always fails to read the file and logs accordingly; the caller is
+ * expected to skip calling it entirely in that case, matching `needsCliInstall`'s own
+ * `hasCliPackage` gate, so no such repo ever sees that log line.
+ */
+export function readCliLockfileHash(repoRoot: string): string | null {
+  try {
+    return computeLockfileHash(path.join(repoRoot, 'packages/cli/pnpm-lock.yaml'));
+  } catch (error) {
+    console.error(
+      'dispatch.ts: could not hash packages/cli/pnpm-lock.yaml; skipping the CLI install check:',
+      error,
+    );
+    return null;
+  }
+}
+
 // ── main ────────────────────────────────────────────────────────────────────────
 
 /** A drained pass may itself drain; two is the cap, so one trigger can never loop the queue. */
@@ -1882,6 +2226,21 @@ function releaseSlotUnderSingleFlight(
   return { kind: 'released' };
 }
 
+/**
+ * The MAIN checkout's `.git` common directory, exactly as `git rev-parse --git-common-dir` reports
+ * it — absolute when run from a worktree, relative when run from the main checkout itself. The one
+ * `gitCommonDir` collaborator `entry.ts`'s `resolveContext`/`resolveMainCheckout` need, real for
+ * every actual trigger; `graph-cli.ts` and `watch.ts` import this same function rather than
+ * shelling out a second way to ask git the same question.
+ */
+export function realGitCommonDir(cwd: string): string {
+  return execFileSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd,
+    encoding: 'utf8',
+    timeout: EXTERNAL_CALL_TIMEOUT_MS,
+  });
+}
+
 /**
  * The single-flight lock file, as one PID a process writes and reads back. Built here rather than
  * inline in `main` because the `--release-slot` rescue serializes on the SAME file: two callers of
@@ -1924,7 +2283,12 @@ function realReleaseSlotDeps(mainCheckoutPath: string, repoRoot: string): Releas
     detach: (slotPath) =>
       detachSlot(
         slotPath,
-        (args, at) => void execFileSync('git', args, { cwd: at, stdio: 'ignore' }),
+        (args, at) =>
+          void execFileSync('git', args, {
+            cwd: at,
+            stdio: 'ignore',
+            timeout: EXTERNAL_CALL_TIMEOUT_MS,
+          }),
       ),
     removeLock: (taskId) => releaseLock(dispatchDir, taskId),
     updateSlots: (mutate) => void slotsFs.updateSlots(mutate),
@@ -1957,15 +2321,20 @@ async function main(): Promise<void> {
     return;
   }
 
+  const cwd = process.cwd();
+  const gitCommonDir = (): string => realGitCommonDir(cwd);
   const { mainCheckoutPath } = resolveContext({
-    cwd: process.cwd(),
+    cwd,
     env: { BACKLOG_CWD: process.env.BACKLOG_CWD },
-    findRepoRoot,
+    gitCommonDir,
   });
-  // Never BACKLOG_CWD-overridden: the code assets lanes.json describes (settings files, worktree
-  // slots) belong to THIS machine's aurora-catalyst checkout, regardless of which backlog project
-  // BACKLOG_CWD points board data at (see realMaintenanceFs's doc comment).
-  const repoRoot = findRepoRoot(process.cwd());
+  // Never BACKLOG_CWD-overridden, and never resolved from a worktree's own copy of this repo: the
+  // code assets lanes.json describes (settings files, worktree slots, `lanes.json` itself) belong to
+  // THIS MACHINE's aurora-catalyst checkout, regardless of which backlog project BACKLOG_CWD points
+  // board data at (see realMaintenanceFs's doc comment) — and regardless of which worktree slot this
+  // very reconciler pass happens to be running from, since `resolveMainCheckout` always walks git
+  // topology up to the main checkout rather than trusting `cwd` directly.
+  const repoRoot = resolveMainCheckout({ cwd, gitCommonDir });
   const dispatchDir = path.join(mainCheckoutPath, DISPATCH_SUBDIR);
   fs.mkdirSync(dispatchDir, { recursive: true });
 
@@ -2093,6 +2462,7 @@ async function runPass(input: RunPassInput) {
     execFileSync('git', ['fetch', 'origin', '--prune'], {
       cwd: repoRoot,
       stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: EXTERNAL_CALL_TIMEOUT_MS,
     });
   } catch (error) {
     console.error(
@@ -2107,6 +2477,7 @@ async function runPass(input: RunPassInput) {
     const output = execFileSync('git', ['branch', '-r', '--format=%(refname:short)'], {
       cwd: repoRoot,
       encoding: 'utf8',
+      timeout: EXTERNAL_CALL_TIMEOUT_MS,
     });
     remoteBranches = output
       .split('\n')
@@ -2127,6 +2498,14 @@ async function runPass(input: RunPassInput) {
 
   const branchesCheckedOutElsewhere = readCheckedOutBranches(repoRoot);
   const lockfileHash = readLockfileHash(repoRoot);
+  // T-50: a monorepo GENERATED by this CLI (`packages/cli/src/templates/monorepo/`) has no
+  // `packages/cli` of its own — it consumes the npm-published `catalyst` binary instead — so the
+  // CLI install/dist-removal step never applies there at all. Checked once per pass: the MAIN
+  // checkout's own `packages/cli` either exists or it does not, for every slot alike. Only read
+  // the CLI's own lockfile hash when the package exists at all, so a generated monorepo never logs
+  // the "could not hash" line `readCliLockfileHash` would otherwise produce on every pass.
+  const hasCliPackage = fs.existsSync(path.join(repoRoot, 'packages/cli'));
+  const currentCliLockfileHash = hasCliPackage ? readCliLockfileHash(repoRoot) : null;
 
   const ctx: RunOnceContext = {
     shouldSelect: shouldDispatchFromCallback(env),
@@ -2167,9 +2546,44 @@ async function runPass(input: RunPassInput) {
       });
       return install && lockfileHash !== null ? { ...slot, lockfileHash } : slot;
     },
+    // T-50: MUST run after `entry.ts` has already called `prepareSlot` — never before, never
+    // folded into `provisionSlot` above. `provisionSlot` runs BEFORE `prepareSlot` (the worktree
+    // may not even exist yet), so acting on `packages/cli` there could touch whatever tree the
+    // slot's PREVIOUS occupant left behind rather than the one `prepareSlot` restores for THIS
+    // task. Returns the slot with `cliLockfileHash` refreshed ONLY when the install actually
+    // succeeded (this call returning at all means it did — a throwing `run` propagates out of
+    // `provisionCliDependencies` and this function never reaches its `return`), never persisted
+    // before that, per `SlotInfo.cliLockfileHash`'s two-artifact design.
+    provisionCliDependencies: (slot) => {
+      const cliNodeModulesExists = fs.existsSync(path.join(slot.path, 'packages/cli/node_modules'));
+      const decision = needsCliInstall({
+        hasCliPackage,
+        cliNodeModulesExists,
+        storedCliLockfileHash: slot.cliLockfileHash,
+        currentCliLockfileHash,
+      });
+      const result = provisionCliDependencies({
+        slotPath: slot.path,
+        hasCliPackage,
+        needsCliInstall: decision,
+        run: (command, args, cwd) => {
+          console.log(`dispatch.ts: provisioning ${slot.name} — ${command} ${args.join(' ')}`);
+          execFileSync(command, args, { cwd, stdio: 'inherit' });
+        },
+      });
+      const cliLockfileHash =
+        result.installed && currentCliLockfileHash !== null
+          ? currentCliLockfileHash
+          : slot.cliLockfileHash;
+      return { ...slot, cliLockfileHash };
+    },
     runGit: (args, cwd) => {
       try {
-        execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        execFileSync('git', args, {
+          cwd,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          timeout: EXTERNAL_CALL_TIMEOUT_MS,
+        });
       } catch (error) {
         throw new Error(`dispatch.ts: git ${args.join(' ')} failed: ${describeExecFailure(error)}`);
       }