mandrel 2.63.0 → 2.65.0

package/.agents/scripts/lib/observability/metrics-ledger.js

@@ -12,13 +12,11 @@ import {
   runArtifactPath,
   tempRootFrom,
 } from '../config/temp-paths.js';
-import { Logger } from '../Logger.js';
 
 export const PLAN_METRICS_BASENAME = 'plan-metrics.json';
 export const PLAN_METRICS_SCHEMA_VERSION = 1;
 
 /** Evidence for dropping a lens that stays at zero findings. */
-const PLAN_METRICS_KIND_FINDINGS_YIELD = 'findings-yield';
 
 /** ~5000 records; rotation only fires on pathological accumulation. */
 export const MAX_LEDGER_BYTES = 1024 * 1024;
@@ -85,73 +83,3 @@ export async function appendLedgerRecord(record, opts = {}) {
   );
   await fs.appendFile(filePath, line, 'utf8');
 }
-
-/**
- * Append one findings-yield record. Never throws.
- *
- * @param {{
- *   storyId: number,
- *   lenses: Array<{ lens: string, findings?: number, skippedByFloor?: boolean }>,
- *   cli?: string,
- *   epicId?: number|null,
- *   diffFloor?: object|null,
- * }} entry
- * @param {object} [config]
- * @param {{ maxBytes?: number }} [opts]
- * @returns {Promise<boolean>} true when the line was written.
- */
-export async function appendFindingsYield(entry, config, opts = {}) {
-  try {
-    if (!entry || typeof entry !== 'object') {
-      throw new TypeError('appendFindingsYield requires an entry object');
-    }
-    const storyId = Number(entry.storyId);
-    if (!Number.isInteger(storyId) || storyId <= 0) {
-      throw new TypeError(
-        'appendFindingsYield requires a positive integer entry.storyId',
-      );
-    }
-    if (!Array.isArray(entry.lenses) || entry.lenses.length === 0) {
-      throw new TypeError(
-        'appendFindingsYield requires a non-empty entry.lenses array',
-      );
-    }
-    const epicId = entry.epicId ?? null;
-    const record = {
-      v: PLAN_METRICS_SCHEMA_VERSION,
-      kind: PLAN_METRICS_KIND_FINDINGS_YIELD,
-      cli:
-        typeof entry.cli === 'string' && entry.cli.length > 0
-          ? entry.cli
-          : 'story-close-review',
-      storyId,
-      epicId,
-      lenses: entry.lenses
-        .filter((l) => l && typeof l.lens === 'string' && l.lens.length > 0)
-        .map((l) => ({
-          lens: l.lens,
-          findings:
-            typeof l.findings === 'number' && Number.isFinite(l.findings)
-              ? l.findings
-              : 0,
-          skippedByFloor: l.skippedByFloor === true,
-        })),
-      diffFloor:
-        entry.diffFloor && typeof entry.diffFloor === 'object'
-          ? entry.diffFloor
-          : null,
-      at: new Date().toISOString(),
-    };
-    await appendLedgerRecord(record, {
-      epicId,
-      config,
-      maxBytes: opts.maxBytes,
-    });
-    return true;
-  } catch (err) {
-    Logger.warn(
-      `[plan-metrics] findings-yield append failed (non-fatal): ${err?.message ?? err}`,
-    );
-    return false;
-  }
-}

package/.agents/scripts/lib/orchestration/ci-red-handling.js

