@nanobpm/nano-workforce 0.110.0 → 0.111.1

package/app/github.test.ts

@@ -3,7 +3,8 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
+import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol, type RequiredCheck } from "./mergeProtocol.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -440,6 +441,8 @@ function prState(over: Partial<PrState>): PrState {
     failingChecks: 0,
     failingCheckNames: [],
     presentCheckNames: [],
+    pendingCheckNames: [],
+    checkConclusions: {},
     totalChecks: 0,
     isDraft: false,
     headRefOid: null,
@@ -463,3 +466,224 @@ test("classifyPrLiveness: a closed-not-merged PR is terminal (abandon)", () => {
 test("classifyPrLiveness: a null read (transport hiccup) is unknown — never abandons blind", () => {
   assertEquals(classifyPrLiveness(null), "unknown");
 });
+
+// ── classifyMergeability: protocol-aware required-checks backstop (issue #392) ────────────────────
+//
+// The merge poller must NOT merge a PR whose DECLARED-required check is red, even on a repo that
+// under-specifies its GitHub-required checks (so GitHub reports the PR as UNSTABLE, i.e. "only
+// non-required checks failing" from GitHub's view). `classifyMergeability` now intersects the repo's
+// merge-protocol `requiredChecks[]`/`waitForChecks` against the head's latest-run-per-check
+// conclusions (via `latestRunPerCheck`, preserving the #348 CANCELLED-supersede semantics) as an
+// independent backstop that runs BEFORE the `mergeStateStatus` switch. These are pure unit tests.
+
+// Build a `PrState` with sensible defaults; `over` supplies the fields a case cares about. `over`
+// may pass a `rollup` shorthand (name → conclusion) that we compile into the exact per-check fields
+// `classifyMergeability` reads (present/pending/conclusions), mirroring what `fetchPrState` derives.
+function mergePrState(over: Partial<PrState> & { rollup?: { name: string; conclusion: string }[] } = {}): PrState {
+  const { rollup, ...rest } = over;
+  const base: PrState = {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "CLEAN",
+    failingChecks: 0,
+    failingCheckNames: [],
+    totalChecks: 0,
+    presentCheckNames: [],
+    pendingCheckNames: [],
+    checkConclusions: {},
+    isDraft: false,
+    headRefOid: "abc123",
+  };
+  if (rollup) {
+    const bad = new Set(["FAILURE", "TIMED_OUT", "CANCELLED", "ACTION_REQUIRED", "STARTUP_FAILURE", "ERROR"]);
+    const pendingStates = new Set(["", "PENDING", "QUEUED", "IN_PROGRESS", "EXPECTED", "WAITING"]);
+    const present: string[] = [];
+    const pending: string[] = [];
+    const failing: string[] = [];
+    const conclusions: Record<string, string> = {};
+    for (const c of rollup) {
+      const v = c.conclusion.toUpperCase();
+      present.push(c.name);
+      conclusions[c.name] = pendingStates.has(v) ? "" : v;
+      if (pendingStates.has(v)) pending.push(c.name);
+      else if (bad.has(v)) failing.push(c.name);
+    }
+    base.presentCheckNames = present;
+    base.pendingCheckNames = pending;
+    base.checkConclusions = conclusions;
+    base.failingCheckNames = failing;
+    base.failingChecks = failing.length;
+    base.totalChecks = rollup.length;
+  }
+  return { ...base, ...rest };
+}
+
+function reqChecks(...names: string[]): RequiredCheck[] {
+  return names.map((name) => ({ name, acceptedConclusions: ["success"] }));
+}
+
+function protocolWith(over: Partial<MergeProtocol>): MergeProtocol {
+  return { ...DEFAULT_MERGE_PROTOCOL, ...over };
+}
+
+interface MergeCase {
+  name: string;
+  state: Partial<PrState> & { rollup?: { name: string; conclusion: string }[] };
+  protocol?: MergeProtocol;
+  want: Mergeability;
+}
+
+const MERGE_CASES: MergeCase[] = [
+  // The exact defect: UNSTABLE + a red DECLARED-required check used to classify `ready` and merge.
+  {
+    name: "UNSTABLE + red declared-required check -> blocked (the #392 defect)",
+    state: { mergeStateStatus: "UNSTABLE", rollup: [{ name: "test (22.x, simple)", conclusion: "FAILURE" }] },
+    protocol: protocolWith({ requiredChecks: [{ name: "test (22.x, simple)", acceptedConclusions: ["success"] }] }),
+    want: "blocked",
+  },
+  {
+    name: "CLEAN + red declared-required check -> blocked (backstop runs before the switch)",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "FAILURE" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "blocked",
+  },
+  {
+    name: "declared-required check pending -> waiting",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "IN_PROGRESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "waiting",
+  },
+  {
+    name: "declared-required check absent from head -> waiting (absence is not a pass)",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "lint", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "waiting",
+  },
+  {
+    name: "declared-required check passing, CLEAN -> ready",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "ready",
+  },
+  {
+    name: "declared-required check passing, UNSTABLE -> ready (falls through to the switch)",
+    state: { mergeStateStatus: "UNSTABLE", rollup: [{ name: "build", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "ready",
+  },
+  {
+    name: "non-required check failing (not declared-required), UNSTABLE -> ready (today's behaviour)",
+    state: {
+      mergeStateStatus: "UNSTABLE",
+      rollup: [{ name: "build", conclusion: "SUCCESS" }, { name: "flaky-optional", conclusion: "FAILURE" }],
+    },
+    protocol: protocolWith({ requiredChecks: reqChecks("build") }),
+    want: "ready",
+  },
+  {
+    name: "CANCELLED superseded by a newer green run on a required check -> ready (#348 semantics)",
+    // `prState`'s rollup shorthand keeps one conclusion per name (latest wins); model the superseded
+    // + re-run by asserting the green outcome the rollup helpers collapse to.
+    state: { mergeStateStatus: "UNSTABLE", rollup: [{ name: "engine-core", conclusion: "SUCCESS" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("engine-core") }),
+    want: "ready",
+  },
+  {
+    name: "acceptedConclusions beyond [success] honoured: NEUTRAL accepted -> ready",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "NEUTRAL" }] },
+    protocol: protocolWith({ requiredChecks: [{ name: "build", acceptedConclusions: ["success", "neutral"] }] }),
+    want: "ready",
+  },
+  {
+    name: "acceptedConclusions [success] does NOT accept a NEUTRAL required conclusion -> blocked",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "NEUTRAL" }] },
+    protocol: protocolWith({ requiredChecks: [{ name: "build", acceptedConclusions: ["success"] }] }),
+    want: "blocked",
+  },
+  {
+    name: "waitForChecks:true + pending required check -> waiting even when CLEAN",
+    state: { mergeStateStatus: "CLEAN", rollup: [{ name: "build", conclusion: "QUEUED" }] },
+    protocol: protocolWith({ requiredChecks: reqChecks("build"), waitForChecks: true }),
+    want: "waiting",
+  },
+];
+
+for (const c of MERGE_CASES) {
+  test(`classifyMergeability: ${c.name}`, () => {
+    assertEquals(classifyMergeability(mergePrState(c.state), c.protocol), c.want);
+  });
+}
+
+// Empty requiredChecks (the DEFAULT protocol) — behaviour must be IDENTICAL to today across every
+// mergeStateStatus, whether a protocol is passed or omitted entirely.
+const DEFAULT_BEHAVIOUR: { status: string; failingChecks?: number; want: Mergeability }[] = [
+  { status: "CLEAN", want: "ready" },
+  { status: "HAS_HOOKS", want: "ready" },
+  { status: "UNSTABLE", want: "ready" },
+  { status: "BEHIND", want: "ready" },
+  { status: "DIRTY", want: "conflict" },
+  { status: "BLOCKED", failingChecks: 1, want: "blocked" },
+  { status: "BLOCKED", failingChecks: 0, want: "waiting" },
+  { status: "UNKNOWN", want: "waiting" },
+  { status: "", want: "waiting" },
+];
+
+for (const c of DEFAULT_BEHAVIOUR) {
+  test(`classifyMergeability: empty requiredChecks keeps today's behaviour (${c.status || "''"} -> ${c.want})`, () => {
+    const s = prState({ mergeStateStatus: c.status, failingChecks: c.failingChecks ?? 0 });
+    // Explicit default protocol and omitted-protocol must agree.
+    assertEquals(classifyMergeability(s, DEFAULT_MERGE_PROTOCOL), c.want);
+    assertEquals(classifyMergeability(s), c.want);
+  });
+}
+
+// Token mode: the transport can't enumerate checks (`failingChecks === -1`, empty per-check lists),
+// so even a repo that declares requiredChecks must fall through to today's `mergeStateStatus`
+// behaviour — the backstop must NEVER newly block or wait when checks are unenumerable.
+const TOKEN_MODE: { status: string; want: Mergeability }[] = [
+  { status: "CLEAN", want: "ready" },
+  { status: "UNSTABLE", want: "ready" },
+  { status: "BLOCKED", want: "waiting" }, // failingChecks<0 → conservative wait, exactly as before
+  { status: "DIRTY", want: "conflict" },
+  { status: "UNKNOWN", want: "waiting" },
+];
+
+for (const c of TOKEN_MODE) {
+  test(`classifyMergeability: token mode falls through, never newly blocks (${c.status} -> ${c.want})`, () => {
+    const s = prState({
+      mergeStateStatus: c.status,
+      failingChecks: -1,
+      totalChecks: -1,
+      presentCheckNames: [],
+      pendingCheckNames: [],
+      checkConclusions: {},
+    });
+    const protocol = protocolWith({ requiredChecks: reqChecks("build"), waitForChecks: true });
+    assertEquals(classifyMergeability(s, protocol), c.want);
+  });
+}
+
+// `checkConclusions` must report a terminal conclusion per check but normalise a STILL-IN-FLIGHT run
+// to "" for BOTH rollup shapes — a CheckRun whose `status` is not COMPLETED, and a legacy
+// StatusContext whose `state` is PENDING/EXPECTED — so a caller never mistakes a pending
+// status-context's upper-cased `state` (e.g. "PENDING") for a terminal conclusion.
+test("checkConclusions: in-flight runs map to '' for both CheckRun and StatusContext shapes", () => {
+  const got = checkConclusions([
+    { name: "ci-success", status: "COMPLETED", conclusion: "SUCCESS" },
+    { name: "ci-failure", status: "COMPLETED", conclusion: "FAILURE" },
+    { name: "ci-running", status: "IN_PROGRESS" }, // CheckRun in flight -> ""
+    { name: "ci-queued", status: "QUEUED" }, // CheckRun queued -> ""
+    { context: "legacy-pending", state: "PENDING" }, // StatusContext in flight -> ""
+    { context: "legacy-expected", state: "EXPECTED" }, // StatusContext in flight -> ""
+    { context: "legacy-error", state: "ERROR" }, // StatusContext terminal -> preserved
+  ]);
+  assertEquals(got, {
+    "ci-success": "SUCCESS",
+    "ci-failure": "FAILURE",
+    "ci-running": "",
+    "ci-queued": "",
+    "legacy-pending": "",
+    "legacy-expected": "",
+    "legacy-error": "ERROR",
+  });
+});

