@nanobpm/nano-workforce 0.189.3 → 0.190.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.190.0](https://github.com/nanobpm/nano-workforce/compare/v0.189.3...v0.190.0) (2026-09-21)
+
+### Features
+
+* **ui:** make Convergence auto-merge opt-in ([#752](https://github.com/nanobpm/nano-workforce/issues/752)) ([db18b17](https://github.com/nanobpm/nano-workforce/commit/db18b17ceadc1cccd48e50a12c98d867f657f3d5)), closes [#751](https://github.com/nanobpm/nano-workforce/issues/751)
+
 ## [0.189.3](https://github.com/nanobpm/nano-workforce/compare/v0.189.2...v0.189.3) (2026-09-20)
 
 ### Bug Fixes

package/README.md

@@ -285,9 +285,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.
+A single submission can choose its merge behavior explicitly with the positive
+`autoMerge` field on the `start/convergence-loop` request: `false` stops at
+`converged` regardless of the global default, while `true` enables the merge-loop
+after convergence only when `NANO_PR_AUTO_MERGE` is enabled.
 
 ### Fleet mode: hand it an issue (plan → implement → converge)
 
@@ -356,7 +357,7 @@ agent at that URL to author, compile, and submit a graph unaided. See
 | `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 (`x-hook-secret`) for guarded operations (e.g. `GET /app/api/agent`, `/app/api/version`, `/app/api/status`); unset = open |
-| `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_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only). Per-submit override via the positive `autoMerge` field on `start/convergence-loop` |
 | `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

@@ -582,10 +582,10 @@ 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).
+A per-submit `autoMerge` setting on the `start/convergence-loop` request is the preferred
+positive control: `false` pins that PR to review-only regardless of the global default, while
+`true` enables the merge-loop after convergence only when `NANO_PR_AUTO_MERGE` is on. No per-submit
+setting forces the merge stage on when the global toggle is off.
 
 Flow:
 
@@ -691,7 +691,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 (`x-hook-secret`) for guarded operations (e.g. `/app/api/agent`, `/app/api/version`, `/app/api/status`) |
-| `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `convergeOnly: true` override) |
+| `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `autoMerge: false` override) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |
 | `NANO_PR_REVIEW_WAIT_TIMEOUT` | PT30M | ISO-8601 wait before a stalled review escalates (timer arm of the `wait-review` event-based gateway); malformed → default |

package/app/agentGuide.ts

@@ -31,7 +31,7 @@ const RAW_GUIDE: string = (() => {
       "Key endpoints (under the app control-API base `__BASE__`):",
       "- `GET /status` — every PR in flight, with its engine `processKey` and any open escalation.",
       "- `GET /version` — which code is live.",
-      "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
+      "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, autoMerge?, maxRounds?, dependsOn? }`; `autoMerge` is the positive per-request merge control).",
       "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue, baseBranch }` or `{ url, baseBranch }`; base is required — a missing `epic/*` base is auto-created, and `confirmDefaultBase`/`allowSharedBase` gate the default-branch and shared-base cases — see ADR 0003).",
       "- `POST /actions/complete-user-task` — answer an escalation (`{ userTaskKey, variables }`); the parked user task's key comes from `GET /status`/the Tasks inbox, and the typed variables match its `.form` (e.g. a PR escalation's `{ answer }`).",
       "- `POST /actions/message` — publish a BPMN message (optionally correlated) into the engine.",

package/app/deliveryGraphVocabulary.ts

@@ -67,7 +67,7 @@ export interface WaitProbeEntry {
 export interface ConnectorTargetEntry {
   target: string;
   status: "real" | "forward-declared";
-  convergeOnlyDefault?: boolean;
+  autoMergeDefault?: boolean;
   summary: string;
 }
 
@@ -143,7 +143,7 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
     mayEmit: true,
     summary:
       "An automated, side-effecting outbound action. `payload` for a converge target is " +
-      "`{ pr, convergeOnly?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
+      "`{ pr, autoMerge?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
       "reference, or omitted to auto-bind the single incoming `pr` fact). Carries a `dedupeKey` " +
       "(at-least-once safe). See connectorTargets for which targets are real vs. forward-declared.",
   },
