@nanobpm/nano-workforce 0.204.1 → 0.205.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.205.0](https://github.com/nanobpm/nano-workforce/compare/v0.204.1...v0.205.0) (2026-11-04)
+
+### Features
+
+* **convergence:** make PR merge intent explicit — carry autoMerge end to end and show the effective merge policy in /status ([#917](https://github.com/nanobpm/nano-workforce/issues/917)) ([31e5b26](https://github.com/nanobpm/nano-workforce/commit/31e5b26f745f58920a9528bb448fe650af9631e3)), closes [#916](https://github.com/nanobpm/nano-workforce/issues/916) [#916](https://github.com/nanobpm/nano-workforce/issues/916)
+
 ## [0.204.1](https://github.com/nanobpm/nano-workforce/compare/v0.204.0...v0.204.1) (2026-11-04)
 
 ### Bug Fixes

package/SPEC.md

@@ -454,13 +454,16 @@ Notes:
   three because the unfiltered merge lets an input-echo replace the identity that
   `progress-check`, `converge-gate`, and `finalize` go on to read (a wrong
   `prNumber` would make `finalize` start the merge loop for the wrong PR) — **and**
-  the gate controls `humanApproval` and `convergeOnly`. These last two are
-  decision flags the loop acts on after the agent returns: `humanApproval = true`
-  routes a converged PR through the `gw-approval` human gate instead of
-  auto-merging, and `convergeOnly = true` ends a review-only run without ever
-  handing the PR to the merge loop. Left unguarded, a converged completion that
-  echoed `humanApproval: false` would **bypass** the approval gate, and one that
-  echoed `convergeOnly: false` would hand a review-only PR to the merge loop.
+  the gate controls `humanApproval` and the merge-intent pair `autoMerge` /
+  `convergeOnly`. These are decision flags the loop acts on after the agent
+  returns: `humanApproval = true` routes a converged PR through the
+  `gw-approval` human gate instead of auto-merging, and the merge intent —
+  `autoMerge` (the canonical positive variable, issue #916), with the legacy
+  inverted `convergeOnly` as its in-flight fallback — decides whether a
+  converged PR is handed to the merge loop at all. Left unguarded, a converged
+  completion that echoed `humanApproval: false` would **bypass** the approval
+  gate, and one that echoed `convergeOnly: false` would hand a review-only PR
+  to the merge loop.
   `convergeOnly` is a plain seeded constant, so the usual `=guardConvergeOnly`
   restore applies. `humanApproval` is the one engine-owned flag that is **also
   legitimately mutated mid-flight** — a gated caller that adopts a live loop

package/app/agentOutputEnvelope.test.ts

@@ -319,6 +319,56 @@ test("a scope-classify agent echoing humanApproval/convergeOnly cannot alter the
   assertEquals(await variableValue(engine, processInstanceKey, "convergeOnly"), true, "convergeOnly flag must be unchanged");
 });
 
+// Issue #916: `autoMerge` is the canonical positive merge intent and is engine-owned like
+// `convergeOnly` — an agent echo in EITHER direction must not flip it.
+for (const seeded of [true, false]) {
+  test(`a review-round agent echoing autoMerge:${!seeded} cannot overwrite seeded autoMerge:${seeded}`, async () => {
+    const { engine } = await boot({
+      vars: { autoMerge: seeded },
+      responses: { "senior:pr-review": { status: "addressed", summary: "fixed", autoMerge: !seeded } },
+    });
+    const incidents = await engine.searchIncidents();
+    assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+    assertEquals(instanceVars(engine).autoMerge, seeded, "seeded autoMerge must survive the agent echo");
+  });
+
+  test(`an adversarial-review agent echoing autoMerge:${!seeded} cannot overwrite seeded autoMerge:${seeded}`, async () => {
+    const { engine } = await boot({
+      vars: { advMax: 1, autoMerge: seeded },
+      responses: {
+        "senior:adversarial-review": { adversarialFindings: "", adversarialSummary: "clean", autoMerge: !seeded },
+      },
+    });
+    const incidents = await engine.searchIncidents();
+    assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+    assertEquals(instanceVars(engine).autoMerge, seeded, "seeded autoMerge must survive the agent echo");
+  });
+
+  test(`a scope-classify agent echoing autoMerge:${!seeded} cannot overwrite seeded autoMerge:${seeded}`, async () => {
+    const { engine, processInstanceKey } = await boot({
+      vars: { humanApproval: true, autoMerge: seeded },
+      responses: {
+        "senior:pr-review": { status: "converged", summary: "done" },
+        "senior:scope-classify": { scopeBlocked: false, scopeBlockReason: "", autoMerge: !seeded },
+      },
+    });
+    const incidents = await engine.searchIncidents();
+    assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+    assertEquals(await variableValue(engine, processInstanceKey, "autoMerge"), seeded, "autoMerge must be unchanged");
+  });
+}
+
+test("an agent echoing autoMerge on a legacy (autoMerge-absent) run cannot inject a merge intent", async () => {
+  const { engine } = await boot({
+    vars: { convergeOnly: true },
+    responses: { "senior:pr-review": { status: "addressed", summary: "fixed", autoMerge: true } },
+  });
+  const incidents = await engine.searchIncidents();
+  assertEquals(incidents.length, 0, `no incident; got: ${JSON.stringify(incidents)}`);
+  const v = instanceVars(engine).autoMerge;
+  assertEquals(v == null, true, `legacy run must keep autoMerge absent so the convergeOnly fallback applies; got ${v}`);
+});
+
 // ---------------------------------------------------------------------------
 // Issue #887 (round 4 — Copilot "previously missed"): `reviewStale` and
 // `roundEntryHead` are ALSO process-owned and readable by downstream decisions,

package/app/feature.ts

@@ -524,9 +524,9 @@ export async function startFeature(
           `(\`gh issue view ${parsed.number} -R ${parsed.repo}\`), implement it completely, ` +
           `and open exactly one pull request that closes it.`,
       },
-      // Follow-on knobs, read by the record/converge workers. `autoMerge` maps to submitPr's
-      // `convergeOnly` (inverted): converge-only stops at `converged`; auto-merge drives the
-      // merge-loop. `converge=false` ⇒ merge is moot.
+      // Follow-on knobs, read by the record/converge workers. `autoMerge` is the canonical
+      // positive merge intent (issue #916), threaded to `submitPr` as-is: converge-only stops at
+      // `converged`; auto-merge drives the merge-loop. `converge=false` ⇒ merge is moot.
       converge,
       autoMerge,
       // Park the converged PR at a human approval user task before the merge-loop (issue #826).

package/app/featureDelivery.test.ts

@@ -215,6 +215,8 @@ test("pollFeatureDelivery: the re-enroll keeps the run's human approval gate (is
   await pollFeatureDelivery(data, engine);
 
   assertEquals(vars?.convergeOnly, false);
+  // Issue #916: the healed enrollment also carries the canonical positive merge-intent variable.
+  assertEquals(vars?.autoMerge, true);
   assertEquals(vars?.humanApproval, true, "a healed enrollment must not silently drop the approval gate");
 });
 

package/app/mergeApproval.test.ts

@@ -80,7 +80,7 @@ test("with humanApproval a converged PR parks for a human, and approve finalizes
 });
 
 test("request changes sends the guidance to the review agent on the same PR, then asks again", async () => {
-  const { engine, answers } = await boot({ humanApproval: true });
+  const { engine, answers, processInstanceKey } = await boot({ humanApproval: true });
   const first = await openApproval(engine);
   assert(first !== undefined, "the approval task is open");
   await engine.completeUserTask(first, { mergeDecision: "revise", answer: "Rename foo to bar." });
@@ -92,6 +92,10 @@ test("request changes sends the guidance to the review agent on the same PR, the
   assertEquals(completions(engine, "persist-converged"), 0);
   const second = await openApproval(engine);
   assert(second !== undefined && second !== first, "approval is asked again after the revision");
+  // A revise is NOT an approval: the gate must stay set, so /status keeps reporting
+  // `blockedBy: "human-approval"` while the re-asked approval is outstanding (PR #917 review).
+  const [row] = await engine.searchVariables({ processInstanceKey: String(processInstanceKey), name: "humanApproval" });
+  assertEquals(row ? JSON.parse(row.value) : undefined, true, "a revise keeps the human-approval gate set");
 });
 
 test("a live ungated loop narrowed to humanApproval (a gated submitPr adopting it) parks for approval", async () => {
@@ -113,6 +117,21 @@ test("fail-closed: a completion without an explicit approve never merges", async
   assertEquals(completions(engine, "persist-converged"), 0);
 });
 
+test("an approve clears the humanApproval gate while finalization is still pending (PR #917 review)", async () => {
+  // The /status merge projection derives `blockedBy: "human-approval"` from the loop's
+  // `humanApproval` variable alone, so an approved PR whose `pr.finalize` handoff is still queued
+  // (or incidented) would otherwise keep reporting a human-approval blocker even though the
+  // approval is complete. Hold `pr.finalize` so the loop stays ACTIVE after the approve, then read
+  // the variable: it must be cleared by the approval itself, not by some later task.
+  const { engine, processInstanceKey } = await boot({ humanApproval: true }, ["pr.finalize"]);
+  const key = await openApproval(engine);
+  assert(key !== undefined, "the approval task is open");
+  await engine.completeUserTask(key, { mergeDecision: "approve" });
+  loop(engine).isActive().hasNoIncident();
+  const [row] = await engine.searchVariables({ processInstanceKey: String(processInstanceKey), name: "humanApproval" });
+  assertEquals(row ? JSON.parse(row.value) : undefined, false, "approval complete — the blocker must clear");
+});
+
 test("merge-approval is human-only, and its form requires guidance only for request changes", () => {
   assert(HUMAN_COMPLETABLE_ELEMENTS.has(PR_MERGE_APPROVAL_ELEMENT), "the human completer accepts it");
   assert(!ESCALATION_TASK_ELEMENTS.has(PR_MERGE_APPROVAL_ELEMENT), "an agent must never approve a merge");

package/app/mergeStatus.test.ts

@@ -0,0 +1,169 @@
+// Red/green for issue #916 — the effective merge policy must be VISIBLE on every PR status row.
+//
+// The defect: whether a PR run will merge was explicit nowhere an operator looks. The
+// convergence-loop instance carried only the INVERTED legacy `convergeOnly` variable (a feature
+// run's `autoMerge: true` became `convergeOnly: false`, so searching the loop's variables for
+// `autoMerge` found nothing and it looked as if auto-merge had been dropped), and the `/status`
+// projection (`activePrs`) carried no merge-intent field at all — `waiting_merge` only appears once
+// merging has STARTED. An operator concluded auto-merge was lost and wrote `autoMerge=true` onto a
+// running loop — a no-op write, because the loop had `convergeOnly=false` from the start.
+//
+// The fix projects a structured `merge` block onto every ActivePr:
+//   merge.requested — the run's merge intent: the canonical positive `autoMerge` process variable
+//     when present, falling back to the INVERSE of the legacy `convergeOnly` variable for in-flight
+//     loops seeded before `autoMerge` existed (and to `true` — the historical default — when the
+//     instance key is unreadable or carries neither variable).
+//   merge.enabled   — the deployment's global `NANO_PR_AUTO_MERGE` switch.
+//   merge.effective — requested && enabled && !humanApproval: the run merges with no human gate.
+//   merge.blockedBy — "env" | "human-approval" | null: WHY a requested merge will not proceed.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import { activePrs } from "./service.ts";
+
+function memTable(rows: any[], key: string) {
+  return {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    all: () => Promise.resolve([...rows]),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any) =>
+      Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+}
+
+type Stores = Record<string, { rows: any[]; key: string }>;
+
+function memData(stores: Stores) {
+  return {
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+  } as any;
+}
+
+/** A fake engine whose `searchVariables` serves the given per-instance variables. */
+function fakeEngine(varsByInstance: Record<string, Record<string, unknown>>) {
+  return {
+    searchVariables: (q: { processInstanceKey?: string; name?: string }) => {
+      const vars = varsByInstance[String(q.processInstanceKey)] ?? {};
+      return Promise.resolve(
+        Object.entries(vars)
+          .filter(([name]) => q.name == null || name === q.name)
+          .map(([name, v]) => ({ name, value: JSON.stringify(v) })),
+      );
+    },
+  } as any;
+}
+
+function prRow(over: Record<string, unknown>) {
+  return {
+    pr_key: "owner/repo#1",
+    repo: "owner/repo",
+    number: 1,
+    url: "https://github.com/owner/repo/pull/1",
+    title: "t",
+    status: "converging",
+    current_round: 1,
+    process_key: "PI-1",
+    updated_at: "2024-01-01",
+    ...over,
+  };
+}
+
+async function mergeOf(vars: Record<string, unknown>, rowOver: Record<string, unknown> = {}) {
+  return mergeOfWith({ activePrs }, vars, rowOver);
+}
+
+/** `mergeOf` against an explicitly-loaded service module — for the env-switched tests that import
+ *  a fresh copy of app/service.ts (e.g. `NANO_PR_AUTO_MERGE=0`). */
+async function mergeOfWith(
+  mod: Pick<typeof import("./service.ts"), "activePrs">,
+  vars: Record<string, unknown>,
+  rowOver: Record<string, unknown> = {},
+) {
+  const stores: Stores = {
+    pull_requests: { rows: [prRow(rowOver)], key: "pr_key" },
+    user_tasks: { rows: [], key: "id" },
+  };
+  const [pr] = await mod.activePrs(memData(stores), fakeEngine({ "PI-1": vars }));
+  return pr.merge;
+}
+
+// AUTO_MERGE is computed once at app/service.ts import time; the test env leaves NANO_PR_AUTO_MERGE
+// unset, so the global switch is ON here (the default).
+
+test("merge policy: a loop seeded autoMerge=true reads requested+effective (the #916 phantom)", async () => {
+  const merge = await mergeOf({ autoMerge: true, convergeOnly: false, humanApproval: false });
+  assertEquals(merge, { requested: true, enabled: true, effective: true, blockedBy: null });
+});
+
+test("merge policy: a legacy in-flight loop (convergeOnly only) derives requested from its inverse", async () => {
+  // Seeded BEFORE `autoMerge` existed: only the legacy inverted variable is present.
+  const review = await mergeOf({ convergeOnly: true });
+  assertEquals(review, { requested: false, enabled: true, effective: false, blockedBy: null });
+  const merging = await mergeOf({ convergeOnly: false });
+  assertEquals(merging, { requested: true, enabled: true, effective: true, blockedBy: null });
+});
+
+test("merge policy: humanApproval gates the effective merge and is named as the blocker", async () => {
+  const merge = await mergeOf({ autoMerge: true, humanApproval: true });
+  assertEquals(merge, { requested: true, enabled: true, effective: false, blockedBy: "human-approval" });
+});
+
+test("merge policy: an approved PR with finalization still pending reports no blocker (PR #917 review)", async () => {
+  // The `merge-approval` user task clears the loop's `humanApproval` variable on an explicit
+  // "approve" (convergence-loop.bpmn), so while `pr.finalize` is still queued or incidented the
+  // projection reads humanApproval=false and must NOT keep reporting a human-approval blocker for
+  // an approval that is already complete. (`status` stays non-terminal: `converged_at` is only
+  // stamped once `pr.finalize` actually runs.)
+  const merge = await mergeOf({ autoMerge: true, humanApproval: false }, { status: "converging" });
+  assertEquals(merge, { requested: true, enabled: true, effective: true, blockedBy: null });
+});
+
+test("merge policy: a review-only request reads requested=false (distinct from env/human blocking)", async () => {
+  const merge = await mergeOf({ autoMerge: false, convergeOnly: true });
+  assertEquals(merge, { requested: false, enabled: true, effective: false, blockedBy: null });
+});
+
+test("merge policy: no readable instance key (or neither variable) defaults to the historical merge default", async () => {
+  // A mid-handoff row (process_key null) or a legacy loop carrying neither variable: the pre-#916
+  // behaviour merged by default, so the projection must NOT read such a PR as review-only.
+  const stores: Stores = {
+    pull_requests: { rows: [prRow({ process_key: null })], key: "pr_key" },
+    user_tasks: { rows: [], key: "id" },
+  };
+  const [noKey] = await activePrs(memData(stores), fakeEngine({}));
+  assertEquals(noKey.merge, { requested: true, enabled: true, effective: true, blockedBy: null });
+  const bare = await mergeOf({});
+  assertEquals(bare, { requested: true, enabled: true, effective: true, blockedBy: null });
+});
+
+test("merge policy: NANO_PR_AUTO_MERGE=0 blocks a requested merge as env, never a review-only one", async () => {
+  // `AUTO_MERGE` is read once at app/service.ts import time, so load a fresh copy of the module
+  // under the env (the same pattern app/service.test.ts uses) — every other test here runs with
+  // the switch ON (the default) and none exercised `blockedBy: "env"` before this one.
+  const prev = process.env["NANO_PR_AUTO_MERGE"];
+  process.env["NANO_PR_AUTO_MERGE"] = "0";
+  try {
+    const mod: typeof import("./service.ts") = await import(`./service.ts?mergeStatusAutoMergeOff=${Date.now()}`);
+    const requested = await mergeOfWith(mod, { autoMerge: true, humanApproval: true });
+    assertEquals(requested, { requested: true, enabled: false, effective: false, blockedBy: "env" });
+    const reviewOnly = await mergeOfWith(mod, { autoMerge: false });
+    assertEquals(reviewOnly, { requested: false, enabled: false, effective: false, blockedBy: null });
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_AUTO_MERGE"];
+    else process.env["NANO_PR_AUTO_MERGE"] = prev;
+  }
+});

package/app/service.test.ts

@@ -1005,6 +1005,31 @@ test("submitPr defaults convergeOnly to false so the global auto-merge default g
   });
 });
 
+// Issue #916: the loop must ALSO carry the POSITIVE `autoMerge` variable — an operator searching a
+// live convergence loop's variables for `autoMerge` previously found nothing (only the inverted
+// `convergeOnly`), and concluded auto-merge had been dropped. `submitPr` seeds both, keeping them
+// consistent: `autoMerge` is canonical, `convergeOnly` its inverse mirror for in-flight compat.
+test("submitPr seeds the positive autoMerge variable alongside the convergeOnly mirror (issue #916)", async () => {
+  await withGithubOff(async () => {
+    const pr = (n: number) => ({ repo: "owner/repo", number: n, url: `https://github.com/owner/repo/pull/${n}`, prKey: `owner/repo#${n}` });
+    // Legacy positional form: convergeOnly=true ⇒ autoMerge=false (both seeded, consistent).
+    const legacy = captureVars();
+    await submitPr(legacy.data, legacy.engine, pr(30), [], 20, true);
+    assertEquals(legacy.get()?.autoMerge, false);
+    assertEquals(legacy.get()?.convergeOnly, true);
+    // Default (no override): merge intent on — the global default governs.
+    const dflt = captureVars();
+    await submitPr(dflt.data, dflt.engine, pr(31));
+    assertEquals(dflt.get()?.autoMerge, true);
+    assertEquals(dflt.get()?.convergeOnly, false);
+    // The positive trailing form wins over the legacy alias when both are supplied.
+    const both = captureVars();
+    await submitPr(both.data, both.engine, pr(32), [], 20, true, null, false, false, true);
+    assertEquals(both.get()?.autoMerge, true);
+    assertEquals(both.get()?.convergeOnly, false);
+  });
+});
+
 // #796 auto-ack budget seeding: `submitPr` is the ONLY production write that makes the retry budget
 // available to a fresh convergence instance — the engine behaviour tests seed `ackRetryRound` /
 // `ackRetryMax` directly and never exercise `submitPr`, so a regression dropping or misconfiguring

package/app/service.ts

@@ -627,9 +627,10 @@ export async function submitPr(
   rootRequestKey: string | null = null,
   humanApproval = false,
   autoResolveEscalations = false,
+  autoMerge?: boolean,
 ) {
   return withPrSubmitLock(parsed.prKey, () =>
-    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval, autoResolveEscalations),
+    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval, autoResolveEscalations, autoMerge),
   );
 }
 
