@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -7,9 +7,11 @@
  * tails EXACTLY this rendering, written once to `run.log` per
  * `.backlog/.dispatch/<TASK_ID>/intento-<N>/`).
  *
- * `renderEvent` is exported standalone (not just `renderStream`) so `watch.ts` (task 3.20) can
- * render events as they arrive live, one at a time, without buffering a whole file first — the
- * same function `renderStream` calls per line here.
+ * `renderEvent` is exported standalone (not just `renderStream`) so `createLiveRenderer` below —
+ * and through it, `watch.ts`'s live tail of `stream.jsonl` (T-30) — can render events as they
+ * arrive, one at a time, without buffering a whole file first. It is the SAME function
+ * `renderStream` calls per line here, so a live tail and a post-hoc `run.log` read never disagree
+ * on what a given event renders as.
  *
  * Deliberately noise-reducing: a SUCCESSFUL tool result renders nothing (the preceding tool_use
  * line already says what ran; seeing its own success again adds no information), only an ERRORED
@@ -150,10 +152,13 @@ export function renderEvent(event: unknown, t0: number): string | null {
 
 /**
  * Replays a whole recorded `stream-json` session (one JSON object per line — the raw shape
- * `stream.jsonl` stores) into its ordered human-rendered lines, per design.md's `run.log` (what
- * `pnpm backlog:watch` tails). The session's start time (`t0`) is taken from the first line that
- * carries a parseable `timestamp`; an unparseable line is skipped rather than aborting the whole
- * replay (a `run.log` should not go blank because one line was truncated mid-write).
+ * `stream.jsonl` stores) into its ordered human-rendered lines, per design.md's `run.log` — the
+ * final, whole-session artifact `sink.finish()` (`attempt.ts`) writes once, at the end of an
+ * attempt. `pnpm backlog:watch` no longer replays this batch form while a worker is running (see
+ * `createLiveRenderer` below); it still applies here, to `run.log`, and to any offline replay of a
+ * recorded session. The session's start time (`t0`) is taken from the first line that carries a
+ * parseable `timestamp`; an unparseable line is skipped rather than aborting the whole replay (a
+ * `run.log` should not go blank because one line was truncated mid-write).
  */
 export function renderStream(lines: readonly string[]): string[] {
   const events = lines
@@ -185,6 +190,50 @@ function findSessionStart(events: readonly unknown[]): number {
   return Date.now();
 }
 
+// ── createLiveRenderer — the incremental counterpart `watch.ts` feeds live ────────
+
+export interface LiveRenderer {
+  /**
+   * Feeds one raw `stream.jsonl` line (already split off its trailing newline). Returns the
+   * rendered line via `renderEvent`, or `null` when the event is silent or the line does not
+   * parse as JSON — same tolerance `renderStream` has for a line truncated mid-write.
+   */
+  feed: (line: string) => string | null;
+}
+
+/**
+ * Builds a `renderEvent`-based renderer for `pnpm backlog:watch`'s live tail of `stream.jsonl`
+ * (T-30): each new line is rendered the instant it arrives, at O(1) cost per line — unlike
+ * `renderStream`, it never re-renders the lines collected so far. `t0` is carried in closure state
+ * and set once, from the first fed line whose `timestamp` parses — the same rule `findSessionStart`
+ * applies to a whole recorded session, just derived incrementally instead of by scanning ahead.
+ */
+export function createLiveRenderer(): LiveRenderer {
+  let t0: number | null = null;
+  return {
+    feed: (line) => {
+      let event: unknown;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        return null;
+      }
+      if (t0 === null && isRecord(event) && typeof event.timestamp === 'string') {
+        const parsed = Date.parse(event.timestamp);
+        if (!Number.isNaN(parsed)) {
+          t0 = parsed;
+        }
+      }
+      // `t0 ?? Date.now()`: the fallback never actually shapes a rendered line. `elapsedLabel`
+      // (the only reader of `t0`) returns '+?s' on its OWN whenever `event.timestamp` itself fails
+      // to parse — and that is the ONLY case `t0` can still be `null` here, since a parseable
+      // timestamp on THIS event would already have set it, just above. A real `number` is required
+      // by `renderEvent`'s signature regardless, so the fallback stays for that, not for its value.
+      return renderEvent(event, t0 ?? Date.now());
+    },
+  };
+}
+
 // ── classifyStreamOutcome — terminal-outcome classification for `entry.ts`/`close.ts` ──────
 //
 // A worker's stream ends one of four ways (design.md's close diagram: "E -- needs-guidance,
@@ -200,6 +249,14 @@ export const STREAM_OUTCOME = {
   NEEDS_GUIDANCE: 'needs-guidance',
   CRASH: 'crash',
   BUDGET: 'budget',
+  /**
+   * `is_error: true` with a `subtype` that itself says `'success'` (T-83, measured on T-13
+   * intento-1: autocompact thrashing) — the CLI flags the result as a failure but names no
+   * error-specific subtype for it. Never surface the literal `'success'` string as a failure
+   * cause: a reader (the «Registro de ejecución» block, the `Blocked` comment) would read it as
+   * the opposite of what happened.
+   */
+  UNNAMED_FAILURE: 'unnamed-failure',
 } as const;
 
 /**
@@ -263,7 +320,12 @@ export function classifyStreamOutcome(lines: readonly string[]): StreamOutcome {
   // future subtype used to fall through to COMPLETED, which sent a truncated session straight into
   // the success close (scope check, PR) instead of saving the work and blocking.
   if (resultEvent.is_error === true || (typeof resultEvent.subtype === 'string' && resultEvent.subtype !== 'success')) {
-    return typeof resultEvent.subtype === 'string' ? resultEvent.subtype : STREAM_OUTCOME.CRASH;
+    if (typeof resultEvent.subtype !== 'string') {
+      return STREAM_OUTCOME.CRASH;
+    }
+    // `is_error: true` but the subtype itself says 'success' (T-83): the CLI names no
+    // error-specific subtype for this failure, so name it ourselves rather than echo 'success'.
+    return resultEvent.subtype === 'success' ? STREAM_OUTCOME.UNNAMED_FAILURE : resultEvent.subtype;
   }
   if (NEEDS_GUIDANCE_PATTERN.test(lastAssistantText(events))) {
     return STREAM_OUTCOME.NEEDS_GUIDANCE;

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

@@ -25,8 +25,10 @@ import {
   detachSlot,
   isLockAlive,
   lockFilePath,
+  needsCliInstall,
   needsInstall,
   prepareSlot,
+  provisionCliDependencies,
   provisionSlot,
   readLock,
   refreshHeartbeat,
@@ -514,32 +516,6 @@ describe('resolveBranch', () => {
     assert.equal(result.base, 'origin/task/T-12');
   });
 
-  // T-15: a subtask branches from its parent's REAL branch — an interactive session's worktree
-  // branch, declared via the parent's own "Branch:" description line — not from a deduction of the
-  // parent's id. `tasksById` is optional so every existing fixture above (no board in hand) keeps
-  // resolving `task/<parentId>`, exactly as it always has.
-  it("branches off the parent's DECLARED branch when tasksById carries one, never task/<parentId>", () => {
-    const result = resolveBranch({
-      taskId: 'T-13',
-      parentId: 'T-12',
-      tasksById: { 'T-12': { declaredBranch: 'fix/parent-branch-resolution' } },
-      remoteBranches: ['main', 'fix/parent-branch-resolution'],
-    });
-    assert.deepEqual(result, { ref: 'task/T-13', base: 'origin/fix/parent-branch-resolution' });
-  });
-
-  it("throws naming the DECLARED branch when it is the one missing from the remote", () => {
-    assert.throws(
-      () =>
-        resolveBranch({
-          taskId: 'T-13',
-          parentId: 'T-12',
-          tasksById: { 'T-12': { declaredBranch: 'fix/parent-branch-resolution' } },
-          remoteBranches: ['main'],
-        }),
-      /T-13.*parent branch.*origin\/fix\/parent-branch-resolution/s,
-    );
-  });
 });
 
 // ── G3: which directory holds a task's work ───────────────────────────────────
@@ -915,6 +891,218 @@ describe('provisionSlot', () => {
     assert.deepEqual(calls, []);
     assert.deepEqual(result, { created: false, installed: false });
   });
+
+  // T-50: `provisionSlot` never touches `packages/cli` at all — installing it is
+  // `provisionCliDependencies`'s job, called separately by the caller AFTER `prepareSlot`, never
+  // here. This would fail if a `pnpm --dir packages/cli install`/`pnpm cli:build` call crept back
+  // in, at any point in the sequence — `mentionsPackagesCli` checks each ARG for the substring, not
+  // for an exact array element (see the `mentionsPackagesCli` tests below for why that distinction
+  // matters).
+  it('never runs anything under packages/cli, even when the root install runs', () => {
+    const calls: string[][] = [];
+    provisionSlot({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      repoRoot: '/repo',
+      slotExists: false,
+      needsInstall: true,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.equal(
+      mentionsPackagesCli(calls),
+      false,
+      'provisionSlot must never mention packages/cli — that is provisionCliDependencies’s job',
+    );
+  });
+});
+
+/**
+ * A `string[]` array's `.includes` compares EXACT elements, not substrings. Measured:
+ * `[['pnpm','cli:build'],['node','packages/cli/bin/run.js']].every(c=>!c.includes('packages/cli'))`
+ * is `true` — writing the guard above that way would have let `packages/cli/bin/run.js` (a
+ * substring match, never an exact one) slip through silently, contradicting its own comment.
+ */
+function mentionsPackagesCli(calls: readonly string[][]): boolean {
+  return calls.some((call) => call.some((arg) => arg.includes('packages/cli')));
+}
+
+describe('mentionsPackagesCli (guarding the guard above)', () => {
+  it('catches an exact packages/cli argument', () => {
+    assert.equal(mentionsPackagesCli([['pnpm', '--dir', 'packages/cli', 'install']]), true);
+  });
+
+  it('catches a --dir ./packages/cli form (a substring, never an exact element)', () => {
+    assert.equal(mentionsPackagesCli([['pnpm', '--dir', './packages/cli', 'install']]), true);
+  });
+
+  it('catches packages/cli as part of a longer path', () => {
+    assert.equal(mentionsPackagesCli([['node', 'packages/cli/bin/run.js']]), true);
+  });
+
+  it('does not flag unrelated calls', () => {
+    assert.equal(mentionsPackagesCli([['pnpm', 'install'], ['git', 'checkout', '-B', 'main']]), false);
+  });
+});
+
+// T-50: the DECISION lives in this pure function, so a review that inverted a negation in the
+// wiring has something direct to fail against instead of only end-to-end tests.
+describe('needsCliInstall', () => {
+  it('does not install when node_modules is present and the stored hash matches the current one', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: 'same-hash',
+        currentCliLockfileHash: 'same-hash',
+      }),
+      false,
+    );
+  });
+
+  it('installs when node_modules is missing, even with a matching hash', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: false,
+        storedCliLockfileHash: 'same-hash',
+        currentCliLockfileHash: 'same-hash',
+      }),
+      true,
+    );
+  });
+
+  it("installs when the CLI's own lockfile hash changed, even with node_modules present", () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: 'old-hash',
+        currentCliLockfileHash: 'new-hash',
+      }),
+      true,
+    );
+  });
+
+  // Backward compatibility: a slot registered before `cliLockfileHash` existed reads it as
+  // `undefined`, which differs from any real hash and correctly fires the install once.
+  it('installs when the slot has no stored CLI hash at all (a legacy slot)', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: undefined,
+        currentCliLockfileHash: 'new-hash',
+      }),
+      true,
+    );
+  });
+
+  // The generated-monorepo case: `packages/cli/src/templates/monorepo/` has no `packages/`
+  // directory of its own and consumes the npm-published `catalyst` binary — this step must not
+  // apply there, regardless of what the other signals say.
+  it('never installs when the repo has no packages/cli of its own, whatever the other signals say', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: false,
+        cliNodeModulesExists: false,
+        storedCliLockfileHash: undefined,
+        currentCliLockfileHash: 'new-hash',
+      }),
+      false,
+    );
+  });
+
+  it('never fires on a hash mismatch alone when the current hash could not be read (null)', () => {
+    assert.equal(
+      needsCliInstall({
+        hasCliPackage: true,
+        cliNodeModulesExists: true,
+        storedCliLockfileHash: 'old-hash',
+        currentCliLockfileHash: null,
+      }),
+      false,
+    );
+  });
+});
+
+describe('provisionCliDependencies', () => {
+  it('runs pnpm --dir packages/cli install, from the slot, when needsCliInstall is true', () => {
+    const calls: Array<{ command: string; args: string[]; cwd: string }> = [];
+    const result = provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: true,
+      needsCliInstall: true,
+      run: (command, args, cwd) => {
+        calls.push({ command, args, cwd });
+      },
+    });
+
+    assert.deepEqual(calls, [
+      {
+        command: 'rm',
+        args: ['-rf', 'packages/cli/dist'],
+        cwd: '/repo/.claude/worktrees/dispatch-a',
+      },
+      {
+        command: 'pnpm',
+        args: ['--dir', 'packages/cli', 'install'],
+        cwd: '/repo/.claude/worktrees/dispatch-a',
+      },
+    ]);
+    assert.deepEqual(result, { installed: true });
+  });
+
+  // `dist` is gitignored, so `prepareSlot`'s `clean -fd` (no `-x`) never removes it — a worker
+  // that inherits the PREVIOUS occupant's `dist` generates silently wrong code. This must fire
+  // EVERY time packages/cli exists, whether or not the install itself runs.
+  it('removes dist even when no install is needed — a matching hash does not mean a clean dist', () => {
+    const calls: string[][] = [];
+    const result = provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: true,
+      needsCliInstall: false,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.deepEqual(calls, [['rm', '-rf', 'packages/cli/dist']]);
+    assert.deepEqual(result, { installed: false });
+  });
+
+  it('does nothing at all — no dist removal, no install — when the repo has no packages/cli', () => {
+    const calls: string[][] = [];
+    const result = provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: false,
+      needsCliInstall: true,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.deepEqual(calls, []);
+    assert.deepEqual(result, { installed: false });
+  });
+
+  it('never builds the CLI — that stays the worker’s job (T-48)', () => {
+    const calls: string[][] = [];
+    provisionCliDependencies({
+      slotPath: '/repo/.claude/worktrees/dispatch-a',
+      hasCliPackage: true,
+      needsCliInstall: true,
+      run: (command, args) => {
+        calls.push([command, ...args]);
+      },
+    });
+
+    assert.ok(
+      calls.every((call) => !call.includes('cli:build')),
+      'provisionCliDependencies must never run the CLI build',
+    );
+  });
 });
 
 // H1: EVERY release detaches. Only the close's own runner used to, so an abort, a branch-in-use

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

