@nanobpm/nano-workforce 0.204.1 → 0.205.1

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/resources/processes/merge-loop.bpmn

@@ -53,11 +53,15 @@
           <nano:extend name="mergeState" type="string" />
           <nano:extend name="failingChecks" type="integer" optional="true" />
           <nano:extend name="failingChecksList" type="string" optional="true" />
+          <nano:extend name="reviewThreads" type="integer" optional="true" />
+          <nano:extend name="pendingChecks" type="integer" optional="true" />
         </nano:shape>
         <nano:shape id="MergeReady" name="merge-ready message payload">
           <nano:extend name="mergeState" type="string" />
           <nano:extend name="failingChecks" type="integer" optional="true" />
           <nano:extend name="failingChecksList" type="string" optional="true" />
+          <nano:extend name="reviewThreads" type="integer" optional="true" />
+          <nano:extend name="pendingChecks" type="integer" optional="true" />
         </nano:shape>
         <nano:shape id="FixCiIn" name="CI fix — input">
           <nano:extend name="prKey" type="string" />
@@ -179,6 +183,7 @@
       <bpmn:outgoing>f_m_mRebase</bpmn:outgoing>
       <bpmn:outgoing>f_m_mWaiting</bpmn:outgoing>
       <bpmn:outgoing>f_m_mDraft</bpmn:outgoing>
+      <bpmn:outgoing>f_m_mThreads</bpmn:outgoing>
       <bpmn:outgoing>f_m_mBlocked</bpmn:outgoing>
     </bpmn:exclusiveGateway>
     <bpmn:serviceTask id="attempt-merge" name="Merge PR">
@@ -258,7 +263,7 @@
         </zeebe:properties>
         <zeebe:ioMapping>
           <zeebe:input source="=&#34;blocked&#34;" target="status" />
-          <zeebe:input source="=if mergeState = &#34;draft&#34; then &#34;This PR is in draft and can&#39;t be merged. Mark it ready (gh pr ready), then reply to retry.&#34; else if mergeState = &#34;waiting&#34; then &#34;GitHub never settled this PR&#39;s mergeability (still computing after repeated re-polls, or the state could not be read). Check the PR on GitHub — resolve any conflict or failing required check if present — then reply to retry.&#34; else &#34;This PR is not mergeable (state: &#34; + mergeState + &#34;). Resolve the conflict or failing required check on the branch, then reply to retry.&#34;" target="question" />
+          <zeebe:input source="=if mergeState = &#34;draft&#34; then &#34;This PR is in draft and can&#39;t be merged. Mark it ready (gh pr ready), then reply to retry.&#34; else if mergeState = &#34;waiting&#34; and reviewThreads = 0 and failingChecks = 0 and pendingChecks = 0 then &#34;This PR is merge-blocked with all checks green (none failing, none pending) and every review thread resolved. GitHub still reports BLOCKED, which means a required review approval (or code-owner review) is outstanding — nothing the automated loop can produce. Approve the PR (or adjust the branch-protection review requirement), then reply to retry.&#34; else if mergeState = &#34;waiting&#34; then &#34;GitHub never settled this PR&#39;s mergeability (still computing or checks still pending after repeated re-polls, or the state could not be read). Check the PR on GitHub — resolve any conflict or failing required check if present — then reply to retry.&#34; else &#34;This PR is not mergeable (state: &#34; + mergeState + &#34;). Resolve the conflict or failing required check on the branch, then reply to retry.&#34;" target="question" />
         </zeebe:ioMapping>
       </bpmn:extensionElements>
       <bpmn:incoming>f_m_mDraft</bpmn:incoming>
@@ -287,9 +292,26 @@
       <bpmn:incoming>f_mr_giveup</bpmn:incoming>
       <bpmn:outgoing>f_m_escA</bpmn:outgoing>
     </bpmn:serviceTask>
+    <bpmn:serviceTask id="merge-esc-threads" name="Escalate: unresolved review threads">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.persist-escalation" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="EscalationIn" />
+          <zeebe:property name="io.nanobpm.dataEnvelope.out" value="EscalationOut" />
+        </zeebe:properties>
+        <zeebe:ioMapping>
+          <zeebe:input source="=&#34;blocked&#34;" target="status" />
+          <zeebe:input source="=&#34;This PR is merge-blocked by &#34; + string(reviewThreads) + &#34; unresolved review thread(s) (branch protection requires every conversation resolved; all checks are green and there is no conflict). These are review findings the loop already converged, so a fresh review round cannot clear them without a reply. Resolve the threads on the PR (or reply with guidance — e.g. which threads to push back on), then reply to retry.&#34;" target="question" />
+          <zeebe:input source="=null" target="agentSlaJobType" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_m_mThreads</bpmn:incoming>
+      <bpmn:outgoing>f_m_escT</bpmn:outgoing>
+    </bpmn:serviceTask>
     <bpmn:exclusiveGateway id="gw-merge-escalated" name="escalation opened?" default="f_m_escReenter">
       <bpmn:incoming>f_m_escA</bpmn:incoming>
       <bpmn:incoming>f_m_escLanded</bpmn:incoming>
