@nanobpm/nano-workforce 0.210.0 → 0.210.2

package/app/migration139.test.ts

@@ -0,0 +1,115 @@
+// Migration guard for 139_pull_requests_backfill_merged_not_abandoned.sql (issue #959): the backfill
+// that re-derives the 23 merged-but-terminated PRs so they show as `merged`, not `abandoned`.
+//
+// Applies the migration to a real in-memory SQLite DB over a pre-existing `pull_requests` + `merges`
+// shape and asserts the contract:
+//   * a row with a `merged` audit outcome but a non-`merged` base status (the loop terminated before
+//     `merged_at` was stamped) is settled to `status='merged'` + `merged_at` — so the merge-aware
+//     derivation reports `merged` however the instance ended;
+//   * a row already settled `merged` is left untouched (idempotent);
+//   * a row with NO `merged` audit outcome (a genuinely abandoned/closed-unmerged run) is NOT
+//     flipped — it stays at its frozen transient so the derivation still reports `abandoned`;
+//   * re-running the migration is a no-op (forward-only, idempotent).
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+const MIGRATION_139 = fileURLToPath(
+  new URL("../db/migrations/139_pull_requests_backfill_merged_not_abandoned.sql", import.meta.url),
+);
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE pull_requests (
+       pr_key TEXT PRIMARY KEY,
+       repo TEXT NOT NULL,
+       number INTEGER NOT NULL,
+       status TEXT NOT NULL,
+       process_key TEXT,
+       merged_at TEXT,
+       updated_at TEXT
+     );
+     CREATE TABLE merges (
+       id INTEGER PRIMARY KEY AUTOINCREMENT,
+       pr_key TEXT NOT NULL,
+       outcome TEXT NOT NULL,
+       method TEXT,
+       detail TEXT,
+       at TEXT NOT NULL
+     );`,
+  );
+  return db;
+}
+
+function addPr(db: DatabaseSync, prKey: string, status: string, mergedAt: string | null = null): void {
+  db.prepare(
+    "INSERT INTO pull_requests (pr_key, repo, number, status, process_key, merged_at, updated_at) VALUES (?, 'o/r', 1, ?, 'PI-1', ?, 't0')",
+  ).run(prKey, status, mergedAt);
+}
+
+function addMerge(db: DatabaseSync, prKey: string, outcome: string, at: string): void {
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES (?, ?, 'squash', 'd', ?)").run(prKey, outcome, at);
+}
+
+function row(db: DatabaseSync, prKey: string): { status: string; merged_at: string | null } {
+  return db.prepare("SELECT status, merged_at FROM pull_requests WHERE pr_key = ?").get(prKey) as {
+    status: string;
+    merged_at: string | null;
+  };
+}
+
+const SQL = () => readFileSync(MIGRATION_139, "utf8");
+
+test("139 backfills a merged-but-terminated PR (frozen transient + merged audit) to status='merged' + merged_at", () => {
+  const db = migratedDb();
+  // The #959 case: PR landed (merged audit row) but the loop was terminated before merged_at was set,
+  // leaving the base status frozen at its in-flight transient.
+  addPr(db, "o/r#landed", "converging", null);
+  addMerge(db, "o/r#landed", "merged", "2026-11-01T02:03:04Z");
+  db.exec(SQL());
+  const r = row(db, "o/r#landed");
+  assertEquals(r.status, "merged");
+  assertEquals(r.merged_at, "2026-11-01T02:03:04Z", "merged_at is stamped from the earliest merged audit row");
+  db.close();
+});
+
+test("139 leaves an already-merged row untouched (idempotent, never overwrites merged_at)", () => {
+  const db = migratedDb();
+  addPr(db, "o/r#already", "merged", "2026-10-30T00:00:00Z");
+  addMerge(db, "o/r#already", "merged", "2026-10-30T00:00:00Z");
+  db.exec(SQL());
+  const r = row(db, "o/r#already");
+  assertEquals(r.status, "merged");
+  assertEquals(r.merged_at, "2026-10-30T00:00:00Z");
+  db.close();
+});
+
+test("139 does NOT flip a closed-unmerged / genuinely-abandoned PR (no merged audit outcome)", () => {
+  const db = migratedDb();
+  // A PR closed without merging: terminated → abandoned, NO merged audit row. Must stay un-merged.
+  addPr(db, "o/r#closed", "converging", null);
+  addMerge(db, "o/r#closed", "abandoned", "2026-11-01T00:00:00Z");
+  // A still-in-flight PR with no merge record at all.
+  addPr(db, "o/r#inflight", "waiting_merge", null);
+  db.exec(SQL());
+  assertEquals(row(db, "o/r#closed").status, "converging", "no merged outcome → not flipped to merged");
+  assertEquals(row(db, "o/r#closed").merged_at, null);
+  assertEquals(row(db, "o/r#inflight").status, "waiting_merge");
+  assertEquals(row(db, "o/r#inflight").merged_at, null);
+  db.close();
+});
+
+test("139 is idempotent — a second run is a no-op", () => {
+  const db = migratedDb();
+  addPr(db, "o/r#landed", "waiting_merge", null);
+  addMerge(db, "o/r#landed", "merged", "2026-11-01T02:03:04Z");
+  db.exec(SQL());
+  const first = row(db, "o/r#landed");
+  db.exec(SQL());
+  const second = row(db, "o/r#landed");
+  assertEquals(second, first);
+  db.close();
+});

package/app/prTrackingReadModel.test.ts

@@ -0,0 +1,175 @@
+// Issue #959 — the canonical "merged beats terminated" effective-status derivation for a PR.
+//
+// THE DEFECT: `pull_requests__tracking.derived_status` mapped ANY terminated run to `abandoned`
+// without consulting the PR's merge state, so the 23 November PRs that MERGED but whose loops were
+// terminated afterwards (operator cancel, out-of-band merge reconcile, restart cleanup) all read
+// "abandoned". These tests pin the fixed semantics against the REAL derivation SQL
+// (`pullRequestTrackingReadModel`, app/prTrackingReadModel.ts) compiled to an in-memory SQLite VIEW
+// over the SAME canonical `urban_instance_state` projection the framework feeds:
+//
+//   terminated + merged PR          → `merged`     (landed wins over terminated)
+//   terminated + closed-unmerged PR → `abandoned`  (no merged_at → the onTerminated edge)
+//   terminated + open PR            → `abandoned`
+//   live (non-terminated) run       → base `status` passes through
+//
+// and the downstream consequence: conformance/retro count a merged-then-terminated PR as LANDED.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { registerCanonicalProjections, readModelRegistry } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import {
+  pullRequestTrackingReadModel,
+  registerPullRequestTrackingReadModel,
+} from "./prTrackingReadModel.ts";
+
+// The projection NAME→physical-table mapping the VIEW's `EXISTS` resolves through.
+registerCanonicalProjections();
+
+/** A minimal in-memory DB: the real `pull_requests` base columns the derivation reads (`status`,
+ *  `process_key`, `merged_at`), the canonical `_urban_instance_state` projection, and the
+ *  app-owned tracking VIEW compiled from the ONE declaration. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, status TEXT, process_key TEXT, merged_at TEXT);
+     CREATE TABLE merges (id INTEGER PRIMARY KEY, pr_key TEXT, outcome TEXT, method TEXT, detail TEXT, at TEXT);
+     CREATE TABLE _urban_instance_state (process_instance_key TEXT PRIMARY KEY, state TEXT, waiting_on_human INTEGER NOT NULL DEFAULT 0, updated_at TEXT);`,
+  );
+  db.exec(pullRequestTrackingReadModel.viewDdl());
+  return db;
+}
+
+function addPr(
+  db: DatabaseSync,
+  prKey: string,
+  opts: { status: string; processKey: string | null; mergedAt: string | null },
+): void {
+  db.prepare("INSERT INTO pull_requests (pr_key, status, process_key, merged_at) VALUES (?, ?, ?, ?)").run(
+    prKey,
+    opts.status,
+    opts.processKey,
+    opts.mergedAt,
+  );
+}
+
+function terminate(db: DatabaseSync, processKey: string): void {
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES (?, 'TERMINATED', 0, 't')",
+  ).run(processKey);
+}
+
+function derivedStatus(db: DatabaseSync, prKey: string): string {
+  const r = db.prepare("SELECT derived_status FROM pull_requests__tracking WHERE pr_key = ?").get(prKey) as {
+    derived_status: string;
+  };
+  return r.derived_status;
+}
+
+test("terminated instance + merged PR (merged_at set) derives `merged`, not `abandoned`", () => {
+  const db = viewDb();
+  // The #959 case: the loop was terminated AFTER the PR landed; base status frozen at its transient.
+  addPr(db, "o/r#merged", { status: "converging", processKey: "514213", mergedAt: "2026-11-01T00:00:00Z" });
+  terminate(db, "514213");
+  assertEquals(derivedStatus(db, "o/r#merged"), "merged");
+  db.close();
+});
+
+test("terminated instance + closed-unmerged PR (no merged_at) derives `abandoned`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#closed", { status: "converging", processKey: "222", mergedAt: null });
+  terminate(db, "222");
+  assertEquals(derivedStatus(db, "o/r#closed"), "abandoned");
+  db.close();
+});
+
+test("terminated instance + open PR (no merged_at) derives `abandoned`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#open", { status: "waiting_review", processKey: "333", mergedAt: null });
+  terminate(db, "333");
+  assertEquals(derivedStatus(db, "o/r#open"), "abandoned");
+  db.close();
+});
+
+test("a live (non-terminated) in-flight run passes its base status through unchanged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#live", { status: "converging", processKey: "444", mergedAt: null });
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES ('444', 'ACTIVE', 0, 't')",
+  ).run();
+  assertEquals(derivedStatus(db, "o/r#live"), "converging");
+  db.close();
+});
+
+test("a merged PR whose instance COMPLETED normally (no terminated edge) reads base `merged`", () => {
+  const db = viewDb();
+  addPr(db, "o/r#done", { status: "merged", processKey: "555", mergedAt: "2026-11-01T00:00:00Z" });
+  db.prepare(
+    "INSERT INTO _urban_instance_state (process_instance_key, state, waiting_on_human, updated_at) VALUES ('555', 'COMPLETED', 0, 't')",
+  ).run();
+  assertEquals(derivedStatus(db, "o/r#done"), "merged");
+  db.close();
+});
+
+test("a landed PR with no instance-state row (null process_key) still derives merged off merged_at", () => {
+  const db = viewDb();
+  // merged_at set but the instance row is gone/null: the merged WHEN keys on merged_at, not the join.
+  addPr(db, "o/r#nullkey", { status: "converging", processKey: null, mergedAt: "2026-11-01T00:00:00Z" });
+  assertEquals(derivedStatus(db, "o/r#nullkey"), "merged");
+  db.close();
+});
+
+test("a landed PR whose instance-state row was pruned still derives merged off merged_at", () => {
+  const db = viewDb();
+  addPr(db, "o/r#pruned", { status: "waiting_merge", processKey: "777", mergedAt: "2026-11-01T00:00:00Z" });
+  assertEquals(derivedStatus(db, "o/r#pruned"), "merged");
+  db.close();
+});
+
+test("a run terminated between pr.merge's audit and pr.mark-merged (merged_at NULL) derives merged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#gap", { status: "merging", processKey: "888", mergedAt: null });
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#gap', 'merged', 'squash', '', 't')").run();
+  terminate(db, "888");
+  assertEquals(derivedStatus(db, "o/r#gap"), "merged");
+  db.close();
+});
+
+test("a non-merged audit outcome does not fold a terminated run to merged", () => {
+  const db = viewDb();
+  addPr(db, "o/r#rc", { status: "merging", processKey: "889", mergedAt: null });
+  db.prepare("INSERT INTO merges (pr_key, outcome, method, detail, at) VALUES ('o/r#rc', 'reconverge', 'x', '', 't')").run();
+  terminate(db, "889");
+  assertEquals(derivedStatus(db, "o/r#rc"), "abandoned");
+  db.close();
+});
+
+test("owner_terminated exposes termination separately: set for a terminated merged PR, NULL for a live one", () => {
+  const db = viewDb();
+  addPr(db, "o/r#mt", { status: "merged", processKey: "901", mergedAt: "t" });
+  terminate(db, "901");
+  addPr(db, "o/r#ml", { status: "merged", processKey: "902", mergedAt: "t" });
+  const get = (k: string) =>
+    (db.prepare("SELECT derived_status, owner_terminated FROM pull_requests__tracking WHERE pr_key = ?").get(k) as {
+      derived_status: string;
+      owner_terminated: number | null;
+    });
+  assertEquals(get("o/r#mt").derived_status, "merged");
+  assertEquals(get("o/r#mt").owner_terminated, 1);
+  assertEquals(get("o/r#ml").owner_terminated, null);
+  db.close();
+});
+
+// The whole fix hinges on the app-owned model claiming the EXACT view name urban's provisioner would
+// otherwise manage, so the framework defers to it. Pin that contract: the model is named
+// `pull_requests__tracking`, registers into the process-wide registry (idempotently), and the
+// registration is what `main.ts` invokes before `runFromEnv`.
+test("the app-owned model is named pull_requests__tracking and registers idempotently", () => {
+  assertEquals(pullRequestTrackingReadModel.decl.name, "pull_requests__tracking");
+  assertEquals(pullRequestTrackingReadModel.decl.baseTable, "pull_requests");
+  registerPullRequestTrackingReadModel();
+  const registered = readModelRegistry.get("pull_requests__tracking");
+  assert(registered, "the model must be registered so the framework defers to it");
+  assertEquals(registered.decl.name, "pull_requests__tracking");
+  // Idempotent: re-registering the identical definition is a no-op (never throws).
+  registerPullRequestTrackingReadModel();
+});

