@nanobpm/nano-workforce 0.193.2 → 0.195.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **cockpit:** collapse agent-history turns behind a timestamped heading ([#832](https://github.com/nanobpm/nano-workforce/issues/832)) ([812907d](https://github.com/nanobpm/nano-workforce/commit/812907d13c49dc8a008bb8682d7d58f04c8ba323)), closes [#831](https://github.com/nanobpm/nano-workforce/issues/831)
+
 ## [0.193.2](https://github.com/nanobpm/nano-workforce/compare/v0.193.1...v0.193.2) (2026-09-29)
 
 ### Bug Fixes

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/agentic/cockpit/agent-history-render.test.ts

@@ -63,6 +63,8 @@ test("renderAgentHistory renders turns with role, text, tool calls and per-turn
         text: "on it",
         toolCalls: [{ toolCallId: "t-1", toolName: "grep", elementId: "tool" }],
         metrics: "12 in \u00b7 4 out \u00b7 900ms",
+        producedAt: "2024-05-01T12:34:56.789Z",
+        time: "12:34:56",
       },
     ],
   };
@@ -78,6 +80,28 @@ test("renderAgentHistory renders turns with role, text, tool calls and per-turn
   assert.equal(host.byClass("cockpit-agent-turn-metrics")[0]?.text(), "12 in \u00b7 4 out \u00b7 900ms");
 });
 
+test("renderAgentHistory renders each turn collapsed: a <details> whose <summary> heading carries the timestamp (#831)", () => {
+  const host = new FakeElement("div");
+  renderAgentHistory(host, doc, {
+    agentInstanceKey: "ai-1",
+    count: 1,
+    turns: [{ historyItemKey: "h-1", loopIteration: 1, role: "ASSISTANT", text: "on it", toolCalls: [], producedAt: "2024-05-01T12:34:56.789Z", time: "12:34:56" }],
+  });
+  const turn = host.byClass("cockpit-agent-turn")[0];
+  assert.equal(turn?.tagName, "details");
+  // Collapsed by default: no `open` attribute — the native <summary> toggles it on click.
+  assert.equal(turn?.getAttribute("open"), undefined);
+  const heading = host.byClass("cockpit-agent-turn-meta")[0];
+  assert.equal(heading?.tagName, "summary");
+  const time = host.byClass("cockpit-agent-turn-time")[0];
+  assert.equal(time?.tagName, "time");
+  assert.equal(time?.text(), "12:34:56");
+  assert.equal(time?.getAttribute("datetime"), "2024-05-01T12:34:56.789Z");
+  // The details body sits inside the collapsible turn, not in the heading.
+  const body = host.byClass("cockpit-agent-turn-body")[0];
+  assert.equal(body?.byClass("cockpit-agent-turn-text")[0]?.text(), "on it");
+});
+
 test("renderAgentHistory renders an empty history state", () => {
   const host = new FakeElement("div");
   renderAgentHistory(host, doc, { agentInstanceKey: "ai-9", count: 0, turns: [] });

package/app/agentic/cockpit/agent-history-render.ts

@@ -106,19 +106,32 @@ export function renderAgentSessions(
   return { root };
 }
 
+/**
+ * One turn as a native collapsible: a `<details>` (collapsed by default — no `open`) whose `<summary>`
+ * heading (role, iteration, timestamp, metrics) toggles the turn's details body on click (#831).
+ */
 function turnBlock(doc: DocumentLike, t: AgentTurnView): ElementLike {
-  const block = el(doc, "div", "cockpit-agent-turn");
+  const block = el(doc, "details", "cockpit-agent-turn");
   block.setAttribute("data-history-item-key", t.historyItemKey);
   block.setAttribute("data-role", t.role);
   block.setAttribute("data-loop-iteration", String(t.loopIteration));
 
-  const meta = el(doc, "div", "cockpit-agent-turn-meta");
+  const meta = el(doc, "summary", "cockpit-agent-turn-meta");
   meta.appendChild(el(doc, "span", "cockpit-agent-turn-role", t.role));
   meta.appendChild(el(doc, "span", "cockpit-agent-turn-iter", `#${t.loopIteration}`));
+  if (t.time !== undefined) {
+    const time = el(doc, "time", "cockpit-agent-turn-time", t.time);
+    if (t.producedAt !== undefined) {
+      time.setAttribute("datetime", t.producedAt);
+      time.setAttribute("title", t.producedAt);
+    }
+    meta.appendChild(time);
+  }
   if (t.metrics !== undefined) meta.appendChild(el(doc, "span", "cockpit-agent-turn-metrics", t.metrics));
   block.appendChild(meta);
 
-  if (t.text !== "") block.appendChild(el(doc, "pre", "cockpit-agent-turn-text", t.text));
+  const body = el(doc, "div", "cockpit-agent-turn-body");
+  if (t.text !== "") body.appendChild(el(doc, "pre", "cockpit-agent-turn-text", t.text));
 
   if (t.toolCalls.length > 0) {
     const tools = el(doc, "ul", "cockpit-agent-turn-tools");
@@ -127,8 +140,9 @@ function turnBlock(doc: DocumentLike, t: AgentTurnView): ElementLike {
       li.setAttribute("data-tool-call-id", call.toolCallId);
       tools.appendChild(li);
     }
-    block.appendChild(tools);
+    body.appendChild(tools);
   }
+  block.appendChild(body);
   return block;
 }
 

package/app/agentic/cockpit/agent-history-view.test.ts

@@ -96,6 +96,22 @@ test("agentHistoryView projects turns in transport order with text, tool calls a
   assert.equal(view.turns[1]?.metrics, "12 in \u00b7 4 out \u00b7 900ms");
 });
 
+test("agentHistoryView carries each turn's producedAt timestamp (absent when unreported)", () => {
+  const view = agentHistoryView({
+    agentInstanceKey: "ai-1",
+    count: 2,
+    records: [
+      { historyItemKey: "h-0", agentInstanceKey: "ai-1", loopIteration: 0, role: "USER", commitStatus: "COMMITTED", content: [], toolCalls: [], producedAt: "2024-05-01T12:34:56.789Z" },
+      { historyItemKey: "h-1", agentInstanceKey: "ai-1", loopIteration: 1, role: "ASSISTANT", commitStatus: "COMMITTED", content: [], toolCalls: [] },
+    ],
+  });
+  assert.equal(view.turns[0]?.producedAt, "2024-05-01T12:34:56.789Z");
+  // UTC: the heading is locale-free, so the expected value is fixed regardless of the runner's timezone.
+  assert.equal(view.turns[0]?.time, "12:34:56");
+  assert.equal(view.turns[1]?.producedAt, undefined);
+  assert.equal(view.turns[1]?.time, undefined);
+});
+
 test("agentHistoryView read-as-absence: an empty history yields zero turns", () => {
   const view = agentHistoryView({ agentInstanceKey: "ai-9", count: 0, records: [] });
   assert.equal(view.count, 0);

package/app/agentic/cockpit/agent-history-view.ts

@@ -63,6 +63,10 @@ export interface AgentTurnView {
   readonly toolCalls: readonly AgentTurnToolCallView[];
   /** A compact per-turn token/duration rollup, when metrics exist. */
   readonly metrics?: string;
+  /** When the turn was produced (ISO-8601), when the engine reports it. */
+  readonly producedAt?: string;
+  /** The turn's compact heading timestamp (`HH:MM:SS`, UTC), when `producedAt` parses. */
+  readonly time?: string;
 }
 
 /** The full renderable history for one agent instance: its rolled-up header + ordered turns. */
@@ -113,6 +117,16 @@ function turnMetrics(r: AgentHistoryRecord): string | undefined {
   return dur !== undefined ? `${base} \u00b7 ${dur}` : base;
 }
 
+/** A compact `HH:MM:SS` heading timestamp in UTC for an ISO instant; undefined when unparseable. */
+export function turnTime(iso: string | undefined): string | undefined {
+  if (iso === undefined || iso === "") return undefined;
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) return undefined;
+  const d = new Date(ms);
+  const pad = (n: number): string => String(n).padStart(2, "0");
+  return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+
 /** The textual content of a turn: TEXT blocks joined in order (non-textual/empty blocks dropped). */
 function turnText(r: AgentHistoryRecord): string {
   const texts: string[] = [];
@@ -156,6 +170,7 @@ export function agentSessionsView(report: AgentInstanceListReport): AgentSession
 /** Project one engine {@link AgentHistoryRecord} onto a renderable {@link AgentTurnView}. */
 export function agentTurnView(r: AgentHistoryRecord): AgentTurnView {
   const metrics = turnMetrics(r);
+  const time = turnTime(r.producedAt);
   return {
     historyItemKey: r.historyItemKey,
     loopIteration: r.loopIteration,
@@ -167,6 +182,8 @@ export function agentTurnView(r: AgentHistoryRecord): AgentTurnView {
       ...(c.elementId !== undefined && c.elementId !== "" ? { elementId: c.elementId } : {}),
     })),
     ...(metrics !== undefined ? { metrics } : {}),
+    ...(r.producedAt !== undefined && r.producedAt !== "" ? { producedAt: r.producedAt } : {}),
+    ...(time !== undefined ? { time } : {}),
   };
 }
 

package/app/agentic/cockpit/mount.test.ts

@@ -303,6 +303,7 @@ test("agent-history panel renders the engine run list and a selected run's turns
         content: [{ contentType: "TEXT", text: "did the thing" }],
         toolCalls: [{ toolCallId: "t-1", toolName: "grep", elementId: "tool", arguments: {} }],
         metrics: { inputTokens: 12, outputTokens: 4, reasoningTokenCount: 0, cacheCreationTokenCount: 0, cacheReadTokenCount: 0, durationMs: 900 },
+        producedAt: "2024-05-01T12:34:56.789Z",
       },
     ],
   };
