mandrel 2.64.0 → 2.66.0

package/.agents/scripts/lib/observability/close-telemetry.js

@@ -0,0 +1,330 @@
+/**
+ * What a Story cost, as close observes it: retries by cause, review halts and
+ * overrides by provider, acceptance rounds, worker tokens. Best-effort and
+ * local only — a failed write is a missing metric, never a failed close.
+ *
+ * @module lib/observability/close-telemetry
+ */
+
+import crypto from 'node:crypto';
+
+import { parseWorkerTokens } from '../cli-args.js';
+import { Logger } from '../Logger.js';
+import { EVENT_KINDS } from '../signals/schema.js';
+import {
+  emitRuntimeFriction,
+  emitTerminalFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from './runtime-friction.js';
+import { appendSignal, forEachLine } from './signals-writer.js';
+
+const RETRY_CAUSES = Object.freeze({
+  CI_RED: 'ci-red',
+  REVIEW_BLOCK: 'review-block',
+  GATE_FAILED: 'gate-failed',
+  MERGE_WAIT: 'merge-wait',
+  OTHER: 'other',
+});
+
+const BLOCK_CLASS_CAUSES = Object.freeze({
+  'checks-failed': RETRY_CAUSES.CI_RED,
+  'advisory-gate-red': RETRY_CAUSES.CI_RED,
+  'checks-pending-timeout': RETRY_CAUSES.MERGE_WAIT,
+});
+
+const FAILED_PHASE_CAUSES = Object.freeze({
+  'code-review': RETRY_CAUSES.REVIEW_BLOCK,
+  'close-validation': RETRY_CAUSES.GATE_FAILED,
+  'confirm-merge': RETRY_CAUSES.MERGE_WAIT,
+});
+
+/**
+ * @param {object|null|undefined} envelope
+ * @returns {string|null} `null` for a landed or pending close.
+ */
+function retryCauseForTerminal(envelope) {
+  const status = envelope?.status;
+  if (status === 'blocked') {
+    return (
+      BLOCK_CLASS_CAUSES[envelope.blocked?.blockClass] ?? RETRY_CAUSES.OTHER
+    );
+  }
+  if (status === 'failed') {
+    return FAILED_PHASE_CAUSES[envelope.phase] ?? RETRY_CAUSES.OTHER;
+  }
+  return null;
+}
+
+/**
+ * @param {{ envelope: object, config?: object }} args
+ * @returns {Promise<boolean>}
+ */
+async function emitCloseRetrySignal({ envelope, config }) {
+  const cause = retryCauseForTerminal(envelope);
+  const storyId = Number(envelope?.storyId);
+  if (cause === null || !Number.isInteger(storyId) || storyId <= 0) {
+    return false;
+  }
+  const signal = {
+    kind: EVENT_KINDS.RETRY,
+    eventId: crypto.randomUUID(),
+    ts: new Date().toISOString(),
+    epicId: null,
+    storyId,
+    taskId: null,
+    phase: 'close',
+    emitter: { tool: 'single-story-close' },
+    details: {
+      cause,
+      status: envelope.status,
+      closePhase: envelope.phase ?? null,
+      blockClass: envelope.blocked?.blockClass ?? null,
+    },
+  };
+  return appendSignal({ epicId: null, storyId, signal, config });
+}
+
+/**
+ * @param {{ envelope: object, config?: object }} args
+ * @returns {Promise<void>}
+ */
+export async function emitCloseTerminalSignals({ envelope, config } = {}) {
+  await emitCloseRetrySignal({ envelope, config });
+  await emitTerminalFriction({ envelope, config });
+}
+
+/**
+ * @param {{ storyId: number, prNumber?: number|null, criticalCount: number,
+ *   criticalByProvider?: Record<string, number>, config?: object }} args
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export function emitReviewBlockedFriction({
+  storyId,
+  prNumber = null,
+  criticalCount,
+  criticalByProvider = {},
+  config,
+}) {
+  return emitRuntimeFriction({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCKED,
+    tool: 'single-story-close',
+    details: { prNumber, criticalCount, criticalByProvider },
+    config,
+  });
+}
+
+/**
+ * @param {Record<string, number>} into
+ * @param {Record<string, number>} from
+ * @returns {Record<string, number>} `into`, mutated.
+ */
+function addCounts(into, from) {
+  for (const [key, count] of Object.entries(from)) {
+    into[key] = (into[key] ?? 0) + count;
+  }
+  return into;
+}
+
+function emptyTelemetryTally() {
+  return {
+    acceptanceRounds: 0,
+    retries: { total: 0, byCause: {} },
+    review: { haltsByProvider: {}, overridesByProvider: {} },
+  };
+}
+
+/**
+ * One incident per provider that raised a critical finding, not per finding.
+ *
+ * @param {object} details
+ * @returns {Record<string, number>}
+ */
+function providerIncidents(details) {
+  const out = {};
+  const byProvider = details?.criticalByProvider;
+  for (const [name, count] of Object.entries(byProvider ?? {})) {
+    if (Number.isInteger(count) && count > 0) out[name] = 1;
+  }
+  return out;
+}
+
+const RECORD_TALLIERS = Object.freeze({
+  [EVENT_KINDS.RETRY]: (tally, record) => {
+    const cause =
+      typeof record.details?.cause === 'string'
+        ? record.details.cause
+        : RETRY_CAUSES.OTHER;
+    tally.retries.total += 1;
+    addCounts(tally.retries.byCause, { [cause]: 1 });
+  },
+  [EVENT_KINDS.ACCEPTANCE_EVAL]: (tally, record) => {
+    const round = Number(record.details?.round);
+    const seen = Number.isInteger(round) && round > 0 ? round : 1;
+    tally.acceptanceRounds = Math.max(tally.acceptanceRounds, seen);
+  },
+  [EVENT_KINDS.FRICTION]: (tally, record) => {
+    if (record.details?.recovered === true) return;
+    if (record.category === RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCKED) {
+      addCounts(
+        tally.review.haltsByProvider,
+        providerIncidents(record.details),
+      );
+    } else if (
+      record.category === RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCK_OVERRIDDEN
+    ) {
+      addCounts(
+        tally.review.overridesByProvider,
+        providerIncidents(record.details),
+      );
+    }
+  },
+});
+
+/**
+ * @param {Iterable<unknown>} records
+ * @returns {ReturnType<typeof emptyTelemetryTally>}
+ */
+function tallyStoryTelemetry(records) {
+  const tally = emptyTelemetryTally();
+  for (const record of records ?? []) {
+    if (!record || typeof record !== 'object') continue;
+    RECORD_TALLIERS[record.kind]?.(tally, record);
+  }
+  return tally;
+}
+
+/**
+ * @param {Array<ReturnType<typeof emptyTelemetryTally>>} tallies
+ * @returns {ReturnType<typeof emptyTelemetryTally>}
+ */
+function mergeTelemetryTallies(tallies) {
+  const total = emptyTelemetryTally();
+  for (const t of tallies ?? []) {
+    total.acceptanceRounds += t.acceptanceRounds;
+    total.retries.total += t.retries.total;
+    addCounts(total.retries.byCause, t.retries.byCause);
+    addCounts(total.review.haltsByProvider, t.review.haltsByProvider);
+    addCounts(total.review.overridesByProvider, t.review.overridesByProvider);
+  }
+  return total;
+}
+
+/**
+ * A halt no override rejected, on a Story that then landed.
+ *
+ * @param {ReturnType<typeof emptyTelemetryTally>} tally
+ * @param {boolean} landed
+ * @returns {Record<string, number>}
+ */
+function confirmedHalts(tally, landed) {
+  if (!landed) return {};
+  const out = {};
+  for (const [name, count] of Object.entries(tally.review.haltsByProvider)) {
+    if (!tally.review.overridesByProvider[name]) out[name] = count;
+  }
+  return out;
+}
+
+/**
+ * @param {{ storyId: number, config?: object, readFn?: typeof forEachLine }} args
+ * @returns {Promise<ReturnType<typeof emptyTelemetryTally>>}
+ */
+async function readStoryTally({ storyId, config, readFn = forEachLine }) {
+  const rows = [];
+  try {
+    await readFn(null, storyId, (parsed) => rows.push(parsed), config);
+  } catch (err) {
+    Logger.warn(
+      `[close-telemetry] signal read failed for Story #${storyId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  return tallyStoryTelemetry(rows);
+}
+
+/**
+ * @param {{ storyId: number, config?: object, workerTokens?: number|null,
+ *   landed?: boolean, readFn?: typeof forEachLine }} args
+ * @returns {Promise<object>}
+ */
+async function buildCloseTelemetry({
+  storyId,
+  config,
+  workerTokens = null,
+  landed = false,
+  readFn,
+}) {
+  const tally = await readStoryTally({ storyId, config, readFn });
+  return {
+    acceptanceRounds: tally.acceptanceRounds,
+    retries: tally.retries,
+    review: {
+      ...tally.review,
+      confirmedHaltsByProvider: confirmedHalts(tally, landed),
+    },
+    workerTokens: Number.isInteger(workerTokens) ? workerTokens : null,
+  };
+}
+
+/**
+ * Over the run's own Stories, not the friction recurrence window.
+ *
+ * @param {Array<string|number>} storyIds
+ * @param {object} [config]
+ * @param {{ readFn?: typeof forEachLine }} [opts]
+ * @returns {Promise<ReturnType<typeof emptyTelemetryTally> & { storyCount: number }>}
+ */
+export async function gatherRunTelemetry(storyIds, config, { readFn } = {}) {
+  const tallies = [];
+  for (const raw of Array.isArray(storyIds) ? storyIds : []) {
+    const storyId = Number(raw);
+    if (!Number.isInteger(storyId) || storyId <= 0) continue;
+    tallies.push(await readStoryTally({ storyId, config, readFn }));
+  }
+  return { ...mergeTelemetryTallies(tallies), storyCount: tallies.length };
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {number|null}
+ */
+export function resolveWorkerTokens(raw) {
+  const { tokens, warning } = parseWorkerTokens(raw);
+  if (warning) Logger.warn(`[single-story-close] ${warning}`);
+  return tokens;
+}
+
+/**
+ * The retry goes first so the summary counts it; a failure leaves
+ * `telemetry: null` and the close's status untouched.
+ *
+ * @param {{ terminal: object, result?: object|null, config?: object,
+ *   workerTokens?: number|null, readFn?: typeof forEachLine }} args
+ * @returns {Promise<void>}
+ */
+export async function recordCloseTelemetry({
+  terminal,
+  result,
+  config,
+  workerTokens = null,
+  readFn,
+}) {
+  await emitCloseRetrySignal({ envelope: terminal, config });
+  if (!result) return;
+  try {
+    result.telemetry = await buildCloseTelemetry({
+      storyId: result.storyId,
+      config,
+      workerTokens,
+      landed: terminal?.status === 'landed',
+      readFn,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[single-story-close] telemetry summary unavailable: ${err?.message ?? err}`,
+    );
+    result.telemetry = null;
+  }
+}

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/observability/runtime-friction.js

@@ -23,6 +23,8 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
   /** A tool failed to execute — kept out of code-finding severity tiers. */
   TOOL_DEGRADED: 'tool-degraded',
   LIGHT_SCOPE_REJECTED: 'light-scope-rejected',
+  /** A critical code-review halt, attributed to the provider(s) that raised it. */
+  REVIEW_BLOCKED: 'review-blocked',
   /** A human shipped over a review blocker; a rising count means miscalibration. */
   REVIEW_BLOCK_OVERRIDDEN: 'review-block-overridden',
 });