@@ -643,11 +644,20 @@ async function submitPrCritical(
   rootRequestKey: string | null = null,
   humanApproval = false,
   autoResolveEscalations = false,
+  autoMerge?: boolean,
 ) {
+  // Merge intent (issue #916): `autoMerge` is the CANONICAL positive form end to end — the same name
+  // the feature/convergence-loop/plan-fanout doors accept. The legacy inverted `convergeOnly`
+  // positional remains as a fallback: an explicit `autoMerge` wins; otherwise intent derives from
+  // `convergeOnly`. The instance carries BOTH (below): `autoMerge` so the intent is searchable under
+  // its positive name, and the `convergeOnly` mirror so in-flight consumers (and the guard-restore
+  // ioMappings on the loop's agent tasks) keep working unchanged.
+  const mergeIntent = autoMerge ?? !convergeOnly;
+  const effectiveConvergeOnly = !mergeIntent;
   // Human approval before merge (issue #826) gates only a PR that `pr.finalize` would hand to the
-  // merge-loop — its own predicate, `AUTO_MERGE && convergeOnly !== true`. A run that won't merge
+  // merge-loop — its own predicate, `AUTO_MERGE && merge intent on`. A run that won't merge
   // (review-only, or the global switch off) must not park for a pointless approval.
-  const gated = humanApproval && !convergeOnly && AUTO_MERGE;
+  const gated = humanApproval && mergeIntent && AUTO_MERGE;
   const table = prs(data);
   const existing = await table.get(parsed.prKey);
   // ADR-0065: classify "already running" on the DERIVED terminal edge, not the base transient. A
@@ -818,10 +828,14 @@ async function submitPrCritical(
       // descendant (and any message it correlates) is stitched back to the originating request.
       // A human/webhook PR that is its own root carries its own `pr_key` (never NULL — see above).
       rootRequestKey: effectiveRoot,
-      // 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,
+      // Per-request merge intent (issue #916): `autoMerge` is the CANONICAL positive variable — the
+      // same name the doors accept — so a live loop's merge intent is searchable under `autoMerge`.
+      // `convergeOnly` is its inverse mirror, kept for in-flight compat: `pr.finalize` reads
+      // `autoMerge` first and falls back to `convergeOnly` when it is absent (a loop seeded before
+      // this variable existed). Merge intent only ever narrows (never forces merge on when the
+      // global NANO_PR_AUTO_MERGE switch is off).
+      autoMerge: mergeIntent,
+      convergeOnly: effectiveConvergeOnly,
       // Human approval before merge (issue #826): a converged PR parks at the `merge-approval` user
       // task before `pr.finalize` hands it to the merge-loop. Pinned off when the PR won't merge.
       humanApproval: gated,
@@ -1024,6 +1038,24 @@ export async function startMerge(
   return { prKey: pr.prKey, mergeProcessKey: processInstanceKey };
 }
 
+/** The effective merge policy for a PR run, surfaced on every `/status` row (issue #916). */
+export interface MergePolicy {
+  /** The run's merge intent: the canonical positive `autoMerge` process variable when present,
+   * else the inverse of the legacy `convergeOnly` variable (in-flight compat), else the historical
+   * default `true` when the instance key is unreadable or carries neither. */
+  requested: boolean;
+  /** The deployment's global `NANO_PR_AUTO_MERGE` switch. */
+  enabled: boolean;
+  /** `requested && enabled && !humanApproval` — the run merges with no further gate. */
+  effective: boolean;
+  /** WHY a requested merge will not proceed: the global env switch is off, or a human merge
+   * approval is outstanding. Null when the merge is effective or none was requested. The
+   * `merge-approval` task clears the loop's `humanApproval` variable on an explicit "approve"
+   * (convergence-loop.bpmn), so the blocker lifts as soon as approval is complete — even while
+   * the `pr.finalize` handoff is still queued or incidented. */
+  blockedBy: "env" | "human-approval" | null;
+}
+
 /** A PR currently in flight, as reported by the status endpoint. */
 export interface ActivePr {
   prKey: string;
@@ -1045,6 +1077,9 @@ export interface ActivePr {
   /** Whether this PR opted in to the escalation steward (issue #889) — its open escalations are
    * eligible for steward auto-resolution. Shown in `/status` per PR. */
   autoResolveEscalations: boolean;
+  /** The effective merge policy (issue #916): what the run intends (`requested`), what the
+   * deployment allows (`enabled`), and what will actually happen (`effective`/`blockedBy`). */
+  merge: MergePolicy;
 }
 
 /** Every tracked PR not in a terminal state (converged/abandoned), newest-updated first. Backs
@@ -1058,7 +1093,10 @@ export interface ActivePr {
  * Both loops park on a native user task answered through the one canonical `completeUserTask` door
  * (#256), so deriving from the read model surfaces BOTH loops' escalations uniformly. Once the task is
  * completed its row is removed, so `openEscalation` derives back to null. */
-export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
+export async function activePrs(
+  data: DataLayer,
+  engine?: Pick<EngineClient, "searchVariables">,
+): Promise<ActivePr[]> {
   const all = await prsTracking(data).all();
   const active = all
     // ADR-0065: classify "in flight" on the DERIVED terminal edge, not the base transient. A PR whose
@@ -1086,6 +1124,16 @@ export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
     if (openEscByPr.has(t.subject_key)) continue;
     openEscByPr.set(t.subject_key, toOpenEscalation(t));
   }
+  // Merge intent (issue #916): read the loop's `autoMerge` / `convergeOnly` / `humanApproval`
+  // variables per PR so the effective merge policy is visible without opening the engine. One
+  // best-effort read per PR; a failure (engine unreachable, instance gone) degrades to the
+  // historical default (merge requested) rather than failing the whole status read.
+  const mergeByPr = new Map<string, MergePolicy>();
+  await Promise.all(
+    active.map(async (p) => {
+      mergeByPr.set(p.pr_key, await mergePolicyFor(p.process_key ?? null, engine));
+    }),
+  );
   return active.map((p) => ({
     prKey: p.pr_key,
     repo: p.repo,
@@ -1101,9 +1149,67 @@ export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
     activeWorker: p.active_worker ?? null,
     leaseUntil: p.lease_until ?? null,
     autoResolveEscalations: p.auto_resolve_escalations === 1,
+    merge: mergeByPr.get(p.pr_key) ?? mergePolicyDefault(),
   }));
 }
 
+/** The default merge policy when no instance variables are readable (mid-handoff row, engine
+ * unreachable, or a legacy loop carrying neither variable): the pre-#916 behaviour merged by
+ * default, so the projection must NOT read such a PR as review-only. */
+function mergePolicyDefault(): MergePolicy {
+  return mergePolicyFrom(true, false);
+}
+
+/** Combine a merge intent + human-approval gate with the global switch into the effective policy.
+ *  `humanApproval` is the OUTSTANDING-approval signal: the loop seeds it when approval is required
+ *  and the `merge-approval` user task clears it on an explicit "approve", so an approved PR whose
+ *  finalization is still queued/incidented reads `effective` with no blocker rather than a stale
+ *  `blockedBy: "human-approval"`. */
+function mergePolicyFrom(requested: boolean, humanApproval: boolean): MergePolicy {
+  const enabled = AUTO_MERGE;
+  const effective = requested && enabled && !humanApproval;
+  const blockedBy = !requested ? null : !enabled ? "env" : humanApproval ? "human-approval" : null;
+  return { requested, enabled, effective, blockedBy };
+}
+
+/** Read one boolean process variable off a live instance; undefined when absent/unreadable. */
+async function readBoolVar(
+  engine: Pick<EngineClient, "searchVariables">,
+  processKey: string,
+  name: string,
+): Promise<boolean | undefined> {
+  const [row] = await engine.searchVariables({ processInstanceKey: processKey, name });
+  if (!row) return undefined;
+  try {
+    const v: unknown = JSON.parse(row.value);
+    return typeof v === "boolean" ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Derive a PR's effective merge policy from its loop's process variables (issue #916). The
+ * canonical positive `autoMerge` wins; the legacy inverted `convergeOnly` is the fallback for
+ * in-flight loops seeded before `autoMerge` existed. Best-effort: any read failure degrades to the
+ * historical default (merge requested) rather than failing the status read. */
+async function mergePolicyFor(
+  processKey: string | null,
+  engine: Pick<EngineClient, "searchVariables"> | undefined,
+): Promise<MergePolicy> {
+  if (processKey == null || !engine) return mergePolicyDefault();
+  try {
+    const [autoMerge, convergeOnly, humanApproval] = await Promise.all([
+      readBoolVar(engine, processKey, "autoMerge"),
+      readBoolVar(engine, processKey, "convergeOnly"),
+      readBoolVar(engine, processKey, "humanApproval"),
+    ]);
+    const requested = autoMerge ?? (convergeOnly === undefined ? true : !convergeOnly);
+    return mergePolicyFrom(requested, humanApproval === true);
+  } catch {
+    return mergePolicyDefault();
+  }
+}
+
 /** A delivery-graph run currently in flight, as reported by the status endpoint (issue #889 §1 —
  *  "Show it in `/status` for each PR or delivery"). Mirrors {@link ActivePr} for the delivery side. */
 export interface ActiveDelivery {
@@ -2784,13 +2890,16 @@ export async function pollFeatureDelivery(
             parsed,
             [],
             MAX_ROUNDS,
-            run.auto_merge !== 1,
+            false,
             run.feature_key,
             run.human_approval === 1,
             // Thread the run's escalation-steward opt-in (issue #889 review) so a re-enrolled PR
             // inherits the feature run's enrolment — and a partial-enrollment repair never overwrites
             // the PR row's previously persisted opt-in with the `false` default.
             run.auto_resolve_escalations === 1,
+            // Merge intent (issue #916): the canonical positive `autoMerge`, derived from the run's
+            // durable `auto_merge` flag (mirrors `converge-feature`).
+            run.auto_merge === 1,
           );
         }
       }

package/docs/agent-guide.md

@@ -31,6 +31,24 @@ Each `/status` entry carries `prKey` (`owner/repo#123`), `status`, `round`, `pro
 `activeWorker`/`leaseUntil` (an agent holds the round, or the job is just queued), and
 `updatedAt`.
 
+It also carries the run's **merge intent** as a structured `merge` block (so "will this PR
+merge?" is a read, not a guess):
+
+```json
+"merge": { "requested": true, "enabled": true, "effective": false, "blockedBy": "human-approval" }
+```
+
+| field | meaning |
+|---|---|
+| `requested` | the run's merge intent — the `autoMerge` process variable on its convergence loop (a loop seeded before that variable existed derives it from the inverse of the legacy flag). |
+| `enabled` | the deployment's global `NANO_PR_AUTO_MERGE` switch. |
+| `effective` | `requested && enabled && !humanApproval` — the run merges with no further gate. |
+| `blockedBy` | why a *requested* merge will not proceed: `"env"` (the global switch is off) or `"human-approval"` (parked at the merge-approval task). `null` when the merge is effective — and when the run is converge-only (`requested: false`), which is a *choice*, not a block. |
+
+The same intent is on the engine variables of the loop itself: query the instance
+(`processKey`) for `autoMerge` — it is always seeded, so a missing `autoMerge` means a loop
+started before this version (read `convergeOnly` and invert it there).
+
 ---
 
 ## 1. Submit a PR for review convergence
@@ -57,6 +75,16 @@ curl -sS -X POST __BASE__/actions/start/convergence-loop \
 Idempotent on the PR key: re-POSTing refreshes the record instead of starting a second
 loop. The 202 response echoes `prKey` and `processKey`.
 
+`autoMerge` must be a JSON **boolean** — a string (`"true"`) is a `400` at every start door
+(`startConvergenceLoop`, `startFeature`), never a silent review-only run. To *read* the intent
+back, use the `merge` block in `/status` (§0). There is **no supported way to flip merge
+intent on a running loop**. Direct variable writes onto a live instance (e.g. `autoMerge=true`)
+are **unsupported and timing-dependent, not reliable no-ops**: the agent tasks guard-restore the
+seeded value, so a write is usually overwritten — but a write that lands while the loop awaits
+merge approval is never restored and reaches `pr.finalize`, where it can change whether merging
+starts. To change the intent, cancel the run (`cancelInstance`, §7) and re-submit with the
+intent you want.
+
 ---
 
 ## 2. Submit an epic (plan → implement → converge)
@@ -174,6 +202,11 @@ PR `status` values: `converging` (round live), `waiting_review`, `escalated`, `c
 `waiting_deps` / `waiting_merge` / `queued` / `merging`, `merged`, `abandoned`. An
 **incident** (§5) can overlay any live status when the engine parks the token on a fault.
 
+The merge-stage statuses only ever appear when the run's merge policy is effective — read the
+`merge` block in `/status` (§0) to distinguish "merge requested but disabled by env"
+(`blockedBy: "env"`) and "waiting for human approval" (`blockedBy: "human-approval"`) from
+"converge-only" (`requested: false`).
+
 ---
 
 ## 5. Debug: find engine instances and relate them to PRs

package/openapi.yaml

@@ -92,6 +92,7 @@ components:
         - activeWorker
         - leaseUntil
         - autoResolveEscalations
+        - merge
       properties:
         prKey:
           type: string
@@ -155,6 +156,39 @@ components:
             Whether this PR's run opted into automatic escalation resolution by the escalation
             steward (issue #889). Derived from the subject row's durable `auto_resolve_escalations`
             flag, never a clobbered process variable.
+        merge:
+          type: object
+          additionalProperties: false
+          description: >-
+            The effective merge policy for this PR's run (issue #916). `requested` is the run's merge
+            intent — the canonical positive `autoMerge` process variable on its convergence loop
+            (falling back to the inverse of the legacy `convergeOnly` variable for a loop seeded
+            before `autoMerge` existed, and to the historical default `true` when the instance is
+            unreadable). `enabled` is the deployment's global `NANO_PR_AUTO_MERGE` switch.
+            `effective` is `requested && enabled && !humanApproval` — the run merges with no further
+            gate. `blockedBy` names WHY a requested merge will not proceed: `env` (the global switch
+            is off) or `human-approval` (parked at the merge-approval task); null when the merge is
+            effective or none was requested (converge-only).
+          required:
+            - requested
+            - enabled
+            - effective
+            - blockedBy
+          properties:
+            requested:
+              type: boolean
+              description: The run's merge intent (the loop's `autoMerge` variable, or the inverse of its legacy `convergeOnly`).
+            enabled:
+              type: boolean
+              description: The deployment's global NANO_PR_AUTO_MERGE switch.
+            effective:
+              type: boolean
+              description: requested && enabled && !humanApproval — the run merges with no further gate.
+            blockedBy:
+              type: string
+              nullable: true
+              enum: ["env", "human-approval", null]
+              description: Why a requested merge will not proceed; null when effective or converge-only.
     ActivePrList:
       type: object
       required:

package/operations/getAgentInstructions.test.ts

@@ -41,7 +41,22 @@ test("the guide covers every capability the endpoint promises", async () => {
   // 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("autoMerge"), "documents the per-request merge control");
-  assert(!md.includes("convergeOnly"), "does not expose the legacy merge control in agent guidance");
+  // Issue #916: the guide must document where to READ merge intent (the `/status` merge block) and
+  // that writing variables onto a running loop is not the way to change it. The legacy inverted
+  // `convergeOnly` name appears ONLY inside that sanctioned fallback explanation (a pre-`autoMerge`
+  // loop exposes its intent solely as `convergeOnly`) — never as a control the agent can set.
+  assert(md.includes('"merge": { "requested"'), "documents the /status merge block");
+  assert(md.includes("blockedBy"), "documents the env / human-approval distinction");
+  assert(
+    md.includes("no supported way to flip merge"),
+    "warns that writing variables onto a running loop is a no-op",
+  );
+  const legacyMentions = md.split("\n").filter((l) => l.includes("convergeOnly"));
+  assert(legacyMentions.length <= 1, `legacy convergeOnly appears only in the #916 fallback note; got: ${legacyMentions.join(" | ")}`);
+  assert(
+    legacyMentions.length === 1 && legacyMentions[0].includes("invert"),
+    "the one convergeOnly mention is the read-side fallback note (read it and invert it)",
+  );
   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/listActivePrs.ts

@@ -20,6 +20,6 @@ export default defineOperation("listActivePrs", async ({ req }, app) => {
     app.log.warn("listActivePrs rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
   }
-  const [prs, deliveries] = await Promise.all([activePrs(app.data), activeDeliveries(app.data)]);
+  const [prs, deliveries] = await Promise.all([activePrs(app.data, app.engine), activeDeliveries(app.data)]);
   return { status: 200, body: { count: prs.length, prs, deliveries } };
 });

package/operations/startAndMessage.test.ts

@@ -190,10 +190,20 @@ test("startConvergenceLoop defaults convergeOnly to false and does not truthy-co
     const stringy = captureApp();
     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);
+// Issue #916: `autoMerge: "true"` (a STRING) was silently FALSE at the door — the delegate read
+// `body.autoMerge === true`, so a mistyped merge request ran review-only with no signal. The door
+// now REJECTS a present-but-non-boolean `autoMerge` with a 400 at every start door.
+test("startConvergenceLoop → 400 on a non-boolean autoMerge (issue #916)", async () => {
+  await withGithubOff(async () => {
+    const { app: capApp, get } = captureApp();
+    const res = await startConvergenceLoop(input({ pr: "owner/repo#15", autoMerge: "true" }), capApp);
+    const r = res as any;
+    assertEquals(r.status, 400);
+    assertEquals(typeof r.body.error, "string");
+    assertEquals(get(), undefined, "a rejected door never reaches the engine");
   });
 });
 

package/operations/startConvergenceLoop.ts

@@ -32,19 +32,25 @@ export default defineOperation("startConvergenceLoop", async ({ body }, app) =>
   const dependsOn = body.dependsOn ?? [];
   const maxRounds = clampRounds(body.maxRounds, MAX_ROUNDS);
   // 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.
+  // callers that omit autoMerge retain the existing convergeOnly/global-default behavior. A
+  // PRESENT-but-non-boolean `autoMerge` (e.g. the string "true") is a 400 (issue #916): it used to
+  // read as silently false (`=== true`), so a mistyped merge request ran review-only with no signal.
+  if ("autoMerge" in body && typeof body.autoMerge !== "boolean") {
+    app.log.warn("start-convergence rejected: autoMerge must be a boolean", { autoMerge: body.autoMerge });
+    return { status: 400, body: { error: "autoMerge must be a boolean (true or false)" } };
+  }
   const hasAutoMerge = typeof body.autoMerge === "boolean";
-  const convergeOnly = hasAutoMerge ? body.autoMerge !== true : body.convergeOnly === true;
+  const autoMerge = hasAutoMerge ? body.autoMerge : body.convergeOnly === true ? false : undefined;
   // Opt-in escalation steward (issue #889): only when explicitly requested do this loop's
   // escalations become eligible for steward auto-resolution. Default off.
   const autoResolveEscalations = "autoResolveEscalations" in body && body.autoResolveEscalations === true;
-  const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly, null, false, autoResolveEscalations);
+  const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, false, null, false, autoResolveEscalations, autoMerge);
   app.log.info("convergence loop started", {
     prKey: parsed.prKey,
     alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
     dependsOn: dependsOn.length,
     maxRounds,
-    convergeOnly,
+    autoMerge: autoMerge ?? body.convergeOnly !== true,
     autoResolveEscalations,
   });
   return { status: 202, body: result };

package/operations/startFeature.readiness.integration.test.ts

@@ -207,3 +207,18 @@ test("humanApproval reaches the run only together with autoMerge", async () => {
     }
   });
 });
+
+// ── issue #916: a present-but-non-boolean `autoMerge` is a 400 at the door, never a silent false ──
+
+test("non-boolean autoMerge → 400 at the edge (never silently review-only)", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, converge: true, autoMerge: "true" }),
+      app,
+    )) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0, "a rejected door never starts a run");
+  });
+});

