mandrel 2.35.0 → 2.37.0

package/.agents/scripts/lib/orchestration/merge-block-class.js

@@ -96,7 +96,15 @@ export const BLOCK_CLASSES = Object.freeze([
  * This is the classifier's four outputs PLUS `predicate-refused` (#4472),
  * emitted DIRECTLY for a headless refusal that never reached the
  * poll-exhaustion classifier — so it is a valid attribution value even though
- * `classifyMergeBlock` never produces it. (The Epic-era listeners that used to
+ * `classifyMergeBlock` never produces it. Story #5096 added
+ * `advisory-gate-red` on the same footing: a genuinely red NON-required check
+ * observed while GitHub reports the PR mergeable anyway
+ * (`mergeStateStatus: UNSTABLE`), which native auto-merge would land straight
+ * past. It is emitted directly by the arm and merge-wait phases — the
+ * classifier cannot produce it, because by construction GitHub is NOT blocking
+ * the merge, which is the entire problem it names. It is deliberately NOT in
+ * `BLOCK_CLASSES`, whose reachability invariant covers only what
+ * `classifyMergeBlock` returns. (The Epic-era listeners that used to
  * emit it, AutomergePredicate and AutomergeArmer, are gone; the value stays
  * because archived `merge.unlanded` records carry it and the schema enum
  * must keep validating them.) `isValidBlockClass` (and the `merge.unlanded` schema enum)
@@ -106,6 +114,7 @@ export const BLOCK_CLASSES = Object.freeze([
 export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
   ...BLOCK_CLASSES,
   'predicate-refused',
+  'advisory-gate-red',
 ]);
 
 const BLOCK_CLASS_SET = new Set(MERGE_UNLANDED_BLOCK_CLASSES);

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

@@ -243,6 +243,170 @@ export function requiredCheckFailedBlocksMerge(prProbe) {
   );
 }
 
+/**
+ * The one `mergeStateStatus` value that means the PR is mergeable **despite**
+ * red runs — GitHub's own words are "mergeable with non-passing commit
+ * status". It is the required-vs-advisory discriminator the rollup itself
+ * cannot supply: under `UNSTABLE` the red runs are, by definition, not
+ * required, so native auto-merge will land the PR over them.
+ *
+ * The exact complement of {@link MERGE_GATED_STATE}: `BLOCKED` means the red
+ * run gates the merge (`failingChecksBlockMerge`), `UNSTABLE` means it does
+ * not and only mandrel can stop the landing.
+ */
+const MERGE_ADVISORY_STATE = 'UNSTABLE';
+
+/**
+ * Pure: project the HEAD-ANCHORED runs that genuinely concluded red, naming
+ * each one (Story #5096).
+ *
+ * Same red-ness test as {@link deriveRequiredRunEvidence} — `FAILURE` /
+ * `ERROR` only, never `CANCELLED` / `TIMED_OUT` / `SKIPPED`, which are the
+ * superseded-push and sibling-invalidated runs a bare rollup read miscounts
+ * (the #4695 / #4710 trap) — but it returns the runs rather than a boolean, so
+ * a block summary can name the offending job and the advisory allowlist can
+ * match on it.
+ *
+ * `name` is the CheckRun's `name`, falling back to a legacy StatusContext's
+ * `context`, and is `null` when the projection carries neither. A run with no
+ * readable name can never match an allowlist entry, so it always blocks — the
+ * conservative direction for a gate whose whole purpose is to stop a silent
+ * landing.
+ *
+ * @param {Array<{name?: string, context?: string, status?: string, conclusion?: string, state?: string}>} statusCheckRollup
+ * @returns {Array<{ name: string|null, conclusion: string }>}
+ */
+export function deriveRedHeadRuns(statusCheckRollup) {
+  if (!Array.isArray(statusCheckRollup)) return [];
+  const red = [];
+  for (const check of statusCheckRollup) {
+    const conclusion = String(check?.conclusion ?? '').toUpperCase();
+    const state = String(check?.state ?? '').toUpperCase();
+    const isRed =
+      conclusion === 'FAILURE' ||
+      conclusion === 'ERROR' ||
+      state === 'FAILURE' ||
+      state === 'ERROR';
+    if (!isRed) continue;
+    const name =
+      typeof check?.name === 'string' && check.name
+        ? check.name
+        : typeof check?.context === 'string' && check.context
+          ? check.context
+          : null;
+    red.push({ name, conclusion: conclusion || state });
+  }
+  return red;
+}
+
+/**
+ * Pure: drop the red runs a consumer has exempted via
+ * `delivery.ci.advisoryAllowlist`, returning the ones that still block.
+ *
+ * Matching is exact on the run name. An unnamed run never matches (see
+ * {@link deriveRedHeadRuns}).
+ *
+ * @param {Array<{ name: string|null, conclusion: string }>} redHeadRuns
+ * @param {string[]} [allowlist]
+ * @returns {Array<{ name: string|null, conclusion: string }>}
+ */
+export function selectBlockingRedRuns(redHeadRuns, allowlist = []) {
+  if (!Array.isArray(redHeadRuns) || redHeadRuns.length === 0) return [];
+  const exempt = new Set(
+    (Array.isArray(allowlist) ? allowlist : [])
+      .filter((entry) => typeof entry === 'string' && entry)
+      .map((entry) => entry),
+  );
+  if (exempt.size === 0) return [...redHeadRuns];
+  return redHeadRuns.filter((run) => !(run?.name && exempt.has(run.name)));
+}
+
+/**
+ * Pure: does this PR carry a genuinely red ADVISORY run — one that will NOT
+ * stop GitHub from landing the PR, and therefore one only mandrel can act on?
+ * (Story #5096.)
+ *
+ * The complement of {@link requiredCheckFailedBlocksMerge}. That predicate
+ * answers "is a red REQUIRED check gating the merge" (`BLOCKED`); this one
+ * answers "is a red NON-required check about to be merged straight past"
+ * (`UNSTABLE`). The two are mutually exclusive by construction, so a red
+ * required check keeps its existing `checks-failed` treatment untouched.
+ *
+ * **Fails OPEN by design.** `UNKNOWN`, `CLEAN`, `BEHIND`, or an absent
+ * `mergeStateStatus` all return `false`. The asymmetry is the same one
+ * {@link failingChecksBlockMerge} documents and is deliberate: failing to
+ * block costs an unattended landing the operator can still revert, whereas
+ * blocking wrongly strands a mergeable PR at `agent::blocked` that only an
+ * operator can unpick. A transient `UNKNOWN` must never do the latter.
+ *
+ * @param {{ mergeStateStatus?: string, redHeadRuns?: Array<{name: string|null, conclusion: string}> }} [prProbe]
+ * @param {string[]} [allowlist] `delivery.ci.advisoryAllowlist`.
+ * @returns {boolean}
+ */
+export function advisoryCheckFailedBlocksArm(prProbe, allowlist = []) {
+  if (
+    String(prProbe?.mergeStateStatus ?? '').toUpperCase() !==
+    MERGE_ADVISORY_STATE
+  ) {
+    return false;
+  }
+  return selectBlockingRedRuns(prProbe?.redHeadRuns, allowlist).length > 0;
+}
+
+/**
+ * Pure: the merge wait's advisory-gate decision, the sibling of
+ * {@link decideMergeWaitFailFast} (Story #5096).
+ *
+ * Encapsulates the whole policy — the knob, the predicate, and the allowlist
+ * projection — so the poll body carries a single assignment rather than three
+ * decision points. `runMergePoll` sits above `check-cyclomatic`'s ceiling
+ * already; every branch added inline there is a real regression, and this
+ * policy has a natural home beside the predicate it consumes.
+ *
+ * Returns `null` when the wait should keep polling — the knob is off, the PR
+ * is not in the advisory-red state, or every red run is allowlisted.
+ *
+ * @param {object} args
+ * @returns {{ blockingRuns: Array<object>, reason: string } | null}
+ */
+export function decideAdvisoryGateBlock({
+  probe,
+  blockOnAdvisoryFailure,
+  advisoryAllowlist,
+}) {
+  if (!blockOnAdvisoryFailure) return null;
+  if (!advisoryCheckFailedBlocksArm(probe, advisoryAllowlist)) return null;
+  const blockingRuns = selectBlockingRedRuns(
+    probe?.redHeadRuns,
+    advisoryAllowlist,
+  );
+  return { blockingRuns, reason: formatAdvisoryGateReason(blockingRuns) };
+}
+
+/**
+ * Format the one-line reason a `merge.unlanded` record and the operator-facing
+ * block carry for an `advisory-gate-red` verdict, naming each offending job
+ * and its conclusion.
+ *
+ * @param {Array<{ name: string|null, conclusion: string }>} blockingRuns
+ * @returns {string}
+ */
+export function formatAdvisoryGateReason(blockingRuns) {
+  const named = (Array.isArray(blockingRuns) ? blockingRuns : [])
+    .map(
+      (run) =>
+        `${run?.name ?? '(unnamed run)'} → ${run?.conclusion ?? 'FAILURE'}`,
+    )
+    .join(', ');
+  return (
+    'A non-required (advisory) check concluded red on the PR head, and GitHub ' +
+    'reports the PR mergeable anyway (mergeStateStatus=UNSTABLE) — native ' +
+    'auto-merge would land it over the failure. Red advisory job(s): ' +
+    `${named || '(none named)'}. Merge by hand to land over it deliberately, ` +
+    'or exempt the job via delivery.ci.advisoryAllowlist.'
+  );
+}
+
 /**
  * Pure: the merge wait's single fail-fast decision (Story #4710 — extracted
  * from the two near-verbatim inline blocks in `runConfirmMergePhase`'s poll

package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js

@@ -197,6 +197,26 @@ function planFingerprintMarker(fingerprint) {
   return `<!-- ${PLAN_FINGERPRINT_MARKER_PREFIX} ${fingerprint} -->`;
 }
 
+/** The one parser for the marker {@link planFingerprintMarker} renders. */
+const PLAN_FINGERPRINT_MARKER_RE = new RegExp(
+  `<!--\\s*${PLAN_FINGERPRINT_MARKER_PREFIX}\\s*([0-9a-f]+)\\s*-->`,
+);
+
+/**
+ * Recover the plan fingerprint an issue body was stamped with, or `null` when
+ * the body carries no marker. Module-private: both readers of the marker (the
+ * resume index and the create-retry adoption probe) go through it so they can
+ * never drift into recognising different Stories as "already created".
+ *
+ * @param {unknown} body
+ * @returns {string|null}
+ */
+function extractPlanFingerprint(body) {
+  if (typeof body !== 'string') return null;
+  const match = body.match(PLAN_FINGERPRINT_MARKER_RE);
+  return match ? match[1] : null;
+}
+
 /**
  * Labels the authoring pass is never allowed to set. The `agent::*` axis is
  * the runtime's lifecycle state (persist owns the terminal `agent::ready`
@@ -617,14 +637,9 @@ async function indexExistingStories(provider) {
     if (title !== '') {
       idsByTitle.set(title, [...(idsByTitle.get(title) ?? []), id]);
     }
-    const body = typeof issue?.body === 'string' ? issue.body : '';
-    const match = body.match(
-      new RegExp(
-        `<!--\\s*${PLAN_FINGERPRINT_MARKER_PREFIX}\\s*([0-9a-f]+)\\s*-->`,
-      ),
-    );
-    if (!match) continue;
-    byFingerprint.set(match[1], {
+    const fingerprint = extractPlanFingerprint(issue?.body);
+    if (!fingerprint) continue;
+    byFingerprint.set(fingerprint, {
       id,
       title,
       url: issue.html_url ?? issue.url ?? undefined,
@@ -633,6 +648,42 @@ async function indexExistingStories(provider) {
   return { byFingerprint, idsByTitle };
 }
 
+/**
+ * Re-run the resume lookup for a single fingerprint and return the **raw**
+ * issue, or `null`.
+ *
+ * This is the probe `createIssue` calls before any retry POST (Story #5112).
+ * A create whose response was lost has already filed the issue; retrying
+ * blind duplicates it. Because the body posted carries the fingerprint
+ * marker, the same content-keyed lookup the resume path uses answers "did
+ * attempt 1 land?" authoritatively — from the server's state, not from a
+ * client-side guess about where the connection broke.
+ *
+ * Best-effort like {@link indexExistingStories}: a provider without the
+ * listing surface, or a listing that throws, yields `null` and the retry
+ * proceeds exactly as it did before.
+ *
+ * @param {{ provider: object, fingerprint: string }} args
+ * @returns {Promise<object|null>}
+ */
+async function findOpenStoryByPlanFingerprint({ provider, fingerprint }) {
+  if (typeof provider?.listIssuesByLabel !== 'function') return null;
+  if (typeof fingerprint !== 'string' || fingerprint.length === 0) return null;
+  let issues;
+  try {
+    issues = await provider.listIssuesByLabel({
+      state: 'open',
+      labels: TYPE_LABELS.STORY,
+    });
+  } catch {
+    return null;
+  }
+  for (const issue of Array.isArray(issues) ? issues : []) {
+    if (extractPlanFingerprint(issue?.body) === fingerprint) return issue;
+  }
+  return null;
+}
+
 /**
  * Warn when a Story with this title is already open but did **not** match the
  * fingerprint — i.e. its authored content differs from what this run is about
@@ -1000,6 +1051,14 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
         ...(applyCohortLabel ? [cohortLabel] : []),
         ...(applyRouteLabel ? [routeLabel] : []),
       ],
+      // Story #5112 — hand the provider the same content-keyed lookup this
+      // loop's resume path uses, so a retry after a lost response adopts the
+      // issue attempt 1 already filed instead of creating a twin.
+      findExisting: () =>
+        findOpenStoryByPlanFingerprint({
+          provider,
+          fingerprint: story.fingerprint,
+        }),
     });
     const id = result?.id ?? result?.number;
     if (!Number.isInteger(id)) {
@@ -1012,7 +1071,9 @@ export async function createStoryIssues({ provider, stories, opts = {} }) {
       id,
       title: story.title,
       url: result.url,
-      adopted: false,
+      // True when the provider's retry probe adopted an issue a lost-response
+      // first attempt had already filed — pre-existing either way.
+      adopted: result.adopted === true,
     });
     idBySlug.set(story.slug, id);
   }

package/.agents/scripts/lib/orchestration/pr-watch.js

@@ -50,35 +50,6 @@ import { applyBehindUpdate } from './behind-recovery.js';
  * values collapse to `'skipped'` so any future GitHub state we haven't
  * enumerated still maps into the vocabulary.
  */
-/**
- * The raw check-state tokens `normalizeCheckState` recognizes (lowercased).
- * A token absent from this set is one we have NOT enumerated — the watch
- * path collapses it to `'skipped'` (validate-anything), but a fail-closed
- * consumer (the auto-merge arming probe) must treat it as unknown-therefore-
- * blocking rather than trust the `'skipped'` collapse. Exported so that
- * stricter consumer lives here as the single vocabulary owner.
- */
-export const RECOGNIZED_CHECK_STATES = Object.freeze(
-  new Set([
-    '',
-    'pending',
-    'queued',
-    'in_progress',
-    'requested',
-    'waiting',
-    'success',
-    'completed',
-    'failure',
-    'startup_failure',
-    'neutral',
-    'cancelled',
-    'timed_out',
-    'action_required',
-    'stale',
-    'skipped',
-  ]),
-);
-
 export function normalizeCheckState(raw) {
   const v = String(raw ?? '')
     .trim()
@@ -325,7 +296,7 @@ export function allTerminal(outcomes) {
  * red check): a `'still-running'` map means "re-arm the watch / hand off
  * to `/loop`," never "the change is broken."
  */
-export const STILL_RUNNING = 'still-running';
+const STILL_RUNNING = 'still-running';
 
 /**
  * Promote any leftover `'pending'` outcomes to the schema-valid

package/.agents/scripts/lib/orchestration/reassert-status-column.js

@@ -38,14 +38,14 @@ import { ColumnSync, columnForLabels } from './column-sync.js';
  * long enough to outlast the typical GitHub built-in workflow fire
  * timing without ballooning the close-path wall clock.
  */
-export const DEFAULT_POLL_ATTEMPTS = 4;
+const DEFAULT_POLL_ATTEMPTS = 4;
 
 /**
  * Default delay between drift checks (ms). Five seconds is a sweet
  * spot: short enough that the operator doesn't perceive the close
  * path as hung, long enough that one re-fire usually wins the race.
  */
-export const DEFAULT_POLL_DELAY_MS = 5000;
+const DEFAULT_POLL_DELAY_MS = 5000;
 
 /**
  * Production sleep function. Tests inject `sleepFn: () => Promise.resolve()`

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

@@ -57,7 +57,7 @@ export const CODEX_REMEDIATIONS = Object.freeze({
  *
  * Exported so tests can extend the list without monkey-patching `os`.
  */
-export const DEFAULT_PLUGIN_MARKERS = Object.freeze([
+const DEFAULT_PLUGIN_MARKERS = Object.freeze([
   path.join(os.homedir(), '.claude', 'plugins', 'codex-plugin-cc'),
   path.join(os.homedir(), '.claude', 'plugins', 'openai', 'codex-plugin-cc'),
 ]);
@@ -194,7 +194,7 @@ export function parseCodexFindings(rawStdout) {
  * @param {{ baseRef: string, headRef: string, depth?: import('./types.js').ReviewDepth }} args
  * @returns {string}
  */
-export function buildCodexReviewPrompt({ baseRef, headRef, depth }) {
+function buildCodexReviewPrompt({ baseRef, headRef, depth }) {
   return (
     `/codex:review --base ${baseRef} --head ${headRef} --wait ` +
     `${renderDepthDirective(depth)}`
@@ -214,7 +214,7 @@ export function buildCodexReviewPrompt({ baseRef, headRef, depth }) {
  * @param {{ baseRef: string, headRef: string, depth?: import('./types.js').ReviewDepth }} args
  * @returns {{ status: number, stdout: string, stderr: string }}
  */
-export function defaultInvokeCodexReview({ baseRef, headRef, depth }) {
+function defaultInvokeCodexReview({ baseRef, headRef, depth }) {
   const cliArgs = [
     '--print',
     buildCodexReviewPrompt({ baseRef, headRef, depth }),

package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js

@@ -102,7 +102,7 @@ export function renderFinding(finding) {
  * @param {ReadonlyArray<string>} messages
  * @returns {string[]}  lines to append (empty when no messages)
  */
-export function renderManualPromptsSection(messages) {
+function renderManualPromptsSection(messages) {
   const filtered = Array.isArray(messages)
     ? messages.filter((m) => typeof m === 'string' && m.trim().length > 0)
     : [];

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

@@ -267,8 +267,14 @@ function isJsMaintainabilityFile(relPath) {
  * `reportFn` forces the serial path (the injected scorer cannot cross the
  * worker boundary).
  *
+ * `serialThreshold` overrides the pool-vs-serial cutover for one call. It is
+ * the seam the parity test uses to drive the pooled branch: Story #5109
+ * retuned `POOL_SERIAL_THRESHOLD` from 8 to 256 against measured data, and a
+ * fixture sized to clear the old number would otherwise have gone quietly
+ * serial while still claiming to cover the pool.
+ *
  * @param {string[]} changedFiles
- * @param {{ reportFn?: Function, classifier?: Function, runOnPoolFn?: typeof runOnPool, headRef?: string|null, gitSpawnFn?: typeof gitSpawn, readHeadSourceFn?: typeof readHeadSource }} [deps]
+ * @param {{ reportFn?: Function, classifier?: Function, runOnPoolFn?: typeof runOnPool, headRef?: string|null, gitSpawnFn?: typeof gitSpawn, readHeadSourceFn?: typeof readHeadSource, serialThreshold?: number }} [deps]
  * @returns {Promise<{ totalFiles: number, jsFiles: number, maintainability: object[], criticalFindings: Finding[], mediumFindings: Finding[] }>}
  */
 export async function analyzeChangedFiles(
@@ -280,6 +286,7 @@ export async function analyzeChangedFiles(
     headRef = null,
     gitSpawnFn = gitSpawn,
     readHeadSourceFn = readHeadSource,
+    serialThreshold = SERIAL_THRESHOLD,
   } = {},
 ) {
   const results = {
@@ -308,7 +315,7 @@ export async function analyzeChangedFiles(
   const customReportFn = reportFn != null;
 
   // Serial path: small batches, or whenever a caller injects its own scorer.
-  if (jsFiles.length < SERIAL_THRESHOLD || customReportFn) {
+  if (jsFiles.length < serialThreshold || customReportFn) {
     for (let i = 0; i < jsFiles.length; i += 1) {
       const relPath = jsFiles[i];
       const source = sources[i];

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

@@ -28,7 +28,7 @@
  *
  * @type {Readonly<Record<ReviewDepth, string>>}
  */
-export const DEPTH_DIRECTIVES = Object.freeze({
+const DEPTH_DIRECTIVES = Object.freeze({
   light:
     'Review depth: LIGHT. Run a single pass focused on spec adherence over the ' +
     'changed surface — confirm the change matches its stated intent. Reduce the ' +
@@ -54,7 +54,7 @@ export const DEPTH_DIRECTIVES = Object.freeze({
  * @param {unknown} depth
  * @returns {ReviewDepth}
  */
-export function normalizeDepth(depth) {
+function normalizeDepth(depth) {
   return depth === 'light' || depth === 'deep' ? depth : 'standard';
 }
 

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

@@ -59,7 +59,7 @@ export const SECURITY_REVIEW_REMEDIATIONS = Object.freeze({
  * @param {{ spawnFn?: typeof spawnSync }} [opts]
  * @returns {boolean}
  */
-export function defaultProbeClaudeCli(opts = {}) {
+function defaultProbeClaudeCli(opts = {}) {
   const spawnFn = opts.spawnFn ?? spawnSync;
   try {
     const result = spawnFn('claude', ['--version'], {
@@ -162,7 +162,7 @@ export function parseSecurityReviewFindings(rawStdout) {
  * (Story #3937) so a high-risk Epic instructs the model toward a deeper
  * second-pass review while a low-risk one keeps it light.
  */
-export const SECURITY_REVIEW_INVOKE_PROMPT =
+const SECURITY_REVIEW_INVOKE_PROMPT =
   'Run /security-review against the diff `{baseRef}`...`{headRef}` ' +
   'for {scopeLabel} #{ticketId}. {depthDirective} After the review, emit ' +
   'ONLY a JSON array of findings on stdout with this exact shape:\n\n' +
@@ -208,7 +208,7 @@ export function buildSecurityReviewPrompt(input) {
  * @param {ReviewInput} input
  * @returns {{ status: number, stdout: string, stderr: string }}
  */
-export function defaultInvokeSecurityReview(input) {
+function defaultInvokeSecurityReview(input) {
   const prompt = buildSecurityReviewPrompt(input);
   const result = spawnSync('claude', ['--print', prompt], {
     encoding: 'utf-8',

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

@@ -63,6 +63,12 @@
 
 import { gh as defaultGh } from '../../../gh-exec.js';
 import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
+import {
+  advisoryCheckFailedBlocksArm,
+  deriveRedHeadRuns,
+  formatAdvisoryGateReason,
+  selectBlockingRedRuns,
+} from '../../merge-poll.js';
 
 /**
  * Arm reasons that mean **the operator deliberately owns the merge** — the PR
@@ -321,6 +327,116 @@ function makeDefaultGhAutoMergeRunner(gh) {
   };
 }
 
+/**
+ * Evaluate the pre-arm advisory-gate verdict (Story #5096).
+ *
+ * GitHub native auto-merge is defined to wait on REQUIRED contexts only, so a
+ * red ADVISORY quality gate — a coverage, mutation, duplication, a11y or
+ * bundle-size ratchet a consumer deliberately left non-required — is merged
+ * straight past once the required contexts go green. The arming decision is
+ * mandrel's, not GitHub's, so this is where it has to be made.
+ *
+ * Reads the SAME head-anchored derivation the merge wait uses
+ * (`readPrWaitProbe` → `deriveRedHeadRuns`), so a `CANCELLED` superseded-push
+ * run or a sibling-invalidated run is never mistaken for a red gate (the
+ * #4695 / #4710 trap), and `mergeStateStatus: UNSTABLE` supplies the
+ * required-vs-advisory discrimination the rollup itself lacks.
+ *
+ * **Non-fatal and fail-open in every degraded case.** A probe error, an absent
+ * or `UNKNOWN` merge state, or a disabled knob all return "do not block" — the
+ * arm proceeds exactly as it did before this Story. Only a positive verdict
+ * refuses.
+ *
+ * @param {object} args
+ * @returns {Promise<{ blocked: boolean, blockingRuns?: Array<object>, reason?: string }>}
+ */
+async function readAdvisoryProbe({ prNumber, gh }) {
+  const view = await (gh ?? defaultGh).pr.view(prNumber, [
+    'mergeStateStatus',
+    'statusCheckRollup',
+  ]);
+  return {
+    mergeStateStatus:
+      typeof view?.mergeStateStatus === 'string'
+        ? view.mergeStateStatus
+        : undefined,
+    redHeadRuns: deriveRedHeadRuns(view?.statusCheckRollup),
+  };
+}
+
+/**
+ * Disarm GitHub native auto-merge on a PR (Story #5096).
+ *
+ * Lives here, beside the arm, because `lifecycle-lint`'s merge-lockout rule
+ * confines every `gh pr merge` invocation to this module: auto-merge
+ * enablement — and therefore its reversal — must flow through the Story close
+ * path rather than being spelled out wherever a caller happens to need it.
+ * The merge wait imports this rather than shelling out itself.
+ *
+ * Best-effort by contract: the caller blocks the Story either way, and a
+ * failed disarm is reported rather than thrown, because the one thing it
+ * cannot do is stop GitHub from landing the PR.
+ *
+ * @returns {Promise<boolean>} whether the disarm actually took.
+ */
+export async function disarmAutoMerge({ prNumber, gh, progress }) {
+  try {
+    await (gh ?? defaultGh).pr.merge(String(prNumber), ['--disable-auto']);
+    progress?.(
+      'CONFIRM',
+      `🔓 Auto-merge DISARMED on PR #${prNumber} — the PR stays open and hand-mergeable.`,
+    );
+    return true;
+  } catch (err) {
+    progress?.(
+      'CONFIRM',
+      `⚠️ Could not disarm auto-merge on PR #${prNumber} (${err?.message ?? err}) — ` +
+        'GitHub may still land it when the required checks pass. Disarm by hand.',
+    );
+    return false;
+  }
+}
+
+async function evaluateAdvisoryGate({
+  prNumber,
+  gh,
+  blockOnAdvisoryFailure,
+  advisoryAllowlist,
+  readPrWaitProbeFn,
+  progress,
+}) {
+  if (!blockOnAdvisoryFailure) return { blocked: false };
+  let probe;
+  try {
+    probe = await readPrWaitProbeFn({ prNumber, gh });
+  } catch (err) {
+    progress?.(
+      'PR',
+      `⚠️ Advisory-gate probe failed (${err?.message ?? err}) — arming anyway.`,
+    );
+    return { blocked: false };
+  }
+  if (probe?.error) {
+    progress?.(
+      'PR',
+      `⚠️ Advisory-gate probe unavailable (${probe.error}) — arming anyway.`,
+    );
+    return { blocked: false };
+  }
+  if (!advisoryCheckFailedBlocksArm(probe, advisoryAllowlist)) {
+    return { blocked: false };
+  }
+  const blockingRuns = selectBlockingRedRuns(
+    probe.redHeadRuns,
+    advisoryAllowlist,
+  );
+  return {
+    blocked: true,
+    blockingRuns,
+    reason: formatAdvisoryGateReason(blockingRuns),
+  };
+}
+
 /**
  * Dispatch auto-merge enablement based on `--no-auto-merge`, an
  * unparseable PR number, or a `gh` failure. Returns the structured
@@ -347,8 +463,11 @@ export async function runAutoMergePhase({
   prUrl,
   noAutoMerge,
   autoMergePolicy = 'trust-ci',
+  blockOnAdvisoryFailure = true,
+  advisoryAllowlist = [],
   gh,
   progress,
+  readPrWaitProbeFn = readAdvisoryProbe,
 }) {
   if (noAutoMerge) {
     progress('PR', '⏭  Auto-merge disabled (--no-auto-merge).');
@@ -381,6 +500,32 @@ export async function runAutoMergePhase({
       autoMergeReason: 'pr-number-unparseable',
     };
   }
+  // Story #5096 — refuse to arm over a genuinely red ADVISORY check. This
+  // gate covers the narrow case where the gate is ALREADY red at close time
+  // (a re-close, or a gate carried over from an earlier push); the merge
+  // wait owns the common case, where the gate reddens after arming.
+  const advisory = await evaluateAdvisoryGate({
+    prNumber,
+    gh,
+    blockOnAdvisoryFailure,
+    advisoryAllowlist,
+    readPrWaitProbeFn,
+    progress,
+  });
+  if (advisory.blocked) {
+    progress(
+      'PR',
+      `🛑 Auto-merge NOT armed on PR #${prNumber}: ${advisory.reason}`,
+    );
+    return {
+      autoMergeEnabled: false,
+      autoMergeReason: 'advisory-gate-red',
+      advisoryGate: {
+        blockingRuns: advisory.blockingRuns,
+        reason: advisory.reason,
+      },
+    };
+  }
   const result = await enableAutoMergeWith({ cwd, prNumber, gh });
   if (result.enabled) {
     if (result.directMerged) {