@@ -218,13 +218,13 @@ const REAL_CONNECTOR_TARGETS: ConnectorTargetEntry[] = [
   {
     target: CONVERGE_TARGET,
     status: "real",
-    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_TARGET),
-    summary: "Converge-only: drive review convergence and STOP at `converged`, never handing off to the merge loop.",
+    autoMergeDefault: !convergeOnlyForTarget(CONVERGE_TARGET),
+    summary: "Review-only: drive convergence and STOP at `converged`, never handing off to the merge loop.",
   },
   {
     target: CONVERGE_MERGE_TARGET,
     status: "real",
-    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_MERGE_TARGET),
+    autoMergeDefault: !convergeOnlyForTarget(CONVERGE_MERGE_TARGET),
     summary:
       "Unit-level land: drive review convergence AND the merge loop, landing the PR onto its OWN base branch " +
       "(for a unit inside an epic that base is the epic integration branch, never `main` directly).",
@@ -232,7 +232,7 @@ const REAL_CONNECTOR_TARGETS: ConnectorTargetEntry[] = [
   {
     target: MERGE_MAIN_TARGET,
     status: "real",
-    convergeOnlyDefault: convergeOnlyForTarget(MERGE_MAIN_TARGET),
+    autoMergeDefault: !convergeOnlyForTarget(MERGE_MAIN_TARGET),
     summary:
       "Graph-level top-level land (two-level merge, ADR 0006 §3): land the graph/epic INTEGRATION PR onto `main`. " +
       "Dispatch-identical to `converge-merge`; the distinction is the LEVEL, kept a first-class literal.",

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -113,7 +113,7 @@ The closed set (extensible only by a deliberate ADR/PR, never by graph authors):
 > PR back to `converging`. `submitPr`'s own `prKey` idempotency additionally makes a resumed re-perform
 > double-safe on a still-live row. This retires the manual `land-*` human gate whose only job was "go run convergence
 > yourself" — the canonical shape is now `agent (opens PR) → connector[converge-merge] →
-> wait[pr, merged]` with no human node. The payload is `{ pr, convergeOnly?, dependsOn? }`; the `pr`
+> wait[pr, merged]` with no human node. The payload is `{ pr, autoMerge?, dependsOn? }`; the `pr`
 > may be a literal `owner/repo#N`, a `<node>.pr` fact reference late-bound from an upstream `agent`
 > node's emitted `pr` fact, or omitted to auto-bind the single incoming `pr` fact (issue #548 —
 > shipped: the connector resolves it via `resolveConvergePr`, and the `wait[pr]` target is late-bound

package/docs/agent-guide.md

@@ -73,7 +73,7 @@ The body is flat. Fields:
 | field | type | meaning |
 |---|---|---|
 | `pr` (or `url`) | string | the PR — `owner/repo#123` or a full PR URL. Required. |
-| `convergeOnly` | boolean | **`true` = review only.** The PR stops at `converged` and is **never** handed to the merge loop, even when `NANO_PR_AUTO_MERGE` is on. Omit / `false` = converge **then merge**. |
+| `autoMerge` | boolean | **Positive per-request setting.** `false` = review only, stopping at `converged`, regardless of the global default; `true` = converge **then merge** when `NANO_PR_AUTO_MERGE` is enabled. |
 | `maxRounds` | integer | per-submit cap before escalating (clamped 1–100; default from `NANO_PR_MAX_ROUNDS`, 20). |
 | `dependsOn` | string[] | other `prKey`s that must land before this one merges (merge-loop barrier). |
 
@@ -84,12 +84,12 @@ The body is flat. Fields:
 # or is only after a review pass):
 curl -sS -X POST __BASE__/actions/start/convergence-loop \
   -H 'content-type: application/json' \
-  -d '{ "pr": "owner/repo#123", "convergeOnly": true }'
+  -d '{ "pr": "owner/repo#123", "autoMerge": false }'
 
 # Converge then merge, with a dependency barrier and a tighter round cap:
 curl -sS -X POST __BASE__/actions/start/convergence-loop \
   -H 'content-type: application/json' \
-  -d '{ "pr": "owner/repo#42", "maxRounds": 8, "dependsOn": ["owner/repo#40"] }'
+  -d '{ "pr": "owner/repo#42", "autoMerge": true, "maxRounds": 8, "dependsOn": ["owner/repo#40"] }'
 ```
 
 Submitting is **idempotent on the PR key** — re-POSTing the same PR refreshes the
@@ -311,7 +311,7 @@ the answer becomes the agent's next-round context.
 ```
  submit ──► convergence-loop
    round (senior:pr-review) ──► addressed ──► wait review-ready ─┐
-                             ├─ converged  ──► finalize ──► merge-loop (unless convergeOnly)
+                             ├─ converged  ──► finalize ──► merge-loop (when autoMerge and NANO_PR_AUTO_MERGE are enabled)
                              └─ needs_input/blocked ──► escalate ──► wait-answer userTask (task inbox)
  merge-loop: wait deps ─► arm merge ─► (queue-aware) merge / land
              blocked (CI red) ─► senior:fix-ci ─► retry     conflict ─► senior:rebase ─► retry
@@ -774,13 +774,13 @@ only job was "go run convergence yourself".
 - **`converge-merge`** — the **unit-level** land: drive review convergence **and then the merge
   loop**, landing the PR onto **its own base branch** (for a unit inside an epic that base is the
   epic integration branch, never `main` directly — ADR 0003 base-branch admission). Equivalent to a
-  submit with `convergeOnly: false`.
+  submit with `autoMerge: true`.
 - **`merge-main`** — the **graph-level** top-level land: the second level of the two-level merge
   (ADR 0006 §3), landing the graph/epic **integration** PR onto **`main`**. Dispatch-identical to
   `converge-merge` (both enroll + merge); the distinction is the *level*, kept a first-class literal
   so the two levels are authored explicitly rather than left emergent.
 - **`converge`** — **converge-only**: drive review convergence and stop at `converged`, never
-  handing off to the merge loop (equivalent to `convergeOnly: true`).
+  handing off to the merge loop (equivalent to `autoMerge: false`).
 
 > **converge/merge are cell POLICY, not raw nodes.** A raw `senior:converge` / `senior:merge`
 > **agent** job is **not expressible** — the compiler rejects it (`raw-converge-node`). Express
@@ -788,10 +788,10 @@ only job was "go run convergence yourself".
 > policy flags (`merge` requires `converge`), or, for enrolling an already-open PR, the
 > `connector` targets above (ADR 0006 §3 / S5).
 
-**Payload:** `{ pr: "owner/repo#123", convergeOnly?: boolean, dependsOn?: string[] }`. `pr` is
+**Payload:** `{ pr: "owner/repo#123", autoMerge?: boolean, dependsOn?: string[] }`. `pr` is
 required (a literal `owner/repo#N`, identical to how a `wait: pr` node targets a known PR).
-`convergeOnly` defaults from the target and may be overridden per-node; `dependsOn` is unioned
-into the PR's merge-stage dependency set. The enrollment is idempotent (the connector's
+`autoMerge` defaults from the target and may be overridden per-node; `dependsOn` is unioned into
+the PR's merge-stage dependency set. The enrollment is idempotent (the connector's
 at-least-once dedupe fence **plus** `submitPr`'s own `prKey` idempotency), so a graph resume /
 redelivery never double-enrolls.
 

package/openapi.yaml

@@ -1823,11 +1823,13 @@ components:
           type: integer
           minimum: 1
           description: Values above 100 are accepted and clamped to 100 by the delegate.
+        autoMerge:
+          type: boolean
+          description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
         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).
+          deprecated: true
+          description: "Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`."
     ConvergenceStartByUrl:
       type: object
       additionalProperties: false
@@ -1845,11 +1847,13 @@ components:
           type: integer
           minimum: 1
           description: Values above 100 are accepted and clamped to 100 by the delegate.
+        autoMerge:
+          type: boolean
+          description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
         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).
