@nanobpm/nano-workforce 0.187.5 → 0.188.0

package/test/derivation-parity/derivation-parity.test.ts

@@ -125,13 +125,14 @@ test("convergence-loop golden has arbitrary-graph features the structured builde
     const body = rest.slice(0, close);
     return (body.match(new RegExp(`<bpmn:${tag}\\b`, "g")) ?? []).length;
   };
-  // (a) the loop head is a serviceTask that MERGES four back-edges directly — after #786/#789 the
+  // (a) the loop head is a serviceTask that MERGES its back-edges directly — after #786/#789 the
   // round-entry head capture (`capture-head`) is the loop head sitting BEFORE `review-round`, so it
-  // is `capture-head` that absorbs the four back-edges (the review loop, the answer resume, the
-  // escalation re-enter, and the #786 husk auto-retry); `review-round` then takes its single
-  // `f_capture` in-edge. A serviceTask merging four back-edges directly is the arbitrary-graph shape
-  // the structured builder cannot emit — the feature this asserts, now on `capture-head`.
-  assertEquals(between("capture-head", "serviceTask", "incoming"), 4, "capture-head should merge 4 flows on the task itself");
+  // is `capture-head` that absorbs the back-edges (f_start, the review loop, the answer resume, the
+  // #786 husk auto-retry, and the #796 bounded auto-ack re-entry f_ackRetry); `review-round` then
+  // takes its single `f_capture` in-edge. A serviceTask merging FIVE back-edges directly is the
+  // arbitrary-graph shape the structured builder cannot emit — the feature this asserts, now on
+  // `capture-head`.
+  assertEquals(between("capture-head", "serviceTask", "incoming"), 5, "capture-head should merge 5 flows on the task itself");
   assertEquals(between("review-round", "serviceTask", "incoming"), 1, "review-round now takes the single f_capture in-edge");
   // (b) a single exclusive gateway forks FOUR heterogeneous-condition out-edges.
   assertEquals(between("gw-status", "exclusiveGateway", "outgoing"), 4, "gw-status should be a 4-way exclusive gateway");