package/operations/startFeature.ts

@@ -113,6 +113,12 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     throw err;
   }
   const converge = "converge" in body && body.converge === true;
+  // A PRESENT-but-non-boolean `autoMerge` (e.g. the string "true") is a 400 (issue #916): it used to
+  // read as silently false (`=== true`), so a mistyped merge request ran review-only with no signal.
+  if ("autoMerge" in body && typeof body.autoMerge !== "boolean") {
+    app.log.warn("start-feature rejected: autoMerge must be a boolean", { autoMerge: body.autoMerge });
+    return { status: 400, body: { error: "autoMerge must be a boolean (true or false)" } };
+  }
   // Auto-merge is only meaningful as a follow-on to convergence; pin it off when converge is off so
   // the persisted row and the process variable can't disagree.
   const autoMerge = converge && "autoMerge" in body && body.autoMerge === true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.204.1",
+  "version": "0.205.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/resources/processes/convergence-loop.bpmn

@@ -103,6 +103,7 @@
           <nano:extend name="prUrl" type="string" />
           <nano:extend name="round" type="integer" />
           <nano:extend name="summary" type="string" optional="true" />
+          <nano:extend name="autoMerge" type="boolean" optional="true" />
           <nano:extend name="convergeOnly" type="boolean" optional="true" />
           <nano:extend name="abandonUrl" type="string" optional="true" />
         </nano:shape>