package/app/prTrackingReadModel.ts

@@ -0,0 +1,152 @@
+// nano-workforce — the ONE canonical "what is this PR's effective status" derivation (issue #959).
+//
+// THE DEFECT. `derived_status` came from the `instanceTracking` `onTerminated.set` edge, which maps
+// **any** terminated run to `abandoned` without consulting the PR's merge state. But a run is
+// terminated AFTER its PR merged in several legitimate ways — an operator cancels a loop that is
+// redundant after a merge, an out-of-band merge (Mergify / a manual click) is reconciled, a restart
+// or upgrade cleans up. Every one of those was recorded "abandoned", which made the status
+// untrustworthy (an operator can't tell dropped work from shipped work) and skewed retro/conformance
+// stats (`LANDED_PR_STATUSES` excludes `abandoned`, so merged PRs didn't count as landed).
+//
+// THE FIX (the defect class, not the instance). `abandoned` must mean "terminated AND the PR did not
+// merge". When the PR landed — recorded on the base row's `merged_at` (set by `pr.mark-merged` or the
+// out-of-band `retireTerminalReviewWait`) — the effective status is `merged` REGARDLESS of how the
+// instance ended. This module owns that derivation ONCE, as a `defineReadModel` over the SAME
+// canonical `urban_instance_state` projection the framework's tracking view uses, plus the base row's
+// own `merged_at` column.
+//
+// HOW IT SHIPS. The model is named `pull_requests__tracking` — the EXACT managed-VIEW name urban's
+// `instanceTracking` provisioner would otherwise create for the `pull_requests` binding
+// (`instanceTrackingReadModelTarget`). Registering it into the process-wide `readModelRegistry` makes
+// the framework's mount DEFER to this app-owned derivation: `provisionInstanceTrackingViews` refuses
+// to clobber a registered read model of the same name (it logs and skips), and `mountWorkers`
+// (`readModelRegistry.ensureViews`) — which runs BEFORE `mountInstanceTracking` — applies this VIEW.
+// So every reader that already routes through `pull_requests__tracking.derived_status` (the abandon
+// check, conformance, retro, the PR list, the read model) picks up the merge-aware edge with NO
+// per-reader change — the "one canonical derivation, no per-reader logic" the issue asks for.
+//
+// PRECEDENCE (merged > terminated > waiting-human > base). The merged `WHEN` is emitted FIRST so a
+// landed PR reads `merged` even when its instance was terminated; a terminated-unmerged run still
+// reads `abandoned`; a waiting-on-human edge (none for pull_requests today, but kept for parity with
+// the framework's derivation) still applies to a live, unmerged run; otherwise the worker-owned base
+// `status` passes through.
+
+import {
+  and,
+  caseWhen,
+  col,
+  defineReadModel,
+  type Expr,
+  eq,
+  exists,
+  isNotNull,
+  lit,
+  not,
+  or,
+  pcol,
+  type ReadModel,
+  readModelRegistry,
+  when,
+} from "@nanobpm/urban";
+import { trackingBindingFor, trackingTargetFor } from "./instanceTracking.ts";
+
+const TABLE = "pull_requests";
+
+/** The engine-truth terminal lifecycle state the terminal edge keys on (mirrors urban's
+ *  `TERMINATED_STATE`). Duplicated as a literal so this module derives from the public DSL primitives
+ *  (`exists`/`pcol`) without reaching into urban's internals. */
+const TERMINATED = "TERMINATED";
+
+/** `EXISTS(urban_instance_state WHERE process_instance_key = base.<keyField> AND state='TERMINATED')`
+ *  — the SAME terminal edge the framework's tracking derivation uses, keyed off the binding's
+ *  `keyField` (`process_key`) so it can never drift from the reconciler's notion of "which column
+ *  holds the engine instance key". */
+function terminatedEdge(keyField: string): Expr {
+  return exists(
+    "urban_instance_state",
+    and(eq(pcol("process_instance_key"), col(keyField)), eq(pcol("state"), lit(TERMINATED))),
+  );
+}
+
+/** `EXISTS(urban_open_user_tasks WHERE process_instance_key = base.<keyField>)` — the wait-on-human
+ *  edge, kept for parity with the framework's derivation (a binding that adds `onWaitingHuman` later
+ *  still derives it correctly). */
+function waitingHumanEdge(keyField: string): Expr {
+  return exists("urban_open_user_tasks", eq(pcol("process_instance_key"), col(keyField)));
+}
+
+/** The landed signal: the base row's `merged_at` stamp OR a durable `merges.outcome='merged'` audit
+ *  row. `pr.merge` writes the audit BEFORE the separate `pr.mark-merged` task stamps `merged_at`, so a
+ *  run terminated between the two still landed — the audit alone must be sufficient. Neither signal
+ *  depends on a retained instance-state row (a pruned/null `process_key` still reads `merged`). */
+function landedEdge(): Expr {
+  return or(
+    isNotNull(col("merged_at")),
+    exists("merges", and(eq(pcol("pr_key"), col("pr_key")), eq(pcol("outcome"), lit("merged")))),
+  );
+}
+
+/** The merge-aware effective-status derivation for the `pull_requests` binding:
+ *
+ *   CASE
+ *     WHEN <merged_at set OR merged audit row>         THEN 'merged'      -- landed wins, however the run ended
+ *     WHEN <terminated>                                THEN <onTerminated> -- terminated-unmerged = abandoned
+ *     WHEN <waiting-on-human> AND NOT <terminated>     THEN <onWaitingHuman>
+ *     ELSE base.<statusField>                          -- the worker-owned transient
+ *   END
+ *
+ * The merged `WHEN` precedes the terminated one so a landed PR is `merged` no matter how its run
+ * ended; the terminated-unmerged branch preserves the manifest's `onTerminated.set.status` value
+ * (`abandoned`) rather than hard-coding it, so the manifest stays the source of truth for the
+ * not-landed terminal. */
+export function derivePrEffectiveStatusExpr(): Expr {
+  const binding = trackingBindingFor(TABLE);
+  const statusField = binding.statusField ?? "status";
+  const keyField = binding.keyField;
+  const terminated = terminatedEdge(keyField);
+
+  const whens = [
+    // Landed beats terminated: a merged PR is `merged` even when its loop was terminated afterwards.
+    when(landedEdge(), lit("merged")),
+  ];
+  const terminalStatus = binding.onTerminated?.set?.[statusField];
+  if (typeof terminalStatus === "string") {
+    whens.push(when(terminated, lit(terminalStatus)));
+  }
+  const waitingStatus = binding.onWaitingHuman?.set?.[statusField];
+  if (typeof waitingStatus === "string") {
+    whens.push(when(and(waitingHumanEdge(keyField), not(terminated)), lit(waitingStatus)));
+  }
+  return caseWhen(whens, col(statusField));
+}
+
+/** The derived column exposing "this PR's owning run was terminated" SEPARATELY from the effective
+ *  status. `derived_status` deliberately reports a landed PR as `merged` even when its run was
+ *  terminated, so it can no longer carry the cancellation signal on its own — the abort protocol
+ *  (`abandonStatusForToken`) reads THIS column too, so terminating a redundant post-merge round still
+ *  tells its agent to stop. `1` when terminated, otherwise `NULL`. */
+export const OWNER_TERMINATED_COLUMN = "owner_terminated";
+
+/** `CASE WHEN <terminated> THEN 1 END` over the same terminal edge `derived_status` uses. */
+export function deriveOwnerTerminatedExpr(): Expr {
+  return caseWhen([when(terminatedEdge(trackingBindingFor(TABLE).keyField), lit(1))], lit(null));
+}
+
+/** The app-owned `pull_requests__tracking` read model. `selectBaseColumns: true` (the default) so the
+ *  VIEW re-exports `pull_requests.*` plus the derived `derived_status` — byte-compatible with the
+ *  framework's own tracking VIEW shape, so every existing reader keeps working unchanged. */
+export const pullRequestTrackingReadModel: ReadModel = defineReadModel({
+  name: trackingTargetFor(TABLE).view,
+  baseTable: TABLE,
+  derive: {
+    [trackingTargetFor(TABLE).statusColumn]: derivePrEffectiveStatusExpr(),
+    [OWNER_TERMINATED_COLUMN]: deriveOwnerTerminatedExpr(),
+  },
+});
+
+/** Register the merge-aware tracking VIEW into the process-wide `readModelRegistry` so the framework
+ *  provisions THIS derivation (and defers its own). Call ONCE at boot, BEFORE `runFromEnv` mounts
+ *  workers/instance-tracking. Idempotent: re-registering the identical definition is a no-op. */
+export function registerPullRequestTrackingReadModel(): void {
+  readModelRegistry.register(pullRequestTrackingReadModel);
+}

