mandrel 2.66.0 → 2.68.0

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -12,12 +12,14 @@ import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-va
 import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
 import { LOCK_WAIT_EXPIRED_EXIT_CODE } from '../../../full-suite-lock.js';
 import { parseLockWaitOutcome } from '../../../full-suite-queue.js';
+import { parseSuiteTimings } from '../../../supervised-suite.js';
 import { createGateLogSink as defaultCreateGateLogSink } from '../gate-log.js';
 import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
 
 /**
  * Pre-gate self-heal steps, then the gates (throws on first failure). The
  * steps commit in the worktree before scoring, so the gates see their output.
+ * `onPreGateStepsDone` (must not throw) runs once the tree is final.
  *
  * @param {{
  *   cwd: string,
@@ -34,10 +36,12 @@ import { runPreGateSteps as defaultRunPreGateSteps } from './pre-gate-steps.js';
  *   runBaselineUpwardWriteback?: Function,
  *   runContextBudgetWriteback?: Function,
  *   createGateLogSink?: typeof defaultCreateGateLogSink,
+ *   onPreGateStepsDone?: () => void,
  * }} args
  * @returns {Promise<{
  *   gates: Record<string, 'passed'|'skipped'>|null,
- *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   lockWait: { waitedSeconds: number, expired: boolean, holder?: object }|null,
+ *   suiteTimings: { lockWaitMs: number, hostWaitMs: number|null, testRunMs: number }|null,
  *   pending: boolean,
  * }>} `pending` (with `gates: null`) when a lock wait expired; any other
  *   failure throws with `err.closeGate` naming the gate.
@@ -57,6 +61,7 @@ export async function runCloseValidationPhase({
   runBaselineUpwardWriteback,
   runContextBudgetWriteback,
   createGateLogSink = defaultCreateGateLogSink,
+  onPreGateStepsDone,
 }) {
   await runPreGateSteps({
     cwd,
@@ -70,6 +75,7 @@ export async function runCloseValidationPhase({
     runBaselineUpwardWriteback,
     runContextBudgetWriteback,
   });
+  onPreGateStepsDone?.();
 
   progress(
     'VALIDATE',
@@ -101,7 +107,6 @@ export async function runCloseValidationPhase({
       baseBranch,
       storyBranch,
       config,
-      deferOnLockExpiry: true,
     });
   } finally {
     // The sink is async-buffered; settle it before anything reads it, on
@@ -116,6 +121,7 @@ export async function runCloseValidationPhase({
   return {
     gates: gateOutcomes(gateList, validation),
     lockWait,
+    suiteTimings: lockWaits.suiteTimings(),
     pending: false,
   };
 }
@@ -129,7 +135,7 @@ export async function runCloseValidationPhase({
  *   gateLog: { replay: () => void },
  *   progress: (tag: string, msg: string) => void,
  * }} args
- * @returns {{ gates: null, lockWait: object, pending: true }}
+ * @returns {{ gates: null, lockWait: object, suiteTimings: null, pending: true }}
  */
 function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
   const [first] = validation.failed;
@@ -139,7 +145,7 @@ function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
       'VALIDATE',
       `⏸ ${gate.name} deferred: the full-suite lock wait expired after ${lockWait.waitedSeconds}s. Nothing was spawned; close will report pending.`,
     );