@@ -161,6 +162,7 @@
           <zeebe:input source="=reviewWaitTimeout" target="guardReviewWaitTimeout" />
           <zeebe:input source="=humanApproval" target="guardHumanApproval" />
           <zeebe:input source="=convergeOnly" target="guardConvergeOnly" />
+          <zeebe:input source="=autoMerge" target="guardAutoMerge" />
           <zeebe:input source="=reviewStale" target="guardReviewStale" />
           <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
           <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
@@ -182,6 +184,7 @@
           <zeebe:output source="=guardReviewWaitTimeout" target="reviewWaitTimeout" />
           <zeebe:output source="=(guardHumanApproval = true) or (humanApproval = true)" target="humanApproval" />
           <zeebe:output source="=guardConvergeOnly" target="convergeOnly" />
+          <zeebe:output source="=guardAutoMerge" target="autoMerge" />
           <zeebe:output source="=guardReviewStale" target="reviewStale" />
           <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
           <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
@@ -255,6 +258,7 @@
           <zeebe:input source="=reviewWaitTimeout" target="guardReviewWaitTimeout" />
           <zeebe:input source="=humanApproval" target="guardHumanApproval" />
           <zeebe:input source="=convergeOnly" target="guardConvergeOnly" />
+          <zeebe:input source="=autoMerge" target="guardAutoMerge" />
           <zeebe:input source="=reviewStale" target="guardReviewStale" />
           <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
           <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
