@nanobpm/nano-workforce 0.98.0 → 0.99.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.99.0](https://github.com/nanobpm/nano-workforce/compare/v0.98.1...v0.99.0) (2026-08-19)
+
+
+### Features
+
+* **review-loop:** re-express the review-ready wait on the ReadinessProbe gate ([#259](https://github.com/nanobpm/nano-workforce/issues/259)) ([#338](https://github.com/nanobpm/nano-workforce/issues/338)) ([4d86509](https://github.com/nanobpm/nano-workforce/commit/4d86509f1f55dd9b31417add323e04da5b574b3d)), closes [#258](https://github.com/nanobpm/nano-workforce/issues/258) [#258](https://github.com/nanobpm/nano-workforce/issues/258)
+
+## [0.98.1](https://github.com/nanobpm/nano-workforce/compare/v0.98.0...v0.98.1) (2026-08-19)
+
+
+### Bug Fixes
+
+* **merge-loop:** transient 'Base branch was modified' merge race → bounded retry, not escalate ([#335](https://github.com/nanobpm/nano-workforce/issues/335)) ([4093d50](https://github.com/nanobpm/nano-workforce/commit/4093d50b0ecd1a226bcfe7a5ecca10ba1db0937a)), closes [#330](https://github.com/nanobpm/nano-workforce/issues/330) [#334](https://github.com/nanobpm/nano-workforce/issues/334)
+
 # [0.98.0](https://github.com/nanobpm/nano-workforce/compare/v0.97.1...v0.98.0) (2026-08-19)
 
 

package/SPEC.md

@@ -29,7 +29,7 @@ surface are proposed and open for adjustment.
           submit (form / webhook)
                      │
                      ▼
-            ┌───────────────────┐        review-ready (msg)      ┌──────────┐
+            ┌───────────────────┐      readiness-ready (msg)     ┌──────────┐
             │  convergence-loop │◀───────────────────────────────│  poller  │
             │      (BPMN)       │                                 └────┬─────┘
             └─────────┬─────────┘◀───────────────┐                    │ polls
@@ -48,8 +48,10 @@ surface are proposed and open for adjustment.
   agent worker slots and job timeouts are never held hostage to Copilot's reply
   latency.
 - **Poller**: an in-app background loop that watches waiting PRs and publishes
-  the `review-ready` message when a new review lands (no GitHub webhook needed;
-  works behind NAT).
+  the canonical `readiness-ready` wait-gate message (ADR 0001 §2) when a new
+  review lands — the "out-of-band poller-correlated shape" the review-ready wait
+  is re-expressed on (#259), so there is one "wait for the world" mechanism (no
+  GitHub webhook needed; works behind NAT).
 
 ## 3. Repository layout
 
@@ -100,7 +102,7 @@ known at submit time, carried as a process variable and stored on the DB row.
 │      ├── converged  → [Mark converged] → (end: converged)
 │      │
 │      ├── addressed  → [Record round] → <event-based gateway: review ready or timeout?>
-│      │                     ├── review-ready (msg catch, key = prKey) → round++ ─────┐
+│      │                     ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
 │      │                     └── =reviewWaitTimeout (timer catch)                     │
 │      │                          → [Escalate: review stalled] (blocked)              │
 │      │                          → [Wait: wait-answer userTask] ─────────────────────┤
@@ -127,8 +129,9 @@ Guard: before each Review round, if round > MAX_ROUNDS → force an escalation
 ```
 
 Notes:
-- On `addressed`, the loop parks at an **event-based gateway** that races a
-  `review-ready` message (correlated by the poller when a fresh review lands)
+- On `addressed`, the loop parks at an **event-based gateway** that races the
+  canonical `readiness-ready` wait-gate message (ADR 0001 §2; correlated by the
+  poller when a fresh review lands)
   against a `=reviewWaitTimeout` timer (seeded at submit from
   `NANO_PR_REVIEW_WAIT_TIMEOUT`, default `PT20M`). Whichever fires first
   withdraws the other — the message arm advances `round`, the timer arm escalates
@@ -136,7 +139,8 @@ Notes:
   hanging forever. Because `persist-round` already recorded this `round` as
   `addressed` before the gateway, the timer arm opens the escalation **without
   re-recording the round** (it passes `recordRound=false`), so a single round is
-  never logged as both `addressed` and `blocked`. This replaced a bare
+  never logged as both `addressed` and `blocked`. This wait is re-expressed on the
+  ONE `ReadinessProbe` wait-gate primitive (#258, ADR 0001 §2); it replaced a bare
   `review-ready` catch that could hang
   indefinitely: Copilot won't re-review a round with no new commit and routinely
   dismisses a re-request, so with no timeout a review that never arrives wedged
@@ -210,7 +214,7 @@ Consequences the prompt (`resources/prompts/review-round.md`) encodes:
 | message | correlationKey | published by | payload |
 |---|---|---|---|
 | `pr-submitted` | — (start) | submit route/webhook | `{repo, prNumber, prUrl, prKey}` |
-| `review-ready` | `prKey` | **poller** | `{reviewId, reviewState, submittedAt}` |
+| `readiness-ready` | `prKey` | **poller** | `{ready, detail?}` (ADR 0001 §2 wait-gate; the review-ready wait, re-expressed on the ReadinessProbe gate — #259) |
 | `deps-cleared` | `prKey` | **poller** (merge) | — (all `Depends-on` PRs merged) |
 | `merge-ready` | `prKey` | **poller** (merge) | `{mergeState}` (`ready` \| `conflict` \| `blocked`); when `blocked`, also `{failingChecks, failingChecksList}` for the `senior:fix-ci` branch |
 | `merge-landed` | `prKey` | **poller** (merge) | — (queued PR merged, or merged out-of-band) |
@@ -368,8 +372,8 @@ An in-app loop (interval `NANO_PR_POLL_MS`, default 60s):
 1. `SELECT pr_key, repo, number, waiting_since, last_review_id, last_nudge_at FROM pull_requests WHERE status = 'waiting_review'`.
 2. For each, GET the PR's reviews from GitHub; find the newest review submitted
    after `waiting_since` with id > `last_review_id`.
-3. If found → publish `review-ready` (key = `pr_key`, `{reviewId, ...}`) and set
-   `last_review_id`.
+3. If found → publish the canonical `readiness-ready` wait-gate message (key =
+   `pr_key`, `{ready, detail}`) and set `last_review_id`.
 4. If **not** found → ensure a review is in flight: unless Copilot is already a
    pending reviewer, **re-request** it (REST `requested_reviewers`, exact login
    `copilot-pull-request-reviewer[bot]`) and record `last_nudge_at`. This is
@@ -377,7 +381,7 @@ An in-app loop (interval `NANO_PR_POLL_MS`, default 60s):
    so a re-request Copilot dismisses is retried without hammering the API. A repo
    where Copilot isn't an assignable reviewer (HTTP 422) is left to the process's
    review-wait timer (§4). This closes the stall where Copilot won't spontaneously
-   re-review and silently dismisses a re-request, so no `review-ready` ever fires.
+   re-review and silently dismisses a re-request, so no `readiness-ready` ever fires.
 
 Requires a GitHub token (`GITHUB_TOKEN`) or the host `gh` CLI. One cheap API call
 per waiting PR per interval (plus at most one reviewer-state check + re-request per
@@ -644,7 +648,7 @@ but encode incompatible decisions about a shared contract** — a genuine design
   `baseRef`) that let large monorepos provision within the clone timeout (#287); the
   harness is PR-agnostic and provisions from that envelope. The worker stays a pure
   provisioner.
-- **review-ready via GitHub webhook** — same message, swappable faster trigger,
+- **readiness-ready via GitHub webhook** — same `readiness-ready` message, swappable faster trigger,
   when the app is publicly reachable. Deferred (poller-only for v1).
 - **Supervised vs external worker** — the agent runs as an external
   `c8ctl nano work` daemon by default; a supervised in-server mode is possible

package/app/contracts.ts

@@ -117,6 +117,13 @@ export const ENV_CONTRACTS = {
     semantics: "Maximum rebase attempts per PR.",
     default: "3",
   },
+  NANO_PR_MAX_MERGE_RETRIES: {
+    category: "env",
+    name: "NANO_PR_MAX_MERGE_RETRIES",
+    owner: "app/service.ts",
+    semantics: "Maximum transient base/head-moved merge-race retries per PR before escalating.",
+    default: "5",
+  },
   NANO_PR_REVIEW_WAIT_TIMEOUT: {
     category: "env",
     name: "NANO_PR_REVIEW_WAIT_TIMEOUT",

package/app/github.ts

@@ -348,7 +348,7 @@ export async function hasPendingCopilotReviewer(
 }
 
 /** Request a fresh Copilot review on the PR (REST reviewers endpoint, exact `[bot]` login), so
- * the process's `review-ready` catch can eventually fire. Returns `"requested"` on success,
+ * the process's `readiness-ready` review wait-gate catch can eventually fire. Returns `"requested"` on success,
  * `"unavailable"` when Copilot is not an assignable reviewer on that repo (HTTP 422 — e.g.
  * Copilot review not enabled there), or `null` when no transport is usable. Never throws for the
  * 422 "not assignable" case; only a genuine transport failure propagates. */
@@ -822,14 +822,26 @@ export interface MergeOptions {
   admin: boolean;
 }
 export interface MergeResult {
-  outcome: "merged" | "queued" | "blocked";
+  outcome: "merged" | "queued" | "blocked" | "retry";
   detail: string;
 }
 
+/** GitHub-flagged *retryable* merge races: the base (or head) branch advanced between the
+ * mergeability read and the merge mutation, so GitHub aborted the merge with a "… try the merge
+ * again" message. These are transient — GitHub itself tells us to just retry — so the merge loop
+ * must re-attempt on the settled base, NOT page a human. Matches GitHub's stable message across
+ * both the GraphQL `mergePullRequest` error and its HTTP 405 REST variant. Kept narrow — the exact
+ * "<Base|Head> branch was modified" phrase — so a genuine block (conflict, failing required check,
+ * 403 perms, 422 not-mergeable) is never swallowed as transient. */
+export function isTransientMergeRace(detail: string): boolean {
+  return /\b(?:base|head) branch was modified\b/i.test(detail);
+}
+
 /** Attempt to land the PR. Returns `merged` (landed now), `queued` (added to the repo's merge
- * queue — the poller then watches for it to land), or `blocked` (GitHub refused — a human must
- * resolve it, then reply to retry). `null` when no transport is usable. Never throws for a
- * refused merge; only a genuine transport failure propagates. */
+ * queue — the poller then watches for it to land), `retry` (a transient base/head-moved race —
+ * GitHub says to re-attempt on the settled base, no human needed), or `blocked` (GitHub refused —
+ * a human must resolve it, then reply to retry). `null` when no transport is usable. Never throws
+ * for a refused merge; only a genuine transport failure propagates. */
 export async function mergePr(
   repo: string,
   number: number | string,
@@ -850,6 +862,9 @@ export async function mergePr(
       // A merge-queue-required branch surfaces as an error on older gh; treat as queued when the
       // message says so, otherwise it is a genuine block (conflict, failing gate, perms).
       if (/added to the merge queue|enqueued/i.test(msg)) return { outcome: "queued", detail: msg };
+      // A base/head-moved race is transient (GitHub says to retry) — re-enter the merge loop
+      // rather than escalate. Checked before the catch-all block so it is never swallowed as blocked.
+      if (isTransientMergeRace(msg)) return { outcome: "retry", detail: msg };
       return { outcome: "blocked", detail: msg };
     }
   }
@@ -877,6 +892,9 @@ export async function mergePr(
     return { outcome: "queued", detail: "merge accepted; PR not yet landed (awaiting merge queue)" };
   }
   const detail = `github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim();
+  // The REST merge endpoint returns 405 "Base branch was modified. Review and try the merge again."
+  // for the same transient race — classify it as retry, not a human-actionable block.
+  if (isTransientMergeRace(detail)) return { outcome: "retry", detail };
   return { outcome: "blocked", detail };
 }
 

package/app/mergeEscalationQuestion.test.ts

@@ -103,6 +103,23 @@ test("the question distinguishes all four blocked/SLA triggers rather than a sin
   assertStringIncludes(el, 'agentVerdict = "blocked"', "must branch CI could-not-fix vs SLA on the agent verdict binding, not the overwritten status");
 });
 
+test("retry-budget-exhausted escalation reads as a repeated race, not a generic merge refusal", () => {
+  // `f_mr_giveup` (transient merge-retry budget exhausted) routes into merge-esc-attempt with
+  // mergeState = "ready" AND mergeStatus = "retry". Without a dedicated branch this reused the
+  // generic gate-blocked ("Investigate why GitHub refused the merge") text, which is misleading for
+  // a repeated base/head-moved race whose retry budget simply ran out. The question must branch on
+  // mergeStatus = "retry" — ahead of the generic `mergeState = "ready"` arm — and name the budget.
+  assert(escAttempt, "merge-esc-attempt service task must exist");
+  const el = escAttempt![0];
+  assertStringIncludes(el, 'mergeStatus = "retry"', "must branch the retry-budget-exhausted escalation on mergeStatus = retry");
+  assertStringIncludes(el, "mergeRetryMax", "the retry-exhausted question must surface the retry budget");
+  // The retry branch must precede the generic `mergeState = "ready"` branch, or the generic arm
+  // (also true here) would shadow it and re-emit the misleading refusal text.
+  const retryIdx = el.indexOf('mergeStatus = "retry"');
+  const readyIdx = el.indexOf('mergeState = "ready"');
+  assert(retryIdx !== -1 && readyIdx !== -1 && retryIdx < readyIdx, "the retry branch must be evaluated before the generic ready branch");
+});
+
 test("a gw-merge-escalated guard honours persist-escalation's escalated:false (mirrors the convergence loop)", () => {
   // The escalation output no longer flows UNCONDITIONALLY into the durable answer wait: it passes
   // through a gateway that reads the worker's `escalated` output.

package/app/mergeRetry.test.ts

@@ -0,0 +1,90 @@
+// Unit tests for the transient merge-race classification (issue #334).
+//
+// #334: a GitHub-flagged *retryable* merge race — the base (or head) branch advanced between the
+// mergeability read and the merge mutation, so GitHub aborted with "… try the merge again" — was
+// misclassified by `mergePr`'s catch-all as `blocked`, producing a misleading human escalation on
+// a PR that was actually mergeable once the base settled. The fix classifies the stable
+// base/head-moved messages as a new `retry` outcome (the merge loop re-attempts on the settled
+// base), while every genuine block (conflict / failing check / 403 perms / 422 not-mergeable)
+// stays `blocked`. These tests pin that split so a real block is never swallowed as transient.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { isTransientMergeRace, mergePr } from "./github.ts";
+
+test("isTransientMergeRace: the base/head-moved races are transient", () => {
+  // GraphQL mergePullRequest error (observed live on nano-workforce #330).
+  assertEquals(
+    isTransientMergeRace(
+      "GraphQL: Base branch was modified. Review and try the merge again. (mergePullRequest)",
+    ),
+    true,
+  );
+  // The head-branch-moved sibling.
+  assertEquals(
+    isTransientMergeRace("Head branch was modified. Review and try the merge again."),
+    true,
+  );
+  // The HTTP 405 REST variant.
+  assertEquals(
+    isTransientMergeRace(
+      "github 405 Method Not Allowed: Base branch was modified. Review and try the merge again.",
+    ),
+    true,
+  );
+});
+
+test("isTransientMergeRace: genuine blocks are NOT transient (never swallowed)", () => {
+  assertEquals(isTransientMergeRace("Pull Request is not mergeable"), false); // conflict / failing check
+  assertEquals(isTransientMergeRace("github 403 Forbidden: Resource not accessible"), false); // perms
+  assertEquals(
+    isTransientMergeRace("github 422 Unprocessable Entity: Required status check is expected"),
+    false,
+  ); // not-mergeable gate
+  assertEquals(isTransientMergeRace("Merge conflict; base branch has conflicts"), false); // a base conflict is a real block
+});
+
+// Drive `mergePr`'s REST (token) transport: the 405 base-moved race must surface as `retry`, while
+// a genuine 405 refusal stays `blocked`.
+async function withMergePut(
+  status: number,
+  statusText: string,
+  body: string,
+  run: () => Promise<void>,
+): Promise<void> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = ((input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    if (/\/pulls\/\d+\/merge$/.test(url) && (init?.method ?? "").toUpperCase() === "PUT") {
+      return Promise.resolve(new Response(body, { status, statusText }));
+    }
+    return Promise.resolve(new Response("not found", { status: 404 }));
+  }) as typeof fetch;
+  try {
+    await run();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("mergePr: a 405 base-moved race → outcome 'retry'", async () => {
+  await withMergePut(
+    405,
+    "Method Not Allowed",
+    "Base branch was modified. Review and try the merge again.",
+    async () => {
+      const res = await mergePr("acme/widgets", 42, "test-token", { method: "squash", admin: false });
+      assertEquals(res?.outcome, "retry");
+    },
+  );
+});
+
+test("mergePr: a genuine 405 refusal → outcome 'blocked' (not swallowed as transient)", async () => {
+  await withMergePut(405, "Method Not Allowed", "Pull Request is not mergeable", async () => {
+    const res = await mergePr("acme/widgets", 42, "test-token", { method: "squash", admin: false });
+    assertEquals(res?.outcome, "blocked");
+  });
+});

package/app/mergeRetryArm.test.ts

@@ -0,0 +1,100 @@
+// Structural regression guard for the merge-loop transient-retry arm (issue #334).
+//
+// #334: a transient, GitHub-flagged-retryable merge race ("Base branch was modified. Review and
+// try the merge again.") was mapped to `blocked` → a decision-required human escalation on a PR
+// that was actually mergeable once the base settled. The fix adds a `retry` merge outcome that
+// re-enters the merge loop on the settled base through a *bounded* budget gate — mirroring the
+// `gw-ci-fix` within-budget / budget-exhausted pattern — WITHOUT any remediation agent, and
+// escalates via the existing `merge-esc-attempt` only when the retry budget is exhausted (so a
+// continuously-moving base still escalates promptly rather than spinning forever).
+//
+// This test asserts the arm's topology on the committed model so it cannot regress silently. It is
+// a pure text assertion over the BPMN (no engine), matching the repo's lightweight model-guard style.
+
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+
+const bpmn = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+function hasFlow(source: string, target: string): boolean {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*\\bsourceRef="${source}"[^>]*\\btargetRef="${target}"|` +
+      `<bpmn:sequenceFlow\\b[^>]*\\btargetRef="${target}"[^>]*\\bsourceRef="${source}"`,
+  );
+  return re.test(flat);
+}
+
+function flowHasId(id: string, source: string, target: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:sequenceFlow\\b[^>]*\\bid="${id}"[^>]*/?>`));
+  if (!m) return false;
+  const tag = m[0];
+  return tag.includes(`sourceRef="${source}"`) && tag.includes(`targetRef="${target}"`);
+}
+
+function gatewayDefault(id: string, def: string): boolean {
+  const m = flat.match(new RegExp(`<bpmn:exclusiveGateway\\b[^>]*\\bid="${id}"[^>]*>`));
+  if (!m) return false;
+  return m[0].includes(`default="${def}"`);
+}
+
+// Assert the conditionExpression *of a specific sequenceFlow* contains `needle`, so the guard
+// cannot be satisfied by the same substring appearing on an unrelated flow (e.g. the
+// merge-esc-attempt question FEEL also mentions `mergeStatus = "retry"`).
+function flowHasCondition(id: string, needle: string): boolean {
+  const m = flat.match(
+    new RegExp(`<bpmn:sequenceFlow\\b[^>]*\\bid="${id}"[^>]*>(.*?)</bpmn:sequenceFlow>`),
+  );
+  if (!m) return false;
+  const cond = m[1].match(/<bpmn:conditionExpression\b[^>]*>(.*?)<\/bpmn:conditionExpression>/);
+  return cond ? cond[1].includes(needle) : false;
+}
+
+test("gw-merge routes the retry outcome to a dedicated budget gate, not to a human", () => {
+  // A `retry` merge result must reach the retry-budget gate…
+  assert(hasFlow("gw-merge", "gw-merge-retry"), "gw-merge → gw-merge-retry (retry) missing");
+  // …guarded by the exact retry condition (mergeStatus = "retry").
+  assert(flowHasId("f_m_gRetry", "gw-merge", "gw-merge-retry"), "f_m_gRetry must be gw-merge → gw-merge-retry");
+  // Assert the retry condition on f_m_gRetry ITSELF — not merely anywhere in the model — so the
+  // guard cannot be satisfied by the identical substring in the merge-esc-attempt question FEEL.
+  assert(
+    flowHasCondition("f_m_gRetry", 'mergeStatus = "retry"'),
+    'f_m_gRetry conditionExpression must be mergeStatus = "retry"',
+  );
+});
+
+test("retry arm mirrors the fix-ci arm: budget gate → re-arm, exhausted → escalate", () => {
+  // Within budget → re-arm the merge poller (re-attempt on the settled base). No remediation agent.
+  assert(hasFlow("gw-merge-retry", "arm-merge"), "gw-merge-retry → arm-merge (within budget) missing");
+  assert(flowHasId("f_mr_go", "gw-merge-retry", "arm-merge"), "f_mr_go must be gw-merge-retry → arm-merge");
+  assertStringIncludes(flat, "mergeRetryRound &lt;= mergeRetryMax");
+
+  // Budget exhausted → the EXISTING human escalation (merge-esc-attempt), and it is the gateway default
+  // so a continuously-moving base can never spin past the cap.
+  assert(
+    hasFlow("gw-merge-retry", "merge-esc-attempt"),
+    "gw-merge-retry → merge-esc-attempt (budget exhausted) missing",
+  );
+  assert(gatewayDefault("gw-merge-retry", "f_mr_giveup"), "gw-merge-retry must default to f_mr_giveup");
+  assert(
+    flowHasId("f_mr_giveup", "gw-merge-retry", "merge-esc-attempt"),
+    "f_mr_giveup must default gw-merge-retry → merge-esc-attempt",
+  );
+});
+
+test("the retry arm advances the attempt counter only on a transient retry outcome", () => {
+  // The counter advances ONLY when the merge attempt returned `retry` — mirroring how fix-ci/rebase
+  // advance their own rounds only on their own remediation — so unrelated merge attempts (initial,
+  // post-rebase, post-fix-ci, post-evict) can't consume the transient-retry budget. N consecutive
+  // transient races then trip the `mergeRetryRound <= mergeRetryMax` gate at exactly the cap.
+  assertStringIncludes(flat, "=if mergeStatus = &#34;retry&#34; then mergeRetryRound + 1 else mergeRetryRound");
+});
+
+test("the retry arm has NO remediation agent (contrast the conflict/rebase arm)", () => {
+  // The base-moved race needs only a re-attempt on the settled base — no rebase/CI-fix agent. The
+  // within-budget flow goes straight back to arm-merge, never through a `senior:*` task.
+  assert(flowHasId("f_mr_go", "gw-merge-retry", "arm-merge"), "retry within-budget must go directly to arm-merge");
+  // Sanity: the untouched blocked path still escalates directly (a genuine refusal is unchanged).
+  assert(flowHasId("f_m_gBlocked", "gw-merge", "merge-esc-attempt"), "blocked → merge-esc-attempt must remain");
+});

package/app/readiness.ts

@@ -150,6 +150,14 @@ export const DEFAULT_ATTEMPT_TIMEOUT_MS = 60_000;
 /** Default gate timeout when neither the descriptor nor `NANO_READINESS_POLL_TIMEOUT` supplies one. */
 export const DEFAULT_READINESS_TIMEOUT = "PT30M";
 
+/** The ONE canonical readiness-signal message the wait-gate correlates on to release the wait
+ * (ADR 0001 §2) — the correlation key is per-caller (`=gateKey` for the in-flow probe worker,
+ * `=prKey` for the review-ready wait), not a single fixed key. Both the in-flow probe worker
+ * (`pr.readiness-probe`) and the out-of-band
+ * poller-correlated shape used by the review-ready migration (#259, per #258 pinned decision 3)
+ * publish under this ONE name — so there is a single "wait for the world" message, no bespoke twin. */
+export const READINESS_READY_MESSAGE = "readiness-ready";
+
 const str = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : String(v));
 const num = (v: unknown): number | undefined =>
   typeof v === "number" && Number.isFinite(v) ? v : undefined;

package/app/reviewReadinessGate.test.ts

@@ -0,0 +1,92 @@
+// Structural guard for the review-ready wait re-expressed on the canonical ReadinessProbe
+// wait-gate contract (ADR 0001 §2, issue #259).
+//
+// #258 landed the generic durable wait-gate: an event-based gateway racing a canonical
+// `readiness-ready` signal against a bounded timer that escalates. #259 collapses nwf's bespoke
+// review-ready poll path onto that ONE primitive — so there is a single "wait for the world"
+// message, no drift-prone twin. The out-of-band poller-correlated shape (#258 pinned decision 3)
+// keeps the canonical self-scheduling poller (`pollReviews` in app/service.ts) publishing the
+// signal when a fresh review lands, while the convergence-loop parks on the canonical gate.
+//
+// These pure text assertions over the committed BPMN lock the migrated wait: it now catches the
+// canonical `readiness-ready` message (the bespoke `review-ready` message is GONE), and it stays
+// BOUNDED — the event-based gateway still races the signal against the `reviewWaitTimeout` timer,
+// whose arm escalates to a human. Matches the repo's model-guard style (see roundResultDefault.test.ts).
+
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { READINESS_READY_MESSAGE } from "./readiness.ts";
+
+const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+test("the review wait catches the canonical readiness-ready message, not a bespoke twin", () => {
+  // The one canonical wait-gate signal (#258), re-used here — no separate `review-ready` message.
+  const msg = flat.match(/<bpmn:message\b[^>]*\bname="readiness-ready"[\s\S]*?<\/bpmn:message>/);
+  assert(msg, "convergence-loop must declare the canonical readiness-ready message");
+  assertStringIncludes(msg![0], 'correlationKey="=prKey"', "correlation shape is preserved (=prKey)");
+
+  // The bespoke review-ready message/shape must be fully retired (one mechanism, no drift).
+  assert(!/name="review-ready"/.test(flat), "the bespoke review-ready message must be gone");
+  assert(!/id="Message_reviewReady"/.test(flat), "the bespoke Message_reviewReady must be gone");
+  assert(!/id="ReviewReady"/.test(flat), "the bespoke ReviewReady payload shape must be gone");
+
+  // And the constant the poller publishes under is the very same canonical name.
+  assert(new RegExp(`name="${READINESS_READY_MESSAGE}"`).test(flat), "message name matches the canonical constant");
+});
+
+test("the review-ready catch subscribes to the canonical readiness-ready message", () => {
+  const wait = flat.match(/<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-review"[\s\S]*?<\/bpmn:intermediateCatchEvent>/);
+  assert(wait, "the wait-review catch event must exist");
+  assertStringIncludes(
+    wait![0],
+    'messageRef="Message_readinessReady"',
+    "wait-review must catch the canonical readiness-ready message",
+  );
+  // The round increment (forward progress) is preserved on the same catch.
+  assertStringIncludes(wait![0], 'target="round"', "wait-review still advances the round on a fresh signal");
+});
+
+test("the migrated wait stays bounded: an event-based gateway races the signal against a timer", () => {
+  // The gate shape from #258: an event-based gateway forks to the signal catch and a timer catch.
+  const gw = flat.match(/<bpmn:eventBasedGateway\b[^>]*\bid="gw-review-wait"[^>]*>/);
+  assert(gw, "the review wait must be an event-based gateway race (bounded gate)");
+
+  const timeout = flat.match(
+    /<bpmn:intermediateCatchEvent\b[^>]*\bid="wait-review-timeout"[\s\S]*?<\/bpmn:intermediateCatchEvent>/,
+  );
+  assert(timeout, "the bounded timer arm (wait-review-timeout) must exist");
+  assertStringIncludes(timeout![0], "<bpmn:timerEventDefinition", "the timer arm bounds the wait");
+  assertStringIncludes(timeout![0], "=reviewWaitTimeout", "the timer is seeded with the review-wait timeout");
+
+  // The gateway forks to BOTH the signal catch and the timer catch (the race).
+  assert(
+    /sourceRef="gw-review-wait"[^>]*targetRef="wait-review"|targetRef="wait-review"[^>]*sourceRef="gw-review-wait"/.test(
+      flat,
+    ),
+    "the gateway races toward the readiness signal catch",
+  );
+  assert(
+    /sourceRef="gw-review-wait"[^>]*targetRef="wait-review-timeout"|targetRef="wait-review-timeout"[^>]*sourceRef="gw-review-wait"/.test(
+      flat,
+    ),
+    "the gateway races toward the bounded timer catch",
+  );
+});
+
+test("the timeout arm escalates to a human (the wait cannot hang forever)", () => {
+  // timer catch → persist-review-stalled (records the escalation) → wait-answer (native userTask).
+  assert(
+    /sourceRef="wait-review-timeout"[^>]*targetRef="persist-review-stalled"|targetRef="persist-review-stalled"[^>]*sourceRef="wait-review-timeout"/.test(
+      flat,
+    ),
+    "a timed-out review wait routes to the stalled-review escalation",
+  );
+  assert(
+    /sourceRef="persist-review-stalled"[^>]*targetRef="wait-answer"|targetRef="wait-answer"[^>]*sourceRef="persist-review-stalled"/.test(
+      flat,
+    ),
+    "the stalled-review escalation parks on the human answer userTask",
+  );
+});

package/app/reviewWait.ts

@@ -5,7 +5,7 @@
 //
 // Two knobs govern the review-wait watchdog:
 //   • the *timeout* — an ISO-8601 duration handed to the process's `wait-review-timeout` timer
-//     catch (the far side of the event-based-gateway race against `review-ready`). If no fresh
+//     catch (the far side of the event-based-gateway race against `readiness-ready`). If no fresh
 //     review arrives within it, the loop escalates to a human instead of hanging forever.
 //   • the *nudge cooldown* — how long the poller waits between automatic Copilot re-requests for
 //     one waiting PR, so a re-request that Copilot dismisses is retried without hammering the API.

package/app/service.ts

@@ -54,7 +54,14 @@ import {
   planTasks,
 } from "./plan.ts";
 import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
-import { defaultProbeExec, type ProbeExec, probeOnce, type ReadinessProbe, readinessTimeout } from "./readiness.ts";
+import {
+  defaultProbeExec,
+  type ProbeExec,
+  probeOnce,
+  READINESS_READY_MESSAGE,
+  type ReadinessProbe,
+  readinessTimeout,
+} from "./readiness.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
@@ -104,6 +111,14 @@ export const MAX_CI_FIX_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_CI_FIX
  * immediately). Reuses the CI-fix budget clamp (allows 0 = disable, ceiling-capped). */
 export const MAX_REBASE_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_REBASE_ROUNDS, 3);
 
+/** How many times the merge stage will re-attempt a merge that GitHub aborted with a *transient*
+ * base/head-moved race (see `isTransientMergeRace`) before giving up and escalating to a human.
+ * The re-attempt runs on the settled base (no remediation agent); the cap keeps a continuously
+ * moving base — or a persistently-failing merge — from spinning forever, escalating within
+ * seconds-to-minutes instead. Default 5; set `NANO_PR_MAX_MERGE_RETRIES=0` to disable transient
+ * retry (a race escalates immediately). Reuses the CI-fix budget clamp (allows 0 = disable). */
+export const MAX_MERGE_RETRIES = clampCiFixBudget(process.env.NANO_PR_MAX_MERGE_RETRIES, 5);
+
 /** How long a merge-loop AGENT service task (rebase / fix-ci) may sit without completing before its
  * interrupting timer boundary fires and the PR escalates for human attention. Seeded as the
  * `agentSlaTimeout` process variable at merge start and evaluated by those tasks' boundary timers.
@@ -577,6 +592,8 @@ export async function startMerge(
       ciFixMax: MAX_CI_FIX_ROUNDS,
       rebaseRound: 0,
       rebaseMax: MAX_REBASE_ROUNDS,
+      mergeRetryRound: 0,
+      mergeRetryMax: MAX_MERGE_RETRIES,
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
       // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
       rootRequestKey,
@@ -658,7 +675,17 @@ export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
 
 /** One review-ready poll pass (SPEC §10): for every PR waiting on a review, fetch its GitHub
  * reviews (via the host `gh` CLI or a token — see `app/github.ts`) and, on a fresh one,
- * correlate a `review-ready` message to resume the loop. */
+ * correlate the canonical `readiness-ready` message to resume the loop.
+ *
+ * This is the review-ready wait re-expressed on the ONE `ReadinessProbe` wait-gate contract
+ * (ADR 0001 §2, issue #259): the convergence-loop parks on the canonical `readiness-ready` gate
+ * (event-based gateway racing the signal against the bounded `reviewWaitTimeout` timer), and this
+ * canonical self-scheduling poller publishes that signal out-of-band when a fresh review lands —
+ * the "out-of-band poller-correlated shape" #258 pinned decision 3 reserved for exactly this
+ * migration. There is no bespoke `review-ready` message any more: one mechanism, no drift. The
+ * fresh-review detection + Copilot nudge below stay here because review freshness is inherently
+ * STATEFUL (keyed off `last_review_id`/`waiting_since`), which the stateless probe matchers cannot
+ * subsume — the poller owns the forward-progress guarantee, the gate owns the bounded wait. */
 async function pollReviews(data: DataLayer, engine: EngineClient, token: string) {
   const waiting = await prs(data).find({ status: "waiting_review" });
   for (const pr of waiting) {
@@ -682,9 +709,12 @@ async function pollReviews(data: DataLayer, engine: EngineClient, token: string)
       }
       await prs(data).update(prKey, { last_review_id: fresh.id, status: "converging", updated_at: now() });
       await engine.publishMessage({
-        name: "review-ready",
+        name: READINESS_READY_MESSAGE,
         correlationKey: prKey,
-        variables: { reviewId: fresh.id, reviewState: fresh.state, submittedAt: fresh.submitted_at },
+        // The canonical readiness-signal payload (`ReadinessReady` shape): the gate only needs to
+        // know the probe went green. The fresh review's id/state is bookkept above on the PR row,
+        // not carried on the message — the convergence-loop consumes only the round increment.
+        variables: { ready: true, detail: `review ${fresh.id} (${fresh.state})` },
       });
       console.log(`[poller] review ${fresh.id} (${fresh.state}) -> ${prKey}`);
     } catch (err) {

package/main.ts

@@ -9,7 +9,8 @@
 //     control endpoints plus the webhook operations under `/app/api/hooks/*` (ADR 0059).
 //
 // The only thing that isn't declarative is the review-ready poller: it does arbitrary GitHub
-// polling and then correlates a `review-ready` message. A cron trigger can only fire an engine
+// polling and then correlates the canonical `readiness-ready` wait-gate message (#259). A cron
+// trigger can only fire an engine
 // start/message action, not this custom I/O glue, so it stays app-side here — driving the same
 // engine client the runtime uses, over `app.data`.
 //
@@ -89,7 +90,7 @@ if (httpServer instanceof Server) {
 }
 
 // Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
-// overlap two passes (which could double-signal `review-ready`); the next pass is scheduled
+// overlap two passes (which could double-signal `readiness-ready`); the next pass is scheduled
 // only after the previous one settles.
 let shuttingDown = false;
 let pollTimer: ReturnType<typeof setTimeout> | null = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.98.0",
+  "version": "0.99.0",
   "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",

package/resources/processes/convergence-loop.bpmn

@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:nano="https://nanobpm.io/schema/shapes/1.0" id="Definitions_nano_workforce" targetNamespace="http://nanobpm.io/nano-workforce">
-  <bpmn:message id="Message_reviewReady" name="review-ready">
+  <bpmn:message id="Message_readinessReady" name="readiness-ready">
     <bpmn:extensionElements>
       <zeebe:subscription correlationKey="=prKey" />
       <zeebe:properties>
-        <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReviewReady" />
+        <zeebe:property name="io.nanobpm.dataEnvelope.in" value="ReadinessReady" />
       </zeebe:properties>
     </bpmn:extensionElements>
   </bpmn:message>
@@ -82,11 +82,6 @@
           <nano:extend name="convergeOnly" type="boolean" optional="true" />
           <nano:extend name="abandonUrl" type="string" optional="true" />
         </nano:shape>
-        <nano:shape id="ReviewReady" name="review-ready message payload">
-          <nano:extend name="reviewId" type="integer" />
-          <nano:extend name="reviewState" type="string" />
-          <nano:extend name="submittedAt" type="datetime" optional="true" />
-        </nano:shape>
       </nano:shapes>
     </bpmn:extensionElements>
     <bpmn:startEvent id="Start" name="PR submitted">
@@ -181,7 +176,7 @@
       </bpmn:extensionElements>
       <bpmn:incoming>f_toReviewWait</bpmn:incoming>
       <bpmn:outgoing>f_reviewLoop</bpmn:outgoing>
-      <bpmn:messageEventDefinition id="med_reviewReady" messageRef="Message_reviewReady" />
+      <bpmn:messageEventDefinition id="med_readinessReady" messageRef="Message_readinessReady" />
     </bpmn:intermediateCatchEvent>
     <bpmn:intermediateCatchEvent id="wait-review-timeout" name="Wait: review timeout">
       <bpmn:incoming>f_toReviewTimeout</bpmn:incoming>

package/resources/processes/merge-loop.bpmn

@@ -106,6 +106,7 @@
       <bpmn:incoming>f_reb_rebased</bpmn:incoming>
       <bpmn:incoming>f_m_evicted</bpmn:incoming>
       <bpmn:incoming>f_m_escReenter</bpmn:incoming>
+      <bpmn:incoming>f_mr_go</bpmn:incoming>
       <bpmn:outgoing>f_m_arm</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:intermediateCatchEvent id="wait-mergeable" name="Wait: mergeable">
@@ -127,6 +128,9 @@
           <zeebe:property name="io.nanobpm.dataEnvelope.in" value="MergeAttemptIn" />
           <zeebe:property name="io.nanobpm.dataEnvelope.out" value="MergeAttemptOut" />
         </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:output source="=if mergeStatus = &#34;retry&#34; then mergeRetryRound + 1 else mergeRetryRound" target="mergeRetryRound" />
+        </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_m_mReady</bpmn:incoming>
       <bpmn:outgoing>f_m_attempt</bpmn:outgoing>
@@ -135,8 +139,14 @@
       <bpmn:incoming>f_m_attempt</bpmn:incoming>
       <bpmn:outgoing>f_m_gMerged</bpmn:outgoing>
       <bpmn:outgoing>f_m_gQueued</bpmn:outgoing>
+      <bpmn:outgoing>f_m_gRetry</bpmn:outgoing>
       <bpmn:outgoing>f_m_gBlocked</bpmn:outgoing>
     </bpmn:exclusiveGateway>
+    <bpmn:exclusiveGateway id="gw-merge-retry" name="retry within budget?" default="f_mr_giveup">
+      <bpmn:incoming>f_m_gRetry</bpmn:incoming>
+      <bpmn:outgoing>f_mr_go</bpmn:outgoing>
+      <bpmn:outgoing>f_mr_giveup</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
     <bpmn:eventBasedGateway id="eg-landed" name="landed or evicted?">
       <bpmn:incoming>f_m_gQueued</bpmn:incoming>
       <bpmn:outgoing>f_eg_landed</bpmn:outgoing>
@@ -193,7 +203,7 @@
         </zeebe:properties>
         <zeebe:ioMapping>
           <zeebe:input source="=status" target="agentVerdict" />
-          <zeebe:input source="=&#34;This PR cannot be merged and needs a human decision. &#34; + (if mergeState = &#34;conflict&#34; then &#34;The automated rebase agent could not resolve the merge conflicts on this branch. Resolve them manually (or reply with guidance), then reply to retry.&#34; else if mergeState = &#34;ready&#34; then &#34;The merge attempt did not land (merge result: &#34; + mergeStatus + &#34;). Investigate why GitHub refused the merge, then reply to retry.&#34; else if agentVerdict = &#34;blocked&#34; then &#34;The automated CI-fix agent could not make the required checks green. Fix the failing checks on the branch (or reply with guidance), then reply to retry.&#34; else &#34;The automated CI-fix agent exceeded its time budget (SLA) before the required checks went green. Check its progress or intervene, then reply to retry.&#34;)" target="question" />
+          <zeebe:input source="=&#34;This PR cannot be merged and needs a human decision. &#34; + (if mergeState = &#34;conflict&#34; then &#34;The automated rebase agent could not resolve the merge conflicts on this branch. Resolve them manually (or reply with guidance), then reply to retry.&#34; else if mergeStatus = &#34;retry&#34; then &#34;The merge kept losing a race with concurrent updates to the base branch and exhausted its automatic retry budget (&#34; + string(mergeRetryMax) + &#34; retries). This is a repeated transient race, not a conflict, failing check, or permissions block. Reply to retry, or investigate why the base branch keeps moving.&#34; else if mergeState = &#34;ready&#34; then &#34;The merge attempt did not land (merge result: &#34; + mergeStatus + &#34;). Investigate why GitHub refused the merge, then reply to retry.&#34; else if agentVerdict = &#34;blocked&#34; then &#34;The automated CI-fix agent could not make the required checks green. Fix the failing checks on the branch (or reply with guidance), then reply to retry.&#34; else &#34;The automated CI-fix agent exceeded its time budget (SLA) before the required checks went green. Check its progress or intervene, then reply to retry.&#34;)" target="question" />
           <zeebe:input source="=&#34;blocked&#34;" target="status" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
@@ -201,6 +211,7 @@
       <bpmn:incoming>f_ci_blocked</bpmn:incoming>
       <bpmn:incoming>f_reb_blocked</bpmn:incoming>
       <bpmn:incoming>f_ci_sla</bpmn:incoming>
+      <bpmn:incoming>f_mr_giveup</bpmn:incoming>
       <bpmn:outgoing>f_m_escA</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:exclusiveGateway id="gw-merge-escalated" name="escalation opened?" default="f_m_escReenter">
@@ -370,6 +381,13 @@
     <bpmn:sequenceFlow id="f_m_gQueued" name="queued" sourceRef="gw-merge" targetRef="eg-landed">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStatus = "queued"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_m_gRetry" name="retry (base moved)" sourceRef="gw-merge" targetRef="gw-merge-retry">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStatus = "retry"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_mr_go" name="within budget" sourceRef="gw-merge-retry" targetRef="arm-merge">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeRetryRound &lt;= mergeRetryMax</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_mr_giveup" name="budget exhausted" sourceRef="gw-merge-retry" targetRef="merge-esc-attempt" />
     <bpmn:sequenceFlow id="f_eg_landed" sourceRef="eg-landed" targetRef="wait-landed" />
     <bpmn:sequenceFlow id="f_eg_evicted" sourceRef="eg-landed" targetRef="wait-evicted" />
     <bpmn:sequenceFlow id="f_m_evicted" sourceRef="wait-evicted" targetRef="arm-merge" />
@@ -425,6 +443,12 @@
           <dc:Bounds x="1022" y="150" width="53" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-merge-retry" bpmnElement="gw-merge-retry" isMarkerVisible="true">
+        <dc:Bounds x="1263" y="1215" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1344" y="1250" width="88" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_eg-landed" bpmnElement="eg-landed" isMarkerVisible="true">
         <dc:Bounds x="1263" y="255" width="50" height="50" />
         <bpmndi:BPMNLabel>
@@ -453,27 +477,27 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-conflict" bpmnElement="merge-esc-conflict">
-        <dc:Bounds x="1238" y="1520" width="100" height="80" />
+        <dc:Bounds x="1238" y="1680" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-attempt" bpmnElement="merge-esc-attempt">
-        <dc:Bounds x="1438" y="1040" width="100" height="80" />
+        <dc:Bounds x="1438" y="1200" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-merge-escalated" bpmnElement="gw-merge-escalated" isMarkerVisible="true">
-        <dc:Bounds x="1663" y="1055" width="50" height="50" />
+        <dc:Bounds x="1663" y="1215" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1651" y="1022" width="74" height="28" />
+          <dc:Bounds x="1651" y="1182" width="74" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-merge-answer" bpmnElement="wait-merge-answer">
-        <dc:Bounds x="1838" y="1040" width="100" height="80" />
+        <dc:Bounds x="1838" y="1200" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-merge-answer" bpmnElement="record-merge-answer">
-        <dc:Bounds x="2038" y="1040" width="100" height="80" />
+        <dc:Bounds x="2038" y="1200" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-ci-fix" bpmnElement="gw-ci-fix" isMarkerVisible="true">
-        <dc:Bounds x="863" y="1535" width="50" height="50" />
+        <dc:Bounds x="863" y="1695" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="769" y="1553" width="89" height="14" />
+          <dc:Bounds x="769" y="1713" width="89" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_fix-ci" bpmnElement="fix-ci">
@@ -512,7 +536,7 @@
       <bpmndi:BPMNShape id="BPMNShape_be_rebase_sla" bpmnElement="be_rebase_sla">
         <dc:Bounds x="1070" y="942" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1046" y="1043" width="84" height="14" />
+          <dc:Bounds x="1046" y="1023" width="84" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_start" bpmnElement="f_m_start">
@@ -554,10 +578,10 @@
         <di:waypoint x="1870" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_giveup" bpmnElement="f_ci_giveup">
-        <di:waypoint x="913" y="1560" />
-        <di:waypoint x="1238" y="1560" />
+        <di:waypoint x="913" y="1720" />
+        <di:waypoint x="1238" y="1720" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1032" y="1527" width="67" height="28" />
+          <dc:Bounds x="1032" y="1687" width="67" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_reconcile" bpmnElement="f_ci_reconcile">
@@ -574,11 +598,11 @@
         <di:waypoint x="933" y="280" />
         <di:waypoint x="933" y="305" />
         <di:waypoint x="1333" y="305" />
-        <di:waypoint x="1333" y="1500" />
-        <di:waypoint x="1288" y="1500" />
-        <di:waypoint x="1288" y="1520" />
+        <di:waypoint x="1333" y="1660" />
+        <di:waypoint x="1288" y="1660" />
+        <di:waypoint x="1288" y="1680" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1338" y="1246" width="67" height="28" />
+          <dc:Bounds x="1338" y="1406" width="67" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_reconcile" bpmnElement="f_reb_reconcile">
@@ -590,6 +614,13 @@
           <dc:Bounds x="804" y="939" width="82" height="56" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_mr_giveup" bpmnElement="f_mr_giveup">
+        <di:waypoint x="1313" y="1240" />
+        <di:waypoint x="1438" y="1240" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1352" y="1307" width="67" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_eg_landed" bpmnElement="f_eg_landed">
         <di:waypoint x="1313" y="280" />
         <di:waypoint x="1470" y="280" />
@@ -600,40 +631,44 @@
         <di:waypoint x="1688" y="160" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escC" bpmnElement="f_m_escC">
-        <di:waypoint x="1338" y="1560" />
-        <di:waypoint x="1888" y="1560" />
-        <di:waypoint x="1888" y="1120" />
+        <di:waypoint x="1338" y="1720" />
+        <di:waypoint x="1888" y="1720" />
+        <di:waypoint x="1888" y="1280" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_escA" bpmnElement="f_m_escA">
+        <di:waypoint x="1538" y="1240" />
+        <di:waypoint x="1663" y="1240" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escReenter" bpmnElement="f_m_escReenter">
-        <di:waypoint x="1688" y="1105" />
-        <di:waypoint x="1688" y="1140" />
-        <di:waypoint x="402" y="1140" />
+        <di:waypoint x="1688" y="1265" />
+        <di:waypoint x="1688" y="1300" />
+        <di:waypoint x="402" y="1300" />
         <di:waypoint x="402" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1008" y="1093" width="74" height="42" />
+          <dc:Bounds x="1008" y="1305" width="74" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_answerRecord" bpmnElement="f_m_answerRecord">
-        <di:waypoint x="1938" y="1080" />
-        <di:waypoint x="2038" y="1080" />
+        <di:waypoint x="1938" y="1240" />
+        <di:waypoint x="2038" y="1240" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_answer" bpmnElement="f_m_answer">
-        <di:waypoint x="2088" y="1120" />
-        <di:waypoint x="2088" y="1140" />
-        <di:waypoint x="402" y="1140" />
+        <di:waypoint x="2088" y="1280" />
+        <di:waypoint x="2088" y="1300" />
+        <di:waypoint x="402" y="1300" />
         <di:waypoint x="402" y="160" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_mCiFix" bpmnElement="f_m_mCiFix">
         <di:waypoint x="713" y="145" />
         <di:waypoint x="713" y="318" />
         <di:waypoint x="1358" y="318" />
-        <di:waypoint x="1358" y="1020" />
-        <di:waypoint x="863" y="1020" />
-        <di:waypoint x="863" y="1515" />
-        <di:waypoint x="888" y="1515" />
-        <di:waypoint x="888" y="1535" />
+        <di:waypoint x="1358" y="1180" />
+        <di:waypoint x="863" y="1180" />
+        <di:waypoint x="863" y="1675" />
+        <di:waypoint x="888" y="1675" />
+        <di:waypoint x="888" y="1695" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="971" y="1025" width="60" height="42" />
+          <dc:Bounds x="1011" y="1133" width="60" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_mRebase" bpmnElement="f_m_mRebase">
@@ -648,33 +683,33 @@
         <di:waypoint x="713" y="145" />
         <di:waypoint x="713" y="318" />
         <di:waypoint x="1333" y="318" />
-        <di:waypoint x="1333" y="1020" />
-        <di:waypoint x="1218" y="1020" />
-        <di:waypoint x="1218" y="1540" />
-        <di:waypoint x="1238" y="1540" />
+        <di:waypoint x="1333" y="1180" />
+        <di:waypoint x="1218" y="1180" />
+        <di:waypoint x="1218" y="1700" />
+        <di:waypoint x="1238" y="1700" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1243" y="702" width="85" height="14" />
+          <dc:Bounds x="1243" y="722" width="85" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_go" bpmnElement="f_ci_go">
-        <di:waypoint x="888" y="1585" />
-        <di:waypoint x="888" y="1605" />
-        <di:waypoint x="2158" y="1605" />
+        <di:waypoint x="888" y="1745" />
+        <di:waypoint x="888" y="1765" />
+        <di:waypoint x="2158" y="1765" />
         <di:waypoint x="2158" y="555" />
         <di:waypoint x="1018" y="555" />
         <di:waypoint x="1018" y="580" />
         <di:waypoint x="1038" y="580" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="2163" y="1066" width="49" height="28" />
+          <dc:Bounds x="2163" y="1146" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_blocked" bpmnElement="f_ci_blocked">
         <di:waypoint x="1313" y="600" />
         <di:waypoint x="1418" y="600" />
-        <di:waypoint x="1418" y="1080" />
-        <di:waypoint x="1438" y="1080" />
+        <di:waypoint x="1418" y="1240" />
+        <di:waypoint x="1438" y="1240" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1423" y="863" width="89" height="14" />
+          <dc:Bounds x="1423" y="853" width="89" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_wait" bpmnElement="f_ci_wait">
@@ -689,21 +724,23 @@
         <di:waypoint x="913" y="280" />
         <di:waypoint x="933" y="280" />
         <di:waypoint x="933" y="305" />
-        <di:waypoint x="1558" y="305" />
-        <di:waypoint x="1558" y="1125" />
-        <di:waypoint x="1418" y="1125" />
+        <di:waypoint x="1733" y="305" />
+        <di:waypoint x="1733" y="1660" />
+        <di:waypoint x="1243" y="1660" />
+        <di:waypoint x="1243" y="1195" />
+        <di:waypoint x="1418" y="1195" />
         <di:waypoint x="1418" y="875" />
         <di:waypoint x="1018" y="875" />
         <di:waypoint x="1018" y="900" />
         <di:waypoint x="1038" y="900" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1563" y="701" width="49" height="28" />
+          <dc:Bounds x="1248" y="1414" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_blocked" bpmnElement="f_reb_blocked">
         <di:waypoint x="1313" y="920" />
         <di:waypoint x="1488" y="920" />
-        <di:waypoint x="1488" y="1040" />
+        <di:waypoint x="1488" y="1200" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="1429" y="887" width="64" height="28" />
         </bpmndi:BPMNLabel>
@@ -724,6 +761,20 @@
           <dc:Bounds x="1093" y="206" width="46" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_gRetry" bpmnElement="f_m_gRetry">
+        <di:waypoint x="1088" y="95" />
+        <di:waypoint x="1088" y="75" />
+        <di:waypoint x="1926" y="75" />
+        <di:waypoint x="1926" y="318" />
+        <di:waypoint x="1643" y="318" />
+        <di:waypoint x="1643" y="1285" />
+        <di:waypoint x="1263" y="1285" />
+        <di:waypoint x="1288" y="1285" />
+        <di:waypoint x="1288" y="1265" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1746" y="285" width="78" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_eg_evicted" bpmnElement="f_eg_evicted">
         <di:waypoint x="1288" y="305" />
         <di:waypoint x="1288" y="440" />
@@ -735,10 +786,10 @@
         <di:waypoint x="1926" y="75" />
         <di:waypoint x="1926" y="820" />
         <di:waypoint x="1418" y="820" />
-        <di:waypoint x="1418" y="1060" />
-        <di:waypoint x="1438" y="1060" />
+        <di:waypoint x="1418" y="1220" />
+        <di:waypoint x="1438" y="1220" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1931" y="441" width="53" height="14" />
+          <dc:Bounds x="1931" y="562" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_done" bpmnElement="f_ci_done">
@@ -749,20 +800,16 @@
         <di:waypoint x="1138" y="920" />
         <di:waypoint x="1263" y="920" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_m_escA" bpmnElement="f_m_escA">
-        <di:waypoint x="1538" y="1080" />
-        <di:waypoint x="1663" y="1080" />
-      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escWait" bpmnElement="f_m_escWait">
-        <di:waypoint x="1713" y="1080" />
-        <di:waypoint x="1838" y="1080" />
+        <di:waypoint x="1713" y="1240" />
+        <di:waypoint x="1838" y="1240" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_sla" bpmnElement="f_reb_sla">
         <di:waypoint x="1088" y="978" />
         <di:waypoint x="1088" y="998" />
         <di:waypoint x="1218" y="998" />
-        <di:waypoint x="1218" y="1560" />
-        <di:waypoint x="1238" y="1560" />
+        <di:waypoint x="1218" y="1720" />
+        <di:waypoint x="1238" y="1720" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="1118" y="965" width="70" height="28" />
         </bpmndi:BPMNLabel>
@@ -772,12 +819,12 @@
         <di:waypoint x="1088" y="678" />
         <di:waypoint x="1018" y="678" />
         <di:waypoint x="1018" y="540" />
-        <di:waypoint x="1618" y="540" />
-        <di:waypoint x="1618" y="820" />
+        <di:waypoint x="1558" y="540" />
+        <di:waypoint x="1558" y="820" />
         <di:waypoint x="1526" y="820" />
-        <di:waypoint x="1526" y="1040" />
+        <di:waypoint x="1526" y="1200" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1243" y="507" width="70" height="28" />
+          <dc:Bounds x="1253" y="507" width="70" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_fixed" bpmnElement="f_ci_fixed">
@@ -795,7 +842,7 @@
         <di:waypoint x="402" y="1000" />
         <di:waypoint x="402" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="799" y="1008" width="53" height="14" />
+          <dc:Bounds x="819" y="1008" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_dep_rewait" bpmnElement="f_dep_rewait">
@@ -804,6 +851,15 @@
         <di:waypoint x="234" y="820" />
         <di:waypoint x="234" y="138" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_mr_go" bpmnElement="f_mr_go">
+        <di:waypoint x="1288" y="1265" />
+        <di:waypoint x="1288" y="1285" />
+        <di:waypoint x="402" y="1285" />
+        <di:waypoint x="402" y="160" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="808" y="1252" width="49" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_evicted" bpmnElement="f_m_evicted">
         <di:waypoint x="1488" y="458" />
         <di:waypoint x="1488" y="478" />

package/workers/merge/worker.test.ts

@@ -207,3 +207,41 @@ test("pr.merge routes a refused merge through the blocked branch (escalation pay
     },
   );
 });
+
+test("pr.merge routes a transient base-moved race through the retry branch (no escalation payload)", async () => {
+  // #334: GitHub aborts the merge PUT with the 405 "Base branch was modified. Review and try the
+  // merge again." race. `mergePr` classifies it as `retry` (not `blocked`), and the retry arm of
+  // `matchTags` returns ONLY the loop-terminal `mergeStatus` — no `status`/`question` escalation
+  // payload — so the model re-attempts on the settled base instead of paging a human.
+  await withGithub(
+    (url) => {
+      if (/\/pulls\/\d+\/merge$/.test(url))
+        return new Response("Base branch was modified. Review and try the merge again.", {
+          status: 405,
+          statusText: "Method Not Allowed",
+        });
+      if (/\/pulls\/\d+$/.test(url)) return new Response(JSON.stringify({ merged: false, mergeable_state: "clean" }));
+      return null; // no AGENTS.md / merge-protocol.json → DEFAULT gh-merge protocol
+    },
+    async (calls) => {
+      const { app, stores } = fakeApp();
+      const out = (await handler(
+        { variables: { prKey: "acme/widgets#11", repo: "acme/widgets", prNumber: 11 } } as any,
+        app,
+      )) as Record<string, unknown>;
+
+      // Retry arm: transient — surfaces the loop-terminal `mergeStatus` only, NO escalation fields.
+      assertEquals(out, { mergeStatus: "retry" });
+      assertEquals(out.status, undefined);
+      assertEquals(out.question, undefined);
+
+      // Attempted a real merge PUT and recorded the retry audit row (not a swallowed block).
+      assertEquals(
+        calls.some((c) => /\/pulls\/\d+\/merge$/.test(c.url) && c.method === "PUT"),
+        true,
+      );
+      assertEquals(stores.merges.length, 1);
+      assertEquals(stores.merges[0].outcome, "retry");
+    },
+  );
+});

package/workers/merge/worker.ts

@@ -1,6 +1,8 @@
 // pr.merge — attempt to land the PR (SPEC §11). Returns `mergeStatus`:
 //   • merged  — landed now (direct merge)            → process marks it merged
 //   • queued  — added to the repo's merge queue       → process waits for `merge-landed`
+//   • retry   — transient base/head-moved race        → process re-attempts on the settled base
+//               via the bounded retry gate (no human, no remediation agent)
 //   • blocked — GitHub refused (conflict / failing gate / perms) → escalate to a human, who
 //               resolves it and replies to retry (the process re-arms and re-polls).
 // HOW it lands is governed by the target repo's published merge protocol (#43): a `mergify-queue`
@@ -21,7 +23,7 @@ import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 type In = WorkerInputs["pr.merge"];
 
 interface Out extends Record<string, unknown> {
-  mergeStatus: "merged" | "queued" | "blocked";
+  mergeStatus: "merged" | "queued" | "blocked" | "retry";
   status?: string;
   question?: string;
 }
@@ -92,7 +94,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const protocol = await loadMergeProtocol(repo, token).catch(() => null);
   const method = protocol?.land.method ?? "gh-merge";
 
-  let outcome: "merged" | "queued" | "blocked";
+  let outcome: "merged" | "queued" | "blocked" | "retry";
   let detail: string;
   let auditMethod: string;
 
@@ -130,7 +132,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
 
   // Exhaustive dispatch on the land outcome. Modelled as a tagged value so
   // `matchTags` forces a handler for every case — adding a new outcome to the
-  // `"merged" | "queued" | "blocked"` union becomes a compile error here rather
+  // `"merged" | "queued" | "blocked" | "retry"` union becomes a compile error here rather
   // than silently falling through to the "blocked" branch.
   const docHint = protocol?.doc ? ` See the repo's merge protocol (${protocol.doc}).` : "";
   return await matchTags(tag(outcome, { detail }), {
@@ -142,6 +144,10 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       return { mergeStatus: "queued" };
     },
     merged: async () => ({ mergeStatus: "merged" }),
+    // retry → a transient base/head-moved race (GitHub told us to re-attempt). Re-enter the merge
+    // loop on the settled base via the model's bounded retry gate — NO human escalation, NO
+    // remediation agent. The gate caps the attempts so a continuously-moving base still escalates.
+    retry: async () => ({ mergeStatus: "retry" }),
     // blocked → hand the escalation machinery a concrete question.
     blocked: async (o) => ({
       mergeStatus: "blocked",

package/workers/readiness-probe/worker.ts

@@ -25,6 +25,7 @@ import {
   parseProbe,
   probeBudgetMs,
   probeOnce,
+  READINESS_READY_MESSAGE,
   type ReadinessProbe,
   redactTarget,
 } from "../../app/readiness.ts";
@@ -36,8 +37,11 @@ import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io
 type In = WorkerInputs["pr.readiness-probe"];
 type Out = WorkerOutputs["pr.readiness-probe"];
 
-/** The message the gate's event-based gateway correlates on `=gateKey` to release the wait. */
-export const READINESS_READY_MESSAGE = "readiness-ready";
+/** The message the gate's event-based gateway correlates on `=gateKey` to release the wait.
+ * Re-exported from the canonical source (`app/readiness.ts`) so the worker and every out-of-band
+ * publisher (the review-ready poller, #259) share ONE message name — no drift-prone local twin.
+ * Re-exports the binding already imported above rather than re-referencing the module. */
+export { READINESS_READY_MESSAGE };
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));