mandrel 2.54.0 → 2.55.0

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

@@ -13,8 +13,18 @@
  * On a merge conflict the Story is transitioned to `agent::blocked` via
  * `handleSyncFailure` and the caller throws — the operator resolves in
  * the worktree and re-runs.
+ *
+ * Story #5267: a sync that lands tracked content also spends the worker's
+ * pre-push credit, because that credit is keyed on the tree. The phase says
+ * so out loud — see `buildStampInvalidatedWarning` — instead of leaving
+ * close's second full suite looking like a bug. Story #5278 splits the claim
+ * in two: gate evidence is spent by any tracked path, the capture stamp only
+ * by one under `crap.targetDirs`.
  */
 
+import { getQuality } from '../../../config/quality.js';
+import { resolveConfig } from '../../../config-resolver.js';
+import { filterFilesUnderTargets } from '../../../coverage-capture.js';
 import { syncBranchFromBase } from '../../../git/sync-from-base.js';
 import { Logger } from '../../../Logger.js';
 import { AGENT_LABELS } from '../../../label-constants.js';
@@ -40,6 +50,7 @@ import {
  *   storyId: number,
  *   provider: object,
  *   injectedSync?: typeof syncBranchFromBase,
+ *   resolveConfigImpl?: typeof resolveConfig,
  *   progress: (tag: string, msg: string) => void,
  * }} args
  */