@@ -0,0 +1,73 @@
+// .agents/scripts/lib/orchestration/ci-red-handling.js
+/**
+ * ci-red-handling.js — the first-red half of the no-rerun guard in
+ * `rules/ci-remediation.md` § Verifier, shared by every path that observes a
+ * red required check: the watcher (`pr-watch-with-update.js`) and the
+ * close-and-land merge wait's `checks-failed` fail-fast. The digest itself
+ * lives in `ci-rerun-guard.js`.
+ */
+
+import { Logger } from '../Logger.js';
+import {
+  resolveDigestScope,
+  resolvePrHeadSha,
+  writeCiDigest,
+} from './ci-rerun-guard.js';
+
+/**
+ * The first-red handling every required-check red goes through — the
+ * watcher's red path and the close's `checks-failed` fail-fast alike: disarm
+ * auto-merge FIRST (the race-free moment), then write the digest keyed to the
+ * red head SHA. One implementation, so the guard cannot drift per path.
+ * Never throws: a digest-write failure is returned as `digestError`.
+ *
+ * @param {object} opts
+ * @param {number|string|null} [opts.storyId]
+ * @param {number} opts.prNumber
+ * @param {string} opts.prRef
+ * @param {Array<{name:string, outcome:string}>} opts.failures
+ * @param {string} opts.tempRoot
+ * @param {string} opts.cwd
+ * @param {(args: { prRef: string }) => Promise<{ disarmed: boolean, alreadyUnarmed?: boolean, detail: string }>} opts.disarmFn
+ * @param {string|null} [opts.headSha] Already-observed head SHA; probed when absent.
+ * @param {Function} [opts.headShaFn]
+ * @param {Function} [opts.writeDigestFn]
+ * @param {object} [opts.logger]
+ * @returns {Promise<{ headSha: string|null, disarm: object, digestPaths: { jsonPath: string, mdPath: string }|null, digestError: string|null }>}
+ */
+export async function recordRequiredRed({
+  storyId = null,
+  prNumber,
+  prRef,
+  failures,
+  tempRoot,
+  cwd,
+  disarmFn,
+  headSha = null,
+  headShaFn = resolvePrHeadSha,
+  writeDigestFn = writeCiDigest,
+  logger = Logger,
+}) {
+  const disarm = await disarmFn({ prRef });
+  const scope = resolveDigestScope({ storyId });
+  const redHeadSha = scope ? (headSha ?? headShaFn({ prRef, cwd })) : null;
+  let digestPaths = null;
+  let digestError = null;
+  try {
+    digestPaths = writeDigestFn({
+      storyId,
+      prNumber,
+      headSha: redHeadSha,
+      failures,
+      tempRoot,
+      cwd,
+      prRef,
+    });
+  } catch (err) {
+    digestError = String(err?.message ?? err);
+    logger?.warn?.(
+      `[ci-rerun-guard] failed to write CI digest (non-fatal): ${digestError}`,
+    );
+  }
+  return { headSha: redHeadSha, disarm, digestPaths, digestError };
+}

package/.agents/scripts/lib/orchestration/code-review.js

@@ -116,12 +116,17 @@ function resolveScopeEnvelope(opts, config) {
  *   blockerReason: string|null,
  * }>}
  */