@@ -277,6 +281,7 @@
           <zeebe:output source="=guardReviewWaitTimeout" target="reviewWaitTimeout" />
           <zeebe:output source="=(guardHumanApproval = true) or (humanApproval = true)" target="humanApproval" />
           <zeebe:output source="=guardConvergeOnly" target="convergeOnly" />
+          <zeebe:output source="=guardAutoMerge" target="autoMerge" />
           <zeebe:output source="=guardReviewStale" target="reviewStale" />
           <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
           <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />
@@ -474,6 +479,7 @@
         <zeebe:ioMapping>
           <zeebe:input source="=prKey" target="prKey" />
           <zeebe:output source="=0" target="huskRetries" />
+          <zeebe:output source="=if mergeDecision = &#34;approve&#34; then false else humanApproval" target="humanApproval" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_needApproval</bpmn:incoming>
@@ -563,6 +569,7 @@
           <zeebe:input source="=reviewWaitTimeout" target="guardReviewWaitTimeout" />
           <zeebe:input source="=humanApproval" target="guardHumanApproval" />
           <zeebe:input source="=convergeOnly" target="guardConvergeOnly" />
+          <zeebe:input source="=autoMerge" target="guardAutoMerge" />
           <zeebe:input source="=reviewStale" target="guardReviewStale" />
           <zeebe:input source="=roundEntryHead" target="guardRoundEntryHead" />
           <zeebe:input source="=abandonUrl" target="guardAbandonUrl" />
