mandrel 2.66.0 → 2.68.0

package/.agents/scripts/lib/observability/source-classifier.js

@@ -37,6 +37,8 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',
   'ceremony-derive.js',
+  'clean-temp.js',
+  'clean-worktrees.js',
   'cleanup-repo-test-temp.js',
   'coverage-capture.js',
   'deliver-light.js',
@@ -51,7 +53,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'generate-lens-checklists.js',
   'generate-skills-index.js',
   'generate-workflows-doc.js',
-  'git-cleanup.js',
+  'clean-git.js',
   'lint-issue-body.js',
   'mandrel-update-preflight.js',
   'merge-baseline.js',
@@ -73,6 +75,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'single-story-confirm-merge.js',
   'single-story-init.js',
   'stories-wave-tick.js',
+  'story-review-compute.js',
   'sync-agentrc.js',
   'sync-claude-agents.js',
   'sync-claude-commands.js',

package/.agents/scripts/lib/orchestration/code-review.js

@@ -103,10 +103,13 @@ function resolveScopeEnvelope(opts, config) {
  *   createReviewProviderFn?: typeof createReviewProvider,
  *   upsertCommentFn?: typeof upsertStructuredComment,
  *   renderFindingsFn?: typeof renderFindings,
+ *   deferPost?: boolean,
  * }} opts
  * @returns {Promise<{
  *   status: 'ok'|'no-changes'|'invalid',
  *   severity: { critical: number, high: number, medium: number, suggestion: number },
+ *   findings?: Array<object>,
+ *   providerName?: string,
  *   report?: string,
  *   posted: boolean,
  *   postedCommentId: number|null,
@@ -196,9 +199,10 @@ async function resolvePromptMessages(reviewProvider, reviewInput, logger) {
 }
 
 /**
- * Posting failure is non-fatal and surfaces as `posted: false`.
+ * Posting failure is non-fatal and surfaces as `posted: false`. Also posts a
+ * `deferPost` review's held report.
  */
-async function postReviewComment({
+export async function postReviewComment({
   upsertCommentFn,
   provider,
   commentTargetId,
@@ -230,6 +234,12 @@ async function postReviewComment({
   }
 }
 
+/** A `deferPost` review holds its report for the caller to post. */
+async function postUnlessDeferred(opts, post) {
+  if (opts.deferPost) return { posted: false, postedCommentId: null };
+  return postReviewComment(post);
+}
+
 /**
  * Which review provider(s) raised the critical findings. A chain reports its
  * own per-entry attribution; any other provider owns every critical.
@@ -309,7 +319,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     degradations,
   });
 
-  const { posted, postedCommentId } = await postReviewComment({
+  const { posted, postedCommentId } = await postUnlessDeferred(opts, {
     upsertCommentFn,
     provider,
     commentTargetId,
@@ -320,6 +330,8 @@ async function executeReviewPipeline({ opts, config, envelope }) {
   return {
     status: 'ok',
     severity,
+    findings,
+    providerName,
     report,
     posted,
     postedCommentId,

package/.agents/scripts/lib/orchestration/git-cleanup/phases/cli.js

@@ -1,5 +1,5 @@
 /**
- * git-cleanup `main()`: argv, base-branch resolution, the four phases, and
+ * `clean-git.js` `main()`: argv, base-branch resolution, the four phases, and
  * the optional JSON envelope.
  *
  * @module lib/orchestration/git-cleanup/phases/cli

package/.agents/scripts/lib/orchestration/merge-poll.js

@@ -26,6 +26,11 @@ export function pollIntervalMs(checksStatus, intervalSeconds) {
 }
 export const DEFAULT_MAX_BUDGET_SECONDS = 3600;
 
+/** CI never reddens in the first minute, so only green or red polls on. */
+export function probeSettlesAsyncWait(checksStatus) {
+  return checksStatus !== 'success' && checksStatus !== 'failure';
+}
+
 /** Bounds every `gh` spawn so a hang degrades to the probe-error path. */
 export const MERGE_WAIT_GH_TIMEOUT_MS = 60_000;
 

package/.agents/scripts/lib/orchestration/plan-runner/worktree-sweep.js

@@ -1,11 +1,17 @@
 /**
- * plan-runner/worktree-sweep.js — plan-boot sweep that force-removes
+ * plan-runner/worktree-sweep.js — boot sweep that removes
  * `.worktrees/story-<id>/` entries whose Story is closed or `agent::done`,
- * after draining the pending-cleanup manifest.
+ * after draining the pending-cleanup manifest. Called by `runBootSweep`
+ * (`boot-sweep.js`) under the shared merged-branch sweep lock.
  *
- * `--force` is deliberate: a done Story's branch is already merged, so any
- * residue (dirty artifacts, an interrupted rebase, a Windows lock) is noise;
- * the `WorktreeManager.reap` safety rails are for the active close path.
+ * Removal goes through `removeWorktreeWithRecovery` — the same seam close
+ * uses: Windows lock retries, an `fs.rm` fallback that discards residue a
+ * done Story's merged branch no longer needs, and the pending-cleanup
+ * hand-off when that exhausts. Branches are never deleted here; the
+ * merged-branch sweep owns them.
+ *
+ * Two trees are never touched: an open Story's, and the one the running
+ * process was loaded from or is working in (`findRunningCodeInside`).
  */
 
 import path from 'node:path';
@@ -13,8 +19,13 @@ import * as defaultGit from '../../git-utils.js';
 import { NOOP_LOGGER } from '../../Logger.js';
 import { AGENT_LABELS } from '../../label-constants.js';
 import { concurrentMap } from '../../util/concurrent-map.js';
-import { parseWorktreePorcelain } from '../../worktree/inspector.js';
+import { canonicalPath } from '../../worktree/canonical-path.js';
+import { parseWorktreePorcelain, samePath } from '../../worktree/inspector.js';
 import { forceDrainPendingCleanup } from '../../worktree/lifecycle/force-drain.js';
+import {
+  findRunningCodeInside,
+  removeWorktreeWithRecovery,
+} from '../../worktree/lifecycle/reap.js';
 
 const TICKET_READ_CONCURRENCY = 8;
 
@@ -27,33 +38,32 @@ function isStoryDone(ticket) {
   return labels.includes(DONE_LABEL);
 }
 
-function storyIdFromPath(wtPath) {
-  const parts = wtPath.replace(/\\/g, '/').split('/');
-  const last = parts[parts.length - 1] ?? '';
-  return defaultGit.parseStoryBranch(last);
+/**
+ * The Story id of a `<worktreeRoot>/story-<id>` entry, else `null` — a
+ * `story-<id>` directory anywhere else (e.g. `.claude/worktrees/`) is not
+ * this sweep's to judge.
+ *
+ * @param {string} wtPath
+ * @param {string} worktreeRoot
+ * @param {string} platform
+ * @returns {number|null}
+ */
+function storyIdFromPath(wtPath, worktreeRoot, platform) {
+  const parent = path.dirname(canonicalPath(wtPath));
+  if (!samePath(parent, canonicalPath(worktreeRoot), platform)) return null;
+  return defaultGit.parseStoryBranch(path.basename(path.resolve(wtPath)));
 }
 
 /**
- * Never touches a worktree whose Story is still open.
+ * Validate and normalise the options bag.
  *
  * @param {object} opts
- * @param {object} opts.provider    Only `getTicket(id)` is required.
- * @param {string} opts.repoRoot    Absolute path to the main checkout.
- * @param {object} [opts.git]
- * @param {object} [opts.logger]
- * @returns {Promise<{
- *   reaped: Array<{ storyId: number, path: string }>,
- *   skipped: Array<{ storyId: number|null, path: string, reason: string }>,
- * }>}
+ * @returns {object}
  */
-export async function sweepStaleStoryWorktrees(opts = {}) {
+function resolveSweepOptions(opts) {
   const ctx = opts.ctx;
   const provider = opts.provider ?? ctx?.provider;
   const repoRoot = opts.repoRoot ?? ctx?.cwd;
-  const git = opts.git ?? defaultGit;
-  const logger = opts.logger ?? ctx?.logger ?? NOOP_LOGGER;
-  const fsRm = opts.fsRm;
-  const worktreeRoot = opts.worktreeRoot;
   if (!provider || typeof provider.getTicket !== 'function') {
     throw new Error(
       'sweepStaleStoryWorktrees: provider with getTicket(id) is required',
@@ -62,107 +72,149 @@ export async function sweepStaleStoryWorktrees(opts = {}) {
   if (!repoRoot || typeof repoRoot !== 'string') {
     throw new Error('sweepStaleStoryWorktrees: repoRoot is required');
   }
+  const platform = opts.platform ?? process.platform;
+  return {
+    provider,
+    repoRoot,
+    platform,
+    git: opts.git ?? defaultGit,
+    logger: opts.logger ?? ctx?.logger ?? NOOP_LOGGER,
+    fsRm: opts.fsRm,
+    sleepFn: opts.sleepFn,
+    worktreeRoot: path.resolve(
+      opts.worktreeRoot ?? path.join(repoRoot, '.worktrees'),
+    ),
+    guardPaths: [process.cwd(), ...(opts.runningPaths ?? [])],
+  };
+}
 
-  const resolvedWorktreeRoot =
-    worktreeRoot ?? path.join(repoRoot, '.worktrees');
+/**
+ * Read every Story worktree's ticket; each mapper captures its own error so
+ * one provider hiccup cannot abort the sweep via concurrentMap's
+ * first-rejection-wins policy.
+ */
+function readStoryTickets(entries, o) {
+  return concurrentMap(
+    entries,
+    async (entry) => {
+      const wtPath = entry.path;
+      const storyId = wtPath
+        ? storyIdFromPath(wtPath, o.worktreeRoot, o.platform)
+        : null;
+      if (storyId === null) return { kind: 'non-story' };
+      try {
+        const ticket = await o.provider.getTicket(storyId);
+        return { kind: 'ok', wtPath, storyId, ticket };
+      } catch (err) {
+        return { kind: 'provider-error', wtPath, storyId, error: err };
+      }
+    },
+    { concurrency: TICKET_READ_CONCURRENCY },
+  );
+}
+
+/**
+ * Why a read entry must be kept, or `null` when it may be removed.
+ *
+ * @returns {string|null}
+ */
+function keepReason(r, o) {
+  if (r.kind === 'provider-error') {
+    o.logger.warn(
+      `worktree-sweep: provider.getTicket(#${r.storyId}) failed: ${r.error.message}`,
+    );
+    return `provider-error: ${r.error.message}`;
+  }
+  if (!isStoryDone(r.ticket)) return 'story-open';
+  const selfPath = findRunningCodeInside(o, r.wtPath, o.guardPaths);
+  if (selfPath) {
+    o.logger.warn(
+      `worktree-sweep: skipped storyId=${r.storyId} path=${r.wtPath} — the running process uses it (${selfPath})`,
+    );
+    return 'running-from-target-tree';
+  }
+  return null;
+}
+
+async function removeOne(r, o) {
+  const ctx = {
+    repoRoot: o.repoRoot,
+    git: o.git,
+    logger: o.logger,
+    platform: o.platform,
+    worktreeRoot: o.worktreeRoot,
+    listCache: { list: null, ts: 0 },
+    fsRm: o.fsRm,
+  };
+  const res = await removeWorktreeWithRecovery(ctx, r.wtPath, {
+    storyId: r.storyId,
+    ...(o.sleepFn ? { sleepFn: o.sleepFn, retryDelay: 0 } : {}),
+  });
+  return res.removed
+    ? null
+    : `remove-failed: ${res.reason ?? 'worktree-remove-failed'}`;
+}
+
+/**
+ * Never touches a worktree whose Story is still open, nor the one the
+ * running process uses.
+ *
+ * @param {object} opts
+ * @param {object} opts.provider    Only `getTicket(id)` is required.
+ * @param {string} opts.repoRoot    Absolute path to the main checkout.
+ * @param {object} [opts.git]
+ * @param {object} [opts.logger]
+ * @param {string[]} [opts.runningPaths] Extra paths the running process owns.
+ * @returns {Promise<{
+ *   reaped: Array<{ storyId: number, path: string }>,
+ *   skipped: Array<{ storyId: number|null, path: string, reason: string }>,
+ * }>}
+ */
+export async function sweepStaleStoryWorktrees(opts = {}) {
+  const o = resolveSweepOptions(opts);
 
   // Drain the pending-cleanup manifest first so entries whose Windows locks
   // have released self-heal instead of accumulating.
   const drainResult = await forceDrainPendingCleanup({
-    repoRoot,
-    worktreeRoot: resolvedWorktreeRoot,
-    git,
-    fsRm,
-    logger,
+    repoRoot: o.repoRoot,
+    worktreeRoot: o.worktreeRoot,
+    git: o.git,
+    fsRm: o.fsRm,
+    logger: o.logger,
   });
 
   const reaped = [];
   const skipped = [];
 
-  const listRes = git.gitSpawn(repoRoot, 'worktree', 'list', '--porcelain');
+  const listRes = o.git.gitSpawn(o.repoRoot, 'worktree', 'list', '--porcelain');
   if (listRes.status !== 0) {
-    logger.warn(
+    o.logger.warn(
       `worktree-sweep: git worktree list failed: ${listRes.stderr || listRes.stdout || 'unknown'}`,
     );
     return { reaped, skipped };
   }
 
-  const entries = parseWorktreePorcelain(listRes.stdout || '');
-
-  // Each mapper captures its own error so one provider hiccup cannot abort
-  // the sweep via concurrentMap's first-rejection-wins policy.
-  const reads = await concurrentMap(
-    entries,
-    async (entry) => {
-      const wtPath = entry.path;
-      if (!wtPath) return { kind: 'no-path' };
-      const storyId = storyIdFromPath(wtPath);
-      if (storyId === null) return { kind: 'non-story' };
-      try {
-        const ticket = await provider.getTicket(storyId);
-        return { kind: 'ok', wtPath, storyId, ticket };
-      } catch (err) {
-        return { kind: 'provider-error', wtPath, storyId, error: err };
-      }
-    },
-    { concurrency: TICKET_READ_CONCURRENCY },
+  const reads = await readStoryTickets(
+    parseWorktreePorcelain(listRes.stdout || ''),
+    o,
   );
 
   // Removes stay sequential: they mutate .git/worktrees/, and racing git's
   // locking on Windows can leave a partial admin dir the next remove trips on.
   for (const r of reads) {
-    if (r.kind === 'no-path' || r.kind === 'non-story') continue;
-    if (r.kind === 'provider-error') {
-      skipped.push({
-        storyId: r.storyId,
-        path: r.wtPath,
-        reason: `provider-error: ${r.error.message}`,
-      });
-      logger.warn(
-        `worktree-sweep: provider.getTicket(#${r.storyId}) failed: ${r.error.message}`,
-      );
-      continue;
-    }
-
-    if (!isStoryDone(r.ticket)) {
-      skipped.push({
-        storyId: r.storyId,
-        path: r.wtPath,
-        reason: 'story-open',
-      });
-      continue;
-    }
-
-    const res = git.gitSpawn(
-      repoRoot,
-      'worktree',
-      'remove',
-      '--force',
-      r.wtPath,
-    );
-    if (res.status !== 0) {
-      const reason = (
-        res.stderr ||
-        res.stdout ||
-        'worktree-remove-failed'
-      ).trim();
-      skipped.push({
-        storyId: r.storyId,
-        path: r.wtPath,
-        reason: `remove-failed: ${reason}`,
-      });
-      logger.warn(
-        `worktree-sweep: failed to reap storyId=${r.storyId} path=${r.wtPath}: ${reason}`,
-      );
+    if (r.kind === 'non-story') continue;
+    const reason = keepReason(r, o) ?? (await removeOne(r, o));
+    if (reason) {
+      skipped.push({ storyId: r.storyId, path: r.wtPath, reason });
       continue;
     }
     reaped.push({ storyId: r.storyId, path: r.wtPath });
-    logger.info(
+    o.logger.info(
       `worktree-sweep: reaped stale worktree storyId=${r.storyId} path=${r.wtPath}`,
     );
   }
 
-  git.gitSpawn(repoRoot, 'worktree', 'prune');
+  o.git.gitSpawn(o.repoRoot, 'worktree', 'prune');
 
   return {
     reaped,

package/.agents/scripts/lib/orchestration/review-deposit.js

@@ -0,0 +1,219 @@
+/**
+ * review-deposit.js — the held Story-scope review a worker computes at push
+ * time, and its identity.
+ *
+ * The identity is the **diff digest**: a sha256 of the exact
+ * `git diff --no-color <base>...<head>` text the review provider is handed.
+ * A clean base-sync merge moves HEAD without changing that text, while any
+ * commit that changes the diff changes it — so close adopts a deposit, and
+ * posts a held result, on digest equality, never on SHA equality.
+ *
+ * The file lives beside the terminal envelope; nothing deletes it but the
+ * Story temp purge. A mismatched deposit is simply not adopted.
+ */
+
+import { createHash } from 'node:crypto';
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+import { storyReviewDepositPath } from '../config/temp-paths.js';
+import { resolveSharedBaseRef } from './review-base-ref.js';
+
+const DEPOSIT_KIND = 'story-review-deposit';
+
+/**
+ * @param {{ cwd: string, ref: string, gitSpawnFn: Function }} args
+ * @returns {string|null} the commit `ref` points at.
+ */
+export function resolveRefSha({ cwd, ref, gitSpawnFn }) {
+  try {
+    const probe = gitSpawnFn(
+      cwd,
+      'rev-parse',
+      '--verify',
+      '--quiet',
+      `${ref}^{commit}`,
+    );
+    const sha = probe?.status === 0 ? String(probe.stdout ?? '').trim() : '';
+    return sha.length > 0 ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * sha256 of the three-dot diff text, spawned exactly as the review provider
+ * spawns it. `null` when the diff cannot be read — an unknown identity that
+ * never matches anything.
+ *
+ * @param {{ cwd: string, baseRef: string|null, headRef: string|null,
+ *   gitSpawnFn: Function }} args
+ * @returns {string|null}
+ */
+export function computeReviewDiffDigest({ cwd, baseRef, headRef, gitSpawnFn }) {
+  if (!baseRef || !headRef) return null;
+  try {
+    const diff = gitSpawnFn(
+      cwd,
+      'diff',
+      '--no-color',
+      `${baseRef}...${headRef}`,
+    );
+    if (diff?.status !== 0) return null;
+    return createHash('sha256')
+      .update(String(diff.stdout ?? ''), 'utf8')
+      .digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Flatten a computed review `result` into the deposit record.
+ *
+ * @param {{ storyId: number, headSha: string, baseRef: string,
+ *   diffDigest: string, result: object, createdAt?: string }} args
+ * @returns {object}
+ */
+export function buildReviewDeposit({
+  storyId,
+  headSha,
+  baseRef,
+  diffDigest,
+  result,
+  createdAt = new Date().toISOString(),
+}) {
+  return {
+    kind: DEPOSIT_KIND,
+    storyId,
+    headSha,
+    baseRef,
+    diffDigest,
+    createdAt,
+    provider: result.providerName ?? null,
+    severity: result.severity,
+    halted: !!result.halted,
+    criticalByProvider: result.criticalByProvider ?? {},
+    findings: Array.isArray(result.findings) ? result.findings : [],
+    report: result.report ?? '',
+    degraded: !!result.degraded,
+    degradations: Array.isArray(result.degradations) ? result.degradations : [],
+    blockerReason: result.blockerReason ?? null,
+  };
+}
+
+/**
+ * The deposit as `computeStoryScopeReview`'s `{ result }` shape, ready for
+ * `settleStoryScopeReview` to post.
+ *
+ * @param {object} deposit
+ * @returns {{ result: object }}
+ */
+export function depositAsComputedReview(deposit) {
+  return {
+    result: {
+      status: 'ok',
+      severity: deposit.severity,
+      findings: deposit.findings,
+      providerName: deposit.provider,
+      report: deposit.report,
+      posted: false,
+      postedCommentId: null,
+      halted: deposit.halted,
+      criticalByProvider: deposit.criticalByProvider,
+      degraded: deposit.degraded,
+      degradations: deposit.degradations,
+      blockerReason: deposit.blockerReason,
+    },
+  };
+}
+
+/**
+ * Atomic write (pid-scoped tmp + rename): close may read it mid-write.
+ *
+ * @param {object} deposit
+ * @param {{ config?: object, fsImpl?: typeof nodeFs }} [deps]
+ * @returns {string} the path written.
+ */
+export function writeReviewDeposit(deposit, { config, fsImpl = nodeFs } = {}) {
+  const target = storyReviewDepositPath(deposit.storyId, config);
+  fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+  const tmpPath = `${target}.${process.pid}.tmp`;
+  fsImpl.writeFileSync(
+    tmpPath,
+    `${JSON.stringify(deposit, null, 2)}\n`,
+    'utf8',
+  );
+  fsImpl.renameSync(tmpPath, target);
+  return target;
+}
+
+/**
+ * @param {unknown} record
+ * @param {number} storyId
+ * @returns {boolean}
+ */
+function isDeposit(record, storyId) {
+  return (
+    record?.kind === DEPOSIT_KIND &&
+    record.storyId === storyId &&
+    typeof record.diffDigest === 'string' &&
+    record.diffDigest.length > 0 &&
+    typeof record.report === 'string' &&
+    typeof record.severity === 'object' &&
+    record.severity !== null
+  );
+}
+
+/**
+ * @param {number} storyId
+ * @param {{ config?: object, fsImpl?: typeof nodeFs }} [deps]
+ * @returns {object|null} the Story's deposit, or `null` when absent or
+ *   malformed.
+ */
+function readReviewDeposit(storyId, { config, fsImpl = nodeFs } = {}) {
+  try {
+    const raw = fsImpl.readFileSync(
+      storyReviewDepositPath(storyId, config),
+      'utf8',
+    );
+    const record = JSON.parse(raw);
+    return isDeposit(record, storyId) ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Close's held-review start point: the base ref, the diff digest of
+ * `origin/<base>...<sha>`, and the worker deposit when its digest matches.
+ *
+ * @param {{ cwd: string, storyId: number|string, sha: string,
+ *   baseBranch: string, gitSpawnFn: Function, config?: object,
+ *   readDepositFn?: typeof readReviewDeposit }} args
+ * @returns {{ baseRef: string|null, diffDigest: string|null,
+ *   deposit: object|null }}
+ */
+export function probeHeldReviewDiff({
+  cwd,
+  storyId,
+  sha,
+  baseBranch,
+  gitSpawnFn,
+  config,
+  readDepositFn = readReviewDeposit,
+}) {
+  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
+  const baseRef = base.resolved ? base.ref : null;
+  const diffDigest = computeReviewDiffDigest({
+    cwd,
+    baseRef,
+    headRef: sha,
+    gitSpawnFn,
+  });
+  const deposit = diffDigest
+    ? readDepositFn(Number(storyId), { config })
+    : null;
+  const matches = deposit?.diffDigest === diffDigest;
+  return { baseRef, diffDigest, deposit: matches ? deposit : null };
+}

package/.agents/scripts/lib/orchestration/review-providers/code-review.js

@@ -15,7 +15,7 @@
  * @typedef {import('./types.js').ReviewProvider} ReviewProvider
  */
 
-import { spawnCapture } from '../../child-exec.js';
+import { spawnCaptureAsync } from '../../child-exec.js';
 import { gitSpawn } from '../../git-utils.js';
 import { PROJECT_ROOT } from '../../project-root.js';
 import { parseProviderFindings } from './parse-findings.js';
@@ -62,14 +62,15 @@ function buildPrompt(input, diff) {
 }
 
 /**
- * The prompt rides stdin so no shell ever quotes it.
+ * The prompt rides stdin so no shell ever quotes it. Asynchronous: the
+ * review overlaps close's gate children, whose output must keep draining.
  *
  * @param {string} prompt
- * @param {Function} [run] - `spawnSync`-shaped seam for tests.
- * @returns {{ status: number, stdout: string, stderr: string }}
+ * @param {Function} [run] - `(file, args, options)` seam for tests.
+ * @returns {Promise<{ status: number, stdout: string, stderr: string }>}
  */
 function invokeClaude(prompt, run) {
-  return spawnCapture('claude', [...CLAUDE_ARGS], {
+  return spawnCaptureAsync('claude', [...CLAUDE_ARGS], {
     cwd: PROJECT_ROOT,
     input: prompt,
     shell: process.platform === 'win32',
@@ -144,7 +145,7 @@ function assertInput(input) {
  *   gitSpawnFn?: typeof gitSpawn,
  *   spawnFn?: Function,
  *   logger?: { info?: Function, warn?: Function },
- * }} [deps] - `spawnFn` replaces `spawnSync` for the `claude` call.
+ * }} [deps] - `spawnFn` replaces the async runner for the `claude` call.
  * @returns {ReviewProvider}
  */
 export function createCodeReviewProviderForRegistry(deps = {}) {
@@ -183,7 +184,10 @@ export function createCodeReviewProviderForRegistry(deps = {}) {
       logger?.info?.(
         `[code-review] Invoking claude --print --effort low for Story #${ticketId} (${baseRef}...${headRef})...`,
       );
-      const result = invokeClaude(buildPrompt(input, diff.stdout), spawnFn);
+      const result = await invokeClaude(
+        buildPrompt(input, diff.stdout),
+        spawnFn,
+      );
       if (result.status !== 0) {
         logger?.warn?.(
           `[code-review] claude exited ${result.status}; emitting advisory.`,