+      <bpmn:incoming>f_m_escT</bpmn:incoming>
       <bpmn:outgoing>f_m_escWait</bpmn:outgoing>
       <bpmn:outgoing>f_m_escReenter</bpmn:outgoing>
     </bpmn:exclusiveGateway>
@@ -732,6 +754,9 @@
     <bpmn:sequenceFlow id="f_m_mDraft" name="draft — mark ready (human)" sourceRef="gw-mergeable" targetRef="merge-esc-conflict">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeState = "draft"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_m_mThreads" name="blocked (unresolved review threads)" sourceRef="gw-mergeable" targetRef="merge-esc-threads">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeState = "review-threads"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_mrp_probe" sourceRef="wait-mergeable-repoll" targetRef="merge-stall-probe" />
     <bpmn:sequenceFlow id="f_m_mBlocked" name="unclassified — auto-rebase" sourceRef="gw-mergeable" targetRef="gw-rebase" />
     <bpmn:sequenceFlow id="f_ci_go" name="within budget" sourceRef="gw-ci-fix" targetRef="SP_cifix">
@@ -773,6 +798,7 @@
     <bpmn:sequenceFlow id="f_m_done" sourceRef="mark-merged" targetRef="MergeEnd" />
     <bpmn:sequenceFlow id="f_m_escC" sourceRef="merge-esc-conflict" targetRef="wait-merge-answer" />
     <bpmn:sequenceFlow id="f_m_escA" sourceRef="merge-esc-attempt" targetRef="gw-merge-escalated" />
+    <bpmn:sequenceFlow id="f_m_escT" sourceRef="merge-esc-threads" targetRef="gw-merge-escalated" />
     <bpmn:sequenceFlow id="f_m_escWait" sourceRef="gw-merge-escalated" targetRef="wait-merge-answer">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=escalated = true</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
@@ -833,7 +859,7 @@
       <bpmndi:BPMNShape id="BPMNShape_gw-merge-stall" bpmnElement="gw-merge-stall" isMarkerVisible="true">
         <dc:Bounds x="1538" y="1535" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1521" y="1650" width="85" height="42" />
+          <dc:Bounds x="1521" y="1630" width="85" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-mergeable" bpmnElement="gw-mergeable" isMarkerVisible="true">
@@ -902,6 +928,9 @@
       <bpmndi:BPMNShape id="BPMNShape_merge-esc-attempt" bpmnElement="merge-esc-attempt">
         <dc:Bounds x="1688" y="720" width="100" height="80" />
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_merge-esc-threads" bpmnElement="merge-esc-threads">
+        <dc:Bounds x="1138" y="1680" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-merge-escalated" bpmnElement="gw-merge-escalated" isMarkerVisible="true">
         <dc:Bounds x="2088" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
@@ -1002,7 +1031,7 @@
         <di:waypoint x="402" y="1300" />
         <di:waypoint x="402" y="320" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="446" y="1239" width="88" height="56" />
+          <dc:Bounds x="919" y="1239" width="88" height="56" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_rearm" bpmnElement="f_reb_rearm">
@@ -1179,6 +1208,14 @@
           <dc:Bounds x="1057" y="483" width="85" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_mThreads" bpmnElement="f_m_mThreads">
+        <di:waypoint x="1013" y="305" />
+        <di:waypoint x="1013" y="1720" />
+        <di:waypoint x="1138" y="1720" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1018" y="1642" width="81" height="56" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_mBlocked" bpmnElement="f_m_mBlocked">
         <di:waypoint x="1013" y="305" />
         <di:waypoint x="1013" y="440" />
@@ -1255,7 +1292,7 @@
         <di:waypoint x="1668" y="740" />
         <di:waypoint x="1688" y="740" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1952" y="616" width="53" height="14" />