+          deprecated: true
+          description: "Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`."
     PlanStart:
       description: The start-plan-fanout request body. Names the target issue by EXACTLY ONE of
         `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a REQUIRED
@@ -3435,8 +3439,8 @@ components:
         autoMerge:
           type: boolean
           description: >-
-            When true (and `converge` is true), drive the merge-loop after convergence — mirrors
-            `convergeOnly`/`NANO_PR_AUTO_MERGE` inverted. When false the run stops at `converged`.
+            When true (and `converge` is true), drive the merge-loop after convergence only when
+            `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`.
             Moot when `converge` is false.
         confirmDefaultBase:
           type: boolean
@@ -4573,9 +4577,13 @@ paths:
                       type: integer
                       minimum: 1
                       description: Values above 100 are accepted and clamped to 100 by the delegate.
+                    autoMerge:
+                      type: boolean
+                      description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
                     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).
+                      deprecated: true
+                      description: 'Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`.'
                 - type: object
                   additionalProperties: false
                   required:
@@ -4592,9 +4600,13 @@ paths:
                       type: integer
                       minimum: 1
                       description: Values above 100 are accepted and clamped to 100 by the delegate.
+                    autoMerge:
+                      type: boolean
+                      description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
                     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).
+                      deprecated: true
+                      description: 'Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`.'
               type: object
               # END generated:mcp-body
       responses:
@@ -5809,9 +5821,9 @@ paths:
                           type: string
                           enum: [real, forward-declared]
                           description: real ⇒ dispatches a real side effect; forward-declared ⇒ a no-op stub.
-                        convergeOnlyDefault:
+                        autoMergeDefault:
                           type: boolean
-                          description: The default `convergeOnly` for a real converge target.
+                          description: The default `autoMerge` for a real converge target.
                         summary:
                           type: string
                           description: What the target does.
@@ -5872,7 +5884,7 @@ paths:
                       optionalFields: [dedupeKey, payload]
                       sideEffecting: true
                       mayEmit: true
-                      summary: "An automated outbound action; payload for a converge target is { pr, convergeOnly?, dependsOn? }."
+                      summary: "An automated outbound action; payload for a converge target is { pr, autoMerge?, dependsOn? }."
                   factTypes: [string, number, boolean, artifact, version, url, pr]
                   guardScalarTypes: [string, number, boolean]
                   waitProbeKinds:
@@ -5893,15 +5905,15 @@ paths:
                   connectorTargets:
                     - target: converge
                       status: real
-                      convergeOnlyDefault: true
+                      autoMergeDefault: false
                       summary: "Converge-only: drive review convergence and stop at converged."
                     - target: converge-merge
                       status: real
-                      convergeOnlyDefault: false
+                      autoMergeDefault: true
                       summary: "Unit-level land: converge AND merge onto the PR's own base branch."
                     - target: merge-main
                       status: real
-                      convergeOnlyDefault: false
+                      autoMergeDefault: true
                       summary: "Graph-level top-level land onto main (two-level merge)."
                     - target: "<any other target>"
                       status: forward-declared
@@ -6168,7 +6180,7 @@ paths:
                       description: When true, hand the opened PR to the convergence loop (review rounds) as a follow-on step. When false (default) the run ends at "PR raised, not reviewed".
                     autoMerge:
                       type: boolean
-                      description: When true (and `converge` is true), drive the merge-loop after convergence — mirrors `convergeOnly`/`NANO_PR_AUTO_MERGE` inverted. When false the run stops at `converged`. Moot when `converge` is false.
+                      description: When true (and `converge` is true), drive the merge-loop after convergence only when `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`. Moot when `converge` is false.
                     confirmDefaultBase:
                       type: boolean
                       description: Acknowledge that `baseBranch` is the repository default branch (the PR would target it directly). See `PlanStartByIssue.confirmDefaultBase`.

package/operations/getAgentInstructions.test.ts

@@ -40,7 +40,8 @@ test("the guide covers every capability the endpoint promises", async () => {
   const md = ((await handler(input(), app)) as any).body.instructions as string;
   // Submit a PR (converge vs. merge), submit an epic, answer escalations…
   assert(md.includes("start/convergence-loop"), "covers submitting a PR for convergence");
-  assert(md.includes("convergeOnly"), "documents review-only vs. merge");
+  assert(md.includes("autoMerge"), "documents the per-request merge control");
+  assert(!md.includes("convergeOnly"), "does not expose the legacy merge control in agent guidance");
   assert(md.includes("start/plan-fanout"), "covers submitting an epic");
   assert(md.includes("complete-user-task"), "covers answering escalations via the native user-task door");
   // …debug the system.

package/operations/startAndMessage.test.ts

@@ -143,15 +143,57 @@ test("startConvergenceLoop forwards convergeOnly:true to the loop", async () =>
   });
 });
 
