@nanobpm/nano-workforce 0.98.1 → 0.99.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.99.1](https://github.com/nanobpm/nano-workforce/compare/v0.99.0...v0.99.1) (2026-08-19)
+
+
+### Bug Fixes
+
+* **convergence-loop:** route every escalation arm through gw-escalated ([#333](https://github.com/nanobpm/nano-workforce/issues/333)) ([#340](https://github.com/nanobpm/nano-workforce/issues/340)) ([0ad7a5c](https://github.com/nanobpm/nano-workforce/commit/0ad7a5c08a659a0ca26dc48def8c024d21a3a53a)), closes [#329](https://github.com/nanobpm/nano-workforce/issues/329)
+
+# [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)
 
 

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/convergeGate.test.ts

@@ -467,11 +467,15 @@ test("gw-converge-gate default arm finalizes with no condition", () => {
   assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
 });
 
-test("the blocked-comments escalation lands on the human wait-answer task with an answerable escalation", () => {
-  const f = flowElement("f_blockedWait");
-  assert(f, "f_blockedWait flow missing");
+test("the blocked-comments escalation routes through gw-escalated toward an answerable wait-answer", () => {
+  // #333: previously this flowed UNCONDITIONALLY into wait-answer, so a blank convergeBlockReason
+  // (the question is mapped from that OPTIONAL variable) opened no escalation yet still parked a
+  // dead wait with a null question. It now routes through gw-escalated, which parks wait-answer
+  // only on a real escalation and otherwise re-enters the loop.
+  const f = flowElement("f_blockedGate");
+  assert(f, "f_blockedGate flow missing");
   assertStringIncludes(f, 'sourceRef="persist-escalation-blockedcomments"');
-  assertStringIncludes(f, 'targetRef="wait-answer"');
+  assertStringIncludes(f, 'targetRef="gw-escalated"');
   const task = flat.match(
     /<bpmn:serviceTask\b[^>]*\bid="persist-escalation-blockedcomments"[^>]*>.*?<\/bpmn:serviceTask>/,
   );

package/app/convergenceEscalationGuard.test.ts

@@ -0,0 +1,106 @@
+// Regression guard for the question-less convergence-loop escalation defect (issue #333).
+//
+// The convergence loop (`resources/processes/convergence-loop.bpmn`) has FIVE `persist-escalation`
+// service tasks, but only ONE — `persist-escalation` (the `f_escalate` agent-verdict arm) — was
+// routed through the `gw-escalated` gateway that honours the worker's `escalated` output. The other
+// four flowed UNCONDITIONALLY into the durable `wait-answer` user task:
+//
+//   • persist-escalation-noprogress      (no progress made this round)
+//   • persist-review-stalled             (review-wait timer fired)          ← wedged live
+//   • persist-escalation-blockedcomments (unaddressed review comments)
+//   • persist-escalation-maxrounds       (round cap reached)
+//
+// Per ADR 0002 §1 a blank question is a NON-escalation: `pr.persist-escalation` opens no row and
+// returns `escalated:false`. The `persist-escalation-blockedcomments` arm maps its question from the
+// OPTIONAL `convergeBlockReason` process variable, so a blank reason returned `escalated:false` yet
+// STILL parked a dead `wait-answer` — a durable answer-wait with no escalation and a `null` question,
+// surfaced on the merge-driving inbox with nothing for a human to answer (observed live on three
+// instances, issue #333).
+//
+// The fix (mirroring the merge loop's `gw-merge-escalated`, PR #331): route EVERY arm that can reach
+// `wait-answer` through the single `gw-escalated` guard, so a `persist-escalation` returning
+// `escalated:false` RE-ENTERS the loop (`gw-guard`) instead of parking a dead wait. This makes the
+// invariant structural — `wait-answer` is reachable ONLY from a `gw-escalated == true` edge, so a
+// "durable answer-wait with no escalation" is unrepresentable.
+//
+// These are pure text assertions over the committed BPMN (no engine), matching the repo's
+// lightweight model-guard style (see mergeEscalationQuestion.test.ts, mergeRebaseArm.test.ts).
+
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+import { readFileSync } from "node:fs";
+
+const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+// Collapse whitespace so attribute-order / line-wrapping churn doesn't make the assertions brittle.
+const flat = bpmn.replace(/\s+/g, " ");
+
+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}"`);
+}
+
+/** The <userTask> element for wait-answer, including its incoming flows. */
+const waitAnswer = flat.match(/<bpmn:userTask\b[^>]*\bid="wait-answer"[\s\S]*?<\/bpmn:userTask>/);
+
+// Every control-flow escalation arm and the gateway edge it must now route through.
+const ARMS: ReadonlyArray<{ task: string; gate: string }> = [
+  { task: "persist-escalation-noprogress", gate: "f_noprogressGate" },
+  { task: "persist-review-stalled", gate: "f_stalledGate" },
+  { task: "persist-escalation-blockedcomments", gate: "f_blockedGate" },
+  { task: "persist-escalation-maxrounds", gate: "f_maxGate" },
+];
+
+test("every persist-escalation arm routes through gw-escalated, not straight to wait-answer", () => {
+  for (const { task, gate } of ARMS) {
+    assert(
+      flowHasId(gate, task, "gw-escalated"),
+      `${task} must route through gw-escalated (flow ${gate}), not directly to wait-answer (the #333 defect)`,
+    );
+  }
+  // The agent-verdict arm already routed through the gate — keep it.
+  assert(flowHasId("f_escGate", "persist-escalation", "gw-escalated"), "persist-escalation must route through gw-escalated");
+});
+
+test("gw-escalated honours persist-escalation's escalated output for every arm", () => {
+  // escalated:true → park the native user task for a human to answer.
+  assert(flowHasId("f_escWait", "gw-escalated", "wait-answer"), "gw-escalated → wait-answer (escalated) missing");
+  const escWait = flat.match(/<bpmn:sequenceFlow[^>]*id="f_escWait"[\s\S]*?<\/bpmn:sequenceFlow>/);
+  assert(escWait, "f_escWait flow missing");
+  assertStringIncludes(escWait![0], "escalated = true", "the wait arm must be guarded by escalated = true");
+  // escalated:false (a non-escalation, e.g. a blank convergeBlockReason) → re-enter the loop, not a dead wait.
+  assert(gatewayDefault("gw-escalated", "f_escReenter"), "gw-escalated default must re-enter the loop");
+  assert(flowHasId("f_escReenter", "gw-escalated", "gw-guard"), "the non-escalation arm must re-enter via gw-guard, not park a wait");
+});
+
+test("wait-answer is reachable ONLY from the gw-escalated == true edge (structural invariant)", () => {
+  // The single most important guarantee of #333: a durable answer-wait with no escalation is
+  // unrepresentable because the ONLY edge into wait-answer is the guarded f_escWait.
+  assert(waitAnswer, "wait-answer user task must exist");
+  const incoming = [...waitAnswer![0].matchAll(/<bpmn:incoming>([^<]+)<\/bpmn:incoming>/g)].map((m) => m[1]);
+  assert(incoming.length === 1, `wait-answer must have exactly one incoming (the guarded f_escWait); found: ${incoming.join(", ")}`);
+  assert(incoming[0] === "f_escWait", `wait-answer's only incoming must be f_escWait; found ${incoming[0]}`);
+  // The retired dead-wait edges must be gone.
+  for (const dead of ["f_noprogressWait", "f_stalledWait", "f_blockedWait", "f_maxWait"]) {
+    assert(!flat.includes(`id="${dead}"`), `the dead-wait edge ${dead} must be removed`);
+  }
+});
+
+test("each control-flow arm still carries a non-blank, human-actionable question", () => {
+  // The guard closes the wedge, but a legitimate control-flow escalation must still open a real
+  // escalation with a concrete question. Assert each arm supplies status + question via ioMapping.
+  for (const { task } of ARMS) {
+    const raw = flat.match(new RegExp(`<bpmn:serviceTask\\b[^>]*\\bid="${task}"[\\s\\S]*?</bpmn:serviceTask>`));
+    assert(raw, `${task} service task must exist`);
+    const el = raw![0];
+    assertStringIncludes(el, 'target="status"', `${task} must set an explicit status`);
+    assertStringIncludes(el, 'target="question"', `${task} must set a question`);
+  }
+});

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. */

package/app/persist-escalation.test.ts

@@ -180,3 +180,35 @@ test("persist-escalation heals from the prKey when repo/prNumber are absent", as
     "the running agent's abandon token is preserved from abandonUrl, not re-minted",
   );
 });
+
+// #333 — the control-flow escalation arms (no-progress / review-stalled / unaddressed-comments /
+// max-rounds) each set an explicit `status="blocked"` + a concrete `question` via `zeebe:input`
+// (recordRound=false for the three that run after `persist-round`). They now route through
+// `gw-escalated`, which branches on the worker's `escalated` output. This pins the contract that
+// gateway depends on: a control-flow arm with a real question OPENS an escalation and returns
+// `escalated:true` + the (trimmed) question, so gw-escalated parks a wait carrying that question —
+// never a dead wait with a null question (the #333 defect).
+test("a control-flow arm with a concrete question opens an escalation gw-escalated can park", async () => {
+  const { app, inserts } = fakeApp();
+  const question = "No review arrived within the review-wait timeout (PT20M). A human must decide how to proceed.";
+  const job = { variables: { prKey: "o/r#5", round: 2, status: "blocked", question, recordRound: false } };
+  const out = await handler(job as any, app as any);
+  assertEquals((out as any).escalated, true, "a real control-flow escalation reports escalated:true");
+  assertEquals((out as any).question, question, "the question is returned for the wait-answer form");
+  assertEquals(inserts.escalations.length, 1, "an escalation row is opened");
+  assertEquals(inserts.rounds.length, 0, "recordRound=false suppresses a duplicate round row");
+});
+
+// #333 — conversely, the `persist-escalation-blockedcomments` arm maps its question from the
+// OPTIONAL `convergeBlockReason`. A blank reason is a NON-escalation: the worker opens nothing and
+// returns `escalated:false`, so gw-escalated's default RE-ENTERS the loop instead of parking a dead
+// `wait-answer` with a null question. This is the exact wedge the guard eliminates.
+test("a control-flow arm with a blank question opens nothing so gw-escalated re-enters", async () => {
+  const { app, inserts, updates } = fakeApp();
+  const job = { variables: { prKey: "o/r#5", round: 2, status: "blocked", question: "  ", recordRound: false } };
+  const out = await handler(job as any, app as any);
+  assertEquals((out as any).escalated, false, "a blank-reason arm reports escalated:false");
+  assertEquals((out as any).escalationId, null, "no escalation id is minted");
+  assertEquals(inserts.escalations.length, 0, "no dead escalation is fabricated");
+  assertEquals(updates.pull_requests?.length ?? 0, 0, "the PR is never flipped to escalated");
+});

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/roundProgress.test.ts

@@ -210,11 +210,14 @@ test("gw-progress default arm re-enters the review wait with no condition", () =
   assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
 });
 
-test("the no-progress escalation lands on the human wait-answer task", () => {
-  const f = flowElement("f_noprogressWait");
-  assert(f, "f_noprogressWait flow missing");
+test("the no-progress escalation routes through gw-escalated toward the human wait-answer task", () => {
+  // #333: the arm no longer flows UNCONDITIONALLY into wait-answer — it routes through the
+  // gw-escalated guard, which parks wait-answer only when the worker opened a real escalation
+  // (escalated=true) and otherwise re-enters the loop (never a dead wait with a null question).
+  const f = flowElement("f_noprogressGate");
+  assert(f, "f_noprogressGate flow missing");
   assertStringIncludes(f, 'sourceRef="persist-escalation-noprogress"');
-  assertStringIncludes(f, 'targetRef="wait-answer"');
+  assertStringIncludes(f, 'targetRef="gw-escalated"');
   // It opens a real, answerable escalation (blocked status + a concrete question) so it is never a
   // blank-question non-escalation that would wedge the token on the wait.
   const task = flat.match(

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 {
@@ -668,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) {
@@ -692,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.1",
+  "version": "0.99.1",
   "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">
@@ -166,7 +161,7 @@
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_noProgress</bpmn:incoming>
-      <bpmn:outgoing>f_noprogressWait</bpmn:outgoing>
+      <bpmn:outgoing>f_noprogressGate</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:eventBasedGateway id="gw-review-wait" name="review ready or timeout?">
       <bpmn:incoming>f_progressOk</bpmn:incoming>
@@ -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>
@@ -204,7 +199,7 @@
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_reviewStalled</bpmn:incoming>
-      <bpmn:outgoing>f_stalledWait</bpmn:outgoing>
+      <bpmn:outgoing>f_stalledGate</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:serviceTask id="persist-escalation" name="Record escalation">
       <bpmn:extensionElements>
@@ -219,6 +214,10 @@
     </bpmn:serviceTask>
     <bpmn:exclusiveGateway id="gw-escalated" name="escalation opened?" default="f_escReenter">
       <bpmn:incoming>f_escGate</bpmn:incoming>
+      <bpmn:incoming>f_noprogressGate</bpmn:incoming>
+      <bpmn:incoming>f_stalledGate</bpmn:incoming>
+      <bpmn:incoming>f_blockedGate</bpmn:incoming>
+      <bpmn:incoming>f_maxGate</bpmn:incoming>
       <bpmn:outgoing>f_escWait</bpmn:outgoing>
       <bpmn:outgoing>f_escReenter</bpmn:outgoing>
     </bpmn:exclusiveGateway>
@@ -235,7 +234,7 @@
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_guardMax</bpmn:incoming>
-      <bpmn:outgoing>f_maxWait</bpmn:outgoing>
+      <bpmn:outgoing>f_maxGate</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:userTask id="wait-answer" name="Answer escalation">
       <bpmn:extensionElements>
@@ -247,10 +246,6 @@
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_escWait</bpmn:incoming>
-      <bpmn:incoming>f_maxWait</bpmn:incoming>
-      <bpmn:incoming>f_stalledWait</bpmn:incoming>
-      <bpmn:incoming>f_noprogressWait</bpmn:incoming>
-      <bpmn:incoming>f_blockedWait</bpmn:incoming>
       <bpmn:outgoing>f_answerRecord</bpmn:outgoing>
     </bpmn:userTask>
     <bpmn:serviceTask id="record-answer" name="Record answer">
@@ -307,7 +302,7 @@
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_convergeBlocked</bpmn:incoming>
-      <bpmn:outgoing>f_blockedWait</bpmn:outgoing>
+      <bpmn:outgoing>f_blockedGate</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:endEvent id="End" name="Converged">
       <bpmn:incoming>f_finalize</bpmn:incoming>
@@ -322,7 +317,7 @@
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=convergeBlocked = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_convergeOk" name="addressed / default" sourceRef="gw-converge-gate" targetRef="persist-converged" />
-    <bpmn:sequenceFlow id="f_blockedWait" sourceRef="persist-escalation-blockedcomments" targetRef="wait-answer" />
+    <bpmn:sequenceFlow id="f_blockedGate" sourceRef="persist-escalation-blockedcomments" targetRef="gw-escalated" />
     <bpmn:sequenceFlow id="f_addressed" name="addressed / default" sourceRef="gw-status" targetRef="gw-guard" />
     <bpmn:sequenceFlow id="f_waiting" name="waiting" sourceRef="gw-status" targetRef="gw-guard">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "waiting"</bpmn:conditionExpression>
@@ -340,18 +335,18 @@
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=progressed = false</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_progressOk" name="progress / default" sourceRef="gw-progress" targetRef="gw-review-wait" />
-    <bpmn:sequenceFlow id="f_noprogressWait" sourceRef="persist-escalation-noprogress" targetRef="wait-answer" />
+    <bpmn:sequenceFlow id="f_noprogressGate" sourceRef="persist-escalation-noprogress" targetRef="gw-escalated" />
     <bpmn:sequenceFlow id="f_toReviewWait" sourceRef="gw-review-wait" targetRef="wait-review" />
     <bpmn:sequenceFlow id="f_toReviewTimeout" sourceRef="gw-review-wait" targetRef="wait-review-timeout" />
     <bpmn:sequenceFlow id="f_reviewLoop" sourceRef="wait-review" targetRef="review-round" />
     <bpmn:sequenceFlow id="f_reviewStalled" sourceRef="wait-review-timeout" targetRef="persist-review-stalled" />
-    <bpmn:sequenceFlow id="f_stalledWait" sourceRef="persist-review-stalled" targetRef="wait-answer" />
+    <bpmn:sequenceFlow id="f_stalledGate" sourceRef="persist-review-stalled" targetRef="gw-escalated" />
     <bpmn:sequenceFlow id="f_escGate" sourceRef="persist-escalation" targetRef="gw-escalated" />
     <bpmn:sequenceFlow id="f_escWait" sourceRef="gw-escalated" targetRef="wait-answer">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=escalated = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_escReenter" name="no escalation opened" sourceRef="gw-escalated" targetRef="gw-guard" />
-    <bpmn:sequenceFlow id="f_maxWait" sourceRef="persist-escalation-maxrounds" targetRef="wait-answer" />
+    <bpmn:sequenceFlow id="f_maxGate" sourceRef="persist-escalation-maxrounds" targetRef="gw-escalated" />
     <bpmn:sequenceFlow id="f_answerRecord" sourceRef="wait-answer" targetRef="record-answer" />
     <bpmn:sequenceFlow id="f_answerLoop" sourceRef="record-answer" targetRef="review-round" />
     <bpmn:sequenceFlow id="f_finalize" sourceRef="persist-converged" targetRef="End" />
@@ -374,84 +369,84 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-guard" bpmnElement="gw-guard" isMarkerVisible="true">
-        <dc:Bounds x="941" y="415" width="50" height="50" />
+        <dc:Bounds x="591" y="415" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="924" y="470" width="85" height="14" />
+          <dc:Bounds x="574" y="470" width="85" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-round" bpmnElement="persist-round">
-        <dc:Bounds x="1116" y="400" width="100" height="80" />
+        <dc:Bounds x="766" y="400" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_check-progress" bpmnElement="check-progress">
-        <dc:Bounds x="1316" y="400" width="100" height="80" />
+        <dc:Bounds x="966" y="400" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-progress" bpmnElement="gw-progress" isMarkerVisible="true">
-        <dc:Bounds x="1516" y="415" width="50" height="50" />
+        <dc:Bounds x="1166" y="415" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1511" y="382" width="60" height="28" />
+          <dc:Bounds x="1161" y="382" width="60" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-escalation-noprogress" bpmnElement="persist-escalation-noprogress">
-        <dc:Bounds x="1666" y="720" width="100" height="80" />
+        <dc:Bounds x="1316" y="720" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-review-wait" bpmnElement="gw-review-wait" isMarkerVisible="true">
-        <dc:Bounds x="1691" y="415" width="50" height="50" />
+        <dc:Bounds x="1341" y="415" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1672" y="382" width="88" height="28" />
+          <dc:Bounds x="1322" y="382" width="88" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-review" bpmnElement="wait-review">
-        <dc:Bounds x="1866" y="422" width="36" height="36" />
+        <dc:Bounds x="1516" y="422" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1840" y="389" width="88" height="28" />
+          <dc:Bounds x="1490" y="389" width="88" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-review-timeout" bpmnElement="wait-review-timeout">
-        <dc:Bounds x="1866" y="582" width="36" height="36" />
+        <dc:Bounds x="1516" y="582" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1856" y="623" width="56" height="42" />
+          <dc:Bounds x="1506" y="623" width="56" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-review-stalled" bpmnElement="persist-review-stalled">
-        <dc:Bounds x="2002" y="560" width="100" height="80" />
+        <dc:Bounds x="1652" y="560" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-escalation" bpmnElement="persist-escalation">
-        <dc:Bounds x="566" y="560" width="100" height="80" />
+        <dc:Bounds x="566" y="1040" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-escalated" bpmnElement="gw-escalated" isMarkerVisible="true">
-        <dc:Bounds x="766" y="575" width="50" height="50" />
+        <dc:Bounds x="1852" y="255" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="821" y="586" width="74" height="28" />
+          <dc:Bounds x="1760" y="290" width="74" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-escalation-maxrounds" bpmnElement="persist-escalation-maxrounds">
-        <dc:Bounds x="1116" y="880" width="100" height="80" />
+        <dc:Bounds x="766" y="880" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_wait-answer" bpmnElement="wait-answer">
-        <dc:Bounds x="2202" y="240" width="100" height="80" />
+        <dc:Bounds x="2002" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_record-answer" bpmnElement="record-answer">
-        <dc:Bounds x="2402" y="240" width="100" height="80" />
+        <dc:Bounds x="2202" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-converged" bpmnElement="persist-converged">
-        <dc:Bounds x="916" y="80" width="100" height="80" />
+        <dc:Bounds x="966" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_check-converge" bpmnElement="check-converge">
         <dc:Bounds x="566" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-converge-gate" bpmnElement="gw-converge-gate" isMarkerVisible="true">
-        <dc:Bounds x="766" y="95" width="50" height="50" />
+        <dc:Bounds x="791" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="754" y="62" width="74" height="28" />
+          <dc:Bounds x="779" y="62" width="74" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_persist-escalation-blockedcomments" bpmnElement="persist-escalation-blockedcomments">
-        <dc:Bounds x="916" y="240" width="100" height="80" />
+        <dc:Bounds x="966" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
-        <dc:Bounds x="1148" y="102" width="36" height="36" />
+        <dc:Bounds x="1173" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1132" y="143" width="69" height="14" />
+          <dc:Bounds x="1157" y="143" width="69" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_start" bpmnElement="f_start">
@@ -471,71 +466,73 @@
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toConvergeGate" bpmnElement="f_toConvergeGate">
         <di:waypoint x="666" y="120" />
-        <di:waypoint x="766" y="120" />
+        <di:waypoint x="791" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_convergeOk" bpmnElement="f_convergeOk">
-        <di:waypoint x="816" y="120" />
-        <di:waypoint x="916" y="120" />
+        <di:waypoint x="841" y="120" />
+        <di:waypoint x="966" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="827" y="125" width="78" height="28" />
+          <dc:Bounds x="865" y="87" width="78" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_finalize" bpmnElement="f_finalize">
-        <di:waypoint x="1016" y="120" />
-        <di:waypoint x="1148" y="120" />
+        <di:waypoint x="1066" y="120" />
+        <di:waypoint x="1173" y="120" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_guardOk" bpmnElement="f_guardOk">
-        <di:waypoint x="991" y="440" />
-        <di:waypoint x="1116" y="440" />
+        <di:waypoint x="641" y="440" />
+        <di:waypoint x="766" y="440" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1014" y="418" width="60" height="14" />
+          <dc:Bounds x="664" y="418" width="60" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_roundWait" bpmnElement="f_roundWait">
-        <di:waypoint x="1216" y="440" />
-        <di:waypoint x="1316" y="440" />
+        <di:waypoint x="866" y="440" />
+        <di:waypoint x="966" y="440" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_checkGate" bpmnElement="f_checkGate">
-        <di:waypoint x="1416" y="440" />
-        <di:waypoint x="1516" y="440" />
+        <di:waypoint x="1066" y="440" />
+        <di:waypoint x="1166" y="440" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_progressOk" bpmnElement="f_progressOk">
-        <di:waypoint x="1566" y="440" />
-        <di:waypoint x="1691" y="440" />
+        <di:waypoint x="1216" y="440" />
+        <di:waypoint x="1341" y="440" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1591" y="407" width="71" height="28" />
+          <dc:Bounds x="1241" y="407" width="71" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toReviewWait" bpmnElement="f_toReviewWait">
-        <di:waypoint x="1741" y="440" />
-        <di:waypoint x="1866" y="440" />
+        <di:waypoint x="1391" y="440" />
+        <di:waypoint x="1516" y="440" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reviewLoop" bpmnElement="f_reviewLoop">
-        <di:waypoint x="1884" y="458" />
-        <di:waypoint x="1884" y="500" />
+        <di:waypoint x="1534" y="458" />
+        <di:waypoint x="1534" y="500" />
         <di:waypoint x="266" y="500" />
         <di:waypoint x="266" y="160" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_escReenter" bpmnElement="f_escReenter">
-        <di:waypoint x="791" y="575" />
-        <di:waypoint x="791" y="440" />
-        <di:waypoint x="941" y="440" />
+        <di:waypoint x="1877" y="255" />
+        <di:waypoint x="1877" y="220" />
+        <di:waypoint x="616" y="220" />
+        <di:waypoint x="616" y="415" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="796" y="507" width="74" height="42" />
+          <dc:Bounds x="1410" y="173" width="74" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_convergeBlocked" bpmnElement="f_convergeBlocked">
-        <di:waypoint x="791" y="145" />
-        <di:waypoint x="791" y="280" />
-        <di:waypoint x="916" y="280" />
+        <di:waypoint x="816" y="145" />
+        <di:waypoint x="816" y="220" />
+        <di:waypoint x="1016" y="220" />
+        <di:waypoint x="1016" y="240" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="796" y="199" width="81" height="28" />
+          <dc:Bounds x="821" y="169" width="81" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_addressed" bpmnElement="f_addressed">
         <di:waypoint x="441" y="145" />
         <di:waypoint x="441" y="440" />
-        <di:waypoint x="941" y="440" />
+        <di:waypoint x="591" y="440" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="446" y="279" width="78" height="28" />
         </bpmndi:BPMNLabel>
@@ -543,87 +540,81 @@
       <bpmndi:BPMNEdge id="BPMNEdge_f_waiting" bpmnElement="f_waiting">
         <di:waypoint x="441" y="145" />
         <di:waypoint x="441" y="440" />
-        <di:waypoint x="941" y="440" />
+        <di:waypoint x="591" y="440" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="380" y="286" width="56" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_escalate" bpmnElement="f_escalate">
         <di:waypoint x="441" y="145" />
-        <di:waypoint x="441" y="600" />
-        <di:waypoint x="566" y="600" />
+        <di:waypoint x="441" y="1080" />
+        <di:waypoint x="566" y="1080" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="446" y="506" width="81" height="28" />
+          <dc:Bounds x="446" y="746" width="81" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_guardMax" bpmnElement="f_guardMax">
-        <di:waypoint x="991" y="440" />
-        <di:waypoint x="1096" y="440" />
-        <di:waypoint x="1096" y="920" />
-        <di:waypoint x="1116" y="920" />
+        <di:waypoint x="641" y="440" />
+        <di:waypoint x="746" y="440" />
+        <di:waypoint x="746" y="920" />
+        <di:waypoint x="766" y="920" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1101" y="673" width="74" height="14" />
+          <dc:Bounds x="751" y="673" width="74" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_noProgress" bpmnElement="f_noProgress">
-        <di:waypoint x="1566" y="440" />
-        <di:waypoint x="1646" y="440" />
-        <di:waypoint x="1646" y="760" />
-        <di:waypoint x="1666" y="760" />
+        <di:waypoint x="1216" y="440" />
+        <di:waypoint x="1296" y="440" />
+        <di:waypoint x="1296" y="760" />
+        <di:waypoint x="1316" y="760" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1563" y="593" width="78" height="14" />
+          <dc:Bounds x="1213" y="593" width="78" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toReviewTimeout" bpmnElement="f_toReviewTimeout">
-        <di:waypoint x="1716" y="465" />
-        <di:waypoint x="1716" y="600" />
-        <di:waypoint x="1866" y="600" />
-      </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_escWait" bpmnElement="f_escWait">
-        <di:waypoint x="791" y="625" />
-        <di:waypoint x="791" y="980" />
-        <di:waypoint x="2182" y="980" />
-        <di:waypoint x="2182" y="300" />
-        <di:waypoint x="2202" y="300" />
+        <di:waypoint x="1366" y="465" />
+        <di:waypoint x="1366" y="600" />
+        <di:waypoint x="1516" y="600" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_blockedWait" bpmnElement="f_blockedWait">
-        <di:waypoint x="1016" y="280" />
-        <di:waypoint x="2202" y="280" />
+      <bpmndi:BPMNEdge id="BPMNEdge_f_blockedGate" bpmnElement="f_blockedGate">
+        <di:waypoint x="1066" y="280" />
+        <di:waypoint x="1852" y="280" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_noprogressWait" bpmnElement="f_noprogressWait">
-        <di:waypoint x="1766" y="780" />
-        <di:waypoint x="1786" y="780" />
-        <di:waypoint x="1786" y="980" />
-        <di:waypoint x="2252" y="980" />
-        <di:waypoint x="2252" y="320" />
+      <bpmndi:BPMNEdge id="BPMNEdge_f_noprogressGate" bpmnElement="f_noprogressGate">
+        <di:waypoint x="1416" y="760" />
+        <di:waypoint x="1877" y="760" />
+        <di:waypoint x="1877" y="305" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reviewStalled" bpmnElement="f_reviewStalled">
-        <di:waypoint x="1902" y="600" />
-        <di:waypoint x="2002" y="600" />
+        <di:waypoint x="1552" y="600" />
+        <di:waypoint x="1652" y="600" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_stalledWait" bpmnElement="f_stalledWait">
-        <di:waypoint x="2052" y="560" />
-        <di:waypoint x="2052" y="280" />
-        <di:waypoint x="2202" y="280" />
+      <bpmndi:BPMNEdge id="BPMNEdge_f_stalledGate" bpmnElement="f_stalledGate">
+        <di:waypoint x="1752" y="600" />
+        <di:waypoint x="1877" y="600" />
+        <di:waypoint x="1877" y="305" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_escGate" bpmnElement="f_escGate">
-        <di:waypoint x="666" y="600" />
-        <di:waypoint x="766" y="600" />
+        <di:waypoint x="666" y="1080" />
+        <di:waypoint x="1877" y="1080" />
+        <di:waypoint x="1877" y="305" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_maxWait" bpmnElement="f_maxWait">
-        <di:waypoint x="1216" y="940" />
-        <di:waypoint x="1236" y="940" />
-        <di:waypoint x="1236" y="980" />
-        <di:waypoint x="2252" y="980" />
-        <di:waypoint x="2252" y="320" />
+      <bpmndi:BPMNEdge id="BPMNEdge_f_escWait" bpmnElement="f_escWait">
+        <di:waypoint x="1902" y="280" />
+        <di:waypoint x="2002" y="280" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_maxGate" bpmnElement="f_maxGate">
+        <di:waypoint x="866" y="920" />
+        <di:waypoint x="1877" y="920" />
+        <di:waypoint x="1877" y="305" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_answerRecord" bpmnElement="f_answerRecord">
-        <di:waypoint x="2302" y="280" />
-        <di:waypoint x="2402" y="280" />
+        <di:waypoint x="2102" y="280" />
+        <di:waypoint x="2202" y="280" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_answerLoop" bpmnElement="f_answerLoop">
-        <di:waypoint x="2452" y="320" />
-        <di:waypoint x="2452" y="340" />
+        <di:waypoint x="2252" y="320" />
+        <di:waypoint x="2252" y="340" />
         <di:waypoint x="266" y="340" />
         <di:waypoint x="266" y="160" />
       </bpmndi:BPMNEdge>

package/workers/persist-escalation/worker.ts

@@ -9,10 +9,13 @@
 // durable review wait instead of routing here (see app/roundResultDefault.ts). This worker keeps
 // the same rule as defence-in-depth via the canonical taxonomy: if a blank-question job ever
 // reaches it, it opens NO escalation and reports `escalated:false` rather than FABRICATING a
-// question (the retired failure mode) or throwing an un-remediable incident. The convergence-loop
-// model branches on that `escalated` output (`gw-escalated`): a `false` return re-enters the loop
-// via `gw-guard` instead of flowing into the `wait-answer` catch, so a non-escalation can never
-// wedge a token on a durable wait that has no escalation for a human to answer.
+// question (the retired failure mode) or throwing an un-remediable incident. EVERY convergence-loop
+// escalation arm — the agent-verdict `persist-escalation` AND the four control-flow arms
+// (`persist-escalation-noprogress`, `persist-review-stalled`, `persist-escalation-blockedcomments`,
+// `persist-escalation-maxrounds`) — now routes its `escalated` output through the `gw-escalated`
+// gateway (issue #333): a `false` return re-enters the loop via `gw-guard` instead of flowing into
+// the `wait-answer` catch, so a non-escalation (e.g. a blank `convergeBlockReason`) can never wedge
+// a token on a durable wait that has no escalation for a human to answer.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { abandonTokenFromUrl } from "../../app/abandon.ts";
 import { classifyEscalation } from "../../app/escalationTaxonomy.ts";

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));