@nanobpm/nano-workforce 0.189.2 → 0.190.0

package/db/migrations/112_feature_read_model_opened_midhandoff.sql

@@ -0,0 +1,63 @@
+-- Feature-run read model: exclude a MID-HANDOFF `opened` run from the `list_bucket` / `ack_open`
+-- DISMISSABLE-terminal predicate (issue #808 follow-up). SUPERSEDES 111's VIEW body — every DERIVED
+-- column is emitted VERBATIM from the ONE declaration in app/featureReadModel.ts, now with `list_bucket`/
+-- `ack_open` driven by the `featureDismissableTerminal` PREDICATE instead of a plain status set. 111 is a
+-- MERGED, IMMUTABLE migration — never edited; this is a NEW migration superseding its VIEW body (the same
+-- pattern by which 111 superseded 099, 099 superseded 081, 081 superseded 076).
+--
+-- WHY. 111 (issue #808) made EVERY `opened` row dismissable-terminal so a finished raise-only run stops
+-- wedging in Active. But `record-feature` writes `status="opened"` for a converge-REQUESTED run TOO,
+-- BEFORE the `gw-converge` gateway routes it into `converge-feature` (which flips it to `converging`).
+-- In that in-between window the row reads `opened` while the feature engine instance is still ACTIVE, so
+-- 111's "any opened is dismissable" rule offered Dismiss on an in-flight convergence handoff — and a
+-- premature ack there stamps `acknowledged_at`, which would later drag a still-converging run to History.
+-- This is the SAME mid-flight failure mode the epic read model already guards against by excluding its
+-- own `converging` delivery (app/planReadModel.ts / app/listBucket.ts). The feature row distinguishes the
+-- transient from a finished run by its own columns: a converge-requested run that actually handed off
+-- carries `converge=1 AND pr_key IS NOT NULL` — exactly the window to exclude. Every other `opened` stays
+-- dismissable: a raise-only run (`converge=0`), or a keyless `opened` that never satisfied the gateway's
+-- `prKey != null` and fell through to `End` (`pr_key IS NULL`).
+--
+-- Every DERIVED column below is emitted VERBATIM from `featureReadModel.sqlSelectFor(col,
+-- { baseAlias: "fr" })` (which ALSO drives the runtime TS via `fnFor`); the `stage`/`stage_state`/
+-- `stage_skipped`/`attention` bodies are UNCHANGED from 111 and only `list_bucket`/`ack_open` gain the
+-- mid-handoff exclusion. The drift guard (app/featureReadModel.test.ts) fails if this file stops matching
+-- the declaration, and `assertReadModelParity` proves the SQL and TS lowerings agree.
+--
+-- SEMANTICS unchanged from 111 EXCEPT the two mid-handoff-narrowed columns: the status-classifying
+-- columns still read the terminal-folded `feature_runs__tracking.derived_status`; base columns stay
+-- aliased identity pass-throughs; `acknowledged_at` still passes through so the read model can classify
+-- on it. The STAGE derivations are untouched, so a mid-handoff `opened` still renders `PR open`.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). `feature_runs__tracking` is the managed VIEW urban
+-- provisions at mount; SQLite does not validate a view body at CREATE time, so this migration (which
+-- runs before that mount) is created fine and resolves once the managed VIEW exists. The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after 111.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("fr"."derived_status" = 'converging'), 0) THEN 'Converging' WHEN COALESCE((COALESCE(("fr"."pr_key" <> ''), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) THEN 'PR open' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'running'), 0) OR COALESCE(("fr"."derived_status" = 'escalated'), 0) OR COALESCE(("fr"."derived_status" = 'awaiting_operator'), 0)), 0) THEN 'Implementing' ELSE 'Requested' END AS stage,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0)), 0) THEN 'ok' WHEN COALESCE(("fr"."derived_status" = 'blocked'), 0) THEN 'blocked' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN (NOT COALESCE("fr"."converge", 0)) THEN 'Converging Merging' WHEN (NOT COALESCE("fr"."auto_merge", 0)) THEN 'Merging' ELSE '' END AS stage_skipped,
+  CASE WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-blocked'), 0)), 0)) THEN 'blocked' WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-escalation'), 0)), 0)) THEN '⚠' ELSE NULL END AS attention,
+  CASE WHEN COALESCE((COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) AND (NOT COALESCE(COALESCE((COALESCE(("fr"."derived_status" = 'opened'), 0) AND COALESCE(("fr"."converge" = 1), 0) AND COALESCE(("fr"."pr_key" = "fr"."pr_key"), 0)), 0), 0))), 0) AND COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) AND (NOT COALESCE(COALESCE((COALESCE(("fr"."derived_status" = 'opened'), 0) AND COALESCE(("fr"."converge" = 1), 0) AND COALESCE(("fr"."pr_key" = "fr"."pr_key"), 0)), 0), 0))), 0) AND (NOT COALESCE(COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM feature_runs__tracking fr;

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.2",
+  "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/converge-feature/worker.ts

@@ -30,14 +30,23 @@ const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
     await featureRuns(app.data).update(featureKey, { status: "opened", updated_at: new Date().toISOString() });
     return {};
   }
-  // `convergeOnly` is the inverse of auto-merge: converge-only stops at `converged`; auto-merge lets
-  // the merge-loop drive the merge. `submitPr` is idempotent on the PR key.
-  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge, featureKey);
+  // Write `converging` BEFORE enrolling the PR (issue #808 / PR #809 review). The old order —
+  // `submitPr` then the status write — left an `opened` + `converge=1` + `pr_key` window spanning an
+  // ALREADY-SUBMITTED, live PR: a terminate/crash in that gap stranded a row whose PR was live while
+  // `pollFeatureDelivery`'s handoff edge (edge 3) read the FEATURE instance state alone and wrongly
+  // folded it to `abandoned`. Flipping to `converging` first shrinks the interrupted-handoff window to
+  // the (now converging-owned) gap BEFORE `submitPr`, which `pollFeatureDelivery`'s converging edge
+  // (edge 1) heals by re-enrolling when the PR row is still missing (idempotent, mirroring the
+  // promotion-PR re-enroll in `pollPromotion`). The reorder is safe: `submitPr` is idempotent on the PR
+  // key (it early-returns `alreadyRunning` for a non-terminal PR), and a `converging` row is owned by
+  // edge (1), never by the handoff edge. `convergeOnly` is the inverse of auto-merge: converge-only
+  // stops at `converged`; auto-merge lets the merge-loop drive the merge.
   await featureRuns(app.data).update(featureKey, {
     status: "converging",
     pr_key: parsed.prKey,
     updated_at: new Date().toISOString(),
   });
+  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge, featureKey);
   app.log.info("converge-feature: enrolled PR into convergence loop", {
     featureKey,
     prKey: parsed.prKey,

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