@@ -52,6 +63,7 @@ export async function runBaseSyncPhase({
   storyId,
   provider,
   injectedSync,
+  resolveConfigImpl = resolveConfig,
   progress,
 }) {
   const syncCwd = worktreePath ?? cwd;
@@ -87,6 +99,95 @@ export async function runBaseSyncPhase({
     );
   }
   progress('SYNC', `✅ Synced from origin/${baseBranch} (${syncResult.kind}).`);
+  for (const line of buildStampInvalidatedWarning({
+    baseBranch,
+    result: syncResult,
+    targetDirs: resolveCrapTargetDirs(resolveConfigImpl, syncCwd),
+  })) {
+    progress('SYNC', line);
+  }
+}
+
+/**
+ * The CRAP scoring scope, or `[]` when it cannot be resolved. A `[]` makes
+ * the warning below fall back to naming the capture stamp unconditionally —
+ * the pre-#5278 wording — because an unresolvable scope is no evidence that
+ * the stamp survived.
+ *
+ * @param {typeof resolveConfig} resolveConfigImpl
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function resolveCrapTargetDirs(resolveConfigImpl, cwd) {
+  try {
+    return getQuality(resolveConfigImpl({ cwd }))?.crap?.targetDirs ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * How many changed paths the warning names before it stops listing.
+ * Enough to recognise the change set; short enough that the warning still
+ * reads as a warning rather than as a diff.
+ */
+const WARNED_PATH_LIMIT = 12;
+
+/**
+ * The loud "your credit is spent" warning, or `[]` when the sync changed
+ * nothing (Story #5267, narrowed by #5278).
+ *
+ * The worker banks two kinds of credit before the push: gate evidence keyed
+ * on the tree (lint, typecheck) and one full-suite capture stamp keyed on the
+ * content of `crap.targetDirs`. This sync runs after that, and the two are
+ * spent on different conditions — which is why #5267's single blanket
+ * sentence was wrong half the time:
+ *
+ *   - **Gate evidence** is spent by any tracked path at all, because the tree
+ *     hash it is keyed on moves with the first byte.
+ *   - **The capture stamp** is spent only when a merged path lands under
+ *     `crap.targetDirs`. A sync that brings in docs, workflows or CI config
+ *     leaves it perfectly valid, and announcing it as spent taught operators
+ *     to expect a second full suite that close was never going to run.
+ *
+ * Quiet by construction on the outcome that cannot spend either: a
+ * `noop-already-current` sync never touched the tree. A content-changing
+ * fast-forward DOES warn — it moves the tree exactly as a merge commit does,
+ * and staying quiet there would be a lie of omission.
+ *
+ * Pure. Module-private: the phase is the seam tests drive it through
+ * (`injectedSync` + a `progress` spy), so it needs no export of its own.
+ *
+ * @param {{ baseBranch: string, result: { kind?: string, changedPaths?: string[] }, targetDirs?: string[] }} args
+ * @returns {string[]} Progress lines, in order. Empty when nothing changed.
+ */
+function buildStampInvalidatedWarning({ baseBranch, result, targetDirs }) {
+  const changed = Array.isArray(result?.changedPaths)
+    ? result.changedPaths
+    : [];
+  if (changed.length === 0) return [];
+  const dirs = Array.isArray(targetDirs) ? targetDirs : [];
+  // An unresolvable scope (`[]`) cannot prove the stamp survived, so it fails
+  // closed to the unconditional wording.
+  const scored =
+    dirs.length === 0 ? changed : filterFilesUnderTargets(changed, dirs);
+  const shown = changed.slice(0, WARNED_PATH_LIMIT);
+  const overflow = changed.length - shown.length;
+  return [
+    `⚠️  BASE MOVED: the ${result?.kind ?? 'sync'} from origin/${baseBranch} ` +
+      `brought ${changed.length} tracked path(s) into this branch, so the tree ` +
+      `hash the pre-push lint/typecheck evidence was keyed on has changed. ` +
+      `That evidence cannot be credited; those gates re-run below.`,
+    scored.length > 0
+      ? `⚠️  The full-suite capture stamp is spent too: ${scored.length} of ` +
+        `those path(s) fall under the CRAP target dirs [${dirs.join(', ')}], ` +
+        `so the suite re-runs against the merged tree. This is expected, not a fault.`
+      : `⚠️  The full-suite capture stamp SURVIVES: no merged path falls under ` +
+        `the CRAP target dirs [${dirs.join(', ')}], so the coverage artifact still ` +
+        `describes this tree and the suite is not re-run.`,
+    ...shown.map((f) => `⚠️    ${f}`),
+    ...(overflow > 0 ? [`⚠️    …and ${overflow} more`] : []),
+  ];
 }
 
 /**

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

@@ -105,6 +105,8 @@ import {
 import { emitMergeUnlanded as defaultEmitMergeUnlanded } from '../../lifecycle/emit-merge-unlanded.js';
 import { classifyMergeBlock as defaultClassifyMergeBlock } from '../../merge-block-class.js';
 import {
+  ADVISORY_GATE_INCONCLUSIVE_CLASS,
+  ADVISORY_GATE_RED_CLASS,
   DEFAULT_INTERVAL_SECONDS,
   DEFAULT_MAX_BUDGET_SECONDS,
   decideAdvisoryGateBlock,
@@ -113,6 +115,9 @@ import {
   deriveRedHeadRuns,
   deriveRequiredRunEvidence,
   MERGE_WAIT_GH_TIMEOUT_MS,
+  parseWorkflowRunId,
+  readRunSummary,
+  resolveAdvisoryGateVerdict,
 } from '../../merge-poll.js';
 import { NEXT_COMMANDS } from '../../story-deliver-terminal.js';
 import {
@@ -209,6 +214,26 @@ function withGhTimeout(promise, timeoutMs, label) {
   return bounded;
 }
 
+/**
+ * One string field off a `gh pr view` payload, or `absent` when the API did
+ * not return one. Deduplicated out of the probe below (Story #5266): six
+ * identical `typeof x === 'string'` ternaries put that one function over the
+ * CRAP ratchet the moment a seventh field was needed.
+ *
+ * An empty string counts as absent — `gh` returns `""` for a field it cannot
+ * read, and every caller treats that exactly as "not there".
+ *
+ * @param {unknown} value
+ * @param {null|undefined} [absent] What to report when the field is missing.
+ *   `null` for the three fields the poll loop compares against null; the
+ *   `undefined` default for the ones whose absence must not shadow a
+ *   downstream default.
+ * @returns {string|null|undefined}
+ */
+function readString(value, absent = undefined) {
+  return typeof value === 'string' && value ? value : absent;
+}
+
 /**
  * One probe per poll iteration, carrying every field the loop and the
  * terminal classifier need: merge state, the checks rollup, the merge-state
@@ -238,22 +263,19 @@ export async function readPrWaitProbe({
         'mergeStateStatus',
         'reviewDecision',
         'statusCheckRollup',
+        // Story #5266 — the head the red advisory runs belong to, so their
+        // check-run output can be read back and classified.
+        'headRefOid',
       ]),
       ghTimeoutMs,
       `gh pr view ${prNumber}`,
     );
     return {
-      state: typeof view?.state === 'string' ? view.state : null,
-      mergedAt: typeof view?.mergedAt === 'string' ? view.mergedAt : null,
-      createdAt: typeof view?.createdAt === 'string' ? view.createdAt : null,
-      mergeStateStatus:
-        typeof view?.mergeStateStatus === 'string'
-          ? view.mergeStateStatus
-          : undefined,
-      reviewDecision:
-        typeof view?.reviewDecision === 'string'
-          ? view.reviewDecision
-          : undefined,
+      state: readString(view?.state, null),
+      mergedAt: readString(view?.mergedAt, null),
+      createdAt: readString(view?.createdAt, null),
+      mergeStateStatus: readString(view?.mergeStateStatus),
+      reviewDecision: readString(view?.reviewDecision),
       checksStatus: deriveChecksStatus(view?.statusCheckRollup),
       // Head-anchored per-run evidence (Story #4695): distinguishes a
       // genuinely red required run from the superseded / still-pending noise
@@ -264,6 +286,7 @@ export async function readPrWaitProbe({
       // verdict can name the offending job and match the allowlist. Same
       // red-ness test as `requiredRunEvidence`, so the two cannot disagree.
       redHeadRuns: deriveRedHeadRuns(view?.statusCheckRollup),
+      headSha: readString(view?.headRefOid),
     };
   } catch (err) {
     return {
@@ -373,6 +396,83 @@ export function resolveBudgetAnchorMs({ createdAt, fallbackMs }) {
   return Number.isFinite(parsed) ? parsed : fallbackMs;
 }
 
+/**
+ * The advisory-gate half of {@link unlandedRemedy} (Story #5279).
+ *
+ * Both advisory classes used to fall through to the generic remedy, which
+ * opens by telling the operator to resolve "branch protection, required
+ * checks, or a manual merge" — a diagnosis of a fault that provably does not
+ * exist here. An advisory gate blocks precisely BECAUSE GitHub reports the PR
+ * mergeable (`mergeStateStatus=UNSTABLE`) over a NON-required red check, so
+ * close refused to let native auto-merge land it. Saying so is the paragraph
+ * that stops the operator hunting a protection rule that is working fine.
+ *
+ * The two classes then part on what the evidence authorises. `inconclusive`
+ * is a job that failed WITHOUT FINISHING and reported no violation — nothing
+ * says the change is bad — so the proportionate act is a re-run, named here
+ * as `--rerun-advisory`; the permanent global exemption is deliberately
+ * mentioned last. `advisory-gate-red` reported a real violation, so the
+ * change is implicated and landing over it is a deliberate override.
+ *
+ * @param {{ storyId: number, blockClass: string }} args
+ * @returns {string}
+ */
+function advisoryGateRemedy({ storyId, blockClass }) {
+  const mergeable =
+    'GitHub reports this PR **mergeable regardless** ' +
+    '(`mergeStateStatus=UNSTABLE`) — the check that blocked is **advisory** ' +
+    '(non-required), so there is nothing wrong with branch protection or the ' +
+    'required checks. Close refused to let native auto-merge land the PR ' +
+    'over the failure, and disarmed it.';
+  const act =
+    blockClass === ADVISORY_GATE_INCONCLUSIVE_CLASS
+      ? 'The job **failed without finishing** and reported no violation, so ' +
+        'nothing here says the change is bad. Re-run it — ' +
+        '`--rerun-advisory <n>` on this command, or ' +
+        '`delivery.ci.rerunAdvisory` — rather than granting the permanent ' +
+        'global exemption `delivery.ci.advisoryAllowlist` is. Merging by ' +
+        'hand also lands it.'
+      : 'The job reported a real violation, so the change **is** implicated. ' +
+        'Fix it and push a new head, merge by hand to land over it ' +
+        'deliberately, re-run the job (`--rerun-advisory <n>`, or ' +
+        '`delivery.ci.rerunAdvisory`) if you believe it flaked, or exempt ' +
+        'the job via `delivery.ci.advisoryAllowlist`.';
+  return (
+    `${mergeable}\n\n${act}\n\nThen resume the land:\n\n` +
+    `\`\`\`bash\n${NEXT_COMMANDS.resumeLand(storyId)}\n\`\`\``
+  );
+}
+
+/**
+ * The class-specific remediation paragraph of the unlanded friction comment.
+ * Split out of {@link formatUnlandedFriction} so each class's wording is one
+ * named branch rather than a nested ternary.
+ *
+ * @param {{ storyId: number, prNumber: number|null, blockClass: string }} args
+ * @returns {string}
+ */
+function unlandedRemedy({ storyId, prNumber, blockClass }) {
+  if (blockClass === 'checks-failed') {
+    return (
+      `A required check is **red**. Fix the failure and push a new commit on \`story-${storyId}\`; ` +
+      `the red disarms auto-merge, and only a green on a new head SHA re-arms it — ` +
+      `re-running the failed job is forbidden. Watch the checks with:\n\n` +
+      `\`\`\`bash\n${NEXT_COMMANDS.watchCi(storyId, prNumber)}\n\`\`\``
+    );
+  }
+  if (
+    blockClass === ADVISORY_GATE_INCONCLUSIVE_CLASS ||
+    blockClass === ADVISORY_GATE_RED_CLASS
+  ) {
+    return advisoryGateRemedy({ storyId, blockClass });
+  }
+  return (
+    `Resolve the underlying condition (branch protection, required checks, ` +
+    `or a manual merge), then resume the land:\n\n` +
+    `\`\`\`bash\n${NEXT_COMMANDS.resumeLand(storyId)}\n\`\`\``
+  );
+}
+
 /**
  * Format the `friction` comment body posted alongside the `agent::blocked`
  * transition when a landing attempt gives up without a confirmed merge.
@@ -389,15 +489,7 @@ function formatUnlandedFriction({
     Number.isInteger(prNumber) && prNumber > 0
       ? `PR #${prNumber}${prUrl ? ` (${prUrl})` : ''}`
       : (prUrl ?? 'the PR');
-  const remedy =
-    blockClass === 'checks-failed'
-      ? `A required check is **red**. Fix the failure and push a new commit on \`story-${storyId}\`; ` +
-        `the red disarms auto-merge, and only a green on a new head SHA re-arms it — ` +
-        `re-running the failed job is forbidden. Watch the checks with:\n\n` +
-        `\`\`\`bash\n${NEXT_COMMANDS.watchCi(storyId, prNumber)}\n\`\`\``
-      : `Resolve the underlying condition (branch protection, required checks, ` +
-        `or a manual merge), then resume the land:\n\n` +
-        `\`\`\`bash\n${NEXT_COMMANDS.resumeLand(storyId)}\n\`\`\``;
+  const remedy = unlandedRemedy({ storyId, prNumber, blockClass });
   return (
     `### close-and-land: merge did not land\n\n` +
     `Story #${storyId}: the close polled ${prLabel} for merge confirmation and ` +
@@ -545,11 +637,179 @@ async function blockOnFlipFailed({
 }
 
 /**
- * Classify the unlanded merge, emit `merge.unlanded`, post a `friction`
- * comment, and transition the Story to `agent::blocked`. Every side effect
- * is best-effort logged rather than thrown — the caller owns surfacing the
- * non-zero exit once this returns.
+ * Story #5266 — the per-invocation advisory rerun allowance.
+ *
+ * `--rerun-advisory <n>` wins over `delivery.ci.rerunAdvisory` on exactly the
+ * precedence `--max-wait-seconds` already uses. Both default to **0**: a
+ * rerun spends CI minutes and mutates GitHub state, so close does neither
+ * unasked. A non-integer or negative override is not an instruction to guess
+ * — it degrades to the config value.
+ *
+ * @param {object|null} config Resolved config (or any `delivery.ci` bag).
+ * @param {number} [override] The `--rerun-advisory` value, when supplied.
+ * @returns {number} allowance ≥ 0
+ */
+export function resolveAdvisoryRerunAllowance(config, override) {
+  if (Number.isInteger(override) && override >= 0) return override;
+  return getCiDelivery(config).rerunAdvisory;
+}
+
+/**
+ * Identify ONE observation of a red run: the job, the workflow run behind it,
+ * and when that run finished. A rerun changes `completedAt` (and eventually
+ * the conclusion), so this is what lets the wait tell a re-run's verdict apart
+ * from the stale pre-rerun snapshot it will keep seeing for a poll or two.
+ *
+ * @param {{name?: string|null, runId?: number, completedAt?: string}} run
+ * @returns {string}
+ */
+function advisoryRunSignature(run) {
+  return `${run?.name ?? '(unnamed)'}@${run?.runId ?? 'no-run'}#${run?.completedAt ?? 'no-stamp'}`;
+}
+
+/**
+ * Story #5266 — read each red advisory run's own account of WHY it failed.
+ *
+ * `gh pr view --json statusCheckRollup` has a fixed projection that carries no
+ * output text for a CheckRun, so on the rollup alone every red advisory run
+ * looks identical — which is the defect. The check-runs API for the head SHA
+ * carries `output.title` / `output.summary`, and ONE call for the whole head
+ * is enough to classify every red run on it.
+ *
+ * Called only on the block path (never per poll), and **fails open**: any
+ * error, timeout, or missing head SHA returns the runs unchanged, which
+ * classifies them as `advisory-gate-red` — the pre-#5266 verdict.
+ *
+ * @returns {Promise<Array<object>>} the runs, enriched where output was found
+ */
+async function enrichRedRunsWithOutput({
+  runs,
+  headSha,
+  gh,
+  ghTimeoutMs,
+  progress,
+}) {
+  if (!Array.isArray(runs) || runs.length === 0 || !headSha) return runs ?? [];
+  try {
+    const raw = await withGhTimeout(
+      (gh ?? defaultGh).api({
+        endpoint: `/repos/{owner}/{repo}/commits/${headSha}/check-runs?per_page=100`,
+      }),
+      ghTimeoutMs,
+      `gh api check-runs ${headSha}`,
+    );
+    const payload = JSON.parse(raw?.stdout ?? '{}');
+    const byName = new Map();
+    for (const checkRun of payload?.check_runs ?? []) {
+      if (typeof checkRun?.name === 'string' && checkRun.name) {
+        byName.set(checkRun.name, checkRun);
+      }
+    }
+    return runs.map((run) => {
+      const summary = readRunSummary(run.name ? byName.get(run.name) : null);
+      return summary ? { ...run, summary } : run;
+    });
+  } catch (err) {
+    progress?.(
+      'CONFIRM',
+      `⚠️ Could not read the advisory check output (${err?.message ?? err}) — ` +
+        'classifying from the rollup alone.',
+    );
+    return runs;
+  }
+}
+
+/**
+ * Story #5266 — re-run the failed advisory workflow run(s), once, within the
+ * caller's remaining allowance.
+ *
+ * Requests `rerun-failed-jobs` per distinct workflow run rather than per job:
+ * one advisory workflow commonly fans out, and re-running the whole failed set
+ * is both cheaper in API calls and what an operator means by "re-run it".
+ *
+ * @returns {Promise<boolean>} whether every rerun request succeeded. `false`
+ *   (including "no run id to re-run") leaves the caller on the block path,
+ *   because an allowance that cannot be spent must not silently suppress the
+ *   gate.
  */