package/.agents/scripts/lib/observability/signal-validator.js

@@ -2,6 +2,10 @@
  * signal-validator.js — write-time validation of signal records against the
  * on-disk `signal-event.schema.json`, compiled once so the writer and the
  * contract test validate against the same document. Never throws.
+ *
+ * The schema is compiled on the first `validateSignal` call, not at import:
+ * every CLI that imports the signals writer (including for `--help`) would
+ * otherwise pay the AJV compile at start-up.
  */
 
 import { readFileSync } from 'node:fs';
@@ -45,7 +49,14 @@ function buildValidator() {
   }
 }
 
-const _validate = buildValidator();
+/** `undefined` until the first `validateSignal` call builds it. */
+let _validate;
+
+/** @returns {import('ajv').ValidateFunction | null} */
+function getValidator() {
+  if (_validate === undefined) _validate = buildValidator();
+  return _validate;
+}
 
 /**
  * @param {import('ajv').ErrorObject[] | null | undefined} errors
@@ -74,7 +85,8 @@ function violatingFieldOf(errors) {
  * @returns {{ valid: boolean, violatingField: string|null, message: string|null }}
  */
 export function validateSignal(record) {
-  if (_validate === null) {
+  const validate = getValidator();
+  if (validate === null) {
     return { valid: true, violatingField: null, message: null };
   }
   if (record === null || typeof record !== 'object' || Array.isArray(record)) {
@@ -84,9 +96,9 @@ export function validateSignal(record) {
       message: 'signal record must be a plain object',
     };
   }
-  const valid = _validate(record);
+  const valid = validate(record);
   if (valid) return { valid: true, violatingField: null, message: null };
-  const field = violatingFieldOf(_validate.errors);
-  const message = _validate.errors?.[0]?.message ?? 'schema validation failed';
+  const field = violatingFieldOf(validate.errors);
+  const message = validate.errors?.[0]?.message ?? 'schema validation failed';
   return { valid: false, violatingField: field, message };
 }

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

@@ -112,16 +112,22 @@ function resolveScopeEnvelope(opts, config) {
  *   postedCommentId: number|null,
  *   commentTargetId: number,
  *   halted: boolean,
+ *   criticalByProvider?: Record<string, number>,
  *   degraded: boolean, degradations: Array<object>,
  *   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';
   }
@@ -224,6 +230,21 @@ async function postReviewComment({
   }
 }
 
+/**
+ * Which review provider(s) raised the critical findings. A chain reports its
+ * own per-entry attribution; any other provider owns every critical.
+ *
+ * @param {{ reviewProvider: object, providerName: string,
+ *   severity: { critical: number } }} args
+ * @returns {Record<string, number>}
+ */
+function resolveCriticalByProvider({ reviewProvider, providerName, severity }) {
+  if (typeof reviewProvider?.getCriticalByProvider === 'function') {
+    return reviewProvider.getCriticalByProvider();
+  }
+  return severity.critical > 0 ? { [providerName]: severity.critical } : {};
+}
+
 async function executeReviewPipeline({ opts, config, envelope }) {
   const {
     provider,
@@ -236,9 +257,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})...`,
@@ -272,6 +293,11 @@ async function executeReviewPipeline({ opts, config, envelope }) {
   );
   const severity = countBySeverity(findings);
   const halted = hasSurvivingCritical(severity);
+  const criticalByProvider = resolveCriticalByProvider({
+    reviewProvider,
+    providerName,
+    severity,
+  });
   const report = renderFindingsFn({
     scope,
     ticketId,
@@ -299,6 +325,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     postedCommentId,
     commentTargetId,
     halted,
+    criticalByProvider,
     ...degradationEnvelope(degradations),
     blockerReason: halted
       ? `code-review reported ${severity.critical} critical blocker(s)`

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).