@nanobpm/nano-workforce 0.70.0 → 0.70.2

package/app/github.ts

@@ -77,6 +77,231 @@ export async function fetchPrReviews(
   return (await r.json()) as GhReview[];
 }
 
+// ── Review-comment convergence gate (don't converge with unaddressed comments) ──────────────
+//
+// A PR must not be declared converged while Copilot still has unaddressed review comments. Two
+// kinds must be gated:
+//   • unresolved review THREADS — deterministic (GraphQL `isResolved`).
+//   • SUPPRESSED / low-confidence advisories — Copilot folds these into the review BODY under a
+//     "Suppressed comments (N)" block; they are NOT threads, cannot be resolved, and are re-listed
+//     every round. To make "acknowledged" trackable, the review-round agent must post a RESOLVED
+//     review thread carrying a `nano-ack: <path>:<line>` marker (the exact key from Copilot's
+//     `**path:line**` header) for each advisory it applies or declines. The gate then treats an
+//     advisory as addressed iff a resolved thread carries its ack marker.
+
+/** One PR review thread, narrowed to what the convergence gate needs. */
+export interface ReviewThread {
+  isResolved: boolean;
+  path: string | null;
+  bodies: string[];
+}
+
+/** The `nano-ack:` acknowledgement marker the review-round agent stamps into the resolved thread
+ * it opens per suppressed advisory. The captured group is the advisory key (`path:line`). */
+const ACK_MARKER = /nano-ack:\s*([^\s)>*]+:\d+)/gi;
+
+/** Parse the `path:line` keys of Copilot's suppressed / low-confidence advisories out of a review
+ * body. Copilot renders them under a `<summary>Suppressed comments (N)</summary>` block, each as a
+ * bold `**path:line**` header. Returns the de-duplicated keys (empty when there is no such block). */
+export function parseSuppressedAdvisories(reviewBody: string | null | undefined): string[] {
+  const body = reviewBody ?? "";
+  const idx = body.search(/Suppressed comments\s*\(/i);
+  if (idx < 0) return [];
+  // Scan only from the "Suppressed comments" marker onward so a `**path:line**` elsewhere in the
+  // overview prose can never be mistaken for an advisory.
+  const region = body.slice(idx);
+  const keys = new Set<string>();
+  const re = /\*\*([^*]+?:\d+)\*\*/g;
+  let m: RegExpExecArray | null;
+  // biome-ignore lint/suspicious/noAssignInExpressions: canonical regex-exec accumulation loop
+  while ((m = re.exec(region)) !== null) keys.add(m[1].trim());
+  return [...keys];
+}
+
+/** Extract the acknowledged advisory keys from a set of review threads (only RESOLVED threads
+ * count — an open ack thread is not yet an acknowledgement). */
+export function parseAckedAdvisories(threads: ReviewThread[]): string[] {
+  const acked = new Set<string>();
+  for (const t of threads) {
+    if (!t.isResolved) continue;
+    for (const body of t.bodies) {
+      ACK_MARKER.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      // biome-ignore lint/suspicious/noAssignInExpressions: canonical regex-exec accumulation loop
+      while ((m = ACK_MARKER.exec(body)) !== null) acked.add(m[1].trim());
+    }
+  }
+  return [...acked];
+}
+
+/** Pick the newest Copilot review body from a reviews list (GitHub returns them oldest→newest).
+ * `truncated = true` means we could NOT read every page — the genuinely-latest review may be unread,
+ * so the result is UNVERIFIABLE and we fail CLOSED (`null`) rather than return a stale page's body;
+ * a fail-OPEN on the advisory dimension (reading an old review and missing a newer suppressed
+ * advisory) is the exact class this gate exists to prevent. A verified-complete read with no Copilot
+ * review returns `""` (a verified "no advisories"). Pure; unit-tested. */
+export function pickLatestCopilotReviewBody(
+  reviews: { user?: { login?: string }; body?: string }[],
+  truncated: boolean,
+): string | null {
+  if (truncated) return null;
+  const copilot = reviews.filter((rv) => isCopilot(rv.user?.login));
+  return copilot[copilot.length - 1]?.body ?? "";
+}
+
+/** Fetch the latest Copilot review body for a PR (the newest review authored by the automated
+ * Copilot reviewer). Returns `null` ONLY when no transport is usable (unverifiable → the worker
+ * fails closed); returns `""` when transport is usable but the PR has no Copilot review yet (a
+ * verified "no suppressed advisories"). Throws on a genuine transport failure. This split keeps
+ * `null` from conflating "unverifiable" with "empty" and fail-OPENing the advisory dimension. */
+export async function fetchLatestCopilotReviewBody(
+  repo: string,
+  number: number | string,
+  token: string,
+): Promise<string | null> {
+  const mode = githubTransport();
+  const useGh = mode === "gh" || (mode === "auto" && (await isGhAvailable()));
+  const basePath = `repos/${repo}/pulls/${number}/reviews?per_page=100`;
+  interface Review {
+    user?: { login?: string };
+    body?: string;
+  }
+  if (useGh) {
+    // `--paginate` merges EVERY page of the (oldest→newest) reviews array, so a >100-review
+    // convergence loop still surfaces the genuinely newest Copilot review rather than the oldest
+    // 100 — reading only the first page here would fail-OPEN the advisory dimension.
+    const out = await runGh(["api", "--paginate", basePath, "-H", "Accept: application/vnd.github+json"]);
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const reviews = JSON.parse(out) as Review[];
+    return pickLatestCopilotReviewBody(reviews, false);
+  }
+  if (!token) return null;
+  // Page the token transport the same way; 20×100 reviews is far past any real convergence loop, and
+  // a genuinely deeper history we can't reach is unverifiable → fail closed.
+  const reviews: Review[] = [];
+  const MAX_PAGES = 20;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const r = await fetch(`https://api.github.com/${basePath}&page=${page}`, {
+      headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+    });
+    if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const batch = (await r.json()) as Review[];
+    reviews.push(...batch);
+    // A short page means we've read every review — the list is complete.
+    if (batch.length < 100) return pickLatestCopilotReviewBody(reviews, false);
+    // A full page on the last allowed page is only truncated if GitHub says there's more; trust the
+    // `Link` header's `rel="next"` so an exact multiple of 100 isn't a false positive.
+    if (page === MAX_PAGES && /<[^>]*>;\s*rel="next"/.test(r.headers.get("link") ?? "")) {
+      return pickLatestCopilotReviewBody(reviews, true);
+    }
+  }
+  return pickLatestCopilotReviewBody(reviews, false);
+}
+
+/** Raw GraphQL response shape for the review-threads query. */
+export interface ReviewThreadsResponse {
+  data?: {
+    repository?: {
+      pullRequest?: {
+        reviewThreads?: {
+          pageInfo?: { hasNextPage?: boolean; endCursor?: string | null };
+          nodes?: { isResolved?: boolean; path?: string | null; comments?: { nodes?: { body?: string }[] } }[];
+        };
+      };
+    };
+  };
+}
+
+/** One page of a review-threads GraphQL response, plus the cursor to advance to the next page. */
+export interface ReviewThreadsPage {
+  threads: ReviewThread[];
+  hasNextPage: boolean;
+  endCursor: string | null;
+}
+
+/** Map ONE page of a review-threads GraphQL response, FAILING CLOSED (returns `null`) on an
+ * UNVERIFIABLE read: a missing `reviewThreads` block (GraphQL errors, permission issues, a malformed
+ * payload) OR a page whose completeness signal (`pageInfo.hasNextPage`) is not a readable boolean.
+ * A readable page yields its mapped nodes plus `hasNextPage`/`endCursor` so the CALLER can page to
+ * completeness (`fetchReviewThreads` follows `endCursor` up to a bounded cap). A `first:100` page
+ * cannot see thread 101+, so a truncated read must be paged, not silently mapped to "no more
+ * threads" and converged (a fail-OPEN, the exact class this gate exists to prevent). Exceeding the
+ * caller's page cap while GitHub still reports more is the caller's fail-closed decision, not this
+ * mapper's. Pure; unit-tested. */
+export function parseReviewThreadsPage(payload: ReviewThreadsResponse): ReviewThreadsPage | null {
+  const block = payload.data?.repository?.pullRequest?.reviewThreads;
+  if (!block || typeof block.pageInfo?.hasNextPage !== "boolean") return null;
+  const nodes = block.nodes ?? [];
+  return {
+    threads: nodes.map((t) => ({
+      isResolved: !!t.isResolved,
+      path: t.path ?? null,
+      bodies: (t.comments?.nodes ?? []).map((c) => c.body ?? ""),
+    })),
+    hasNextPage: block.pageInfo.hasNextPage,
+    endCursor: block.pageInfo.endCursor ?? null,
+  };
+}
+
+/** 20×100 review threads is far past any real convergence loop; a genuinely deeper set we can't
+ * page to is unverifiable → fail closed. */
+const MAX_THREAD_PAGES = 20;
+
+/** Fetch ALL of a PR's review threads (resolution state + path + comment bodies) via GraphQL, paging
+ * to completeness up to `MAX_THREAD_PAGES`. `null` when no transport is usable, a page is
+ * unreadable, or the set is still truncated past the page cap (fail closed); throws on a genuine
+ * transport failure. */
+export async function fetchReviewThreads(
+  repo: string,
+  number: number | string,
+  token: string,
+): Promise<ReviewThread[] | null> {
+  const [owner, name] = repo.split("/");
+  const query =
+    "query($o:String!,$r:String!,$n:Int!,$after:String){repository(owner:$o,name:$r){pullRequest(number:$n){" +
+    "reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor}nodes{isResolved path comments(first:100){nodes{body}}}}}}}";
+  const mode = githubTransport();
+  const useGh = mode === "gh" || (mode === "auto" && (await isGhAvailable()));
+  if (!useGh && !token) return null;
+
+  const fetchPage = async (after: string | null): Promise<ReviewThreadsResponse> => {
+    if (useGh) {
+      const args = ["api", "graphql", "-f", `query=${query}`, "-F", `o=${owner}`, "-F", `r=${name}`, "-F", `n=${number}`];
+      if (after !== null) args.push("-F", `after=${after}`);
+      const out = await runGh(args);
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      return JSON.parse(out) as ReviewThreadsResponse;
+    }
+    const variables: Record<string, unknown> = { o: owner, r: name, n: Number(number) };
+    if (after !== null) variables.after = after;
+    const r = await fetch("https://api.github.com/graphql", {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify({ query, variables }),
+    });
+    if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    return (await r.json()) as ReviewThreadsResponse;
+  };
+
+  const all: ReviewThread[] = [];
+  let after: string | null = null;
+  for (let page = 1; page <= MAX_THREAD_PAGES; page++) {
+    const parsed = parseReviewThreadsPage(await fetchPage(after));
+    // An unreadable page is unverifiable — fail closed rather than converging on a partial read.
+    if (parsed === null) return null;
+    all.push(...parsed.threads);
+    // A confirmed last page is the only complete read.
+    if (!parsed.hasNextPage) return all;
+    // More pages exist but no cursor to advance — unverifiable, fail closed.
+    if (parsed.endCursor === null) return null;
+    after = parsed.endCursor;
+  }
+  // Exceeded the page cap and GitHub still reports more — unverifiable, fail closed.
+  return null;
+}
+
 // ── Copilot re-request (review-wait liveness) ───────────────────────────────
 // A PR parked in `waiting_review` blocks on a *fresh* Copilot review. Copilot won't
 // spontaneously re-review a round with no new commit, and routinely dismisses a re-request, so