+async function rerunAdvisoryRuns({ blockingRuns, gh, ghTimeoutMs, progress }) {
+  const runIds = [
+    ...new Set(
+      blockingRuns
+        .map((run) => run?.runId ?? parseWorkflowRunId(run?.detailsUrl))
+        .filter((id) => Number.isInteger(id) && id > 0),
+    ),
+  ];
+  if (runIds.length === 0) {
+    progress?.(
+      'CONFIRM',
+      '⚠️ Advisory rerun requested but no workflow run id is readable on the ' +
+        'red run(s) — blocking instead.',
+    );
+    return false;
+  }
+  for (const runId of runIds) {
+    try {
+      await withGhTimeout(
+        (gh ?? defaultGh).api({
+          method: 'POST',
+          endpoint: `/repos/{owner}/{repo}/actions/runs/${runId}/rerun-failed-jobs`,
+        }),
+        ghTimeoutMs,
+        `gh api rerun-failed-jobs ${runId}`,
+      );
+    } catch (err) {
+      progress?.(
+        'CONFIRM',
+        `⚠️ Advisory rerun of workflow run ${runId} failed (${err?.message ?? err}) — blocking instead.`,
+      );
+      return false;
+    }
+  }
+  progress?.(
+    'CONFIRM',
+    `🔁 Re-ran ${runIds.length} failed advisory workflow run(s) [${runIds.join(', ')}] — ` +
+      'the merge wait keeps polling inside its existing budget.',
+  );
+  return true;
+}
+
+/**
+ * Spend one unit of the rerun allowance, if there is one and the rerun takes.
+ * Records the observation signature of every run it re-ran, so the stale
+ * pre-rerun snapshot the next poll reads does not re-block on the same job.
+ *
+ * Deliberately does NOT disarm first, unlike the block path: the whole point
+ * of a rerun is that a green re-run lands the PR on its own. The cost is an
+ * armed window in which GitHub could land the PR over the still-red advisory
+ * if the required contexts go green before the re-run reports — which is
+ * exactly what opting in to `--rerun-advisory` buys and accepts. At the
+ * default 0 there is no such window.
+ *
+ * @returns {Promise<boolean>} `true` when the caller should keep polling.
+ */
+async function maybeRerunAdvisory({
+  rerunState,
+  blockingRuns,
+  gh,
+  ghTimeoutMs,
+  progress,
+}) {
+  if (rerunState.remaining <= 0) return false;
+  const rerun = await rerunAdvisoryRuns({
+    blockingRuns,
+    gh,
+    ghTimeoutMs,
+    progress,
+  });
+  if (!rerun) return false;
+  rerunState.remaining -= 1;
+  for (const run of blockingRuns) {
+    rerunState.issued.add(advisoryRunSignature(run));
+  }
+  return true;
+}
+
 /**
  * Story #5096 — resolve the advisory-gate terminal for one poll.
  *
@@ -561,14 +821,22 @@ async function blockOnFlipFailed({
  *
  * Disarms BEFORE returning the terminal: an armed PR can merge out from under
  * the block the caller is about to record.
+ *
+ * Story #5266 threads three more steps through the same single assignment:
+ * runs this invocation already re-ran (and has no fresh verdict for) are
+ * skipped rather than re-blocked; the survivors are enriched with their own
+ * check-run output so the class can be `advisory-gate-inconclusive`; and a
+ * remaining rerun allowance is spent before any block is recorded.
  */
 async function resolveAdvisoryUnlanded({
   unlanded,
   probe,
   blockOnAdvisoryFailure,
   advisoryAllowlist,
+  rerunState,
   prNumber,
   gh,
+  ghTimeoutMs,
   progress,
   disarmAutoMergeFn,
   elapsedSeconds,
@@ -580,16 +848,51 @@ async function resolveAdvisoryUnlanded({
     advisoryAllowlist,
   });
   if (!advisory) return null;
-  progress?.('CONFIRM', `🛑 PR #${prNumber}: ${advisory.reason}`);
+  // Every blocking run is one this invocation already re-ran and has not seen
+  // a fresh verdict for yet (Story #5266) — keep polling rather than blocking
+  // on the snapshot the rerun was meant to replace.
+  const pending = advisory.blockingRuns.filter(
+    (run) => !rerunState.issued.has(advisoryRunSignature(run)),
+  );
+  if (pending.length === 0) return null;
+  const blockingRuns = await enrichRedRunsWithOutput({
+    runs: pending,
+    headSha: probe?.headSha,
+    gh,
+    ghTimeoutMs,
+    progress,
+  });
+  if (
+    await maybeRerunAdvisory({
+      rerunState,
+      blockingRuns,
+      gh,
+      ghTimeoutMs,
+      progress,
+    })
+  ) {
+    return null;
+  }
+  const verdict = resolveAdvisoryGateVerdict({
+    blockingRuns,
+    rerunAllowance: rerunState.allowance,
+  });
+  progress?.('CONFIRM', `🛑 PR #${prNumber}: ${verdict.reason}`);
   await disarmAutoMergeFn({ prNumber, gh, progress });
   return {
     prProbe: probe,
     budget: { exhausted: false, elapsedSeconds },
-    blockClassOverride: 'advisory-gate-red',
-    reasonOverride: advisory.reason,
+    blockClassOverride: verdict.blockClass,
+    reasonOverride: verdict.reason,
   };
 }
 
+/**
+ * Classify the unlanded merge, emit `merge.unlanded`, post a `friction`
+ * comment, and transition the Story to `agent::blocked`. Every side effect
+ * is best-effort logged rather than thrown — the caller owns surfacing the
+ * non-zero exit once this returns.
+ */
 async function blockOnUnlanded({
   storyId,
   prNumber,
@@ -853,6 +1156,8 @@ async function onMergeObserved({
  *   `--merge-watch-mode` override (Story #4949); wins over
  *   `delivery.mergeWatch.mode`.
  * @param {(tag: string, msg: string) => void} [args.progress]
+ * @param {number} [args.rerunAdvisory] `--rerun-advisory <n>` — the
+ *   per-invocation override of `delivery.ci.rerunAdvisory` (both default 0).
  * @param {object} [args.injectedGh]
  * @param {Function} [args.injectedNotify]
  * @param {Function} [args.confirmStoryMergedFn] Test seam — defaults to the
@@ -886,6 +1191,7 @@ export async function runConfirmMergePhase({
   config,
   maxWaitSeconds: maxWaitSecondsOverride,
   mergeWatchMode: mergeWatchModeOverride,
+  rerunAdvisory: rerunAdvisoryOverride,
   progress,
   injectedGh,
   injectedNotify,
@@ -923,9 +1229,12 @@ export async function runConfirmMergePhase({
       // Story #5096 — the arm phase already refused over a red advisory gate;
       // carry its verdict through instead of letting the classifier read this
       // as a generic `arm-failure`.
+      // Story #5266 — carry the arm phase's CLASS too: a pre-arm refusal over
+      // a scan that never finished is `advisory-gate-inconclusive`, and
+      // hard-coding the red class here would relabel it at the terminal.
       ...(autoMergeReason === 'advisory-gate-red'
         ? {
-            blockClassOverride: 'advisory-gate-red',
+            blockClassOverride: advisoryGate?.blockClass ?? 'advisory-gate-red',
             reasonOverride: advisoryGate?.reason,
           }
         : {}),
@@ -945,6 +1254,18 @@ export async function runConfirmMergePhase({
   );
   // Story #5096 — the advisory-gate knobs, read once for the whole wait.
   const { blockOnAdvisoryFailure, advisoryAllowlist } = getCiDelivery(config);
+  // Story #5266 — the rerun allowance and its ledger, spent across the whole
+  // wait rather than per poll, so `n` bounds the CI minutes this invocation
+  // can cost no matter how many times the gate is observed red.
+  const rerunAllowance = resolveAdvisoryRerunAllowance(
+    config,
+    rerunAdvisoryOverride,
+  );
+  const rerunState = {
+    allowance: rerunAllowance,
+    remaining: rerunAllowance,
+    issued: new Set(),
+  };
   const intervalMs = intervalSeconds * 1000;
   const startedAtMs = nowMsFn();
   let anchorMs = startedAtMs;
@@ -1105,8 +1426,10 @@ export async function runConfirmMergePhase({
         probe,
         blockOnAdvisoryFailure,
         advisoryAllowlist,
+        rerunState,
         prNumber,
         gh: injectedGh,
+        ghTimeoutMs,
         progress,
         disarmAutoMergeFn,
         elapsedSeconds: Math.round(waitedMs / 1000),