@nanobpm/nano-workforce 0.194.0 → 0.195.1

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
@@ -1121,8 +1226,10 @@ test("repoEnvelopeVars emits the push-checkpoint under the harness-read `sha` ke
 
 // Pre-PR provisioning (issue #684): the implementation path has no head branch yet, so it passes
 // `ref = base` + a `branchCreate` so the harness clones the base and cuts the deterministic
-// `feat/<task.id>` feature branch off it. `branch.create` is emitted only for a non-blank branch and
-// is absent on the PR-based paths (which check out an existing head).
+// `feat/<task.id>` feature branch off it. `branch.create` is emitted only for a non-blank branch.
+// The PR-based paths (review-round / fix-ci / rebase) now pass `branchCreate = headRef` too (equal
+// to `ref`) so the harness commits/pushes to the PR head branch instead of cutting a throwaway
+// `nano/agent-work/*` fallback (jwulf/c8ctl-plugin-nano#231); see the PR-path test below.
 test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#684)", () => {
   const repo = (repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7") as any)["io.nanobpm.agentTask"]
     .repository;
@@ -1147,7 +1254,95 @@ test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#
   assertEquals("branch" in (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"].repository, false);
 });
 
-// Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5): `worldRestoreSha` — the seam
+// PR-path provisioning (jwulf/c8ctl-plugin-nano#231): the review-round / fix-ci / rebase call sites
+// pass `branchCreate = headRef` (equal to `ref`, the PR head). 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 (the head never advances → no-progress escalation). With
+// `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR
+// head branch itself.
+test("repoEnvelopeVars emits branch.create = head on the PR path (ref == create == head) (#231)", () => {
+  const repo = (repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12") as any)[
+    "io.nanobpm.agentTask"
+  ].repository;
+  assertEquals(repo.ref, "feat/issue-12", "the PR-path envelope checks out the head branch");
+  assertEquals(repo.branch.create, "feat/issue-12", "and asks the harness to work on that same head branch, not a fallback");
+  // Still branch-scoped and blobless, and the base tip stays reachable for the 3-dot diff.
+  assertEquals(repo.singleBranch, true);
+  assertEquals(repo.filter, "blob:none");
+  assertEquals(repo.baseRef, "main");
+});
+
+// Regression guard for the ACTUAL call sites (Copilot PR #817 review): the helper test above would
+// still pass if `submitPr`/`startMerge` dropped the 5th `branchCreate` argument, because
+// `repoEnvelopeVars` accepted it before this change. Drive both PUBLIC entry points with a mocked
+// PR-head response and assert the seeded `createInstance` envelope carries `branch.create === headRef`
+// — i.e. the call sites really thread the PR head into the branch-create slot (jwulf/c8ctl-plugin-nano#231).
+// Both `fetchPrMeta` (submit) and `fetchPrHead` (merge) read the same token-transport pulls endpoint,
+// so one fetch stub returning `head.ref` covers both.
+function withGithubHead(headRef: string, baseRef: string, run: () => Promise<void>): Promise<void> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "t0ken";
+  globalThis.fetch = ((url: string | URL | Request) => {
+    void url;
+    return Promise.resolve(
+      new Response(
+        JSON.stringify({ title: "PR title", body: "", head: { ref: headRef, sha: "HEADSHA" }, base: { ref: baseRef } }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      ),
+    );
+  }) as typeof fetch;
+  return run().finally(() => {
+    globalThis.fetch = prevFetch;
+    if (prevMode !== undefined) process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    else delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    if (prevTok !== undefined) process.env["GITHUB_TOKEN"] = prevTok;
+    else delete process.env["GITHUB_TOKEN"];
+  });
+}
+
+test("submitPr threads the resolved PR head into the envelope branch.create (#231)", async () => {
+  await withGithubHead("feat/issue-12", "main", async () => {
+    const { data, engine, get } = captureVars();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 12,
+      url: "https://github.com/owner/repo/pull/12",
+      prKey: "owner/repo#12",
+    });
+    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
+    assertEquals(repo?.ref, "feat/issue-12", "submitPr checks out the PR head branch");
+    assertEquals(repo?.branch?.create, "feat/issue-12", "submitPr passes headRef as branch.create, not a fallback");
+  });
+});
+
+test("startMerge threads the resolved PR head into the envelope branch.create (#231)", async () => {
+  await withGithubHead("feat/issue-13", "main", async () => {
+    const { data, engine, get } = captureVars();
+    await data.table("pull_requests", "pr_key").insert({
+      pr_key: "owner/repo#13",
+      repo: "owner/repo",
+      number: 13,
+      url: "https://github.com/owner/repo/pull/13",
+      status: "converged",
+      abandon_token: "tok-13",
+      root_request_key: "owner/repo#13",
+    });
+    await startMerge(data, engine, {
+      repo: "owner/repo",
+      number: 13,
+      url: "https://github.com/owner/repo/pull/13",
+      prKey: "owner/repo#13",
+      round: 2,
+    });
+    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
+    assertEquals(repo?.ref, "feat/issue-13", "startMerge checks out the PR head branch");
+    assertEquals(repo?.branch?.create, "feat/issue-13", "startMerge passes headRef as branch.create, not a fallback");
+  });
+});
+
 // `submitPr`/`startMerge` thread into `repoEnvelopeVars` — hands the harness the last push-checkpoint
 // ONLY when the enrolled fleet advertises `durable-resume`. With no participant it degrades to null,
 // so the round redrives from scratch (exactly as today). Proven against a REAL in-memory SQLite db

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,
@@ -731,7 +758,14 @@ async function submitPrCritical(
       // Host-git provisioning (c8ctl): deliver the repository envelope so the `senior:pr-review`
       // harness clones an isolated workspace checked out on the PR head branch. Spread last so an
       // unresolved head (`{}`) leaves the other vars untouched.
-      ...repoEnvelopeVars(parsed.repo, headRef, baseRef, worldSha),
+      //
+      // Pass `headRef` as `branch.create` too (5th arg): on a PR path `ref` is the head branch, but
+      // 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 (the head never advances → no-progress escalation).
+      // With `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes
+      // to the PR head branch itself. Mirrors the delivery-graph node path (`agentNodeRepoEnvelope`, #776).
+      ...repoEnvelopeVars(parsed.repo, headRef, baseRef, worldSha, headRef),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
@@ -892,8 +926,10 @@ export async function startMerge(
       abandonUrl: abUrl,
       abandonBrief: renderAbandonBrief(abUrl),
       // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the
-      // fix-ci/rebase agents operate on an isolated checkout of the PR head branch.
-      ...repoEnvelopeVars(pr.repo, headRef, baseRef, worldSha),
+      // fix-ci/rebase agents operate on an isolated checkout of the PR head branch. `headRef` is
+      // passed as `branch.create` (5th arg) so the harness commits/pushes to the PR head branch
+      // instead of cutting a `nano/agent-work/*` fallback (jwulf/c8ctl-plugin-nano#231); see submitPr.
+      ...repoEnvelopeVars(pr.repo, headRef, baseRef, worldSha, headRef),
     },
   });
   if (processInstanceKey != null) {
@@ -2469,13 +2505,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 +3104,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",

package/db/migrations/116_feature_runs_human_approval.sql

@@ -0,0 +1,51 @@
+-- Issue #826: optional human approval before merge. 1 ⇒ the converged PR parks at the
+-- `merge-approval` user task in convergence-loop.bpmn before the merge-loop runs. Additive (expand).
+ALTER TABLE feature_runs ADD COLUMN human_approval INTEGER NOT NULL DEFAULT 0;
+
+-- Mirror the new column through the `delivery_units` aggregate so the `feature_runs__units` compat VIEW
+-- stays row-for-row equal to `feature_runs` (ADR 0006, parity-tested in app/deliveryUnit.test.ts): the
+-- Feature sync triggers (089) and VIEW (091) are re-created verbatim plus `human_approval`.
+ALTER TABLE delivery_units ADD COLUMN human_approval INTEGER;
+UPDATE delivery_units SET human_approval = 0 WHERE kind = 'feature';
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, human_approval, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.human_approval, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.human_approval AS human_approval,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';

package/e2e/feature-run.e2e.ts

@@ -62,6 +62,7 @@ interface FeatureRow {
 }
 interface PrRow {
   pr_key: string;
+  process_key: string | null;
 }
 
 describe("single-issue feature run (#172 — feature.bpmn)", () => {
@@ -184,6 +185,23 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
     );
   });
 
