@nanobpm/nano-workforce 0.187.6 → 0.188.0

package/app/convergeGate.test.ts

@@ -15,6 +15,7 @@ import { assert, assertEquals, assertNotEquals, assertStringIncludes } from "#te
 import { evaluateConvergeGate } from "./convergeGate.ts";
 import {
   advisoryStableKey,
+  isAckThread,
   parseAckedAdvisories,
   parseReviewThreadsPage,
   parseSuppressedAdvisories,
@@ -29,12 +30,15 @@ test("evaluateConvergeGate: a clean PR (no unresolved threads, no advisories) co
   const r = evaluateConvergeGate({ unresolvedThreadCount: 0, suppressedAdvisories: [], acknowledgedKeys: [] });
   assertEquals(r.convergeBlocked, false);
   assertEquals(r.convergeBlockReason, "");
+  assertEquals(r.ackOnly, false);
 });
 
 test("evaluateConvergeGate: an unresolved review thread blocks convergence", () => {
   const r = evaluateConvergeGate({ unresolvedThreadCount: 2, suppressedAdvisories: [], acknowledgedKeys: [] });
   assertEquals(r.convergeBlocked, true);
   assertStringIncludes(r.convergeBlockReason, "2 unresolved review threads");
+  // An unresolved inline thread needs the round agent's code/reply work — NOT ack-only (#796).
+  assertEquals(r.ackOnly, false);
 });
 
 test("evaluateConvergeGate: an unacknowledged suppressed advisory blocks convergence", () => {
@@ -47,6 +51,8 @@ test("evaluateConvergeGate: an unacknowledged suppressed advisory blocks converg
   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 (");
+  // Blocked SOLELY on an unacked advisory → the recoverable, bounded-auto-ack case (#796).
+  assertEquals(r.ackOnly, true);
 });
 
 test("evaluateConvergeGate: an ACKNOWLEDGED suppressed advisory no longer blocks convergence", () => {
@@ -99,6 +105,9 @@ test("evaluateConvergeGate: reports both a thread and an advisory when both are
   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");
+  // A mix of an unresolved thread AND an unacked advisory is NOT ack-only — the thread still needs
+  // the round agent's code/reply work, so it escalates to a human as before (#796).
+  assertEquals(r.ackOnly, false);
 });
 
 // ── The parsers (app/github.ts) ─────────────────────────────────────────────
@@ -139,6 +148,122 @@ test("parseSuppressedAdvisories: returns [] when there is no suppressed block",
   assertEquals(parseSuppressedAdvisories(undefined), []);
 });
 
+// An UNRESOLVED ack thread (one the round agent posted but has not resolved yet) must NOT count as
+// an unresolved *review* thread: it is a partially-completed acknowledgement the bounded #796
+// auto-ack retry can finish, so counting it would flip an otherwise ack-only block off the
+// recoverable path and escalate to a human despite there being no substantive open code-review
+// thread. `isAckThread` is the single source of truth the converge-gate worker filters on.
+test("isAckThread: a thread carrying a nano-ack marker is an ack thread (resolved or not)", () => {
+  assert(
+    isAckThread({
+      isResolved: false,
+      path: "a.ts",
+      bodies: ["Applied. nano-ack: app/x.ts :: Guard the empty input."],
+    }),
+  );
+  assert(
+    isAckThread({ isResolved: true, path: "a.ts", bodies: ["Declined. nano-ack: app/x.ts :: Narrow this type."] }),
+  );
+});
+
+test("isAckThread: a substantive review thread (no nano-ack marker) is NOT an ack thread", () => {
+  assertEquals(isAckThread({ isResolved: false, path: "a.ts", bodies: ["This can NPE on empty input."] }), false);
+  assertEquals(isAckThread({ isResolved: false, path: "a.ts", bodies: [] }), false);
+});
+
+// FAIL-CLOSED guard #1 — the retired bare `nano-ack: <path>:<line>` form is prose-blind and NOT
+// honoured by `parseAckedAdvisories`; classifying it as an ack thread would drop a genuine unresolved
+// thread from the count and let the gate finalize with it still open. It must stay counted.
+test("isAckThread: a bare `<path>:<line>` marker is NOT a dedicated ack thread (stays counted)", () => {
+  assertEquals(
+    isAckThread({ isResolved: false, path: "a.ts", bodies: ["Applied. nano-ack: app/x.ts:12"] }),
+    false,
+  );
+});
+
+// FAIL-CLOSED guard #2 — a substantive reviewer thread whose ROOT is the finding, with a later reply
+// merely QUOTING a canonical marker, must NOT be classified as an ack thread. Only the thread root is
+// inspected, and the root here carries no marker, so the substantive thread stays counted.
+test("isAckThread: a substantive thread that only quotes nano-ack in a reply is NOT an ack thread", () => {
+  assertEquals(
+    isAckThread({
+      isResolved: false,
+      path: "a.ts",
+      bodies: [
+        "This can NPE on empty input.",
+        "Re: your `nano-ack: app/x.ts :: Guard the empty input.` — that is unrelated to this finding.",
+      ],
+    }),
+    false,
+  );
+});
+
+// Mirrors the converge-gate worker's split: an unresolved ack thread is classified separately (it
+// still BLOCKS but stays ack-only/recoverable), while a substantive unresolved thread escalates.
+test("converge gate: an unresolved ack thread does not count as a SUBSTANTIVE thread (stays ack-only)", () => {
+  const threads: ReviewThread[] = [
+    { isResolved: false, path: "a.ts", bodies: ["Applied. nano-ack: app/x.ts :: Guard the empty input."] },
+    { isResolved: true, path: "b.ts", bodies: ["already fixed"] },
+  ];
+  const unresolved = threads.filter((t) => !t.isResolved);
+  const unresolvedAckThreadCount = unresolved.filter((t) => isAckThread(t)).length;
+  const unresolvedThreadCount = unresolved.length - unresolvedAckThreadCount;
+  assertEquals(unresolvedThreadCount, 0);
+  assertEquals(unresolvedAckThreadCount, 1);
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount,
+    unresolvedAckThreadCount,
+    suppressedAdvisories: [{ key: "app/x.ts#deadbeef", label: "app/x.ts:12" }],
+    acknowledgedKeys: [],
+  });
+  assertEquals(r.convergeBlocked, true);
+  assertEquals(r.ackOnly, true);
+});
+
+// FAIL-CLOSED regression (thread 2): an unresolved ack thread with NO outstanding advisory must NOT
+// finalize the gate — dropping it entirely (the old `!isAckThread` filter) let the process converge
+// with a genuinely-open GitHub thread. It now BLOCKS, classified ack-only (recoverable).
+test("converge gate: a lone unresolved ack thread (no advisory) BLOCKS, ack-only (no fail-open finalize)", () => {
+  const threads: ReviewThread[] = [
+    { isResolved: false, path: "a.ts", bodies: ["Applied. nano-ack: app/x.ts :: Guard the empty input."] },
+  ];
+  const unresolved = threads.filter((t) => !t.isResolved);
+  const unresolvedAckThreadCount = unresolved.filter((t) => isAckThread(t)).length;
+  const unresolvedThreadCount = unresolved.length - unresolvedAckThreadCount;
+  assertEquals(unresolvedThreadCount, 0);
+  assertEquals(unresolvedAckThreadCount, 1);
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount,
+    unresolvedAckThreadCount,
+    suppressedAdvisories: [],
+    acknowledgedKeys: [],
+  });
+  assertEquals(r.convergeBlocked, true);
+  assertEquals(r.ackOnly, true);
+  assertStringIncludes(r.convergeBlockReason, "unresolved acknowledgement thread");
+});
+
+// A genuine reviewer thread left open still blocks off the ack-only path (fail-closed intact).
+test("converge gate: a substantive unresolved thread still counts (not ack-only)", () => {
+  const threads: ReviewThread[] = [
+    { isResolved: false, path: "a.ts", bodies: ["This can NPE on empty input."] },
+    { isResolved: false, path: "b.ts", bodies: ["Applied. nano-ack: app/x.ts :: Guard the empty input."] },
+  ];
+  const unresolved = threads.filter((t) => !t.isResolved);
+  const unresolvedAckThreadCount = unresolved.filter((t) => isAckThread(t)).length;
+  const unresolvedThreadCount = unresolved.length - unresolvedAckThreadCount;
+  assertEquals(unresolvedThreadCount, 1);
+  assertEquals(unresolvedAckThreadCount, 1);
+  const r = evaluateConvergeGate({
+    unresolvedThreadCount,
+    unresolvedAckThreadCount,
+    suppressedAdvisories: [{ key: "app/x.ts#deadbeef", label: "app/x.ts:12" }],
+    acknowledgedKeys: [],
+  });
+  assertEquals(r.convergeBlocked, true);
+  assertEquals(r.ackOnly, false);
+});
+
 test("parseAckedAdvisories: only RESOLVED threads carrying a nano-ack marker count", () => {
   const threads: ReviewThread[] = [
     {
@@ -498,7 +623,7 @@ test("converge-gate: a clean PR is allowed to converge", async () => {
     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: "", reviewStale: false });
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: false });
 });
 
 test("converge-gate: an unresolved thread blocks convergence", async () => {
@@ -509,6 +634,7 @@ test("converge-gate: an unresolved thread blocks convergence", 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");
+  assertEquals(out.convergeAckOnly, false);
 });
 
 test("converge-gate: an unacknowledged suppressed advisory blocks convergence", async () => {
@@ -519,6 +645,8 @@ test("converge-gate: an unacknowledged suppressed advisory blocks convergence",
   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");
+  // Blocked SOLELY on unacked advisories → ack-only, so the loop auto-acks before a human (#796).
+  assertEquals(out.convergeAckOnly, true);
 });
 
 test("converge-gate: an acknowledged advisory (resolved ack thread) is allowed", async () => {
@@ -540,7 +668,56 @@ test("converge-gate: an acknowledged advisory (resolved ack thread) is allowed",
     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: "", reviewStale: false });
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: false });
+});
+
+// WIRING regression guard (through makeHandler, not a local re-implementation of the filter): an
+// UNRESOLVED ack thread is classified separately (ack-only), so a block whose only substantive cause
+// is unacked advisories stays ack-only. If the worker regressed to counting an unresolved ack thread
+// as a SUBSTANTIVE thread, convergeAckOnly would flip to false and this handler-level test would fail.
+test("converge-gate: an unresolved ack thread is classified ack-only, not substantive (through the handler)", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [
+      // A partially-completed acknowledgement (posted, not yet resolved) — its root carries the
+      // canonical marker, so isAckThread classifies it as an (unresolved) ack thread, not substantive.
+      {
+        isResolved: false,
+        path: "spec-app/nano-app.schema.json",
+        bodies: [
+          "Applied. nano-ack: spec-app/nano-app.schema.json :: The description could be clearer about the loopback default.",
+        ],
+      },
+    ],
+    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);
+  // No SUBSTANTIVE unresolved thread was counted → the block is ack-only (recoverable).
+  assertEquals(out.convergeAckOnly, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "unacknowledged suppressed");
+});
+
+// FAIL-CLOSED wiring guard (thread 2, through the handler): a lone UNRESOLVED ack thread with NO
+// outstanding advisory must NOT let the gate finalize. The old `!isAckThread` filter dropped it
+// entirely (unresolvedThreadCount = 0, no advisory) → convergeBlocked = false → the process could
+// converge with a genuinely-open GitHub thread. It must now BLOCK (ack-only, recoverable).
+test("converge-gate: a lone unresolved ack thread (no advisory) BLOCKS, ack-only — no fail-open finalize (through the handler)", async () => {
+  const handler = await makeUnderTest({
+    readThreads: async () => [
+      {
+        isResolved: false,
+        path: "spec-app/nano-app.schema.json",
+        bodies: [
+          "Applied. nano-ack: spec-app/nano-app.schema.json :: The description could be clearer about the loopback default.",
+        ],
+      },
+    ],
+    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, true);
+  assertEquals(out.convergeAckOnly, true);
+  assertStringIncludes(out.convergeBlockReason ?? "", "unresolved acknowledgement thread");
 });
 
 test("converge-gate: FAILS CLOSED when the threads read returns null (no transport)", async () => {
@@ -551,6 +728,8 @@ test("converge-gate: FAILS CLOSED when the threads read returns null (no transpo
   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");
+  // An unverifiable block is NOT ack-only — it must go to a human, never the auto-ack path (#796).
+  assertEquals(out.convergeAckOnly, false);
 });
 
 test("converge-gate: FAILS CLOSED when the review-body read returns null (no transport)", async () => {
@@ -596,7 +775,7 @@ test("converge-gate: a non-string prKey does not throw — resolves from repo/pr
     readReviewBody: async () => "",
   });
   const out = await handler({ variables: { repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", reviewStale: false });
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: false });
 });
 
 test("converge-gate: FAILS CLOSED (no throw) when prKey is non-string and repo/prNumber are absent", async () => {
@@ -641,7 +820,7 @@ test("converge-gate #799: a STALE review (commit_id predates HEAD) does not bloc
     headSha: "newsha2222222222222222222222222222222222",
   });
   const out = await handler({ variables: { prKey: "o/r#1", repo: "o/r", prNumber: 1 } } as any, {} as any);
-  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", reviewStale: true });
+  assertEquals(out, { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: true });
 });
 
 test("converge-gate #799: a HEAD-CURRENT review still blocks on an unacked advisory (control)", async () => {
@@ -705,10 +884,62 @@ test("check-converge runs the deterministic converge-gate job and feeds gw-conve
 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"');
+  // A block now routes to the bounded auto-ack gateway first (#796), not straight to the human.
+  assertStringIncludes(f, 'targetRef="gw-ack-retry"');
   assertStringIncludes(f, "convergeBlocked = true");
 });
 
+// ── Bounded agent auto-ack before human escalation (#796) ────────────────────
+// A converge-gate block whose SOLE cause is unacked suppressed advisories is recoverable by
+// re-dispatching the review-round agent to post the missing acks. gw-ack-retry sends such an
+// ack-only block back into review-round (bounded by ackRetryMax), and only a non-ack-only block
+// (an unresolved inline thread) or an exhausted budget escalates to the human wait-answer.
+
+test("gw-ack-retry routes an ack-only block (within budget) back into the review-round agent", () => {
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-ack-retry"[^>]*>/);
+  assert(gw, "gw-ack-retry gateway missing");
+  assertStringIncludes(gw[0], 'default="f_ackEscalate"');
+  const retry = flowElement("f_ackRetry");
+  assert(retry, "f_ackRetry flow missing");
+  assertStringIncludes(retry, 'sourceRef="gw-ack-retry"');
+  // The re-entry rejoins the loop at `capture-head` (the loop head that captures the round-entry
+  // head, #786) which then flows straight into `review-round` — so the ack-only block re-dispatches
+  // the review-round agent, freshly baselined.
+  assertStringIncludes(retry, 'targetRef="capture-head"');
+  assertStringIncludes(retry, "convergeAckOnly = true");
+  // Bounded: re-dispatch only while the ack-retry budget is not exhausted.
+  assert(/ackRetryRound &lt;= ackRetryMax|ackRetryRound <= ackRetryMax/.test(retry), "f_ackRetry must be budget-bounded");
+});
+
+test("gw-ack-retry default arm escalates to the human (threads or exhausted budget)", () => {
+  const esc = flowElement("f_ackEscalate");
+  assert(esc, "f_ackEscalate flow missing");
+  assertStringIncludes(esc, 'sourceRef="gw-ack-retry"');
+  assertStringIncludes(esc, 'targetRef="persist-escalation-blockedcomments"');
+  assert(!/conditionExpression/.test(esc), "the escalate arm is the default — no conditionExpression");
+});
+
+test("capture-head accepts the ack-retry re-entry flow", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="capture-head"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "capture-head task missing");
+  assertStringIncludes(task[0], "<bpmn:incoming>f_ackRetry</bpmn:incoming>");
+});
+
+test("check-converge advances the ack-retry counter only on an ack-only block (bounded)", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="check-converge"[^>]*>.*?<\/bpmn:serviceTask>/);
+  assert(task, "check-converge task missing");
+  assertStringIncludes(
+    task[0],
+    "if convergeBlocked = true and convergeAckOnly = true then ackRetryRound + 1 else ackRetryRound",
+  );
+});
+
+test("PrConvergeGateOut carries the convergeAckOnly signal for the auto-ack router", () => {
+  const shape = flat.match(/<nano:shape\b[^>]*\bid="PrConvergeGateOut"[^>]*>.*?<\/nano:shape>/);
+  assert(shape, "PrConvergeGateOut envelope missing");
+  assertStringIncludes(shape[0], 'name="convergeAckOnly"');
+});
+
 test("gw-converge-gate routes a STALE review back to persist-round (re-solicit), not to escalation (#799)", () => {
   const f = flowElement("f_convergeStale");
   assert(f, "f_convergeStale flow missing");

package/app/convergeGate.ts

@@ -4,17 +4,35 @@
 // 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
+// while any of:
+//   • any SUBSTANTIVE review THREAD is still unresolved, or
+//   • any partially-completed `nano-ack:` ACK THREAD is still unresolved (blocks, but recoverable —
+//     see `unresolvedAckThreadCount`), or
 //   • any SUPPRESSED advisory (in the latest Copilot review body) lacks a matching
 //     RESOLVED ack thread (a thread carrying a line-stable `nano-ack: <path> :: <text>` marker; the
 //     bare `nano-ack: <path>:<line>` form is NOT honoured — its `path:line` key is prose-blind and
 //     would false-OPEN a new advisory re-emitted at a previously-acked line).
-// A blocked gate escalates to the human wait-answer task (recoverable), never a hard wedge.
+// A blocked gate is recoverable, never a hard wedge — but the route depends on WHY it blocked: an
+// ack-only block (sole cause unacked advisories and/or an unresolved `nano-ack:` thread) re-enters
+// the `review-round` agent first, bounded by `ackRetryMax`, and only escalates to the human
+// wait-answer task once that budget is exhausted; a substantive unresolved thread escalates to
+// wait-answer immediately.
 
 export interface ConvergeGateInput {
-  /** Count of review threads with `isResolved === false`. */
+  /** Count of unresolved review threads that are NOT `nano-ack:` ack threads (substantive reviewer
+   * findings). Any of these forces the block off the ack-only path — it needs the round agent's
+   * code/reply work, so it escalates to a human. */
   unresolvedThreadCount: number;
+  /** Count of unresolved threads the worker classified as `nano-ack:` ACK threads (partially-completed
+   * acknowledgements: posted but not yet resolved). These NEVER silently drop out of the gate — an
+   * unresolved ack thread is still a genuinely-open GitHub thread, so it BLOCKS convergence; but the
+   * block stays ack-only (recoverable by the bounded #796 auto-ack retry, which re-posts/resolves).
+   * Keeping this a blocking condition (rather than filtering the thread away) is what makes the
+   * `isAckThread` root-marker classifier FAIL-CLOSED: even if it mis-labels a substantive thread as
+   * an ack, that thread still BLOCKS (as ack-only) instead of finalizing with the finding open — and
+   * the bounded retry cannot ack a non-advisory, so it escalates to a human on exhaustion. Optional
+   * (defaults to 0) so the pure function stays total for callers that only track substantive threads. */
+  unresolvedAckThreadCount?: number;
   /** Copilot's suppressed advisories (latest review body), each with its line-stable key + label. */
   suppressedAdvisories: { key: string; label: string }[];
   /** Acknowledged line-stable keys (`<path>#<fp>`) from RESOLVED `nano-ack:` threads. An advisory is
@@ -25,6 +43,15 @@ export interface ConvergeGateInput {
 export interface ConvergeGateResult {
   convergeBlocked: boolean;
   convergeBlockReason: string;
+  /** True when the block is caused SOLELY by recoverable, agent-fixable state and no SUBSTANTIVE
+   * (non-ack) reviewer thread is open: unacknowledged suppressed advisories and/or a
+   * partially-completed (unresolved) `nano-ack:` ack thread. This is the case the loop can auto-ack:
+   * re-dispatching the review-round agent posts/resolves the missing ack threads and converges, so
+   * the process routes an ack-only block through a bounded agent auto-ack step BEFORE the human
+   * `wait-answer` (issue #796). A block that includes any unresolved SUBSTANTIVE inline thread (which
+   * needs the round agent's code/reply work) is NOT ack-only and escalates to a human as before.
+   * Always false when not blocked. */
+  ackOnly: boolean;
 }
 
 /** Decide whether a self-reported "converged" round may proceed to finalize. Pure; the worker
@@ -36,20 +63,29 @@ export function evaluateConvergeGate(input: ConvergeGateInput): ConvergeGateResu
   // NOT consulted: it would let a resolved ack for one advisory silently acknowledge a genuinely new
   // advisory re-emitted at the same line (a false-OPEN this gate exists to prevent).
   const unacked = input.suppressedAdvisories.filter((a) => !acked.has(a.key));
+  const unresolvedAck = input.unresolvedAckThreadCount ?? 0;
   const reasons: string[] = [];
   if (input.unresolvedThreadCount > 0) {
     const n = input.unresolvedThreadCount;
     reasons.push(`${n} unresolved review thread${n === 1 ? "" : "s"}`);
   }
+  if (unresolvedAck > 0) {
+    reasons.push(`${unresolvedAck} unresolved acknowledgement thread${unresolvedAck === 1 ? "" : "s"}`);
+  }
   if (unacked.length > 0) {
     const noun = unacked.length === 1 ? "advisory" : "advisories";
     reasons.push(`${unacked.length} unacknowledged suppressed ${noun} (${unacked.map((a) => a.label).join(", ")})`);
   }
   if (reasons.length === 0) {
-    return { convergeBlocked: false, convergeBlockReason: "" };
+    return { convergeBlocked: false, convergeBlockReason: "", ackOnly: false };
   }
   return {
     convergeBlocked: true,
     convergeBlockReason: `Convergence blocked: ${reasons.join("; ")}. Resolve every review thread and reply-and-resolve an ack thread (nano-ack: <path> :: <verbatim advisory text>) for each suppressed advisory before converging.`,
+    // Ack-only iff NO substantive (non-ack) reviewer thread is open — the only remaining causes are
+    // recoverable by re-dispatching the review-round agent (#796): unacked suppressed advisories
+    // and/or a partially-completed (unresolved) ack thread it can re-post and resolve. A substantive
+    // unresolved thread needs the round agent's code/reply work and escalates to a human.
+    ackOnly: input.unresolvedThreadCount === 0 && (unacked.length > 0 || unresolvedAck > 0),
   };
 }

package/app/github.ts

@@ -281,25 +281,59 @@ export function parseSuppressedAdvisories(reviewBody: string | null | undefined)
   return out;
 }
 
+/** The line-stable advisory keys carried by a SINGLE comment body's canonical `nano-ack: <path> ::
+ * <text>` markers. This is the SOLE recognizer of an acknowledgement, shared by `isAckThread` and
+ * `parseAckedAdvisories` so "is this an ack?" has ONE canonical implementation (derivation over
+ * duplication — no drift between the two consumers). The bare `nano-ack: <path>:<line>` form yields
+ * NOTHING here: `NEW_ACK` requires the ` :: <text>` prose (a bare `path:line` is prose-blind and
+ * would false-OPEN a new advisory re-emitted at a previously-acked line). */
+function canonicalAckKeys(body: string): string[] {
+  const keys: string[] = [];
+  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) {
+    const nw = NEW_ACK.exec(m[1].trim());
+    if (nw) keys.push(advisoryStableKey(nw[1], nw[2]));
+  }
+  return keys;
+}
+
+/** True when a review thread is a DEDICATED `nano-ack:` acknowledgement thread — one whose ROOT
+ * comment (`bodies[0]`, the thread-opening comment) carries a valid canonical `nano-ack: <path> ::
+ * <text>` marker — rather than a substantive code-review thread. This is a CLASSIFICATION only: the
+ * converge gate never DROPS an unresolved thread on the strength of this predicate. An unresolved ack
+ * thread still BLOCKS convergence (it is a genuinely-open GitHub thread); the classification only
+ * routes that block onto the recoverable ack-only path — a partially-completed acknowledgement the
+ * bounded #796 auto-ack retry can finish (post-and-resolve) — instead of escalating a human. A
+ * substantive unresolved thread escalates to a human.
+ *
+ * Because the gate BLOCKS either way, this predicate is FAIL-CLOSED even under a false positive:
+ *   1. Only the canonical prose-keyed form counts (via `canonicalAckKeys`); the retired bare
+ *      `nano-ack: <path>:<line>` form does NOT — matching `parseAckedAdvisories`.
+ *   2. Only the ROOT comment is inspected — a reviewer's substantive finding is ALWAYS its thread's
+ *      root and (canonical-form) never carries this marker, so a substantive thread that merely
+ *      quotes or replies `nano-ack:` in a later comment is not mis-classified.
+ *   3. Even if a root DID quote the canonical marker mid-prose and were mis-labelled an ack, the
+ *      thread is NOT excluded — it still blocks (as ack-only), and the bounded auto-ack retry cannot
+ *      ack a non-advisory, so it escalates to a human on exhaustion. Marker presence never finalizes
+ *      the gate with an open thread (the fail-OPEN this design forecloses). */
+export function isAckThread(thread: ReviewThread): boolean {
+  const root = thread.bodies[0];
+  return root !== undefined && canonicalAckKeys(root).length > 0;
+}
+
 /** Extract the acknowledged advisory keys from a set of review threads (only RESOLVED threads
  * count — an open ack thread is not yet an acknowledgement). Returns line-stable keys (`<path>#<fp>`)
- * parsed from the `nano-ack: <path> :: <text>` form ONLY. A bare `nano-ack: <path>:<line>` marker is
- * intentionally NOT honoured: its `path:line` key is blind to the advisory prose and would false-OPEN
- * a genuinely new advisory re-emitted at a previously-acked line. The gate treats an advisory as
- * acked iff its stable key appears here. */
+ * parsed from the `nano-ack: <path> :: <text>` form ONLY (via the shared `canonicalAckKeys`). A bare
+ * `nano-ack: <path>:<line>` marker is intentionally NOT honoured: its `path:line` key is blind to the
+ * advisory prose and would false-OPEN a genuinely new advisory re-emitted at a previously-acked line.
+ * The gate treats an advisory as acked iff its stable key appears here. */
 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) {
-        const nw = NEW_ACK.exec(m[1].trim());
-        if (nw) acked.add(advisoryStableKey(nw[1], nw[2]));
-      }
-    }
+    for (const body of t.bodies) for (const k of canonicalAckKeys(body)) acked.add(k);
   }
   return [...acked];
 }

