@nanobpm/nano-workforce 0.204.1 → 0.205.1

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 {
@@ -1592,6 +1698,77 @@ export async function maybeEnsureFreshHeadRun(
  * EVERY branch first runs {@link advanceIfTerminalOutOfBand} — one shared "is this PR already
  * terminal (merged/closed) out-of-band?" pre-check — so no merge stage can silently strand when a PR
  * is landed/closed outside the loop (the `waiting_deps` self-merged wedge, #368). */
+/** Durably hand a `waiting_merge` PR back into the canonical convergence loop (issue #921, PR #922
+ * review): flip the row to `waiting_review` FIRST (so a review landing in the start window is still
+ * collected by `pollReviews` — it scans on `waiting_review`, not on instance liveness), RETIRE the
+ * live merge instance (while the row's `process_key` names a non-terminal merge instance, `submitPr`'s
+ * idempotency gate classifies the PR `alreadyRunning` and starts NOTHING — the cancel flips the derived
+ * tracking status terminal so the gate falls through), then `submitPr` re-opens the PR into a fresh
+ * convergence instance (round 1). The review-round agent's backlog IS the open threads: it fixes or
+ * pushes back, replies, and resolves them; on `converged` the converge-gate re-verifies zero
+ * unresolved threads and `pr.finalize` re-enters the merge stage — merging resumes automatically.
+ *
+ * The escalation-steward opt-in is carried through the resubmission (PR #922 review): `submitPr`
+ * defaults `autoResolveEscalations` to false and overwrites the row's flag on reopen, so an opted-in PR
+ * would silently lose automated escalation resolution merely because late review threads appeared.
+ *
+ * RETRYABLE on failure (PR #922 review, thread 3): if the cancel succeeds but `submitPr` throws, the
+ * row is restored to `waiting_merge` so the next pass re-attempts the handoff against the
+ * already-retired (terminal) merge key — rather than stranding in `waiting_review`, which `pollMerges`
+ * no longer scans and whose `readiness-ready` resume correlates to nothing once the merge instance is
+ * cancelled. The restored row's `process_key` still names the now-terminal merge instance, so the
+ * unfinished handoff is re-detected next pass by the dead-owner guard in `pollMerges` (which keys off
+ * the terminal `derived_status`, independently of the GitHub verdict). Best-effort throughout: a failed
+ * cancel or restore only logs, leaving the row for the next pass. */
+async function handoffWaitingMergeToConvergence(
+  data: DataLayer,
+  engine: EngineClient,
+  pr: PullRequest,
+  logContext: string,
+) {
+  const prKey = pr.pr_key;
+  try {
+    // `waiting_since` bounds the review the fresh loop collects: only a review submitted at or after
+    // the handoff counts, so a pre-merge review (submitted before this flip) can never satisfy the new
+    // run's wait.
+    const handoffTs = now();
+    await prs(data).update(prKey, { status: "waiting_review", waiting_since: handoffTs, updated_at: handoffTs });
+    const mergeKey = pr.process_key;
+    if (mergeKey != null) {
+      try {
+        await engine.cancelInstance({ processInstanceKey: String(mergeKey) });
+      } catch (cancelErr) {
+        console.error(`[poller] ${logContext} handoff ${prKey}: retire merge instance ${mergeKey}: ${cancelErr}`);
+      }
+    }
+    await submitPr(
+      data,
+      engine,
+      { repo: pr.repo, number: pr.number, url: pr.url, prKey },
+      [],
+      MAX_ROUNDS,
+      false,
+      null,
+      false,
+      pr.auto_resolve_escalations === 1,
+    );
+    console.log(`[poller] ${logContext} -> handed back into convergence -> ${prKey}`);
+  } catch (err) {
+    console.error(`[poller] ${logContext} handoff ${prKey}: ${err}`);
+    // Restore the row to `waiting_merge` so the next pass re-attempts the handoff, and NULL the
+    // `process_key`: the merge instance was retired above (or never lived), so the row genuinely has
+    // NO live owner. The null key is the durable "unfinished handoff" marker the dead-owner guard in
+    // `pollMerges` keys on — and it is what distinguishes this retryable shape from a HUMAN cancel of a
+    // parked merge wait (which leaves `process_key` naming the terminated instance and must NOT be
+    // resurrected). Best-effort: a failed restore still leaves the original error logged.
+    try {
+      await prs(data).update(prKey, { status: "waiting_merge", process_key: null, updated_at: now() });
+    } catch (restoreErr) {
+      console.error(`[poller] ${logContext} handoff ${prKey}: restore waiting_merge: ${restoreErr}`);
+    }
+  }
+}
+
 export async function pollMerges(data: DataLayer, engine: EngineClient, token: string) {
   // 1) Dependencies merged?
   for (const pr of await prs(data).find({ status: "waiting_deps" })) {
@@ -1625,7 +1802,12 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
   for (const pr of await prs(data).find({ status: "waiting_merge" })) {
     const { repo, number, pr_key: prKey } = pr;
     try {
-      const st = await fetchPrState(repo, number, token);
+      // Opt into the review-threads probe so a `BLOCKED` merge state is classified by its real
+      // cause (issue #921): unresolved review threads (branch protection
+      // `required_conversation_resolution`) surface as the `review-threads` verdict below instead
+      // of polling as "waiting" until the mergeable-wait timer escalates the misleading
+      // "mergeability never settled". One extra GraphQL read per pass per waiting PR.
+      const st = await fetchPrState(repo, number, token, { withReviewThreads: true });
       if (st === null) continue; // no transport → skip this PR (others may still advance)
       // Out-of-band terminal (merged/closed) → the shared pre-check publishes `merge-ready {ready}`,
       // routing through `gw-mergeable → attempt-merge` whose idempotent already-merged check completes
@@ -1633,6 +1815,39 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
       // (#342/#350). Reuse the `st` we just read so we don't double-fetch. This is the proven terminal
       // path the whole class (#368) now shares.
       if (await advanceIfTerminalOutOfBand(data, engine, pr, token, st)) continue;
+      // DEAD-OWNER guard (PR #922 review, round 5): a `waiting_merge` row with `process_key === null`
+      // has NO live owner — the unfinished-handoff shape {@link handoffWaitingMergeToConvergence}
+      // leaves when its `submitPr` failed after the merge instance was retired (the restore nulls the
+      // key to mark exactly this). The verdict switch below must NOT run against it: every arm ends in
+      // `flipToMergingThenPublish`, which would publish `merge-ready`/`merge-evicted`/remediation
+      // correlated to a merge instance that no longer exists — the message is dropped and the row wedges
+      // at the transient `merging` with no live owner (a fresh `ready`/`conflict`/`blocked` verdict after
+      // the threads cleared is exactly the case the retry-restore leaves behind). Persist the handoff
+      // INDEPENDENTLY of the current GitHub verdict: re-establish a live convergence owner FIRST,
+      // publishing nothing. Keying on the NULL key — not on the terminal `derived_status` — is what
+      // keeps a HUMAN cancel of a parked merge wait (which leaves `process_key` naming the terminated
+      // instance) OUT of this path: a cancelled run must stay cancelled, never auto-resurrected. A
+      // normal merge wait always carries a live `process_key`, so this fires only on the
+      // ownerless-handoff shape. Placed after the out-of-band terminal pre-check so a merged/closed PR
+      // still takes the proven terminal path first.
+      if (pr.process_key == null) {
+        await handoffWaitingMergeToConvergence(data, engine, pr, "dead merge owner (unfinished handoff)");
+        continue;
+      }
+      // HUMAN-CANCEL guard (PR #922 review, round 5): a `waiting_merge` row whose `process_key` names a
+      // TERMINAL merge instance (`derived_status` folded to `abandoned`) was cancelled out-of-band. The
+      // verdict switch must NOT run against it either — publishing `merge-ready`/`merge-evicted`/
+      // remediation to the dead instance is dropped and wedges the row at `merging` (the reviewer's "a
+      // new conflict or check failure likewise sends remediation to the dead owner"). Unlike the
+      // unfinished-handoff shape above, a cancelled run must NOT be resurrected into convergence — the
+      // abandon protocol exists to stop exactly that orphaned side effect — so it is simply SKIPPED
+      // (left cancelled) with nothing published. A LIVE parked merge wait reads a non-terminal
+      // `derived_status` (`waiting_merge` ∈ activeStatuses), so this fires only on the cancelled shape.
+      const trackedMerge = await prsTracking(data).get(prKey);
+      if (trackedMerge && TERMINAL_STATUSES.includes(trackedMerge.derived_status)) {
+        console.log(`[poller] merge owner terminal (cancelled) — leaving ${prKey} abandoned, no merge message published`);
+        continue;
+      }
       // Load the repo's merge protocol ONCE per PR iteration and pass it into the classifier so the
       // protocol-aware backstop (#392) can gate a red DECLARED-required check even when GitHub reports
       // the PR as UNSTABLE. The same handle is reused by the frugal-CI fresh-head-run branch below.
@@ -1682,6 +1897,25 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
         }
         continue; // GitHub still computing / checks pending
       }
+      if (verdict === "review-threads") {
+        // BLOCKED by unresolved review threads with every check green (issue #921): the threads are
+        // findings from the reviewer this loop converges with, so route them back into convergence
+        // rather than escalating to a human. Requesting another Copilot review alone does NOT
+        // remediate them: `pollReviews` only scans `waiting_review` rows, so a review landing while
+        // the PR sits in `waiting_merge` is never picked up and no review-fix agent ever activates
+        // (PR #922 review). The handoff is a DURABLE re-entry into the canonical convergence loop
+        // (see {@link handoffWaitingMergeToConvergence}). Once the fresh convergence instance exists,
+        // `pr.progress-check` parks the row back in `waiting_merge` after the round, where this
+        // block's verdict has by then flipped off `review-threads` (the gate guarantees it) — so this
+        // fires at most once per thread-blocked episode.
+        await handoffWaitingMergeToConvergence(
+          data,
+          engine,
+          pr,
+          `blocked by ${st.unresolvedThreads} unresolved review thread(s)`,
+        );
+        continue;
+      }
       if (verdict === "ready") {
         const lane = await mergeLaneDecisionForPr(data, prKey);
         if (lane?.isHeld) {
@@ -1701,6 +1935,16 @@ export async function pollMerges(data: DataLayer, engine: EngineClient, token: s
           // fix-ci task appends it to the agent prompt so the agent knows which gates to green.
           failingChecks: st.failingChecks,
           failingChecksList: st.failingCheckNames.join("\n"),
+          // The probed unresolved-thread count (issue #921) — carried so a later stall-budget
+          // escalation can name the real BLOCKED cause (and so the `review-threads` arm's question
+          // can quote it). `-1` when the probe was unreadable.
+          reviewThreads: st.unresolvedThreads,
+          // 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. 0 in token mode (checks unenumerable — the conservative `waiting` verdict already
+          // keeps the approval wording from firing there).
+          pendingChecks: st.pendingCheckNames.length,
         },
       });
       console.log(`[poller] mergeable=${verdict} (${st.mergeStateStatus}) -> ${prKey}`);
@@ -2784,13 +3028,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/app/userTasks.ts

@@ -90,6 +90,7 @@ export const PR_ESCALATION_PRODUCER_ELEMENTS: readonly string[] = [
   "merge-esc-conflict",
   "merge-esc-attempt",
   "merge-esc-landed",
+  "merge-esc-threads",
 ];
 
 /** The ACP permission-prompt escalation (issue #559, ADR 0056) — the Tasks-inbox kind a bridged

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.1",
   "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",