package/app/roundProgress.test.ts

@@ -0,0 +1,229 @@
+// No-progress guard — unit tests for the canonical router (app/roundProgress.ts), the
+// pr.progress-check worker, and a structural guard over the committed convergence-loop BPMN.
+//
+// The convergence loop used to trust the agent's self-reported `addressed` status to trigger the
+// next Copilot review round. An agent could return `addressed` (or fall back to the safe default)
+// WITHOUT pushing a commit, so Copilot re-reviewed byte-identical code and the loop burned rounds
+// making no progress until the round cap escalated. The fix inserts a deterministic
+// `pr.progress-check` step that compares the PR head SHA across rounds and routes an `addressed`
+// round whose head did not advance to the human `wait-answer` escalation instead of another review.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
+import { routeProgress } from "./roundProgress.ts";
+
+// ── The canonical router ────────────────────────────────────────────────────
+
+test("routeProgress: an addressed round whose head did not advance escalates", () => {
+  assertEquals(routeProgress("addressed", "sha-1", "sha-1"), "escalate");
+});
+
+test("routeProgress: an addressed round whose head advanced continues", () => {
+  assertEquals(routeProgress("addressed", "sha-1", "sha-2"), "continue");
+});
+
+test("routeProgress: an explicit non-addressed round always continues (no push is expected)", () => {
+  // These are the statuses gw-status routes AWAY from the addressed/default arm — a legit no-push
+  // round. They always continue regardless of the head.
+  for (const status of ["waiting", "converged", "needs_input", "blocked"]) {
+    assertEquals(
+      routeProgress(status, "sha-1", "sha-1"),
+      "continue",
+      `status ${JSON.stringify(status)} must continue even with an unchanged head`,
+    );
+  }
+});
+
+test("routeProgress: blank/unknown status behaves like addressed (the safe-default trap)", () => {
+  // gw-status defaults blank/unknown/unrecognized status down the addressed arm and pr.persist-round
+  // records a missing status as `addressed`, so the no-progress guard must apply to them too: an
+  // unchanged head escalates, an advanced head continues.
+  for (const status of [undefined, null, "", "x"]) {
+    assertEquals(
+      routeProgress(status, "sha-1", "sha-1"),
+      "escalate",
+      `blank/unknown status ${JSON.stringify(status)} with an unchanged head must escalate like addressed`,
+    );
+    assertEquals(
+      routeProgress(status, "sha-1", "sha-2"),
+      "continue",
+      `blank/unknown status ${JSON.stringify(status)} with an advanced head must continue`,
+    );
+  }
+});
+
+test("routeProgress: fails OPEN when either head is unknown (no baseline / unreadable head)", () => {
+  for (const [prev, cur] of [
+    [null, "sha-1"],
+    [undefined, "sha-1"],
+    ["sha-1", null],
+    ["sha-1", undefined],
+    [null, null],
+  ] as const) {
+    assertEquals(
+      routeProgress("addressed", prev, cur),
+      "continue",
+      `unknown head (${JSON.stringify(prev)} -> ${JSON.stringify(cur)}) must fail open`,
+    );
+  }
+});
+
+// ── The worker (with an injected head reader — never touches git/network) ────
+
+function fakeApp(row?: { last_round_head: string | null }) {
+  const updates: { key: string; patch: Record<string, unknown> }[] = [];
+  const store = new Map<string, unknown>();
+  if (row) store.set("o/r#1", { pr_key: "o/r#1", ...row });
+  const app = {
+    data: {
+      table(_name: string, _key: string) {
+        return {
+          async get(key: string) {
+            return store.get(key);
+          },
+          async update(key: string, patch: Record<string, unknown>) {
+            updates.push({ key, patch });
+          },
+        };
+      },
+    },
+  };
+  return { app, updates };
+}
+
+async function makeUnderTest(readHead: (repo: string, n: number) => Promise<string | null>) {
+  const { makeHandler } = await import("../workers/progress-check/worker.ts");
+  return makeHandler({ readHead });
+}
+
+test("progress-check: skips the head read entirely for a non-addressed round", async () => {
+  let called = false;
+  const handler = await makeUnderTest(async () => {
+    called = true;
+    return "sha-2";
+  });
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ variables: { prKey: "o/r#1", status: "waiting", repo: "o/r", prNumber: 1 } } as any, app as any);
+  assertEquals(out, { progressed: true });
+  assertEquals(called, false, "a waiting round never reads the head");
+  assertEquals(updates.length, 0, "and never rewrites the baseline");
+});
+
+test("progress-check: a blank/unknown status is treated as addressed — reads the head and can report no progress", async () => {
+  let called = false;
+  const handler = await makeUnderTest(async () => {
+    called = true;
+    return "sha-1";
+  });
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ variables: { prKey: "o/r#1", status: "", repo: "o/r", prNumber: 1 } } as any, app as any);
+  assertEquals(out, { progressed: false }, "a blank-status no-progress round is caught, not waved through");
+  assertEquals(called, true, "a blank status (the safe-default addressed trap) still reads the head");
+});
+
+test("progress-check: an addressed round whose head is unchanged reports progressed:false", async () => {
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
+  assertEquals(out, { progressed: false });
+});
+
+test("progress-check: an addressed round whose head advanced reports progressed:true and rebaselines", async () => {
+  const handler = await makeUnderTest(async () => "sha-2");
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
+  assertEquals(out, { progressed: true });
+  assertEquals(updates.length, 1, "the observed head is recorded as the new baseline");
+  assertEquals(updates[0]!.patch.last_round_head, "sha-2");
+});
+
+test("progress-check: the first observed round (no baseline) continues and records the baseline", async () => {
+  const handler = await makeUnderTest(async () => "sha-1");
+  const { app, updates } = fakeApp(); // no row yet -> previousHead null
+  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
+  assertEquals(out, { progressed: true }, "no baseline yet fails open");
+  assertEquals(updates[0]!.patch.last_round_head, "sha-1");
+});
+
+test("progress-check: an unreadable head fails open and does not clobber the baseline", async () => {
+  const handler = await makeUnderTest(async () => null);
+  const { app, updates } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler({ variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1 } } as any, app as any);
+  assertEquals(out, { progressed: true }, "a null head fails open");
+  assertEquals(updates.length, 0, "a null head never overwrites the good baseline");
+});
+
+test("progress-check: resolves repo/prNumber from the prKey when the vars are absent", async () => {
+  let seen: [string, number] | null = null;
+  const handler = await makeUnderTest(async (repo, n) => {
+    seen = [repo, n];
+    return "sha-2";
+  });
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  await handler({ variables: { prKey: "o/r#1", status: "addressed" } } as any, app as any);
+  assertEquals(seen, ["o/r", 1], "falls back to parsing owner/repo#N from the prKey");
+});
+
+// ── 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("persist-round routes through check-progress before the review wait", () => {
+  const f = flowElement("f_roundWait");
+  assert(f, "f_roundWait flow missing");
+  assertStringIncludes(f, 'sourceRef="persist-round"');
+  assertStringIncludes(f, 'targetRef="check-progress"');
+});
+
+test("check-progress feeds the gw-progress gateway", () => {
+  const f = flowElement("f_checkGate");
+  assert(f, "f_checkGate flow missing");
+  assertStringIncludes(f, 'sourceRef="check-progress"');
+  assertStringIncludes(f, 'targetRef="gw-progress"');
+  // The task runs the deterministic no-progress guard job.
+  assertStringIncludes(flat, 'type="pr.progress-check"');
+});
+
+test("gw-progress escalates a no-progress round on an explicit progressed = false condition", () => {
+  const f = flowElement("f_noProgress");
+  assert(f, "f_noProgress flow missing");
+  assertStringIncludes(f, 'targetRef="persist-escalation-noprogress"');
+  assertStringIncludes(f, "progressed = false");
+});
+
+test("gw-progress default arm re-enters the review wait with no condition", () => {
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-progress"[^>]*>/);
+  assert(gw, "gw-progress gateway missing");
+  assertStringIncludes(gw[0], 'default="f_progressOk"');
+  const ok = flowElement("f_progressOk");
+  assert(ok, "f_progressOk flow missing");
+  assertStringIncludes(ok, 'targetRef="gw-review-wait"');
+  assert(!/conditionExpression/.test(ok), "the default arm must carry no conditionExpression");
+});
+
+test("the no-progress escalation lands on the human wait-answer task", () => {
+  const f = flowElement("f_noprogressWait");
+  assert(f, "f_noprogressWait flow missing");
+  assertStringIncludes(f, 'sourceRef="persist-escalation-noprogress"');
+  assertStringIncludes(f, 'targetRef="wait-answer"');
+  // It opens a real, answerable escalation (blocked status + a concrete question) so it is never a
+  // blank-question non-escalation that would wedge the token on the wait.
+  const task = flat.match(
+    /<bpmn:serviceTask\b[^>]*\bid="persist-escalation-noprogress"[^>]*>.*?<\/bpmn:serviceTask>/,
+  );
+  assert(task, "persist-escalation-noprogress task missing");
+  assertStringIncludes(task[0], 'type="pr.persist-escalation"');
+  assertStringIncludes(task[0], 'target="status"');
+  assertStringIncludes(task[0], 'target="question"');
+  // It must NOT double-record the round persist-round already recorded.
+  assertStringIncludes(task[0], 'target="recordRound"');
+});