package/app/service.test.ts

@@ -11,7 +11,7 @@ import { memDataFor } from "../test/worldDb.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import { DurableResumeRegistry } from "./durableResume.ts";
 import { WorldStore } from "./world/index.ts";
-import { abandonClosedPr, isPrSettled, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
+import { abandonClosedPr, isPrSettled, MAX_ACK_RETRIES, parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
 import { trackingTargetFor } from "./instanceTracking.ts";
 import type { DataLayer } from "@nanobpm/urban";
 
@@ -378,6 +378,45 @@ test("submitPr defaults convergeOnly to false so the global auto-merge default g
   });
 });
 
+// #796 auto-ack budget seeding: `submitPr` is the ONLY production write that makes the retry budget
+// available to a fresh convergence instance — the engine behaviour tests seed `ackRetryRound` /
+// `ackRetryMax` directly and never exercise `submitPr`, so a regression dropping or misconfiguring
+// this seed would leave deployed loops on the escalation default while every added behaviour test
+// still passes. Assert both the initial counter and the configured max propagate onto the instance.
+function captureVars() {
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" },
+    escalations: { rows: [], key: "id" },
+    pr_dependencies: { rows: [], key: "pr_key" },
+  };
+  const data = {
+    table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+  } as any;
+  let captured: Record<string, unknown> | undefined;
+  const engine = {
+    createInstance: (req: { variables?: Record<string, unknown> }) => {
+      captured = req.variables;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  } as any;
+  return { data, engine, get: () => captured };
+}
+
+test("submitPr seeds the #796 auto-ack budget onto the instance (ackRetryRound=0, ackRetryMax=MAX_ACK_RETRIES)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, get } = captureVars();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 10,
+      url: "https://github.com/owner/repo/pull/10",
+      prKey: "owner/repo#10",
+    });
+    const vars = get();
+    assertEquals(vars?.ackRetryRound, 0);
+    assertEquals(vars?.ackRetryMax, MAX_ACK_RETRIES);
+  });
+});
+
 // Lineage threading (issue #245): `submitPr` persists the origin `root_request_key` on the PR row
 // and carries it onto the convergence instance; `startMerge` reads it back off the row onto the
 // merge instance. A human/webhook submit that supplies no root self-roots on the `pr_key` (its own

