@nanobpm/nano-workforce 0.69.1 → 0.70.1

package/app/agentic/transcript-read.ts

@@ -0,0 +1,161 @@
+// nano-workforce — the transcript READ projection (ADR 0056, H3 / #146, read path #222).
+//
+// The write path (relay.family.ts) flushes an ephemeral agent's PTY stream to a durable transcript on
+// job completion; this module is the READ counterpart the advisory `GET /agentic/transcripts*`
+// endpoints share. It projects a {@link TranscriptStore} row (+ its retained chunks) onto the wire
+// shape and enriches it with the H6 correlation (`app/agentic/correlation.ts`) so a captured session
+// lines up with "that process instance / this plan" — even after the ephemeral agent has exited.
+//
+// Correlation is BEST-EFFORT and advisory: the correlation registry is in-memory and only holds
+// currently-linked jobs, so a completed session's process-instance / plan context is present only
+// while the job is still live. The jobKey itself is always recoverable — it is encoded in the stream
+// id (`job:<jobKey>`), so a past session is never anonymous even once its correlation has been released.
+//
+// Pure and side-effect-free apart from reading the store: no I/O beyond the injected store, so it is
+// unit-testable on the injected env (Node, no browser), and never touches the engine or a BPMN flow.
+
+import type { TranscriptChunk, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
+import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
+
+/** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
+export function byteLengthOf(chunks: readonly TranscriptChunk[]): number {
+  let total = 0;
+  for (const c of chunks) total += Buffer.byteLength(c.chunk, "utf8");
+  return total;
+}
+
+/** The correlation fields (jobKey + engine context) a stream id resolves to, best-effort. */
+interface CorrelationFields {
+  jobKey?: string;
+  processInstanceKey?: string;
+  bpmnProcessId?: string;
+  elementId?: string;
+  planKey?: string;
+}
+
+/**
+ * Resolve a stream id to its correlation fields: the jobKey is always decoded from a `job:<jobKey>`
+ * stream id; the engine context (process instance / plan) is added only when the correlation registry
+ * still holds the (live) job. Non-job streams yield an empty object.
+ */
+export function correlationFieldsFor(stream: string, correlation: CorrelationRegistry | undefined): CorrelationFields {
+  const jobKey = jobKeyOfStream(stream);
+  if (jobKey === undefined) return {};
+  const fields: CorrelationFields = { jobKey };
+  const context = correlation?.resolve(jobKey);
+  if (context) {
+    if (context.processInstanceKey !== undefined) fields.processInstanceKey = context.processInstanceKey;
+    if (context.bpmnProcessId !== undefined) fields.bpmnProcessId = context.bpmnProcessId;
+    if (context.elementId !== undefined) fields.elementId = context.elementId;
+    if (context.planKey !== undefined) fields.planKey = context.planKey;
+  }
+  return fields;
+}
+
+/** Project a stored transcript's metadata (+ its retained chunks) onto the list wire shape. */
+export function toTranscript(
+  meta: TranscriptStream,
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+): AgenticTranscript {
+  const chunks = store.read(meta.stream);
+  const out: AgenticTranscript = {
+    stream: meta.stream,
+    lifecycle: meta.lifecycle,
+    status: meta.status,
+    createdAt: meta.createdAt,
+    nextOffset: meta.nextOffset,
+    byteLength: byteLengthOf(chunks),
+    chunkCount: chunks.length,
+  };
+  if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
+  if (meta.firstOffset !== undefined) out.firstOffset = meta.firstOffset;
+  const fields = correlationFieldsFor(meta.stream, correlation);
+  if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
+  if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
+  if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
+  if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.planKey !== undefined) out.planKey = fields.planKey;
+  return out;
+}
+
+/** The filters {@link listTranscripts} understands (all optional; an empty filter returns everything). */
+export interface TranscriptFilter {
+  readonly jobKey?: string;
+  readonly processInstanceKey?: string;
+  readonly planKey?: string;
+  /** ISO-8601 lower bound (inclusive) on the session's createdAt. */
+  readonly since?: string;
+  /** ISO-8601 upper bound (inclusive) on the session's createdAt. */
+  readonly until?: string;
+}
+
+/**
+ * List every captured session projected to the wire shape, sorted newest-first by createdAt (then by
+ * stream for a stable tie-break), after applying the (advisory) filters. jobKey / process-instance /
+ * plan filters match the correlation-enriched fields; since/until bound createdAt.
+ */
+export function listTranscripts(
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+  filter: TranscriptFilter = {},
+): AgenticTranscript[] {
+  const sinceMs = filter.since !== undefined ? Date.parse(filter.since) : undefined;
+  const untilMs = filter.until !== undefined ? Date.parse(filter.until) : undefined;
+  const rows = store
+    .list()
+    .map((meta) => toTranscript(meta, store, correlation))
+    .filter((t) => {
+      if (filter.jobKey !== undefined && t.jobKey !== filter.jobKey) return false;
+      if (filter.processInstanceKey !== undefined && t.processInstanceKey !== filter.processInstanceKey) return false;
+      if (filter.planKey !== undefined && t.planKey !== filter.planKey) return false;
+      const createdMs = Date.parse(t.createdAt);
+      if (sinceMs !== undefined && Number.isFinite(createdMs) && createdMs < sinceMs) return false;
+      if (untilMs !== undefined && Number.isFinite(createdMs) && createdMs > untilMs) return false;
+      return true;
+    });
+  // Newest session first (a "past sessions" feed reads best most-recent-first); stable on stream id.
+  rows.sort((a, b) => {
+    const byTime = b.createdAt.localeCompare(a.createdAt);
+    return byTime !== 0 ? byTime : a.stream.localeCompare(b.stream);
+  });
+  return rows;
+}
+
+/**
+ * Fetch a stored transcript's bytes from offset `from` (inclusive), projected onto the range/offset
+ * wire shape — the SAME resume-from-offset contract the live terminal renders, so the cockpit replays
+ * a closed stream through its existing renderer. Returns undefined when the stream has no transcript.
+ */
+export function readTranscriptFrom(
+  stream: string,
+  from: number,
+  store: TranscriptStore,
+  correlation: CorrelationRegistry | undefined,
+): AgenticTranscriptData | undefined {
+  const meta = store.get(stream);
+  if (meta === undefined) return undefined;
+  const slice = store.since(stream, from);
+  const entries = slice.entries.map((c) => ({ offset: c.offset, chunk: c.chunk }));
+  const out: AgenticTranscriptData = {
+    stream: meta.stream,
+    lifecycle: meta.lifecycle,
+    status: meta.status,
+    createdAt: meta.createdAt,
+    nextOffset: slice.nextOffset,
+    byteLength: byteLengthOf(slice.entries),
+    chunkCount: entries.length,
+    from,
+    gap: slice.gap,
+    entries,
+  };
+  if (meta.completedAt !== undefined) out.completedAt = meta.completedAt;
+  const fields = correlationFieldsFor(meta.stream, correlation);
+  if (fields.jobKey !== undefined) out.jobKey = fields.jobKey;
+  if (fields.processInstanceKey !== undefined) out.processInstanceKey = fields.processInstanceKey;
+  if (fields.bpmnProcessId !== undefined) out.bpmnProcessId = fields.bpmnProcessId;
+  if (fields.elementId !== undefined) out.elementId = fields.elementId;
+  if (fields.planKey !== undefined) out.planKey = fields.planKey;
+  return out;
+}