+test("startConvergenceLoop maps autoMerge:true to merge-enabled convergence", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureApp();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#9", autoMerge: true }), capApp);
+    assertEquals((res as any).status, 202);
+    assertEquals(get(), false);
+  });
+});
+
+test("startConvergenceLoop maps autoMerge:false to review-only convergence", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureApp();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#10", autoMerge: false }), capApp);
+    assertEquals((res as any).status, 202);
+    assertEquals(get(), true);
+  });
+});
+
+test("startConvergenceLoop lets autoMerge override the legacy convergeOnly alias", async () => {
+  await withGithubOff(async () => {
+    const merge = captureApp();
+    const mergeRes = await startConvergenceLoop(
+      input({ pr: "owner/repo#13", autoMerge: true, convergeOnly: true }),
+      merge.app,
+    );
+    assertEquals((mergeRes as any).status, 202);
+    assertEquals(merge.get(), false);
+
+    const review = captureApp();
+    const reviewRes = await startConvergenceLoop(
+      input({ pr: "owner/repo#14", autoMerge: false, convergeOnly: false }),
+      review.app,
+    );
+    assertEquals((reviewRes as any).status, 202);
+    assertEquals(review.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);
+    await startConvergenceLoop(input({ pr: "owner/repo#11" }), omitted.app);
     assertEquals(omitted.get(), false);
 
     const stringy = captureApp();
-    await startConvergenceLoop(input({ pr: "owner/repo#10", convergeOnly: "true" }), stringy.app);
+    await startConvergenceLoop(input({ pr: "owner/repo#12", convergeOnly: "true" }), stringy.app);
     assertEquals(stringy.get(), false);
+
+    const stringyAutoMerge = captureApp();
+    await startConvergenceLoop(input({ pr: "owner/repo#15", autoMerge: "true" }), stringyAutoMerge.app);
+    assertEquals(stringyAutoMerge.get(), false);
   });
 });
 

package/operations/startConvergenceLoop.ts

@@ -3,13 +3,15 @@
 // 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?, 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 body is a `oneOf` — EXACTLY
-// ONE of `pr` or `url` — so the runtime rejects an empty or ambiguous target at the edge (a 400 that
-// names the allowed shapes); this delegate no longer coalesces `pr ?? url`, it just narrows the
-// validated variant. It keeps the PR-parse guard because the reference FORMAT (owner/repo#123 or a
-// URL) is app logic the JSON schema can't express — an unparseable reference is a 400.
+// The request body is FLAT (`{ pr | url, dependsOn?, maxRounds?, autoMerge?, 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. `autoMerge` is
+// the positive, preferred form for UI/API callers; `convergeOnly` remains a legacy negative alias.
+// When both are present, `autoMerge` wins. The body is a `oneOf` — EXACTLY ONE of `pr` or `url` — so
+// the runtime rejects an empty or ambiguous target at the edge (a 400 that names the allowed
+// shapes); this delegate no longer coalesces `pr ?? url`, it just narrows the validated variant. It
+// keeps the PR-parse guard because the reference FORMAT (owner/repo#123 or a URL) is app logic the
+// JSON schema can't express — an unparseable reference is a 400.
 
 import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
@@ -29,9 +31,10 @@ export default defineOperation("startConvergenceLoop", async ({ body }, app) =>
   }
   const dependsOn = body.dependsOn ?? [];
   const maxRounds = clampRounds(body.maxRounds, MAX_ROUNDS);
