mandrel 1.89.0 → 1.91.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-armer.js

@@ -54,7 +54,10 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { parsePrNumberFromUrl } from '../../../github-url.js';
 import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
+import { classifyMergeBlock } from '../../merge-block-class.js';
+import { emitMergeUnlanded } from '../emit-merge-unlanded.js';
 
 /**
  * Default `gh pr view --json autoMergeRequest` probe. Pure-spawn helper
@@ -109,6 +112,64 @@ export function ghPrMergeAuto({
   };
 }
 
+/**
+ * Story #4472 — direct (non-`--auto`) squash-merge fallback.
+ *
+ * GitHub's native auto-merge (`gh pr merge --auto`) can only be QUEUED on a
+ * repository that has the "Allow auto-merge" setting enabled — which in
+ * practice requires branch protection. A repo with zero required checks and
+ * no branch protection (every mandrel-bench sandbox, many real consumer
+ * repos) rejects the `--auto` arm outright with `Auto merge is not allowed
+ * for this repository`. The AutomergePredicate has already cleared the merge
+ * (green/absent required checks + a clean structured-signal verdict) by the
+ * time the armer runs, so the safe, must-land-satisfying fallback is a
+ * direct immediate squash-merge — the epic path's observed de-facto manual
+ * fallback, made legal and kept inside the sole authorized `gh pr merge`
+ * call site.
+ *
+ * Same `--squash --delete-branch` shape and same `resolveArmCwd` re-point as
+ * `ghPrMergeAuto` (so the trailing local `--delete-branch` housekeeping runs
+ * from the primary worktree, not a head-branch worktree). Omitting `--auto`
+ * makes `gh` merge synchronously.
+ */
+export function ghPrMergeDirect({
+  prUrl,
+  cwd,
+  spawnFn = spawnSync,
+  resolveArmCwd = resolveAutoMergeArmCwd,
+}) {
+  const armCwd = resolveArmCwd(cwd);
+  const result = spawnFn(
+    'gh',
+    ['pr', 'merge', prUrl, '--squash', '--delete-branch'],
+    { cwd: armCwd, encoding: 'utf-8', shell: false },
+  );
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Pure: does this `gh pr merge --auto` stderr indicate that native
+ * auto-merge is unavailable on the repository (as opposed to a genuine arm
+ * failure — auth, a merge conflict, an already-merged race)? Only this
+ * specific class of failure is safe to retry as a direct merge; everything
+ * else must surface as a real failure. Matched case-insensitively.
+ *
+ * Exported so the marker set is reviewable and testable in isolation.
+ */
+export function isAutoMergeUnavailable(stderr) {
+  const text = String(stderr ?? '').toLowerCase();
+  return (
+    text.includes('auto merge is not allowed') ||
+    text.includes('auto-merge is not allowed') ||
+    text.includes('enablepullrequestautomerge') ||
+    (text.includes('auto') && text.includes('not enabled'))
+  );
+}
+
 /**
  * Pure: parse `gh pr view --json autoMergeRequest,mergeCommit` output.
  * `autoMergeRequest` is `null` when auto-merge is NOT armed; a non-null
@@ -172,9 +233,17 @@ export class AutomergeArmer {
   /**
    * @param {object} opts
    * @param {object} opts.bus
+   * @param {number} [opts.epicId] Epic id — required for the headless
+   *   `merge.unlanded` attribution on a genuine arm failure (Story #4472).
+   * @param {boolean} [opts.headless] When true (a `/deliver --yes` run), a
+   *   genuine (non-fallback) arm failure escalates to an explicit
+   *   `merge.unlanded` + `epic.blocked` terminal instead of returning
+   *   silently (Story #4472). Defaults to `false` (attended).
    * @param {string} [opts.cwd]
    * @param {Function} [opts.ghPrViewAutoMergeFn] override for tests.
    * @param {Function} [opts.ghPrMergeAutoFn] override for tests.
+   * @param {Function} [opts.ghPrMergeDirectFn] override for tests.
+   * @param {Function} [opts.emitMergeUnlandedFn] override for tests.
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
@@ -186,9 +255,13 @@ export class AutomergeArmer {
       throw new TypeError('AutomergeArmer requires a bus with on() and emit()');
     }
     this.bus = opts.bus;
+    this.epicId = Number.isInteger(opts.epicId) ? opts.epicId : null;
+    this.headless = opts.headless === true;
     this.cwd = opts.cwd ?? process.cwd();
     this.ghPrViewAutoMergeFn = opts.ghPrViewAutoMergeFn ?? ghPrViewAutoMerge;
     this.ghPrMergeAutoFn = opts.ghPrMergeAutoFn ?? ghPrMergeAuto;
+    this.ghPrMergeDirectFn = opts.ghPrMergeDirectFn ?? ghPrMergeDirect;
+    this.emitMergeUnlandedFn = opts.emitMergeUnlandedFn ?? emitMergeUnlanded;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
@@ -293,16 +366,26 @@ export class AutomergeArmer {
         await this._emitArmed(prUrl);
         return;
       }
-      this.classifications.push({
+
+      // Story #4472 — native auto-merge is unavailable on this repository
+      // (no branch protection / "Allow auto-merge" disabled). The predicate
+      // already cleared the merge, so fall back to a direct immediate
+      // squash-merge instead of stranding a landable PR on the
+      // operator-merges path.
+      if (isAutoMergeUnavailable(arm.stderr)) {
+        const armed = await this._tryDirectMerge({ event, seqId, prUrl, arm });
+        if (armed) return;
+      }
+
+      // Genuine arm failure (auth, conflict, an unresolved direct-merge
+      // fallback, …). Classify + escalate.
+      await this._emitArmFailure({
         event,
         seqId,
-        outcome: 'failed',
+        prUrl,
         reason: `arm-failed:status=${arm.status}`,
         ghStderr: arm.stderr,
       });
-      this.logger.warn?.(
-        `[AutomergeArmer] gh pr merge --auto failed (status=${arm.status}): ${arm.stderr}`,
-      );
       return;
     }
 
@@ -320,6 +403,97 @@ export class AutomergeArmer {
     }
   }
 
+  /**
+   * Story #4472 — direct-merge fallback when native auto-merge is
+   * unavailable. Runs an immediate `gh pr merge --squash --delete-branch`
+   * (no `--auto`) then re-probes; on a confirmed merge (or the same
+   * post-merge `--delete-branch` housekeeping grumble the `--auto` path
+   * already tolerates) it emits `epic.merge.armed` so the
+   * MergeWatcher → Cleaner → LabelTransitioner chain engages and confirms
+   * the merge on its first poll.
+   *
+   * @returns {Promise<boolean>} `true` when the fallback landed the PR (an
+   *   `epic.merge.armed` was emitted); `false` when the direct merge did
+   *   not land, so the caller escalates the original arm failure.
+   */
+  async _tryDirectMerge({ event, seqId, prUrl, arm }) {
+    this.logger.info?.(
+      `[AutomergeArmer] native auto-merge unavailable (${arm.stderr?.trim?.() ?? arm.stderr}); falling back to a direct squash-merge on ${prUrl}.`,
+    );
+    const direct = this.ghPrMergeDirectFn({ prUrl, cwd: this.cwd });
+    const recheck = this.ghPrViewAutoMergeFn({ prUrl, cwd: this.cwd });
+    const merged =
+      recheck.status === 0 &&
+      (parsePrMerged(recheck.stdout) || parseAutoMergeArmed(recheck.stdout));
+    if (direct.status === 0 || merged) {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'armed',
+        prUrl,
+        note: `direct-merge fallback (native auto-merge unavailable); direct exit ${direct.status}${direct.status !== 0 ? ` but re-probe shows merged/armed (housekeeping stderr: ${direct.stderr})` : ''}`,
+      });
+      await this._emitArmed(prUrl);
+      return true;
+    }
+    this.logger.warn?.(
+      `[AutomergeArmer] direct-merge fallback failed (status=${direct.status}): ${direct.stderr}`,
+    );
+    return false;
+  }
+
+  /**
+   * Classify + (in headless) escalate a genuine arm failure. The `--auto`
+   * path historically returned silently here; a `/deliver --yes` run has no
+   * operator to notice, so we mirror the MergeWatcher's terminal:
+   * `merge.unlanded` ledger attribution + an explicit `epic.blocked`
+   * transition. Attended runs keep the classify-and-return behaviour.
+   */
+  async _emitArmFailure({ event, seqId, prUrl, reason, ghStderr }) {
+    this.classifications.push({
+      event,
+      seqId,
+      outcome: 'failed',
+      reason,
+      ghStderr,
+    });
+    this.logger.warn?.(
+      `[AutomergeArmer] gh pr merge --auto failed (${reason}): ${ghStderr}`,
+    );
+    if (!this.headless) return;
+    const classification = classifyMergeBlock({
+      armResult: { armed: false, reason: ghStderr },
+    });
+    const prNumber = parsePrNumberFromUrl(prUrl);
+    if (
+      Number.isInteger(this.epicId) &&
+      Number.isInteger(prNumber) &&
+      prNumber > 0
+    ) {
+      try {
+        this.emitMergeUnlandedFn({
+          scope: 'epic',
+          ticketId: this.epicId,
+          prNumber,
+          blockClass: classification.blockClass,
+          reason: classification.reason,
+          elapsedSeconds: 0,
+        });
+      } catch (err) {
+        this.logger.warn?.(
+          `[AutomergeArmer] emitMergeUnlanded failed (swallowed): ${err?.message ?? err}`,
+        );
+      }
+    }
+    try {
+      await this.bus.emit('epic.blocked', { reason: `merge-arm:failed` });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergeArmer] epic.blocked emit on arm failure failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
+  }
+
   reset() {
     this._seen.clear();
     this.classifications = [];

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -68,8 +68,10 @@ import { spawnSync } from 'node:child_process';
 
 import { hasSurvivingCritical } from '../../../audit-suite/findings.js';
 import { getCiDelivery } from '../../../config/ci.js';
+import { parsePrNumberFromUrl } from '../../../github-url.js';
 import * as epicRunStateStore from '../../epic-run-state-store.js';
 import { findStructuredComment } from '../../ticketing.js';
+import { emitMergeUnlanded } from '../emit-merge-unlanded.js';
 import { normalizeCheckState, RECOGNIZED_CHECK_STATES } from './watcher.js';
 
 /**
@@ -224,19 +226,51 @@ export function probeRequiredChecks({ prUrl, cwd, spawnFn = spawnSync }) {
  * stdout. We parse stdout first (it is populated even on the non-zero
  * exit) and classify from the outcomes.
  *
+ * Story #4472 — checks-less repos. In a repo with zero required checks
+ * (no branch protection, or protection that requires no status checks),
+ * `gh pr checks --required` writes NOTHING to stdout and reports
+ * `no checks reported on the <branch> branch` to stderr with a non-zero
+ * exit. That is the SAME empty-parsed-set condition the outcomes loop
+ * below already treats as green — there is simply nothing to gate on — so
+ * we must not conflate it with a genuine probe failure (auth, network, no
+ * PR). We detect the `no checks reported` stderr signature and return
+ * green, UNLESS the consumer opted into `delivery.ci.requireChecks`, in
+ * which case the absent CI gate is a deliberate hard block.
+ *
  * @param {{ status: number, stdout: string, stderr: string }} probe
+ * @param {{ requireChecks?: boolean }} [opts] When `requireChecks` is
+ *   true, a checks-less repo fails closed instead of arming.
  * @returns {{ ok: boolean, reason: string|null, outcomes: Record<string, string> }}
  */
-export function classifyRequiredChecksProbe(probe) {
+export function classifyRequiredChecksProbe(
+  probe,
+  { requireChecks = false } = {},
+) {
   const stdout = String(probe?.stdout ?? '').trim();
-  // Empty stdout with a non-zero status → probe genuinely failed (auth,
-  // network, no PR). Fail closed.
+  const stderr = String(probe?.stderr ?? '').trim();
+  // Empty stdout: either a checks-less repo (green, nothing to gate on) or
+  // a genuine probe failure. The `no checks reported` stderr signature
+  // distinguishes them.
   if (stdout.length === 0) {
+    const noChecksReported = /no checks reported/i.test(stderr);
+    if (noChecksReported && !requireChecks) {
+      // Zero required checks configured — matches the empty-parsed-set
+      // "treated as green" branch below. Nothing to gate on.
+      return { ok: true, reason: null, outcomes: {} };
+    }
+    if (noChecksReported && requireChecks) {
+      return {
+        ok: false,
+        reason:
+          'no required checks reported and delivery.ci.requireChecks is set — failing closed per policy',
+        outcomes: {},
+      };
+    }
     return {
       ok: false,
       reason:
         `live required-check probe failed (status=${probe?.status ?? 'unknown'})` +
-        (probe?.stderr ? `: ${String(probe.stderr).trim().slice(0, 200)}` : ''),
+        (stderr ? `: ${stderr.slice(0, 200)}` : ''),
       outcomes: {},
     };
   }
@@ -678,8 +712,13 @@ export class AutomergePredicate {
    *   evaluator). Required for the read of run-state + structured
    *   comments.
    * @param {object} [opts.config] Resolved agent config. Read for the
-   *   `delivery.ci.autoMerge` policy via `getCiDelivery`. Defaults to the
-   *   framework default (`trust-ci`) when omitted.
+   *   `delivery.ci.autoMerge` policy and the `delivery.ci.requireChecks`
+   *   fail-closed-without-checks policy via `getCiDelivery`. Defaults to the
+   *   framework defaults (`trust-ci` / `requireChecks: false`) when omitted.
+   * @param {boolean} [opts.headless] When true (a `/deliver --yes` run), a
+   *   predicate refusal escalates to an explicit `merge.unlanded` +
+   *   `epic.blocked` terminal instead of silently parking on the
+   *   operator-merges path (Story #4472). Defaults to `false` (attended).
    * @param {string} [opts.cwd] Working directory for the live
    *   `gh pr checks --required` probe. Defaults to `process.cwd()`.
    * @param {Function} [opts.evaluatePredicateFn] override of
@@ -708,13 +747,20 @@ export class AutomergePredicate {
     this.epicId = opts.epicId;
     this.provider = opts.provider;
     this.cwd = opts.cwd ?? process.cwd();
-    // Resolve the merge posture once at construction. `getCiDelivery`
-    // applies the framework default (`trust-ci`) for any omitted field.
-    this.policy = getCiDelivery(opts.config ?? null).autoMerge;
+    // Resolve the merge posture + fail-closed policy once at construction.
+    // `getCiDelivery` applies the framework defaults (`trust-ci` /
+    // `requireChecks: false`) for any omitted field.
+    const ci = getCiDelivery(opts.config ?? null);
+    this.policy = ci.autoMerge;
+    this.requireChecks = ci.requireChecks;
+    this.headless = opts.headless === true;
     this.evaluatePredicateFn =
       opts.evaluatePredicateFn ?? evaluateAutoMergePredicate;
     this.probeRequiredChecksFn =
       opts.probeRequiredChecksFn ?? probeRequiredChecks;
+    // Injected for tests so the headless terminal escalation can be
+    // observed without touching disk.
+    this.emitMergeUnlandedFn = opts.emitMergeUnlandedFn ?? emitMergeUnlanded;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
@@ -786,7 +832,9 @@ export class AutomergePredicate {
       let probeVerdict;
       try {
         const probe = this.probeRequiredChecksFn({ prUrl, cwd: this.cwd });
-        probeVerdict = classifyRequiredChecksProbe(probe);
+        probeVerdict = classifyRequiredChecksProbe(probe, {
+          requireChecks: this.requireChecks,
+        });
       } catch (err) {
         probeVerdict = {
           ok: false,
@@ -878,6 +926,17 @@ export class AutomergePredicate {
    * Emit `epic.merge.blocked`. Helper carved out so the blocking paths
    * (CI failure / predicate dirty / evaluator throw) share the same emit
    * shape.
+   *
+   * Story #4472 — must-land coverage of predicate refusal. In a headless
+   * (`/deliver --yes`) run there is no operator to act on a bare
+   * `epic.merge.blocked` (nothing in the listener chain consumes it), so
+   * the run would silently park on the operator-merges path. When
+   * `this.headless`, we additionally attribute the refusal to the
+   * lifecycle ledger via `merge.unlanded` (blockClass `predicate-refused`)
+   * and drive the explicit `epic.blocked` terminal — the same
+   * escalation the MergeWatcher performs on post-arm budget exhaustion —
+   * so the Epic transitions to `agent::blocked` with an operator-visible
+   * reason instead of stalling.
    */
   async _emitBlocked(prUrl, reason) {
     try {
@@ -887,6 +946,35 @@ export class AutomergePredicate {
         `[AutomergePredicate] epic.merge.blocked emit failed (swallowed): ${err?.message ?? err}`,
       );
     }
+    if (!this.headless) return;
+    // Ledger attribution — best-effort; a failed append must NOT mask the
+    // epic.blocked transition below.
+    try {
+      const prNumber = parsePrNumberFromUrl(prUrl);
+      if (Number.isInteger(prNumber) && prNumber > 0) {
+        this.emitMergeUnlandedFn({
+          scope: 'epic',
+          ticketId: this.epicId,
+          prNumber,
+          blockClass: 'predicate-refused',
+          reason,
+          elapsedSeconds: 0,
+        });
+      }
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergePredicate] emitMergeUnlanded failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
+    try {
+      await this.bus.emit('epic.blocked', {
+        reason: `merge-predicate:refused`,
+      });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergePredicate] epic.blocked emit on predicate refusal failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
   }
 
   reset() {

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

@@ -82,6 +82,7 @@ import {
   openOrLocatePr as defaultOpenOrLocatePr,
 } from '../../finalize/open-or-locate-pr.js';
 import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/post-handoff-comment.js';
+import { probeRemoteBranch as defaultProbeRemoteBranch } from '../../remote-verifier.js';
 
 /**
  * Build the production default `runFinalizeFn` that composes the
@@ -103,12 +104,22 @@ import { postHandoffComment as defaultPostHandoffComment } from '../../finalize/
  * contract is identical and `markPrReady` is a no-op on an already-ready
  * PR, so replay stays idempotent.
  *
+ * Issue #4483 — deterministic land-or-block backstop. Before opening (or
+ * readying) the PR, finalize asserts the delivery branch `epic/<id>`
+ * actually exists on origin. A delivery that was never pushed — e.g. an
+ * agent that built the Epic inline on local `main` and skipped the
+ * orchestration — MUST surface as an explicit
+ * `delivery-branch-missing-on-origin` blocker (which keeps the Epic at
+ * `agent::blocked`), never a declared success. The probe is bounded
+ * (timeout + SIGKILL) so a hung remote degrades to a blocker too.
+ *
  * @param {{
  *   provider?: object|null,
  *   earlyPr?: boolean,
  *   openOrLocatePrFn?: typeof defaultOpenOrLocatePr,
  *   markPrReadyFn?: typeof defaultMarkPrReady,
  *   postHandoffCommentFn?: typeof defaultPostHandoffComment,
+ *   probeRemoteBranchFn?: typeof defaultProbeRemoteBranch,
  * }} deps
  */
 export function composeBusOwnedFinalize(deps = {}) {
@@ -116,6 +127,8 @@ export function composeBusOwnedFinalize(deps = {}) {
   const markPrReadyFn = deps.markPrReadyFn ?? defaultMarkPrReady;
   const postHandoffCommentFn =
     deps.postHandoffCommentFn ?? defaultPostHandoffComment;
+  const probeRemoteBranchFn =
+    deps.probeRemoteBranchFn ?? defaultProbeRemoteBranch;
   const provider = deps.provider ?? null;
   const earlyPr = deps.earlyPr !== false;
 
@@ -128,6 +141,25 @@ export function composeBusOwnedFinalize(deps = {}) {
         },
       };
     }
+
+    // Issue #4483 backstop — the delivery branch MUST be on origin before
+    // finalize declares any success. A never-pushed branch is the silent
+    // local-main failure shape; block explicitly with the probe detail.
+    let branchProbe;
+    try {
+      branchProbe = probeRemoteBranchFn({ branch: `epic/${epicId}`, cwd });
+    } catch (err) {
+      branchProbe = { exists: false, detail: err?.message ?? String(err) };
+    }
+    if (!branchProbe.exists) {
+      return {
+        blocker: {
+          reason: 'delivery-branch-missing-on-origin',
+          detail: `epic/${epicId} is not on origin — the delivery was never pushed; refusing to finalize (issue #4483). Probe: ${branchProbe.detail}`,
+        },
+      };
+    }
+
     let openResult;
     try {
       openResult = await openOrLocatePrFn({

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

@@ -226,10 +226,15 @@ export async function buildDefaultListenerChain(opts = {}) {
   order.push('Finalizer');
 
   // 4. AutomergeArmer — arms `gh pr merge --auto --squash --delete-branch`
-  //    on epic.merge.ready.
+  //    on epic.merge.ready. Story #4472: `headless` gates the direct-merge
+  //    fallback's terminal escalation (a genuine arm failure emits
+  //    `merge.unlanded` + `epic.blocked` in a `--yes` run instead of
+  //    returning silently); `epicId` scopes the `merge.unlanded` ledger row.
   const automergeArmer = new AutomergeArmer({
     bus,
+    epicId,
     cwd: repoRoot,
+    headless,
     logger,
   });
   automergeArmer.register();
@@ -250,6 +255,7 @@ export async function buildDefaultListenerChain(opts = {}) {
       provider,
       config,
       cwd: repoRoot,
+      headless,
       logger,
     });
     automergePredicate.register();

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

@@ -10,7 +10,7 @@
  * one of four classes from the SAME decision logic, instead of each path
  * inventing its own ad hoc diagnosis.
  *
- * Block classes (Epic #4425 Goal):
+ * 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
@@ -33,6 +33,18 @@
  *                                         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`,
@@ -55,12 +67,28 @@ export const BLOCK_CLASSES = Object.freeze([
   'api-race-other',
 ]);
 
-const BLOCK_CLASS_SET = new Set(BLOCK_CLASSES);
+/**
+ * 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 one of the four canonical
- *   block classes.
+ * @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);