@nanobpm/nano-workforce 0.70.0 → 0.70.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.70.2](https://github.com/nanobpm/nano-workforce/compare/v0.70.1...v0.70.2) (2026-08-15)
+
+
+### Bug Fixes
+
+* **merge-loop:** add agent-task liveness SLA backstop for rebase/fix-ci ([#237](https://github.com/nanobpm/nano-workforce/issues/237)) ([c77cdca](https://github.com/nanobpm/nano-workforce/commit/c77cdca974a1e53ef2f9757cc5cedf95068713f1))
+
+## [0.70.1](https://github.com/nanobpm/nano-workforce/compare/v0.70.0...v0.70.1) (2026-08-15)
+
+
+### Bug Fixes
+
+* **convergence:** don't re-review a no-progress round ([#230](https://github.com/nanobpm/nano-workforce/issues/230)) ([a8ea844](https://github.com/nanobpm/nano-workforce/commit/a8ea84444b351989f716124d0b485b42e1ec2a35)), closes [#231](https://github.com/nanobpm/nano-workforce/issues/231) [Magikcraft/nano-bpm#770](https://github.com/Magikcraft/nano-bpm/issues/770) [#770](https://github.com/nanobpm/nano-workforce/issues/770) [nanobpm/nano-workforce#225](https://github.com/nanobpm/nano-workforce/issues/225) [#2](https://github.com/nanobpm/nano-workforce/issues/2) [#770](https://github.com/nanobpm/nano-workforce/issues/770)
+
 # [0.70.0](https://github.com/nanobpm/nano-workforce/compare/v0.69.1...v0.70.0) (2026-08-15)
 
 

package/app/agentSla.test.ts

@@ -0,0 +1,39 @@
+// Unit coverage for the agent-task liveness SLA duration policy. The value is baked into every
+// merge-loop instance's `agentSlaTimeout` process variable and evaluated by the rebase / fix-ci
+// agent tasks' interrupting timer boundary, so a malformed operator env must never deploy an
+// uninterpretable `<bpmn:timeDuration>` — it falls back to the default instead. Run with
+// `node --test`.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { agentSlaTimeout, DEFAULT_AGENT_SLA_TIMEOUT } from "./agentSla.ts";
+
+test("agentSlaTimeout: blank / absent / malformed → default", () => {
+  assert.equal(agentSlaTimeout(undefined), DEFAULT_AGENT_SLA_TIMEOUT);
+  assert.equal(agentSlaTimeout(""), DEFAULT_AGENT_SLA_TIMEOUT);
+  assert.equal(agentSlaTimeout("   "), DEFAULT_AGENT_SLA_TIMEOUT);
+  assert.equal(agentSlaTimeout("2h"), DEFAULT_AGENT_SLA_TIMEOUT); // missing leading P/T
+  assert.equal(agentSlaTimeout("P"), DEFAULT_AGENT_SLA_TIMEOUT); // no component
+  assert.equal(agentSlaTimeout("PT"), DEFAULT_AGENT_SLA_TIMEOUT); // T with no time part
+  assert.equal(agentSlaTimeout("garbage"), DEFAULT_AGENT_SLA_TIMEOUT);
+});
+
+test("agentSlaTimeout: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assert.equal(agentSlaTimeout("PT30M"), "PT30M");
+  assert.equal(agentSlaTimeout("pt4h"), "PT4H");
+  assert.equal(agentSlaTimeout("P1D"), "P1D");
+  assert.equal(agentSlaTimeout("  pt90m  "), "PT90M");
+});
+
+test("agentSlaTimeout: an explicit fallback is honoured for a bad value", () => {
+  assert.equal(agentSlaTimeout("nope", "PT10M"), "PT10M");
+  assert.equal(agentSlaTimeout("PT45M", "PT10M"), "PT45M");
+});
+
+test("the default is itself a well-formed ISO-8601 duration (never an uninterpretable timer)", () => {
+  // Validate the default against the grammar with a *distinct* fallback: if the default were
+  // malformed it would fall through to the sentinel, so equality to itself proves it parses.
+  const sentinel = "PT1S";
+  assert.notEqual(DEFAULT_AGENT_SLA_TIMEOUT, sentinel);
+  assert.equal(agentSlaTimeout(DEFAULT_AGENT_SLA_TIMEOUT, sentinel), DEFAULT_AGENT_SLA_TIMEOUT);
+});

package/app/agentSla.ts

@@ -0,0 +1,33 @@
+// Agent-task liveness SLA policy — kept as a pure module (no env, no I/O) so it is trivially
+// testable, mirroring app/escalationSla.ts. `app/service.ts` seeds the validated `agentSlaTimeout`
+// process variable when it starts the merge-loop; the merge-loop's AGENT service tasks (rebase,
+// fix-ci) carry an interrupting timer boundary whose `<bpmn:timeDuration>=agentSlaTimeout` evaluates
+// it at timer creation (FEEL-expression timer durations, engine-native).
+//
+// This closes the agent-task liveness gap: unlike an escalation *user* task (whose SLA the
+// escalationSla policy already bounds), an AGENT service task has no human in the loop — if no
+// worker holds its capability, or the agent hangs/crashes without failing the job, the token parks
+// on the task forever (no incident, no escalation). The boundary timer makes that impossible: when
+// the SLA elapses the boundary fires, cancels the stuck job, and routes the token to the existing
+// merge escalation so a human is pulled in. It is a durable, in-process backstop — no external
+// watchdog required.
+
+import { isoDuration } from "./reviewWait.ts";
+
+/** Default agent-task SLA (ISO-8601 duration): how long a merge-loop agent service task (rebase /
+ * fix-ci) may sit without completing before its interrupting timer boundary fires and the process
+ * escalates for human attention. Deliberately much shorter than the human-decision escalation SLA
+ * (PT24H): an agent that has not even started (unstaffed capability) or is stuck should surface to a
+ * human quickly, while still being generous enough not to interrupt a legitimately long rebase. */
+export const DEFAULT_AGENT_SLA_TIMEOUT = "PT2H";
+
+/** Validate the operator-supplied agent SLA (env `NANO_PR_AGENT_SLA_TIMEOUT`, ISO-8601 duration),
+ * falling back to {@link DEFAULT_AGENT_SLA_TIMEOUT} when absent, blank, or malformed — a bad env
+ * value must never deploy an uninterpretable timer expression. Derives its validation from the
+ * single canonical {@link isoDuration}. */
+export function agentSlaTimeout(
+  raw: string | undefined,
+  def: string = DEFAULT_AGENT_SLA_TIMEOUT,
+): string {
+  return isoDuration(raw, def);
+}

package/app/convergeGate.test.ts

@@ -0,0 +1,406 @@
+// Convergence comment-gate — unit tests for the canonical router (app/convergeGate.ts), the
+// suppressed-advisory / ack-marker parsers + review-thread fetch helpers (app/github.ts), the
+// pr.converge-gate worker (fail-closed, with injected GitHub readers), and a structural guard over
+// the committed convergence-loop BPMN.
+//
+// The loop used to declare convergence on the agent's self-reported `status = "converged"` with no
+// deterministic check that Copilot's comments were addressed. On Magikcraft/nano-bpm#770 a
+// suppressed advisory was never applied across 20 rounds, yet the PR converged and auto-merged. The
+// fix inserts a deterministic `pr.converge-gate` step on the converged path that blocks convergence
+// while any review thread is unresolved OR any suppressed advisory lacks a RESOLVED `nano-ack:`
+// thread, escalating to the human `wait-answer` task instead of finalizing.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
+import { evaluateConvergeGate } from "./convergeGate.ts";
+import {
+  parseAckedAdvisories,
+  parseReviewThreadsPage,
+  parseSuppressedAdvisories,
+  pickLatestCopilotReviewBody,
+  type ReviewThread,
+} from "./github.ts";
+
+// ── The canonical router ────────────────────────────────────────────────────
+
+test("evaluateConvergeGate: a clean PR (no unresolved threads, no advisories) converges", () => {
+  const r = evaluateConvergeGate({ unresolvedThreadCount: 0, suppressedKeys: [], acknowledgedKeys: [] });
+  assertEquals(r.convergeBlocked, false);
+  assertEquals(r.convergeBlockReason, "");
+});
+
+test("evaluateConvergeGate: an unresolved review thread blocks convergence", () => {
+  const r = evaluateConvergeGate({ unresolvedThreadCount: 2, suppressedKeys: [], acknowledgedKeys: [] });
+  assertEquals(r.convergeBlocked, true);
+  assertStringIncludes(r.convergeBlockReason, "2 unresolved review threads");
+});
+
+test("evaluateConvergeGate: an unacknowledged suppressed advisory blocks convergence", () => {
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount: 0,
+    suppressedKeys: ["spec/a.json:613"],
+    acknowledgedKeys: [],
+  });
+  assertEquals(r.convergeBlocked, true);
+  assertStringIncludes(r.convergeBlockReason, "spec/a.json:613");
+  // Singular noun for exactly one advisory (explicit, not "advisor" + "y/ies" concatenation).
+  assertStringIncludes(r.convergeBlockReason, "1 unacknowledged suppressed advisory (");
+});
+
+test("evaluateConvergeGate: an ACKNOWLEDGED suppressed advisory no longer blocks convergence", () => {
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount: 0,
+    suppressedKeys: ["spec/a.json:613"],
+    acknowledgedKeys: ["spec/a.json:613"],
+  });
+  assertEquals(r.convergeBlocked, false);
+});
+
+test("evaluateConvergeGate: multiple unacknowledged advisories use the plural noun", () => {
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount: 0,
+    suppressedKeys: ["x.ts:10", "y.ts:20"],
+    acknowledgedKeys: [],
+  });
+  assertEquals(r.convergeBlocked, true);
+  assertStringIncludes(r.convergeBlockReason, "2 unacknowledged suppressed advisories (");
+});
+
+test("evaluateConvergeGate: reports both a thread and an advisory when both are outstanding", () => {
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount: 1,
+    suppressedKeys: ["x.ts:10", "y.ts:20"],
+    acknowledgedKeys: ["x.ts:10"],
+  });
+  assertEquals(r.convergeBlocked, true);
+  assertStringIncludes(r.convergeBlockReason, "1 unresolved review thread");
+  assertStringIncludes(r.convergeBlockReason, "y.ts:20");
+  assert(!r.convergeBlockReason.includes("x.ts:10"), "an acknowledged advisory must not be listed");
+});
+
+// ── The parsers (app/github.ts) ─────────────────────────────────────────────
+
+const SAMPLE_REVIEW_BODY = [
+  "## Pull Request Overview",
+  "Some prose that mentions **not/an/advisory:1** in passing.",
+  "",
+  "<details>",
+  "<summary>Suppressed comments (2)</summary>",
+  "",
+  "**spec-app/nano-app.schema.json:613**",
+  "- The description could be clearer about the loopback default.",
+  "",
+  "**server/src/main.rs:42**",
+  "- Consider narrowing this type.",
+  "</details>",
+].join("\n");
+
+test("parseSuppressedAdvisories: extracts only the keys inside the Suppressed comments block", () => {
+  const keys = parseSuppressedAdvisories(SAMPLE_REVIEW_BODY);
+  assertEquals(keys, ["spec-app/nano-app.schema.json:613", "server/src/main.rs:42"]);
+});
+
+test("parseSuppressedAdvisories: returns [] when there is no suppressed block", () => {
+  assertEquals(parseSuppressedAdvisories("## Overview\nLooks good, **file.ts:1** is fine."), []);
+  assertEquals(parseSuppressedAdvisories(null), []);
+  assertEquals(parseSuppressedAdvisories(undefined), []);
+});
+
+test("parseAckedAdvisories: only RESOLVED threads carrying a nano-ack marker count", () => {
+  const threads: ReviewThread[] = [
+    { isResolved: true, path: "a.ts", bodies: ["Fixed. nano-ack: spec-app/nano-app.schema.json:613"] },
+    { isResolved: false, path: "b.ts", bodies: ["nano-ack: server/src/main.rs:42"] }, // open -> ignored
+    { isResolved: true, path: "c.ts", bodies: ["unrelated resolved comment"] },
+  ];
+  const acked = parseAckedAdvisories(threads);
+  assertEquals(acked, ["spec-app/nano-app.schema.json:613"]);
+});
+
+test("parseReviewThreadsPage: maps nodes and reports a complete (final) page", () => {
+  const page = parseReviewThreadsPage({
+    data: {
+      repository: {
+        pullRequest: {
+          reviewThreads: {
+            pageInfo: { hasNextPage: false, endCursor: null },
+            nodes: [{ isResolved: false, path: "a.ts", comments: { nodes: [{ body: "please fix" }] } }],
+          },
+        },
+      },
+    },
+  });
+  assertEquals(page, {
+    threads: [{ isResolved: false, path: "a.ts", bodies: ["please fix"] }],
+    hasNextPage: false,
+    endCursor: null,
+  });
+});
+
+test("parseReviewThreadsPage: a TRUNCATED page reports hasNextPage + its cursor (caller pages on)", () => {
+  // >100 threads: the first:100 page cannot see thread 101+, so instead of silently dropping the
+  // overflow the mapper surfaces `hasNextPage`/`endCursor` and `fetchReviewThreads` pages to
+  // completeness (or fails closed once its bounded page cap is exhausted).
+  const page = parseReviewThreadsPage({
+    data: {
+      repository: {
+        pullRequest: {
+          reviewThreads: {
+            pageInfo: { hasNextPage: true, endCursor: "CURSOR123" },
+            nodes: [{ isResolved: true, path: "a.ts", comments: { nodes: [{ body: "ok" }] } }],
+          },
+        },
+      },
+    },
+  });
+  assertEquals(page, {
+    threads: [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
+    hasNextPage: true,
+    endCursor: "CURSOR123",
+  });
+});
+
+test("parseReviewThreadsPage: FAILS CLOSED (null) when the reviewThreads block is MISSING", () => {
+  // GraphQL errors, permission issues, or a malformed payload can omit `reviewThreads`. Treating that
+  // as "no threads" (empty array) is a fail-OPEN — an unverifiable read must return null so the worker
+  // blocks/escalates rather than converging on a read that never happened.
+  assertEquals(parseReviewThreadsPage({}), null);
+  assertEquals(parseReviewThreadsPage({ data: { repository: { pullRequest: {} } } }), null);
+});
+
+test("parseReviewThreadsPage: FAILS CLOSED (null) when the completeness signal is UNREADABLE", () => {
+  // A present block whose `pageInfo.hasNextPage` is not a readable boolean is unverifiable — we cannot
+  // tell whether more pages exist, so we cannot safely page or map it.
+  const page = parseReviewThreadsPage({
+    data: {
+      repository: {
+        pullRequest: {
+          reviewThreads: {
+            nodes: [{ isResolved: true, path: "a.ts", comments: { nodes: [{ body: "ok" }] } }],
+          },
+        },
+      },
+    },
+  });
+  assertEquals(page, null);
+});
+
+test("pickLatestCopilotReviewBody: picks the NEWEST Copilot review body (oldest\u2192newest order)", () => {
+  const body = pickLatestCopilotReviewBody(
+    [
+      { user: { login: "human" }, body: "human review" },
+      { user: { login: "Copilot" }, body: "old copilot review" },
+      { user: { login: "Copilot" }, body: "newest copilot review" },
+    ],
+    false,
+  );
+  assertEquals(body, "newest copilot review");
+});
+
+test('pickLatestCopilotReviewBody: a complete read with NO Copilot review is verified empty ("")', () => {
+  assertEquals(pickLatestCopilotReviewBody([{ user: { login: "human" }, body: "hi" }], false), "");
+  assertEquals(pickLatestCopilotReviewBody([], false), "");
+});
+
+test("pickLatestCopilotReviewBody: FAILS CLOSED (null) when the reviews read was TRUNCATED", () => {
+  // >100 reviews (a long convergence loop): a first-page-only read returns the OLDEST 100 and misses
+  // the genuinely newest Copilot review, so an unverifiable (truncated) read must block, never return
+  // a stale page's body \u2014 a fail-OPEN on the advisory dimension is the class this gate prevents.
+  assertEquals(
+    pickLatestCopilotReviewBody(
+      [{ user: { login: "Copilot" }, body: "possibly stale" }],
+      true,
+    ),
+    null,
+  );
+});
+
+async function makeUnderTest(deps: {
+  readThreads: (repo: string, n: number) => Promise<ReviewThread[] | null>;
+  readReviewBody: (repo: string, n: number) => Promise<string | null>;
+}) {
+  const { makeHandler } = await import("../workers/converge-gate/worker.ts");
+  return makeHandler(deps);
+}
+
+test("converge-gate: a clean PR is allowed to converge", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
+    readReviewBody: async () => "## Overview\nNo suppressed block.",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
+});
+
+test("converge-gate: an unresolved thread blocks convergence", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [{ isResolved: false, path: "a.ts", bodies: ["please fix"] }],
+    readReviewBody: async () => "",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "unresolved review thread");
+});
+
+test("converge-gate: an unacknowledged suppressed advisory blocks convergence", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => SAMPLE_REVIEW_BODY,
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "spec-app/nano-app.schema.json:613");
+});
+
+test("converge-gate: an acknowledged advisory (resolved ack thread) is allowed", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [
+      { isResolved: true, path: "spec-app/nano-app.schema.json", bodies: ["Applied. nano-ack: spec-app/nano-app.schema.json:613"] },
+      { isResolved: true, path: "server/src/main.rs", bodies: ["Declined, false positive. nano-ack: server/src/main.rs:42"] },
+    ],
+    readReviewBody: async () => SAMPLE_REVIEW_BODY,
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
+});
+
+test("converge-gate: FAILS CLOSED when the threads read returns null (no transport)", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => null,
+    readReviewBody: async () => "",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "could not verify");
+});
+
+test("converge-gate: FAILS CLOSED when the review-body read returns null (no transport)", async () => {
+  // A null review body is unverifiable, not "no advisories" — the gate must block, not fail open on
+  // the suppressed-advisory dimension while the threads read happened to succeed.
+  const handler = await makeUnderTest({
+    readThreads: async () => [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
+    readReviewBody: async () => null,
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "could not verify");
+});
+
+test("converge-gate: FAILS CLOSED when a reader throws", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => {
+      throw new Error("boom");
+    },
+    readReviewBody: async () => "",
+  });
+  const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "could not verify");
+});
+
+test("converge-gate: FAILS CLOSED when the target cannot be resolved", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => "",
+  });
+  const out = await handler({ variables: { prKey: "not-a-pr-key" } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "could not verify");
+});
+
+test("converge-gate: a non-string prKey does not throw — resolves from repo/prNumber vars", async () => {
+  // `parsePr` calls `.trim()`, so a missing/non-string prKey must not reach it: otherwise the job
+  // throws and retries instead of running the fail-closed gate. A well-formed job carrying valid
+  // repo + prNumber but no prKey must still evaluate normally.
+  const handler = await makeUnderTest({
+    readThreads: async () => [{ isResolved: true, path: "a.ts", bodies: ["ok"] }],
+    readReviewBody: async () => "",
+  });
+  const out = await handler({ variables: { repo: "o/r", prNumber: 1 } } as any, {} as any);
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "" });
+});
+
+test("converge-gate: FAILS CLOSED (no throw) when prKey is non-string and repo/prNumber are absent", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [],
+    readReviewBody: async () => "",
+  });
+  const out = await handler({ variables: { prKey: 123 } } as any, {} as any);
+  assertEquals(out.convergeBlocked, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "could not verify");
+});
+
+test("converge-gate: resolves repo/prNumber from the prKey when the vars are absent", async () => {
+  let seen: [string, number] | null = null;
+  const handler = await makeUnderTest({
+    readThreads: async (repo, n) => {
+      seen = [repo, n];
+      return [];
+    },
+    readReviewBody: async () => "",
+  });
+  await handler({ variables: { prKey: "o/r#7" } } as any, {} as any);
+  assertEquals(seen, ["o/r", 7]);
+});
+
+// ── Structural guard over the committed BPMN (no engine) ─────────────────────
+
+const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+function flowElement(id: string): string | null {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*?\\bid="${id}"[^>]*?(?:/>|>(?:(?!<bpmn:sequenceFlow\\b).)*?</bpmn:sequenceFlow>)`,
+  );
+  const m = flat.match(re);
+  return m ? m[0] : null;
+}
+
+test("the converged status arm routes through the check-converge gate, not straight to finalize", () => {
+  const f = flowElement("f_converged");
+  assert(f, "f_converged flow missing");
+  assertStringIncludes(f, 'sourceRef="gw-status"');
+  assertStringIncludes(f, 'targetRef="check-converge"');
+  assertStringIncludes(f, 'status = "converged"');
+});
+
+test("check-converge runs the deterministic converge-gate job and feeds gw-converge-gate", () => {
+  const f = flowElement("f_toConvergeGate");
+  assert(f, "f_toConvergeGate flow missing");
+  assertStringIncludes(f, 'sourceRef="check-converge"');
+  assertStringIncludes(f, 'targetRef="gw-converge-gate"');
+  assertStringIncludes(flat, 'type="pr.converge-gate"');
+});
+
+test("gw-converge-gate blocks on an explicit convergeBlocked = true condition", () => {
+  const f = flowElement("f_convergeBlocked");
+  assert(f, "f_convergeBlocked flow missing");
+  assertStringIncludes(f, 'targetRef="persist-escalation-blockedcomments"');
+  assertStringIncludes(f, "convergeBlocked = true");
+});
+
+test("gw-converge-gate default arm finalizes with no condition", () => {
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-converge-gate"[^>]*>/);
+  assert(gw, "gw-converge-gate gateway missing");
+  assertStringIncludes(gw[0], 'default="f_convergeOk"');
+  const ok = flowElement("f_convergeOk");
+  assert(ok, "f_convergeOk flow missing");
+  assertStringIncludes(ok, 'targetRef="persist-converged"');
+  assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
+});
+
+test("the blocked-comments escalation lands on the human wait-answer task with an answerable escalation", () => {
+  const f = flowElement("f_blockedWait");
+  assert(f, "f_blockedWait flow missing");
+  assertStringIncludes(f, 'sourceRef="persist-escalation-blockedcomments"');
+  assertStringIncludes(f, 'targetRef="wait-answer"');
+  const task = flat.match(
+    /<bpmn:serviceTask\b[^>]*\bid="persist-escalation-blockedcomments"[^>]*>.*?<\/bpmn:serviceTask>/,
+  );
+  assert(task, "persist-escalation-blockedcomments task missing");
+  assertStringIncludes(task[0], 'type="pr.persist-escalation"');
+  assertStringIncludes(task[0], 'target="status"');
+  assertStringIncludes(task[0], 'target="question"');
+  assertStringIncludes(task[0], 'target="recordRound"');
+  // The human sees the gate's own reason (the unresolved threads / unacknowledged advisories).
+  assertStringIncludes(task[0], "convergeBlockReason");
+});

package/app/convergeGate.ts

@@ -0,0 +1,48 @@
+// Convergence comment-gate (issue: don't converge with unaddressed review comments).
+//
+// The review loop declares convergence on the AGENT's self-reported status. That trusts the agent
+// to only say "converged" once every Copilot comment is addressed — which failed on
+// Magikcraft/nano-bpm#770 (20 rounds, a suppressed advisory never applied, then auto-merged with
+// the comment unaddressed). This deterministic gate runs on the converged path and blocks handoff
+// while either:
+//   • any review THREAD is still unresolved, or
+//   • any SUPPRESSED advisory (`path:line` in the latest Copilot review body) lacks a matching
+//     RESOLVED ack thread (a thread carrying a `nano-ack: <path>:<line>` marker).
+// A blocked gate escalates to the human wait-answer task (recoverable), never a hard wedge.
+
+export interface ConvergeGateInput {
+  /** Count of review threads with `isResolved === false`. */
+  unresolvedThreadCount: number;
+  /** `path:line` keys of Copilot's suppressed advisories (latest review body). */
+  suppressedKeys: string[];
+  /** `path:line` keys acknowledged by RESOLVED `nano-ack:` threads. */
+  acknowledgedKeys: string[];
+}
+
+export interface ConvergeGateResult {
+  convergeBlocked: boolean;
+  convergeBlockReason: string;
+}
+
+/** Decide whether a self-reported "converged" round may proceed to finalize. Pure; the worker
+ * feeds it live GitHub state and fails CLOSED (blocks) when that state cannot be read. */
+export function evaluateConvergeGate(input: ConvergeGateInput): ConvergeGateResult {
+  const acked = new Set(input.acknowledgedKeys);
+  const unacked = input.suppressedKeys.filter((k) => !acked.has(k));
+  const reasons: string[] = [];
+  if (input.unresolvedThreadCount > 0) {
+    const n = input.unresolvedThreadCount;
+    reasons.push(`${n} unresolved review thread${n === 1 ? "" : "s"}`);
+  }
+  if (unacked.length > 0) {
+    const noun = unacked.length === 1 ? "advisory" : "advisories";
+    reasons.push(`${unacked.length} unacknowledged suppressed ${noun} (${unacked.join(", ")})`);
+  }
+  if (reasons.length === 0) {
+    return { convergeBlocked: false, convergeBlockReason: "" };
+  }
+  return {
+    convergeBlocked: true,
+    convergeBlockReason: `Convergence blocked: ${reasons.join("; ")}. Resolve every review thread and reply-and-resolve an ack thread (nano-ack: <path>:<line>) for each suppressed advisory before converging.`,
+  };
+}