-  // 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 = body.convergeOnly === true;
+  // Prefer the positive autoMerge form so an unchecked UI box is explicitly review-only. Legacy
+  // callers that omit autoMerge retain the existing convergeOnly/global-default behavior.
+  const hasAutoMerge = typeof body.autoMerge === "boolean";
+  const convergeOnly = hasAutoMerge ? body.autoMerge !== true : body.convergeOnly === true;
   const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly);
   app.log.info("convergence loop started", {
     prKey: parsed.prKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.189.3",
+  "version": "0.190.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/home.page.json

@@ -105,8 +105,8 @@
             "type": "number"
           },
           {
-            "key": "convergeOnly",
-            "label": "Converge only \u2014 stop at review consensus, do not merge",
+            "key": "autoMerge",
+            "label": "Auto-merge \u2014 after convergence, drive the merge-loop",
             "type": "checkbox"
           }
         ]

package/workers/delivery-connector/worker.test.ts

@@ -149,6 +149,14 @@ test("readConvergeInput: an explicit payload.convergeOnly overrides the target d
   assertEquals(r.dependsOn, ["owner/repo#5"], "non-string dependsOn entries are dropped");
 });
 
+test("readConvergeInput: autoMerge is the positive per-dispatch control", () => {
+  const merge = readConvergeInput("converge", { pr: "owner/repo#7", autoMerge: true }, null);
+  assertEquals(merge.convergeOnly, false);
+
+  const review = readConvergeInput("converge-merge", { pr: "owner/repo#7", autoMerge: false }, null);
+  assertEquals(review.convergeOnly, true);
+});
+
 test("readConvergeInput: a missing / unparseable pr fails CLOSED (a converge connector with no target PR is meaningless)", () => {
   assertThrows(() => readConvergeInput("converge-merge", null, null), Error, "payload.pr");
   assertThrows(() => readConvergeInput("converge-merge", {}, null), Error, "payload.pr");

package/workers/delivery-connector/worker.ts

@@ -76,13 +76,14 @@ export function safeStringify(value: unknown): string {
   }
 }
 
-/** Parse + validate the converge connector's payload (`{ pr, convergeOnly?, dependsOn? }`) for a
+/** Parse + validate the converge connector's payload (`{ pr, autoMerge?, dependsOn? }`) for a
  * `converge` / `converge-merge` / `merge-main` target. `pr` is REQUIRED and must parse to a canonical `owner/repo#N`
  * (fail CLOSED — a converge connector with no target PR is meaningless and could never enroll).
- * `convergeOnly` DEFAULTS from the target (`converge` → review-only `true`; `converge-merge`/`merge-main` → drive
- * the merge loop `false`) and may be overridden per-dispatch by an explicit boolean. `dependsOn` is an
- * optional list of PR refs unioned into the enrolled PR's merge-stage dependency set (only non-string
- * entries are dropped; `submitPr` itself ignores unparseable refs). Exported for unit coverage.
+ * `autoMerge` DEFAULTS from the target (`converge` → `false`; `converge-merge`/`merge-main` → `true`) and
+ * may be overridden per-dispatch by an explicit boolean. The deprecated `convergeOnly` alias is still
+ * accepted for compatibility. `dependsOn` is an optional list of PR refs unioned into the enrolled PR's
+ * merge-stage dependency set (only non-string entries are dropped; `submitPr` itself ignores unparseable
+ * refs). Exported for unit coverage.
  *
  * `pr` may be sourced three ways (issue #548), resolved by {@link resolveConvergePr} against the
  * threaded `boundFacts` BEFORE parsing: a LITERAL `owner/repo#N`, an explicit fact REFERENCE
@@ -104,7 +105,13 @@ export function readConvergeInput(
         `bound from an upstream \`agent\` node (got ${safeStringify(prValue ?? null)})`,
     );
   }
-  const convergeOnly = typeof p.convergeOnly === "boolean" ? p.convergeOnly : convergeOnlyForTarget(target);
+  const autoMerge =
+    typeof p.autoMerge === "boolean"
+      ? p.autoMerge
+      : typeof p.convergeOnly === "boolean"
+        ? !p.convergeOnly
+        : !convergeOnlyForTarget(target);
+  const convergeOnly = !autoMerge;
   const dependsOn = Array.isArray(p.dependsOn) ? p.dependsOn.filter((d): d is string => typeof d === "string") : [];
   return { parsed, convergeOnly, dependsOn };
 }