package/app/roundProgress.ts

@@ -0,0 +1,70 @@
+// No-progress guard routing — the canonical, testable mirror of the convergence-loop
+// `gw-progress` exclusive gateway (see resources/processes/convergence-loop.bpmn and the
+// structural guard in roundProgress.test.ts).
+//
+// The convergence loop trusts the agent's self-reported `addressed` status to trigger the next
+// Copilot review round. But an agent can return `addressed` (or fall back to the safe `addressed`
+// default) WITHOUT actually pushing a commit — nothing landed on the PR head. Copilot then
+// re-reviews byte-identical code, produces the same comments, and the loop burns rounds making no
+// progress until the round cap escalates. That is the trap.
+//
+// So a deterministic step (`pr.progress-check`, workers/progress-check/worker.ts) reads the PR's
+// head SHA and compares it to the head observed at the previous round. When an `addressed` round's
+// head did NOT advance, the process must NOT request another review round — it escalates to the
+// human `wait-answer` task instead. This module is the single source of truth for that decision so
+// the worker and the BPMN gateway can never drift apart.
+
+/** Where a recorded round routes after the progress check:
+ *  • `continue`  — request another review round (the head advanced, or the round carried an
+ *                  explicit non-addressed status — e.g. `waiting` — that claims no push, or the
+ *                  head could not be read so we fail OPEN rather than fabricate a no-progress
+ *                  escalation).
+ *  • `escalate`  — an `addressed` round whose PR head did not move: no commit was really pushed,
+ *                  so re-review would loop. Escalate to a human instead of looping. */
+export type ProgressRouting = "continue" | "escalate";
+
+// The statuses that route AWAY from gw-status's `addressed`/default arm (see the explicit
+// conditions on f_converged/f_waiting/f_escalate in convergence-loop.bpmn). A round carrying one of
+// these legitimately claims no push and must always continue past the no-progress guard.
+//
+// Everything else — an explicit `addressed`, a blank/unknown/empty status, or any unrecognized
+// string — takes gw-status's `addressed`/default arm, and pr.persist-round records a missing status
+// as `addressed` too. That safe-default `addressed` round is EXACTLY the no-progress trap this guard
+// exists for, so blank/unknown status must be treated as `addressed` here (subject to the head
+// comparison), never waved through. Matching is exact (no trim) to mirror gw-status's `=status =
+// "waiting"` equality: a padded `" waiting "` matches no arm there, so it defaults to `addressed`
+// here as well.
+const NON_ADDRESSED_STATUSES: ReadonlySet<string> = new Set([
+  "waiting",
+  "converged",
+  "needs_input",
+  "blocked",
+]);
+
+/** True when a round's status is `addressed` for no-progress purposes — i.e. NOT one of the
+ * explicitly recognized non-addressed statuses. Blank/unknown/empty status is `addressed` here,
+ * mirroring gw-status's default arm and pr.persist-round's missing-status default. The single
+ * source of truth for both {@link routeProgress} and the pr.progress-check worker's early skip. */
+export function isAddressedStatus(status: string | null | undefined): boolean {
+  return !NON_ADDRESSED_STATUSES.has(status ?? "");
+}
+
+/** Decide whether a recorded round made real progress, exactly as `gw-progress` does.
+ *
+ * Only an `addressed` round claims the agent pushed changes, so only it can be a no-progress
+ * round — and blank/unknown status counts as `addressed` (see {@link isAddressedStatus}): it is the
+ * safe-default round this guard exists to catch. An explicitly recognized non-addressed status
+ * (`waiting` on round 1, awaiting the first review, etc.) legitimately has no push and must always
+ * continue. The check FAILS OPEN: when either head SHA is unknown — no GitHub transport, a transient
+ * read error, or no baseline recorded yet (the first observed round) — we never fabricate a
+ * no-progress escalation; we continue and let the round cap / review-wait timeout remain the safety
+ * nets. */
+export function routeProgress(
+  status: string | null | undefined,
+  previousHead: string | null | undefined,
+  currentHead: string | null | undefined,
+): ProgressRouting {
+  if (!isAddressedStatus(status)) return "continue";
+  if (!previousHead || !currentHead) return "continue";
+  return currentHead === previousHead ? "escalate" : "continue";
+}