package/app/readiness.test.ts

@@ -554,6 +554,95 @@ test("#856 parsePrTarget agrees with the canonical parsePr on every PR shape (no
   }
 });
 
+// ── PR #957 review round 3: the readiness `pr` path normalises events too ────────────────────────
+//
+// The `gh pr view` rollup omits `event`, so before this fix the readiness path grouped by name alone
+// and a green `push` run hid a red required `pull_request` run of the same name — `checks-green`
+// reported ready while the PR run was red. `probeOnce` now enriches the rollup through the injected
+// executor (shared transport logic with the merge loop) before parsing.
+
+test("#957 probeOnce pr checks-green: a green push run never hides a red pull_request run of the same name", async () => {
+  const head = "5fbd262a28987d647621da324bf1a7855a8da500";
+  // The `gh pr view` payload: two same-named runs, NO event on either (the CLI exporter omits it).
+  const prView = {
+    state: "OPEN",
+    mergedAt: null,
+    mergeStateStatus: "CLEAN",
+    isDraft: false,
+    headRefOid: head,
+    mergeCommit: null,
+    statusCheckRollup: [
+      { name: "build", conclusion: "FAILURE", status: "COMPLETED", startedAt: "2026-11-12T00:30:00Z", completedAt: "2026-11-12T00:41:34Z" },
+      { name: "build", conclusion: "SUCCESS", status: "COMPLETED", startedAt: "2026-11-12T00:41:30Z", completedAt: "2026-11-12T00:41:38Z" },
+    ],
+  };
+  // The GraphQL event read, keyed by the SAME head, joining by (name, startedAt).
+  const events = {
+    data: {
+      repository: {
+        pullRequest: {
+          commits: {
+            nodes: [
+              {
+                commit: {
+                  oid: head,
+                  statusCheckRollup: {
+                    contexts: {
+                      nodes: [
+                        { __typename: "CheckRun", databaseId: 1001, name: "build", startedAt: "2026-11-12T00:30:00Z", checkSuite: { workflowRun: { event: "pull_request" } } },
+                        { __typename: "CheckRun", databaseId: 1002, name: "build", startedAt: "2026-11-12T00:41:30Z", checkSuite: { workflowRun: { event: "push" } } },
+                      ],
+                      pageInfo: { hasNextPage: false, endCursor: null },
+                    },
+                  },
+                },
+              },
+            ],
+          },
+        },
+      },
+    },
+  };
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 0, body: "" };
+    },
+    async run(command) {
+      // Route the two reads by shape: the GraphQL call carries `api graphql`, the rollup read `pr view`.
+      if (command.includes("api") && command.includes("graphql")) return { code: 0, stdout: JSON.stringify(events), stderr: "" };
+      return { code: 0, stdout: JSON.stringify(prView), stderr: "" };
+    },
+  };
+  const p = parseProbe({ kind: "pr", target: "o/r#12", match: { prState: "checks-green" } });
+  const res = await probeOnce(p, exec, {});
+  assertEquals(res.ready, false, "the red pull_request run survives event normalisation — checks-green is NOT ready");
+  assertStringIncludes(res.detail, "failing");
+});
+
+test("#957 probeOnce pr checks-green: an event-enrichment failure degrades to name-only, never throws", async () => {
+  const prView = {
+    state: "OPEN",
+    mergedAt: null,
+    mergeStateStatus: "CLEAN",
+    isDraft: false,
+    headRefOid: "abc",
+    mergeCommit: null,
+    statusCheckRollup: [{ name: "build", conclusion: "SUCCESS", status: "COMPLETED", startedAt: "2026-11-12T00:41:30Z", completedAt: "2026-11-12T00:41:38Z" }],
+  };
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 0, body: "" };
+    },
+    async run(command) {
+      if (command.includes("api") && command.includes("graphql")) return { code: 1, stdout: "", stderr: "boom" }; // the event read fails
+      return { code: 0, stdout: JSON.stringify(prView), stderr: "" };
+    },
+  };
+  const p = parseProbe({ kind: "pr", target: "o/r#12", match: { prState: "checks-green" } });
+  const res = await probeOnce(p, exec, {});
+  assertEquals(res.ready, true, "a failed event read leaves the rollup event-less — a single green run is still green");
+});
+
 // ── #857: an epic target is a CANONICAL planKey (`owner/repo#N`) — never a URL ────────────────────
 // The epic probe keys off the durable lineage root (`owner/repo#N`, `parseIssue`'s `planKey` shape).
 // Delegating its validation to `parsePr` (whose grammar includes GitHub PR URLs) let a URL pass the
