@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -3,14 +3,15 @@
  *
  * Runner: `node --import tsx --test scripts/backlog/entry.test.ts`
  *
- * Covers `resolveContext` (`BACKLOG_CWD` resolution via an injected `findRepoRoot`),
- * `acquireSingleFlight`/`releaseSingleFlight` (a concurrent second invocation is refused; a stale
- * lock naming a dead PID is replaced), `shouldDispatchFromCallback` (the anti-loop guard:
- * `specs/backlog-task-dispatcher/spec.md` — "Anti-loop guard on status transitions"), and
- * `selectNextTask` (priority then age — "Task selection ordering"). `runOnce`'s wiring order
- * (maintenance → selection → guards → slot → launch → close) is asserted through recording
- * doubles for every injected collaborator, so this suite never touches a real filesystem, git
- * repository, or `claude` process.
+ * Covers `resolveContext`/`resolveMainCheckout` — the one main-checkout resolver every dispatcher
+ * entry point shares: `BACKLOG_CWD` resolution, or `git rev-parse --git-common-dir` from either a
+ * worktree or the main checkout itself —, `acquireSingleFlight`/`releaseSingleFlight` (a
+ * concurrent second invocation is refused; a stale lock naming a dead PID is replaced),
+ * `shouldDispatchFromCallback` (the anti-loop guard: `specs/backlog-task-dispatcher/spec.md` —
+ * "Anti-loop guard on status transitions"), and `selectNextTask` (priority then age — "Task
+ * selection ordering"). `runOnce`'s wiring order (maintenance → selection → guards → slot → launch
+ * → close) is asserted through recording doubles for every injected collaborator, so this suite
+ * never touches a real filesystem, git repository, or `claude` process.
  */
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
@@ -20,6 +21,7 @@ import {
   isDispatcherOwnedCallback,
   releaseSingleFlight,
   resolveContext,
+  resolveMainCheckout,
   runOnce,
   selectNextTask,
   shouldDispatchFromCallback,
@@ -30,14 +32,16 @@ import type { MaintenanceContext } from './maintenance.js';
 import {
   EXECUTION_PATH,
   LANE,
+  MODE,
   TASK_STATUS,
   TIER,
   type SettingsAllowRule,
+  type SlotInfo,
   type SlotRegistry,
   type Task,
 } from './types.js';
 
-// ── resolveContext ───────────────────────────────────────────────────────────
+// ── resolveMainCheckout / resolveContext ─────────────────────────────────────
 
 /** Loaded allow rules as the PROJECT settings file contributes them. */
 const projectRules = (...rules: string[]): SettingsAllowRule[] =>
@@ -45,33 +49,55 @@ const projectRules = (...rules: string[]): SettingsAllowRule[] =>
 const userRules = (...rules: string[]): SettingsAllowRule[] =>
   rules.map((rule) => ({ rule, source: 'user' as const }));
 
+describe('resolveMainCheckout', () => {
+  // The git-topology half of `resolveContext`, its own function because `dispatch.ts`'s `main()`
+  // needs it UNCONDITIONALLY (never `BACKLOG_CWD`-overridden) for `repoRoot`.
+  it('resolves the main checkout from an ABSOLUTE git-common-dir, as printed from a worktree', () => {
+    const result = resolveMainCheckout({
+      cwd: '/repo/.claude/worktrees/task+T-113',
+      gitCommonDir: () => '/repo/.git\n',
+    });
+    assert.equal(result, '/repo');
+  });
+
+  it('resolves the main checkout from a RELATIVE git-common-dir, as printed from the main checkout itself', () => {
+    const result = resolveMainCheckout({
+      cwd: '/repo',
+      gitCommonDir: () => '.git\n',
+    });
+    assert.equal(result, '/repo');
+  });
+});
+
 describe('resolveContext', () => {
-  it('resolves the main checkout path via the injected findRepoRoot, from the given cwd', () => {
-    const calls: string[] = [];
+  it('from a worktree (gitCommonDir returns an ABSOLUTE /main/.git), resolves the main checkout — not the cwd it was called from', () => {
     const result = resolveContext({
-      cwd: '/repo/.claude/worktrees/dispatch-a',
+      cwd: '/repo/.claude/worktrees/task-T-121',
       env: {},
-      findRepoRoot: (startDir) => {
-        calls.push(startDir);
-        return '/repo';
-      },
+      gitCommonDir: () => '/repo/.git\n',
     });
     assert.equal(result.mainCheckoutPath, '/repo');
-    assert.deepEqual(calls, ['/repo/.claude/worktrees/dispatch-a']);
+    assert.notEqual(result.mainCheckoutPath, '/repo/.claude/worktrees/task-T-121');
   });
 
-  it('prefers an explicit BACKLOG_CWD over findRepoRoot, without even calling it', () => {
-    const calls: string[] = [];
+  it("from a repository with no worktrees (gitCommonDir returns the relative .git), resolves exactly the cwd's repository root — today's behaviour, unchanged", () => {
+    const result = resolveContext({
+      cwd: '/repo',
+      env: {},
+      gitCommonDir: () => '.git\n',
+    });
+    assert.equal(result.mainCheckoutPath, '/repo');
+  });
+
+  it('BACKLOG_CWD wins outright — gitCommonDir is never even called', () => {
     const result = resolveContext({
       cwd: '/repo',
       env: { BACKLOG_CWD: '/tmp/isolated-backlog-project' },
-      findRepoRoot: (startDir) => {
-        calls.push(startDir);
-        return '/repo';
+      gitCommonDir: () => {
+        throw new Error('must not be called when BACKLOG_CWD is set');
       },
     });
     assert.equal(result.mainCheckoutPath, '/tmp/isolated-backlog-project');
-    assert.deepEqual(calls, []);
   });
 });
 
@@ -223,8 +249,11 @@ const baseTask = (overrides: Partial<Task> = {}): Task => ({
   tier: TIER.MINOR,
   lane: LANE.LOCAL,
   path: EXECUTION_PATH.DIRECT,
+  mode: MODE.HEADLESS,
   // Non-empty on purpose: guard 1 blocks a `lane:local` task that declares no files to touch.
-  filesToTouch: ['scripts/backlog/entry.ts'],
+  // An ordinary product path, never `scripts/backlog/` — that path is supervised-only (guard 1e)
+  // and would block every test in this file that expects the task to reach dispatch.
+  filesToTouch: ['backend/src/@app/some-bc/x.service.ts'],
   testCommand: 'pnpm test:backlog',
   acceptanceCriteria: [],
   definitionOfDone: [],
@@ -306,9 +335,23 @@ function noopMaintenanceContext(tasks: Task[], slots: SlotRegistry): Maintenance
       // whole contract this double owes `MaintenanceFs`.
       hasCloseAttemptBeenEnqueued: () => false,
       markCloseAttemptEnqueued: () => {},
+      // T-68: no fixture in this suite exercises the «Registro de ejecución» block (that lives in
+      // `maintenance.test.ts`) — every attempt reads as unknown, the whole contract this double
+      // owes the two new `MaintenanceFs` members.
+      attemptStreamOutcome: () => null,
+      attemptReviewVerdict: () => null,
+    },
+    gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+    backlog: {
+      setStatus: () => {},
+      comment: () => {},
+      appendNotes: () => {},
+      readNotes: () => null,
+      // No fixture in this suite carries the `board:graph` label (that lives in
+      // `maintenance.test.ts`), so step 5b always resolves to `no-holder` and never calls either.
+      setDescription: () => {},
+      readDescription: () => null,
     },
-    gh: { isPrMerged: () => false },
-    backlog: { setStatus: () => {}, comment: () => {} },
     git: {
       hasPendingBacklogChanges: () => false,
       commitBacklogChanges: () => {},
@@ -354,6 +397,13 @@ function makeRunOnceContext(
       calls.push('provisionSlot');
       return slot;
     },
+    // Returns a DISTINCT object from its input — a fake that echoed the same slot back could
+    // never distinguish "the right slot was passed in" from "any slot was passed in", so a test
+    // asserting on the persisted result would pass regardless of what argument reached it.
+    provisionCliDependencies: (slot) => {
+      calls.push('provisionCliDependencies');
+      return { ...slot, cliLockfileHash: 'stub-cli-lockfile-hash' };
+    },
     writeLock: () => calls.push('writeLock'),
     // The default fake still owns the lock: it echoes back what this pass would have written.
     readLock: (taskId) => ({
@@ -608,6 +658,14 @@ describe('runOnce', () => {
       'runGit(clean -fd)',
       'runGit(fetch origin --prune)',
       'runGit(checkout -B task/T-1 origin/main)',
+      // T-50: packages/cli's own dist-removal/install must run AFTER prepareSlot's git sequence
+      // above (never before, never folded into provisionSlot) — this position is what a caller
+      // that put it back before prepareSlot, or dropped it, would break. Its OWN `updateSlots`
+      // write follows immediately: `cliLockfileHash` is persisted only once this call returns —
+      // a SEPARATE write from the one right after `provisionSlot` above, never merged into it,
+      // since the two installs succeed (or fail) at different points in this sequence.
+      'provisionCliDependencies',
+      'updateSlots',
       'writeLock',
       'setInProgress',
       'releaseSingleFlight',
@@ -630,6 +688,43 @@ describe('runOnce', () => {
     ]);
   });
 
+  // The wiring decision lives here — WHICH slot object reaches `ctx.provisionCliDependencies`,
+  // and whether its RETURN VALUE actually reaches `slots.json`. A fake that echoed its input back
+  // unchanged (the old default mock) could never distinguish a correct call from a wrong one; this
+  // fixture's default mock now returns a DISTINCT object (`cliLockfileHash: 'stub-cli-lockfile-hash'`)
+  // specifically so this assertion means something. This would fail if `entry.ts` called
+  // `ctx.provisionCliDependencies` with the wrong slot, or dropped its return value on the floor
+  // instead of persisting it.
+  it('passes the acquired slot to provisionCliDependencies and persists its returned cliLockfileHash', async () => {
+    const calls: string[] = [];
+    const written: SlotRegistry[] = [];
+    let received: SlotInfo | undefined;
+    const ctx = recordingUpdates(
+      makeRunOnceContext(
+        {
+          tasks: [baseTask()],
+          provisionCliDependencies: (slot) => {
+            received = slot;
+            calls.push('provisionCliDependencies');
+            return { ...slot, cliLockfileHash: 'stub-cli-lockfile-hash' };
+          },
+        },
+        calls,
+      ),
+      written,
+    );
+
+    await runOnce(ctx);
+
+    assert.equal(received?.name, 'dispatch-a', 'must receive the SLOT this task actually acquired');
+    const persisted = written.at(-1)?.slots.find((slot) => slot.name === 'dispatch-a');
+    assert.equal(
+      persisted?.cliLockfileHash,
+      'stub-cli-lockfile-hash',
+      'the CLI hash provisionCliDependencies returned must reach the registry',
+    );
+  });
+
   // F2 (T-14 fix round, 2026-09-08): the pair below is what would have caught the F1 mutation —
   // the reviewer deleted `ctx.remoteBranches` from the `evaluateGuards` call this module makes and
   // the WHOLE suite stayed green at 963/963, because no `runOnce` fixture ever exercised guard 4b in
@@ -648,39 +743,26 @@ describe('runOnce', () => {
     assert.equal(result.outcome.kind, 'dispatched');
   });
 
-  // Fix round B3: `tasksById: board.tasksById` in the `prepareSlot` call is the wiring point this
-  // test exists to protect — deleting it is invisible to the type checker (this repo's CI never
-  // runs `tsc` over `scripts/`) and every OTHER fixture here has no parent that declared a branch,
-  // so nothing failed when that line was silently dropped. A parent's DECLARED branch (T-15) must
-  // reach the actual `git checkout`, not just guard 4b's pre-launch check.
-  it("prepares the slot against the parent's DECLARED branch, not the task/<parentId> deduction", async () => {
+  // Restores the coverage "Fix round B3" used to protect (T-52 dropped the declared-branch half of
+  // that test along with the `Branch:` convention, but not this half): `selected.parentId` must
+  // actually REACH `prepareSlot` — this module's own `parentId: selected.parentId` wiring
+  // (`entry.ts`'s `prepareSlot` call) — not just guard 4b's pre-launch check. `PrepareSlotInput`'s
+  // `parentId` is optional and this repo's CI never runs `tsc` over `scripts/`, so dropping that one
+  // argument is invisible to the type checker; only a test that inspects the actual `git checkout`
+  // catches it. With `task/<parentId>` the ONLY base a subtask ever resolves to (T-52), the checkout
+  // must target `origin/task/T-0`.
+  it("prepares the slot against the parent's task/<parentId> branch — parentId must reach prepareSlot", async () => {
     const calls: string[] = [];
     const ctx = makeRunOnceContext(
-      {
-        tasks: [
-          // Not QUEUED: the parent is not a dispatch candidate itself here, only a board entry
-          // `board.tasksById` must expose for the subtask's `declaredBranch` lookup.
-          baseTask({
-            id: 'T-0',
-            status: TASK_STATUS.IN_PROGRESS,
-            declaredBranch: 'fix/parent-branch-resolution',
-          }),
-          baseTask({ id: 'T-1', parentId: 'T-0' }),
-        ],
-        remoteBranches: ['main', 'fix/parent-branch-resolution'],
-      },
+      { tasks: [baseTask({ parentId: 'T-0' })], remoteBranches: ['main', 'task/T-0'] },
       calls,
     );
     const result = await runOnce(ctx);
 
     assert.equal(result.outcome.kind, 'dispatched');
     assert.ok(
-      calls.includes('runGit(checkout -B task/T-1 origin/fix/parent-branch-resolution)'),
-      `expected a checkout against the declared branch; got: ${calls.join(', ')}`,
-    );
-    assert.ok(
-      !calls.some((call) => call.includes('origin/task/T-0')),
-      'must never fall back to the task/<parentId> deduction when the parent declared a real branch',
+      calls.includes('runGit(checkout -B task/T-1 origin/task/T-0)'),
+      `expected a checkout against the parent's task/<parentId> branch; got: ${calls.join(', ')}`,
     );
   });
 
@@ -699,12 +781,11 @@ describe('runOnce', () => {
     assert.deepEqual(calls, ['onBlock']);
   });
 
-  // Fix round B4: `reloadTasks()` returns the whole `BoardLoad`, `complete` included — this module
-  // used to keep only `.tasks`, so an incomplete read (the parent's own `backlog task view` threw)
-  // was indistinguishable from a complete one where the parent genuinely declares nothing. Guard 4b
-  // must WAIT here, not block: blocking would tell a person to push a branch that likely exists —
-  // the read just failed transiently this pass.
-  it('waits, never blocks, on guard 4b when the board read was incomplete and the parent is unreadable', async () => {
+  // T-52 fix round B3: guard 4b resolves a subtask's base purely off `task.parentId` and the live
+  // `remoteBranches` — never the board — so an incomplete board read (the parent's own
+  // `backlog task view` threw this pass) has no bearing on the verdict. It must still BLOCK, exactly
+  // as it would on a complete board.
+  it('blocks on guard 4b even when the board read was incomplete — board completeness has no bearing', async () => {
     const calls: string[] = [];
     const ctx = makeRunOnceContext(
       {
@@ -718,11 +799,10 @@ describe('runOnce', () => {
     );
     const result = await runOnce(ctx);
 
-    assert.equal(result.outcome.kind, 'waiting');
-    if (result.outcome.kind === 'waiting') {
-      assert.equal(result.outcome.reason, 'parent-read-incomplete');
+    assert.equal(result.outcome.kind, 'blocked');
+    if (result.outcome.kind === 'blocked') {
+      assert.equal(result.outcome.reason, 'missing-parent-branch');
     }
-    assert.deepEqual(calls, [], 'a wait must take no slot and call onBlock for nothing');
   });
 
   it('writes the lock with BACKLOG_DISPATCH_ACTIVE carried in the launch env (checked via the recorded launch, not the lock)', async () => {
@@ -839,7 +919,10 @@ describe('runOnce', () => {
   it('asks checkBranchNotMerged before any push, and skips straight to blockKeepSlot when the PR is already merged', async () => {
     const calls: string[] = [];
     const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
-    ctx.maintenance = { ...ctx.maintenance, gh: { isPrMerged: () => true } };
+    ctx.maintenance = {
+      ...ctx.maintenance,
+      gh: { isPrMerged: () => true, mergedState: () => 'merged' },
+    };
 
     const result = await runOnce(ctx);
 
@@ -854,7 +937,10 @@ describe('runOnce', () => {
   it('proceeds through the normal success plan (openPr included) when the branch has no merged PR', async () => {
     const calls: string[] = [];
     const ctx = makeRunOnceContext({ tasks: [baseTask()] }, calls);
-    ctx.maintenance = { ...ctx.maintenance, gh: { isPrMerged: () => false } };
+    ctx.maintenance = {
+      ...ctx.maintenance,
+      gh: { isPrMerged: () => false, mergedState: () => 'not-merged' },
+    };
 
     const result = await runOnce(ctx);
 
@@ -1377,6 +1463,26 @@ describe('runOnce — the task branch is checked out in another slot', () => {
 
     assert.ok(calls.includes('runGit(checkout --detach)'), 'the handback must detach the slot');
   });
+
+  // The scenario the two-artifact hash design exists for: this early return happens AFTER
+  // `provisionSlot`'s own `persistSlot` already wrote the root's refreshed `lockfileHash`, but
+  // BEFORE `ctx.provisionCliDependencies` is ever reached — so nothing about `packages/cli` may be
+  // touched or persisted here, and the NEXT pass's `needsCliInstall` must still correctly see the
+  // CLI as not yet installed.
+  it('never touches packages/cli when the branch is already checked out elsewhere', async () => {
+    const calls: string[] = [];
+    const ctx = makeRunOnceContext(
+      { tasks: [baseTask()], branchesCheckedOutElsewhere: ['task/T-1'] },
+      calls,
+    );
+
+    await runOnce(ctx);
+
+    assert.ok(
+      !calls.includes('provisionCliDependencies'),
+      'a branch-in-use handback must never reach the CLI provisioning step',
+    );
+  });
 });
 
 // ── G5: a step between taking the slot and spawning the worker throws ─────────
@@ -1384,6 +1490,7 @@ describe('runOnce — the task branch is checked out in another slot', () => {
 describe('runOnce — the acquisition-to-spawn span aborts cleanly', () => {
   for (const failing of [
     'provisionSlot',
+    'provisionCliDependencies',
     'runGit',
     'beginAttempt',
     'buildPrompt',
@@ -1400,6 +1507,7 @@ describe('runOnce — the acquisition-to-spawn span aborts cleanly', () => {
           {
             tasks: [baseTask()],
             ...(failing === 'provisionSlot' ? { provisionSlot: boom } : {}),
+            ...(failing === 'provisionCliDependencies' ? { provisionCliDependencies: boom } : {}),
             ...(failing === 'runGit' ? { runGit: boom } : {}),
             ...(failing === 'beginAttempt' ? { beginAttempt: boom } : {}),
             ...(failing === 'buildPrompt' ? { buildPrompt: boom } : {}),
@@ -1483,6 +1591,7 @@ describe('runOnce — the board is re-read after maintenance', () => {
         }
         return false;
       },
+      mergedState: (branch) => (branch === 'task/T-2' ? 'merged' : 'not-merged'),
     };
     ctx.reloadTasks = () => ({
       tasks: [swept ? { ...dependency, status: TASK_STATUS.DONE } : dependency, dependent],

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

@@ -11,6 +11,7 @@
  * `BACKLOG_CWD`, single-flight file lock, orchestrate the pass") so this module unit-tests without
  * a real filesystem, git repository, or `claude` process — see `entry.test.ts`.
  */
+import path from 'node:path';
 import { type AttemptSink } from './attempt.js';
 import {
   checkBranchNotMerged,
@@ -59,25 +60,58 @@ export interface ResolvedContext {
   mainCheckoutPath: string;
 }
 
+/**
+ * Resolves the MAIN checkout — where board data and dispatch state live — from `git rev-parse
+ * --git-common-dir`, honoring no override at all: this is the pure git-topology half of
+ * `resolveContext`, factored out as its own function because `dispatch.ts`'s `main()` also needs it
+ * UNCONDITIONALLY, for `repoRoot` (the code assets `lanes.json` describes — settings files,
+ * worktree slots — which stay bound to THIS machine's checkout regardless of which project
+ * `BACKLOG_CWD` points board data at; see `dispatch.ts`'s own doc comment on `repoRoot`).
+ *
+ * `git rev-parse --git-common-dir` prints the MAIN checkout's ABSOLUTE `.git` directory when run
+ * from a worktree (a worktree's own `.git` is a file pointing back at it, never a directory of its
+ * own), and the RELATIVE `.git`, resolved against `cwd`, when run from the main checkout itself.
+ * Either way the main checkout is that directory's parent. `gitCommonDir` and `cwd` are both
+ * injected so this is testable without shelling out to git.
+ */
+export function resolveMainCheckout(input: { cwd: string; gitCommonDir: () => string }): string {
+  const raw = input.gitCommonDir().trim();
+  const gitDir = path.isAbsolute(raw) ? raw : path.resolve(input.cwd, raw);
+  return path.dirname(gitDir);
+}
+
 /**
  * Resolves the main checkout path the reconciler must read and write backlog state in — never a
  * worktree slot's own copy (spec: "Reconciler operates only on the main checkout"). An explicit
  * `BACKLOG_CWD` in `env` wins outright (same override Backlog.md's own CLI honors — see
  * `backlog init --help`'s "in the current directory (or BACKLOG_CWD when set)"), letting a
  * manual/CI run point the whole reconciler at an isolated project without ever calling
- * `findRepoRoot`; otherwise `findRepoRoot(cwd)` resolves it (the production path: every real
- * trigger already runs from the main checkout, with no `BACKLOG_CWD` override set). Both
- * `findRepoRoot` and `cwd` are injected so this is testable without walking a real directory tree.
+ * `gitCommonDir`; otherwise `resolveMainCheckout` resolves it via `git rev-parse --git-common-dir`.
+ *
+ * A trigger firing from a WORKTREE is the NORMAL case here, not the exception: the root
+ * `CLAUDE.md`'s Worktree Gate mandates that every change — the dispatcher's own work included —
+ * happens on a `task/T-nn` branch inside a worktree, never directly in the main checkout's working
+ * tree. `git rev-parse --git-common-dir` is what tells the two situations apart: from a worktree it
+ * prints the MAIN checkout's ABSOLUTE `.git` directory; from the main checkout itself it prints the
+ * RELATIVE `.git`. `findRepoRoot` (`scripts/_catalog-runtime/repo-root.ts`) cannot make this
+ * distinction — it walks up for a `package.json` named `aurora-catalyst`, which a worktree carries
+ * too, so from inside one it returns the WORKTREE, not the main checkout. Measured consequence
+ * (T-4, 2026-09-16): a reconciler pass triggered from a worktree read `.backlog/.dispatch/` inside
+ * the worktree — gitignored, so it saw no locks, no slots, and no `close-attempt-enqueued` marker —
+ * and `parent.ts`'s rule 4 re-queued an already-closed task. `gitCommonDir` and `cwd` are both
+ * injected so this is testable without shelling out to git.
  */
 export function resolveContext(input: {
   cwd: string;
   env: { BACKLOG_CWD?: string };
-  findRepoRoot: (startDir: string) => string;
+  gitCommonDir: () => string;
 }): ResolvedContext {
   if (input.env.BACKLOG_CWD) {
     return { mainCheckoutPath: input.env.BACKLOG_CWD };
   }
-  return { mainCheckoutPath: input.findRepoRoot(input.cwd) };
+  return {
+    mainCheckoutPath: resolveMainCheckout({ cwd: input.cwd, gitCommonDir: input.gitCommonDir }),
+  };
 }
 
 // ── Single-flight file lock ─────────────────────────────────────────────────────
@@ -248,9 +282,22 @@ export interface RunOnceContext {
   /**
    * Brings the slot's worktree into existence and installs it if the lockfile moved, returning the
    * slot with its refreshed `lockfileHash`. Injected because it shells out to `git worktree add`,
-   * `scripts/worktree-link.sh` and `pnpm install`.
+   * `scripts/worktree-link.sh` and `pnpm install`. Never touches `packages/cli` — see
+   * `provisionCliDependencies` just below.
    */
   provisionSlot: (slot: SlotInfo) => SlotInfo;
+  /**
+   * Removes the slot's stale `packages/cli/dist` and, when needed, (re)installs `packages/cli`'s
+   * OWN dependencies (T-50) — never builds it, the worker does that itself
+   * (`Bash(pnpm cli:build:*)`, T-48). MUST be called AFTER `prepareSlot` has already
+   * reset/cleaned/checked the slot onto the task's branch, never before: `provisionSlot` above runs
+   * BEFORE `prepareSlot`, while the slot's tree may still belong to whichever task last occupied
+   * it, and acting on `packages/cli` there could touch that stale tree instead of the one git just
+   * restored from the remote for THIS task. Returns the slot with `cliLockfileHash` refreshed ONLY
+   * when the install actually ran and succeeded — `SlotInfo.cliLockfileHash`'s doc comment explains
+   * why this is a field of its own, persisted at its own point, never folded into `lockfileHash`.
+   */
+  provisionCliDependencies: (slot: SlotInfo) => SlotInfo;
   writeLock: (lock: DispatchLock) => void;
   /**
    * Reads this task's dispatch lock back from disk, or `null` when there is none. The close checks
@@ -388,10 +435,9 @@ export async function runOnce(ctx: RunOnceContext): Promise<RunOnceResult> {
   // makes the pass answer questions its own maintenance step already resolved.
   const boardLoad = ctx.reloadTasks();
   const tasks = boardLoad.tasks;
-  // `complete` travels onto `board` too, not just `tasks` — fix round B4: guard 4b
-  // (`checkParentBranchOnRemote`) reads it to tell "this pass's parent read failed transiently"
-  // apart from "the parent genuinely declares nothing", and dropping it here made both look
-  // identical to that guard.
+  // `complete` travels onto `board` too, not just `tasks`, keeping this read the same shape as
+  // every other board load in this module — no guard reads it today (`resolveTaskBase` resolves a
+  // subtask's base purely off the live `remoteBranches` list), but the field costs nothing to carry.
   const board: Board = {
     tasksById: Object.fromEntries(tasks.map((task) => [task.id, task])),
     complete: boardLoad.complete,
@@ -541,14 +587,16 @@ export async function runOnce(ctx: RunOnceContext): Promise<RunOnceResult> {
     // The worktree may not exist yet (a fresh checkout, or someone pruned `.claude/worktrees/`):
     // create and install it before anything runs against it. Returns the slot with the lockfile
     // hash this install used, so the next task on this slot skips a redundant `pnpm install`.
-    const slot = { ...ctx.provisionSlot(acquireResult.slot), pid: ctx.currentPid };
+    // Annotated, not inferred: the literal would narrow `pid` to `number`, and the
+    // reassignment at `provisionCliDependencies` below carries the port's nullable
+    // `SlotInfo.pid` — `null` is what a FREE slot holds (`slots.ts`'s release paths).
+    let slot: SlotInfo = { ...ctx.provisionSlot(acquireResult.slot), pid: ctx.currentPid };
     persistSlot(slot);
 
     const prepared = prepareSlot({
       slotPath: slot.path,
       taskId: selected.id,
       parentId: selected.parentId,
-      tasksById: board.tasksById,
       remoteBranches: ctx.remoteBranches,
       branchesCheckedOutElsewhere: ctx.branchesCheckedOutElsewhere,
       runGit: ctx.runGit,
@@ -568,6 +616,15 @@ export async function runOnce(ctx: RunOnceContext): Promise<RunOnceResult> {
       };
     }
 
+    // T-50: only NOW, after `prepareSlot` has reset/cleaned/checked this slot onto the task's own
+    // branch, may anything act on `packages/cli` (dist removal, dependency install). Persisted
+    // in its OWN write, separate from the one above: `cliLockfileHash` must reach `slots.json`
+    // only once the CLI's own install has actually succeeded, never before — see
+    // `SlotInfo.cliLockfileHash`'s doc comment for why a single combined write cannot honor both
+    // this and the root's success moment at once.
+    slot = ctx.provisionCliDependencies(slot);
+    persistSlot(slot);
+
     const nowIso = new Date().toISOString();
     const lock: DispatchLock = {
       taskId: selected.id,

package/dist/templates/monorepo/scripts/backlog/graph-cli.ts

@@ -0,0 +1,70 @@
+/**
+ * graph-cli.ts — the `backlog:graph` executable entry point. Binds `graph.ts`'s pure `runGraphCli`
+ * to the real world: the board (via `dispatch.ts`'s `loadAllTasks`), the `backlog` CLI (via
+ * `dispatch.ts`'s `realBacklog`), the main-checkout resolution (via `entry.ts`'s `resolveContext`,
+ * fed `dispatch.ts`'s `realGitCommonDir`) and stdio.
+ *
+ * The ONLY module in the `backlog-dependency-graph` capability that imports `dispatch.js` —
+ * `graph.ts` itself stays pure over injected effects so `maintenance.ts` (which already imports it
+ * for `decideGraphWrite`) never reaches `dispatch.ts` through it. See `types.ts`'s wiring-direction
+ * rule ("entry.ts cannot import from dispatch.ts — that is the direction the wiring runs"), which
+ * this split keeps intact for the graph code too: graph-cli → dispatch → entry never closes back to
+ * graph.
+ */
+import { fileURLToPath } from 'node:url';
+import { loadAllTasks, realBacklog, realGitCommonDir } from './dispatch.js';
+import { resolveContext } from './entry.js';
+import { GRAPH_CLI_EXIT, runGraphCli, type GraphCliExitCode } from './graph.js';
+
+/**
+ * Binds `runGraphCli` to the real board and the real `backlog` CLI, and turns its exit code into
+ * `process.exitCode` — never a raw stack trace: a failing `git rev-parse` (or any other setup
+ * failure) is caught here and reported the same way `dispatch.ts`'s own `main().catch(...)` does,
+ * message only.
+ *
+ * Resolves the MAIN checkout — where board data lives — through `entry.ts`'s `resolveContext`,
+ * exactly like every other dispatcher entry point: `BACKLOG_CWD` first, `git rev-parse
+ * --git-common-dir` (via `dispatch.ts`'s `realGitCommonDir`) otherwise. See `resolveContext`'s own
+ * doc comment for why `findRepoRoot` cannot be used here — it returns the WORKTREE, not the main
+ * checkout, when run from one.
+ */
+function main(argv: string[]): GraphCliExitCode {
+  try {
+    const cwd = process.cwd();
+    const { mainCheckoutPath } = resolveContext({
+      cwd,
+      env: process.env,
+      gitCommonDir: () => realGitCommonDir(cwd),
+    });
+    // Same dispatcher-owned write channel every other board write goes through (`ownedWrite`'s
+    // busy-retry and `BACKLOG_DISPATCH_ACTIVE` sentinel) — never a bespoke `execFileSync` here.
+    const backlog = realBacklog(mainCheckoutPath);
+
+    return runGraphCli(argv, {
+      loadBoard: () => {
+        const boardLoad = loadAllTasks(mainCheckoutPath);
+        return {
+          tasksById: Object.fromEntries(boardLoad.tasks.map((task) => [task.id, task])),
+          complete: boardLoad.complete,
+        };
+      },
+      // `dispatch.ts`'s `realBacklog.readDescription` throws on a failed underlying read — never
+      // `''` — so `runGraphCli` can report that throw as a failed run instead of treating it as
+      // "nothing to write".
+      readDescription: (id) => backlog.readDescription(id) ?? '',
+      writeDescription: (id, description) => backlog.setDescription(id, description),
+      print: (line) => console.log(line),
+      reportError: (line) => console.error(line),
+    });
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return GRAPH_CLI_EXIT.FAILURE;
+  }
+}
+
+// Entry-point guard: the file is imported by `dispatch.test.ts`/`graph.test.ts` to reuse its
+// types, which must not trigger a real run. `fileURLToPath`, not `new URL(...).pathname` — a space
+// in the path would break the comparison.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  process.exitCode = main(process.argv.slice(2));
+}