+  test("raise + converge + human approval: the enrolled convergence loop carries the approval gate (issue #826)", async () => {
+    await withApp(
+      { "senior:feature": () => ({ status: "opened", pr: "owner/repo#103", summary: "built it" }) },
+      { baseBranch: "epic/e2e", converge: true, autoMerge: true, humanApproval: true },
+      async ({ app }) => {
+        // The flag must survive the real handoff: feature.bpmn → converge-cell callActivity →
+        // pr.converge-feature → submitPr → the live loop instance (still ACTIVE, so its vars are readable).
+        const pr = await app.db.table<PrRow>("pull_requests", "pr_key").findOne({ pr_key: "owner/repo#103" });
+        assert.ok(pr?.process_key, "converge enrolled the raised PR into a live convergence loop");
+        const instances = app.snapshot().instances;
+        assert.ok(Array.isArray(instances), "snapshot.instances is an array of instance rows");
+        const loop = instances.find((i) => i?.key === pr.process_key);
+        assert.equal(loop?.variables?.humanApproval, true, "the convergence loop was seeded with humanApproval");
+      },
+    );
+  });
+
   test("blocked: parks at the operators' user task (non-terminal), never enrolls a PR, settles on ack", async () => {
     await withApp(
       { "senior:feature": () => ({ status: "blocked", summary: "could not proceed" }) },

package/openapi.yaml

@@ -3442,6 +3442,12 @@ components:
             When true (and `converge` is true), drive the merge-loop after convergence only when
             `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`.
             Moot when `converge` is false.
+        humanApproval:
+          type: boolean
+          description: >-
+            When true (with `autoMerge`), the converged PR waits in Tasks for a human to approve the
+            merge or request changes; the agent applies them to the same PR and convergence re-runs.
+            Moot when the run does not merge (see `autoMerge`).
         confirmDefaultBase:
           type: boolean
           description: >-
@@ -3513,6 +3519,9 @@ components:
         autoMerge:
           type: boolean
           description: When true (with `converge`), drive the merge-loop. See `FeatureStartByIssue.autoMerge`.
+        humanApproval:
+          type: boolean
+          description: When true (with `autoMerge`), a human approves the merge. See `FeatureStartByIssue.humanApproval`.
         confirmDefaultBase:
           type: boolean
           description: Acknowledge landing on the default branch. See `PlanStartByIssue.confirmDefaultBase`.
@@ -6181,6 +6190,9 @@ paths:
                     autoMerge:
                       type: boolean
                       description: When true (and `converge` is true), drive the merge-loop after convergence only when `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`. Moot when `converge` is false.
+                    humanApproval:
+                      type: boolean
+                      description: When true (with `autoMerge`), the converged PR waits in Tasks for a human to approve the merge or request changes; the agent applies them to the same PR and convergence re-runs. Moot when the run does not merge (see `autoMerge`).
                     confirmDefaultBase:
                       type: boolean
                       description: Acknowledge that `baseBranch` is the repository default branch (the PR would target it directly). See `PlanStartByIssue.confirmDefaultBase`.
@@ -6326,6 +6338,9 @@ paths:
                     autoMerge:
                       type: boolean
                       description: When true (with `converge`), drive the merge-loop. See `FeatureStartByIssue.autoMerge`.
+                    humanApproval:
+                      type: boolean
+                      description: When true (with `autoMerge`), a human approves the merge. See `FeatureStartByIssue.humanApproval`.
                     confirmDefaultBase:
                       type: boolean
                       description: Acknowledge landing on the default branch. See `PlanStartByIssue.confirmDefaultBase`.

package/operations/startFeature.readiness.integration.test.ts

@@ -193,3 +193,17 @@ test("malformed readiness descriptor → 400 at the edge (never a 500)", async (
     assertEquals(started.length, 0);
   });
 });
+
+// ── human approval before merge (issue #826): threaded through the edge, pinned off without autoMerge ─
+
+test("humanApproval reaches the run only together with autoMerge", async () => {
+  await withGithub(REPO, async () => {
+    for (const [autoMerge, expected] of [[true, true], [false, false]] as const) {
+      const { app, started } = makeApp();
+      const body = { issue: `${REPO}#577`, ...GATED_BASE, converge: true, autoMerge, humanApproval: true };
+      const res = (await startFeature(input(body), app)) as any;
+      assertEquals(res.status, 202);
+      assertEquals(started[0].variables?.humanApproval, expected);
+    }
+  });
+});

package/operations/startFeature.ts

@@ -116,6 +116,8 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // Auto-merge is only meaningful as a follow-on to convergence; pin it off when converge is off so
   // the persisted row and the process variable can't disagree.
   const autoMerge = converge && "autoMerge" in body && body.autoMerge === true;
+  // Human approval gates the merge-loop, so it is moot (pinned off) without auto-merge (issue #826).
+  const humanApproval = autoMerge && "humanApproval" in body && body.humanApproval === true;
   // Optional operator steering threaded to the implementation agent's prompt. Empty/whitespace is
   // normalized to null downstream (startFeature) so it never appends an empty instruction block.
   const customInstructions = "customInstructions" in body && typeof body.customInstructions === "string"
@@ -176,12 +178,14 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     autoMerge,
     customInstructions,
     { probes: readiness.probes, probeTimeout: readiness.probeTimeout, probePollEvery: readiness.probePollEvery },
+    humanApproval,
   );
   app.log.info("feature run intake", {
     featureKey: parsed.planKey,
     requestedBaseBranch: normalizedBase,
     converge,
     autoMerge,
+    humanApproval,
     hasCustomInstructions: typeof customInstructions === "string" && customInstructions.trim() !== "",
     readinessProbes: readiness.probes.length,
     outcome: result.outcome,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.194.0",
+  "version": "0.195.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/feature.page.json

@@ -90,6 +90,7 @@
           { "key": "baseBranch", "label": "Base branch: the branch the PR targets, e.g. main. A missing epic/* branch is auto-created off default HEAD; a non-epic/* branch must already exist.", "type": "text", "required": true, "requiredMessage": "Name the branch the PR targets (e.g. main or epic/agent-protocol)" },
           { "key": "customInstructions", "label": "Custom instructions (optional) \u2014 extra steering appended to the implementation agent's prompt, e.g. \u201cprefer Deno; keep the diff small; add integration tests\u201d", "type": "text" },
           { "key": "converge", "label": "Converge \u2014 hand the raised PR to the review-convergence loop", "type": "checkbox" },
+          { "key": "humanApproval", "label": "Human approval before merge \u2014 a converged PR waits in Tasks for you to approve the merge or request changes (only applies when Auto-merge is on)", "type": "checkbox" },
           { "key": "autoMerge", "label": "Auto-merge \u2014 after convergence, drive the merge-loop (only applies when Converge is on)", "type": "checkbox" },
           { "key": "confirmDefaultBase", "label": "Confirm landing on the default branch \u2014 required only when the base above IS the repository default", "type": "checkbox" },
           { "key": "allowSharedBase", "label": "Allow sharing a custom integration branch with another active epic", "type": "checkbox" }

package/resources/forms/merge-approval.form

@@ -0,0 +1,36 @@
+{
+  "id": "merge-approval",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "text",
+      "label": "Approve merge",
+      "text": "This PR passed review convergence. Approve it to hand it to the merge loop, or request changes: your guidance goes to the review agent, which updates this same PR. Convergence then re-runs and approval is asked again."
+    },
+    {
+      "type": "select",
+      "key": "mergeDecision",
+      "label": "Decision",
+      "values": [
+        { "label": "Approve — merge the PR", "value": "approve" },
+        { "label": "Request changes — send guidance to the agent", "value": "revise" }
+      ],
+      "validate": {
+        "required": true
+      }
+    },
+    {
+      "type": "textarea",
+      "key": "answer",
+      "label": "Guidance for the agent",
+      "description": "What should change before this PR merges? The agent implements it on the same PR.",
+      "validate": {
+        "required": true
+      },
+      "conditional": {
+        "hide": "=mergeDecision != \"revise\""
+      }
+    }
+  ]
+}