mandrel 2.67.0 → 2.69.0

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,
+  });
+}

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

@@ -33,7 +33,7 @@ import { deriveCloseNote } from './close-note.js';
 import { runAutoMergePhase } from './phases/auto-merge.js';
 import { runBaseSyncPhase } from './phases/base-sync.js';
 import { runCloseValidationPhase } from './phases/close-validation.js';
-import { parsePrNumber, runStoryScopeReview } from './phases/code-review.js';
+import { parsePrNumber } from './phases/code-review.js';
 import { runConfirmMergePhase } from './phases/confirm-merge.js';
 import { runGraphqlPreflight } from './phases/graphql-preflight.js';
 import { lockWaitPending } from './phases/lock-wait-pending.js';
@@ -45,11 +45,17 @@ import { handleCriticalReviewBlock } from './phases/review-block.js';
 import { handleOverriddenReviewBlock } from './phases/review-override.js';
 import { reapWorktreePhase } from './phases/worktree-reap.js';
 import { runWrongTreeGuardPhase } from './phases/wrong-tree-guard.js';
+import {
+  discardHeldReview,
+  reviewAfterPrOpen,
+  startHeldReview,
+} from './review-overlap.js';
 
 const progress = Logger.createProgress('single-story-close', { stderr: true });
 
 /**
  * Wall-clock seconds per named phase; each transition logs the phase it ends.
+ * Overlapping work `pause`s the clock and `record`s its own time.
  *
  * @param {() => number} [nowMs]
  */