package/app/service.ts

@@ -159,6 +159,20 @@ export const MAX_REBASE_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_REBASE
  * retry (a race escalates immediately). Reuses the CI-fix budget clamp (allows 0 = disable). */
 export const MAX_MERGE_RETRIES = clampCiFixBudget(process.env.NANO_PR_MAX_MERGE_RETRIES, 5);
 
+/** How many times the convergence loop will re-dispatch the `senior:pr-review` (review-round) agent
+ * to auto-ack unacked suppressed advisories before escalating to a human. When the converge-gate
+ * blocks SOLELY on unacknowledged suppressed advisories (no unresolved inline threads), the block is
+ * recoverable: re-running the review-round agent posts the missing `nano-ack:` threads and converges,
+ * so the loop tries that — bounded — before parking the human `wait-answer` (issue #796). A resolved
+ * `Declined … nano-ack:` advisory is an acknowledgement and CONVERGES (issue #787), so a decline does
+ * not escalate; only the agent returning `needs_input` (a genuinely contested advisory it cannot
+ * decide) or `blocked` (an external blocker it reports with a question — the `gw-status` arm at
+ * `convergence-loop.bpmn:442-443` routes both to `wait-answer`), or this budget being exhausted,
+ * escalates. Default 2; set
+ * `NANO_PR_MAX_ACK_RETRIES=0` to escalate on the first ack-only block. Reuses the CI-fix budget clamp
+ * (allows 0 = disable, ceiling-capped). */
+export const MAX_ACK_RETRIES = clampCiFixBudget(process.env.NANO_PR_MAX_ACK_RETRIES, 2);
+
 /** How many times the mergeable-wait timeout backstop (`merge-stall-probe`) will re-derive
  * mergeability from ground truth and re-arm the merge stage before giving up and escalating to a
  * human. Bounds the timer arm of the `gw-merge-wait` event-based gateway so a dead in-process poller
@@ -644,6 +658,11 @@ export async function submitPr(
       round: 1,
       maxRounds: clampRounds(maxRounds, MAX_ROUNDS),
       reviewWaitTimeout: REVIEW_WAIT_TIMEOUT,
+      // Bounded agent auto-ack (issue #796): the convergence loop re-dispatches the review-round
+      // agent up to `ackRetryMax` times to ack suppressed advisories when the converge-gate blocks
+      // solely on unacked ones, before escalating to a human. `ackRetryRound` counts those passes.
+      ackRetryRound: 0,
+      ackRetryMax: MAX_ACK_RETRIES,
       // Lineage (issue #245): carry the origin identity onto the convergence instance so every
       // descendant (and any message it correlates) is stitched back to the originating request.
       // A human/webhook PR that is its own root carries its own `pr_key` (never NULL — see above).

package/package.json

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