@@ -334,6 +335,17 @@ test("agent-history panel renders the engine run list and a selected run's turns
       assert(transcript != null, "the selected run's history rendered");
       assert((transcript?.textContent ?? "").includes("did the thing"), "the turn text rendered");
       assert((transcript?.textContent ?? "").includes("grep"), "the tool call rendered");
+      // #831 — each turn renders as a collapsed native <details> whose <summary> heading carries the
+      // UTC timestamp. Assert the browser twin mirrors the typed renderer so mount.js can't regress.
+      const turn = transcript?.querySelector(".cockpit-agent-turn");
+      assertEquals(turn?.tagName?.toLowerCase(), "details", "the turn is a <details>");
+      assertEquals(turn?.hasAttribute("open"), false, "collapsed by default: no open attribute");
+      const summary = turn?.querySelector(".cockpit-agent-turn-meta");
+      assertEquals(summary?.tagName?.toLowerCase(), "summary", "the heading is a <summary>");
+      const time = turn?.querySelector(".cockpit-agent-turn-time");
+      assertEquals(time?.tagName?.toLowerCase(), "time", "the timestamp is a <time>");
+      assertEquals(time?.textContent, "12:34:56", "the heading shows the UTC HH:MM:SS");
+      assertEquals(time?.getAttribute("datetime"), "2024-05-01T12:34:56.789Z", "the <time> carries the ISO instant");
     } finally {
       handle.dispose();
     }

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");
+});