package/app/service.test.ts

@@ -7,7 +7,7 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { pollIncidentsImpl, repoEnvelopeVars, submitPr } from "./service.ts";
+import { parsePr, pollIncidentsImpl, repoEnvelopeVars, submitPr } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -382,3 +382,20 @@ test("repoEnvelopeVars emits nothing for a malformed repo (not owner/repo)", ()
     );
   }
 });
+
+// `parsePr` is total on any input: it is called unguarded from several workers (progress-check,
+// persist-round, persist-escalation, record-dependency) with a process variable that a regression
+// — or an older in-flight instance — could carry as a non-string. `.trim()` on a non-string throws,
+// which would turn a should-fail-open caller into a retrying job. A non-string must resolve to
+// `null` (fail closed) so every caller's fail-open path runs instead of the handler crashing.
+test("parsePr fails closed to null on a non-string input (no throw)", () => {
+  for (const bad of [undefined, null, 123, {}, [], true] as unknown[]) {
+    assertEquals(parsePr(bad as any), null, `expected null for ${JSON.stringify(bad)}`);
+  }
+});
+
+test("parsePr still resolves a well-formed prKey and PR URL", () => {
+  assertEquals(parsePr("owner/repo#42")?.prKey, "owner/repo#42");
+  assertEquals(parsePr("  owner/repo#42  ")?.number, 42);
+  assertEquals(parsePr("https://github.com/owner/repo/pull/7")?.repo, "owner/repo");
+});

