@nanobpm/nano-workforce 0.194.0 → 0.195.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.195.0](https://github.com/nanobpm/nano-workforce/compare/v0.194.0...v0.195.0) (2026-09-30)
+
+### Features
+
+* **feature:** add optional human approval before merge ([#827](https://github.com/nanobpm/nano-workforce/issues/827)) ([fea6b54](https://github.com/nanobpm/nano-workforce/commit/fea6b54ee3fd63f0adccd230e45ee46ed9df24f8)), closes [#826](https://github.com/nanobpm/nano-workforce/issues/826) [#826](https://github.com/nanobpm/nano-workforce/issues/826)
+
 ## [0.194.0](https://github.com/nanobpm/nano-workforce/compare/v0.193.2...v0.194.0) (2026-09-30)
 
 ### Features

package/README.md

@@ -290,6 +290,12 @@ A single submission can choose its merge behavior explicitly with the positive
 `converged` regardless of the global default, while `true` enables the merge-loop
 after convergence only when `NANO_PR_AUTO_MERGE` is enabled.
 
+A feature run started with `humanApproval` adds a human gate before the merge-loop
+(so it applies only when the run would merge: `autoMerge` with `NANO_PR_AUTO_MERGE`
+enabled): the converged PR waits in the Tasks inbox as "PR merge approval". Approve it
+to merge, or request changes with guidance. The agent then updates the same PR,
+convergence re-runs, and approval is asked again.
+
 ### Fleet mode: hand it an issue (plan → implement → converge)
 
 ```

package/SPEC.md

@@ -101,7 +101,7 @@ known at submit time, carried as a process variable and stored on the DB row.
 │    <gateway: status>
 │      ├── converged  → [Check review comments] (pr.converge-gate; ++ackRetryRound on ack-only block)
 │      │                   → <gateway: comments addressed?>
-│      │                       ├── addressed → [Scope classifier] → … → [Mark converged] → (end)
+│      │                       ├── addressed → [Scope classifier] → … → <human approval?> → [Mark converged] → (end)
 │      │                       ├── review stale (#799) → [Record round] (re-solicit fresh review) ┐
 │      │                       └── unaddressed → <gateway: auto-ack within budget?>               │
 │      │                            ├── convergeAckOnly and ackRetryRound ≤ ackRetryMax           │
@@ -155,6 +155,24 @@ escalates, resolution failure fails open to the human, and re-submitting the PR
 loop feeds and reads this memory — a merge-loop answer (same `pr.answer-escalation` step)
 is tagged `answerContext = "merge"` and never recorded as a convergence adjudication.
 
+**Human approval before merge (issue #826).** A feature run started with `humanApproval`
+seeds `humanApproval = true` on its convergence instance — only when the PR would merge
+(`autoMerge` on and `NANO_PR_AUTO_MERGE` enabled; otherwise it is pinned off).
+After the scope gate passes, the `human approval?` gateway then parks the converged PR on the
+native `merge-approval` user task (`merge-approval.form`, surfaced in the Tasks inbox as
+"PR merge approval") instead of going straight to `[Mark converged]`. `mergeDecision = "approve"`
+continues to `pr.finalize`, which hands the PR to the merge-loop. Approval covers the PR, not a
+pinned SHA: as with any auto-merge, the merge-loop may still rebase it or fix CI before landing.
+Anything else (the form's
+`revise` plus required guidance) loops back to `capture-head` with the guidance as `answer`, so
+the review agent updates the **same** PR. Convergence then re-runs and approval is asked again.
+The default route is fail-closed: once parked, nothing merges without an explicit approval. A
+gated run that adopts a PR already converging under a live loop (e.g. one an ungated run started)
+narrows that loop to `humanApproval = true` rather than inheriting its auto-merge; a loop already
+past its `human approval?` gateway can no longer be gated. The task is
+human-only (never agent-answerable) and never auto-resumed from an adjudication. Without the
+flag the gateway defaults straight through, so existing runs are unchanged.
+
 Guard: after progress classification, a **progressing** round with round ≥
 MAX_ROUNDS forces an escalation ("not converged after N rounds") so a human
 decides rather than looping forever. The guard sits *after* `check-progress`

package/app/agentCompletion.ts

@@ -25,7 +25,7 @@ import type { DataLayer, EngineClient, GatewayDataSource } from "@nanobpm/urban"
 import { invalidateAdjudication, invalidateAdjudicationByCompletion } from "./adjudications.ts";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
-import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT, READINESS_ESCALATION_ELEMENT, READINESS_ESCALATION_PF_ELEMENT } from "./userTasks.ts";
+import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT, PR_MERGE_APPROVAL_ELEMENT, READINESS_ESCALATION_ELEMENT, READINESS_ESCALATION_PF_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
 
@@ -136,6 +136,9 @@ export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   READINESS_ESCALATION_PF_TASK_ELEMENT,
   READINESS_ESCALATION_TASK_ELEMENT,
   ACP_PERMISSION_ELEMENT,
+  // Human-only (issue #826): never agent-answerable, so it stays OUT of ESCALATION_TASK_ELEMENTS and the
+  // fleet can never auto-approve a merge.
+  PR_MERGE_APPROVAL_ELEMENT,
 ]);
 
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
@@ -153,6 +156,7 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   [CONFORMANCE_ESCALATION_TASK_ELEMENT]: "conformance-escalation",
   [READINESS_ESCALATION_PF_TASK_ELEMENT]: "readiness-escalation",
   [READINESS_ESCALATION_TASK_ELEMENT]: "readiness-escalation",
+  [PR_MERGE_APPROVAL_ELEMENT]: "merge-approval",
   // NOTE: the delivery-graph `human` node (`DELIVERY_HUMAN_ELEMENT`, ADR 0005 S3) is intentionally
   // ABSENT here. Unlike the fixed-form escalations above, ONE `delivery-human-task` element is DESIGNED
   // to render DIFFERENT forms per node (explicit → category → generic → agent-router, `app/deliveryHuman.ts`

package/app/convergeGate.test.ts

@@ -1073,14 +1073,21 @@ test("classify-scope feeds gw-scope-gate, which blocks on scopeBlocked = true",
   assertStringIncludes(blocked, "scopeBlocked = true");
 });
 
-test("gw-scope-gate default arm finalizes (scope ok → persist-converged)", () => {
+test("gw-scope-gate default arm continues to the optional merge approval, whose default finalizes", () => {
   const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-scope-gate"[^>]*>/);
   assert(gw, "gw-scope-gate gateway missing");
   assertStringIncludes(gw[0], 'default="f_scopeOk"');
   const ok = flowElement("f_scopeOk");
   assert(ok, "f_scopeOk flow missing");
-  assertStringIncludes(ok, 'targetRef="persist-converged"');
+  assertStringIncludes(ok, 'targetRef="gw-approval"');
   assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
+  // Issue #826: without `humanApproval` the approval gateway's default arm finalizes as before.
+  const approval = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-approval"[^>]*>/);
+  assert(approval, "gw-approval gateway missing");
+  assertStringIncludes(approval[0], 'default="f_noApproval"');
+  const noApproval = flowElement("f_noApproval");
+  assert(noApproval, "f_noApproval flow missing");
+  assertStringIncludes(noApproval, 'targetRef="persist-converged"');
 });
 
 test("the scope escalation routes through gw-escalated with the classifier's specific reason", () => {

package/app/convergenceStaleRoundReset.test.ts

@@ -73,7 +73,7 @@ test("capture-head still precedes review-round on every loop entry (the reset is
   const el = serviceTask("capture-head");
   assert(el, "capture-head service task must exist");
   const incoming = [...el!.matchAll(/<bpmn:incoming>([^<]+)<\/bpmn:incoming>/g)].map((m) => m[1]);
-  for (const flow of ["f_start", "f_reviewLoop", "f_answerLoop", "f_huskRetry", "f_ackRetry"]) {
+  for (const flow of ["f_start", "f_reviewLoop", "f_answerLoop", "f_huskRetry", "f_ackRetry", "f_revise"]) {
     assert(incoming.includes(flow), `capture-head must be the entry join for ${flow} so the reset covers that re-entry (issue #822)`);
   }
   const capture = flat.match(/<bpmn:sequenceFlow[^>]*\bid="f_capture"[^>]*\/>/);

package/app/feature.test.ts

@@ -124,6 +124,22 @@ test("startFeature: converge/autoMerge flags are persisted as 0/1", async () =>
   assertEquals(row.auto_merge, 1);
 });
 
+test("startFeature: humanApproval is persisted as 0/1 and seeded onto the instance (issue #826)", async () => {
+  for (const humanApproval of [true, false]) {
+    const stores = { feature_runs: { rows: [] as any[], key: "feature_key" } };
+    let vars: any = null;
+    const engine = {
+      createInstance: (req: any) => {
+        vars = req.variables;
+        return Promise.resolve({ processInstanceKey: "PI-1" });
+      },
+    } as any;
+    await startFeature(memData(stores), engine, PARSED, "main", true, true, null, {}, humanApproval);
+    assertEquals(stores.feature_runs.rows[0].human_approval, humanApproval ? 1 : 0);
+    assertEquals(vars.humanApproval, humanApproval);
+  }
+});
+
 test("startFeature: seeds the single task slice + base-branch brief onto the instance", async () => {
   let captured: any = null;
   const engine = {

package/app/feature.ts

@@ -60,6 +60,9 @@ export interface FeatureRun {
   pr_key: string | null;
   converge: number;
   auto_merge: number;
+  /** 1 ⇒ a human must approve the converged PR before the merge-loop runs (issue #826). Only
+   * meaningful with `auto_merge = 1`; the `startFeature` operation pins it to 0 otherwise. */
+  human_approval: number;
   outcome: string | null;
   /** Human rollup detail. Projected by `pollFeatureDelivery` (fix: Feature history stuck at
    * `converging`) and also written by `pr.record-blocked-ack` with the operator's disposition
@@ -352,6 +355,7 @@ export async function startFeature(
   autoMerge: boolean,
   customInstructions: string | null = null,
   readiness: FeatureReadinessOptions = {},
+  humanApproval = false,
 ): Promise<StartFeatureResult> {
   // Intake-time readiness gate (issue #295): the probes the run must satisfy before it implements,
   // and the bound its preflight escalation timers fire off. Both are load-bearing together —
@@ -450,6 +454,7 @@ export async function startFeature(
       pr_key: null,
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,
+      human_approval: humanApproval ? 1 : 0,
       outcome: null,
       delivery_label: null,
       // Clear the operator tick-off so a re-dispatched run is NOT silently dropped into History when
@@ -472,6 +477,7 @@ export async function startFeature(
       pr_key: null,
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,
+      human_approval: humanApproval ? 1 : 0,
       outcome: null,
       delivery_label: null,
       created_at: ts,
@@ -507,6 +513,8 @@ export async function startFeature(
       // 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).
+      humanApproval,
       // A single-issue feature run OWNS its issue (the whole issue is the slice), so the agent may
       // claim it with a "starting work" comment on a first run (resources/prompts/feature.md). Epic slices
       // (plan-fanout) deliberately DO NOT set this — their `issue` is the shared parent epic, which

package/app/featureDelivery.test.ts

@@ -197,6 +197,27 @@ test("pollFeatureDelivery: a converging run whose PR row is MISSING is re-enroll
   assertEquals(stores.feature_runs[0].delivery_label, "PR record missing");
 });
 
+test("pollFeatureDelivery: the re-enroll keeps the run's human approval gate (issue #826)", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#7", status: "converging", pr_key: "o/r#407", auto_merge: 1, human_approval: 1, delivery_label: null },
+  ];
+  stores.pull_requests = [];
+  let vars: Record<string, unknown> | undefined;
+  const engine = {
+    searchProcessInstances: async () => [],
+    createInstance: async (req: { variables?: Record<string, unknown> }) => {
+      vars = req.variables;
+      return { processInstanceKey: "pi-407" };
+    },
+  } as any;
+
+  await pollFeatureDelivery(data, engine);
+
+  assertEquals(vars?.convergeOnly, false);
+  assertEquals(vars?.humanApproval, true, "a healed enrollment must not silently drop the approval gate");
+});
+
 test("pollFeatureDelivery: a converging run whose PR row is PARTIALLY enrolled (present, non-terminal, process_key NULL) is re-enrolled — a create-instance crash after the row insert does not wedge it (PR #809)", async () => {
   const { data, stores } = memData();
   stores.feature_runs = [

package/app/fineGrainedCells.test.ts

@@ -115,7 +115,7 @@ test("feature.bpmn composes its converge step via callActivity to converge-cell
     /<zeebe:ioMapping>[\s\S]*?<\/zeebe:ioMapping>/.test(convergeBlock),
     "the converge callActivity must carry an explicit zeebe:ioMapping",
   );
-  for (const field of ["featureKey", "prKey", "autoMerge"]) {
+  for (const field of ["featureKey", "prKey", "autoMerge", "humanApproval"]) {
     assert(
       new RegExp(`<zeebe:input\\b[^>]*\\btarget="${field}"`).test(convergeBlock),
       `the converge callActivity ioMapping must map ConvergeFeatureIn.${field} into the child scope`,

package/app/mcpToolSurface.ts

@@ -111,8 +111,13 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * `getAgenticSupply`, and registry read schemas (plus the `StaleWorker` leaf) so an operator can spot
  * and drain a stale harness from the tool surface alone. Measured 86,509 bytes serialized — 9 over the
  * old ceiling's headroom. Deliberate, documented growth — not schema fat.
+ *
+ * RAISE PROVENANCE — 87_000 → 87_500 (#826): the per-run `humanApproval` start option on both
+ * `startFeature` body variants (`FeatureStartByIssue`/`FeatureStartByUrl`) — the Feature tab's
+ * "Human approval before merge" checkbox. Measured 87,293 bytes serialized (86,862 → 87,293 — over
+ * the old ceiling's 138-byte headroom). Deliberate, documented growth — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 87_000;
+export const MCP_SURFACE_BYTES_BUDGET = 87_500;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/app/mergeApproval.test.ts

@@ -0,0 +1,126 @@
+// Human approval before merge (issue #826): an optional `merge-approval` user task in the convergence
+// loop, between the scope gate and `persist-converged` (`pr.finalize`, the merge-loop handoff). These
+// deploy the committed model into the WASM engine and drive tokens through it: flag off → finalizes
+// straight away; flag on → parks for a human; approve → finalizes; request changes (or anything that is
+// not an explicit approve) → the guidance goes back to the review agent on the same PR, then approval is
+// asked again.
+import { after, test } from "node:test";
+import { readFileSync } from "node:fs";
+import { assert, assertEquals } from "#test-assert";
+import { assertThatInstance, byProcessId, createWasmEngineClient, type WasmEngineClient } from "@nanobpm/urban-testkit";
+import { ESCALATION_TASK_ELEMENTS, HUMAN_COMPLETABLE_ELEMENTS, validateEscalationVariables } from "./agentCompletion.ts";
+import { PR_MERGE_APPROVAL_ELEMENT } from "./userTasks.ts";
+
+const MODEL = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+
+const engines: WasmEngineClient[] = [];
+after(async () => {
+  await Promise.all(engines.map((e) => e.close()));
+});
+
+/** Boots one loop whose every round converges cleanly; `answers` records the `answer` each review round saw.
+ *  Job types in `held` get no worker until `register(type)`, so a test can act while the loop waits there. */
+async function boot(vars: Record<string, unknown>, held: string[] = []) {
+  const engine = await createWasmEngineClient();
+  engines.push(engine);
+  await engine.deployResources([{ name: "convergence-loop.bpmn", content: MODEL, contentType: "text/xml" }]);
+  const answers: unknown[] = [];
+  const workers: Record<string, (v: Record<string, unknown>) => Record<string, unknown>> = {
+    "senior:pr-review": (v) => {
+      answers.push(v.answer);
+      return { status: "converged", summary: "done" };
+    },
+    "pr.capture-head": () => ({ roundEntryHead: "sha" }),
+    "pr.persist-round": () => ({}),
+    "pr.progress-check": () => ({ progressed: true }),
+    "pr.converge-gate": () => ({ convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false }),
+    "senior:scope-classify": () => ({ scopeBlocked: false, scopeBlockReason: "" }),
+    "pr.finalize": () => ({}),
+  };
+  const register = (type: string) =>
+    engine.registerWorker(type, (job) => workers[type]((job as { variables: Record<string, unknown> }).variables));
+  for (const type of Object.keys(workers)) if (!held.includes(type)) await register(type);
+  const { processInstanceKey } = await engine.createInstance({
+    processDefinitionId: "convergence-loop",
+    awaitCompletion: false,
+    variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1, round: 1, maxRounds: 20, answer: null, huskRetries: 0, ...vars },
+  });
+  return { engine, answers, register, processInstanceKey };
+}
+
+function completions(engine: WasmEngineClient, elementId: string): number {
+  const snap = engine.snapshot() as { elementStats?: { elementId: string; completed: number }[] };
+  return (snap.elementStats ?? []).find((s) => s.elementId === elementId)?.completed ?? 0;
+}
+
+async function openApproval(engine: WasmEngineClient): Promise<string | undefined> {
+  return (await engine.openUserTasks()).find((t) => t.elementId === PR_MERGE_APPROVAL_ELEMENT)?.userTaskKey;
+}
+
+const loop = (engine: WasmEngineClient) => assertThatInstance(engine, byProcessId("convergence-loop"));
+
+test("without humanApproval a converged PR finalizes straight away — no approval task", async () => {
+  // `humanApproval` deliberately unseeded: a missing flag must behave exactly like `false`.
+  const { engine } = await boot({});
+  loop(engine).hasCompleted().hasNoIncident();
+  assertEquals(completions(engine, "persist-converged"), 1);
+  assertEquals(completions(engine, PR_MERGE_APPROVAL_ELEMENT), 0);
+});
+
+test("with humanApproval a converged PR parks for a human, and approve finalizes it", async () => {
+  const { engine } = await boot({ humanApproval: true });
+  loop(engine).isActive().hasActiveElement(PR_MERGE_APPROVAL_ELEMENT).hasNoIncident();
+  assertEquals(completions(engine, "persist-converged"), 0, "nothing hands off to the merge-loop before approval");
+
+  const key = await openApproval(engine);
+  assert(key !== undefined, "the approval task is open");
+  await engine.completeUserTask(key, { mergeDecision: "approve" });
+  loop(engine).hasCompleted().hasNoIncident();
+  assertEquals(completions(engine, "persist-converged"), 1);
+});
+
+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 first = await openApproval(engine);
+  assert(first !== undefined, "the approval task is open");
+  await engine.completeUserTask(first, { mergeDecision: "revise", answer: "Rename foo to bar." });
+
+  loop(engine).isActive().hasActiveElement(PR_MERGE_APPROVAL_ELEMENT).hasNoIncident();
+  assertEquals(answers.length, 2, "the review agent ran again");
+  assertEquals(answers[1], "Rename foo to bar.", "the revise round received the human's guidance");
+  assertEquals(completions(engine, "capture-head"), 2, "the revise re-entered the same loop");
+  assertEquals(completions(engine, "persist-converged"), 0);
+  const second = await openApproval(engine);
+  assert(second !== undefined && second !== first, "approval is asked again after the revision");
+});
+
+test("a live ungated loop narrowed to humanApproval (a gated submitPr adopting it) parks for approval", async () => {
+  // `submitPr` narrows an adopted live loop with setVariables (app/service.ts); the gateway must honour it.
+  const { engine, register, processInstanceKey } = await boot({ humanApproval: false }, ["senior:pr-review"]);
+  loop(engine).isActive().hasActiveElement("review-round");
+  await engine.setVariables({ scopeKey: String(processInstanceKey), variables: { humanApproval: true } });
+  await register("senior:pr-review");
+  loop(engine).isActive().hasActiveElement(PR_MERGE_APPROVAL_ELEMENT).hasNoIncident();
+  assertEquals(completions(engine, "persist-converged"), 0, "the adopted loop never merges unapproved");
+});
+
+test("fail-closed: a completion without an explicit approve never merges", async () => {
+  const { engine } = await boot({ humanApproval: true });
+  const key = await openApproval(engine);
+  assert(key !== undefined, "the approval task is open");
+  await engine.completeUserTask(key, {});
+  loop(engine).isActive().hasActiveElement(PR_MERGE_APPROVAL_ELEMENT).hasNoIncident();
+  assertEquals(completions(engine, "persist-converged"), 0);
+});
+
+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");
+  const check = (vars: Record<string, unknown>) => validateEscalationVariables(PR_MERGE_APPROVAL_ELEMENT, vars);
+  assertEquals(check({ mergeDecision: "approve" }), null);
+  assertEquals(check({ mergeDecision: "revise", answer: "Rename foo." }), null);
+  assert(check({}) !== null, "a decision is required");
+  assert(check({ mergeDecision: "revise" }) !== null, "request changes needs guidance");
+  assert(check({ mergeDecision: "revise", answer: "  " }) !== null, "blank guidance is rejected");
+  assert(check({ mergeDecision: "merge" }) !== null, "only approve/revise are accepted");
+});

package/app/service.test.ts

@@ -876,6 +876,111 @@ test("submitPr seeds the #796 auto-ack budget onto the instance (ackRetryRound=0
   });
 });
 
