@nanobpm/nano-workforce 0.194.0 → 0.195.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.195.1](https://github.com/nanobpm/nano-workforce/compare/v0.195.0...v0.195.1) (2026-09-30)
+
+### Bug Fixes
+
+* **service:** commit review/fix-ci/rebase rounds to the PR branch, not a nano/agent-work fallback ([#817](https://github.com/nanobpm/nano-workforce/issues/817)) ([212e0cc](https://github.com/nanobpm/nano-workforce/commit/212e0cc9755d2cbba34ed5f170952a5e6a142729)), closes [jwulf/c8ctl-plugin-nano#231](https://github.com/jwulf/c8ctl-plugin-nano/issues/231) [#776](https://github.com/nanobpm/nano-workforce/issues/776)
+
+## [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/contracts.ts

@@ -424,7 +424,7 @@ export const WIRE_CONTRACTS = {
     name: "io.nanobpm.agentTask.repository",
     owner: "app/repoEnvelope.ts",
     semantics:
-      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create` (the deterministic `feat/<task.id>`, emitted for a single-task feature run AND — per issue #776 — the deterministic `feat/<node.id>` for each single-instance delivery-graph agent cell, injected per-cell by `agentNodeRepoEnvelope`/`app/deliveryRunner.ts` so a forgetful agent can never be left committing on the base branch and stranding its run on a non-ff push; the epic plan-fanout seed still omits it because its MI children each cut a per-child `feat/<task.id>` the app can't name at compile time, so those agents branch themselves). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable) and a `cloneTimeoutMs` (from `NANO_PR_CLONE_TIMEOUT_MS`, default 600000 = 10 min) that raises the harness's 120s default so a large monorepo's blobless single-branch clone provisions instead of dying at 120s (issue #694). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `sha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). Alongside the `repository` slice the envelope carries a sibling `task.allowPr: true` (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the git credential (GITHUB_TOKEN, or the `gh` default) for repo provisioning behind that flag, so every repo-backed envelope sets it or the clone dies with `unable to get password from user`; the repoless path emits no envelope and so no `task`. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91, branch-cut guard jwulf/c8ctl-plugin-nano#231).",
+      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create`. On the PRE-PR path `branch.create` is the deterministic `feat/<task.id>` (emitted for a single-task feature run AND — per issue #776 — the deterministic `feat/<node.id>` for each single-instance delivery-graph agent cell, injected per-cell by `agentNodeRepoEnvelope`/`app/deliveryRunner.ts` so a forgetful agent can never be left committing on the base branch and stranding its run on a non-ff push; the epic plan-fanout seed still omits it because its MI children each cut a per-child `feat/<task.id>` the app can't name at compile time, so those agents branch themselves). On the PR-based paths `branch.create` is set to the PR HEAD branch itself (equal to `ref`, jwulf/c8ctl-plugin-nano#231): without it the harness's base-branch guard treats the checkout as base-like and cuts a throwaway `nano/agent-work/<base>-<run>` fallback, stranding the round's commits OFF the PR; with `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR head branch. So `branch.create` is present on both the pre-PR and PR-based paths (only a blank/omitted value drops the key). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable) and a `cloneTimeoutMs` (from `NANO_PR_CLONE_TIMEOUT_MS`, default 600000 = 10 min) that raises the harness's 120s default so a large monorepo's blobless single-branch clone provisions instead of dying at 120s (issue #694). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `sha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). Alongside the `repository` slice the envelope carries a sibling `task.allowPr: true` (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the git credential (GITHUB_TOKEN, or the `gh` default) for repo provisioning behind that flag, so every repo-backed envelope sets it or the clone dies with `unable to get password from user`; the repoless path emits no envelope and so no `task`. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91, branch-cut guard jwulf/c8ctl-plugin-nano#231).",
     shape:
       'io.nanobpm.agentTask: { repository: { provider: "github", url: string, ref?: string, singleBranch: true, filter: "blob:none", cloneTimeoutMs: number, baseRef?: string, sha?: string, branch?: { create: string } }, task: { allowPr: true } }',
   },

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/repoEnvelope.ts

@@ -133,8 +133,14 @@ export class RepoEnvelopeConflictError extends Error {
  * `implement-cell`) dispatches its agent BEFORE any PR exists, so it passes `ref = base` and a
  * `branchCreate` naming the deterministic `feat/<task.id>` feature branch the harness cuts off that
  * base itself (the agent-guide's `feat/*` convention) — instead of the agent branching by hand — so
- * the isolated clone lands on the right branch deterministically across a resume. `branchCreate` is
- * omitted on the PR-based paths, which check out an existing head. */
+ * the isolated clone lands on the right branch deterministically across a resume. The PR-based paths
+ * (review-round / fix-ci / rebase) ALSO pass `branchCreate = ref` (the PR HEAD branch, equal to
+ * `ref`): without an explicit `branch.create` the harness's base-branch guard
+ * (jwulf/c8ctl-plugin-nano#231) treats the checkout as base-like and cuts a throwaway
+ * `nano/agent-work/<base>-<run>` fallback, stranding the round's commits OFF the PR; with
+ * `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR
+ * head branch itself. `branchCreate` is therefore emitted on both the pre-PR and PR-based paths (only
+ * a blank/omitted value drops the key). */
 export function repoEnvelopeVars(
   repo: string,
   ref: string | null,
@@ -186,7 +192,10 @@ export function repoEnvelopeVars(
         // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch
         // off that base itself (the agent-guide's `feat/*` convention) instead of the agent branching by
         // hand — making the isolated clone land on the right branch deterministically across a resume.
-        // Omitted (no key) on the PR-based paths (review/fix-ci/rebase), which check out an existing head.
+        // The PR-based paths (review/fix-ci/rebase) ALSO pass `branchCreate = ref` (the PR head): without
+        // it the harness's base-branch guard (jwulf/c8ctl-plugin-nano#231) cuts a throwaway
+        // `nano/agent-work/*` fallback OFF the PR; with `ref == create == head` it commits/pushes to the
+        // head branch. Only a blank/omitted value drops the key.
         ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
           ? { branch: { create: branchCreate.trim() } }
           : {}),