@nanobpm/nano-workforce 0.39.3 → 0.40.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.40.1](https://github.com/nanobpm/nano-workforce/compare/v0.40.0...v0.40.1) (2026-08-11)
+
+
+### Bug Fixes
+
+* **convergence:** safe default for resultless review rounds ([#116](https://github.com/nanobpm/nano-workforce/issues/116)) ([de85188](https://github.com/nanobpm/nano-workforce/commit/de85188f57b69496596f4c41cf555c9f6f2090da))
+
+# [0.40.0](https://github.com/nanobpm/nano-workforce/compare/v0.39.3...v0.40.0) (2026-08-11)
+
+
+### Features
+
+* **convergence:** per-request convergeOnly override to skip the merge-loop ([#115](https://github.com/nanobpm/nano-workforce/issues/115)) ([8840b23](https://github.com/nanobpm/nano-workforce/commit/8840b23e97ed56aaf43df20d3f9a97b00b7e865d))
+
 ## [0.39.3](https://github.com/nanobpm/nano-workforce/compare/v0.39.2...v0.39.3) (2026-08-11)
 
 

package/README.md

@@ -210,6 +210,10 @@ branch before escalating (`NANO_PR_MAX_CI_FIX_ROUNDS`, default 3). Conflicts, an
 exhausted budget, or an agent that can't fix the build escalate to a human; answer in
 the UI and the process re-arms and retries.
 
+A single submission can pin **review-only** regardless of the global default by
+passing `convergeOnly: true` on the `start/convergence-loop` request — the PR stops at
+`converged` and is never handed to `merge-loop`, even with `NANO_PR_AUTO_MERGE` on.
+
 ### Fleet mode: hand it an issue (plan → implement → converge)
 
 ```
@@ -244,7 +248,7 @@ curl -sS -X POST http://localhost:3000/app/api/actions/start/plan-fanout \
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
 | `NANO_PR_MAX_ROUNDS` | `20` | default cap: escalate after N rounds (per-submit override via the form / the `maxRounds` field on `start/convergence-loop`; clamped 1–100) |
 | `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret for the `POST /app/api/hooks/feature-answer` webhook operation (`X-Hook-Secret`); unset = open |
-| `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only) |
+| `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only). Per-submit override via the `convergeOnly` field on `start/convergence-loop` (`true` forces review-only for that PR) |
 | `NANO_PR_MERGE_METHOD` | `squash` | merge method: `squash`, `merge`, or `rebase` |
 | `NANO_PR_MERGE_ADMIN` | `0` | pass `--admin` to override failing non-required checks (use with care) |
 | `NANO_PR_MAX_CI_FIX_ROUNDS` | `3` | max `senior:fix-ci` attempts to green a `blocked` PR before escalating; `0` disables (escalate immediately), clamped 0–20 |

package/SPEC.md

@@ -336,6 +336,11 @@ same `prKey`, sharing the datasource and poller. It merges the PR, honouring
 merge-queue branches and cross-PR dependencies, and reuses the review stage's
 escalation machinery for anything it can't resolve autonomously.
 
+A per-submit `convergeOnly: true` on the `start/convergence-loop` request pins that PR
+to review-only regardless of the global default: `pr.finalize` reads the flag off the
+instance and rests the PR at `converged` without starting `merge-loop`. The flag only
+ever narrows (it never forces the merge stage on when `NANO_PR_AUTO_MERGE` is off).
+
 Flow:
 
 ```
@@ -396,7 +401,7 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `NANO_PR_POLL_MS` | 60000 | poll interval |
 | `NANO_PR_MAX_ROUNDS` | 20 | default round cap (per-submit `maxRounds` override, clamped 1–100) |
 | `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret for the `/app/api/hooks/feature-answer` webhook operation (`X-Hook-Secret`) |
-| `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only) |
+| `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `convergeOnly: true` override) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |
 | `NANO_PR_REVIEW_WAIT_TIMEOUT` | PT20M | ISO-8601 wait before a stalled review escalates (timer arm of the `wait-review` event-based gateway); malformed → default |

package/app/persist-escalation.test.ts

@@ -95,11 +95,17 @@ test("a padded question is persisted trimmed (no whitespace drift)", async () =>
   assertEquals((updates.pull_requests![0] as any).patch.open_escalation_question, "needs a decision", "denormalised question is trimmed too");
 });
 
-// A round that fell through the `gw-status` default (no `converged`/`addressed` status and no
-// question — the prompt-less-agent failure behind the empty "(no question provided)" escalations
-// on Magikcraft/nano-bpm #597/#599) must NOT throw (which parked an un-remediable JobNoRetries
-// incident). It now opens an *answerable* escalation with a fabricated, concrete question and the
-// agent's transcript attached, so a human can unblock the loop entirely from the UI.
+// Defence-in-depth for the persist-escalation worker: if the gateway ever DOES route a
+// blank-status / blank-question job here (an agent-raised `needs_input`/`blocked` with no
+// question, or the max-rounds / review-stalled arms), the worker must NOT throw — throwing
+// parked an un-remediable JobNoRetries incident (the empty "(no question provided)" escalations
+// on Magikcraft/nano-bpm #597/#599). It opens an *answerable* escalation with a fabricated,
+// concrete question and the agent's transcript attached, so a human can unblock the loop from
+// the UI.
+//
+// NOTE: the `gw-status` gateway no longer routes an empty/unknown status here — that now
+// defaults to `f_addressed` and re-enters the review wait (see roundResultDefault.test.ts).
+// This fabrication path stays as a worker-level backstop for the explicit escalation arms.
 test("blank question fabricates an answerable escalation (no throw, no incident)", async () => {
   for (const question of [undefined, "", "   "]) {
     const { app, inserts, updates } = fakeApp();

package/app/roundResultDefault.test.ts

@@ -0,0 +1,94 @@
+// Structural regression guard for the review-round "safe default" routing.
+//
+// A review round that exits without a machine-readable result (empty/unknown status)
+// used to fall through the `gw-status` exclusive gateway's `default="f_escalate"`
+// arm and escalate to a human — even after a benign rebase/force-push with no
+// reviewer comments. That is premature: the round-cap gate (`gw-guard`) and the
+// review-wait timeout already provide the human-escalation safety nets, and
+// `persist-round` defaults an absent status to `addressed`.
+//
+// The fix inverts the gateway: escalation is now an EXPLICIT arm gated on
+// `needs_input`/`blocked`, and `f_addressed` is the default, so any unknown/empty
+// status re-enters the durable review wait instead of paging a human.
+//
+// This is a pure text assertion over the committed BPMN (no engine), matching the
+// repo's lightweight model-guard style (see 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, " ");
+
+// The `<sequenceFlow id="...">` element (whole element, up to its close), whether
+// self-closing or with children. Returns the matched text or null.
+//
+// The body branch uses a tempered negative lookahead — `(?:(?!<bpmn:sequenceFlow\b).)*?`
+// — so it can never over-match across a following `<bpmn:sequenceFlow>` element; it
+// captures only up to *this* element's own close.
+function flowElement(id: string): string | null {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*?\\bid="${id}"[^>]*?(?:/>|>(?:(?!<bpmn:sequenceFlow\\b).)*?</bpmn:sequenceFlow>)`,
+  );
+  const m = flat.match(re);
+  return m ? m[0] : null;
+}
+
+// Every `<bpmn:sequenceFlow>` element (whole element, self-closing or with children),
+// using the same tempered-lookahead boundary as flowElement() so a captured element can
+// never bleed into the next one.
+function allFlows(): string[] {
+  const re = new RegExp(
+    "<bpmn:sequenceFlow\\b[^>]*?(?:/>|>(?:(?!<bpmn:sequenceFlow\\b).)*?</bpmn:sequenceFlow>)",
+    "g",
+  );
+  return flat.match(re) ?? [];
+}
+
+test("gw-status defaults to the addressed arm, not escalation", () => {
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-status"[^>]*>/);
+  assert(gw, "gw-status gateway missing");
+  assertStringIncludes(gw[0], 'default="f_addressed"');
+  // The old premature-escalation default must be gone.
+  assert(
+    !/id="gw-status"[^>]*default="f_escalate"/.test(flat),
+    "gw-status must no longer default to escalation",
+  );
+});
+
+test("escalation is an explicit needs_input/blocked arm", () => {
+  const esc = flowElement("f_escalate");
+  assert(esc, "f_escalate flow missing");
+  assertStringIncludes(esc, 'targetRef="persist-escalation"');
+  // Escalation now only fires on an explicit human-blocking status.
+  assertStringIncludes(esc, 'status = "needs_input" or status = "blocked"');
+});
+
+test("the default (addressed) arm carries no condition and re-enters the guard", () => {
+  const addressed = flowElement("f_addressed");
+  assert(addressed, "f_addressed flow missing");
+  assertStringIncludes(addressed, 'targetRef="gw-guard"');
+  // A default flow must have NO conditionExpression.
+  assert(
+    !/conditionExpression/.test(addressed),
+    "f_addressed is the default flow and must not carry a conditionExpression",
+  );
+});
+
+test("regression: an empty/unknown status no longer routes to persist-escalation", () => {
+  // Escalation is reachable ONLY via an explicit condition (the needs_input/blocked arm),
+  // never as a catch-all default. Enumerate EVERY sequenceFlow into `persist-escalation`
+  // and assert each one carries a conditionExpression — so no future edit can slip an
+  // unconditional (default) arm into escalation.
+  const intoEscalation = allFlows().filter((f) => /targetRef="persist-escalation"/.test(f));
+  assert(intoEscalation.length > 0, "no flow targets persist-escalation");
+  for (const f of intoEscalation) {
+    assertStringIncludes(f, "conditionExpression");
+  }
+  // The addressed default must land on the guard (which re-solicits the review), not escalation.
+  const addressed = flowElement("f_addressed");
+  assert(addressed && /targetRef="gw-guard"/.test(addressed), "default arm must re-enter gw-guard");
+});

package/app/service.test.ts

@@ -281,3 +281,53 @@ test("submitPr stringifies a numeric processInstanceKey (contract: string | null
     assertEquals(pr.process_key, "2251799813685249");
   });
 });
+
+// Per-request review-only override: `submitPr` carries `convergeOnly` onto the convergence
+// instance so `pr.finalize` can stop at `converged` without handing off to the merge-loop. Default
+// false (so the global auto-merge default governs); true when the caller pins review-only.
+function captureConvergeOnly() {
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" },
+    escalations: { rows: [], key: "id" },
+    pr_dependencies: { rows: [], key: "pr_key" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+  let captured: unknown;
+  const engine = {
+    createInstance: (req: { variables?: Record<string, unknown> }) => {
+      captured = req.variables?.convergeOnly;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  } as any;
+  return { data, engine, get: () => captured };
+}
+
+test("submitPr threads convergeOnly=true onto the instance as a process variable", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, get } = captureConvergeOnly();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 8, url: "https://github.com/owner/repo/pull/8", prKey: "owner/repo#8" },
+      [],
+      20,
+      true,
+    );
+    assertEquals(get(), true);
+  });
+});
+
+test("submitPr defaults convergeOnly to false so the global auto-merge default governs", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, get } = captureConvergeOnly();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 9,
+      url: "https://github.com/owner/repo/pull/9",
+      prKey: "owner/repo#9",
+    });
+    assertEquals(get(), false);
+  });
+});

package/app/service.ts

@@ -285,6 +285,7 @@ export async function submitPr(
   parsed: ParsedPr,
   dependsOn: string[] = [],
   maxRounds: number = MAX_ROUNDS,
+  convergeOnly = false,
 ) {
   const table = prs(data);
   const existing = await table.get(parsed.prKey);
@@ -365,6 +366,10 @@ export async function submitPr(
       round: 1,
       maxRounds: clampRounds(maxRounds, MAX_ROUNDS),
       reviewWaitTimeout: REVIEW_WAIT_TIMEOUT,
+      // Per-request review-only override: carried on the instance so `pr.finalize` can stop at
+      // `converged` for this PR without handing off to the merge-loop, independent of the global
+      // NANO_PR_AUTO_MERGE default. Only ever narrows (never forces merge on when auto-merge is off).
+      convergeOnly,
       // Cooperative abandon check (#76): the capability URL + the abort brief appended to the
       // review-round agent's prompt, so it can stop before pushing if the run is cancelled.
       abandonUrl: abUrl,

package/openapi.yaml

@@ -189,6 +189,11 @@ components:
           type: integer
           minimum: 1
           description: Values above 100 are accepted and clamped to 100 by the delegate.
+        convergeOnly:
+          type: boolean
+          description: When true, run convergence only and stop at `converged` — the PR is never
+            handed to the merge-loop even if auto-merge is on globally (`NANO_PR_AUTO_MERGE`). A
+            per-request review-only override; defaults to false (the global auto-merge default applies).
     MessageResult:
       type: object
       description: The result of publishing a message / answering an escalation. Shape varies by message

package/operations/startAndMessage.test.ts

@@ -29,6 +29,75 @@ test("startConvergenceLoop → 400 on an unparseable PR reference", async () =>
   assertEquals(typeof r.body.error, "string");
 });
 
+// The delegate forwards a per-request review-only override to `submitPr`, coercing strictly: only a
+// JSON `true` enables convergence-only (a stray string/other value is NOT truthy-coerced). Drives the
+// real delegate → submitPr against an in-memory app and captures the `convergeOnly` process variable.
+function captureApp() {
+  const rows: Record<string, unknown>[] = [];
+  let captured: unknown;
+  const data = {
+    table: (_name: string, key: string) => ({
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    }),
+  };
+  const engine = {
+    createInstance: (req: { variables?: Record<string, unknown> }) => {
+      captured = req.variables?.convergeOnly;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  };
+  return { app: { data, engine } as any as AppApi, get: () => captured };
+}
+
+function withGithubOff(run: () => Promise<void>): Promise<void> {
+  const prev = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token"; // no token → meta fetch is skipped
+  delete process.env["GITHUB_TOKEN"];
+  return run().finally(() => {
+    if (prev !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prev;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+  });
+}
+
+test("startConvergenceLoop forwards convergeOnly:true to the loop", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureApp();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#8", convergeOnly: true }), capApp);
+    assertEquals((res as any).status, 202);
+    assertEquals(get(), true);
+  });
+});
+
+test("startConvergenceLoop defaults convergeOnly to false and does not truthy-coerce a non-boolean", async () => {
+  await withGithubOff(async () => {
+    const omitted = captureApp();
+    await startConvergenceLoop(input({ pr: "owner/repo#9" }), omitted.app);
+    assertEquals(omitted.get(), false);
+
+    const stringy = captureApp();
+    await startConvergenceLoop(input({ pr: "owner/repo#10", convergeOnly: "true" }), stringy.app);
+    assertEquals(stringy.get(), false);
+  });
+});
+
 test("startPlanFanout → 400 on an unparseable issue reference", async () => {
   const res = await startPlanFanout(input({ issue: "" }), app);
   const r = res as any;

package/operations/startConvergenceLoop.ts

@@ -3,11 +3,12 @@
 // external webhook relay, a CI job, and Swagger all POST here. Parse the PR reference and
 // register/refresh the PR aggregate (idempotent on prKey) before starting the loop.
 //
-// The request body is FLAT (`{ pr | url, dependsOn?, maxRounds? }`), not wrapped in a `variables`
-// envelope: this is a purpose-built operation, not a generic engine "start process" call, so it does
-// not leak the engine's variable-map concept to callers. The runtime validates the body against
-// openapi.yaml; this delegate keeps the PR-parse guard because the reference format (owner/repo#123
-// or a URL) is app logic, not something the JSON schema can express — an unparseable reference is a 400.
+// The request body is FLAT (`{ pr | url, dependsOn?, maxRounds?, convergeOnly? }`), not wrapped in a
+// `variables` envelope: this is a purpose-built operation, not a generic engine "start process" call,
+// so it does not leak the engine's variable-map concept to callers. The runtime validates the body
+// against openapi.yaml; this delegate keeps the PR-parse guard because the reference format
+// (owner/repo#123 or a URL) is app logic, not something the JSON schema can express — an unparseable
+// reference is a 400.
 
 import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -21,5 +22,11 @@ export default defineOperation("startConvergenceLoop", async ({ body }, app) =>
   }
   const dependsOn = Array.isArray(b.dependsOn) ? b.dependsOn.map((d) => String(d)) : [];
   const maxRounds = clampRounds(b.maxRounds, MAX_ROUNDS);
-  return { status: 202, body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds) };
+  // Per-request review-only override: when true the PR stops at `converged` and is never
+  // handed to the merge-loop, regardless of the global NANO_PR_AUTO_MERGE default.
+  const convergeOnly = b.convergeOnly === true;
+  return {
+    status: 202,
+    body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly),
+  };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.39.3",
+  "version": "0.40.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/prompts/review-round.md

@@ -58,7 +58,11 @@ Because several agents may run on the same host at once:
 3. **Act.** Make the code changes for all fixes + nitpicks in your workspace (`cwd`)
    in one coherent, signed-off commit (`git commit -s`). Run the repo's
    build/test/lint locally before pushing. Push to the PR's head branch (the branch
-   you are already on) — do not open a new branch or PR.
+   you are already on) — do not open a new branch or PR. If the branch has drifted
+   behind its base and you need to **rebase / resolve a merge conflict** to keep it
+   mergeable, that is allowed: do it in place on this branch and **force-push**
+   (`--force-with-lease`). Any push this round — including a rebase/force-push with
+   no reviewer comments to act on — is an **`addressed`** round (see the return table).
 4. **Reply in-thread** to each comment you addressed or pushed back on, one reply
    per comment, so the trail lives on the PR.
 5. **Resolve the thread** for every comment you handled — every *fix*, *nitpick*,
@@ -128,7 +132,7 @@ Return **one** of:
 | `status`      | when                                                          | also set        |
 |---------------|---------------------------------------------------------------|-----------------|
 | `converged`   | nothing actionable left (see above)                           | `summary`       |
-| `addressed`   | you made changes + pushed this round                          | `summary`       |
+| `addressed`   | you pushed anything this round — code fixes, nitpicks, **or** a rebase/force-push to resolve a conflict | `summary`       |
 | `waiting`     | nothing to triage yet — you are awaiting a pending review (typically round 1) | `summary` |
 | `needs_input` | you hit a decision only a human can make                      | `summary`, `question` |
 | `blocked`     | you are stuck on something external (auth, failing push, missing secret) | `summary`, `question` |
@@ -143,7 +147,8 @@ Never guess on a `needs_input` decision — raise it and let a human answer.
 
 Your result variables only reach the process if you emit them through the harness's
 result channel. Prose in your normal output is **not** parsed — if you only "say"
-your status in the transcript, the round escalates with an empty question. So:
+your status in the transcript, the process can't read it, falls back to a safe
+default, and you waste a round. So emit a machine-readable result one of two ways:
 
 1. **Write a JSON object to the file at `$AGENT_RESULT_FILE`** (an env var the
    harness sets for you). The object's keys become process variables. Example for a
@@ -169,3 +174,12 @@ your status in the transcript, the round escalates with an empty question. So:
 Do not put the result file inside the repo checkout or `git add` it — it lives
 outside your workspace. Exit `0` for every status (including `blocked`/`needs_input`);
 a non-zero exit means a genuine crash and the job is retried.
+
+**Emitting a machine-readable result is your mandatory final step — never exit
+silently.** Emitting a result (the `$AGENT_RESULT_FILE` write, or the stdout fallback
+above if you truly cannot write the file) is the last thing you do on every path out of
+this round (including after a rebase/force-push, or when nothing needed doing). If you
+are ever unsure which status applies and you are not blocked on a human decision,
+return **`addressed`** (or **`waiting`** if you are still awaiting the first review) —
+never leave without a result. A missing result is treated as a safe `addressed` and
+re-enters the review wait, but relying on that instead of emitting one wastes a round.

package/resources/processes/convergence-loop.bpmn

@@ -90,7 +90,7 @@
       <bpmn:incoming>f_answerLoop</bpmn:incoming>
       <bpmn:outgoing>f_toStatus</bpmn:outgoing>
     </bpmn:serviceTask>
-    <bpmn:exclusiveGateway id="gw-status" name="status?" default="f_escalate">
+    <bpmn:exclusiveGateway id="gw-status" name="status?" default="f_addressed">
       <bpmn:incoming>f_toStatus</bpmn:incoming>
       <bpmn:outgoing>f_converged</bpmn:outgoing>
       <bpmn:outgoing>f_addressed</bpmn:outgoing>
@@ -202,13 +202,13 @@
     <bpmn:sequenceFlow id="f_converged" name="converged" sourceRef="gw-status" targetRef="persist-converged">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "converged"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
-    <bpmn:sequenceFlow id="f_addressed" name="addressed" sourceRef="gw-status" targetRef="gw-guard">
-      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "addressed"</bpmn:conditionExpression>
-    </bpmn:sequenceFlow>
+    <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>
     </bpmn:sequenceFlow>
-    <bpmn:sequenceFlow id="f_escalate" name="needs_input / blocked" sourceRef="gw-status" targetRef="persist-escalation" />
+    <bpmn:sequenceFlow id="f_escalate" name="needs_input / blocked" sourceRef="gw-status" targetRef="persist-escalation">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "needs_input" or status = "blocked"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_guardMax" name="max rounds" sourceRef="gw-guard" targetRef="persist-escalation-maxrounds">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=round &gt;= maxRounds</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
@@ -337,7 +337,7 @@
         <di:waypoint x="441" y="280" />
         <di:waypoint x="591" y="280" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="446" y="206" width="67" height="14" />
+          <dc:Bounds x="446" y="199" width="78" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_waiting" bpmnElement="f_waiting">

package/workers/finalize/worker.test.ts

@@ -0,0 +1,104 @@
+// Red/green for the per-request review-only override (`convergeOnly`). `pr.finalize` decides,
+// on convergence, whether to hand the PR to the merge-loop (auto-merge) or rest it at `converged`
+// (review-only). The global default is `NANO_PR_AUTO_MERGE` (on), but a single submission can pin
+// review-only by carrying `convergeOnly: true` on the instance. These drive the worker against an
+// in-memory data layer + a capturing engine and assert the hand-off happens iff auto-merge is on
+// AND the request did not force convergence-only.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import handler from "./worker.ts";
+import { MERGE_PROCESS_ID } from "../../app/service.ts";
+
+function fakeApp() {
+  const stores: Record<string, Record<string, unknown>[]> = {
+    pull_requests: [],
+    rounds: [],
+  };
+  const createdProcesses: string[] = [];
+  return {
+    createdProcesses,
+    stores,
+    app: {
+      data: {
+        table(name: string, key: string) {
+          const store = (stores[name] ??= []);
+          return {
+            // biome-ignore lint/plugin: in-memory test double for the data layer
+            get: (k: unknown) => Promise.resolve(store.find((r) => r[key] === k)),
+            // biome-ignore lint/plugin: in-memory test double for the data layer
+            find: (q: Record<string, unknown>) =>
+              Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+            // biome-ignore lint/plugin: in-memory test double for the data layer
+            insert: (row: Record<string, unknown>) => {
+              store.push(row);
+              return Promise.resolve(store.length);
+            },
+            // biome-ignore lint/plugin: in-memory test double for the data layer
+            update: (k: unknown, patch: Record<string, unknown>) => {
+              const row = store.find((r) => r[key] === k);
+              if (row) Object.assign(row, patch);
+              return Promise.resolve(row);
+            },
+          };
+        },
+      },
+      engine: {
+        createInstance: (req: { processDefinitionId: string }) => {
+          createdProcesses.push(req.processDefinitionId);
+          return Promise.resolve({ processInstanceKey: "MERGE-1" });
+        },
+      },
+      log: () => undefined,
+    },
+  };
+}
+
+const BASE_VARS = {
+  prKey: "owner/repo#5",
+  repo: "owner/repo",
+  prNumber: 5,
+  prUrl: "https://github.com/owner/repo/pull/5",
+  round: 2,
+  summary: "looks good",
+};
+
+// Auto-retro reads plan tables this fixture doesn't populate; disable it so the terminal
+// `converged` path doesn't spuriously probe for a retro. The hand-off decision under test is
+// independent of retro. Auto-merge is left at its default (on): `AUTO_MERGE` is computed once at
+// `app/service.ts` import time and captured by the imported handler, so toggling
+// `NANO_PR_AUTO_MERGE` here would be a no-op — only `NANO_AUTO_RETRO` is read dynamically.
+function withRetroOff(run: () => Promise<void>): Promise<void> {
+  const prevRetro = process.env["NANO_AUTO_RETRO"];
+  process.env["NANO_AUTO_RETRO"] = "0";
+  return run().finally(() => {
+    if (prevRetro == null) delete process.env["NANO_AUTO_RETRO"];
+    else process.env["NANO_AUTO_RETRO"] = prevRetro;
+  });
+}
+
+test("finalize with convergeOnly=true rests the PR at converged and never starts the merge-loop", async () => {
+  await withRetroOff(async () => {
+    const { app, stores, createdProcesses } = fakeApp();
+    // biome-ignore lint/plugin: constructing the framework's job envelope for the handler under test
+    await handler({ variables: { ...BASE_VARS, convergeOnly: true } } as never, app as never);
+
+    // No merge-loop instance started even though auto-merge is on globally …
+    assertEquals(createdProcesses.includes(MERGE_PROCESS_ID), false);
+    // … and the PR rests at the review-only terminal status.
+    const pr = stores.pull_requests[0];
+    assertEquals(pr.status, "converged");
+  });
+});
+
+test("finalize with convergeOnly absent hands off to the merge-loop when auto-merge is on", async () => {
+  await withRetroOff(async () => {
+    const { app, stores, createdProcesses } = fakeApp();
+    // biome-ignore lint/plugin: constructing the framework's job envelope for the handler under test
+    await handler({ variables: { ...BASE_VARS } } as never, app as never);
+
+    // The default (env-governed) path starts the merge-loop and parks the PR in the merge stage.
+    assertEquals(createdProcesses.includes(MERGE_PROCESS_ID), true);
+    const pr = stores.pull_requests[0];
+    assertEquals(pr.status, "waiting_deps");
+  });
+});

package/workers/finalize/worker.ts

@@ -15,6 +15,9 @@ interface In extends Record<string, unknown> {
   prUrl: string;
   round: number;
   summary?: string;
+  // Per-request review-only override: when true, stop at `converged` and never hand off to the
+  // merge-loop even if auto-merge is on globally. Set at submit time, carried on the instance.
+  convergeOnly?: boolean;
   // The per-PR abandon capability URL the agent was handed; its token is preserved on a heal so
   // the agent's cooperative-abort check keeps resolving (see ensurePr).
   abandonUrl?: string;
@@ -31,7 +34,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // `summary` is left undefined when absent so the write boundary omits it: the
   // nullable `rounds.summary` stays NULL and `pull_requests.outcome` is untouched
   // rather than being coerced to "".
-  const { prKey, repo, prNumber, prUrl, round, summary, abandonUrl } = job.variables;
+  const { prKey, repo, prNumber, prUrl, round, summary, abandonUrl, convergeOnly } = job.variables;
   const now = new Date().toISOString();
 
   // Heal a missing FK parent (engine/app.db desync) before the child `rounds` insert.
@@ -60,8 +63,11 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // once merge-loop is actually running — otherwise the PR would be parked in a merge-stage status
   // with no process behind it, and `submitPr` refuses to restart it (only `cancel` recovers). On
   // failure we leave the PR terminal as `converged` so a human/operator can (re)start merge.
+  //
+  // A per-request `convergeOnly` override forces the review-only path for this PR regardless of the
+  // global auto-merge default — the PR rests at `converged` and is never handed to the merge-loop.
   let status = "converged";
-  if (AUTO_MERGE) {
+  if (AUTO_MERGE && convergeOnly !== true) {
     try {
       const { mergeProcessKey } = await startMerge(app.data, app.engine, {
         repo,