@@ -143,8 +144,9 @@ test("convergence-loop golden has arbitrary-graph features the structured builde
 // CLASS 2, empirical — demonstrate WHY the structured builder cannot reproduce
 // (a): a `loop()` whose body starts with a task derives an exclusive-gateway
 // loop head that absorbs the back-edge (in>=2), leaving the task itself at
-// in=1. The golden instead merges its back-edges directly into `review-round`
-// (in=4) with no loop-head gateway — a shape the builder cannot express.
+// in=1. The golden instead merges its back-edges directly into `capture-head`
+// (capture-head in=5: f_start, f_reviewLoop, f_answerLoop, the #786 f_huskRetry, and the #796
+// f_ackRetry re-entry) with no loop-head gateway — a shape the builder cannot express.
 test("loop() inserts a gateway head, so back-edges cannot merge into a task", () => {
   const probe = defineFlow("loop-head-probe", (w) => {
     w.loop((b) => {

package/test/derivation-parity/flows.ts

@@ -23,8 +23,8 @@
 //     (2) ARBITRARY control-flow graph (convergence-loop). Single start/end —
 //         so it clears class (1) — but its topology is NOT expressible with the
 //         structured-only builder (`loop`/`switch`/`branch`), empirically proven
-//         (see `derivation-parity.test.ts`): its loop head `review-round` is a
-//         serviceTask that MERGES four back-edges directly (in=4), whereas
+//         (see `derivation-parity.test.ts`): its loop head `capture-head` is a
+//         serviceTask that MERGES five back-edges directly (in=5), whereas
 //         `loop()` always inserts an exclusive-gateway loop head (the task stays
 //         in=1); `gw-status` is a single exclusive gateway with FOUR
 //         heterogeneous-condition out-edges (two `=x = "v"`, one complex boolean,
@@ -207,8 +207,10 @@ export const PORTS: readonly PortEntry[] = [
       "blocked (arbitrary control-flow graph): single top-level start/end, but " +
       "its topology is not expressible with the published @nanobpm/workflow's " +
       "structured-only builder (loop/switch/branch). Proven in the test suite: " +
-      "the loop head `review-round` is a serviceTask that merges 4 back-edges " +
-      "directly (in=4), but loop() always inserts an exclusive-gateway head " +
+      "the loop head `capture-head` is a serviceTask that merges 5 back-edges " +
+      "directly (in=5: f_start, f_reviewLoop, f_answerLoop, the #786 husk " +
+      "auto-retry f_huskRetry, and the #796 bounded auto-ack re-entry " +
+      "f_ackRetry), but loop() always inserts an exclusive-gateway head " +
       "(task stays in=1); `gw-status` is one gateway with 4 heterogeneous-" +
       "condition out-edges (no switch/branch emits that); `gw-escalated` is one " +
       "gateway that is at once a 6-way merge and a 2-way split. Awaits an " +

package/workers/converge-gate/worker.ts

@@ -6,15 +6,28 @@
 // the comment unaddressed). This step runs on the converged path, BEFORE the scope classifier and
 // pr.finalize hand off to the merge loop, and blocks handoff while GitHub still shows unaddressed
 // comments:
-//   • any review THREAD is still unresolved (GraphQL `isResolved = false`), or
+//   • any SUBSTANTIVE review THREAD is still unresolved (GraphQL `isResolved = false`), or an
+//     unresolved `nano-ack:` ACK thread is open — an ack thread is a partially-completed
+//     acknowledgement the bounded #796 auto-ack retry can finish, so it still BLOCKS (a
+//     genuinely-open GitHub thread) but the block stays ack-only (recoverable) rather than escalating
+//     to a human; only a substantive open thread escalates, or
 //   • any SUPPRESSED advisory in the latest Copilot review body lacks a matching RESOLVED ack
 //     thread (a `nano-ack: <path> :: <verbatim advisory text>` marker whose line-stable prose
 //     fingerprint matches Copilot's advisory). The bare legacy `nano-ack: <path>:<line>` form is
 //     NOT honoured: keyed only on `path:line`, it is blind to the advisory prose and would let a
 //     resolved ack for one advisory silently acknowledge a genuinely new advisory re-emitted at
 //     that same line (a false-OPEN). Only the prose-keyed `<path> :: <text>` form acknowledges.
-// A blocked gate returns `convergeBlocked = true`; the model's `gw-converge-gate` gateway routes to
-// the human `wait-answer` escalation (recoverable), never a hard wedge.
+// A blocked gate returns `convergeBlocked = true` (recoverable, never a hard wedge); the route then
+// depends on WHY it blocked. An ack-only block (`convergeAckOnly = true` — sole cause is unacked
+// suppressed advisories and/or an unresolved `nano-ack:` ack thread) re-dispatches the `review-round`
+// agent first, bounded by `ackRetryMax`, and only reaches the human `wait-answer` escalation once
+// that budget is exhausted. A substantive unresolved thread routes to `wait-answer` immediately.
+//
+// STALE-REVIEW GUARD (issue #799): when the PR HEAD has advanced PAST the commit the latest Copilot
+// review was submitted against, that review's body describes code the head has moved past, so the
+// gate signals `reviewStale = true` (rather than blocking on the obsolete body) and the process
+// re-enters the review wait for a fresh review of the current HEAD. The head read fails OPEN, so a
+// transport hiccup can never fabricate a stale verdict.
 //
 // Scope integrity is NO LONGER judged here. A deterministic regex over the PR description could not
 // read the closed issue's acceptance criteria, so it false-positived on any body that merely
@@ -30,14 +43,19 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { type ConvergeGateResult, evaluateConvergeGate } from "../../app/convergeGate.ts";
 import {
-  fetchLatestCopilotReviewBody,
+  fetchBranchHead,
+  fetchLatestCopilotReview,
+  fetchPrHead,
   fetchReviewThreads,
+  isAckThread,
   parseAckedAdvisories,
   parseSuppressedAdvisories,
   type ReviewThread,
 } from "../../app/github.ts";
+import { isReviewStale } from "../../app/reviewWait.ts";
 import { parsePr } from "../../app/service.ts";
 import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
+import { type HeadReader, makeDefaultReadHead } from "../progress-check/worker.ts";
 
 // Input/output typed off the model data envelopes (`PrConvergeGateIn` / `PrConvergeGateOut` in
 // convergence-loop.bpmn), the single source of truth for this worker's wire contract (ADR 0040).
@@ -47,14 +65,20 @@ type Out = WorkerOutputs["pr.converge-gate"];
 // Reads a PR's review threads. `null` = no usable transport (treated as an unverifiable read →
 // fail closed). Throws propagate to the fail-closed catch below.
 export type ThreadsReader = (repo: string, prNumber: number) => Promise<ReviewThread[] | null>;
-// Reads the latest Copilot review body. `null` = no usable transport (unverifiable → fail closed);
-// `""` = transport usable but no Copilot review yet (verified: no suppressed advisories).
-export type ReviewBodyReader = (repo: string, prNumber: number) => Promise<string | null>;
+// Reads the latest Copilot review — body AND the commit SHA it was submitted against. `null` = no
+// usable transport (unverifiable → fail closed); `{ body: "", commitId: null }` = transport usable
+// but no Copilot review yet (verified: no suppressed advisories). The `commitId` drives the
+// stale-review detection below (issue #799).
+export type ReviewReader = (repo: string, prNumber: number) => Promise<{ body: string; commitId: string | null } | null>;
 
 const defaultReadThreads: ThreadsReader = (repo, prNumber) =>
   fetchReviewThreads(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
-const defaultReadReviewBody: ReviewBodyReader = (repo, prNumber) =>
-  fetchLatestCopilotReviewBody(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
+const defaultReadReview: ReviewReader = (repo, prNumber) =>
+  fetchLatestCopilotReview(repo, prNumber, process.env.GITHUB_TOKEN ?? "");
+// The PR's current HEAD SHA, read via the same branch-ref-over-stale-`head.sha` reader the
+// capture-head / progress-check steps use (#786), so the gate's staleness comparison sees the exact
+// head those steps do. Fails OPEN to `null` (unreadable head → not-stale, per {@link isReviewStale}).
+const defaultReadHead: HeadReader = makeDefaultReadHead({ fetchPrHead, fetchBranchHead });
 
 const BLOCK_UNVERIFIABLE =
   "Convergence blocked: could not verify the PR's review comments against GitHub. A human must confirm every Copilot review thread is resolved and every suppressed advisory acknowledged before this PR converges (reply to resume the loop).";
@@ -63,8 +87,10 @@ const BLOCK_UNVERIFIABLE =
  * tests inject stubs. Fails CLOSED — any unreadable/errored state blocks convergence. */
 export function makeHandler(deps: {
   readThreads: ThreadsReader;
-  readReviewBody: ReviewBodyReader;
+  readReview: ReviewReader;
+  readHeadSha?: HeadReader;
 }): AppJobHandler<In, Out> {
+  const readHeadSha = deps.readHeadSha ?? defaultReadHead;
   return async (job) => {
     const { prKey, repo, prNumber } = job.variables;
     // `parsePr` is total on any input (fails closed to `null` on a missing/non-string prKey), so
@@ -73,43 +99,76 @@ export function makeHandler(deps: {
     const ghRepo = repo ?? parsed?.repo;
     const ghNumber = typeof prNumber === "number" ? prNumber : parsed?.number;
     if (!ghRepo || typeof ghNumber !== "number") {
-      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
     }
 
     let result: ConvergeGateResult;
     try {
-      const threads = await deps.readThreads(ghRepo, ghNumber);
+      const threadsRead = await deps.readThreads(ghRepo, ghNumber);
       // A null threads read is an unverifiable gate — fail closed. (An empty ARRAY is a verified
-      // "no threads" and is fine.)
-      if (threads === null) {
-        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+      // "no threads" and is fine.) An unverifiable block is NOT ack-only: it needs a human to
+      // confirm GitHub state, so it must not enter the bounded agent auto-ack path (#796).
+      if (threadsRead === null) {
+        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
+      }
+      const review = await deps.readReview(ghRepo, ghNumber);
+      // A null review read is an unverifiable read (no usable transport) — fail closed, same as a
+      // null threads read. (A `{ body: "", commitId: null }` result is a verified "no Copilot
+      // review / no advisories".)
+      if (review === null) {
+        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
       }
-      const reviewBody = await deps.readReviewBody(ghRepo, ghNumber);
-      // A null review body is an unverifiable read (no usable transport) — fail closed, same as a
-      // null threads read. (An empty STRING is a verified "no Copilot review / no advisories".)
-      if (reviewBody === null) {
-        return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+      // STALE-REVIEW GUARD (issue #799). When the PR HEAD has advanced PAST the commit the latest
+      // Copilot review was submitted against, that review's suppressed advisories describe code the
+      // head has moved past — e.g. an advisory the agent already FIXED IN CODE (but did not ack) is
+      // still re-listed in the obsolete body. Blocking/escalating on it re-escalates a human
+      // indefinitely (PR #789). Instead of gating on the stale body, signal `reviewStale` so the
+      // process re-enters the review wait and the poller re-solicits a fresh review of the current
+      // HEAD to gate on. The head read fails OPEN (null → not stale), so a transport hiccup can never
+      // fabricate a stale verdict; the ordinary gate below still runs on a HEAD-current review.
+      const headSha = await readHeadSha(ghRepo, ghNumber).catch(() => null);
+      if (isReviewStale(review.commitId, headSha)) {
+        return { convergeBlocked: false, convergeBlockReason: "", convergeAckOnly: false, reviewStale: true };
       }
-      const unresolvedThreadCount = threads.filter((t) => !t.isResolved).length;
-      const advisories = parseSuppressedAdvisories(reviewBody);
+      // Split the unresolved threads into SUBSTANTIVE reviewer findings vs partially-completed
+      // `nano-ack:` ACK threads (root carries a canonical `nano-ack: <path> :: <text>` marker — see
+      // `isAckThread`). Neither is ever dropped from the gate: a substantive unresolved thread blocks
+      // and escalates to a human; an unresolved ack thread ALSO blocks (it is a genuinely-open GitHub
+      // thread), but the block stays ack-only (recoverable by the bounded #796 auto-ack retry, which
+      // re-posts/resolves it). Keeping the ack thread a BLOCKING condition — rather than filtering it
+      // away — is what makes the root-marker classifier fail-CLOSED: a mislabelled substantive 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.
+      const unresolved = threadsRead.filter((t) => !t.isResolved);
+      const unresolvedAckThreadCount = unresolved.filter((t) => isAckThread(t)).length;
+      const unresolvedThreadCount = unresolved.length - unresolvedAckThreadCount;
+      const advisories = parseSuppressedAdvisories(review.body);
       result = evaluateConvergeGate({
         unresolvedThreadCount,
+        unresolvedAckThreadCount,
         suppressedAdvisories: advisories.map((a) => ({ key: a.key, label: a.label })),
-        acknowledgedKeys: parseAckedAdvisories(threads),
+        acknowledgedKeys: parseAckedAdvisories(threadsRead),
       });
     } catch {
-      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE };
+      return { convergeBlocked: true, convergeBlockReason: BLOCK_UNVERIFIABLE, convergeAckOnly: false, reviewStale: false };
     }
 
     return {
       convergeBlocked: result.convergeBlocked,
       convergeBlockReason: result.convergeBlockReason,
+      // Signals the bounded agent auto-ack path (#796): a block whose sole cause is recoverable —
+      // unacked suppressed advisories AND/OR a lone unresolved `nano-ack:` ack thread (a
+      // partially-completed acknowledgement), with NO substantive unresolved thread — re-dispatches
+      // the review-round agent before escalating to a human.
+      convergeAckOnly: result.ackOnly,
+      reviewStale: false,
     };
   };
 }
 
 const handler = makeHandler({
   readThreads: defaultReadThreads,
-  readReviewBody: defaultReadReviewBody,
+  readReview: defaultReadReview,
+  readHeadSha: defaultReadHead,
 });
 export default handler;

package/workers/progress-check/worker.ts

@@ -16,6 +16,7 @@
 // could not read fails OPEN — the round cap and the review-wait timeout stay the safety nets so a
 // transient GitHub hiccup can never fabricate a no-progress escalation.
 import type { AgentInstanceSummary, AppApi, AppJobHandler } from "@nanobpm/urban";
+import { type HeadReader, makeDefaultReadHead } from "../../app/currentHead.ts";
 import { fetchBranchHead, fetchPrHead } from "../../app/github.ts";
 import { decideProgress, isAddressedStatus } from "../../app/roundProgress.ts";
 import { parsePr } from "../../app/service.ts";
@@ -26,16 +27,6 @@ import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io
 type In = WorkerInputs["pr.progress-check"];
 type Out = WorkerOutputs["pr.progress-check"];
 
-// Reads a PR's current head SHA. Injectable so unit tests never touch git/network; the default
-// binds the real GitHub reader (the shared gh | token transport) and swallows any failure to
-// `null` so the guard fails OPEN. It reads the BRANCH ref (`git/ref/heads/<branch>`) — updated
-// atomically with the push — in preference to the PR object's asynchronously-denormalized
-// `head.sha`, so a lagging PR projection can never fabricate a stale-but-valid no-advance
-// escalation (#786). Once a head ref is known this trusts ONLY its atomic ref: a failed/absent
-// ref read fails OPEN (`null`), never falling back to `head.sha`. The PR head is used only when
-// the PR carries NO head ref at all.
-export type HeadReader = (repo: string, prNumber: number) => Promise<string | null>;
-
 /** The outcome of an agent-work corroboration, optionally carrying the ATTEMPT WATERMARK it
  * consumed. `work` is the husk verdict decideProgress routes on (`true` no-advance / `false` husk /
  * `null` unknown). `consumedKey` — when present — is the greatest `review-round` instance key this
@@ -76,40 +67,11 @@ function normalizeAgentWork(raw: boolean | null | AgentWorkObservation | undefin
   return raw;
 }
 
-/** Build the default head reader over injected GitHub fetchers. Exported (with injectable fetchers)
- * so the branch-ref-over-stale-`head.sha` preference — the whole point of {@link fetchBranchHead}
- * here (#786) — is covered by a handler-level regression test, not only inside the private binding:
- * a change that stopped reading the branch ref, or fell back to `head.sha`, must turn a test red. */
-export function makeDefaultReadHead(deps: {
-  fetchPrHead: typeof fetchPrHead;
-  fetchBranchHead: typeof fetchBranchHead;
-}): HeadReader {
-  return async (repo, prNumber) => {
-    const token = process.env.GITHUB_TOKEN ?? "";
-    const pr = await deps.fetchPrHead(repo, prNumber, token).catch(() => null);
-    if (!pr) return null;
-    // Prefer the branch ref (atomic with the push) over the PR object's denormalized head.sha (#786).
-    // Once the head branch is known, trust ONLY its atomic ref: a failed/absent ref read fails OPEN
-    // (`null`) rather than falling back to the PR object's asynchronously-denormalized head.sha, which
-    // can still report a stale-but-valid SHA after a push and fabricate a no-advance escalation — the
-    // very projection this branch-ref read exists to avoid. The ref is read in the repository the
-    // head branch actually lives in (the fork for a cross-repo PR — see below), so a fork PR fails
-    // open safely instead of comparing an unrelated base-repo SHA. Fall back to the PR head only when
-    // there is NO head ref.
-    if (pr.headRef) {
-      // Resolve the head ref in the repository the head branch actually lives in — the FORK for a
-      // cross-repo PR (`pr.headRepo`), else the base `repo`. Querying the base repo unconditionally
-      // would, for a fork PR whose head branch shares a name with a base-repo branch, read the
-      // unrelated base-branch SHA and fabricate progress/no-progress (#786). When the head repo
-      // cannot be resolved (a deleted fork ⇒ `headRepo:null`) fail OPEN to `null` rather than fall
-      // back to the base repo and risk that collision.
-      const headRepo = pr.headRepo;
-      if (!headRepo) return null;
-      return await deps.fetchBranchHead(headRepo, pr.headRef, token).catch(() => null);
-    }
-    return pr.headSha ?? null;
-  };
-}
+/** Re-exported from {@link ../../app/currentHead.ts} (the single canonical implementation of the
+ * branch-ref-over-stale-`head.sha` head reader, #786/#799) so existing importers of these symbols
+ * from this worker keep resolving without a duplicated copy — the poller in `app/service.ts` binds
+ * the same reader from `currentHead.ts` directly. */
+export { type HeadReader, makeDefaultReadHead };
 
 const defaultReadHead: HeadReader = makeDefaultReadHead({ fetchPrHead, fetchBranchHead });