@@ -57,11 +63,14 @@ function createPhaseTimer(nowMs = Date.now) {
   const durations = {};
   let current = null;
   let since = 0;
+  const record = (phase, ms) => {
+    const seconds = Math.round(Math.max(0, ms) / 100) / 10;
+    durations[phase] = (durations[phase] ?? 0) + seconds;
+    progress('TIMING', `⏱  ${phase}: ${seconds}s`);
+  };
   const end = () => {
     if (current === null) return;
-    const seconds = Math.round((nowMs() - since) / 100) / 10;
-    durations[current] = (durations[current] ?? 0) + seconds;
-    progress('TIMING', `⏱  ${current}: ${seconds}s`);
+    record(current, nowMs() - since);
     current = null;
   };
   return {
@@ -71,6 +80,8 @@ function createPhaseTimer(nowMs = Date.now) {
       current = phase;
       since = nowMs();
     },
+    record,
+    pause: end,
     finish() {
       end();
       return Object.keys(durations).length > 0 ? { ...durations } : null;
@@ -257,6 +268,7 @@ function resolveWorktreePath({ cwd, config, storyId }) {
  * @returns {Promise<{
  *   validationGates: Record<string, string>|null,
  *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   suiteTimings: object|null,
  *   pending: boolean,
  * }>} `validationGates` is null when skipped; `pending` means a full-suite
  *   lock wait expired and the gates deferred.
@@ -293,7 +305,12 @@ async function runPrePushPhases(ctx, deps) {
   }
   if (options.skipValidation) {
     progress('VALIDATE', '⏭ Skipped (--skip-validation).');
-    return { validationGates: null, lockWait: null, pending: false };
+    return {
+      validationGates: null,
+      lockWait: null,
+      suiteTimings: null,
+      pending: false,
+    };
   }
   setPhase('close-validation');
   let validation;
@@ -308,8 +325,22 @@ async function runPrePushPhases(ctx, deps) {
       progress,
       runCloseValidation,
       buildDefaultGates,
+      onPreGateStepsDone: () => {
+        ctx.heldReview = startHeldReview({
+          cwd,
+          storyId,
+          storyBranch,
+          baseBranch,
+          provider: deps.provider,
+          runCodeReviewFn: deps.runCodeReview,
+          gitSpawnFn: gitSpawn,
+          progress,
+          config: deps.config,
+        });
+      },
     });
   } catch (err) {
+    discardHeldReview(ctx.heldReview, 'validation failed', progress);
     // The gate that died is all this run observed; the envelope claims no more.
     if (typeof err?.closeGate === 'string') {
       ctx.setObservedGates({ [err.closeGate]: 'failed' });
@@ -321,6 +352,7 @@ async function runPrePushPhases(ctx, deps) {
   return {
     validationGates: gates,
     lockWait: validation?.lockWait ?? null,
+    suiteTimings: validation?.suiteTimings ?? null,
     pending: validation?.pending === true,
   };
 }
@@ -396,10 +428,11 @@ async function openAndReviewPr(ctx, deps) {
   const prNumber = parsePrNumber(prUrl);
   // Already merged (landed between invocations): skip review and arm; confirm observes it.
   if (alreadyMerged) {
+    discardHeldReview(ctx.heldReview, 'PR already merged', progress);
     return { prUrl, prNumber, alreadyMerged: true };
   }
-  ctx.setPhase('code-review');
-  const reviewOutcome = await runStoryScopeReview({
+  const reviewOutcome = await reviewAfterPrOpen({
+    held: ctx.heldReview,
     cwd,
     storyId,
     storyBranch,
@@ -410,6 +443,9 @@ async function openAndReviewPr(ctx, deps) {
     runCodeReviewFn: deps.runCodeReview,
     gitSpawnFn: gitSpawn,
     progress,
+    setPhase: ctx.setPhase,
+    pauseTimer: ctx.phaseTimer.pause,
+    recordDuration: ctx.phaseTimer.record,
   });
   const reviewOverride = reviewOutcome.halted
     ? await resolveReviewHalt(ctx, deps, { prUrl, prNumber, reviewOutcome })
@@ -690,6 +726,7 @@ async function finishWithMergeWait(prCtx, deps) {
     autoMergeEnabled: prCtx.autoMergeEnabled,
     gates: prCtx.gates,
     lockWait: prCtx.lockWait,
+    suiteTimings: prCtx.suiteTimings,
     elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
   });
   const result = closeResult({
@@ -763,6 +800,7 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
     },
     gates: prCtx.gates,
     lockWait: prCtx.lockWait,
+    suiteTimings: prCtx.suiteTimings,
     nextCommand: NEXT_COMMANDS.confirmMerge(prCtx.storyId),
     elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
   });
@@ -891,6 +929,7 @@ async function prePushPhase(ctx, deps) {
     deps,
   );
   if (!ctx.prePush.pending) return null;
+  discardHeldReview(ctx.heldReview, 'validation pending', progress);
   return await finishDeferred(ctx.prePush.lockWait, {
     storyId: ctx.storyId,
     storyBranch: ctx.storyBranch,
@@ -991,6 +1030,7 @@ async function finishPhase(ctx, deps) {
     phaseTimer: ctx.phaseTimer,
     workerTokens: ctx.workerTokens,
     lockWait: ctx.prePush.lockWait,
+    suiteTimings: ctx.prePush.suiteTimings,
     gates: closeEnvelopeGates(
       options,
       ctx.prePush.validationGates,

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -114,8 +114,9 @@ function compact(obj) {
  * @param {string|null} [args.nextCommand]
  * @param {number} args.elapsedSeconds
  * @param {object|null} [args.waitBudget]
- * @param {{ waitedSeconds: number, expired: boolean }|null} [args.lockWait]
+ * @param {{ waitedSeconds: number, expired: boolean, holder?: object }|null} [args.lockWait]
  *   Full-suite lock wait; `waitBudget` is merge-wait only.
+ * @param {{ lockWaitMs: number, hostWaitMs: number|null, testRunMs: number }|null} [args.suiteTimings]
  * @param {Record<string, number>|null} [args.phaseDurations] Seconds per phase.
  * @param {string} [args.timestamp]
  * @param {{ schema: object|null, error: string|null }} [args.schemaSource]
@@ -138,6 +139,7 @@ export function buildTerminalEnvelope({
   elapsedSeconds = 0,
   waitBudget,
   lockWait,
+  suiteTimings,
   phaseDurations,
   timestamp = new Date().toISOString(),
   schemaSource,
@@ -160,6 +162,7 @@ export function buildTerminalEnvelope({
     elapsedSeconds: Math.max(0, Number(elapsedSeconds) || 0),
     waitBudget: waitBudget ?? null,
     lockWait: lockWait ?? null,
+    suiteTimings: suiteTimings ?? null,
     phaseDurations,
     timestamp,
   });
@@ -324,35 +327,24 @@ export function emitTerminalEnvelope(
 }
 
 /**
- * Map a `runConfirmMergePhase` outcome onto the terminal envelope.
+ * Map a `runConfirmMergePhase` outcome onto the terminal envelope; the other
+ * fields pass through.
  *
  * @returns {object} A validated `story-deliver-terminal` envelope.
  */
 export function terminalFromWaitOutcome({
   waitOutcome,
-  storyId,
-  storyBranch,
-  baseBranch,
   prNumber,
   prUrl,
   autoMergeEnabled,
-  gates,
-  lockWait,
-  elapsedSeconds,
+  ...common
 }) {
+  const { storyId } = common;
   const prBase = {
     number: prNumber,
     url: prUrl ?? null,
     autoMergeEnabled: Boolean(autoMergeEnabled),
   };
-  const common = {
-    storyId,
-    storyBranch,
-    baseBranch,
-    gates,
-    lockWait,
-    elapsedSeconds,
-  };
 
   if (waitOutcome.terminal === 'landed') {
     return buildTerminalEnvelope({

package/.agents/scripts/lib/process-group.js

@@ -27,7 +27,7 @@ export function groupSpawnOptions(platform = process.platform) {
  * @param {{ platform?: string, killFn?: (pid: number, signal: string) => void }} [opts]
  * @returns {boolean}
  */
-function killProcessGroup(
+export function killProcessGroup(
   child,
   signal = 'SIGKILL',
   { platform = process.platform, killFn = process.kill.bind(process) } = {},