package/app/service.ts

@@ -9,6 +9,7 @@
 // `Table<T>` surface), not hand-written SQL. Row shapes are declared inline here.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
+import { agentSlaTimeout } from "./agentSla.ts";
 import { deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureRun, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
@@ -58,6 +59,14 @@ export const MAX_CI_FIX_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_CI_FIX
  * immediately). Reuses the CI-fix budget clamp (allows 0 = disable, ceiling-capped). */
 export const MAX_REBASE_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_REBASE_ROUNDS, 3);
 
+/** How long a merge-loop AGENT service task (rebase / fix-ci) may sit without completing before its
+ * interrupting timer boundary fires and the PR escalates for human attention. Seeded as the
+ * `agentSlaTimeout` process variable at merge start and evaluated by those tasks' boundary timers.
+ * Unlike a human-decision escalation (PT24H), an agent task has no human in the loop — if its
+ * capability is unstaffed or the agent hangs/crashes without failing the job, the token would
+ * otherwise park forever. Override with `NANO_PR_AGENT_SLA_TIMEOUT` (ISO-8601 duration). */
+export const AGENT_SLA_TIMEOUT = agentSlaTimeout(process.env.NANO_PR_AGENT_SLA_TIMEOUT);
+
 /** How long the convergence loop waits for a fresh review before escalating to a human. Seeded as
  * the `reviewWaitTimeout` process variable at submit and evaluated by the process's
  * `wait-review-timeout` timer catch (the timer arm of the event-based-gateway race against
@@ -295,7 +304,11 @@ export async function ensurePr(
 }
 
 /** Parse "owner/repo#123" or a canonical PR URL into its parts. */