-    return { gates: null, lockWait, pending: true };
+    return { gates: null, lockWait, suiteTimings: null, pending: true };
   }
   gateLog.replay();
   const err = new Error(
@@ -151,27 +157,40 @@ function settleFailedValidation({ validation, lockWait, gateLog, progress }) {
 }
 
 /**
- * Parsed from the gate log because it is the one place that sees waits both
+ * Parsed from the gate log: the one place that sees waits and timings both
  * in-process and in gate children.
  *
  * @param {{ sink: (m: string) => void, progress: (tag: string, msg: string) => void }} args
- * @returns {{ log: (m: string) => void, summary: () => { waitedSeconds: number, expired: boolean }|null }}
+ * @returns {{ log: (m: string) => void, summary: () => { waitedSeconds: number, expired: boolean, holder?: object }|null, suiteTimings: () => object|null }}
  */
 function trackLockWaits({ sink, progress }) {
   let tally = null;
+  let timings = null;
   return {
     log(line) {
       sink(line);
+      timings = parseSuiteTimings(line) ?? timings;
       if (!String(line).includes('[full-suite-lock]')) return;
       progress('LOCK', line);
       const outcome = parseLockWaitOutcome(line);
       if (!outcome) return;
-      tally = {
-        waitedSeconds: (tally?.waitedSeconds ?? 0) + outcome.waitedSeconds,
-        expired: Boolean(tally?.expired) || outcome.expired,
-      };
+      tally = mergeLockWait(tally, outcome);
     },
     summary: () => tally,
+    suiteTimings: () => timings,
+  };
+}
+
+/**
+ * @param {{ waitedSeconds: number, expired: boolean, holder?: object }|null} tally
+ * @param {{ waitedSeconds: number, expired: boolean, holder?: object }} outcome
+ */
+function mergeLockWait(tally, outcome) {
+  const holder = outcome.holder ?? tally?.holder;
+  return {
+    waitedSeconds: (tally?.waitedSeconds ?? 0) + outcome.waitedSeconds,
+    expired: Boolean(tally?.expired) || outcome.expired,
+    ...(holder ? { holder } : {}),
   };
 }
 

package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js

@@ -49,29 +49,6 @@ export function buildStoryReviewCrossRefBody({
   );
 }
 
-async function invokeStoryReviewCore({
-  storyId,
-  storyBranch,
-  baseRef,
-  prNumber,
-  provider,
-  runCodeReviewFn,
-  gitSpawnFn,
-  progress,
-}) {
-  return runStoryReviewCore({
-    storyId,
-    baseRef,
-    headRef: storyBranch,
-    commentTargetId: prNumber,
-    provider,
-    progress,
-    progressTag: 'REVIEW',
-    runCodeReviewFn,
-    gitSpawnFn,
-  });
-}
-
 async function postStoryReviewCrossRef({
   provider,
   storyId,
@@ -115,7 +92,122 @@ async function postStoryReviewCrossRef({
 }
 
 /**
- * Skips on an unparseable PR number or an unresolvable base (recording a
+ * Run the review against `headRef`; `deferPost` holds the report unposted.
+ *
+ * @returns {Promise<{ outcome: object }|{ result: object }>} a final
+ *   `outcome` (unresolvable base), or the `result` to settle.
+ */
+export async function computeStoryScopeReview({
+  cwd,
+  storyId,
+  headRef,
+  baseBranch,
+  commentTargetId = null,
+  deferPost = false,
+  provider,
+  runCodeReviewFn,
+  gitSpawnFn,
+  progress,
+}) {
+  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
+  if (!base.resolved) {
+    return {
+      outcome: unresolvedBaseReviewOutcome({
+        storyId,
+        baseBranch,
+        remoteRef: base.remoteRef,
+        progress,
+      }),
+    };
+  }
+  const target = deferPost
+    ? 'held until the PR exists'
+    : `→ PR #${commentTargetId}`;
+  progress(
+    'REVIEW',
+    `Running Story-scope code review for Story #${storyId} (${base.ref}...${headRef}) ${target}...`,
+  );
+  const result = await runStoryReviewCore({
+    storyId,
+    baseRef: base.ref,
+    headRef,
+    commentTargetId,
+    provider,
+    progress,
+    progressTag: 'REVIEW',
+    runCodeReviewFn: deferPost
+      ? (opts) => runCodeReviewFn({ ...opts, deferPost: true })
+      : runCodeReviewFn,
+    gitSpawnFn,
+  });
+  return { result };
+}
+
+/**
+ * Settle a computed review on the PR: post a held report via `postReportFn`,
+ * report the tally, cross-reference the Story.
+ *
+ * @returns {Promise<object>} the review outcome.
+ */
+export async function settleStoryScopeReview({
+  computed,
+  storyId,
+  prUrl,
+  prNumber,
+  provider,
+  progress,
+  postReportFn = null,
+}) {
+  if (computed.outcome) return computed.outcome;
+  const posting = postReportFn
+    ? await postReportFn({
+        provider,
+        commentTargetId: prNumber,
+        report: computed.result.report,
+        logger: {
+          info: (m) => progress('REVIEW', m),
+          warn: (m) => progress('REVIEW', `⚠️ ${m}`),
+        },
+      })
+    : {};
+  const result = { ...computed.result, ...posting };
+  const sev = result.severity ?? {
+    critical: 0,
+    high: 0,
+    medium: 0,
+    suggestion: 0,
+  };
+  const outcome = formatReviewOutcomeLines({
+    severity: sev,
+    degradations: result.degradations,
+    prNumber,
+    posted: result.posted,
+  });
+  for (const line of outcome) progress('REVIEW', line);
+
+  const crossRefPosted = await postStoryReviewCrossRef({
+    provider,
+    storyId,
+    prUrl,
+    prNumber,
+    result,
+    severity: sev,
+    progress,
+  });
+
+  return {
+    halted: !!result.halted,
+    severity: sev,
+    criticalByProvider: result.criticalByProvider,
+    posted: result.posted,
+    postedCommentId: result.postedCommentId ?? null,
+    ...degradationEnvelope(result.degradations),
+    crossRefPosted,
+  };
+}
+
+/**
+ * The serial review, posting to the PR. Skips on an unparseable PR number or an unresolvable base (recording a
  * degradation); a runner throw propagates and fails the close.
  *
  * @param {{
@@ -161,64 +253,23 @@ export async function runStoryScopeReview({
     );
     return { halted: false, skipped: true };
   }
-
-  const base = resolveSharedBaseRef({ baseBranch, cwd, gitSpawnFn });
-  if (!base.resolved) {
-    return unresolvedBaseReviewOutcome({
-      storyId,
-      baseBranch,
-      remoteRef: base.remoteRef,
-      progress,
-    });
-  }
-
-  progress(
-    'REVIEW',
-    `Running Story-scope code review for Story #${storyId} (${base.ref}...${storyBranch}) → PR #${prNumber}...`,
-  );
-
-  const result = await invokeStoryReviewCore({
+  const computed = await computeStoryScopeReview({
+    cwd,
     storyId,
-    storyBranch,
-    baseRef: base.ref,
-    prNumber,
+    headRef: storyBranch,
+    baseBranch,
+    commentTargetId: prNumber,
     provider,
     runCodeReviewFn,
     gitSpawnFn,
     progress,
   });
-
-  const sev = result.severity ?? {
-    critical: 0,
-    high: 0,
-    medium: 0,
-    suggestion: 0,
-  };
-  const outcome = formatReviewOutcomeLines({
-    severity: sev,
-    degradations: result.degradations,
-    prNumber,
-    posted: result.posted,
-  });
-  for (const line of outcome) progress('REVIEW', line);
-
-  const crossRefPosted = await postStoryReviewCrossRef({
-    provider,
+  return settleStoryScopeReview({
+    computed,
     storyId,
     prUrl,
     prNumber,
-    result,
-    severity: sev,
+    provider,
     progress,
   });
-
-  return {
-    halted: !!result.halted,
-    severity: sev,
-    criticalByProvider: result.criticalByProvider,
-    posted: result.posted,
-    postedCommentId: result.postedCommentId ?? null,
-    ...degradationEnvelope(result.degradations),
-    crossRefPosted,
-  };
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js

@@ -7,8 +7,8 @@
  * resumable `pending` with no mutation; `maxBudgetSeconds` bounds the
  * cumulative wait, anchored at the PR's `createdAt` so resumes don't restart
  * it, and exhausting it is the real give-up (classify, emit, block). The
- * poll is stateless and re-entrant. Async mode only shortens the
- * per-invocation window. Checks are probed every iteration so a red required
+ * poll is stateless and re-entrant. Async mode probes once (see
+ * ASYNC_PROBE_WINDOW_SECONDS). Checks are probed every iteration so a red required
  * check fails fast instead of burning the budget.
  *
  * Terminals: `landed` (confirmed, post-land tail ran); `pending` (nothing
@@ -48,6 +48,7 @@ import {
   MERGE_WAIT_GH_TIMEOUT_MS,
   parseWorkflowRunId,
   pollIntervalMs,
+  probeSettlesAsyncWait,
   readRunSummary,
   resolveAdvisoryGateVerdict,
 } from '../../merge-poll.js';
@@ -65,7 +66,7 @@ import { runPostLandTail as defaultRunPostLandTail } from './post-land.js';
 /** Per-invocation bound; fits the host's ~10-min tool ceiling after the gates. */
 export const DEFAULT_MAX_WAIT_SECONDS = 300;
 
-/** Async-mode per-invocation cap: long enough to catch an instant merge or red check. */
+/** Async cap; only a green or red first probe polls on inside it. */
 export const ASYNC_PROBE_WINDOW_SECONDS = 60;
 
 export const DEFAULT_UPDATE_ATTEMPTS = 3;
@@ -223,7 +224,7 @@ export async function readPrWaitProbe({
  * @param {object} [config]
  * @param {number} [maxWaitSecondsOverride]
  * @param {'sync'|'async'} [modeOverride]
- * @returns {{ mode: 'sync'|'async', intervalSeconds: number, maxWaitSeconds: number, maxBudgetSeconds: number, updateAttempts: number }}
+ * @returns {{ mode: 'sync'|'async', singleProbe: boolean, intervalSeconds: number, maxWaitSeconds: number, maxBudgetSeconds: number, updateAttempts: number }}
  */
 export function resolveMergeWaitConfig(
   config,
@@ -239,15 +240,16 @@ export function resolveMergeWaitConfig(
     maxWaitSecondsOverride,
     int(mergeWatch.maxWaitSeconds, DEFAULT_MAX_WAIT_SECONDS),
   );
-  const maxWaitSeconds =
-    mode === 'async' && maxWaitSecondsOverride == null
-      ? Math.min(configuredMaxWait, ASYNC_PROBE_WINDOW_SECONDS)
-      : configuredMaxWait;
+  const singleProbe = mode === 'async' && maxWaitSecondsOverride == null;
+  const maxWaitSeconds = singleProbe
+    ? Math.min(configuredMaxWait, ASYNC_PROBE_WINDOW_SECONDS)
+    : configuredMaxWait;
   // An interval longer than the bound would expire every invocation on poll
   // 1, so MIN_POLLS_BEFORE_BUDGET_BLOCK and the budget could never be reached.
   const intervalSeconds = Math.min(DEFAULT_INTERVAL_SECONDS, maxWaitSeconds);
   return {
     mode,
+    singleProbe,
     intervalSeconds,
     maxWaitSeconds,
     maxBudgetSeconds: int(
@@ -1015,25 +1017,30 @@ export function createMergeWaitState({ startedAtMs, intervalSeconds }) {
   };
 }
 
-/** Budget first — it is the real give-up. */
+/** Budget first — it is the real give-up; the single probe yields to it. */
 function provisionalVerdict(
   { polls, intervalMs, waitedMs, cumulativeMs },
   limits,
+  checksStatus,
 ) {
-  if (
-    polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK &&
-    cumulativeMs + intervalMs > limits.maxBudgetSeconds * 1000
-  ) {
+  const overBudget = cumulativeMs + intervalMs > limits.maxBudgetSeconds * 1000;
+  if (polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK && overBudget) {
     return 'budget-exhausted';
   }
   if (waitedMs + intervalMs > limits.maxWaitSeconds * 1000) return 'wait-bound';
-  return 'continue';
+  return singleProbeOrContinue(limits, overBudget, checksStatus);
+}
+
+function singleProbeOrContinue(limits, overBudget, checksStatus) {
+  const settles =
+    limits.singleProbe && !overBudget && probeSettlesAsyncWait(checksStatus);
+  return settles ? 'single-probe' : 'continue';
 }
 
 /**
  * Pure: state + probe + clock → next state and verdict. `merged`, `closed`
- * and `checks-failed` are definitive; `budget-exhausted`, `wait-bound` and
- * `continue` hold only if the loop's advisory check does not block first.
+ * and `checks-failed` are definitive; `budget-exhausted`, `wait-bound`,
+ * `single-probe` and `continue` hold only if the loop's advisory check does not block first.
  * The two clock reads (wait bound, then budget) keep a stepping test clock's
  * call sequence.
  *
@@ -1090,7 +1097,11 @@ export function decideMergeWaitPoll({
   }
   return {
     state: next,
-    verdict: provisionalVerdict({ ...next, waitedMs, cumulativeMs }, limits),
+    verdict: provisionalVerdict(
+      { ...next, waitedMs, cumulativeMs },
+      limits,
+      probe.checksStatus,
+    ),
     ...timing,
   };
 }
@@ -1158,13 +1169,20 @@ const DEFINITIVE_SETTLERS = Object.freeze({
   'checks-failed': settleChecksFailed,
 });
 
-/** Invocation bound reached: resumable `pending`, no mutation. */
+/** The verdicts that settle a resumable `pending`, keyed to their headline. */
+const PENDING_HEADLINES = Object.freeze({
+  'wait-bound': 'Merge wait bound reached',
+  'single-probe': 'Async single probe settled',
+});
+
+/** Invocation bound or single probe: resumable `pending`, no mutation. */
 function pendingAtWaitBound(ctx, decision, probe) {
   const { waitBudget } = decision;
   const checks = probe.checksStatus ?? 'unknown';
+  const why = PENDING_HEADLINES[decision.verdict];
   ctx.progress?.(
     'CONFIRM',
-    `⏸  Merge wait bound reached (${waitBudget.waitedSeconds}s of ${waitBudget.maxWaitSeconds}s this invocation; ` +
+    `⏸  ${why} (${waitBudget.waitedSeconds}s of ${waitBudget.maxWaitSeconds}s this invocation; ` +
       `${waitBudget.cumulativeSeconds}s of ${waitBudget.maxBudgetSeconds}s cumulative). PR #${ctx.prNumber} still in flight ` +
       `(checks=${checks}). Story stays at agent::closing — resumable.`,
   );
@@ -1223,7 +1241,7 @@ async function settleProvisional(ctx, decision, probe) {
     });
     return { state, outcome };
   }
-  if (decision.verdict === 'wait-bound') {
+  if (Object.hasOwn(PENDING_HEADLINES, decision.verdict)) {
     return { state, outcome: pendingAtWaitBound(ctx, decision, probe) };
   }
   return { state, outcome: null };

package/.agents/scripts/lib/orchestration/single-story-close/phases/lock-wait-pending.js

@@ -13,7 +13,7 @@ import {
  *   storyId: number,
  *   storyBranch: string,
  *   baseBranch: string,
- *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   lockWait: { waitedSeconds: number, expired: boolean, holder?: object }|null,
  *   elapsedSeconds: number,
  * }} args
  * @returns {{ result: object, terminal: object, note: string }} The close
@@ -44,6 +44,12 @@ export function lockWaitPending({
       nextCommand,
       elapsedSeconds,
     }),
-    note: `⏸  Story #${storyId}: another full suite held the host lock past the wait budget — resume with: ${nextCommand}`,
+    note: `⏸  Story #${storyId}: another full suite${describeHolder(lockWait?.holder)} held the host lock past the wait budget — resume with: ${nextCommand}`,
   };
 }
+
+/** @param {{ ownerId: string|null, pid: number|null, ageSeconds: number|null }} [holder] */
+function describeHolder(holder) {
+  if (!holder) return '';
+  return ` (${holder.ownerId ?? 'unknown owner'}, pid ${holder.pid ?? 'unknown'}, lock age ${holder.ageSeconds ?? 'unknown'}s)`;
+}

package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js

@@ -0,0 +1,161 @@
+/**
+ * The Story-scope review, overlapped with the close-validation gates: started
+ * once the pre-gate self-heal commits land and held (computed, never posted)
+ * until the PR exists. A worker deposit whose diff digest matches the diff at
+ * that point **is** the held result, so nothing is computed. After PR-open a
+ * pushed diff with a different digest discards it for a serial review — a
+ * clean base-sync merge moves HEAD without changing the digest. The held
+ * promise never rejects, so an abandoned review leaves no unhandled rejection.
+ */
+
+import { postReviewComment } from '../code-review.js';
+import {
+  computeReviewDiffDigest,
+  depositAsComputedReview,
+  probeHeldReviewDiff,
+  resolveRefSha,
+} from '../review-deposit.js';
+import { upsertStructuredComment } from '../ticketing.js';
+import {
+  computeStoryScopeReview,
+  runStoryScopeReview,
+  settleStoryScopeReview,
+} from './phases/code-review.js';
+
+/** @typedef {{ sha: string, baseRef: string|null, diffDigest: string|null, adopted: boolean, startedAtMs: number, settled: Promise<object> }} HeldReview */
+
+/** @returns {string|null} the commit `storyBranch` points at. */
+function resolveBranchSha({ cwd, storyBranch, gitSpawnFn }) {
+  return resolveRefSha({ cwd, ref: storyBranch, gitSpawnFn });
+}
+
+/** A held result already in hand: the worker deposit. */
+function adoptedSettlement(deposit, atMs) {
+  const value = depositAsComputedReview(deposit);
+  return Promise.resolve({ ok: true, value, endedAtMs: atMs });
+}
+
+/** Compute the review of `sha`, held unposted; never rejects. */
+function computeHeldReview({ sha, nowMs, ...args }) {
+  return computeStoryScopeReview({
+    ...args,
+    headRef: sha,
+    deferPost: true,
+  }).then(
+    (value) => ({ ok: true, value, endedAtMs: nowMs() }),
+    (error) => ({ ok: false, error, endedAtMs: nowMs() }),
+  );
+}
+
+/**
+ * @param {{ cwd: string, storyId: number, storyBranch: string,
+ *   baseBranch: string, provider: object, runCodeReviewFn: Function,
+ *   gitSpawnFn: Function, progress: Function, config?: object,
+ *   readDepositFn?: Function, nowMs?: () => number }} args
+ * @returns {HeldReview|null} null when the SHA is unresolvable.
+ */
+export function startHeldReview(args) {
+  const { cwd, storyBranch, gitSpawnFn, progress, nowMs = Date.now } = args;
+  const sha = resolveBranchSha({ cwd, storyBranch, gitSpawnFn });
+  if (!sha) {
+    progress(
+      'REVIEW',
+      `⏭ Could not resolve ${storyBranch}; the Story-scope review runs after PR-open.`,
+    );
+    return null;
+  }
+  const { baseRef, diffDigest, deposit } = probeHeldReviewDiff({
+    ...args,
+    sha,
+  });
+  const startedAtMs = nowMs();
+  const held = { sha, baseRef, diffDigest, adopted: !!deposit, startedAtMs };
+  if (deposit) {
+    progress('REVIEW', `♻️ Adopting the worker's held review; none computed.`);
+    return { ...held, settled: adoptedSettlement(deposit, startedAtMs) };
+  }
+  const settled = computeHeldReview({ ...args, sha, nowMs });
+  return { ...held, settled };
+}
+
+/** Drop a held review unposted. */
+export function discardHeldReview(held, reason, progress) {
+  if (!held) return;
+  progress('REVIEW', `🗑  Held Story-scope review discarded (${reason}).`);
+}
+
+/** Post the held review; records compute + post time, never the idle gap. */
+async function postHeldReview(held, args) {
+  const { recordDuration, nowMs = Date.now, postReportFn } = args;
+  const settledReview = await held.settled;
+  const computeMs = settledReview.endedAtMs - held.startedAtMs;
+  if (!settledReview.ok) {
+    recordDuration('code-review', computeMs);
+    throw settledReview.error;
+  }
+  const postStartedAtMs = nowMs();
+  try {
+    return await settleStoryScopeReview({
+      computed: settledReview.value,
+      storyId: args.storyId,
+      prUrl: args.prUrl,
+      prNumber: args.prNumber,
+      provider: args.provider,
+      progress: args.progress,
+      postReportFn:
+        postReportFn ??
+        ((post) =>
+          postReviewComment({
+            ...post,
+            upsertCommentFn: upsertStructuredComment,
+          })),
+    });
+  } finally {
+    recordDuration('code-review', computeMs + (nowMs() - postStartedAtMs));
+  }
+}
+
+/**
+ * Post a held review whose diff digest matches the pushed diff (phase
+ * untimed: it records its own wall time), else run the serial review.
+ *
+ * @returns {Promise<object>} the review outcome.
+ */
+export async function reviewAfterPrOpen(args) {
+  const { held, setPhase, progress } = args;
+  if (held && args.prNumber != null) {
+    const pushedDigest = computeReviewDiffDigest({
+      cwd: args.cwd,
+      baseRef: held.baseRef,
+      headRef: resolveBranchSha(args),
+      gitSpawnFn: args.gitSpawnFn,
+    });
+    if (pushedDigest !== null && pushedDigest === held.diffDigest) {
+      setPhase('code-review');
+      args.pauseTimer();
+      progress(
+        'REVIEW',
+        `Posting the held Story-scope review → PR #${args.prNumber}...`,
+      );
+      return await postHeldReview(held, args);
+    }
+    discardHeldReview(
+      held,
+      'the pushed diff is not the reviewed diff; re-running serially',
+      progress,
+    );
+  }
+  setPhase('code-review');
+  return await runStoryScopeReview({
+    cwd: args.cwd,
+    storyId: args.storyId,
+    storyBranch: args.storyBranch,
+    baseBranch: args.baseBranch,
+    prUrl: args.prUrl,
+    prNumber: args.prNumber,
+    provider: args.provider,
+    runCodeReviewFn: args.runCodeReviewFn,
+    gitSpawnFn: args.gitSpawnFn,
+    progress,
+  });
+}