@@ -17,7 +17,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { type DeclaredBranchLookup, resolveTaskBase } from './guards.js';
+import { resolveTaskBase } from './guards.js';
 import {
   DEFAULT_DISPATCH_LIMITS,
   type DispatchLock,
@@ -409,6 +409,14 @@ export function needsInstall(slot: SlotInfo, currentLockfileHash: string): boole
   return slot.lockfileHash !== currentLockfileHash;
 }
 
+/**
+ * Hashes ONE lockfile's content. Used for both `pnpm-lock.yaml` (the root install check,
+ * `lockfileHash`) and `packages/cli/pnpm-lock.yaml` (the CLI install check, `cliLockfileHash`,
+ * T-50) — two SEPARATE calls against two separate files, each stored in its own `SlotInfo` field,
+ * never combined into one digest: the two installs are decided and persisted at different points
+ * in the dispatch sequence, so a single digest covering both files could not honor either success
+ * moment on its own.
+ */
 export function computeLockfileHash(lockfilePath: string): string {
   const content = fs.readFileSync(lockfilePath);
   return crypto.createHash('sha256').update(content).digest('hex');
@@ -422,14 +430,6 @@ export interface ResolveBranchInput {
    *  convention — or `undefined` when this task has no parent. Matches `Task.parentId`'s own type
    *  (`types.ts`: `parentId?: string`, never `null`) so passing it through needs no conversion. */
   parentId?: string;
-  /**
-   * The board's task lookup, for the PARENT's DECLARED branch (`guards.ts`'s `resolveTaskBase`
-   * reads `tasksById[parentId]?.declaredBranch` — T-15, 2026-09-09). Optional so a caller with no
-   * board in hand (every fixture that predates the declared-branch chain) keeps resolving
-   * `task/<parentId>`, exactly as before — never a silently wrong answer, since an absent lookup
-   * reads the same as a parent that declared nothing.
-   */
-  tasksById?: DeclaredBranchLookup;
   remoteBranches: string[];
 }
 
@@ -468,11 +468,7 @@ export function resolveBranch(input: ResolveBranchInput): ResolveBranchResult {
   if (input.remoteBranches.includes(ref)) {
     return { ref, base: 'existing' };
   }
-  const resolution = resolveTaskBase(
-    { parentId: input.parentId },
-    input.tasksById ?? {},
-    input.remoteBranches,
-  );
+  const resolution = resolveTaskBase({ parentId: input.parentId }, input.remoteBranches);
   if (resolution.kind === 'missing-parent-branch') {
     // Fix round B5: this is the LOUDEST failure the resolution chain has — reaching it at all means
     // guard 4b already failed to do its job — so the candidates it computed two lines above must
@@ -495,8 +491,6 @@ export interface PrepareSlotInput {
   taskId: string;
   /** Matches `Task.parentId`'s own type (`types.ts`: `parentId?: string`, never `null`). */
   parentId?: string;
-  /** See `ResolveBranchInput.tasksById` — threaded straight through to `resolveBranch`. */
-  tasksById?: DeclaredBranchLookup;
   remoteBranches: string[];
   /** Branch names other worktrees currently have checked out (`git worktree list --porcelain`). */
   branchesCheckedOutElsewhere: readonly string[];
@@ -525,7 +519,6 @@ export function prepareSlot(input: PrepareSlotInput): PrepareSlotResult {
   const resolved = resolveBranch({
     taskId: input.taskId,
     parentId: input.parentId,
-    tasksById: input.tasksById,
     remoteBranches: input.remoteBranches,
   });
 
@@ -571,6 +564,9 @@ export interface ProvisionSlotResult {
  * (`backend/.keys`, `backend/.env` — without them the backend cannot boot), then `pnpm install`
  * because a worktree installs its OWN dependency tree.
  *
+ * This function never touches `packages/cli` — see `provisionCliDependencies` below, called
+ * separately (and LATER, after `prepareSlot`) for that.
+ *
  * On-demand rather than a bootstrap script: three empty worktrees and three full installs would be
  * paid up front for slots that may never be used, and a missing slot is exactly the state the
  * dispatcher hits after someone prunes `.claude/worktrees/`.
@@ -595,6 +591,121 @@ export function provisionSlot(input: ProvisionSlotInput): ProvisionSlotResult {
   return { created: !input.slotExists, installed: input.needsInstall };
 }
 
+export interface NeedsCliInstallInput {
+  /**
+   * False for a repo with no `packages/cli` of its own. A monorepo GENERATED by this CLI
+   * (`packages/cli/src/templates/monorepo/`) has no `packages/` directory at all and its
+   * `package.json` declares no CLI dependency — a project generated from it consumes the
+   * npm-published `catalyst` binary, never a local one — so this step does not apply there at all.
+   */
+  hasCliPackage: boolean;
+  /**
+   * Whether `packages/cli/node_modules` exists in THIS slot. Gitignored
+   * (`packages/cli/.gitignore`), so `git clean -fd` (no `-x`) never removes it and a fresh
+   * worktree never has it — a condition no lockfile hash can see on its own.
+   */
+  cliNodeModulesExists: boolean;
+  /**
+   * This slot's STORED `packages/cli/pnpm-lock.yaml` hash (`SlotInfo.cliLockfileHash`) —
+   * `undefined` for a slot registered before this field existed, which never equals any real hash
+   * and so correctly fires the install once.
+   */
+  storedCliLockfileHash: string | null | undefined;
+  /**
+   * The CURRENT hash of `packages/cli/pnpm-lock.yaml`, or `null` when it could not be read. A
+   * `null` here never fires the comparison on its own — mirrors `needsInstall`'s own
+   * never-fire-spuriously contract on a failed read.
+   */
+  currentCliLockfileHash: string | null;
+}
+
+/**
+ * Decides whether THIS slot needs `packages/cli`'s dependencies (re)installed (T-50): skipped
+ * outright when the repo has no `packages/cli` of its own; otherwise fired by
+ * `packages/cli/node_modules` being missing, OR the slot's stored CLI lockfile hash differing from
+ * the current one. Deliberately independent of the ROOT's own `needsInstall` decision — the two are
+ * persisted at different points in the dispatch sequence (see `SlotInfo.cliLockfileHash`'s doc
+ * comment), so folding one into the other was the defect this shape replaces. Building the CLI is
+ * NOT this decision's concern — see `provisionCliDependencies`'s doc comment for why installing and
+ * building are split between the dispatcher and the worker.
+ */
+export function needsCliInstall(input: NeedsCliInstallInput): boolean {
+  if (!input.hasCliPackage) {
+    return false;
+  }
+  if (!input.cliNodeModulesExists) {
+    return true;
+  }
+  return (
+    input.currentCliLockfileHash !== null &&
+    input.storedCliLockfileHash !== input.currentCliLockfileHash
+  );
+}
+
+export interface ProvisionCliDependenciesInput {
+  slotPath: string;
+  /** See `NeedsCliInstallInput.hasCliPackage` — skips this ENTIRE step, dist removal included, when false. */
+  hasCliPackage: boolean;
+  /** From `needsCliInstall(...)`. */
+  needsCliInstall: boolean;
+  run: (command: string, args: string[], cwd: string) => void;
+}
+
+export interface ProvisionCliDependenciesResult {
+  installed: boolean;
+}
+
+/**
+ * Prepares `packages/cli` in a slot for the WORKER to build — it never builds it itself. Two
+ * things happen here, both gated on `hasCliPackage` alone (never on `needsCliInstall`):
+ *
+ * 1. **Removes `packages/cli/dist`, unconditionally.** `dist` is gitignored
+ *    (`packages/cli/.gitignore`), so `prepareSlot`'s `git clean -fd` (no `-x`) never touches it —
+ *    without this, a worker inherits the PREVIOUS occupant's build output, produced from THAT
+ *    task's sources, while `packages/cli/src` now holds THIS task's. Running the generator against
+ *    that mismatch is silently wrong codegen (the wrong templates, or templates one commit behind).
+ *    Removing it turns a worker that forgets to rebuild into a LOUD failure (`dist` missing)
+ *    instead — a worker's own task must run `pnpm cli:build` before `node
+ *    packages/cli/bin/run.js` (stated in `frontier-worker-addendum.md`, the only lane with either
+ *    grant, T-48).
+ * 2. **Installs `packages/cli`'s dependencies, only when `needsCliInstall` says to.**
+ *    `packages/cli` is deliberately NOT a pnpm workspace member (root `CLAUDE.md`, D8), so
+ *    `provisionSlot`'s root `pnpm install` never reaches it.
+ *
+ * The caller MUST invoke this AFTER `prepareSlot` has already run `reset --hard` / `clean -fd` /
+ * `checkout -B` — never before. `provisionSlot` runs BEFORE `prepareSlot` (the worktree may not
+ * even exist yet), so acting on `packages/cli` there would touch whatever tree the slot's PREVIOUS
+ * occupant left behind — not necessarily the one git just restored for THIS task, since `prepareSlot`
+ * is what actually performs that restoration. That said, "after `prepareSlot`" only removes the
+ * PREVIOUS OCCUPANT's tree from the picture — it does not guarantee the checked-out tree is
+ * otherwise clean for the CURRENT task: a retry reuses the same `task/T-nn` branch, which may
+ * already carry commits from an earlier attempt (the close saves and pushes work before blocking,
+ * even on `scope-check-failed`), and a subtask's base is `origin/task/<parent>` — another worker's
+ * own tree, not this task's. `packages/cli/package.json` itself also stays editable by the lane's
+ * `Edit(./**)` grant — the security-surface deny list only names the bare `package.json`, never
+ * that nested path — so a legitimate edit there is expected, not a leak this ordering closes.
+ *
+ * This function only ever installs — it never runs `pnpm cli:build`. Building stays with the
+ * WORKER: the frontier lane already grants `Bash(pnpm cli:build:*)` (T-48), and only a task's own
+ * worker knows whether that task needs the generator at all. A dispatcher that also built the CLI
+ * would risk running whatever a worker legitimately wrote into `packages/cli/package.json`'s
+ * `scripts` — the same "dispatcher executes a worker's own code" risk the ordering above closes
+ * for `pnpm install`'s lifecycle scripts; extending that execution to a full build was never
+ * necessary once the worker can do it itself.
+ */
+export function provisionCliDependencies(
+  input: ProvisionCliDependenciesInput,
+): ProvisionCliDependenciesResult {
+  if (!input.hasCliPackage) {
+    return { installed: false };
+  }
+  input.run('rm', ['-rf', 'packages/cli/dist'], input.slotPath);
+  if (input.needsCliInstall) {
+    input.run('pnpm', ['--dir', 'packages/cli', 'install'], input.slotPath);
+  }
+  return { installed: input.needsCliInstall };
+}
+
 export interface ReleaseSlotAndDetachInput {
   taskId: string;
   /** The directory holding this task's work, or `null` when no slot holds it. */