+test("submitPr seeds humanApproval (issue #826), pinned off for a converge-only run that never merges", 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}` });
+    const merging = captureVars();
+    await submitPr(merging.data, merging.engine, pr(11), [], 20, false, null, true);
+    assertEquals(merging.get()?.humanApproval, true);
+    const convergeOnly = captureVars();
+    await submitPr(convergeOnly.data, convergeOnly.engine, pr(12), [], 20, true, null, true);
+    assertEquals(convergeOnly.get()?.humanApproval, false);
+    const unset = captureVars();
+    await submitPr(unset.data, unset.engine, pr(13));
+    assertEquals(unset.get()?.humanApproval, false);
+  });
+});
+
+// Adoption (issue #826, Copilot review): `submitPr` returns `alreadyRunning` for a PR whose loop is
+// live, so a gated caller adopting an UNGATED loop would inherit its auto-merge. `humanApproval` is
+// monotonic: the gated caller narrows the live loop (idempotent, so a retry against its own gated loop
+// is a no-op). A PR already finalized (`converged_at` set) is past its approval point: `startMerge`
+// re-pointed its `process_key` at the LIVE merge-loop, which must never be written to.
+function adoptLoop(status: string, loopState: string, convergedAt: string | null = null) {
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: {
+      rows: [
+        {
+          pr_key: "owner/repo#14",
+          repo: "owner/repo",
+          number: 14,
+          url: "https://github.com/owner/repo/pull/14",
+          title: "t",
+          status,
+          current_round: 1,
+          process_key: "PI-LOOP",
+          converged_at: convergedAt,
+        },
+      ],
+      key: "pr_key",
+    },
+    escalations: { rows: [], key: "id" },
+    pr_dependencies: { rows: [], key: "pr_key" },
+  };
+  const data = {
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+    open: () => memOpen(stores),
+  } as any;
+  const narrowed: unknown[] = [];
+  const engine = {
+    createInstance: () => Promise.reject(new Error("a live PR is adopted, never re-created")),
+    searchProcessInstances: () => Promise.resolve([{ processInstanceKey: "PI-LOOP", state: loopState }]),
+    setVariables: (req: unknown) => {
+      narrowed.push(req);
+      return Promise.resolve();
+    },
+  } as any;
+  return { data, engine, narrowed };
+}
+
+test("a gated submitPr adopting a live loop narrows it to humanApproval (issue #826)", async () => {
+  await withGithubOff(async () => {
+    const pr = { repo: "owner/repo", number: 14, url: "https://github.com/owner/repo/pull/14", prKey: "owner/repo#14" };
+    const live = adoptLoop("converging", "ACTIVE");
+    assertEquals(await submitPr(live.data, live.engine, pr, [], 20, false, null, true), { prKey: pr.prKey, alreadyRunning: true });
+    assertEquals(live.narrowed, [{ scopeKey: "PI-LOOP", variables: { humanApproval: true } }]);
+
+    const ungated = adoptLoop("converging", "ACTIVE");
+    await submitPr(ungated.data, ungated.engine, pr);
+    assertEquals(ungated.narrowed, [], "an ungated adopter leaves the loop's mode alone");
+
+    const convergeOnly = adoptLoop("converging", "ACTIVE");
+    await submitPr(convergeOnly.data, convergeOnly.engine, pr, [], 20, true, null, true);
+    assertEquals(convergeOnly.narrowed, [], "a converge-only adopter never merges, so never gates");
+
+    const merging = adoptLoop("waiting_deps", "ACTIVE", "2026-01-01T00:00:00.000Z");
+    assertEquals(await submitPr(merging.data, merging.engine, pr, [], 20, false, null, true), { prKey: pr.prKey, alreadyRunning: true });
+    assertEquals(merging.narrowed, [], "the live merge-loop of a finalized PR is never written to");
+
+    const ended = adoptLoop("converging", "COMPLETED");
+    await submitPr(ended.data, ended.engine, pr, [], 20, false, null, true);
+    assertEquals(ended.narrowed, [], "a loop the engine no longer reports running is left alone");
+  });
+});
+
+test("human approval is pinned off when NANO_PR_AUTO_MERGE is off — the PR never merges (issue #826)", async () => {
+  // `AUTO_MERGE` is read once at import, so load a fresh copy of the module under the env.
+  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?autoMergeOff=${Date.now()}`);
+    await withGithubOff(async () => {
+      const fresh = captureVars();
+      const pr15 = { repo: "owner/repo", number: 15, url: "https://github.com/owner/repo/pull/15", prKey: "owner/repo#15" };
+      await mod.submitPr(fresh.data, fresh.engine, pr15, [], 20, false, null, true);
+      assertEquals(fresh.get()?.humanApproval, false, "no approval task for a merge that never happens");
+
+      const live = adoptLoop("converging", "ACTIVE");
+      const pr14 = { repo: "owner/repo", number: 14, url: "https://github.com/owner/repo/pull/14", prKey: "owner/repo#14" };
+      await mod.submitPr(live.data, live.engine, pr14, [], 20, false, null, true);
+      assertEquals(live.narrowed, [], "nor is an adopted loop narrowed");
+    });
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_AUTO_MERGE"];
+    else process.env["NANO_PR_AUTO_MERGE"] = prev;
+  }
+});
+
 // Lineage threading (issue #245): `submitPr` persists the origin `root_request_key` on the PR row
 // and carries it onto the convergence instance; `startMerge` reads it back off the row onto the
 // merge instance. A human/webhook submit that supplies no root self-roots on the `pr_key` (its own