@@ -582,6 +589,7 @@
           <zeebe:output source="=guardReviewWaitTimeout" target="reviewWaitTimeout" />
           <zeebe:output source="=(guardHumanApproval = true) or (humanApproval = true)" target="humanApproval" />
           <zeebe:output source="=guardConvergeOnly" target="convergeOnly" />
+          <zeebe:output source="=guardAutoMerge" target="autoMerge" />
           <zeebe:output source="=guardReviewStale" target="reviewStale" />
           <zeebe:output source="=guardRoundEntryHead" target="roundEntryHead" />
           <zeebe:output source="=guardAbandonUrl" target="abandonUrl" />

package/skills/nano-workforce/SKILL.md

@@ -126,3 +126,10 @@ debugging. **Re-fetch it every session.** For one section, use
 - **Submissions are idempotent.** Re-submitting the same work must not double-dispatch.
 - **Escalations are for humans.** Surface them with options; don't silently answer design or
   product decisions.
+- **Merge intent is a read, not a write.** Every `/status` PR row carries a `merge` block —
+  `requested` (the run's `autoMerge`), `enabled` (the deployment's `NANO_PR_AUTO_MERGE`),
+  `effective`, and `blockedBy` (`"env"` | `"human-approval"` | `null`). Read it there; never
+  write variables onto a running loop to change it. Such writes are unsupported and
+  timing-dependent, not reliable no-ops — one landing while the loop awaits merge approval
+  reaches `pr.finalize` unrestored and can change whether merging starts. Cancel and re-submit
+  instead.

