mandrel 1.88.0 → 1.90.0

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

@@ -41,11 +41,47 @@
  * labels, post comments, or call `notify`. Downstream listeners
  * (Cleaner / LabelTransitioner on `epic.merge.confirmed`, Task #2912)
  * own those side effects.
+ *
+ * Must-land terminal step (Story #4427, Epic #4425 slice 2). In
+ * headless (`--yes`) delivery runs — signalled via the explicit
+ * `headless` constructor option, threaded from `/deliver`'s `--yes`
+ * flag through `lifecycle-emit.js`'s `--headless` runtime flag and
+ * `buildDefaultListenerChain({ headless })` — budget exhaustion no
+ * longer falls straight through to `epic.blocked`. Instead the watcher
+ * classifies the block (`classifyMergeBlock`, the shared classifier
+ * from Story #4426) and, bounded by one attempt each per watch run:
+ *
+ *   - `checks-pending-timeout` (required checks still progressing) →
+ *     extend the watch budget once and keep polling in the SAME watch
+ *     cycle.
+ *   - `api-race-other` (no definitive block signal) → re-arm once by
+ *     re-emitting `epic.merge.ready` on the bus. This does NOT call
+ *     `gh pr merge` directly — AutomergeArmer remains the sole
+ *     authorized call site (merge-lockout invariant, Story #4427 AC).
+ *     AutomergeArmer's own idempotent `gh pr view` probe short-circuits
+ *     to a single `epic.merge.armed` re-emit when auto-merge is
+ *     already armed on the PR, which re-triggers this watcher's
+ *     `handle()` for a fresh watch cycle that continues the resume
+ *     ledger's attempt count.
+ *   - `branch-protection-human-required`, or retries already
+ *     exhausted (both bounded attempts spent) → terminal: emit
+ *     `merge.unlanded` (scope `"epic"`, carrying the block class) via
+ *     `emitMergeUnlanded`, THEN fall through to the existing single
+ *     `epic.blocked` emit below — one blocked path, never a duplicate
+ *     `agent::blocked` transition.
+ *
+ * Attended-mode (headless === false, the default) behavior is
+ * byte-for-byte unchanged: budget exhaustion emits exactly
+ * `epic.blocked` with `reason: 'merge-watch:budget-exceeded'`, no
+ * classification, no retry, no `merge.unlanded`.
  */
 
 import { spawnSync } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { parsePrNumberFromUrl } from '../../../github-url.js';
+import { classifyMergeBlock } from '../../merge-block-class.js';
+import { emitMergeUnlanded } from '../emit-merge-unlanded.js';
 
 /**
  * Default poll interval and budget. The schema in
@@ -59,15 +95,31 @@ export const DEFAULT_INTERVAL_SECONDS = 30;
 export const DEFAULT_MAX_BUDGET_SECONDS = 3600;
 
 /**
- * Default `gh pr view --json mergeCommit,mergedAt` probe. Pure-spawn
+ * Fields requested from `gh pr view` on every poll. The merge-confirm
+ * fields (`mergeCommit`, `mergedAt`, `number`) are the original Story
+ * #2896 contract; `mergeStateStatus`, `reviewDecision`, and
+ * `statusCheckRollup` were added in Story #4427 so a headless
+ * budget-exhaustion path can classify the block (`classifyMergeBlock`)
+ * from the SAME probe already being polled, instead of issuing a
+ * second `gh` call.
+ */
+const PR_VIEW_JSON_FIELDS =
+  'mergeCommit,mergedAt,number,mergeStateStatus,reviewDecision,statusCheckRollup';
+
+/**
+ * Default `gh pr view --json <PR_VIEW_JSON_FIELDS>` probe. Pure-spawn
  * helper — exported so tests can stub the shell-out without touching
  * the spawn wrapper.
  */
 export function ghPrViewMerge({ prUrl, cwd, spawnFn = spawnSync }) {
   const result = spawnFn(
     'gh',
-    ['pr', 'view', prUrl, '--json', 'mergeCommit,mergedAt,number'],
-    { cwd, encoding: 'utf-8', shell: false },
+    ['pr', 'view', prUrl, '--json', PR_VIEW_JSON_FIELDS],
+    {
+      cwd,
+      encoding: 'utf-8',
+      shell: false,
+    },
   );
   return {
     status: result.status ?? 1,
@@ -77,24 +129,58 @@ export function ghPrViewMerge({ prUrl, cwd, spawnFn = spawnSync }) {
 }
 
 /**
- * Parse `gh pr view --json mergeCommit,mergedAt,number` output.
- * Returns `{ mergeCommitSha, mergedAt, prNumber }` where
- * `mergeCommitSha` is `null` until the PR has merged. Pure — exported
- * for tests so the JSON-shape pin is reviewable.
+ * Pure: derive an aggregate `checksStatus` (`success` | `pending` |
+ * `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`.
+ */
+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';
+}
+
+/**
+ * Parse `gh pr view --json <PR_VIEW_JSON_FIELDS>` output. Returns
+ * `{ mergeCommitSha, mergedAt, prNumber, mergeStateStatus,
+ * reviewDecision, checksStatus }` where `mergeCommitSha` is `null`
+ * until the PR has merged. Pure — exported for tests so the
+ * JSON-shape pin is reviewable.
  */
 export function parseMergeView(stdout) {
+  const empty = {
+    mergeCommitSha: null,
+    mergedAt: null,
+    prNumber: null,
+    mergeStateStatus: null,
+    reviewDecision: null,
+    checksStatus: 'unknown',
+  };
   const trimmed = String(stdout ?? '').trim();
   if (trimmed.length === 0) {
-    return { mergeCommitSha: null, mergedAt: null, prNumber: null };
+    return empty;
   }
   let parsed;
   try {
     parsed = JSON.parse(trimmed);
   } catch {
-    return { mergeCommitSha: null, mergedAt: null, prNumber: null };
+    return empty;
   }
   if (!parsed || typeof parsed !== 'object') {
-    return { mergeCommitSha: null, mergedAt: null, prNumber: null };
+    return empty;
   }
   const merge = parsed.mergeCommit;
   const sha =
@@ -103,9 +189,35 @@ export function parseMergeView(stdout) {
       : null;
   const mergedAt = typeof parsed.mergedAt === 'string' ? parsed.mergedAt : null;
   const prNumber = Number.isInteger(parsed.number) ? parsed.number : null;
-  return { mergeCommitSha: sha, mergedAt, prNumber };
+  const mergeStateStatus =
+    typeof parsed.mergeStateStatus === 'string'
+      ? parsed.mergeStateStatus
+      : null;
+  const reviewDecision =
+    typeof parsed.reviewDecision === 'string' ? parsed.reviewDecision : null;
+  const checksStatus = deriveChecksStatus(parsed.statusCheckRollup);
+  return {
+    mergeCommitSha: sha,
+    mergedAt,
+    prNumber,
+    mergeStateStatus,
+    reviewDecision,
+    checksStatus,
+  };
 }
 
+// `parsePrNumberFromUrl` (imported above from the Story #3649 canonical
+// `lib/github-url.js` helper) is the last-resort fallback for a `gh pr
+// view` probe that never successfully returned `number` (e.g. every poll
+// on the final watch cycle probe-failed). `emitMergeUnlanded` requires a
+// positive-integer `prNumber`, and `prUrl` is always present by the time
+// a watch cycle starts (checked in `handle()`), so this is the
+// last-resort source of truth. Re-exported here so existing imports of
+// `parsePrNumberFromUrl` from this module (e.g.
+// `tests/epic-must-land-terminal.test.js`) keep working without a
+// duplicate implementation (code-review finding, Epic #4425).
+export { parsePrNumberFromUrl };
+
 /**
  * Resolve the resume-ledger path for an Epic. Pure helper — exported
  * so tests can pin the layout.
@@ -194,6 +306,16 @@ export class MergeWatcher {
    *   epoch ms.
    * @param {() => string} [opts.nowIsoFn] override for tests; returns
    *   ISO-8601 wall-clock for the attempt record.
+   * @param {boolean} [opts.headless] Explicit must-land signal (Story
+   *   #4427). Defaults to `false` — attended-mode behavior (immediate
+   *   `epic.blocked` on budget exhaustion, no classification, no
+   *   retry) is unchanged. `true` engages the bounded classify-and-
+   *   retry terminal step. Threaded from `/deliver`'s `--yes` flag via
+   *   `lifecycle-emit.js --headless true` → `buildDefaultListenerChain`
+   *   — an explicit constructor input, never an ambient global.
+   * @param {Function} [opts.emitMergeUnlandedFn] override for tests
+   *   (defaults to the real `emitMergeUnlanded`, which appends to the
+   *   on-disk lifecycle ledger).
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
@@ -229,14 +351,26 @@ export class MergeWatcher {
     this.nowMsFn = opts.nowMsFn ?? Date.now;
     this.nowIsoFn =
       opts.nowIsoFn ?? (() => new Date(this.nowMsFn()).toISOString());
+    this.headless = opts.headless === true;
+    this.emitMergeUnlandedFn = opts.emitMergeUnlandedFn ?? emitMergeUnlanded;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
+    /**
+     * Must-land bounded-retry state (Story #4427, headless only). Each
+     * flips to `true` on its single use across the instance's whole
+     * lifetime — NOT per watch cycle — so a re-armed or budget-extended
+     * cycle that times out again falls straight through to the
+     * `merge.unlanded` terminal rather than retrying indefinitely.
+     */
+    this._budgetExtended = false;
+    this._reArmed = false;
     /**
      * Classification log — every `epic.merge.armed` observed lands
      * here with the outcome (`confirmed`, `budget-exceeded`,
-     * `skipped-duplicate`, `failed`). Mirrors the Armer / Cleaner
-     * "no silent skip" surface.
+     * `skipped-duplicate`, `failed`, or — headless only — `extended` /
+     * `re-armed`). Mirrors the Armer / Cleaner "no silent skip"
+     * surface.
      */
     this.classifications = [];
     // Frozen tuple — MergeWatcher subscribes to EXACTLY one event.
@@ -292,7 +426,9 @@ export class MergeWatcher {
     }
 
     const intervalMs = this.intervalSeconds * 1000;
-    const budgetMs = this.maxBudgetSeconds * 1000;
+    // `let`, not `const`: the headless must-land path extends this
+    // once on a `checks-pending-timeout` classification (Story #4427).
+    let budgetMs = this.maxBudgetSeconds * 1000;
     const startedAtMs = this.nowMsFn();
     let attempt = priorAttempts;
 
@@ -377,6 +513,112 @@ export class MergeWatcher {
       // Not merged. Budget check before sleeping.
       const elapsedMs = this.nowMsFn() - startedAtMs;
       if (elapsedMs + intervalMs > budgetMs) {
+        // Headless must-land: classify the block and try the bounded
+        // per-instance retry (budget extension OR re-arm, each at most
+        // once across this watcher's whole lifetime) before giving up.
+        // Attended mode (this.headless === false) skips straight to the
+        // unchanged budget-exceeded → epic.blocked path below.
+        if (this.headless) {
+          const elapsedSeconds = Math.floor(elapsedMs / 1000);
+          const classification = classifyMergeBlock({
+            prProbe: {
+              reviewDecision: view.reviewDecision,
+              mergeStateStatus: view.mergeStateStatus,
+              checksStatus: view.checksStatus,
+              error:
+                probe.status !== 0
+                  ? probe.stderr || 'gh pr view failed'
+                  : undefined,
+            },
+            budget: { exhausted: true, elapsedSeconds },
+          });
+
+          if (
+            classification.blockClass === 'checks-pending-timeout' &&
+            !this._budgetExtended
+          ) {
+            this._budgetExtended = true;
+            budgetMs += this.maxBudgetSeconds * 1000;
+            this.classifications.push({
+              event,
+              seqId,
+              outcome: 'extended',
+              reason: classification.reason,
+              prUrl,
+              pollAttempts: attempt,
+            });
+            this.logger.info?.(
+              `[MergeWatcher] extending watch budget once (checks-pending-timeout): ${classification.reason}`,
+            );
+            await this.sleepFn(intervalMs);
+            continue;
+          }
+
+          if (
+            classification.blockClass === 'api-race-other' &&
+            !this._reArmed
+          ) {
+            this._reArmed = true;
+            this.classifications.push({
+              event,
+              seqId,
+              outcome: 're-armed',
+              reason: classification.reason,
+              prUrl,
+              pollAttempts: attempt,
+            });
+            this.logger.info?.(
+              `[MergeWatcher] re-arming once (api-race-other): ${classification.reason}`,
+            );
+            let reArmEmitSucceeded = false;
+            try {
+              await this.bus.emit('epic.merge.ready', {
+                prUrl,
+                reason: `must-land retry: ${classification.reason}`,
+              });
+              reArmEmitSucceeded = true;
+            } catch (err) {
+              this.logger.warn?.(
+                `[MergeWatcher] must-land re-arm epic.merge.ready emit failed: ${err?.message ?? err}`,
+              );
+            }
+            if (reArmEmitSucceeded) {
+              // A successful re-arm re-emits epic.merge.armed (via
+              // AutomergeArmer's idempotent-probe short-circuit or a
+              // fresh arm), which re-triggers this watcher's handle()
+              // for a new watch cycle continuing the resume ledger's
+              // attempt count. Do NOT also emit epic.blocked here.
+              return;
+            }
+            // The re-arm attempt itself failed to emit — the bounded
+            // retry is spent with nothing landed. Fall through to the
+            // terminal merge.unlanded + epic.blocked path below rather
+            // than returning silently (audit-quality Critical finding,
+            // Epic #4425): a swallowed re-arm failure must still
+            // surface as an explicit block, never a silent stall.
+          }
+
+          // Terminal: branch-protection-human-required, or both bounded
+          // retries already spent. Emit merge.unlanded before falling
+          // through to the existing single epic.blocked emit below —
+          // one blocked path, never a duplicate agent::blocked
+          // transition.
+          try {
+            this.emitMergeUnlandedFn({
+              scope: 'epic',
+              ticketId: this.epicId,
+              prNumber: view.prNumber ?? parsePrNumberFromUrl(prUrl),
+              blockClass: classification.blockClass,
+              reason: classification.reason,
+              elapsedSeconds,
+            });
+          } catch (err) {
+            this.logger.warn?.(
+              `[MergeWatcher] emitMergeUnlanded failed (swallowed): ${err?.message ?? err}`,
+            );
+          }
+        }
+
         this.classifications.push({
           event,
           seqId,
@@ -416,6 +658,8 @@ export class MergeWatcher {
 
   reset() {
     this._seen.clear();
+    this._budgetExtended = false;
+    this._reArmed = false;
     this.classifications = [];
   }
 }

package/.agents/scripts/lib/orchestration/lifecycle/listeners/notify-dispatcher.js

@@ -147,6 +147,12 @@ export class NotifyDispatcher {
         kind: 'notification.emitted',
         seqId,
         ts: new Date(this._now()).toISOString(),
+        // The common signal envelope requires `epicId` on the record
+        // itself — `hasCommonEnvelope` (lib/signals/schema.js) rejects
+        // rows without it and the read side silently drops them, so
+        // without this field the record was write-only (invisible to
+        // signals-view.js and every other reader).
+        epicId: this.epicId,
         sourceEvent: event,
         webhookEvent,
       };

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

@@ -0,0 +1,246 @@
+// .agents/scripts/lib/orchestration/merge-block-class.js
+/**
+ * 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.
+ *
+ * Block classes (Epic #4425 Goal; `predicate-refused` added by #4472):
+ *   - `checks-pending-timeout`           The watch/poll budget was
+ *                                         exhausted while required checks
+ *                                         were still pending/running — not
+ *                                         a hard block, the run simply ran
+ *                                         out of time.
+ *   - `branch-protection-human-required` GitHub reports the PR needs a
+ *                                         human action: a required review
+ *                                         that hasn't been granted, or a
+ *                                         branch-protection rule the
+ *                                         automation cannot satisfy on its
+ *                                         own.
+ *   - `arm-failure`                      The arm call itself (`gh pr merge
+ *                                         --auto` or equivalent) failed for
+ *                                         a reason that is NOT branch
+ *                                         protection — auth, rate limit, an
+ *                                         already-merged race, a network
+ *                                         error.
+ *   - `api-race-other`                   Fallback for anything that does
+ *                                         not cleanly fit the above three —
+ *                                         a transient GraphQL/API error, an
+ *                                         ambiguous probe result, or a
+ *                                         genuinely novel condition.
+ *   - `predicate-refused`                The AutomergePredicate refused to
+ *                                         arm merge BEFORE any arm attempt —
+ *                                         a red/pending required check, an
+ *                                         unreadable check probe, a dirty
+ *                                         structured-signal verdict, or a
+ *                                         `delivery.ci.requireChecks` policy
+ *                                         block on a checks-less repo (#4472).
+ *                                         The must-land contract previously
+ *                                         only covered post-arm poll
+ *                                         exhaustion, so a predicate refusal
+ *                                         in headless mode silently parked;
+ *                                         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
+ * `single-story-confirm-merge.js` poll) and get back a
+ * `{ blockClass, reason }` verdict ready to hand to `emitMergeUnlanded`
+ * (`emit-merge-unlanded.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.
+ */
+export const BLOCK_CLASSES = Object.freeze([
+  'checks-pending-timeout',
+  'branch-protection-human-required',
+  'arm-failure',
+  'api-race-other',
+]);
+
+/**
+ * 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)
+ * validate against this broader set; the classifier's own reachability
+ * invariant stays scoped to `BLOCK_CLASSES`.
+ */
+export const MERGE_UNLANDED_BLOCK_CLASSES = Object.freeze([
+  ...BLOCK_CLASSES,
+  'predicate-refused',
+]);
+
+const BLOCK_CLASS_SET = new Set(MERGE_UNLANDED_BLOCK_CLASSES);
+
+/**
+ * @param {string} value
+ * @returns {boolean} `true` iff `value` is a valid `merge.unlanded`
+ *   block-class attribution (the four classifier outputs plus the directly-
+ *   emitted `predicate-refused`).
+ */
+export function isValidBlockClass(value) {
+  return BLOCK_CLASS_SET.has(value);
+}
+
+/**
+ * Substrings that identify a branch-protection / human-review rejection
+ * surfaced through an arm call's stderr or reason text. Matched
+ * case-insensitively against the whole string.
+ */
+const BRANCH_PROTECTION_MARKERS = Object.freeze([
+  'review',
+  'required_status_checks',
+  'protected branch',
+  'branch protection',
+  'approval',
+]);
+
+function textIncludesAny(text, markers) {
+  const lower = String(text ?? '').toLowerCase();
+  return markers.some((marker) => lower.includes(marker));
+}
+
+/**
+ * Build the `api-race-other` fallback reason from whatever signal is
+ * available, so the emitted event still carries a specific-as-possible
+ * explanation rather than a bare "unknown".
+ */
+function describeApiRaceFallback(prProbe, budget) {
+  if (prProbe?.error) {
+    return `PR probe error: ${prProbe.error}`;
+  }
+  if (budget && budget.exhausted === true) {
+    return `watch budget exhausted with an unrecognised checks status (${prProbe?.checksStatus ?? 'unknown'})`;
+  }
+  return 'no definitive block signal observed; classified as a transient API race or other condition';
+}
+
+/**
+ * Classify why a delivery run finished without a confirmed merge.
+ *
+ * Evaluation order (first match wins):
+ *   1. Arm failure — the arm call itself did not succeed. A failed arm
+ *      means there is no "armed but stuck" PR left to probe, so this is
+ *      checked before any PR-probe or budget signal. A branch-protection
+ *      rejection surfaced AT arm time still routes to
+ *      `branch-protection-human-required` rather than the generic
+ *      `arm-failure`.
+ *   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
+ *      `mergeStateStatus: 'BLOCKED'` for the entire time required checks
+ *      are still running — a slow-CI timeout would otherwise always
+ *      misclassify as `branch-protection-human-required` and the
+ *      headless once-only budget extension could never engage.
+ *   3. PR-probe human-required signals — `reviewDecision` reporting a
+ *      required review, or `mergeStateStatus: 'BLOCKED'` with checks NOT
+ *      in flight (green/failed checks + BLOCKED = a genuinely human
+ *      gate, e.g. a missing approval).
+ *   4. Fallback — `api-race-other`.
+ *
+ * @param {object} input
+ * @param {object} [input.armResult] Outcome of the arm call.
+ * @param {boolean} [input.armResult.armed] `false` when the arm call
+ *   itself failed (a non-zero `gh pr merge` exit, or arming was refused
+ *   up-front).
+ * @param {string} [input.armResult.reason] Free-form failure detail (e.g.
+ *   `gh` stderr) — inspected for branch-protection markers.
+ * @param {string} [input.armResult.error] Alternate free-form failure
+ *   detail field, checked when `reason` is absent.
+ * @param {object} [input.prProbe] Latest `gh pr view` read.
+ * @param {string} [input.prProbe.reviewDecision] GitHub review decision
+ *   (`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.error] Set when the probe call itself
+ *   errored (network / API failure reading the PR).
+ * @param {object} [input.budget] Poll-budget accounting.
+ * @param {boolean} [input.budget.exhausted] `true` once the watch loop hit
+ *   its budget without observing a confirmed merge.
+ * @param {number} [input.budget.elapsedSeconds] Elapsed watch time in
+ *   seconds, folded into the `reason` text.
+ * @returns {{ blockClass: string, reason: string }}
+ */
+export function classifyMergeBlock(input) {
+  const { armResult, prProbe, budget } = input ?? {};
+
+  // 1. Arm call failure.
+  if (armResult && armResult.armed === false) {
+    const detail = armResult.reason ?? armResult.error ?? '';
+    if (textIncludesAny(detail, BRANCH_PROTECTION_MARKERS)) {
+      return {
+        blockClass: 'branch-protection-human-required',
+        reason:
+          detail ||
+          'arm call rejected: branch protection requires a human action',
+      };
+    }
+    return {
+      blockClass: 'arm-failure',
+      reason: detail || 'arm call failed for an unspecified reason',
+    };
+  }
+
+  // Positive in-flight evidence from the latest probe. Only `pending` /
+  // `still-running` count — `unknown` (empty rollup: a checks-less repo
+  // or a probe race) routes to the api-race re-arm below, and
+  // `undefined` (no probe at all) keeps its budget-timeout mapping in
+  // step 2 without suppressing the step-3 human-required verdict.
+  const checksStatus = prProbe?.checksStatus;
+  const checksPendingEvidence =
+    checksStatus === 'pending' || checksStatus === 'still-running';
+
+  // 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
+  // checks run, so a slow-CI timeout must not read as human-required —
+  // it must consume the headless once-only budget extension instead.
+  if (
+    budget &&
+    budget.exhausted === true &&
+    (checksPendingEvidence || checksStatus === undefined)
+  ) {
+    return {
+      blockClass: 'checks-pending-timeout',
+      reason: `watch budget exhausted after ${budget.elapsedSeconds ?? 'an unknown number of'} seconds with required checks still pending`,
+    };
+  }
+
+  // 3. PR-probe human-required signals. A BLOCKED merge state counts
+  // only without positive checks-in-flight evidence —
+  // BLOCKED-with-settled-checks is a genuinely human gate (e.g. a
+  // missing required approval), whereas BLOCKED-while-checks-run is the
+  // protected-branch steady state.
+  if (prProbe) {
+    if (
+      prProbe.reviewDecision === 'REVIEW_REQUIRED' ||
+      (prProbe.mergeStateStatus === 'BLOCKED' && !checksPendingEvidence)
+    ) {
+      return {
+        blockClass: 'branch-protection-human-required',
+        reason: `PR requires human action (reviewDecision=${prProbe.reviewDecision ?? 'n/a'}, mergeStateStatus=${prProbe.mergeStateStatus ?? 'n/a'})`,
+      };
+    }
+  }
+
+  // 4. Fallback.
+  return {
+    blockClass: 'api-race-other',
+    reason: describeApiRaceFallback(prProbe, budget),
+  };
+}

package/.agents/scripts/lib/orchestration/plan-review-routing.js

@@ -24,7 +24,7 @@ const AUTO_PROCEED_MESSAGE =
   'Planning risk is low — auto-proceeding to Phase 8 decomposition after spec validation. Context tickets remain open until Epic delivery finalizes.';
 
 const REVIEW_REQUIRED_MESSAGE =
-  'Planning risk requires operator review — STOP before Phase 8. Review the PRD, Tech Spec, and Acceptance Spec on GitHub and confirm in this session before decomposition.';
+  'Planning risk requires operator review — STOP before Phase 8. Review the Tech Spec sections and the Acceptance Table — both managed sections of the Epic body — on GitHub and confirm in this session before decomposition.';
 
 const FORCE_REVIEW_MESSAGE =
   'Operator override — forcing review stop before Phase 8 despite low planning risk.';

package/.agents/scripts/lib/orchestration/post-merge/phases/worktree-reap.js

@@ -119,12 +119,12 @@ async function emitReapFailureFriction({
       storyId: Number(storyId),
       signal: {
         kind: 'friction',
-        timestamp: new Date().toISOString(),
+        ts: new Date().toISOString(),
         epicId: Number(epicId),
         storyId: Number(storyId),
         category: 'reap-failure',
-        source: { tool: 'story-close.js' },
-        details: `Worktree reap failed: ${reason}`,
+        emitter: { tool: 'story-close.js' },
+        details: { message: `Worktree reap failed: ${reason}` },
         epicBranch,
         worktreePath: wtPath,
         reason,