package/app/service.ts

@@ -107,6 +107,7 @@ import {
   type OpenEscalation,
   PLAN_REVIEW_ELEMENT,
   PR_ESCALATION_PRODUCER_ELEMENTS,
+  PR_MERGE_APPROVAL_ELEMENT,
   PR_RECORD_ANSWER_ELEMENT,
   PR_RECORD_MERGE_ANSWER_ELEMENT,
   PR_WAIT_ANSWER_ELEMENT,
@@ -573,9 +574,10 @@ export async function submitPr(
   maxRounds: number = MAX_ROUNDS,
   convergeOnly = false,
   rootRequestKey: string | null = null,
+  humanApproval = false,
 ) {
   return withPrSubmitLock(parsed.prKey, () =>
-    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey),
+    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey, humanApproval),
   );
 }
 
@@ -587,7 +589,12 @@ async function submitPrCritical(
   maxRounds: number = MAX_ROUNDS,
   convergeOnly = false,
   rootRequestKey: string | null = null,
+  humanApproval = false,
 ) {
+  // 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
+  // (review-only, or the global switch off) must not park for a pointless approval.
+  const gated = humanApproval && !convergeOnly && 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
@@ -607,6 +614,23 @@ async function submitPrCritical(
   // RESUBMITTABLE — fall through and re-enroll, exactly as `startFeature`'s intake guard (feature.ts)
   // treats a keyless `running` feature row. A terminal row (any `process_key`) already falls through.
   if (trackedExisting && existing?.process_key != null && !TERMINAL_STATUSES.includes(trackedExisting.derived_status)) {
+    // Human approval is monotonic (issue #826): a gated caller adopting a live loop — possibly an
+    // ungated one another run started — narrows it to gated instead of inheriting its auto-merge.
+    // Idempotent, so a retry against our own gated loop is a no-op. A loop the engine no longer reports
+    // running is left alone; one already past its `human approval?` gateway can no longer be gated. A
+    // finalized PR (`converged_at` set) is past it, and `startMerge` has re-pointed its `process_key` at
+    // the merge-loop, so it is skipped. Mid-handoff (key re-pointed, `converged_at` not yet stamped) the
+    // write reaches the merge-loop but is inert: nothing there reads `humanApproval`.
+    if (gated && existing.converged_at == null) {
+      const loopKey = existing.process_key;
+      const match = (await engine.searchProcessInstances({ processInstanceKeys: [loopKey] })).find(
+        (s) => String(s.processInstanceKey) === loopKey,
+      );
+      const state = match ? String(match.state ?? "").trim().toUpperCase() : null;
+      if (state !== null && !ENGINE_TERMINAL_STATES.has(state)) {
+        await engine.setVariables({ scopeKey: loopKey, variables: { humanApproval: true } });
+      }
+    }
     return { prKey: parsed.prKey, alreadyRunning: true };
   }
 
@@ -724,6 +748,9 @@ async function submitPrCritical(
       // `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,
+      // 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,
       // Cooperative abandon check (#76): the capability URL + the abort brief appended to the
       // review-round agent's prompt, so it can stop before pushing if the run is cancelled.
       abandonUrl: abUrl,
@@ -2469,13 +2496,24 @@ export async function pollFeatureDelivery(
       //       it would wedge `converging` forever with no PR process.
       // Both heal via the SAME idempotent `submitPr`: it is idempotent on the PR key (a redundant call
       // on an already-live PR early-returns `alreadyRunning`), and now treats a keyless non-terminal row
-      // as resubmittable, so it re-creates the instance and installs `process_key`. `convergeOnly`
-      // mirrors `converge-feature` — the inverse of the run's `auto_merge` flag.
+      // as resubmittable, so it re-creates the instance and installs `process_key`. `convergeOnly` and
+      // `humanApproval` mirror `converge-feature` — derived from the run's `auto_merge`/`human_approval`.
       const partiallyEnrolled =
         trackedPr != null && trackedPr.process_key == null && !TERMINAL_STATUSES.includes(trackedPr.derived_status);
       if (prStatus === null || partiallyEnrolled) {
         const parsed = parsePr(run.pr_key);
-        if (parsed) await submitPr(data, engine, parsed, [], MAX_ROUNDS, run.auto_merge !== 1, run.feature_key);
+        if (parsed) {
+          await submitPr(
+            data,
+            engine,
+            parsed,
+            [],
+            MAX_ROUNDS,
+            run.auto_merge !== 1,
+            run.feature_key,
+            run.human_approval === 1,
+          );
+        }
       }
       const { status, label } = deriveFeatureDelivery(prStatus);
       if (run.status !== status || run.delivery_label !== label) {
@@ -3057,6 +3095,7 @@ export async function pollUserTasks(
     [READINESS_ESCALATION_ELEMENT]: "plan",
     [PR_WAIT_ANSWER_ELEMENT]: "pr",
     [PR_WAIT_MERGE_ANSWER_ELEMENT]: "pr",
+    [PR_MERGE_APPROVAL_ELEMENT]: "pr",
   };
 
   // The SINGLE enrichment derivation both discovery paths feed: resolve one open escalation task (by

package/app/userTasks.ts

@@ -52,6 +52,12 @@ export const PR_WAIT_ANSWER_ELEMENT = "wait-answer";
  *  canonical `completeUserTask` door and surfaced in this same Tasks inbox. */
 export const PR_WAIT_MERGE_ANSWER_ELEMENT = "wait-merge-answer";
 
+/** The optional human merge-approval user task (convergence-loop.bpmn, issue #826) — a converged PR
+ *  parks here before `pr.finalize` hands it to the merge-loop. Approve merges; request changes loops
+ *  the guidance (`answer`) back to the review agent on the same PR. HUMAN-only: never agent-answerable,
+ *  so the fleet can never auto-approve a merge. */
+export const PR_MERGE_APPROVAL_ELEMENT = "merge-approval";
+
 /** The PR review-loop answer-recording service task (convergence-loop.bpmn) — the `pr.answer-escalation`
  *  job the token moves to IMMEDIATELY when `wait-answer` completes. Its ACTIVE element instance is the
  *  positive-evidence marker that an operator's answer is in-flight (recorded but the loop hasn't looped
@@ -237,6 +243,7 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [TRIAL_MERGE_ELEMENT]: "Trial merge",
   [PR_WAIT_ANSWER_ELEMENT]: "PR review",
   [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",
+  [PR_MERGE_APPROVAL_ELEMENT]: "PR merge approval",
   [CONFORMANCE_ESCALATION_ELEMENT]: "Conformance review",
   [READINESS_ESCALATION_PF_ELEMENT]: "Upstream readiness stalled",
   [READINESS_ESCALATION_ELEMENT]: "Readiness escalation",