package/workers/converge-feature/worker.ts

@@ -3,8 +3,8 @@
 // Reached only via the `converge?` gateway's true branch (converge requested AND the agent opened a
 // keyed PR). Reuses `submitPr` — the SAME enrollment the epic waves and the standalone
 // `startConvergenceLoop` action use — so a feature run's PR gets identical review-round + merge
-// behaviour with no duplicated machinery. `autoMerge` maps to `submitPr`'s `convergeOnly`
-// (inverted): auto-merge → drive the merge-loop; otherwise stop at `converged`.
+// behaviour with no duplicated machinery. The run's positive `autoMerge` is threaded to `submitPr`
+// as-is (issue #916): auto-merge → drive the merge-loop; otherwise stop at `converged`.
 //
 // The feature-run's OWN process ends here; the PR's live convergence/merge state lives on the
 // `pull_requests` row keyed by `pr_key`, which the feature page links to. We therefore leave the
@@ -40,8 +40,10 @@ const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
   // (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.
+  // edge (1), never by the handoff edge.
+  //
+  // `autoMerge` is the canonical positive merge intent (issue #916): 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,
@@ -51,11 +53,11 @@ const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
   // read the durable flag off the `feature_runs` row (the source of truth) and hand it to `submitPr`.
   const featureRow = await featureRuns(app.data).get(featureKey);
   const autoResolve = featureRow?.auto_resolve_escalations === 1;
