mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/watcher.js

@@ -5,10 +5,9 @@
  *
  * Subscribes to:
  *   - `pr.created` → resolve the required-check names from GitHub at
- *     runtime via `gh pr checks <pr> --required`, emit
- *     `epic.watch.start` carrying that list, poll until every check
- *     reaches a terminal state (or a per-listener wall-clock deadline
- *     expires), then emit `epic.watch.end` with the outcome map.
+ *     runtime via `gh pr checks <pr> --required`, then poll until every
+ *     check reaches a terminal state (or a per-listener wall-clock
+ *     deadline expires), recording the outcome in `classifications`.
  *
  * Critical contract:
  *   - Required-check **names** are resolved from `gh pr checks` at
@@ -28,11 +27,13 @@
  * re-runs the poll loop (which is itself idempotent: the outcome map
  * always reflects the live GitHub state).
  *
- * Side-effect firewall: the listener emits on the bus and shells out
- * to `gh`. It does NOT mutate ticket labels, post comments, or call
- * `notify` — those listeners receive `epic.watch.end` (via the
- * downstream AutomergePredicate → epic.merge.ready/blocked chain) and
- * own their own side effects.
+ * Side-effect firewall: the listener shells out to `gh` and records
+ * its outcome in the in-memory `classifications` log. It does NOT
+ * mutate ticket labels, post comments, call `notify`, or emit on the
+ * bus — the production consumer (`pr-watch-with-update.js`) drives
+ * `watchPrToTerminal` directly without a bus, and the retired
+ * `epic.watch.start` / `epic.watch.end` bus events went with the
+ * Epic-orchestration stratum.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -40,20 +41,20 @@ import { spawnSync } from 'node:child_process';
 import { parsePrNumberFromUrl } from '../../../github-url.js';
 
 /**
- * Map `gh pr checks` `state` values to the canonical outcome enum on
- * the `epic.watch.end` schema, with a fourth `'pending'` sentinel for
- * in-flight checks. Pure — exported for tests so the pin is explicit
- * and reviewable.
+ * Map `gh pr checks` `state` values to the canonical lowercase outcome
+ * vocabulary (`success` | `failure` | `timed_out` | `skipped`), with a
+ * fourth `'pending'` sentinel for in-flight checks. Pure — exported for
+ * tests so the pin is explicit and reviewable.
  *
  * `gh` returns capitalized SCREAMING_SNAKE values (`SUCCESS`,
- * `FAILURE`, `TIMED_OUT`, etc.); the schema enum is lowercase. An
- * empty / queued / in_progress state collapses to `'pending'` so the
- * poll loop can distinguish "still running" from terminal outcomes.
- * `'pending'` is intentionally NOT in the schema enum — `reduceOutcomes`
- * is called only on the live state, and the final emit gates on
- * `allTerminal()` so no `'pending'` ever leaks into `epic.watch.end`.
- * Unknown / non-pending unrecognized values collapse to `'skipped'`
- * so any future GitHub state we haven't enumerated still validates.
+ * `FAILURE`, `TIMED_OUT`, etc.). An empty / queued / in_progress state
+ * collapses to `'pending'` so the poll loop can distinguish "still
+ * running" from terminal outcomes. `'pending'` is intentionally NOT a
+ * terminal outcome — `reduceOutcomes` is called only on the live state,
+ * and the final outcome map gates on `allTerminal()` so no `'pending'`
+ * ever leaks into a finished watch. Unknown / non-pending unrecognized
+ * 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).
@@ -264,8 +265,8 @@ export function parseGhPrChecks(stdout) {
 }
 
 /**
- * Reduce a list of check entries to the `{ checkName: outcome }` map
- * the `epic.watch.end` schema expects. Pure — exported for tests.
+ * Reduce a list of check entries to the canonical `{ checkName: outcome }`
+ * map. Pure — exported for tests.
  *
  * When `gh` returns the same `name` more than once (parallel matrix
  * builds, retries), the LAST entry wins. The poll loop calls this on
@@ -431,9 +432,9 @@ export async function pollUntilTerminal({
  * @param {{status:number,stdout:string,stderr:string}} [opts.firstProbe]
  *   Optional already-issued `gh pr checks` result. When the caller (the
  *   `Watcher` listener) has already probed once to resolve the required
- *   names for `epic.watch.start`, it threads that result here so the
- *   loop does not double-spend the first `gh pr checks` call. Omit it
- *   (the CLI path) and the loop issues the first probe itself.
+ *   check names, it threads that result here so the loop does not
+ *   double-spend the first `gh pr checks` call. Omit it (the CLI path)
+ *   and the loop issues the first probe itself.
  * @returns {Promise<{
  *   outcomes: object,
  *   requiredChecks: string[],
@@ -466,8 +467,8 @@ export async function watchPrToTerminal({
   firstProbe,
 }) {
   // First probe: resolve the required-check name set at runtime. Reuse a
-  // caller-supplied probe (the listener already issued one for
-  // `epic.watch.start`) so we never double-spend the first `gh` call.
+  // caller-supplied probe (the listener already issued one to resolve the
+  // required check names) so we never double-spend the first `gh` call.
   const first = firstProbe ?? ghPrChecksFn({ prUrl, cwd });
   // `gh` exits 8 when checks are still pending; this is expected and
   // does not indicate failure. Any other non-zero status with no
@@ -619,12 +620,8 @@ export class Watcher {
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
-    if (
-      !opts.bus ||
-      typeof opts.bus.on !== 'function' ||
-      typeof opts.bus.emit !== 'function'
-    ) {
-      throw new TypeError('Watcher requires a bus with on() and emit()');
+    if (!opts.bus || typeof opts.bus.on !== 'function') {
+      throw new TypeError('Watcher requires a bus with on()');
     }
     this.bus = opts.bus;
     this.cwd = opts.cwd ?? process.cwd();
@@ -688,11 +685,10 @@ export class Watcher {
       return;
     }
 
-    // First probe: resolve the required-check name set at runtime, so we
-    // can carry the list on `epic.watch.start` BEFORE the (potentially
-    // long) poll loop runs. We thread this probe into `watchPrToTerminal`
-    // (via `firstProbe`) so the shared loop reuses it instead of
-    // double-spending the first `gh pr checks` call.
+    // First probe: resolve the required-check name set at runtime BEFORE
+    // the (potentially long) poll loop runs. We thread this probe into
+    // `watchPrToTerminal` (via `firstProbe`) so the shared loop reuses it
+    // instead of double-spending the first `gh pr checks` call.
     const first = this.ghPrChecksFn({ prUrl, cwd: this.cwd });
     const firstEntries = parseGhPrChecks(first.stdout);
     if (firstEntries.length === 0 && first.status !== 0 && first.status !== 8) {
@@ -710,45 +706,24 @@ export class Watcher {
 
     const requiredChecks = firstEntries.map((e) => e.name);
 
-    try {
-      await this.bus.emit('epic.watch.start', { prUrl, requiredChecks });
-    } catch (err) {
-      this.classifications.push({
-        event,
-        seqId,
-        outcome: 'failed',
-        reason: `start-emit-failed:${err?.message ?? err}`,
-      });
-      this.logger.warn?.(
-        `[Watcher] epic.watch.start emit failed: ${err?.message ?? err}`,
-      );
-      return;
-    }
-
     // Delegate the poll + BEHIND-recovery loop to the shared plain
     // primitive so the CLI (`pr-watch-with-update.js`) and this listener
     // run identical logic.
-    const {
-      outcomes: emitOutcomes,
-      polls,
-      updatesApplied,
-      resumesApplied,
-      terminal,
-      stillRunning,
-    } = await watchPrToTerminal({
-      prUrl,
-      cwd: this.cwd,
-      maxPolls: this.maxPolls,
-      maxUpdates: this.maxUpdates,
-      maxResumes: this.maxResumes,
-      pollIntervalMs: this.pollIntervalMs,
-      ghPrChecksFn: this.ghPrChecksFn,
-      ghPrViewFn: this.ghPrViewFn,
-      ghPrUpdateBranchFn: this.ghPrUpdateBranchFn,
-      sleepFn: this.sleepFn,
-      logger: this.logger,
-      firstProbe: first,
-    });
+    const { polls, updatesApplied, resumesApplied, terminal, stillRunning } =
+      await watchPrToTerminal({
+        prUrl,
+        cwd: this.cwd,
+        maxPolls: this.maxPolls,
+        maxUpdates: this.maxUpdates,
+        maxResumes: this.maxResumes,
+        pollIntervalMs: this.pollIntervalMs,
+        ghPrChecksFn: this.ghPrChecksFn,
+        ghPrViewFn: this.ghPrViewFn,
+        ghPrUpdateBranchFn: this.ghPrUpdateBranchFn,
+        sleepFn: this.sleepFn,
+        logger: this.logger,
+        firstProbe: first,
+      });
 
     // `still-running` (slow CI, not red) is a distinct classification from
     // a genuine `timed-out` — reserved for a check that never went
@@ -768,16 +743,6 @@ export class Watcher {
       resumesApplied,
       requiredChecks: requiredChecks.length,
     });
-    try {
-      await this.bus.emit('epic.watch.end', {
-        prUrl,
-        checkOutcomes: emitOutcomes,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[Watcher] epic.watch.end emit failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
   }
 
   reset() {

package/.agents/scripts/lib/orchestration/lifecycle/trace-logger.js

@@ -40,28 +40,17 @@ function formatClock(iso) {
  * mapping is stable across runs.
  */
 const PHASE_BY_PREFIX = Object.freeze({
-  'epic.snapshot': 'Snapshot',
-  'epic.plan': 'Plan',
   'story.dispatch': 'Waves',
   'story.merged': 'Waves',
   'story.blocked': 'Waves',
-  'epic.blocked': 'Waves',
-  'epic.close': 'Close-tail',
-  'acceptance.reconcile': 'Acceptance Reconciliation',
-  'epic.finalize': 'Finalize',
   'pr.created': 'Finalize',
-  'epic.watch': 'Watch',
-  'epic.automerge': 'Automerge',
-  'epic.merge': 'Automerge',
-  'epic.cleanup': 'Cleanup',
-  'epic.complete': 'Complete',
   'notification.emitted': 'Notifications',
   'checkpoint.written': 'Checkpoint',
 });
 
 function phaseFor(eventName) {
-  // Match longest prefix first so `epic.snapshot.start` resolves before
-  // `epic.snapshot` would match an unrelated `epic.*` block.
+  // Match longest prefix first so `story.dispatch.start` resolves before
+  // `story.dispatch` would match an unrelated `story.*` block.
   const keys = Object.keys(PHASE_BY_PREFIX).sort((a, b) => b.length - a.length);
   for (const k of keys) {
     if (eventName === k || eventName.startsWith(`${k}.`)) {
@@ -277,7 +266,7 @@ export function render(ledger, opts = {}) {
  *
  * The wildcard-firewall rule (Tech Spec § Bus contract) requires that
  * trace observers do NOT import any module that mutates GitHub state,
- * the worktree, or the filesystem outside `temp/epic-<id>/`. This
+ * the worktree, or the filesystem outside `temp/run-<id>/`. This
  * module satisfies that constraint: the only filesystem writes are to
  * the companion path under the same temp directory the ledger lives
  * in.

package/.agents/scripts/lib/orchestration/lint-baseline-service.js

@@ -1,10 +1,10 @@
 /**
  * lib/orchestration/lint-baseline-service.js
  *
- * Captures the Epic lint baseline (see `lint-baseline.js capture`). Extracted
- * from the inline implementation that used to live in `dispatch-engine.js`
- * so the coordinator no longer reaches into `node:child_process` or
- * `node:fs` directly. Tests can exercise the service with a stubbed exec
+ * Captures the lint baseline (see `lint-baseline.js capture`). Extracted
+ * from the inline implementation that used to live in the deleted
+ * `dispatch-engine.js` entry seam so the coordinator no longer reaches into
+ * `node:child_process` or `node:fs` directly. Tests can exercise the service with a stubbed exec
  * adapter and no filesystem interaction.
  */
 

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

@@ -2,13 +2,12 @@
 /**
  * merge-block-class.js — Story #4426 (Epic #4425, slice 1: foundation).
  *
- * Shared block-class classifier consumed by BOTH delivery paths — the
- * epic-path must-land terminal step and the standalone
- * `single-story-close` must-land terminal step (the not-yet-landed
- * follow-on Stories under Epic #4425) — so a headless delivery run that
- * finishes its work without a confirmed merge is attributable to exactly
- * one of four classes from the SAME decision logic, instead of each path
- * inventing its own ad hoc diagnosis.
+ * Shared block-class classifier for the `single-story-close` must-land
+ * terminal step and `deliver-recover`, so a headless delivery run that
+ * finishes its work without a confirmed merge is attributable to exactly one
+ * class from ONE decision logic, instead of each caller inventing its own ad
+ * hoc diagnosis. (It was written to serve an epic-path terminal too; the v2
+ * cutover left `single-story-close` as the only delivery path.)
  *
  * Block classes (Epic #4425 Goal; `predicate-refused` added by #4472):
  *   - `checks-pending-timeout`           The watch/poll budget was
@@ -16,6 +15,24 @@
  *                                         were still pending/running — not
  *                                         a hard block, the run simply ran
  *                                         out of time.
+ *   - `checks-failed`                    A required check went RED — red
+ *                                         checks that branch protection does
+ *                                         not require are NOT this class
+ *                                         (see `failingChecksBlockMerge`). A
+ *                                         definitive terminal the merge wait
+ *                                         must fail fast on (Story #4543):
+ *                                         before this class the in-close poll
+ *                                         read only `state`/`mergedAt`, so a
+ *                                         check that failed at minute one
+ *                                         burned the entire budget and then
+ *                                         classified as
+ *                                         `branch-protection-human-required`
+ *                                         (the exhaustion probe sees
+ *                                         `mergeStateStatus: BLOCKED` with
+ *                                         checks settled) — sending the
+ *                                         operator to diagnose branch
+ *                                         protection instead of the red check
+ *                                         that is actually in their way.
  *   - `branch-protection-human-required` GitHub reports the PR needs a
  *                                         human action: a required review
  *                                         that hasn't been granted, or a
@@ -38,7 +55,7 @@
  *                                         a red/pending required check, an
  *                                         unreadable check probe, a dirty
  *                                         structured-signal verdict, or a
- *                                         `delivery.ci.requireChecks` policy
+ *                                         (retired `requireChecks` policy
  *                                         block on a checks-less repo (#4472).
  *                                         The must-land contract previously
  *                                         only covered post-arm poll
@@ -47,20 +64,27 @@
  *                                         this class makes it attributable.
  *
  * Pure function, no I/O: callers pass in the already-observed
- * arm-result / PR-probe / budget signals (from `AutomergeArmer`,
- * `MergeWatcher`, a raw `gh pr view` read, or the standalone
+ * arm-result / PR-probe / budget signals (from the close path's merge wait,
+ * a raw `gh pr view` read, or the standalone
  * `single-story-confirm-merge.js` poll) and get back a
  * `{ blockClass, reason }` verdict ready to hand to `emitMergeUnlanded`
  * (`emit-merge-unlanded.js`).
  */
 
+import { failingChecksBlockMerge } from './merge-poll.js';
+
 /**
- * The four block classes named in the Epic #4425 Goal. Order is the
- * evaluation priority documented on `classifyMergeBlock` below, NOT an
- * arbitrary listing — earlier entries are checked first when a real input
- * happens to satisfy more than one heuristic.
+ * Every class `classifyMergeBlock` can return. Order is the evaluation
+ * priority documented on `classifyMergeBlock` below, NOT an arbitrary
+ * listing — earlier entries are checked first when a real input happens to
+ * satisfy more than one heuristic.
+ *
+ * Started as the four classes named in the Epic #4425 Goal; Story #4543
+ * added `checks-failed` so a red required check is attributable as itself
+ * rather than being absorbed by the timeout or branch-protection verdicts.
  */
 export const BLOCK_CLASSES = Object.freeze([
+  'checks-failed',
   'checks-pending-timeout',
   'branch-protection-human-required',
   'arm-failure',
@@ -70,10 +94,12 @@ export const BLOCK_CLASSES = Object.freeze([
 /**
  * The full set of block-class values a `merge.unlanded` record may carry.
  * This is the classifier's four outputs PLUS `predicate-refused` (#4472),
- * which is emitted DIRECTLY by the AutomergePredicate / AutomergeArmer for a
- * headless refusal that never reached the poll-exhaustion classifier — so it
- * is a valid attribution value even though `classifyMergeBlock` never
- * produces it. `isValidBlockClass` (and the `merge.unlanded` schema enum)
+ * 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
+ * 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)
  * validate against this broader set; the classifier's own reachability
  * invariant stays scoped to `BLOCK_CLASSES`.
  */
@@ -121,6 +147,12 @@ function describeApiRaceFallback(prProbe, budget) {
   if (prProbe?.error) {
     return `PR probe error: ${prProbe.error}`;
   }
+  // Red checks that do not gate the merge (step 1b declined them). Name the
+  // situation precisely: the operator must NOT be sent to fix the red check,
+  // because auto-merge was free to land this PR and did not.
+  if (prProbe?.checksStatus === 'failure') {
+    return `PR did not land although its failing checks are not required (mergeStateStatus=${prProbe?.mergeStateStatus ?? 'n/a'}); the red checks are not the block — check that auto-merge is still armed`;
+  }
   if (budget && budget.exhausted === true) {
     return `watch budget exhausted with an unrecognised checks status (${prProbe?.checksStatus ?? 'unknown'})`;
   }
@@ -137,6 +169,12 @@ function describeApiRaceFallback(prProbe, budget) {
  *      rejection surfaced AT arm time still routes to
  *      `branch-protection-human-required` rather than the generic
  *      `arm-failure`.
+ *   1b. A red required check — `checks-failed` (Story #4543). Evaluated
+ *      before every budget and probe signal because it is *definitive*:
+ *      no amount of remaining budget turns a failed check green, and on a
+ *      protected branch it also presents as `mergeStateStatus: 'BLOCKED'`,
+ *      so leaving it to step 3 would attribute the operator's red test run
+ *      to branch protection.
  *   2. Budget exhaustion while checks were still in flight —
  *      `checks-pending-timeout`. Evaluated BEFORE the human-required
  *      probe signals because on a protected branch GitHub reports
@@ -164,9 +202,10 @@ function describeApiRaceFallback(prProbe, budget) {
  *   (`REVIEW_REQUIRED`, `APPROVED`, …).
  * @param {string} [input.prProbe.mergeStateStatus] GitHub merge-state
  *   status (`BLOCKED`, `BEHIND`, `CLEAN`, …).
- * @param {string} [input.prProbe.checksStatus] Aggregate required-check
- *   status observed on the last probe (`success` | `pending` |
- *   `still-running` | `failure` | `unknown`).
+ * @param {string} [input.prProbe.checksStatus] Aggregate status across ALL
+ *   checks observed on the last probe (`success` | `pending` |
+ *   `still-running` | `failure` | `unknown`) — required-ness is decided by
+ *   `mergeStateStatus`, not by this field.
  * @param {string} [input.prProbe.error] Set when the probe call itself
  *   errored (network / API failure reading the PR).
  * @param {object} [input.budget] Poll-budget accounting.
@@ -205,6 +244,23 @@ export function classifyMergeBlock(input) {
   const checksPendingEvidence =
     checksStatus === 'pending' || checksStatus === 'still-running';
 
+  // 1b. A required check is RED. Definitive — no remaining budget makes a
+  // failed check pass — so this precedes both the budget branch and the
+  // BLOCKED-merge-state heuristic, which would otherwise attribute the red
+  // check to branch protection on any protected base.
+  //
+  // Gated on `failingChecksBlockMerge` rather than the raw rollup status:
+  // `checksStatus: 'failure'` covers optional checks too, and naming an
+  // optional red check as THE block sends the operator to fix a check that
+  // was never gating the merge. A red-but-not-gating PR that still failed to
+  // land falls through to the fallback, whose reason says exactly that.
+  if (failingChecksBlockMerge(prProbe)) {
+    return {
+      blockClass: 'checks-failed',
+      reason: `a required check failed (mergeStateStatus=${prProbe?.mergeStateStatus ?? 'n/a'})`,
+    };
+  }
+
   // 2. Budget exhausted while checks were still in flight. Ordered
   // before the human-required probe signals: `mergeStateStatus:
   // 'BLOCKED'` is the steady state on a protected branch while required

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

@@ -0,0 +1,104 @@
+/**
+ * merge-poll.js — merge-wait constants and check-rollup derivation owned by
+ * the close path.
+ *
+ * Story #4545 — these three symbols used to live in the Epic-era
+ * `lifecycle/listeners/merge-watcher.js`. That listener class had no
+ * production caller after the v2.0.0 Story-only cutover, but it was not
+ * importer-less: the live close path (`single-story-close/phases/confirm-merge.js`)
+ * and `deliver-recover.js` both reached into it for the poll defaults and
+ * `deriveChecksStatus`. Relocating them here lets the listener go without
+ * leaving the close path importing a lifecycle module it does not otherwise
+ * participate in.
+ *
+ * Sits beside `merge-block-class.js`, its sole consumer pairing:
+ * `deriveChecksStatus` produces the `prProbe.checksStatus` value that
+ * `classifyMergeBlock` reads.
+ */
+
+/**
+ * Default poll interval and cumulative budget for the merge wait. The schema
+ * in `.agents/schemas/agentrc.schema.json` exposes these as
+ * `delivery.mergeWatch.intervalSeconds` (default 30) and
+ * `delivery.mergeWatch.maxBudgetSeconds` (default 3600). Hard-coding the same
+ * numbers here keeps the close path self-contained when no config is wired in
+ * (e.g. unit tests).
+ */
+export const DEFAULT_INTERVAL_SECONDS = 30;
+export const DEFAULT_MAX_BUDGET_SECONDS = 3600;
+
+/**
+ * Pure: derive an aggregate `checksStatus` (`success` | `still-running` |
+ * `failure` | `unknown`) from a `statusCheckRollup` array (`gh pr view --json
+ * statusCheckRollup` shape: `{ status, conclusion }` per check). Mirrors the
+ * values `classifyMergeBlock` expects on `prProbe.checksStatus`.
+ *
+ * **Scope: EVERY check reported on the PR, required or not.** The rollup
+ * carries no required-vs-optional discriminator (`gh`'s projection has no
+ * `isRequired` field), so `failure` here means "something on this PR is red",
+ * NOT "the merge is blocked". Use {@link failingChecksBlockMerge} before
+ * treating a `failure` as terminal.
+ */
+export function deriveChecksStatus(statusCheckRollup) {
+  if (!Array.isArray(statusCheckRollup) || statusCheckRollup.length === 0) {
+    return 'unknown';
+  }
+  let anyPending = false;
+  for (const check of statusCheckRollup) {
+    const conclusion = String(check?.conclusion ?? '').toUpperCase();
+    const status = String(check?.status ?? '').toUpperCase();
+    if (['FAILURE', 'CANCELLED', 'TIMED_OUT', 'ERROR'].includes(conclusion)) {
+      return 'failure';
+    }
+    if (status !== 'COMPLETED') {
+      anyPending = true;
+    }
+  }
+  return anyPending ? 'still-running' : 'success';
+}
+
+/**
+ * The one `mergeStateStatus` value that means GitHub itself is gating the
+ * merge. See {@link failingChecksBlockMerge}.
+ */
+const MERGE_GATED_STATE = 'BLOCKED';
+
+/**
+ * Pure: does the PR's RED check status actually gate the merge?
+ *
+ * `deriveChecksStatus` aggregates the whole rollup, so it reports `failure`
+ * for a red check of any kind. Branch protection — and therefore GitHub
+ * native auto-merge — gates only on REQUIRED checks. A red optional check
+ * (an advisory bot, or a `CANCELLED` superseded workflow run, which the
+ * rollup derivation counts as a failure) says nothing about whether the PR
+ * will land: auto-merge lands it regardless. Treating that as terminal is
+ * what stranded a Story `agent::blocked` on a PR that merged anyway.
+ *
+ * `mergeStateStatus` is GitHub's own verdict, computed against the live
+ * branch-protection rules, so it supplies the required-vs-optional
+ * discrimination the rollup lacks:
+ *
+ *   - `BLOCKED`  — merging is gated. With red checks observed, the red
+ *                  required check is the gate.
+ *   - `UNSTABLE` — "mergeable with non-passing commit status": the red
+ *                  checks are NOT required. Auto-merge will land it.
+ *   - `CLEAN` / `BEHIND` / `UNKNOWN` / absent — not evidence that the red
+ *     check gates the merge.
+ *
+ * Deliberately conservative: only `BLOCKED` returns `true`. A transient
+ * `UNKNOWN` (GitHub has not finished computing the merge state) or a token
+ * that cannot see the field degrades to "keep waiting" — the caller's poll
+ * budget still bounds the wait and the budget-exhausted classification still
+ * fires. The asymmetry is intentional: failing to fail fast costs poll time,
+ * whereas failing fast wrongly costs a merged-but-`agent::blocked` strand
+ * that only an operator can unpick.
+ *
+ * @param {{ checksStatus?: string, mergeStateStatus?: string }} [prProbe]
+ * @returns {boolean}
+ */
+export function failingChecksBlockMerge(prProbe) {
+  if (prProbe?.checksStatus !== 'failure') return false;
+  return (
+    String(prProbe?.mergeStateStatus ?? '').toUpperCase() === MERGE_GATED_STATE
+  );
+}

package/.agents/scripts/lib/orchestration/phase-runner.js

@@ -1,8 +1,9 @@
 /**
  * phase-runner.js — Lightweight wrappers for "named phase" error handling.
  *
- * Many orchestration entry points (story-init, story-close,
- * the epic-runner submodules) repeat the same `try { ... } catch (err) {
+ * Many orchestration entry points (`single-story-init.js`,
+ * `single-story-close.js`, and other phase modules) repeat the same
+ * `try { ... } catch (err) {
  * logger.error('[phase=foo] ' + err.message); ... }` block. These two
  * helpers consolidate that pattern.
  *