+          <dc:Bounds x="1932" y="616" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_gAbandoned" bpmnElement="f_m_gAbandoned">
@@ -1281,8 +1318,9 @@
         <di:waypoint x="870" y="618" />
         <di:waypoint x="870" y="638" />
         <di:waypoint x="888" y="638" />
-        <di:waypoint x="888" y="1598" />
-        <di:waypoint x="1338" y="1598" />
+        <di:waypoint x="888" y="1780" />
+        <di:waypoint x="1388" y="1780" />
+        <di:waypoint x="1388" y="1600" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_msp_gate" bpmnElement="f_msp_gate">
         <di:waypoint x="1438" y="1560" />
@@ -1308,6 +1346,14 @@
         <di:waypoint x="1988" y="120" />
         <di:waypoint x="2088" y="120" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_m_escT" bpmnElement="f_m_escT">
+        <di:waypoint x="1238" y="1720" />
+        <di:waypoint x="2008" y="1720" />
+        <di:waypoint x="2008" y="145" />
+        <di:waypoint x="2068" y="145" />
+        <di:waypoint x="2068" y="120" />
+        <di:waypoint x="2088" y="120" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_escWait" bpmnElement="f_m_escWait">
         <di:waypoint x="2138" y="120" />
         <di:waypoint x="2238" y="120" />
@@ -1327,13 +1373,13 @@
         <di:waypoint x="1013" y="1620" />
         <di:waypoint x="1013" y="305" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1446" y="1587" width="85" height="28" />
+          <dc:Bounds x="1246" y="1587" width="85" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_dep_rewait" bpmnElement="f_dep_rewait">
         <di:waypoint x="1738" y="1280" />
-        <di:waypoint x="1738" y="1640" />
-        <di:waypoint x="234" y="1640" />
+        <di:waypoint x="1738" y="1300" />
+        <di:waypoint x="234" y="1300" />
         <di:waypoint x="234" y="298" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_mr_go" bpmnElement="f_mr_go">

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,

package/workers/merge-stall-probe/worker.ts

@@ -33,6 +33,14 @@ interface Out extends Record<string, unknown> {
   mergeState: string;
   failingChecks: number;
   failingChecksList: string;
+  // The unresolved-review-thread count behind a `review-threads` verdict (issue #921), mirrored
+  // into the escalation question so a human sees exactly what blocks the merge. `-1` = unprobed.
+  reviewThreads: number;
+  // The pending-check count (PR #922 review): zero failing checks does not mean checks are green —
+  // a queued/running check leaves the BLOCKED cause undetermined, so the stall-escalation question
+  // gates its "required review approval" wording on this being 0 too (never claims a verified
+  // blocker off a half-settled rollup).
+  pendingChecks: number;
 }
 
 const handler: AppJobHandler<In, Out> = async (job, app) => {
@@ -44,10 +52,14 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // GitHub reports UNSTABLE. Any transport hiccup is treated as "still waiting" — never a spurious
   // ready/conflict verdict — so a bad read is surfaced as `waiting`, which `gw-mergeable` routes to
   // a bounded re-poll (#774) rather than misrouting the token to a wrong remediation arm; a
-  // genuinely stuck verdict still escalates once the `mergeStallMax` budget is exhausted.
-  const st = await fetchPrState(repo, prNumber, token).catch(() => null);
+  // genuinely stuck verdict still escalates once the `mergeStallMax` budget is exhausted. The read
+  // opts into the review-threads probe (`withReviewThreads`) so a `BLOCKED` merge state is
+  // classified by its real cause (issue #921) — unresolved review threads surface as the
+  // `review-threads` verdict and route to their own arm instead of re-polling until the budget
+  // exhausts into the misleading "mergeability never settled" escalation.
+  const st = await fetchPrState(repo, prNumber, token, { withReviewThreads: true }).catch(() => null);
   if (st === null) {
-    return { mergeState: "waiting", failingChecks: 0, failingChecksList: "" };
+    return { mergeState: "waiting", failingChecks: 0, failingChecksList: "", reviewThreads: -1, pendingChecks: 0 };
   }
   const protocol = await loadMergeProtocol(repo, token).catch(() => null);
   const mergeState = classifyMergeability(st, protocol ?? undefined);
@@ -64,6 +76,8 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     // poller's `merge-ready` payload so fix-ci knows which gates to green.
     failingChecks: st.failingChecks,
     failingChecksList: st.failingCheckNames.join("\n"),
+    reviewThreads: st.unresolvedThreads,
+    pendingChecks: st.pendingCheckNames.length,
   };
 };