package/app/github.ts

@@ -11,6 +11,11 @@
 // The poller is app-side host glue (main.ts), so host-specific subprocess I/O is allowed here.
 // Cross-runtime: runs under Node (`node:child_process`).
 
+// Type-only import (erased at runtime, so no runtime cycle with mergeProtocol.ts, which imports
+// `fetchRepoFile` from here): `classifyMergeability` reads a repo's declared required checks to gate
+// a merge independently of GitHub branch protection.
+import type { MergeProtocol } from "./mergeProtocol.ts";
+
 /** A GitHub pull-request review, narrowed to the fields the poller needs. */
 export interface GhReview {
   id: number;
@@ -502,6 +507,17 @@ export interface PrState {
    * unrelated always-on check (e.g. Mergify's "Merge Queue") must not read as "the required run
    * already happened". */
   presentCheckNames: string[];
+  /** Names of every head check still in flight (queued/in progress, not yet concluded and not a hard
+  * failure), derived over the newest run per check (`pendingCheckNames`). Empty in token mode (the
+  * REST fallback can't enumerate checks). Lets `classifyMergeability` hold a merge when a
+  * declared-required check has not yet concluded, without re-deriving conclusions by hand. */
+  pendingCheckNames: string[];
+  /** The newest concluded conclusion per head check (name → uppercase conclusion, e.g. `SUCCESS` /
+  * `FAILURE` / `NEUTRAL` / `SKIPPED`), derived over `latestRunPerCheck` so a `CANCELLED` run
+  * superseded by a newer green run on the same head reports the green result (#348). A still-pending
+  * run maps to `""` (it has no conclusion yet — use `pendingCheckNames`). Empty in token mode. Lets
+  * `classifyMergeability` honour a required check's `acceptedConclusions` precisely. */
+  checkConclusions: Record<string, string>;
   /** Whether the PR is a draft (a fresh head run is produced by marking it ready, not reopen). */
   isDraft: boolean;
   /** Current head commit. Used to scope one-shot merge-protocol nudges to a landing attempt. */
@@ -597,6 +613,28 @@ export function failingCheckNames(rollup: RollupEntry[]): string[] {
   return names;
 }
 
+/** Names of checks that are still in flight — queued or in progress, i.e. NOT yet complete and not a
+ * hard failure. Covers the CheckRun shape (`status` QUEUED/IN_PROGRESS/PENDING/WAITING/… anything but
+ * COMPLETED) and the legacy StatusContext shape (`state` PENDING/EXPECTED). Derived over the newest
+ * run per check (`latestRunPerCheck`) like {@link failingCheckNames}, so a superseded run doesn't
+ * linger as pending. A `checks-green` gate MUST count these so it never reports green while a run has
+ * not yet concluded (a pending run has no failing conclusion, so it would otherwise slip through). */
+export function pendingCheckNames(rollup: RollupEntry[]): string[] {
+  const names: string[] = [];
+  for (const c of latestRunPerCheck(rollup)) {
+    const status = (c.status || "").toUpperCase();
+    if (status !== "") {
+      // CheckRun: anything other than COMPLETED is still running/queued.
+      if (status !== "COMPLETED") names.push(checkKey(c));
+    } else {
+      // Legacy StatusContext: PENDING/EXPECTED are not-yet-concluded.
+      const state = (c.state || "").toUpperCase();
+      if (state === "PENDING" || state === "EXPECTED") names.push(checkKey(c));
+    }
+  }
+  return names;
+}
+
 /** Names of every head check present, regardless of state. Covers both the CheckRun shape
  * (`name`/`workflowName`) and the legacy StatusContext shape (`context`). Used to test whether a
  * repo's *required* checks are present on the head — so an unrelated always-on check (e.g.
@@ -611,6 +649,29 @@ export function allCheckNames(rollup: RollupEntry[]): string[] {
   return names;
 }
 
+/** The ground-truth conclusion of each head check, keyed by check name, derived over the **newest run
+ * per check** (`latestRunPerCheck`) so a `CANCELLED` run superseded by a newer green run on the
+ * identical head SHA reports the green result, not the stale cancellation (issue #348). The value is
+ * the run's `conclusion` (CheckRun) or `state` (legacy StatusContext), upper-cased; a still-in-flight
+ * run that has not concluded maps to `""` (it has no conclusion — `pendingCheckNames` tracks those).
+ * In-flight is normalised to `""` for BOTH shapes: a CheckRun whose `status` is not `COMPLETED`, and a
+ * legacy StatusContext whose `state` is `PENDING`/`EXPECTED`, so a caller never mistakes a pending
+ * status-context's `PENDING`/`EXPECTED` `state` for a terminal conclusion.
+ * Lets `classifyMergeability` intersect a repo's declared `requiredChecks` against actual head
+ * conclusions and honour each check's `acceptedConclusions` without re-deriving per-run state. */
+export function checkConclusions(rollup: RollupEntry[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const c of latestRunPerCheck(rollup)) {
+    const status = (c.status || "").toUpperCase();
+    const state = (c.state || "").toUpperCase();
+    // A still-in-flight run has no terminal conclusion — normalise both shapes to "" (mirrors
+    // `pendingCheckNames`): CheckRun status != COMPLETED, or legacy StatusContext state PENDING/EXPECTED.
+    const inFlight = status !== "" ? status !== "COMPLETED" : state === "PENDING" || state === "EXPECTED";
+    out[checkKey(c)] = inFlight ? "" : (c.conclusion || c.state || "").toUpperCase();
+  }
+  return out;
+}
+
 /** True when `err` is GitHub reporting that a ref which parsed as `owner/repo#N` is not a pull
  * request — either it's an issue (issues and PRs share GitHub's number space, so an issue number
  * is indistinguishable from a PR number by shape alone) or the number does not exist. Both
@@ -660,6 +721,8 @@ export async function fetchPrState(
       failingCheckNames: names,
       totalChecks: rollup.length,
       presentCheckNames: allCheckNames(rollup),
+      pendingCheckNames: pendingCheckNames(rollup),
+      checkConclusions: checkConclusions(rollup),
       isDraft: !!j.isDraft,
       headRefOid: j.headRefOid ?? null,
     };
@@ -691,6 +754,8 @@ export async function fetchPrState(
     failingCheckNames: [], // …and the CI-fix agent gets no per-check list in token mode
     totalChecks: -1, // …and the fresh-head-run remedy stays conservative (never reopens blind)
     presentCheckNames: [], // …can't enumerate checks in token mode → no required-check presence signal
+    pendingCheckNames: [], // …no per-check pending signal either → classifier degrades to today's switch
+    checkConclusions: {}, // …no per-check conclusions → protocol-aware gate falls through in token mode
     isDraft: !!j.draft,
     headRefOid: j.head?.sha ?? null,
   };
@@ -893,11 +958,68 @@ export async function baseBranchLanded(
  * verdict; `waiting` means re-poll later. */
 export type Mergeability = "ready" | "waiting" | "conflict" | "blocked";
 
-export function classifyMergeability(s: PrState): Mergeability {
+/** Intersect a repo's declared `requiredChecks` against the head's actual per-check conclusions —
+ * an INDEPENDENT backstop that runs BEFORE the `mergeStateStatus` switch, so nwf never merges a red
+ * required check even on a repo that has NOT wired that check as a GitHub-required status check
+ * (issue #392). Returns:
+ *   • `"blocked"` — a declared-required check is present, concluded, and its conclusion is NOT in that
+ *      check's `acceptedConclusions` (a hard failure like `FAILURE`, or any other unaccepted terminal
+ *      conclusion) → route to fix-ci, do not merge.
+ *   • `"waiting"` — a declared-required check is still pending, or absent from the head entirely
+ *      (not-yet-run counts as pending, NOT as pass): a declared-required check that has not
+ *      concluded is never mergeable.
+ *   • `"pass"` — every declared-required check is present and its conclusion accepted → fall through to
+ *      today's `mergeStateStatus` logic (GitHub branch protection stays the primary gate).
+ * Degrades safely: with no declared `requiredChecks`, or in token mode where checks can't be
+ * enumerated (`failingChecks < 0`, so the per-check lists are empty), it returns `"pass"` and never
+ * newly blocks or waits — repos keep exactly today's behaviour. */
+function requiredChecksVerdict(s: PrState, protocol?: MergeProtocol): "blocked" | "waiting" | "pass" {
+  const required = protocol?.requiredChecks ?? [];
+  if (required.length === 0) return "pass";
+  // Token mode: the transport can't enumerate checks (`failingChecks === -1`), so the per-check lists
+  // are empty and absence is indistinguishable from not-yet-run. Do NOT newly block/wait — fall
+  // through to today's `mergeStateStatus` behaviour. (A real gh-mode head with no checks yet reports
+  // `failingChecks === 0`, so absence there is correctly treated as not-yet-run below.)
+  if (s.failingChecks < 0) return "pass";
+  const present = new Set(s.presentCheckNames);
+  const pending = new Set(s.pendingCheckNames);
+  let anyBlocked = false;
+  let anyPending = false;
+  for (const rc of required) {
+    // Absent from the head, or still in flight → not-yet-run → wait (never treat absence as pass).
+    if (!present.has(rc.name) || pending.has(rc.name)) {
+      anyPending = true;
+      continue;
+    }
+    const conclusion = (s.checkConclusions[rc.name] ?? "").toUpperCase();
+    if (conclusion === "") {
+      // Present but no terminal conclusion yet (and not flagged pending) — treat conservatively as
+      // not-yet-concluded rather than as a pass.
+      anyPending = true;
+      continue;
+    }
+    const accepted = rc.acceptedConclusions.map((a) => a.toUpperCase());
+    if (accepted.includes(conclusion)) continue; // satisfied
+    anyBlocked = true; // present, concluded, NOT accepted → a red required check
+  }
+  // A failing required check outranks a pending one: it needs fix-ci now, not more waiting.
+  if (anyBlocked) return "blocked";
+  if (anyPending) return "waiting";
+  return "pass";
+}
+
+export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Mergeability {
+  // Protocol-aware backstop FIRST (issue #392): honour the repo's declared `requiredChecks`
+  // against the actual head rollup, so an `UNSTABLE` PR with a red DECLARED-required
+  // check is no longer blindly `ready`. This never weakens GitHub branch protection (the switch
+  // below still gates) — it only tightens merges on repos that under-specify their required checks.
+  const gate = requiredChecksVerdict(s, protocol);
+  if (gate === "blocked") return "blocked";
+  if (gate === "waiting") return "waiting";
   switch (s.mergeStateStatus) {
     case "CLEAN":
     case "HAS_HOOKS":
-    case "UNSTABLE": // only non-required checks failing — still mergeable
+    case "UNSTABLE": // only non-required checks failing — still mergeable (no DECLARED-required red)
     case "BEHIND": // out of date; a queue rebases, a direct merge is still allowed
       return "ready";
     case "DIRTY":

package/app/readiness.test.ts

@@ -21,17 +21,22 @@ import {
   matchGithubCheck,
   matchHttp,
   matchNpm,
+  matchPr,
   msToIsoDuration,
   newestPublishedVersion,
   nextDelay,
   normalizePoll,
   parseProbe,
+  parsePrTarget,
+  parsePrView,
   parseReleases,
   parseReleasesTarget,
   parseRepoRef,
   probeBudgetMs,
   probeOnce,
   type ProbeExec,
+  type PrObservation,
+  prViewCommand,
   readinessTimeout,
   readinessTimeoutMs,
   redactString,
@@ -375,6 +380,163 @@ test("probeOnce github-check: a failed gh api call is not-ready (never throws)",
   assert(!res.ready);
 });
 
+// ── parseProbe: pr kind (ADR 0005 §2 — owner/repo#N target + validated prState) ──────────────────
+test("parseProbe: accepts an owner/repo#N pr probe and defaults onTimeout to escalate (timeout → escalate)", () => {
+  const p = parseProbe({ kind: "pr", target: "nanobpm/nano-workforce#377" });
+  assertEquals(p.kind, "pr");
+  assertEquals(p.onTimeout, "escalate");
+});
+
+test("parseProbe: a pr probe whose target carries no numeric PR id throws (never resolvable)", () => {
+  assertThrows(() => parseProbe({ kind: "pr", target: "nanobpm/nano-workforce" }), Error, "owner/repo#<number>");
+});
+
+test("parseProbe: a pr probe with an unknown match.prState throws (mistyped state fails loudly)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "pr", target: "o/r#1", match: { prState: "landed" } }),
+    Error,
+    "invalid match.prState",
+  );
+});
+
+test("parseProbe: a valid pr probe round-trips its prState", () => {
+  const p = parseProbe({ kind: "pr", target: "o/r#12", match: { prState: "mergeable" } });
+  assertEquals(p.match?.prState, "mergeable");
+});
+
+// ── matchPr (pure — operates on an already-fetched PR observation) ────────────────────────────────
+function prObs(over: Partial<PrObservation> = {}): PrObservation {
+  return {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "UNKNOWN",
+    failingChecks: 0,
+    failingCheckNames: [],
+    totalChecks: 0,
+    presentCheckNames: [],
+    pendingCheckNames: [],
+    checkConclusions: {},
+    isDraft: false,
+    headRefOid: "abc123",
+    mergedSha: null,
+    pendingChecks: 0,
+    ...over,
+  };
+}
+
+test("matchPr: prState 'ready' is the draft→ready transition (a non-draft PR is ready)", () => {
+  assert(!matchPr({ prState: "ready" }, prObs({ isDraft: true })).ready);
+  assert(matchPr({ prState: "ready" }, prObs({ isDraft: false })).ready);
+});
+
+test("matchPr: prState 'merged' waits for the merge and binds mergedSha (mirrors resolvedArtifact)", () => {
+  assert(!matchPr({ prState: "merged" }, prObs({ merged: false })).ready);
+  const res = matchPr({ prState: "merged" }, prObs({ merged: true, state: "merged", mergedSha: "deadbeef" }));
+  assert(res.ready);
+  assertEquals(res.bind?.mergedSha, "deadbeef");
+});
+
+test("matchPr: 'merged' is the default when no prState is declared", () => {
+  assert(!matchPr(undefined, prObs({ merged: false })).ready);
+  assert(matchPr(undefined, prObs({ merged: true, state: "merged" })).ready);
+});
+
+test("matchPr: prState 'mergeable' reuses classifyMergeability (CLEAN is ready, BLOCKED is not)", () => {
+  assert(matchPr({ prState: "mergeable" }, prObs({ mergeStateStatus: "CLEAN" })).ready);
+  assert(!matchPr({ prState: "mergeable" }, prObs({ mergeStateStatus: "BLOCKED", failingChecks: 1 })).ready);
+});
+
+test("matchPr: prState 'checks-green' needs a present, non-failing, non-pending head run", () => {
+  assert(matchPr({ prState: "checks-green" }, prObs({ totalChecks: 2, failingChecks: 0 })).ready);
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 2, failingChecks: 1 })).ready);
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 0, failingChecks: 0 })).ready);
+  // A run still queued/in-progress (no failing conclusion yet) must NOT read as green.
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 2, failingChecks: 0, pendingChecks: 1 })).ready);
+  // token mode (checks unenumerable, totalChecks < 0) stays conservative — never falsely green.
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: -1, failingChecks: -1 })).ready);
+});
+
+test("matchPr: a not-yet-satisfied state is not-ready — the bounded gate keeps waiting → timeout escalates", () => {
+  // Every un-reached state resolves to ready:false, which is exactly what the engine timer arm bounds
+  // (onTimeout defaults to 'escalate'): a PR that never lands is never falsely resolved.
+  assert(!matchPr({ prState: "merged" }, prObs({ merged: false })).ready);
+  assert(!matchPr({ prState: "ready" }, prObs({ isDraft: true })).ready);
+  assert(!matchPr({ prState: "checks-green" }, prObs({ totalChecks: 1, failingChecks: 1 })).ready);
+});
+
+// ── parsePrView + probeOnce pr dispatch (injected exec — no I/O) ─────────────────────────────────
+test("parsePrView: reduces a gh pr view payload and collapses the check rollup", () => {
+  const obs = parsePrView({
+    state: "OPEN",
+    mergeStateStatus: "clean",
+    isDraft: false,
+    headRefOid: "sha1",
+    statusCheckRollup: [
+      { name: "build", status: "COMPLETED", conclusion: "SUCCESS" },
+      { name: "lint", status: "COMPLETED", conclusion: "FAILURE" },
+    ],
+  });
+  assertEquals(obs.merged, false);
+  assertEquals(obs.mergeStateStatus, "CLEAN");
+  assertEquals(obs.totalChecks, 2);
+  assertEquals(obs.failingCheckNames, ["lint"]);
+});
+
+test("parsePrView: an in-flight run is counted as pending (so checks-green stays not-green)", () => {
+  const obs = parsePrView({
+    state: "OPEN",
+    statusCheckRollup: [
+      { name: "build", status: "COMPLETED", conclusion: "SUCCESS" },
+      { name: "e2e", status: "IN_PROGRESS" },
+    ],
+  });
+  assertEquals(obs.failingChecks, 0);
+  assertEquals(obs.pendingChecks, 1);
+  assert(!matchPr({ prState: "checks-green" }, obs).ready);
+});
+
+test("parsePrView: a merged PR carries its merge commit oid", () => {
+  const obs = parsePrView({ state: "MERGED", mergedAt: "2026-08-20T00:00:00Z", mergeCommit: { oid: "cafe" } });
+  assertEquals(obs.merged, true);
+  assertEquals(obs.state, "merged");
+  assertEquals(obs.mergedSha, "cafe");
+});
+
+test("parsePrView: a garbled payload degrades to an all-open, no-checks observation (never throws)", () => {
+  const obs = parsePrView(null);
+  assertEquals(obs.merged, false);
+  assertEquals(obs.totalChecks, 0);
+});
+
+test("probeOnce pr: builds a quoted `gh pr view` command and matches merged, binding mergedSha", async () => {
+  const cap: { cmd?: string } = {};
+  const exec = stubExec({
+    command: { code: 0, stdout: JSON.stringify({ state: "MERGED", mergeCommit: { oid: "abc" } }), stderr: "" },
+    capture: cap,
+  });
+  const res = await probeOnce(parseProbe({ kind: "pr", target: "nanobpm/nano-workforce#377" }), exec, {});
+  assert(res.ready);
+  assertEquals(res.bind?.mergedSha, "abc");
+  assertStringIncludes(cap.cmd ?? "", "gh pr view '377' --repo 'nanobpm/nano-workforce'");
+});
+
+test("probeOnce pr: a failed gh pr view call is not-ready (never throws)", async () => {
+  const exec = stubExec({ command: { code: 1, stdout: "", stderr: "no pr" } });
+  const res = await probeOnce(parseProbe({ kind: "pr", target: "o/r#1" }), exec, {});
+  assert(!res.ready);
+});
+
+test("parsePrTarget: parses owner/repo#N, rejects @N and a bare repo", () => {
+  assertEquals(parsePrTarget("o/r#12"), { repo: "o/r", number: "12" });
+  // `@N` is deliberately NOT a PR handle — it's the repo-ref syntax, so it must not parse as a PR.
+  assertEquals(parsePrTarget("o/r@34"), null);
+  assertEquals(parsePrTarget("o/r"), null);
+});
+
+test("prViewCommand: single-quote-escapes its args", () => {
+  assertStringIncludes(prViewCommand("o/r", "9"), "gh pr view '9' --repo 'o/r'");
+});
+
 // ── backoff + poll normalisation ──────────────────────────────────────────────────────────────
 test("normalizePoll: fills defaults and clamps everyMs to the ceiling", () => {
   const d = normalizePoll(undefined);