@nanobpm/nano-workforce 0.39.2 → 0.40.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Bug Fixes
+
+* **merge-loop:** judge fresh-head-run by required checks, not rollup length ([#113](https://github.com/nanobpm/nano-workforce/issues/113)) ([a10c4c5](https://github.com/nanobpm/nano-workforce/commit/a10c4c5b3ee5c452591eeb6c6206c4815674959a))
+
 ## [0.39.2](https://github.com/nanobpm/nano-workforce/compare/v0.39.1...v0.39.2) (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/github.ts

@@ -214,6 +214,12 @@ export interface PrState {
    * frugal-CI stuck state the fresh-head-run remedy targets); `-1` when the transport can't
    * enumerate checks (token mode). */
   totalChecks: number;
+  /** Names of every head check present in any state (pending/failed/passed). Empty in token mode
+   * (the REST fallback can't enumerate checks). Lets the fresh-head-run remedy judge whether the
+   * repo's *required* checks (per its merge protocol) are actually present on the head — an
+   * unrelated always-on check (e.g. Mergify's "Merge Queue") must not read as "the required run
+   * already happened". */
+  presentCheckNames: string[];
   /** Whether the PR is a draft (a fresh head run is produced by marking it ready, not reopen). */
   isDraft: boolean;
   /** Current head commit. Used to scope one-shot merge-protocol nudges to a landing attempt. */
@@ -248,6 +254,19 @@ function failingCheckNames(rollup: RollupEntry[]): string[] {
   return names;
 }
 
+/** Names of every head check present, regardless of state. Covers both the CheckRun shape
+ * (`name`/`workflowName`) and the legacy StatusContext shape (`context`). Used to test whether a
+ * repo's *required* checks are present on the head — so an unrelated always-on check (e.g.
+ * Mergify's "Merge Queue") doesn't masquerade as the required CI run having already happened. */
+function allCheckNames(rollup: RollupEntry[]): string[] {
+  const names: string[] = [];
+  for (const c of rollup) {
+    const name = c.name || c.context || c.workflowName;
+    if (name) names.push(name);
+  }
+  return names;
+}
+
 export async function fetchPrState(
   repo: string,
   number: number | string,
@@ -280,6 +299,7 @@ export async function fetchPrState(
       failingChecks: names.length,
       failingCheckNames: names,
       totalChecks: rollup.length,
+      presentCheckNames: allCheckNames(rollup),
       isDraft: !!j.isDraft,
       headRefOid: j.headRefOid ?? null,
     };
@@ -305,6 +325,7 @@ export async function fetchPrState(
     failingChecks: -1, // REST here doesn't enumerate checks → classifier treats BLOCKED as "wait"
     failingCheckNames: [], // …and the CI-fix agent gets no per-check list in token mode
     totalChecks: -1, // …and the fresh-head-run remedy stays conservative (never reopens blind)
+    presentCheckNames: [], // …can't enumerate checks in token mode → no required-check presence signal
     isDraft: !!j.draft,
     headRefOid: j.head?.sha ?? null,
   };

package/app/mergeProtocol.test.ts

@@ -10,8 +10,10 @@ import {
   DEFAULT_MERGE_PROTOCOL,
   extractProtocolBlock,
   freshHeadRunAction,
+  headRunPresenceCount,
   type MergeProtocol,
   parseMergeProtocol,
+  presentRequiredCheckCount,
 } from "./mergeProtocol.ts";
 
 test("parseMergeProtocol: non-object / junk → defaults (total, never throws)", () => {
@@ -27,7 +29,10 @@ test("parseMergeProtocol: full nano-bpm-style descriptor", () => {
     freshHeadRun: "ready-or-reopen",
     waitForChecks: true,
     land: { method: "mergify-queue", comment: "@mergifyio queue" },
-    requiredChecks: ["rustfmt (pinned nightly)", "server (clippy + test)"],
+    requiredChecks: [
+      { name: "rustfmt (pinned nightly)", acceptedConclusions: ["success"] },
+      { name: "processos (clippy + test)", acceptedConclusions: ["success", "skipped"] },
+    ],
     doc: "AGENTS.md#merging-prs",
   });
   assertEquals(got.autoMerge, false);
@@ -35,20 +40,38 @@ test("parseMergeProtocol: full nano-bpm-style descriptor", () => {
   assertEquals(got.waitForChecks, true);
   assertEquals(got.land, { method: "mergify-queue", comment: "@mergifyio queue" });
   assertEquals(got.requiredChecks.length, 2);
+  assertEquals(got.requiredChecks[0], { name: "rustfmt (pinned nightly)", acceptedConclusions: ["success"] });
+  assertEquals(got.requiredChecks[1].acceptedConclusions, ["success", "skipped"]);
   assertEquals(got.doc, "AGENTS.md#merging-prs");
 });
 
+test("parseMergeProtocol: requiredChecks tolerates bare-string entries + drops nameless/junk", () => {
+  const got = parseMergeProtocol({
+    requiredChecks: [
+      "server (clippy + test)", // bare name → default acceptedConclusions ["success"]
+      { name: "engine-core (clippy + test)" }, // object, no acceptedConclusions → default
+      { name: "", acceptedConclusions: ["success"] }, // empty name → dropped
+      { acceptedConclusions: ["success"] }, // no name → dropped
+      42, // junk → dropped
+    ],
+  });
+  assertEquals(got.requiredChecks, [
+    { name: "server (clippy + test)", acceptedConclusions: ["success"] },
+    { name: "engine-core (clippy + test)", acceptedConclusions: ["success"] },
+  ]);
+});
+
 test("parseMergeProtocol: invalid enums / wrong types fall back per-field", () => {
   const got = parseMergeProtocol({
     autoMerge: "yes", // not a boolean → default
     freshHeadRun: "sometimes", // not in the enum → default (none)
     land: { method: "teleport" }, // not in the enum → default (gh-merge)
-    requiredChecks: ["ok", 7, null], // keep only strings
+    requiredChecks: ["ok", 7, null], // keep only usable names
   });
   assertEquals(got.autoMerge, DEFAULT_MERGE_PROTOCOL.autoMerge);
   assertEquals(got.freshHeadRun, "none");
   assertEquals(got.land.method, "gh-merge");
-  assertEquals(got.requiredChecks, ["ok"]);
+  assertEquals(got.requiredChecks, [{ name: "ok", acceptedConclusions: ["success"] }]);
 });
 
 test("parseMergeProtocol: comment dropped when absent", () => {
@@ -123,3 +146,52 @@ test("freshHeadRunAction: mode=ready only acts on drafts", () => {
   assertEquals(freshHeadRunAction(readyOnly, "waiting", 0, true), "ready");
   assertEquals(freshHeadRunAction(readyOnly, "waiting", 0, false), null); // not a draft → nothing to ready
 });
+
+// The nano-bpm merge protocol: 3 required checks, one skip-tolerant.
+const NANO_REQ: MergeProtocol = parseMergeProtocol({
+  freshHeadRun: "ready-or-reopen",
+  land: { method: "mergify-queue" },
+  requiredChecks: [
+    { name: "rustfmt (pinned nightly)", acceptedConclusions: ["success"] },
+    { name: "server (clippy + test)", acceptedConclusions: ["success"] },
+    { name: "processos (clippy + test)", acceptedConclusions: ["success", "skipped"] },
+  ],
+});
+
+test("presentRequiredCheckCount: counts only declared required checks present on the head", () => {
+  // Only an unrelated always-on check (Mergify) is present → zero required checks present.
+  assertEquals(presentRequiredCheckCount(NANO_REQ, ["Mergify Merge Queue"]), 0);
+  // Two of the three required checks present (plus the incidental Mergify one).
+  assertEquals(
+    presentRequiredCheckCount(NANO_REQ, ["Mergify Merge Queue", "server (clippy + test)", "rustfmt (pinned nightly)"]),
+    2,
+  );
+  // A repo that declares no required checks → nothing to count.
+  assertEquals(presentRequiredCheckCount(DEFAULT_MERGE_PROTOCOL, ["anything"]), 0);
+});
+
+test("headRunPresenceCount: required-aware — Mergify's incidental check doesn't mask a missing run", () => {
+  // The #727 stuck state: BLOCKED head carries only Mergify's neutral check, none of the 3
+  // required checks ran. Raw rollup length is 1, but the required-check presence is 0 → the
+  // remedy must see 0 and fire the reopen.
+  const st = { totalChecks: 1, presentCheckNames: ["Mergify Merge Queue"] };
+  assertEquals(headRunPresenceCount(NANO_REQ, st), 0);
+  assertEquals(freshHeadRunAction(NANO_REQ, "waiting", headRunPresenceCount(NANO_REQ, st), false), "reopen");
+});
+
+test("headRunPresenceCount: a present required check reads as run-exists (no reopen)", () => {
+  const st = { totalChecks: 2, presentCheckNames: ["Mergify Merge Queue", "server (clippy + test)"] };
+  assertEquals(headRunPresenceCount(NANO_REQ, st), 1);
+  assertEquals(freshHeadRunAction(NANO_REQ, "waiting", headRunPresenceCount(NANO_REQ, st), false), null);
+});
+
+test("headRunPresenceCount: no declared required checks → falls back to total rollup length", () => {
+  const proto = parseMergeProtocol({ freshHeadRun: "ready-or-reopen", land: { method: "gh-merge" } });
+  assertEquals(headRunPresenceCount(proto, { totalChecks: 0, presentCheckNames: [] }), 0);
+  assertEquals(headRunPresenceCount(proto, { totalChecks: 3, presentCheckNames: ["a", "b", "c"] }), 3);
+});
+
+test("headRunPresenceCount: token mode (totalChecks < 0) stays conservative (-1)", () => {
+  assertEquals(headRunPresenceCount(NANO_REQ, { totalChecks: -1, presentCheckNames: [] }), -1);
+  assertEquals(freshHeadRunAction(NANO_REQ, "waiting", -1, false), null);
+});

package/app/mergeProtocol.ts

@@ -28,6 +28,16 @@ export type FreshHeadRun = "none" | "ready" | "reopen" | "ready-or-reopen";
  * `ui` = a human clicks Merge (Merlin can't do it → escalate). */
 export type LandMethod = "gh-merge" | "admin" | "mergify-queue" | "ui";
 
+/** One required status check a repo declares in its merge protocol. `name` is the check-run /
+ * status-context name exactly as GitHub reports it in the head `statusCheckRollup`.
+ * `acceptedConclusions` are the conclusions that count as satisfied (default `["success"]`); a
+ * change-gated check that is skipped for irrelevant PRs also lists `"skipped"` so a skip counts
+ * as satisfied (required-when-run, skip-tolerant). */
+export interface RequiredCheck {
+  name: string;
+  acceptedConclusions: string[];
+}
+
 export interface MergeProtocol {
   /** Does the repo auto-merge a PR once its checks go green? (Informational; Merlin never relies
    * on auto-merge — it lands deliberately.) */
@@ -38,8 +48,10 @@ export interface MergeProtocol {
   waitForChecks: boolean;
   /** How to land the PR. */
   land: { method: LandMethod; comment?: string };
-  /** Names of the required checks (informational; the poller reads live state). */
-  requiredChecks: string[];
+  /** The checks that gate the merge. A repo publishing these lets the fresh-head-run remedy judge
+   * "is the required CI run present on the head?" by *these* checks — not by total rollup length,
+   * which an unrelated always-on check (e.g. Mergify's "Merge Queue") would otherwise satisfy. */
+  requiredChecks: RequiredCheck[];
   /** Pointer to the human doc, for escalation messages. */
   doc?: string;
 }
@@ -70,6 +82,30 @@ function strArray(v: unknown): string[] | undefined {
   if (!Array.isArray(v)) return undefined;
   return v.filter((x): x is string => typeof x === "string");
 }
+/** Parse `requiredChecks`, tolerating both the rich object shape (`{ name, acceptedConclusions }`)
+ * and a bare list of check names (each → `{ name, acceptedConclusions: ["success"] }`). Entries
+ * without a usable `name` are dropped. Total — never throws. */
+function requiredCheckArray(v: unknown): RequiredCheck[] {
+  if (!Array.isArray(v)) return [];
+  const out: RequiredCheck[] = [];
+  for (const entry of v) {
+    if (typeof entry === "string") {
+      const name = entry.trim();
+      if (name === "") continue;
+      out.push({ name, acceptedConclusions: ["success"] });
+      continue;
+    }
+    if (!isRecord(entry)) continue;
+    const name = str(entry.name)?.trim();
+    if (name === undefined || name === "") continue;
+    const accepted = strArray(entry.acceptedConclusions);
+    out.push({
+      name,
+      acceptedConclusions: accepted && accepted.length > 0 ? accepted : ["success"],
+    });
+  }
+  return out;
+}
 function oneOf<T extends string>(v: unknown, allowed: ReadonlySet<string>): T | undefined {
   const s = str(v);
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
@@ -88,7 +124,7 @@ export function parseMergeProtocol(raw: unknown): MergeProtocol {
     freshHeadRun: oneOf<FreshHeadRun>(raw.freshHeadRun, FRESH_HEAD_RUNS) ?? DEFAULT_MERGE_PROTOCOL.freshHeadRun,
     waitForChecks: bool(raw.waitForChecks) ?? DEFAULT_MERGE_PROTOCOL.waitForChecks,
     land: comment !== undefined ? { method, comment } : { method },
-    requiredChecks: strArray(raw.requiredChecks) ?? [],
+    requiredChecks: requiredCheckArray(raw.requiredChecks),
     doc: str(raw.doc),
   };
 }
@@ -159,27 +195,53 @@ export interface FreshHeadRunAttempt {
   lastActionHeadRefOid?: string | null;
 }
 
+/** Count of the protocol's required checks currently present on the head (in any state). This is
+ * the signal the fresh-head-run remedy actually wants — "has the required CI run happened?" — as
+ * opposed to the raw rollup length, which an unrelated always-on check (e.g. Mergify's "Merge
+ * Queue") inflates. A required check matches by exact name against the head `statusCheckRollup`. */
+export function presentRequiredCheckCount(protocol: MergeProtocol, presentCheckNames: string[]): number {
+  const present = new Set(presentCheckNames);
+  return protocol.requiredChecks.filter((c) => present.has(c.name)).length;
+}
+
+/** The "does a head run already exist?" count to feed {@link freshHeadRunAction}. When the repo
+ * declares `requiredChecks`, judge presence by *those* checks — so an incidental always-on check
+ * (Mergify) never masks a genuinely-missing required run and wedges the merge. When it declares
+ * none, fall back to the total rollup length (legacy behaviour, default repos unchanged). Token
+ * mode (`totalChecks < 0`, checks unenumerable) stays `-1` so the remedy remains conservative and
+ * never reopens blind. */
+export function headRunPresenceCount(
+  protocol: MergeProtocol,
+  state: { totalChecks: number; presentCheckNames: string[] },
+): number {
+  if (state.totalChecks < 0) return -1; // token mode → unknown → conservative
+  if (protocol.requiredChecks.length === 0) return state.totalChecks;
+  return presentRequiredCheckCount(protocol, state.presentCheckNames);
+}
+
 /** Whether the merge poller should produce a synthetic fresh head run *now*, and how.
  *
- * Fires only when the protocol asks for a fresh run AND the PR currently has **no head check run
- * at all** (`totalChecks === 0`) while GitHub still reports it un-landable-but-not-conflicting
+ * Fires only when the protocol asks for a fresh run AND the PR currently has **no required head
+ * run** (`headRunCount === 0`) while GitHub still reports it un-landable-but-not-conflicting
  * (`waiting`). That is exactly the frugal-CI stuck state: review converged, the last push produced
- * no run, so branch protection's required checks read as *expected* forever. Once a run exists for
- * the current head (`totalChecks > 0`, pending or done), or this same head already got its nudge,
- * this returns `null`, so the poller never re-triggers inside one landing attempt. A rebase changes
- * `headRefOid`, so the decision is re-derived and can fire again for the fresh post-rebase head.
- * A genuinely-failing check (`blocked`) is left to the fix-ci arm, a conflict (`conflict`) to the
- * rebase arm (#42). */
+ * no run, so branch protection's required checks read as *expected* forever. `headRunCount` is the
+ * required-check-aware presence count from {@link headRunPresenceCount} — NOT the raw rollup
+ * length — so an incidental always-on check (e.g. Mergify's "Merge Queue") does not read as "a run
+ * already exists". Once the required run is present (`headRunCount > 0`, pending or done), or this
+ * same head already got its nudge, this returns `null`, so the poller never re-triggers inside one
+ * landing attempt. A rebase changes `headRefOid`, so the decision is re-derived and can fire again
+ * for the fresh post-rebase head. A genuinely-failing check (`blocked`) is left to the fix-ci arm,
+ * a conflict (`conflict`) to the rebase arm (#42). */
 export function freshHeadRunAction(
   protocol: MergeProtocol,
   verdict: "ready" | "waiting" | "conflict" | "blocked",
-  totalChecks: number,
+  headRunCount: number,
   isDraft: boolean,
   attempt: FreshHeadRunAttempt = {},
 ): "ready" | "reopen" | null {
   if (protocol.freshHeadRun === "none") return null;
   if (verdict !== "waiting") return null; // ready = go land; blocked/conflict = other arms
-  if (totalChecks !== 0) return null; // a run already exists (or unknown in token mode) → wait
+  if (headRunCount !== 0) return null; // required run already present (or unknown in token mode) → wait
   if (attempt.headRefOid && attempt.headRefOid === attempt.lastActionHeadRefOid) return null;
   switch (protocol.freshHeadRun) {
     case "ready":

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

@@ -20,7 +20,7 @@ import {
   requestCopilotReview,
 } from "./github.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
-import { freshHeadRunAction, loadMergeProtocol } from "./mergeProtocol.ts";
+import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
 import { plans, planTaskDeps, planTasks } from "./plan.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.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,
@@ -686,14 +691,17 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
       const verdict = classifyMergeability(st);
       if (verdict === "waiting") {
         // Frugal-CI remedy (#43): when the repo publishes a merge protocol that wants a fresh
-        // head run and the PR has NO head run at all, review has converged but the last push
+        // head run and the PR has NO required head run yet, review has converged but the last push
         // produced no CI run — so branch protection's required checks read as "expected" forever
-        // and this PR would wait indefinitely. Produce a fresh `pull_request` run once per head
-        // (mark ready / close+reopen); rebases change `headRefOid`, so downstream merge-train PRs
-        // get a new nudge after every post-rebase landing attempt.
+        // and this PR would wait indefinitely. Judge "no run yet" by the protocol's *required*
+        // checks (headRunPresenceCount), not the raw rollup length, so an incidental always-on
+        // check (e.g. Mergify's "Merge Queue") doesn't mask a missing run. Produce a fresh
+        // `pull_request` run once per head (mark ready / close+reopen); rebases change
+        // `headRefOid`, so downstream merge-train PRs get a new nudge after every post-rebase
+        // landing attempt.
         const protocol = await loadMergeProtocol(repo, token).catch(() => null);
         if (protocol) {
-          const action = freshHeadRunAction(protocol, verdict, st.totalChecks, st.isDraft, {
+          const action = freshHeadRunAction(protocol, verdict, headRunPresenceCount(protocol, st), st.isDraft, {
             headRefOid: st.headRefOid,
             lastActionHeadRefOid: pr.fresh_head_run_head,
           });

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.2",
+  "version": "0.40.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",
@@ -45,7 +45,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts main.ts"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.38.0"
+    "@nanobpm/urban": "^0.40.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

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,