@nanobpm/nano-workforce 0.107.0 → 0.107.2

package/.github/workflows/ci.yml

@@ -5,6 +5,12 @@ on:
     branches: [main]
   push:
     branches: [main]
+  # Merge-skew guard (issue #366): also run the required gates against the merge queue's
+  # PROSPECTIVE merged commit (GitHub Actions `merge_group` event). Several gates assert a whole-repo invariant (migration prefixes,
+  # BPMN DI freshness, committed generated artifacts) that two PRs can each satisfy in isolation yet
+  # violate once BOTH land on `main`. Validating the speculative merge commit the queue builds — not
+  # the stale PR head — blocks such a merge categorically instead of letting it poison the next PR.
+  merge_group:
 
 permissions:
   contents: read
@@ -77,3 +83,30 @@ jobs:
       - name: E2E (urban-testkit)
         run: npm run e2e
 
+  # FINAL regression guard for epic nano-ide#314 (S6, #321): the compounding oracle that keeps the
+  # code-first (`defineFlow`) and model-first (`.bpmn`) representations of the nano-workforce corpus
+  # in lockstep. For every model it DERIVES the BPMN from its defineFlow port, structurally DIFFS it
+  # against the checked-in golden via the S0 harness (@nanobpm/workflow/test-support), and DEPLOYS
+  # the derived model to the in-process @nanobpm/engine-wasm engine — failing on any structural drift
+  # OR deploy rejection. Parked models (awaiting an upstream construct) must each carry a documented
+  # blocker, and a self-proving canary asserts the oracle's red path genuinely fires so the gate can
+  # never rot into a vacuous green while the corpus is parked. Hermetic (in-process wasm engine, no
+  # sockets), so it runs on every PR/push as its own job.
+  derivation-parity:
+    name: derivation parity (nwf corpus regression guard)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Derive + diff + deploy the full nwf corpus
+        run: npm run check:derivation-parity
+

package/.github/workflows/invariants.yml

@@ -0,0 +1,72 @@
+name: Whole-repo invariants (merge-skew guard)
+
+# Closes the merge-skew failure class (issue #366).
+#
+# Several gates assert a GLOBAL invariant / checked-in DERIVED artifact — `derived == f(sources)` —
+# but the main CI only ever verifies them against a PR's OWN head. Two PRs can each pass in isolation
+# and still break the invariant once BOTH squash-merge, because `main`'s `derived` is then
+# `f(sources_A ∪ sources_B)`, which neither branch's green CI ever saw (the 052 migration collision,
+# #359; the stale `retro.bpmn` DI, #365). Nothing re-checked `main`, so the breakage landed silently
+# and poisoned the next unrelated PR to touch the same job.
+#
+# This lean workflow re-asserts those whole-repo invariants where the merge actually happens:
+#   - `merge_group`  — the queue's PROSPECTIVE merged commit, so a skew is blocked BEFORE it lands.
+#   - `push: [main]` — a fast backstop that fails a `main`-scoped build within minutes if something
+#                      slipped through, instead of first surfacing on an unrelated open PR.
+#   - `schedule`     — a daily catch-all for any skew introduced by a merge that bypassed the queue.
+on:
+  merge_group:
+  push:
+    branches: [main]
+  schedule:
+    # 06:00 UTC daily — cheap catch-all backstop.
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  invariants:
+    name: whole-repo invariants
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history: the migration immutability gate diffs against the merge-base with
+          # origin/main, and the layout gate needs the whole tree — neither works on a shallow clone.
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+
+      - name: Install dependencies
+        run: npm ci
+
+      # Prefix-collision (+ immutability): two branches that each took "the next" free migration
+      # prefix collide once merged. Re-run on the merged/`main` tree so the collision can't hide.
+      - name: Check migration prefixes (no collisions)
+        run: npm run check:migrations
+
+      # BPMN DI freshness: a merged semantic model can carry flows whose DI was regenerated on neither
+      # branch. Regenerate the DI over the merged model and fail if any committed diagram is stale.
+      - name: Check BPMN diagram freshness (layout)
+        run: npm run layout:check
+
+      # Generated-artifact freshness (`urban gen --check`): landscape.gen.html, JSON Schemas / OpenAPI,
+      # the processos grammar (ir.gbnf) and friends are `derived == f(sources)` — re-derive over the
+      # merged sources and fail if a committed artifact drifted.
+      - name: Check generated artifacts (urban gen --check)
+        run: npm run gen:check
+
+      # Navigation index is another checked-in derived artifact; re-assert it on the merged tree too.
+      - name: Check navigation index freshness
+        run: npm run sync:nav:check
+
+      # Backstop: catch ANY other committed generated file that the merged sources render stale, even
+      # one without its own `--check` script above. A clean tree is the whole-repo invariant.
+      - name: No stale committed artifacts on the merged tree
+        run: git diff --exit-code

package/AGENTS.md

@@ -272,7 +272,13 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
   Check `origin/main`, not your branch point — a fan-out epic branch forks at one
   prefix while `main` keeps advancing, so the branch-local "next" number collides
   on merge. Two files must never share a prefix; `npm run check:migrations`