-  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge, featureKey, humanApproval, autoResolve);
+  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, false, featureKey, humanApproval, autoResolve, autoMerge);
   app.log.info("converge-feature: enrolled PR into convergence loop", {
     featureKey,
     prKey: parsed.prKey,
-    convergeOnly: !autoMerge,
+    autoMerge,
     humanApproval,
     autoResolveEscalations: autoResolve,
   });

package/workers/delivery-connector/worker.ts

@@ -217,7 +217,7 @@ const handler: AppJobHandler<In, ConnectorDispatchResult> = async (job, app) =>
           // completion can clobber that variable, so the durable row is the only trustworthy source
           // (issue #889 review). Fails closed (false) when no run row matches.
           const autoResolve = await resolveAutoResolveEscalations(app.data, job.processInstanceKey != null ? String(job.processInstanceKey) : null);
-          await submitPr(app.data, app.engine, converge.parsed, converge.dependsOn, MAX_ROUNDS, converge.convergeOnly, dedupeKey, false, autoResolve);
+          await submitPr(app.data, app.engine, converge.parsed, converge.dependsOn, MAX_ROUNDS, converge.convergeOnly, dedupeKey, false, autoResolve, !converge.convergeOnly);
           app.log.info("delivery-connector: enrolled PR into convergence loop", {
             target,
             dedupeKey,

package/workers/finalize/worker.test.ts

@@ -103,3 +103,38 @@ test("finalize with convergeOnly absent hands off to the merge-loop when auto-me
     assertEquals(pr.status, "waiting_deps");
   });
 });
+
+// Issue #916: `autoMerge` is the CANONICAL positive merge-intent variable on the convergence loop.
+// `pr.finalize` reads it first and falls back to the legacy inverted `convergeOnly` only when
+// `autoMerge` is absent — so an in-flight loop seeded before `autoMerge` existed keeps its behaviour.
+test("finalize with autoMerge=false rests at converged even when the legacy convergeOnly mirror is absent", 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, autoMerge: false } } as never, app as never);
+    assertEquals(createdProcesses.includes(MERGE_PROCESS_ID), false);
+    assertEquals(stores.pull_requests[0].status, "converged");
+  });
+});
+
+test("finalize with autoMerge=true hands off to the merge-loop (canonical positive variable)", 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, autoMerge: true } } as never, app as never);
+    assertEquals(createdProcesses.includes(MERGE_PROCESS_ID), true);
+    assertEquals(stores.pull_requests[0].status, "waiting_deps");
+  });
+});
+
+test("finalize prefers autoMerge over the legacy convergeOnly mirror when they disagree", async () => {
+  await withRetroOff(async () => {
+    const { app, stores, createdProcesses } = fakeApp();
+    // A contradictory pair (autoMerge=true, convergeOnly=true) can only arise from a hand-seeded or
+    // half-migrated instance: the positive canonical variable wins.
+    // biome-ignore lint/plugin: constructing the framework's job envelope for the handler under test
+    await handler({ variables: { ...BASE_VARS, autoMerge: true, convergeOnly: true } } as never, app as never);
+    assertEquals(createdProcesses.includes(MERGE_PROCESS_ID), true);
+    assertEquals(stores.pull_requests[0].status, "waiting_deps");
+  });
+});

package/workers/finalize/worker.ts

@@ -22,7 +22,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, convergeOnly } = job.variables;
+  const { prKey, repo, prNumber, prUrl, round, summary, abandonUrl, convergeOnly, autoMerge } = job.variables;
   const now = new Date().toISOString();
 
   // Heal a missing FK parent (engine/app.db desync) before the child `rounds` insert.
@@ -52,10 +52,15 @@ const handler: AppJobHandler<In> = async (job, app) => {
   // 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.
+  // Merge intent (issue #916): `autoMerge` is the CANONICAL positive variable — read it first and
+  // fall back to the legacy inverted `convergeOnly` only when `autoMerge` is absent, so an in-flight
+  // loop seeded before `autoMerge` existed keeps its behaviour. A review-only intent
+  // (`autoMerge:false`, or legacy `convergeOnly:true`) 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.
+  const mergeRequested = autoMerge === true || (autoMerge == null && convergeOnly !== true);
   let status = "converged";
-  if (AUTO_MERGE && convergeOnly !== true) {
+  if (AUTO_MERGE && mergeRequested) {
     try {
       const { mergeProcessKey } = await startMerge(app.data, app.engine, {
         repo,