-/** Display name: the single entry's name, `chain[a,b]`, or `'native'`. */
-function resolveProviderName(codeReviewConfig) {
+/**
+ * Display name: the single entry's name, `chain[a,b]`, or `'native'`. An
+ * unset chain names the entries the factory actually built, so a skipped
+ * optional provider is not reported as having run.
+ */
+function resolveProviderName(codeReviewConfig, reviewProvider) {
+  const configured = Array.isArray(codeReviewConfig?.providers)
+    ? codeReviewConfig.providers
+    : [];
   const providers =
-    codeReviewConfig && Array.isArray(codeReviewConfig.providers)
-      ? codeReviewConfig.providers
-      : [];
+    configured.length > 0 ? configured : (reviewProvider?.chain?.inline ?? []);
   if (providers.length === 1) {
     return providers[0]?.name ?? 'native';
   }
@@ -236,9 +241,9 @@ async function executeReviewPipeline({ opts, config, envelope }) {
   const { scope, ticketId, baseRef, headRef, commentTargetId } = envelope;
 
   const codeReviewConfig = config?.delivery?.codeReview ?? null;
-  const providerName = resolveProviderName(codeReviewConfig);
   const reviewProvider =
     injectedReviewProvider ?? createReviewProviderFn(codeReviewConfig);
+  const providerName = resolveProviderName(codeReviewConfig, reviewProvider);
 
   logger?.info?.(
     `[code-review] Running ${providerName} adapter for Story #${ticketId} (${baseRef}...${headRef})...`,

package/.agents/scripts/lib/orchestration/deliver-recover.js

@@ -13,7 +13,11 @@ import {
 } from '../config/temp-paths.js';
 import { gh as defaultGh } from '../gh-exec.js';
 import { gitSpawn as defaultGitSpawn, getStoryBranch } from '../git-utils.js';
-import { deriveChecksStatus, isPrMerged } from './merge-poll.js';
+import {
+  CHECKS_FAILED_CLASS,
+  deriveChecksStatus,
+  isPrMerged,
+} from './merge-poll.js';
 import { NEXT_COMMANDS } from './story-deliver-terminal.js';
 import { STATE_LABELS } from './ticketing.js';
 
@@ -302,6 +306,56 @@ function decideExecuting({ storyId, branch, pr, closeArtifacts, evidence }) {
   };
 }
 
+/**
+ * A close that blocked on a red required check disarmed auto-merge and wrote
+ * the CI digest, so the next step is the ci-remediation loop — never this
+ * probe again. `null` for every other blocked class (or with no PR to watch).
+ *
+ * @returns {{ shape: string, nextCommand: string, detail: string, evidence: string[] } | null}
+ */
+function decideBlockedChecksFailed({ storyId, pr, closeArtifacts, evidence }) {
+  const envelope = closeArtifacts?.envelope;
+  if (envelope?.blocked?.blockClass !== CHECKS_FAILED_CLASS) return null;
+  const prNumber = pr?.number ?? envelope?.pr?.number ?? null;
+  if (!prNumber) return null;
+  return {
+    shape: 'blocked-checks-failed',
+    nextCommand: NEXT_COMMANDS.watchCi(storyId, prNumber),
+    detail:
+      `Story is \`agent::blocked\` because a required check on PR #${prNumber} went red. ` +
+      `The close disarmed auto-merge and wrote the CI digest ` +
+      `(\`story-${storyId}-ci-digest.json\` under the configured tempRoot). Per ` +
+      `\`.agents/rules/ci-remediation.md\`, either fix the failure at source and push a new ` +
+      `commit on \`story-${storyId}\`, or — when the root cause is outside this delivery — run ` +
+      `\`node .agents/scripts/file-ci-gap.js --story ${storyId} --pr ${prNumber} --verdict <verdict> ` +
+      `--owner <consumer|framework|platform> --evidence "<proof reading>"\`. Then run the watcher: ` +
+      `a green on a new head SHA, or the one rerun a filed capacity / unreproducible-tier verdict ` +
+      `admits, re-arms auto-merge.`,
+    evidence,
+  };
+}
+
+/**
+ * A blocked Story: the checks-failed route when it applies, else the
+ * class-specific remediation the friction comment already carries.
+ *
+ * @returns {{ shape: string, nextCommand: string, detail: string, evidence: string[] }}
+ */
+function decideBlocked({ storyId, pr, closeArtifacts, evidence }) {
+  return (
+    decideBlockedChecksFailed({ storyId, pr, closeArtifacts, evidence }) ?? {
+      shape: 'blocked',
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+      detail:
+        `Story is at \`agent::blocked\`. The block was already classified when it was ` +
+        `filed — read the \`friction\` comment on #${storyId} for the class-specific ` +
+        `remediation, resolve it, then transition back to \`agent::executing\`. ` +
+        `Re-run this probe afterwards to confirm the strand cleared.`,
+      evidence,
+    }
+  );
+}
+
 /**
  * The pure decision table: exactly one verdict, never a list.
  *
@@ -357,16 +411,7 @@ export function decideRecovery({
   }
 
   if (label === STATE_LABELS.BLOCKED) {
-    return {
-      shape: 'blocked',
-      nextCommand: NEXT_COMMANDS.recover(storyId),
-      detail:
-        `Story is at \`agent::blocked\`. The block was already classified when it was ` +
-        `filed — read the \`friction\` comment on #${storyId} for the class-specific ` +
-        `remediation, resolve it, then transition back to \`agent::executing\`. ` +
-        `Re-run this probe afterwards to confirm the strand cleared.`,
-      evidence,
-    };
+    return decideBlocked({ storyId, pr, closeArtifacts, evidence });
   }
 
   if (label === STATE_LABELS.DONE) {

package/.agents/scripts/lib/orchestration/epic-rollup.js

@@ -24,6 +24,7 @@ import { ColumnSync, LABEL_TO_COLUMN } from './column-sync.js';
 import {
   isEpicTicket,
   nativeChildReader,
+  readEpicChildIds,
   readEpicChildIdsFrom,
 } from './epic-container.js';
 import { resolveOperatorFromCandidates } from './lease-guard-shared.js';
@@ -302,26 +303,29 @@ async function rollUpOneEpic({
 
 /**
  * Resolve this Story's container in one request via the native parent edge.
- * `null` (never throws) means "no answer here" — linkage may still exist as
- * a body checklist row, which the caller's scan covers.
+ * `authoritative`: the lookup answered, so no parent means no native edge.
  *
  * @param {{ storyId: number, provider: object }} opts
- * @returns {Promise<object|null>} Mapped parent Epic, or null.
+ * @returns {Promise<{ parent: object|null, authoritative: boolean }>}
  */
 async function parentEpicFor({ storyId, provider }) {
-  if (typeof provider?.getParentIssue !== 'function') return null;
+  if (typeof provider?.getParentIssue !== 'function') {
+    return { parent: null, authoritative: false };
+  }
   let parent;
   try {
     parent = await provider.getParentIssue(storyId);
   } catch (err) {
     Logger.warn(
       `[epic-rollup] Parent lookup for Story #${storyId} degraded ` +
-        `(${err?.message ?? err}); falling back to the label scan.`,
+        `(${err?.message ?? err}); falling back to the full label scan.`,
     );
-    return null;
+    return { parent: null, authoritative: false };
   }
-  if (!parent || !isEpicTicket(parent)) return null;
-  return parent;
+  return {
+    parent: parent && isEpicTicket(parent) ? parent : null,
+    authoritative: true,
+  };
 }
 
 /**
@@ -349,6 +353,18 @@ async function scanContainerEpics({ provider }) {
   return (Array.isArray(epics) ? epics : []).filter(isEpicTicket);
 }
 
+/**
+ * `bodyOnly` keeps only Epics whose checklist names the Story (no requests).
+ *
+ * @param {{ storyId: number, provider: object, bodyOnly: boolean }} opts
+ * @returns {Promise<object[]>}
+ */
+async function candidateEpics({ storyId, provider, bodyOnly }) {
+  const epics = await scanContainerEpics({ provider });
+  if (!bodyOnly) return epics;
+  return epics.filter((epic) => readEpicChildIds(epic?.body).includes(storyId));
+}
+
 /**
  * Find the container Epics holding a Story (Story bodies carry no parent
  * pointer). Native edge first, scan otherwise; a scanned Epic must prove it
@@ -358,9 +374,10 @@ async function scanContainerEpics({ provider }) {
  * @returns {Promise<Array<{ epic: object, childIds: number[], nativeReadFailed: boolean, bodyOnlyIds: number[] }>>}
  */
 async function findEpicsForStory({ storyId, provider, skipEpicIds }) {
-  const parent = await parentEpicFor({ storyId, provider });
-  const epics = parent ? [parent] : await scanContainerEpics({ provider });
-  const authoritative = parent !== null;
+  const { parent, authoritative } = await parentEpicFor({ storyId, provider });
+  const epics = parent
+    ? [parent]
+    : await candidateEpics({ storyId, provider, bodyOnly: authoritative });
 
   const matches = [];
   for (const epic of epics) {
@@ -378,7 +395,7 @@ async function findEpicsForStory({ storyId, provider, skipEpicIds }) {
       readNativeChildIds: nativeChildReader(provider),
       onWarn: (message) => Logger.warn(message),
     });
-    if (!authoritative && !childIds.includes(storyId)) {
+    if (!parent && !childIds.includes(storyId)) {
       // A degraded read may have truncated this Story out; skip, but say so.
       if (nativeReadFailed) {
         Logger.warn(

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

@@ -77,6 +77,25 @@ function describeApiRaceFallback(prProbe, budget) {
   return 'no definitive block signal observed; classified as a transient API race or other condition';
 }
 
+/**
+ * Positive evidence a check is still running. Attributed evidence scopes
+ * `requiredRunInFlight` to re-runs; `runInFlight` still says "something is
+ * running".
+ *
+ * @param {object} [prProbe]
+ * @returns {boolean}
+ */
+function hasChecksPendingEvidence(prProbe) {
+  const status = prProbe?.checksStatus;
+  const evidence = prProbe?.requiredRunEvidence;
+  return (
+    status === 'pending' ||
+    status === 'still-running' ||
+    evidence?.requiredRunInFlight === true ||
+    evidence?.runInFlight === true
+  );
+}
+
 /**
  * Classify why a delivery run finished without a confirmed merge. First match
  * wins: (1) arm failure (a protection rejection at arm time still routes to
@@ -123,10 +142,7 @@ export function classifyMergeBlock(input) {
   // Positive evidence only: `unknown` routes to the fallback; `undefined`
   // (no probe) keeps the step-2 mapping.
   const checksStatus = prProbe?.checksStatus;
-  const checksPendingEvidence =
-    checksStatus === 'pending' ||
-    checksStatus === 'still-running' ||
-    prProbe?.requiredRunEvidence?.requiredRunInFlight === true;
+  const checksPendingEvidence = hasChecksPendingEvidence(prProbe);
 
   // 1b. Definitive, and before step 3 since it also presents as BLOCKED.
   // Head-anchored evidence, not the raw rollup (optional/superseded runs).

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

@@ -8,13 +8,29 @@ import { checkVerdict, classifyRollupEntry } from './check-state.js';
 
 /** Fixed poll interval; default for `delivery.mergeWatch.maxBudgetSeconds`. */
 export const DEFAULT_INTERVAL_SECONDS = 30;
+
+/** Checks green, PR unmerged: the merge is imminent, so observe it sooner. */
+const GREEN_INTERVAL_SECONDS = 10;
+
+/**
+ * @param {string|undefined} checksStatus
+ * @param {number} intervalSeconds The in-flight cadence.
+ * @returns {number} Milliseconds until the next poll.
+ */
+export function pollIntervalMs(checksStatus, intervalSeconds) {
+  const seconds =
+    checksStatus === 'success'
+      ? Math.min(GREEN_INTERVAL_SECONDS, intervalSeconds)
+      : intervalSeconds;
+  return seconds * 1000;
+}
 export const DEFAULT_MAX_BUDGET_SECONDS = 3600;
 
 /** Bounds every `gh` spawn so a hang degrades to the probe-error path. */
 export const MERGE_WAIT_GH_TIMEOUT_MS = 60_000;
 
 /**
- * Aggregate over EVERY check (the rollup has no `isRequired`): `failure`
+ * Aggregate over EVERY check (the view rollup has no `isRequired`): `failure`
  * means "something is red", not "blocked" — see {@link failingChecksBlockMerge}.
  */
 export function deriveChecksStatus(statusCheckRollup) {
@@ -47,7 +63,7 @@ export function isPrMerged(pr) {
  * @param {{ conclusion?: string, state?: string }} [check]
  * @returns {string|null}
  */
-function redConclusionOf(check) {
+export function redConclusionOf(check) {
   const conclusion = String(check?.conclusion ?? '').toUpperCase();
   if (conclusion === 'FAILURE' || conclusion === 'ERROR') return conclusion;
   const state = String(check?.state ?? '').toUpperCase();
@@ -61,17 +77,29 @@ function redConclusionOf(check) {
  * @param {{ name?: string, context?: string }} [check]
  * @returns {string|null}
  */
-function readRunName(check) {
+export function readRunName(check) {
   for (const value of [check?.name, check?.context]) {
     if (typeof value === 'string' && value) return value;
   }
   return null;
 }
 
+/**
+ * @param {{ status?: string, state?: string }} [check]
+ * @returns {boolean}
+ */
+export function isRunInFlight(check) {
+  const status = String(check?.status ?? '').toUpperCase();
+  // `status` is empty on a StatusContext, so it falls to the `state` branch.
+  if (status) return status !== 'COMPLETED';
+  const state = String(check?.state ?? '').toUpperCase();
+  return state === 'PENDING' || state === 'EXPECTED';
+}
+
 /**
  * Head-anchored evidence; `null` on an empty rollup (the caller falls back
- * to consecutive probes). Reads EVERY run despite the names — required-ness
- * is attributed via `BLOCKED` in {@link requiredCheckFailedBlocksMerge}.
+ * to consecutive probes). Reads EVERY run — the unscoped rule used when
+ * GitHub's required attribution is unavailable (see `required-checks.js`).
  *
  * @param {Array<{status?: string, conclusion?: string, state?: string}>} statusCheckRollup
  * @returns {{ requiredRunFailed: boolean, requiredRunInFlight: boolean } | null}
@@ -80,22 +108,12 @@ export function deriveRequiredRunEvidence(statusCheckRollup) {
   if (!Array.isArray(statusCheckRollup) || statusCheckRollup.length === 0) {
     return null;
   }
-  let requiredRunFailed = false;
-  let requiredRunInFlight = false;
-  for (const check of statusCheckRollup) {
-    const status = String(check?.status ?? '').toUpperCase();
-    const state = String(check?.state ?? '').toUpperCase();
-    // `status` is empty on a StatusContext, so it falls to the `state` branch.
-    if (status && status !== 'COMPLETED') {
-      requiredRunInFlight = true;
-    } else if (state === 'PENDING' || state === 'EXPECTED') {
-      requiredRunInFlight = true;
-    }
-    if (redConclusionOf(check)) {
-      requiredRunFailed = true;
-    }
-  }
-  return { requiredRunFailed, requiredRunInFlight };
+  return {
+    requiredRunFailed: statusCheckRollup.some(
+      (c) => redConclusionOf(c) !== null,
+    ),
+    requiredRunInFlight: statusCheckRollup.some(isRunInFlight),
+  };
 }
 
 /** The `mergeStateStatus` meaning GitHub itself gates the merge. */
@@ -139,7 +157,8 @@ export function formatChecksFailedReason(prProbe, evidencePath) {
 
 /**
  * A genuinely red REQUIRED check: gated, no review owns `BLOCKED`, a run is
- * red and none in flight. No evidence → false (consecutive-probe path).
+ * red and none in flight — with GitHub attribution, a required run is red and
+ * no re-run of it is in flight. No evidence → false (consecutive-probe path).
  *
  * @param {{ checksStatus?: string, mergeStateStatus?: string,
  *   reviewDecision?: string,

package/.agents/scripts/lib/orchestration/required-checks.js

@@ -0,0 +1,147 @@
+/**
+ * GitHub's per-PR required-check attribution (GraphQL `isRequired`), not
+ * `.agentrc` requiredChecks, which are local command names.
+ */
+
+import {
+  deriveRequiredRunEvidence,
+  failingChecksBlockMerge,
+  isRunInFlight,
+  MERGE_WAIT_GH_TIMEOUT_MS,
+  readRunName,
+  redConclusionOf,
+} from './merge-poll.js';
+
+/**
+ * A required run is red and no re-run of that same check is in flight.
+ *
+ * @param {Array<object>} statusCheckRollup non-empty
+ * @param {Set<string>} requiredNames
+ */
+function deriveAttributedEvidence(statusCheckRollup, requiredNames) {
+  const failedRequired = new Set();
+  for (const check of statusCheckRollup) {
+    const name = readRunName(check);
+    if (name && requiredNames.has(name) && redConclusionOf(check)) {
+      failedRequired.add(name);
+    }
+  }
+  let requiredRunInFlight = false;
+  let runInFlight = false;
+  for (const check of statusCheckRollup) {
+    if (!isRunInFlight(check)) continue;
+    runInFlight = true;
+    if (failedRequired.has(readRunName(check))) requiredRunInFlight = true;
+  }
+  return {
+    requiredRunFailed: failedRequired.size > 0,
+    requiredRunInFlight,
+    runInFlight,
+    attribution: 'github',
+  };
+}
+
+const REQUIRED_CHECKS_QUERY =
+  'query($id: ID!, $n: Int!) { node(id: $id) { ... on PullRequest { ' +
+  'commits(last: 1) { nodes { commit { statusCheckRollup { ' +
+  'contexts(first: 100) { nodes { __typename ' +
+  '... on CheckRun { name isRequired(pullRequestNumber: $n) } ' +
+  '... on StatusContext { context isRequired(pullRequestNumber: $n) } ' +
+  '} } } } } } } } }';
+
+/**
+ * @param {object|string} result `gh api graphql` output
+ * @returns {Set<string>}
+ */
+function parseRequiredNames(result) {
+  const text = typeof result === 'string' ? result : result?.stdout;
+  const parsed = JSON.parse(String(text ?? ''));
+  if (Array.isArray(parsed?.errors) && parsed.errors.length > 0) {
+    throw new Error('graphql errors reading required checks');
+  }
+  const nodes =
+    parsed?.data?.node?.commits?.nodes?.[0]?.commit?.statusCheckRollup?.contexts
+      ?.nodes;
+  if (!Array.isArray(nodes)) throw new Error('required-check contexts absent');
+  const names = new Set();
+  for (const node of nodes) {
+    const name = readRunName(node);
+    if (node?.isRequired === true && name) names.add(name);
+  }
+  return names;
+}
+
+/** Per-head cache: required attribution is read at most once per PR head. */
+const requiredNamesCache = new Map();
+
+/**
+ * Required check names, cached per PR head. `null` on any failure.
+ *
+ * @param {{ prNodeId?: string, prNumber: number|string, headSha?: string,
+ *   gh: { api: Function }, timeoutMs?: number }} args
+ * @returns {Promise<Set<string>|null>}
+ */
+async function readRequiredCheckNames({
+  prNodeId,
+  prNumber,
+  headSha,
+  gh,
+  timeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
+}) {
+  if (!prNodeId || !headSha) return null;
+  const key = `${prNodeId}@${headSha}`;
+  if (requiredNamesCache.has(key)) return requiredNamesCache.get(key);
+  try {
+    const names = parseRequiredNames(
+      await gh.api({
+        method: 'POST',
+        endpoint: 'graphql',
+        body: {
+          query: REQUIRED_CHECKS_QUERY,
+          variables: { id: prNodeId, n: Number(prNumber) },
+        },
+        execOpts: { timeoutMs },
+      }),
+    );
+    requiredNamesCache.set(key, names);
+    return names;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scoped evidence when a red gates the merge and attribution reads; else
+ * the unscoped rule.
+ *
+ * @param {{ view?: object, checksStatus?: string, prNumber: number|string,
+ *   gh: object, ghTimeoutMs?: number, readFn?: Function }} args
+ * @returns {Promise<object|null>}
+ */
+export async function readProbeRunEvidence({
+  view,
+  checksStatus,
+  prNumber,
+  gh,
+  ghTimeoutMs,
+  readFn = readRequiredCheckNames,
+}) {
+  const rollup = view?.statusCheckRollup;
+  const gated = failingChecksBlockMerge({
+    checksStatus,
+    mergeStateStatus: view?.mergeStateStatus,
+  });
+  const names = gated
+    ? await readFn({
+        prNodeId: view?.id,
+        prNumber,
+        headSha: view?.headRefOid,
+        gh,
+        timeoutMs: ghTimeoutMs,
+      })
+    : null;
+  if (names instanceof Set && Array.isArray(rollup) && rollup.length > 0) {
+    return deriveAttributedEvidence(rollup, names);
+  }
+  return deriveRequiredRunEvidence(rollup);
+}