-  (a CI gate) enforces this and fails the build on any new duplicate.
+  (a CI gate) enforces this and fails the build on any new duplicate. Because a
+  prefix collision only exists in the *union* of two branches, this gate — like
+  `layout:check` and the generated-artifact `--check`s — is also re-run on the
+  merge queue's **prospective merged commit** and on **push to `main`** by
+  `.github/workflows/invariants.yml` (issue #366), so a merge-skew collision is
+  blocked at merge time or fails a `main`-scoped build within minutes rather than
+  first surfacing on an unrelated open PR.
 - **A merged migration is IMMUTABLE — never rename, delete, or edit it.** The
   runtime keys the `_urban_migrations` ledger by *filename*, so a renamed file is
   a *new* migration to the runner: it re-runs its DDL against an already-migrated

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.107.2](https://github.com/nanobpm/nano-workforce/compare/v0.107.1...v0.107.2) (2026-08-20)
+
+
+### Bug Fixes
+
+* **ci:** close the merge-skew failure class — re-check whole-repo invariants on the post-merge state ([#367](https://github.com/nanobpm/nano-workforce/issues/367)) ([62f5214](https://github.com/nanobpm/nano-workforce/commit/62f5214961cdb82a708d7cc08acecbf5eecf25ed)), closes [#359](https://github.com/nanobpm/nano-workforce/issues/359) [#365](https://github.com/nanobpm/nano-workforce/issues/365) [#366](https://github.com/nanobpm/nano-workforce/issues/366)
+
+## [0.107.1](https://github.com/nanobpm/nano-workforce/compare/v0.107.0...v0.107.1) (2026-08-20)
+
+
+### Bug Fixes
+
+* **merge-loop:** converge PRs merged/closed out-of-band at every merge-stage wait ([#370](https://github.com/nanobpm/nano-workforce/issues/370)) ([c673c82](https://github.com/nanobpm/nano-workforce/commit/c673c823b6ed5dde5710c4cb677f7c6f01ae59de)), closes [nanobpm/nano-workforce#368](https://github.com/nanobpm/nano-workforce/issues/368)
+
 # [0.107.0](https://github.com/nanobpm/nano-workforce/compare/v0.106.3...v0.107.0) (2026-08-20)
 
 

package/app/mergeOutOfBandTerminal.test.ts

@@ -0,0 +1,178 @@
+// Class regression guard for the out-of-band terminal escape shared by EVERY merge-stage durable
+// wait (issue #368).
+//
+// #368: a PR merged (or closed) OUT-OF-BAND — a maintainer clicks Merge, or a mergify queue lands
+// it — while its merge-loop instance is parked at a durable GitHub wait can silently wedge forever.
+// The `waiting_deps` branch of `pollMerges` only advanced a PR when its *declared dependencies*
+// merged and had NO check on the PR itself already being merged: if those deps never cleared, the
+// instance sat at `wait-deps` forever (ACTIVE, no incident, no timer boundary). `waiting_merge`
+// already guarded this; the fix lifts that guard into ONE shared pre-check
+// (`advanceIfTerminalOutOfBand`) run at the top of all four merge-stage waits — `waiting_deps`,
+// `waiting_merge`, `waiting_lane`, `queued` — so no stage can strand on an out-of-band terminal
+// transition. Each wait subscribes to a DIFFERENT catch, so the pre-check must publish the escape
+// message THAT wait correlates to; this test asserts the class over every (status × merged/closed).
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { pollMerges } from "./service.ts";
+
+// In-memory record gateway (get/find/insert/update/delete), matching app/promotionPoll.test.ts.
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+      async delete(id: any) {
+        for (let i = rows.length - 1; i >= 0; i--) if (rows[i][pk] === id) rows.splice(i, 1);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+// Records every message the poller publishes so a test can assert the exact escape.
+function recordingEngine(): { engine: EngineClient; messages: any[] } {
+  const messages: any[] = [];
+  const engine = {
+    async publishMessage(msg: any) {
+      messages.push(msg);
+    },
+  } as any as EngineClient;
+  return { engine, messages };
+}
+
+// A token-transport GitHub stub. Serves `GET /repos/{repo}/pulls/{n}` from a per-number liveness
+// map so `fetchPrState` (→ `classifyPrLiveness`) reads "merged" / "closed" / "open".
+type Live = "merged" | "closed" | "open";
+function githubFetch(states: Map<number, Live>) {
+  return (url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const json = (obj: unknown, status = 200) =>
+      Promise.resolve(new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } }));
+    const m = u.pathname.match(/\/repos\/[^/]+\/[^/]+\/pulls\/(\d+)$/);
+    if (m) {
+      const n = Number(m[1]);
+      const live = states.get(n) ?? "open";
+      return json({
+        merged: live === "merged",
+        merged_at: live === "merged" ? "2026-08-20T02:35:42Z" : null,
+        state: live === "open" ? "open" : "closed",
+        mergeable_state: live === "open" ? "clean" : "unknown",
+        draft: false,
+        head: { sha: "deadbeef" },
+      });
+    }
+    return Promise.resolve(new Response(`unexpected ${u.pathname}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(states: Map<number, Live>, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = githubFetch(states) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+function prRow(prKey: string, number: number, status: string) {
+  const ts = "2026-08-20T00:00:00Z";
+  return {
+    pr_key: prKey,
+    repo: "o/r",
+    number,
+    url: `https://github.com/o/r/pull/${number}`,
+    title: "t",
+    status,
+    current_round: 0,
+    process_key: null,
+    waiting_since: null,
+    last_review_id: null,
+    outcome: null,
+    created_at: ts,
+    updated_at: ts,
+    converged_at: null,
+    merged_at: null,
+  };
+}
+
+// Every merge-stage durable wait, with the escape message its parked catch subscribes to. The
+// escape differs per wait because each subscribes to a different message — the whole point of the
+// shared pre-check is to publish the RIGHT one so it correlates instead of being dropped.
+const CASES: { status: string; merged: string; closed: string }[] = [
+  // wait-deps subscribes only `deps-cleared` (→ arm-merge → wait-mergeable, where block 2 converges).
+  { status: "waiting_deps", merged: "deps-cleared", closed: "deps-cleared" },
+  // wait-mergeable subscribes `merge-ready` (→ gw-mergeable → attempt-merge terminal short-circuits).
+  { status: "waiting_merge", merged: "merge-ready", closed: "merge-ready" },
+  // waiting_lane is an app hold that leaves the process on wait-mergeable → also `merge-ready`.
+  { status: "waiting_lane", merged: "merge-ready", closed: "merge-ready" },
+  // wait-landed subscribes `merge-landed` (→ mark-merged) and `merge-evicted` (→ arm-merge). A
+  // merged queue PR lands; a closed one can never land, so re-arm and let block 2 abandon it.
+  { status: "queued", merged: "merge-landed", closed: "merge-evicted" },
+];
+
+for (const c of CASES) {
+  for (const live of ["merged", "closed"] as const) {
+    test(`out-of-band ${live} PR at ${c.status} converges via ${live === "merged" ? c.merged : c.closed}`, async () => {
+      const { data, stores } = memData();
+      const { engine, messages } = recordingEngine();
+      stores["pull_requests"] = [prRow("o/r#100", 100, c.status)];
+      // A declared dependency that has NOT merged — the exact condition that wedged `waiting_deps`:
+      // the deps loop would never clear, so ONLY the PR's own terminal state can converge it.
+      stores["pr_dependencies"] = [{ pr_key: "o/r#100", depends_on_key: "o/r#200", created_at: "t" }];
+
+      await withGithub(new Map<number, Live>([[100, live], [200, "open"]]), () =>
+        pollMerges(data, engine, "tok"),
+      );
+
+      assertEquals(messages.length, 1, `expected exactly one escape message for ${c.status}/${live}`);
+      const expected = live === "merged" ? c.merged : c.closed;
+      assertEquals(messages[0].name, expected);
+      assertEquals(messages[0].correlationKey, "o/r#100");
+      if (expected === "merge-ready") assertEquals(messages[0].variables.mergeState, "ready");
+      // Flipped onto the transient `merging` status so a slow pass can't double-signal.
+      assertEquals(stores["pull_requests"][0].status, "merging");
+    });
+  }
+}
+
+// Negative guard: a still-OPEN `waiting_deps` PR whose declared dep is unmerged must NOT be forced
+// terminal by the pre-check — it stays parked (no escape published), proving the pre-check fires
+// only on a real out-of-band terminal transition and never drops a live PR.
+test("still-open waiting_deps PR with an unmerged dep publishes nothing and stays parked", async () => {
+  const { data, stores } = memData();
+  const { engine, messages } = recordingEngine();
+  stores["pull_requests"] = [prRow("o/r#100", 100, "waiting_deps")];
+  stores["pr_dependencies"] = [{ pr_key: "o/r#100", depends_on_key: "o/r#200", created_at: "t" }];
+
+  await withGithub(new Map<number, Live>([[100, "open"], [200, "open"]]), () =>
+    pollMerges(data, engine, "tok"),
+  );
+
+  assertEquals(messages.length, 0);
+  assertEquals(stores["pull_requests"][0].status, "waiting_deps");
+});

package/app/service.ts

@@ -1014,6 +1014,87 @@ async function mirrorTaskStatusForPr(data: DataLayer, prKey: string, status: "op
   }
 }
 
+/** The escape message a merge-stage durable wait must publish when its PR has gone terminal
+ * (merged/closed) OUT-OF-BAND — i.e. someone landed or closed it on GitHub while the process was
+ * parked, so the wait's own declared trigger (deps clearing, a mergeable verdict, a lane release, a
+ * queue landing) may never fire. Each wait subscribes to a DIFFERENT message, so the escape MUST be
+ * the one its parked catch actually correlates to (publishing any other name is dropped by the
+ * engine and re-wedges the PR in the transient `merging` status). All roads lead to the same proven
+ * terminal path — `attempt-merge`'s idempotent already-merged / closed short-circuits (#368):
+ *   • waiting_deps  → parked at `wait-deps`, subscribes ONLY `deps-cleared`. Deps are moot once the
+ *     PR itself landed, so clear them regardless of liveness; `deps-cleared` → `arm-merge` →
+ *     `wait-mergeable`, where block 2 (below) reads the terminal state and drives merged→mark-merged
+ *     / closed→abandon. This is the gap the incident hit — `wait-deps` had NO self-merged escape.
+ *   • waiting_merge / waiting_lane → both parked at `wait-mergeable` (waiting_lane is an app-internal
+ *     hold that leaves the process on `wait-mergeable`), which subscribes `merge-ready`. Route a
+ *     `ready` verdict through `gw-mergeable → attempt-merge`, whose short-circuits complete/abandon.
+ *   • queued → parked at `wait-landed`, subscribes `merge-landed` (→ mark-merged) and `merge-evicted`
+ *     (→ arm-merge). A merged queue PR lands (`merge-landed`); a closed-unmerged one can NEVER land,
+ *     so publishing `merge-landed` would falsely mark it merged — re-arm via `merge-evicted` instead
+ *     and let block 2 abandon it on the next pass. */
+function outOfBandEscapeMessage(
+  status: string,
+  liveness: "merged" | "closed",
+  prKey: string,
+): Parameters<EngineClient["publishMessage"]>[0] {
+  switch (status) {
+    case "waiting_deps":
+      return { name: "deps-cleared", correlationKey: prKey, variables: {} };
+    case "waiting_merge":
+    case "waiting_lane":
+      return {
+        name: "merge-ready",
+        correlationKey: prKey,
+        variables: { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
+      };
+    case "queued":
+      return liveness === "merged"
+        ? { name: "merge-landed", correlationKey: prKey, variables: {} }
+        : { name: "merge-evicted", correlationKey: prKey, variables: {} };
+    default:
+      // Unreachable: only the four merge-stage durable waits call this. Fail loud rather than
+      // mis-route a message the parked catch can't correlate (which would silently re-wedge the PR).
+      throw new Error(`outOfBandEscapeMessage: unexpected merge-stage status ${JSON.stringify(status)}`);
+  }
+}
+
+/** ONE shared out-of-band terminal pre-check for EVERY merge-stage durable wait (#368). A PR parked
+ * at any durable GitHub wait can be merged or closed out-of-band; without a per-branch check on the
+ * PR's OWN state, a wait that keys only off its declared trigger (e.g. `waiting_deps`' declared
+ * deps) strands its instance forever — ACTIVE, no incident, no timer boundary. `waiting_merge`
+ * already guarded this; centralising the check here closes the whole class so no merge stage can
+ * silently wedge on an out-of-band terminal transition.
+ *
+ * Reads the PR's live state (reusing an already-fetched `st` when the caller has one, e.g. block 2)
+ * and, if terminal, publishes the escape message its parked catch subscribes to via
+ * {@link flipToMergingThenPublish} — flipping to the transient `merging` so a slow pass can't
+ * double-signal, reverting on a failed publish. Returns `true` when it advanced the PR (the caller
+ * must `continue`), `false` when the PR is still live / unreadable and the caller should run its
+ * normal per-status logic. Conservative: an unreadable (`null`) or ambiguous (`unknown`/open) state
+ * never resolves terminal, so a false negative only costs a retry while dropping a live PR is
+ * impossible. */
+async function advanceIfTerminalOutOfBand(
+  data: DataLayer,
+  engine: EngineClient,
+  pr: { repo: string; number: number | string; pr_key: string; status: string },
+  token: string,
+  st?: PrState | null,
+): Promise<boolean> {
+  const state = st !== undefined ? st : await fetchPrState(pr.repo, pr.number, token);
+  const liveness = classifyPrLiveness(state);
+  if (liveness !== "merged" && liveness !== "closed") return false;
+  const fromStatus = pr.status; // capture before flip: flipToMergingThenPublish mutates it to `merging`
+  await flipToMergingThenPublish(
+    data,
+    engine,
+    pr.pr_key,
+    fromStatus,
+    outOfBandEscapeMessage(fromStatus, liveness, pr.pr_key),
+  );
+  console.log(`[poller] out-of-band ${liveness} (${fromStatus}) -> ${pr.pr_key}`);
+  return true;
+}
+
 /** Merge-stage poll pass (SPEC §11). Four durable waits, each keyed off the PR's `status`, are
  * advanced by correlating a message — mirroring the review-ready pattern so the process owns
  * the wait and this glue only signals when a GitHub condition is met:
@@ -1023,12 +1104,20 @@ async function mirrorTaskStatusForPr(data: DataLayer, prKey: string, status: "op
  *   • queued        → the queued PR landed → `merge-landed`; or it conflicts (DIRTY) → `merge-evicted`
  * On publish we flip status to the transient `merging` (which no branch scans) so a slow pass
  * can't double-signal, exactly as `pollReviews` flips to `converging`; `flipToMergingThenPublish`
- * reverts the flip if the publish fails so a failed handoff can't wedge the PR. */
-async function pollMerges(data: DataLayer, engine: EngineClient, token: string) {
+ * reverts the flip if the publish fails so a failed handoff can't wedge the PR.
+ *
+ * EVERY branch first runs {@link advanceIfTerminalOutOfBand} — one shared "is this PR already
+ * terminal (merged/closed) out-of-band?" pre-check — so no merge stage can silently strand when a PR
+ * is landed/closed outside the loop (the `waiting_deps` self-merged wedge, #368). */
+export async function pollMerges(data: DataLayer, engine: EngineClient, token: string) {
   // 1) Dependencies merged?
   for (const pr of await prs(data).find({ status: "waiting_deps" })) {
     const prKey = pr.pr_key;
     try {
+      // Out-of-band terminal FIRST: a PR merged/closed outside the loop while parked at `wait-deps`
+      // must converge even if its declared deps never clear (the #368 wedge). `wait-deps` subscribes
+      // only `deps-cleared`, so the shared pre-check publishes exactly that.
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token)) continue;
       const depRows = await deps(data).find({ pr_key: prKey });
       let allMerged = true;
       for (const d of depRows) {
@@ -1055,38 +1144,12 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
     try {
       const st = await fetchPrState(repo, number, token);
       if (st === null) continue; // no transport → skip this PR (others may still advance)
-      const liveness = classifyPrLiveness(st);
-      if (liveness === "merged") {
-        // Landed out-of-band (a maintainer clicked Merge, a mergify queue merged it, etc.). The
-        // instance is parked at `wait-mergeable`, which subscribes to `merge-ready` — NOT
-        // `merge-landed` (that catch, `wait-landed`, only exists later, after we enqueue). Publishing
-        // `merge-landed` here has no subscription to correlate to, so the engine drops it and the PR
-        // wedges forever in the transient `merging` status (which no poller branch re-scans).
-        // Publish `merge-ready` with a `ready` verdict instead: it routes through `gw-mergeable` to
-        // `attempt-merge`, whose idempotent already-merged check completes the loop (`mark-merged`).
-        await flipToMergingThenPublish(data, engine, prKey, "waiting_merge", {
-          name: "merge-ready",
-          correlationKey: prKey,
-          variables: { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
-        });
-        console.log(`[poller] already merged -> ${prKey}`);
-        continue;
-      }
-      if (liveness === "closed") {
-        // Closed on GitHub WITHOUT merging (e.g. superseded by a newer PR — #350). The PR can never
-        // land, so it must NOT be classified as blocked/conflict and escalated (that orphans the
-        // process on a dead PR, #342). Route it through the same canonical `merge-ready` → `ready` →
-        // `attempt-merge` path as the merged case; the merge worker's closed short-circuit records a
-        // terminal `abandoned` audit row and drives the loop down its terminate/abandon end event.
-        // One canonical abandon implementation lives in the worker — the poller only routes to it.
-        await flipToMergingThenPublish(data, engine, prKey, "waiting_merge", {
-          name: "merge-ready",
-          correlationKey: prKey,
-          variables: { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
-        });
-        console.log(`[poller] closed without merging -> ${prKey}`);
-        continue;
-      }
+      // Out-of-band terminal (merged/closed) → the shared pre-check publishes `merge-ready {ready}`,
+      // routing through `gw-mergeable → attempt-merge` whose idempotent already-merged check completes
+      // the loop (`mark-merged`) and whose closed short-circuit abandons a PR closed without merging
+      // (#342/#350). Reuse the `st` we just read so we don't double-fetch. This is the proven terminal
+      // path the whole class (#368) now shares.
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
       const verdict = classifyMergeability(st);
       if (verdict === "waiting") {
         // Frugal-CI remedy (#43): when the repo publishes a merge protocol that wants a fresh
@@ -1145,6 +1208,10 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
   for (const pr of await prs(data).find({ status: "waiting_lane" })) {
     const prKey = pr.pr_key;
     try {
+      // Out-of-band terminal FIRST: a lane-held PR merged/closed outside the loop must converge even
+      // if its lane predecessor never releases the hold. waiting_lane leaves the process parked at
+      // `wait-mergeable`, so the shared pre-check publishes `merge-ready {ready}` (→ attempt-merge).
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token)) continue;
       const lane = await mergeLaneDecisionForPr(data, prKey);
       if (lane?.isHeld) continue;
       await prs(data).update(prKey, { status: "waiting_merge", updated_at: now() });
@@ -1172,15 +1239,16 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
     try {
       const st = await fetchPrState(repo, number, token);
       if (st === null) continue; // no transport → skip this PR (others may still advance)
-      const verdict = queuedVerdict(st);
-      if (verdict === "landed") {
-        await flipToMergingThenPublish(data, engine, prKey, "queued", {
-          name: "merge-landed",
-          correlationKey: prKey,
-          variables: {},
-        });
-        console.log(`[poller] queued PR landed -> ${prKey}`);
-      } else if (verdict === "evicted") {
+      // Out-of-band terminal FIRST (reusing `st`): a queued PR merged out-of-band lands
+      // (`merge-landed` → mark-merged); one CLOSED out-of-band without merging can never land, so the
+      // pre-check re-arms it (`merge-evicted` → arm-merge) and block 2 abandons it — a closed queued
+      // PR would otherwise wedge, since `queuedVerdict` calls a non-DIRTY closed PR merely "waiting"
+      // (#368). The DIRTY-while-open eviction below still handles a live-but-conflicted queue drop.
+      if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
+      // Terminal states (merged/closed) are handled by the shared pre-check above; here the PR is
+      // still open, so the only remaining reason to leave `wait-landed` is a live queue DROP — a real
+      // merge CONFLICT (`DIRTY`). `queuedVerdict` stays the canonical classifier for that.
+      if (queuedVerdict(st) === "evicted") {
         await flipToMergingThenPublish(data, engine, prKey, "queued", {
           name: "merge-evicted",
           correlationKey: prKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.107.0",
+  "version": "0.107.2",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -41,6 +41,8 @@
     "heal:migrations": "node --experimental-strip-types scripts/heal-migration-ledger.ts",
     "check:contracts": "node --experimental-strip-types scripts/check-contracts.ts",
     "reconcile:contracts": "node --experimental-strip-types scripts/reconcile-contracts.ts",
+    "precheck:derivation-parity": "urban gen",
+    "check:derivation-parity": "node --experimental-strip-types scripts/check-derivation-parity.ts",
     "gen": "urban gen",
     "gen:check": "urban gen --check",
     "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",

package/scripts/check-derivation-parity.ts

@@ -0,0 +1,213 @@
+// check-derivation-parity — the FINAL regression guard for epic nanobpm/nano-ide#314 (S6, #321).
+//
+// This is the compounding oracle that keeps the code-first (`defineFlow`) and model-first (`.bpmn`)
+// representations of the nano-workforce corpus in lockstep. For EVERY golden under
+// `resources/processes/*.bpmn` it runs the full derive → diff → deploy loop:
+//
+//   (a) DERIVE  — take the golden's `defineFlow` port (test/derivation-parity/flows.ts) and derive
+//                 its BPMN with `@nanobpm/workflow`.
+//   (b) DIFF    — structurally compare the derived model against the checked-in golden using the S0
+//                 parity harness (`@nanobpm/workflow/test-support`'s `normalize` / `assertDerivation-
+//                 Parity`). The normalization/diff is NEVER reimplemented here — this gate only calls
+//                 the shared harness, so the code-first check can't drift from the unit suite's.
+//   (c) DEPLOY  — deploy the derived model to the in-process `@nanobpm/engine-wasm` engine (via
+//                 `@nanobpm/urban-testkit`) and assert the engine ACCEPTS it.
+//
+// Any structural drift (b) OR deploy rejection (c) fails the build.
+//
+// PARKED MODELS ARE ACCOUNTED FOR, NOT IGNORED. The corpus is currently fully parked behind
+// upstream `@nanobpm/workflow` constructs (see test/derivation-parity/flows.ts for the three blocker
+// classes). Each parked model must carry a documented `blockedReason`; a model that is neither
+// ported nor documented fails this gate, so the corpus can never silently lose coverage. As each
+// parked model flips to a real `flow` upstream, it is automatically pulled into the full
+// derive → diff → deploy loop here with NO change to this script.
+//
+// SELF-PROVING CANARY. Because the corpus is (today) all-parked, a gate that merely iterated it
+// would be a vacuous green — it could rot without anyone noticing. So before touching the corpus we
+// run a CANARY that proves the oracle's RED path genuinely fires: a faithful derived flow deploys
+// green and diffs green, a drifted derivation is CAUGHT by the diff, and a corrupted model is
+// REJECTED by the engine. If any red path fails to fire (the diff misses drift, or the engine
+// accepts garbage), the gate fails — the oracle must be able to say no.
+
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createWasmEngineClient } from "@nanobpm/urban-testkit";
+import type { DeclarativeFlow } from "@nanobpm/workflow";
+import { declarativeToBpmn, defineFlow, toDeployableBpmn } from "@nanobpm/workflow";
+import { assertDerivationParity } from "@nanobpm/workflow/test-support";
+import { PORTS } from "../test/derivation-parity/flows.ts";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PROCESSES_DIR = join(REPO_ROOT, "resources", "processes");
+const goldenPath = (model: string): string => join(PROCESSES_DIR, `${model}.bpmn`);
+
+type WasmEngine = Awaited<ReturnType<typeof createWasmEngineClient>>;
+
+const errMsg = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
+/** Deploy a derived flow's *deployable* BPMN (semantic model + auto-layout DI) to the wasm engine
+ *  and assert acceptance. Throws when the engine rejects the model or reports nothing deployed. */
+async function deployDerived(engine: WasmEngine, id: string, flow: DeclarativeFlow): Promise<void> {
+  const xml = await toDeployableBpmn(flow);
+  const result = await engine.deployResources([{ name: `${id}.bpmn`, content: xml, contentType: "application/xml" }]);
+  if (!result || result.deployed < 1) {
+    throw new Error(`engine did not accept derived "${id}" (deployed=${result?.deployed ?? 0})`);
+  }
+}
+
+/** Prove the derive → diff → deploy oracle can actually say NO, so an all-parked corpus can't let
+ *  this gate rot into a vacuous green. Pushes a line onto `errors` for any red path that fails to
+ *  fire. */
+async function proveOracleFiresRed(engine: WasmEngine, errors: string[]): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-parity-canary-"));
+  try {
+    const canary = defineFlow("parity-canary", (w) => {
+      w.task("step-a", { jobType: "senior:noop" });
+    });
+    const golden = join(dir, "parity-canary.bpmn");
+    writeFileSync(golden, declarativeToBpmn(canary), "utf8");
+
+    // DIFF, green: a faithful derivation matches its own golden.
+    try {
+      assertDerivationParity(canary, golden);
+    } catch (e) {
+      errors.push(`  canary: a faithful derivation was reported as drift — the diff is broken (${errMsg(e)})`);
+    }
+
+    // DIFF, red: a structurally different derivation MUST be caught.
+    const drifted = defineFlow("parity-canary", (w) => {
+      w.task("step-a", { jobType: "senior:noop" });
+      w.task("step-b", { jobType: "senior:noop" });
+    });
+    let structuralFired = false;
+    try {
+      assertDerivationParity(drifted, golden);
+    } catch {
+      structuralFired = true;
+    }
+    if (!structuralFired) {
+      errors.push("  canary: the structural-drift oracle did NOT fire (an added node slipped past the diff)");
+    }
+
+    // DEPLOY, green: a valid derived model is accepted by the engine.
+    try {
+      await deployDerived(engine, "parity-canary", canary);
+    } catch (e) {
+      errors.push(`  canary: the engine rejected a VALID derived model — the deploy oracle is broken (${errMsg(e)})`);
+    }
+
+    // DEPLOY, red: a corrupted model MUST be rejected.
+    let deployFired = false;
+    try {
+      await engine.deployResources([{ name: "corrupt.bpmn", content: "<not-bpmn/>", contentType: "application/xml" }]);
+    } catch {
+      deployFired = true;
+    }
+    if (!deployFired) {
+      errors.push("  canary: the deploy-rejection oracle did NOT fire (the engine accepted invalid BPMN)");
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Assert PORTS covers EXACTLY the checked-in goldens under
+ *  `resources/processes/*.bpmn`. Without this the guard's "full corpus" claim is
+ *  unproven: a newly-added golden with no PORTS entry would be silently skipped
+ *  (eroding coverage while still reporting OK), and a stale PORTS entry for a
+ *  deleted golden would iterate a model that no longer exists. Both directions
+ *  fail the gate. */
+function assertPortsCoverGoldens(errors: string[]): void {
+  const goldens = readdirSync(PROCESSES_DIR)
+    .filter((f) => f.endsWith(".bpmn"))
+    .map((f) => f.slice(0, -".bpmn".length));
+  const ported = PORTS.map((p) => p.model);
+
+  const missing = goldens.filter((g) => !ported.includes(g)).sort();
+  if (missing.length > 0) {
+    errors.push(
+      `  PORTS is missing ${missing.length} checked-in golden(s) under resources/processes ` +
+        `(${missing.join(", ")}) — add a derived flow or a documented blockedReason so the ` +
+        `"full corpus" guard can't silently skip them.`,
+    );
+  }
+
+  const orphaned = ported.filter((m) => !goldens.includes(m)).sort();
+  if (orphaned.length > 0) {
+    errors.push(
+      `  PORTS references ${orphaned.length} model(s) with no golden under resources/processes ` +
+        `(${orphaned.join(", ")}) — remove the stale entry or restore its golden.`,
+    );
+  }
+
+  const seen = new Set<string>();
+  const duplicated = new Set<string>();
+  for (const m of ported) {
+    if (seen.has(m)) duplicated.add(m);
+    seen.add(m);
+  }
+  if (duplicated.size > 0) {
+    errors.push(
+      `  PORTS has duplicate entries for ${duplicated.size} model(s) (${[...duplicated].sort().join(", ")}) — ` +
+        `each golden must appear exactly once.`,
+    );
+  }
+}
+
+async function main(): Promise<void> {
+  const errors: string[] = [];
+  const engine = await createWasmEngineClient();
+
+  let ported = 0;
+  let deployed = 0;
+  let parked = 0;
+
+  try {
+    assertPortsCoverGoldens(errors);
+    await proveOracleFiresRed(engine, errors);
+
+    for (const port of PORTS) {
+      if (port.flow) {
+        ported++;
+        const golden = goldenPath(port.model);
+        try {
+          assertDerivationParity(port.flow, golden);
+        } catch (e) {
+          errors.push(`  ${port.model}: STRUCTURAL DRIFT vs golden — ${errMsg(e)}`);
+          continue; // a model that doesn't derive its golden can't be trusted to deploy meaningfully
+        }
+        try {
+          await deployDerived(engine, port.model, port.flow);
+          deployed++;
+        } catch (e) {
+          errors.push(`  ${port.model}: DEPLOY REJECTED by wasm engine — ${errMsg(e)}`);
+        }
+      } else {
+        parked++;
+        if (!port.blockedReason || port.blockedReason.trim().length === 0) {
+          errors.push(
+            `  ${port.model}: neither ported (no flow) nor documented (no blockedReason) — every ` +
+              `corpus model must derive its golden or carry a precise blocker.`,
+          );
+        }
+      }
+    }
+  } finally {
+    // Release the underlying WASM engine resources so repeated runs (local / CI matrix) don't leak.
+    await engine.close();
+  }
+
+  if (errors.length > 0) {
+    console.error(`check-derivation-parity: the nano-workforce corpus failed its derivation-parity guard:\n${errors.join("\n")}`);
+    process.exit(1);
+  }
+
+  console.log(
+    `check-derivation-parity: OK (${PORTS.length} corpus models — ${ported} ported ` +
+      `[${deployed} deploy-accepted by the wasm engine], ${parked} documented-parked; oracle red paths verified).`,
+  );
+}
+
+if (import.meta.main) main();

package/scripts/check-migrations.test.ts

@@ -6,7 +6,7 @@
 // with origin/main; here we drive its diff classifier directly with representative
 // `git diff --find-renames --name-status` output so each violation shape is pinned.
 import test from "node:test";
-import { immutabilityErrorsFromDiff } from "./check-migrations.ts";
+import { collisionErrorsFromFiles, immutabilityErrorsFromDiff } from "./check-migrations.ts";
 import { assert, assertEquals } from "#test-assert";
 
 test("a rename of a merged migration is a violation", () => {
@@ -56,3 +56,41 @@ test("mixed changes report every violation but ignore the addition", () => {
   assert(errors.some((e) => /DELETED/.test(e)));
   assert(errors.some((e) => /RENAMED/.test(e)));
 });
+
+// Merge-skew regression coverage (issue #366).
+//
+// The failure class this pins: two PRs each pass `check:migrations` on their OWN head, but their
+// COMBINATION on `main` after both squash-merge violates the prefix-collision invariant — because
+// neither branch's green CI ever saw the other's file. The 052 collision (#351 + #355, hotfixed in
+// #359) was exactly this. Driving the pure collision detector with each branch's tree AND their union
+// demonstrates that only the post-merge state trips the gate, which is why the gate must re-run on
+// the prospective merged commit (merge_group) / on push to `main`, not just PR heads.
+test("merge skew: two individually-clean branches whose union collides IS caught", () => {
+  const mainTree = ["050_capability_gates.sql", "051_merges_per_day.sql"];
+  // Each branch independently picks the same "next free" prefix (060) without seeing its sibling.
+  const branchA = [...mainTree, "060_plan_conformance.sql"];
+  const branchB = [...mainTree, "060_worker_durable_resume.sql"];
+
+  // On its own head, each branch is clean — this is why both PRs go green in isolation.
+  assertEquals(collisionErrorsFromFiles(branchA), [], "branch A alone has no colliding prefix");
+  assertEquals(collisionErrorsFromFiles(branchB), [], "branch B alone has no colliding prefix");
+
+  // The post-merge tree on `main` (git merges both files cleanly — the names don't textually
+  // conflict) now shares slot 060. The gate, re-run on that merged state, catches it.
+  const mergedOnMain = [...new Set([...branchA, ...branchB])].sort();
+  const errors = collisionErrorsFromFiles(mergedOnMain);
+  assertEquals(errors.length, 1, "the merged tree has exactly one colliding prefix");
+  assert(/prefix 060/.test(errors[0]));
+  assert(/060_plan_conformance.sql/.test(errors[0]));
+  assert(/060_worker_durable_resume.sql/.test(errors[0]));
+});
+
+test("collision detector flags a non-NNN shape and grandfathers historical dupes", () => {
+  assert(collisionErrorsFromFiles(["nope.sql"]).some((e) => /required NNN_name.sql shape/.test(e)));
+  // Grandfathered historical collisions (already applied forward-only) must stay exempt.
+  assertEquals(
+    collisionErrorsFromFiles(["052_plan_conformance.sql", "052_worker_durable_resume.sql"]),
+    [],
+    "grandfathered prefix 052 is not a new violation",
+  );
+});

package/scripts/check-migrations.ts

@@ -150,11 +150,13 @@ function checkImmutability(errors: string[]): boolean {
   return true;
 }
 
-function main(): void {
-  const files = readdirSync(MIGRATIONS_DIR)
-    .filter((f) => f.endsWith(".sql"))
-    .sort();
-
+/** Classify a migration file listing into shape + prefix-collision errors. Pure over the file list
+ *  so the MERGE-SKEW scenario can be pinned in a test: two individually-clean branches each pass this
+ *  over their OWN tree, but the gate must fail over the UNION that lands on `main` after both merge
+ *  (issue #366). This is exactly why the gate has to re-run on the post-merge state — neither branch's
+ *  green CI ever saw the other's prefix. Grandfathered historical collisions stay exempt. Exported
+ *  for unit coverage. */
+export function collisionErrorsFromFiles(files: readonly string[]): string[] {
   const errors: string[] = [];
   const byPrefix = new Map<string, string[]>();
 
@@ -175,13 +177,23 @@ function main(): void {
   for (const [prefix, group] of byPrefix) {
     if (group.length > 1 && !GRANDFATHERED_DUPES.has(prefix)) {
       errors.push(
-        `  prefix ${prefix} is used by ${group.length} files: ${group.join(", ")} — ` +
+        `  prefix ${prefix} is used by ${group.length} files: ${[...group].sort().join(", ")} — ` +
           `two migrations cannot share an apply-order slot. Renumber the newer one to the next ` +
           `free prefix (check origin/main, not your branch point).`,
       );
     }
   }
 
+  return errors;
+}
+
+function main(): void {
+  const files = readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith(".sql"))
+    .sort();
+
+  const errors: string[] = collisionErrorsFromFiles(files);
+
   const immutabilityChecked = checkImmutability(errors);
 
   if (errors.length > 0) {

package/test/derivation-parity/README.md

@@ -121,3 +121,28 @@ Then, on a resumed run here:
 
 No golden `.bpmn` file may be edited to force a match — the derivation must
 reproduce the checked-in golden.
+
+## CI regression guard (S6, nano-ide#321)
+
+The unit suite above (run under `npm test`) does the DERIVE + structural DIFF for
+every ported model. The **final regression guard** adds the third leg — DEPLOY —
+and wires the whole corpus into CI as its own job:
+
+    npm run check:derivation-parity        # scripts/check-derivation-parity.ts
+
+For every model it derives the BPMN from its `defineFlow` port, structurally
+diffs it against the checked-in golden via the **same** S0 harness
+(`normalize` / `assertDerivationParity` — never reimplemented), and **deploys the
+derived model to the in-process `@nanobpm/engine-wasm` engine**
+(`@nanobpm/urban-testkit`), asserting the engine accepts it. Any structural drift
+**or** deploy rejection fails the build. Parked models must each carry a
+documented `blockedReason`, so the corpus can never silently lose coverage; a
+parked model flips into the full derive → diff → deploy loop automatically the
+moment its `flow` lands — no change to the gate.
+
+Because the corpus is (currently) fully parked, the gate runs a **self-proving
+canary** first: it proves a faithful derivation deploys and diffs green, a
+drifted derivation is caught by the diff, and a corrupted model is rejected by
+the engine — so the oracle's red path can never rot into a vacuous green. The
+guard runs on every PR/push as the `derivation-parity` job in
+`.github/workflows/ci.yml`.