@@ -780,7 +869,7 @@ function prObs(over: Partial<PrObservation> = {}): PrObservation {
     totalChecks: 0,
     presentCheckNames: [],
     pendingCheckNames: [],
-    checkConclusions: {},
+    checkGateConclusions: {},
     isDraft: false,
     headRefOid: "abc123",
     mergedSha: null,

package/app/readiness.ts

@@ -18,7 +18,7 @@
 // any credential is read at execution time from the typed env-contract (`credentialEnv` names a
 // declared {@link EnvKey}; ADR 0004 pinned decision 2) and is redacted from every log line.
 import { isEnvKey, readEnv, readEnvOr } from "./contracts.ts";
-import { allCheckNames, checkConclusions, classifyMergeability, failingCheckNames, type PrState, pendingCheckNames } from "./github.ts";
+import { allCheckNames, applyRollupEvents, CHECK_EVENTS_QUERY, checkGateConclusions, classifyMergeability, failingCheckNames, type PrState, pendingCheckNames } from "./github.ts";
 import { parsePr } from "./prParse.ts";
 import { isoDuration, isoDurationToMs } from "./reviewWait.ts";
 
@@ -764,7 +764,7 @@ export function parsePrView(payload: unknown): PrObservation {
     totalChecks: rollup.length,
     presentCheckNames: allCheckNames(rollup),
     pendingCheckNames: pending,
-    checkConclusions: checkConclusions(rollup),
+    checkGateConclusions: checkGateConclusions(rollup),
     isDraft: j.isDraft === true,
     headRefOid: str(j.headRefOid).trim() || null,
     mergeQueueEntry: null, // readiness probe doesn't read native-queue membership (merge-loop-only signal)
@@ -857,6 +857,76 @@ export function prViewCommand(repo: string, number: string): string {
   return `gh pr view ${shellQuote(number)} --repo ${shellQuote(repo)} --json ${shellQuote("state,mergedAt,mergeStateStatus,statusCheckRollup,isDraft,headRefOid,mergeCommit")}`;
 }
 
+/** The GraphQL page query backing {@link enrichPrViewEvents}, as a single-quoted shell argument.
+ * Mirrors the merge loop's enrichment (`enrichRollupEvents` in `app/github.ts`) but runs through the
+ * probe's injected {@link ProbeExec} so the readiness path stays host-agnostic and unit-testable. */
+function prCheckEventsQuery(): string {
+  return CHECK_EVENTS_QUERY;
+}
+
+/** Enrich a `pr`-probe rollup with each run's triggering event, through the probe's injected
+ * executor. The `gh pr view --json statusCheckRollup` read omits `event`, so without this the
+ * readiness path groups by name alone and a green `push` run hides a red required `pull_request` run
+ * of the same name — `checks-green` then reports ready while the PR run is red (PR #957 review).
+ * Pages `statusCheckRollup.contexts` to exhaustion and pins the read to the rollup's head SHA
+ * (aborting the stamp when the head moved between the two reads), exactly like the merge loop's
+ * `enrichRollupEvents`. Never throws: any transport/parse failure leaves the rollup event-less. */
+async function enrichPrViewEvents(
+  exec: ProbeExec,
+  env: Record<string, string | undefined>,
+  repo: string,
+  number: string,
+  payload: Record<string, unknown>,
+): Promise<void> {
+  const j = payload;
+  if (!Array.isArray(j.statusCheckRollup) || j.statusCheckRollup.length === 0) return;
+  const rollup = j.statusCheckRollup;
+  const headSha = typeof j.headRefOid === "string" ? j.headRefOid : "";
+  const [owner, name] = repo.split("/");
+  const nodes: unknown[] = [];
+  let after: string | null = null;
+  for (;;) {
+    const args = [
+      "api",
+      "graphql",
+      "-f",
+      `query=${prCheckEventsQuery()}`,
+      "-f",
+      `o=${owner}`,
+      "-f",
+      `r=${name}`,
+      "-F",
+      `n=${number}`,
+    ];
+    if (after !== null) args.push("-f", `after=${after}`);
+    const command = `gh ${args.map(shellQuote).join(" ")}`;
+    const out = await exec.run(command, env);
+    if (out.code !== 0) return; // a transport hiccup leaves the rollup event-less (name-only gates)
+    const page = parseJson(out.stdout);
+    if (!isRecord(page)) return;
+    const data = isRecord(page.data) ? page.data : undefined;
+    const repository = data && isRecord(data.repository) ? data.repository : undefined;
+    const pullRequest = repository && isRecord(repository.pullRequest) ? repository.pullRequest : undefined;
+    const commits = pullRequest && isRecord(pullRequest.commits) ? pullRequest.commits : undefined;
+    const firstCommit = commits && Array.isArray(commits.nodes) ? commits.nodes[0] : undefined;
+    const commit = isRecord(firstCommit) && isRecord(firstCommit.commit) ? firstCommit.commit : undefined;
+    if (!isRecord(commit)) return;
+    // Head-pin: the rollup came from the earlier `gh pr view`; if the head moved since, these
+    // contexts belong to a different head — stamping them would join events across heads.
+    const oid = typeof commit.oid === "string" ? commit.oid : "";
+    if (headSha !== "" && oid !== "" && oid !== headSha) return;
+    const rollupObj = isRecord(commit.statusCheckRollup) ? commit.statusCheckRollup : undefined;
+    const contexts = rollupObj && isRecord(rollupObj.contexts) ? rollupObj.contexts : undefined;
+    if (contexts === undefined) return;
+    if (Array.isArray(contexts.nodes)) nodes.push(...contexts.nodes);
+    const pageInfo = isRecord(contexts.pageInfo) ? contexts.pageInfo : undefined;
+    const endCursor = pageInfo && typeof pageInfo.endCursor === "string" ? pageInfo.endCursor : "";
+    if (pageInfo?.hasNextPage !== true || endCursor === "") break;
+    after = endCursor;
+  }
+  applyRollupEvents(rollup, nodes);
+}
+
 // ── Epic / plan-fanout probe (issue #568 — gate a graph on an epic reaching "fully merged") ──────
 
 /** A live epic (plan-fanout) observation, reduced to the fields {@link matchEpic} reads. An nwf epic
@@ -974,7 +1044,15 @@ export async function probeOnce(
       if (!ref) return { ready: false, detail: "pr: unparseable target (not ready)" };
       const out = await exec.run(prViewCommand(ref.repo, ref.number), env);
       if (out.code !== 0) return { ready: false, detail: "pr: gh pr view failed (not ready)" };
-      return matchPr(probe.match, parsePrView(parseJson(out.stdout)));
+      const payload = parseJson(out.stdout);
+      if (!isRecord(payload)) return matchPr(probe.match, parsePrView(payload));
+      // Normalise each run's triggering event BEFORE parsing (PR #957 review): the `gh pr view`
+      // rollup omits `event`, so an un-enriched read groups by name alone and a green `push` run
+      // hides a red required `pull_request` run of the same name — `checks-green` would report
+      // ready while the PR run is red. Shared transport logic with the merge loop, over the
+      // injected executor.
+      await enrichPrViewEvents(exec, env, ref.repo, ref.number, payload);
+      return matchPr(probe.match, parsePrView(payload));
     }
     case "epic": {
       // "Fully merged" is the app's AGGREGATE, not a GitHub read — observe it over the app's own