-export function parsePr(input: string): ParsedPr | null {
+export function parsePr(input: unknown): ParsedPr | null {
+  // Total on any input: a process-variable regression (or an older in-flight instance) can carry a
+  // non-string prKey, and `.trim()` on a non-string throws — turning a should-fail-open caller into
+  // a retrying job. Fail closed to `null` here so every caller resolves safely instead of throwing.
+  if (typeof input !== "string") return null;
   const s = input.trim();
   let m = s.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/i);
   if (m) {
@@ -527,6 +540,7 @@ export async function startMerge(
       ciFixMax: MAX_CI_FIX_ROUNDS,
       rebaseRound: 0,
       rebaseMax: MAX_REBASE_ROUNDS,
+      agentSlaTimeout: AGENT_SLA_TIMEOUT,
       abandonUrl: abUrl,
       abandonBrief: renderAbandonBrief(abUrl),
       // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the

package/db/migrations/033_pr_round_head.sql

@@ -0,0 +1,16 @@
+-- Track the PR head SHA observed at each recorded convergence round so the loop can detect a
+-- NO-PROGRESS `addressed` round: the agent reported it addressed the review comments, but the
+-- branch head never moved — no commit was actually pushed. Requesting another Copilot review then
+-- loops on byte-identical code (same comments, round after round) until the round cap escalates.
+--
+-- The deterministic `pr.progress-check` guard (workers/progress-check/worker.ts) reads the PR's
+-- current head SHA each continue-round, compares it to this column (the head at the PREVIOUS
+-- round), and — when an `addressed` round's head did not advance — routes the convergence-loop
+-- `gw-progress` gateway to the human `wait-answer` escalation instead of soliciting another
+-- review. It then writes the freshly observed head here as the baseline for the next round. NULL
+-- until the first round observes a head; the guard fails OPEN on a NULL/unreadable head.
+--
+-- Forward-only, additive (expand): the column is nullable with no default. Numbered after the
+-- current highest prefix (032); the runner wraps each file in its own transaction, so this file
+-- must NOT contain BEGIN/COMMIT.
+ALTER TABLE pull_requests ADD COLUMN last_round_head TEXT;

package/nano.app.json

@@ -164,6 +164,14 @@
     {
       "taskType": "pr.retro-record",
       "handler": "workers/retro-record/worker.ts"
+    },
+    {
+      "taskType": "pr.progress-check",
+      "handler": "workers/progress-check/worker.ts"
+    },
+    {
+      "taskType": "pr.converge-gate",
+      "handler": "workers/converge-gate/worker.ts"
     }
   ],
   "externalTaskTypes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.70.0",
+  "version": "0.70.2",
   "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",