package/app/blackboard.test.ts

@@ -36,15 +36,23 @@ test("publicBaseUrl: honours the env override and trims a trailing slash", () =>
 });
 
 test("publicBaseUrl: a blank/whitespace override falls back instead of yielding a bad URL", () => {
-  const prev = process.env.NANO_PR_BASE_URL;
-  delete process.env.NANO_PR_BASE_URL;
+  // Explicit override args bypass the `process.env.NANO_WORKFORCE_BASE_URL` default, so this test
+  // needs no env manipulation — the env-read path is covered by the dedicated test below.
+  assertEquals(publicBaseUrl(""), "http://localhost:3000");
+  assertEquals(publicBaseUrl("   "), "http://localhost:3000");
+  assertEquals(blackboardUrl("t", publicBaseUrl("")), "http://localhost:3000/app/api/hooks/blackboard?token=t");
+});
+
+test("publicBaseUrl: reads NANO_WORKFORCE_BASE_URL from the environment by default", () => {
+  const prev = process.env.NANO_WORKFORCE_BASE_URL;
   try {
-    assertEquals(publicBaseUrl(""), "http://localhost:3000");
-    assertEquals(publicBaseUrl("   "), "http://localhost:3000");
-    assertEquals(blackboardUrl("t", publicBaseUrl("")), "http://localhost:3000/app/api/hooks/blackboard?token=t");
+    process.env.NANO_WORKFORCE_BASE_URL = "https://fleet.example.com/console/app-view/Workforce/";
+    assertEquals(publicBaseUrl(), "https://fleet.example.com/console/app-view/Workforce");
+    delete process.env.NANO_WORKFORCE_BASE_URL;
+    assertEquals(publicBaseUrl(), "http://localhost:3000");
   } finally {
-    if (prev === undefined) delete process.env.NANO_PR_BASE_URL;
-    else process.env.NANO_PR_BASE_URL = prev;
+    if (prev === undefined) delete process.env.NANO_WORKFORCE_BASE_URL;
+    else process.env.NANO_WORKFORCE_BASE_URL = prev;
   }
 });
 

package/app/blackboard.ts

@@ -70,11 +70,11 @@ export function mintBlackboardToken(): string {
 
 /** The externally-reachable base URL agents use to reach this app. Must resolve from WHEREVER the
  * agent runs (co-located or remote/containerised), so it is configured, never hardcoded. */
-export function publicBaseUrl(env: string | undefined = process.env.NANO_PR_PUBLIC_BASE_URL): string {
-  // Cascade through the fallback chain, skipping any value that is unset OR blank/whitespace, so an
-  // explicitly-set-but-empty NANO_PR_PUBLIC_BASE_URL can't yield a malformed capability URL.
+export function publicBaseUrl(env: string | undefined = process.env.NANO_WORKFORCE_BASE_URL): string {
+  // Skip the override if it is unset OR blank/whitespace, so an explicitly-set-but-empty
+  // NANO_WORKFORCE_BASE_URL can't yield a malformed capability URL.
   const base =
-    [env, process.env.NANO_PR_BASE_URL, "http://localhost:3000"]
+    [env, "http://localhost:3000"]
       .map((v) => v?.trim())
       .find((v): v is string => Boolean(v)) ?? "http://localhost:3000";
   return base.replace(/\/+$/, "");

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.`,
+  };
+}