@nanobpm/nano-workforce 0.193.2 → 0.195.0

package/app/service.test.ts

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

package/app/service.ts

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

package/app/userTasks.ts

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

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.193.2",
+  "version": "0.195.0",
   "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/cockpit/cockpit.css

@@ -316,9 +316,24 @@
   display: flex;
   gap: 8px;
   align-items: baseline;
-  margin-bottom: 4px;
+  cursor: pointer;
+  list-style: none;
+  user-select: none;
+}
+
+.cockpit-agent-turn-meta::-webkit-details-marker { display: none; }
+
+.cockpit-agent-turn-meta::before {
+  content: "\25B8";
+  color: var(--cockpit-muted);
+  font-size: 11px;
+  width: 10px;
 }
 
+.cockpit-agent-turn[open] > .cockpit-agent-turn-meta::before { content: "\25BE"; }
+
+.cockpit-agent-turn-body { margin-top: 4px; padding-left: 18px; }
+
 .cockpit-agent-turn-role {
   font-size: 11px;
   text-transform: uppercase;
@@ -327,6 +342,7 @@
 }
 
 .cockpit-agent-turn-iter,
+.cockpit-agent-turn-time,
 .cockpit-agent-turn-metrics {
   font-size: 11px;
   color: var(--cockpit-muted);

package/pages/cockpit/mount.js

@@ -574,6 +574,15 @@ function turnMetrics(m) {
   return dur != null ? `${base} \u00b7 ${dur}` : base;
 }
 
+function turnTime(iso) {
+  if (iso == null || iso === "") return undefined;
+  const ms = Date.parse(iso);
+  if (!Number.isFinite(ms)) return undefined;
+  const d = new Date(ms);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}`;
+}
+
 function agentHistoryView(report) {
   const turns = (report.records ?? []).map((r) => ({
     historyItemKey: r.historyItemKey,
@@ -582,6 +591,8 @@ function agentHistoryView(report) {
     text: turnText(r),
     toolCalls: (r.toolCalls ?? []).map((c) => ({ toolCallId: c.toolCallId, toolName: c.toolName, elementId: c.elementId })),
     metrics: turnMetrics(r.metrics),
+    producedAt: r.producedAt != null && r.producedAt !== "" ? r.producedAt : undefined,
+    time: turnTime(r.producedAt),
   }));
   return {
     agentInstanceKey: report.agentInstanceKey,
@@ -639,17 +650,28 @@ function renderAgentSessions(host, doc, view, onSelect, activeInstanceKey) {
   host.appendChild(root);
 }
 
+// One turn as a native collapsible <details> (collapsed by default); its <summary> heading (role,
+// iteration, timestamp, metrics) toggles the details body on click (#831).
 function agentTurnBlock(doc, t) {
-  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 != null) {
+    const time = el(doc, "time", "cockpit-agent-turn-time", t.time);
+    if (t.producedAt != null) {
+      time.setAttribute("datetime", t.producedAt);
+      time.setAttribute("title", t.producedAt);
+    }
+    meta.appendChild(time);
+  }
   if (t.metrics != null) 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");
     for (const call of t.toolCalls) {
@@ -657,8 +679,9 @@ function agentTurnBlock(doc, t) {
       li.setAttribute("data-tool-call-id", call.toolCallId);
       tools.appendChild(li);
     }
-    block.appendChild(tools);
+    body.appendChild(tools);
   }
+  block.appendChild(body);
   return block;
 }
 

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\""
+      }
+    }
+  ]
+}