mandrel 2.64.0 → 2.66.0

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

@@ -44,14 +44,15 @@ import {
   decideMergeWaitFailFast,
   deriveChecksStatus,
   deriveRedHeadRuns,
-  deriveRequiredRunEvidence,
   isPrMerged,
   MERGE_WAIT_GH_TIMEOUT_MS,
   parseWorkflowRunId,
+  pollIntervalMs,
   readRunSummary,
   resolveAdvisoryGateVerdict,
 } from '../../merge-poll.js';
 import { readMergeQueueState } from '../../merge-queue.js';
+import { readProbeRunEvidence } from '../../required-checks.js';
 import { NEXT_COMMANDS } from '../../story-deliver-terminal.js';
 import {
   postStructuredComment,
@@ -155,6 +156,7 @@ export async function readPrWaitProbe({
   gh = defaultGh,
   ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
   readMergeQueueStateFn = readMergeQueueState,
+  readRequiredCheckNamesFn,
 }) {
   try {
     const view = await withGhTimeout(
@@ -188,7 +190,14 @@ export async function readPrWaitProbe({
       }),
       // Head-anchored, so superseded/pending runs don't read as red; `null`
       // when the rollup is empty (the consecutive-probe fallback owns that).
-      requiredRunEvidence: deriveRequiredRunEvidence(view?.statusCheckRollup),
+      requiredRunEvidence: await readProbeRunEvidence({
+        view,
+        checksStatus,
+        prNumber,
+        gh,
+        ghTimeoutMs,
+        readFn: readRequiredCheckNamesFn,
+      }),
       redHeadRuns: deriveRedHeadRuns(view?.statusCheckRollup),
       headSha: readString(view?.headRefOid),
     };
@@ -645,13 +654,11 @@ async function maybeRerunAdvisory({
 }
 
 /**
- * Advisory-gate terminal for one poll; passes a decided `unlanded` through so
- * the caller stays branch-free (`runMergePoll` is at the cyclomatic ceiling).
- * Skips runs already re-ran, enriches the rest, spends any rerun allowance,
- * and disarms BEFORE returning a block so the PR cannot merge out from under it.
+ * Advisory-gate terminal for one poll, or `null` to keep polling. Skips runs
+ * already re-ran, enriches the rest, spends any rerun allowance, and disarms
+ * BEFORE returning a block so the PR cannot merge out from under it.
  */
 async function resolveAdvisoryUnlanded({
-  unlanded,
   probe,
   blockOnAdvisoryFailure,
   advisoryAllowlist,
@@ -663,7 +670,6 @@ async function resolveAdvisoryUnlanded({
   disarmAutoMergeFn,
   elapsedSeconds,
 }) {
-  if (unlanded) return unlanded;
   const advisory = decideAdvisoryGateBlock({
     probe,
     blockOnAdvisoryFailure,
@@ -992,6 +998,308 @@ async function onMergeObserved({
   };
 }
 
+/**
+ * Everything one poll hands the next.
+ *
+ * @param {{ startedAtMs: number, intervalSeconds: number }} args
+ * @returns {{ startedAtMs: number, polls: number, intervalMs: number,
+ *   updatesUsed: number, consecutiveRequiredFailSnapshots: number }}
+ */
+export function createMergeWaitState({ startedAtMs, intervalSeconds }) {
+  return {
+    startedAtMs,
+    polls: 0,
+    intervalMs: intervalSeconds * 1000,
+    updatesUsed: 0,
+    consecutiveRequiredFailSnapshots: 0,
+  };
+}
+
+/** Budget first — it is the real give-up. */
+function provisionalVerdict(
+  { polls, intervalMs, waitedMs, cumulativeMs },
+  limits,
+) {
+  if (
+    polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK &&
+    cumulativeMs + intervalMs > limits.maxBudgetSeconds * 1000
+  ) {
+    return 'budget-exhausted';
+  }
+  if (waitedMs + intervalMs > limits.maxWaitSeconds * 1000) return 'wait-bound';
+  return '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.
+ * The two clock reads (wait bound, then budget) keep a stepping test clock's
+ * call sequence.
+ *
+ * @param {{ state: object, probe: object, nowMs: number,
+ *   cumulativeNowMs?: number, limits: object }} args
+ * @returns {{ state: object, verdict: string, waitedMs: number,
+ *   cumulativeMs: number, elapsedSeconds: number, waitBudget: object,
+ *   failFast?: object }}
+ */
+export function decideMergeWaitPoll({
+  state,
+  probe,
+  nowMs,
+  cumulativeNowMs = nowMs,
+  limits,
+}) {
+  const anchorMs = resolveBudgetAnchorMs({
+    createdAt: probe.createdAt,
+    fallbackMs: state.startedAtMs,
+  });
+  const waitedMs = nowMs - state.startedAtMs;
+  const cumulativeMs = Math.max(cumulativeNowMs - anchorMs, waitedMs);
+  const polled = {
+    ...state,
+    polls: state.polls + 1,
+    intervalMs: pollIntervalMs(probe.checksStatus, limits.intervalSeconds),
+  };
+  const timing = {
+    waitedMs,
+    cumulativeMs,
+    elapsedSeconds: Math.round(waitedMs / 1000),
+    waitBudget: {
+      maxWaitSeconds: limits.maxWaitSeconds,
+      waitedSeconds: Math.round(waitedMs / 1000),
+      cumulativeSeconds: Math.round(cumulativeMs / 1000),
+      maxBudgetSeconds: limits.maxBudgetSeconds,
+    },
+  };
+  if (isPrMerged(probe)) return { state: polled, verdict: 'merged', ...timing };
+  if (probe.state === 'CLOSED') {
+    return { state: polled, verdict: 'closed', ...timing };
+  }
+  // No remaining budget turns a red required check green; fail fast.
+  const failFast = decideMergeWaitFailFast({
+    probe,
+    consecutiveRequiredFailSnapshots: state.consecutiveRequiredFailSnapshots,
+  });
+  const next = {
+    ...polled,
+    consecutiveRequiredFailSnapshots: failFast.consecutiveRequiredFailSnapshots,
+  };
+  if (failFast.failFast) {
+    return { state: next, verdict: 'checks-failed', failFast, ...timing };
+  }
+  return {
+    state: next,
+    verdict: provisionalVerdict({ ...next, waitedMs, cumulativeMs }, limits),
+    ...timing,
+  };
+}
+
+function blockWith(ctx, unlanded) {
+  return blockOnUnlanded({
+    storyId: ctx.storyId,
+    prNumber: ctx.prNumber,
+    prUrl: ctx.prUrl,
+    ...unlanded,
+    provider: ctx.provider,
+    progress: ctx.progress,
+    classifyMergeBlockFn: ctx.classifyMergeBlockFn,
+    emitMergeUnlandedFn: ctx.emitMergeUnlandedFn,
+  });
+}
+
+function settleMerged(ctx, decision, probe) {
+  return onMergeObserved({
+    ...ctx,
+    prProbe: probe,
+    elapsedSeconds: decision.elapsedSeconds,
+  });
+}
+
+function settleClosed(ctx, decision, probe) {
+  return blockWith(ctx, {
+    prProbe: probe,
+    budget: { exhausted: true, elapsedSeconds: decision.elapsedSeconds },
+    blockClassOverride: CLOSED_UNMERGED_BLOCK_CLASS,
+    reasonOverride: CLOSED_UNMERGED_REASON,
+  });
+}
+
+async function settleChecksFailed(ctx, decision, probe) {
+  const { failFast } = decision;
+  ctx.progress?.(
+    'CONFIRM',
+    failFast.evidencePath === 'per-run'
+      ? `🛑 PR #${ctx.prNumber}: a required check concluded failure with none in flight — failing fast (evidence=per-run).`
+      : `🛑 PR #${ctx.prNumber}: two consecutive failing check probes without per-run evidence — failing fast (evidence=consecutive-probe).`,
+  );
+  return blockWith(ctx, {
+    prProbe: failFast.prProbe,
+    budget: { exhausted: false, elapsedSeconds: decision.elapsedSeconds },
+    blockClassOverride: failFast.blockClass,
+    reasonOverride: failFast.reason,
+    redRecord: await recordChecksFailedRed({
+      storyId: ctx.storyId,
+      prNumber: ctx.prNumber,
+      probe,
+      cwd: ctx.cwd,
+      config: ctx.config,
+      gh: ctx.injectedGh,
+      progress: ctx.progress,
+      disarmAutoMergeFn: ctx.disarmAutoMergeFn,
+      recordRequiredRedFn: ctx.recordRequiredRedFn,
+    }),
+  });
+}
+
+const DEFINITIVE_SETTLERS = Object.freeze({
+  merged: settleMerged,
+  closed: settleClosed,
+  'checks-failed': settleChecksFailed,
+});
+
+/** Invocation bound reached: resumable `pending`, no mutation. */
+function pendingAtWaitBound(ctx, decision, probe) {
+  const { waitBudget } = decision;
+  const checks = probe.checksStatus ?? 'unknown';
+  ctx.progress?.(
+    'CONFIRM',
+    `⏸  Merge wait bound reached (${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.`,
+  );
+  return {
+    confirmed: false,
+    terminal: 'pending',
+    reason: `merge wait bound reached with the PR still in flight (checks=${checks})`,
+    prProbe: probe,
+    waitBudget,
+    elapsedSeconds: waitBudget.waitedSeconds,
+  };
+}
+
+/**
+ * Advisory gates are usually still QUEUED at arm time, so they redden here,
+ * mid-wait, before auto-merge lands over them.
+ *
+ * @returns {Promise<{ state: object, outcome: object|null }>}
+ */
+async function settleProvisional(ctx, decision, probe) {
+  const advisory = await resolveAdvisoryUnlanded({
+    probe,
+    blockOnAdvisoryFailure: ctx.blockOnAdvisoryFailure,
+    advisoryAllowlist: ctx.advisoryAllowlist,
+    rerunState: ctx.rerunState,
+    prNumber: ctx.prNumber,
+    gh: ctx.injectedGh,
+    ghTimeoutMs: ctx.ghTimeoutMs,
+    progress: ctx.progress,
+    disarmAutoMergeFn: ctx.disarmAutoMergeFn,
+    elapsedSeconds: decision.elapsedSeconds,
+  });
+  if (advisory) {
+    return { state: decision.state, outcome: await blockWith(ctx, advisory) };
+  }
+  const updated = await maybeUpdateBehindPr({
+    probe,
+    prNumber: ctx.prNumber,
+    updatesUsed: decision.state.updatesUsed,
+    updateAttempts: ctx.limits.updateAttempts,
+    gh: ctx.injectedGh,
+    ghTimeoutMs: ctx.ghTimeoutMs,
+    progress: ctx.progress,
+  });
+  const state = updated
+    ? { ...decision.state, updatesUsed: decision.state.updatesUsed + 1 }
+    : decision.state;
+  if (decision.verdict === 'budget-exhausted') {
+    const outcome = await blockWith(ctx, {
+      prProbe: probe,
+      budget: {
+        exhausted: true,
+        elapsedSeconds: Math.round(decision.cumulativeMs / 1000),
+      },
+      ...queuedExhaustionVerdict(probe, decision.cumulativeMs),
+    });
+    return { state, outcome };
+  }
+  if (decision.verdict === 'wait-bound') {
+    return { state, outcome: pendingAtWaitBound(ctx, decision, probe) };
+  }
+  return { state, outcome: null };
+}
+
+/** @returns {Promise<{ state: object, done: boolean, outcome?: object }>} */
+async function runMergePoll(ctx, state) {
+  const probe = await ctx.readPrWaitProbeFn({
+    prNumber: ctx.prNumber,
+    gh: ctx.injectedGh,
+    ghTimeoutMs: ctx.ghTimeoutMs,
+  });
+  const decision = decideMergeWaitPoll({
+    state,
+    probe,
+    nowMs: ctx.nowMsFn(),
+    cumulativeNowMs: ctx.nowMsFn(),
+    limits: ctx.limits,
+  });
+  // Heartbeat: a backgrounded close's output-file growth is its liveness signal.
+  ctx.progress?.(
+    'CONFIRM',
+    pollHeartbeat({
+      polls: decision.state.polls,
+      prNumber: ctx.prNumber,
+      probe,
+      waitBudget: decision.waitBudget,
+    }),
+  );
+  const definitive = DEFINITIVE_SETTLERS[decision.verdict];
+  const settled = definitive
+    ? {
+        state: decision.state,
+        outcome: await definitive(ctx, decision, probe),
+      }
+    : await settleProvisional(ctx, decision, probe);
+  return settled.outcome
+    ? { state: settled.state, done: true, outcome: settled.outcome }
+    : { state: settled.state, done: false };
+}
+
+/** Carries the arm phase's advisory class rather than a generic `arm-failure`. */
+function blockNeverArmed({
+  storyId,
+  prNumber,
+  prUrl,
+  autoMergeReason,
+  advisoryGate,
+  provider,
+  progress,
+  classifyMergeBlockFn,
+  emitMergeUnlandedFn,
+}) {
+  progress?.(
+    'CONFIRM',
+    `⚠️ Auto-merge not enabled (${autoMergeReason ?? 'unknown'}) — cannot wait for a merge that was never armed.`,
+  );
+  return blockOnUnlanded({
+    storyId,
+    prNumber,
+    prUrl,
+    armResult: { armed: false, reason: autoMergeReason },
+    budget: { elapsedSeconds: 0 },
+    provider,
+    progress,
+    classifyMergeBlockFn,
+    emitMergeUnlandedFn,
+    ...(autoMergeReason === 'advisory-gate-red'
+      ? {
+          blockClassOverride: advisoryGate?.blockClass ?? 'advisory-gate-red',
+          reasonOverride: advisoryGate?.reason,
+        }
+      : {}),
+  });
+}
+
 /**
  * Poll an armed Story PR to merge confirmation, a resumable `pending`
  * expiry, or a classified `agent::blocked` terminal.
@@ -1026,23 +1334,9 @@ async function onMergeObserved({
  * @returns {Promise<object>}
  */
 export async function runConfirmMergePhase({
-  cwd,
-  storyId,
-  storyBranch,
-  baseBranch,
-  prNumber,
-  prUrl,
-  autoMergeEnabled,
-  autoMergeReason,
-  advisoryGate,
-  provider,
-  config,
   maxWaitSeconds: maxWaitSecondsOverride,
   mergeWatchMode: mergeWatchModeOverride,
   rerunAdvisory: rerunAdvisoryOverride,
-  progress,
-  injectedGh,
-  injectedNotify,
   confirmStoryMergedFn = defaultConfirmStoryMerged,
   readPrWaitProbeFn = readPrWaitProbe,
   readPrMergeStateFn = defaultReadPrMergeState,
@@ -1055,282 +1349,90 @@ export async function runConfirmMergePhase({
   sleepFn = defaultSleep,
   nowMsFn = Date.now,
   ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
+  ...args
 }) {
-  // Never armed: nothing to poll, but a terminal is still required.
-  if (!autoMergeEnabled) {
-    progress?.(
-      'CONFIRM',
-      `⚠️ Auto-merge not enabled (${autoMergeReason ?? 'unknown'}) — cannot wait for a merge that was never armed.`,
-    );
-    return blockOnUnlanded({
-      storyId,
-      prNumber,
-      prUrl,
-      armResult: { armed: false, reason: autoMergeReason },
-      budget: { elapsedSeconds: 0 },
-      provider,
-      progress,
+  if (!args.autoMergeEnabled) {
+    return blockNeverArmed({
+      ...args,
       classifyMergeBlockFn,
       emitMergeUnlandedFn,
-      // Carry the arm phase's advisory verdict and class (which may be
-      // `inconclusive`) rather than a generic `arm-failure`.
-      ...(autoMergeReason === 'advisory-gate-red'
-        ? {
-            blockClassOverride: advisoryGate?.blockClass ?? 'advisory-gate-red',
-            reasonOverride: advisoryGate?.reason,
-          }
-        : {}),
     });
   }
 
-  const {
-    mode,
-    intervalSeconds,
-    maxWaitSeconds,
-    maxBudgetSeconds,
-    updateAttempts,
-  } = resolveMergeWaitConfig(
-    config,
+  const limits = resolveMergeWaitConfig(
+    args.config,
     maxWaitSecondsOverride,
     mergeWatchModeOverride,
   );
-  const { blockOnAdvisoryFailure, advisoryAllowlist } = getCiDelivery(config);
+  const { blockOnAdvisoryFailure, advisoryAllowlist } = getCiDelivery(
+    args.config,
+  );
   // Spent across the whole wait, not per poll, so `n` bounds CI minutes.
   const rerunAllowance = resolveAdvisoryRerunAllowance(
-    config,
+    args.config,
     rerunAdvisoryOverride,
   );
-  const rerunState = {
-    allowance: rerunAllowance,
-    remaining: rerunAllowance,
-    issued: new Set(),
+  const ctx = {
+    ...args,
+    limits,
+    blockOnAdvisoryFailure,
+    advisoryAllowlist,
+    rerunState: {
+      allowance: rerunAllowance,
+      remaining: rerunAllowance,
+      issued: new Set(),
+    },
+    confirmStoryMergedFn,
+    readPrWaitProbeFn,
+    readPrMergeStateFn,
+    classifyMergeBlockFn,
+    emitMergeUnlandedFn,
+    emitMergeFlipFailedFn,
+    runPostLandTailFn,
+    disarmAutoMergeFn,
+    recordRequiredRedFn,
+    nowMsFn,
+    ghTimeoutMs,
   };
-  const intervalMs = intervalSeconds * 1000;
-  const startedAtMs = nowMsFn();
-  let anchorMs = startedAtMs;
-  let updatesUsed = 0;
-  let polls = 0;
-  // Without per-run evidence, fail fast only after two consecutive failing
-  // probes an interval apart; reset on any other probe.
-  let consecutiveRequiredFailSnapshots = 0;
+  let state = createMergeWaitState({
+    startedAtMs: nowMsFn(),
+    intervalSeconds: limits.intervalSeconds,
+  });
 
-  progress?.(
+  args.progress?.(
     'CONFIRM',
-    `⏳ Close-and-land: polling PR #${prNumber} for merge confirmation ` +
-      `(mode=${mode}, wait=${maxWaitSeconds}s this invocation, ` +
-      `cumulative budget=${maxBudgetSeconds}s)...`,
+    `⏳ Close-and-land: polling PR #${args.prNumber} for merge confirmation ` +
+      `(mode=${limits.mode}, wait=${limits.maxWaitSeconds}s this invocation, ` +
+      `cumulative budget=${limits.maxBudgetSeconds}s)...`,
   );
 
-  /** One iteration: `{ done: false }` or `{ done: true, outcome }`. */
-  async function runMergePoll() {
-    const probe = await readPrWaitProbeFn({
-      prNumber,
-      gh: injectedGh,
-      ghTimeoutMs,
-    });
-    polls += 1;
-
-    anchorMs = resolveBudgetAnchorMs({
-      createdAt: probe.createdAt,
-      fallbackMs: startedAtMs,
-    });
-
-    const waitedMs = nowMsFn() - startedAtMs;
-    const cumulativeMs = Math.max(nowMsFn() - anchorMs, waitedMs);
-    const waitBudget = {
-      maxWaitSeconds,
-      waitedSeconds: Math.round(waitedMs / 1000),
-      cumulativeSeconds: Math.round(cumulativeMs / 1000),
-      maxBudgetSeconds,
-    };
-
-    // Heartbeat: a backgrounded close's output-file growth is its liveness signal.
-    progress?.(
-      'CONFIRM',
-      `⏱  poll ${polls}: PR #${prNumber} state=${probe.state ?? 'unknown'} ` +
-        `checks=${probe.checksStatus ?? 'unknown'} ` +
-        `mergeState=${probe.mergeStateStatus ?? 'unknown'} ` +
-        `(${waitBudget.waitedSeconds}s of ${maxWaitSeconds}s this invocation; ` +
-        `${waitBudget.cumulativeSeconds}s of ${maxBudgetSeconds}s cumulative)` +
-        (probe.error ? ` — probe error: ${probe.error}` : ''),
-    );
-
-    if (isPrMerged(probe)) {
-      return doneWith(
-        await onMergeObserved({
-          storyId,
-          storyBranch,
-          baseBranch,
-          prNumber,
-          prUrl,
-          cwd,
-          config,
-          provider,
-          progress,
-          injectedGh,
-          injectedNotify,
-          readPrMergeStateFn,
-          confirmStoryMergedFn,
-          runPostLandTailFn,
-          emitMergeFlipFailedFn,
-          prProbe: probe,
-          elapsedSeconds: Math.round(waitedMs / 1000),
-        }),
-      );
-    }
-
-    // Each definitive condition fills `unlanded`; one call site below blocks.
-    let unlanded = null;
-
-    if (probe.state === 'CLOSED') {
-      unlanded = {
-        prProbe: probe,
-        budget: {
-          exhausted: true,
-          elapsedSeconds: Math.round(waitedMs / 1000),
-        },
-        blockClassOverride: CLOSED_UNMERGED_BLOCK_CLASS,
-        reasonOverride: CLOSED_UNMERGED_REASON,
-      };
-    } else {
-      // No remaining budget turns a red required check green; fail fast.
-      const decision = decideMergeWaitFailFast({
-        probe,
-        consecutiveRequiredFailSnapshots,
-      });
-      consecutiveRequiredFailSnapshots =
-        decision.consecutiveRequiredFailSnapshots;
-      if (decision.failFast) {
-        progress?.(
-          'CONFIRM',
-          decision.evidencePath === 'per-run'
-            ? `🛑 PR #${prNumber}: a required check concluded failure with none in flight — failing fast (evidence=per-run).`
-            : `🛑 PR #${prNumber}: two consecutive failing check probes without per-run evidence — failing fast (evidence=consecutive-probe).`,
-        );
-        unlanded = {
-          prProbe: decision.prProbe,
-          budget: {
-            exhausted: false,
-            elapsedSeconds: Math.round(waitedMs / 1000),
-          },
-          blockClassOverride: decision.blockClass,
-          reasonOverride: decision.reason,
-          redRecord: await recordChecksFailedRed({
-            storyId,
-            prNumber,
-            probe,
-            cwd,
-            config,
-            gh: injectedGh,
-            progress,
-            disarmAutoMergeFn,
-            recordRequiredRedFn,
-          }),
-        };
-      }
-
-      // Advisory gates are usually still QUEUED at arm time, so they redden
-      // here, mid-wait, before auto-merge lands over them.
-      unlanded = await resolveAdvisoryUnlanded({
-        unlanded,
-        probe,
-        blockOnAdvisoryFailure,
-        advisoryAllowlist,
-        rerunState,
-        prNumber,
-        gh: injectedGh,
-        ghTimeoutMs,
-        progress,
-        disarmAutoMergeFn,
-        elapsedSeconds: Math.round(waitedMs / 1000),
-      });
-    }
-
-    if (!unlanded) {
-      if (
-        await maybeUpdateBehindPr({
-          probe,
-          prNumber,
-          updatesUsed,
-          updateAttempts,
-          gh: injectedGh,
-          ghTimeoutMs,
-          progress,
-        })
-      ) {
-        updatesUsed += 1;
-      }
-
-      // Cumulative budget exhausted, behind the poll floor.
-      if (
-        polls >= MIN_POLLS_BEFORE_BUDGET_BLOCK &&
-        cumulativeMs + intervalMs > maxBudgetSeconds * 1000
-      ) {
-        unlanded = {
-          prProbe: probe,
-          budget: {
-            exhausted: true,
-            elapsedSeconds: Math.round(cumulativeMs / 1000),
-          },
-          ...queuedExhaustionVerdict(probe, cumulativeMs),
-        };
-      }
-    }
-
-    if (unlanded) {
-      return doneWith(
-        await blockOnUnlanded({
-          storyId,
-          prNumber,
-          prUrl,
-          ...unlanded,
-          provider,
-          progress,
-          classifyMergeBlockFn,
-          emitMergeUnlandedFn,
-        }),
-      );
-    }
-
-    // Invocation bound reached: resumable `pending`, no mutation.
-    if (waitedMs + intervalMs > maxWaitSeconds * 1000) {
-      progress?.(
-        'CONFIRM',
-        `⏸  Merge wait bound reached (${waitBudget.waitedSeconds}s of ${maxWaitSeconds}s this invocation; ` +
-          `${waitBudget.cumulativeSeconds}s of ${maxBudgetSeconds}s cumulative). PR #${prNumber} still in flight ` +
-          `(checks=${probe.checksStatus ?? 'unknown'}). Story stays at agent::closing — resumable.`,
-      );
-      return doneWith({
-        confirmed: false,
-        terminal: 'pending',
-        reason: `merge wait bound reached with the PR still in flight (checks=${probe.checksStatus ?? 'unknown'})`,
-        prProbe: probe,
-        waitBudget,
-        elapsedSeconds: waitBudget.waitedSeconds,
-      });
-    }
-
-    return { done: false };
-  }
-
   const tick = await pollUntil({
     fn: async () => {
       try {
-        return await runMergePoll();
+        const step = await runMergePoll(ctx, state);
+        state = step.state;
+        return step;
       } catch (err) {
         // pollUntil treats a throw as a non-match and would spin; carry it out.
         return { done: true, thrown: err };
       }
     },
     predicate: (result) => result?.done === true,
-    intervalMs,
-    // No pollUntil timeout: the tick owns both bounds and their classification.
-    sleepFn: (ms) => sleepFn(ms),
+    intervalMs: state.intervalMs,
+    // No pollUntil timeout: the tick owns both bounds and the cadence.
+    sleepFn: () => sleepFn(state.intervalMs),
   });
   if (tick.thrown) throw tick.thrown;
   return tick.outcome;
 }
 
-function doneWith(outcome) {
-  return { done: true, outcome };
+function pollHeartbeat({ polls, prNumber, probe, waitBudget }) {
+  return (
+    `⏱  poll ${polls}: PR #${prNumber} state=${probe.state ?? 'unknown'} ` +
+    `checks=${probe.checksStatus ?? 'unknown'} ` +
+    `mergeState=${probe.mergeStateStatus ?? 'unknown'} ` +
+    `(${waitBudget.waitedSeconds}s of ${waitBudget.maxWaitSeconds}s this invocation; ` +
+    `${waitBudget.cumulativeSeconds}s of ${waitBudget.maxBudgetSeconds}s cumulative)` +
+    (probe.error ? ` — probe error: ${probe.error}` : '')
+  );
 }