@nanobpm/nano-workforce 0.187.4 → 0.187.5

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.187.5](https://github.com/nanobpm/nano-workforce/compare/v0.187.4...v0.187.5) (2026-09-15)
+
+### Bug Fixes
+
+* **convergence:** classify husked review rounds and bound-retry the no-progress loop ([#789](https://github.com/nanobpm/nano-workforce/issues/789)) ([faebcdc](https://github.com/nanobpm/nano-workforce/commit/faebcdcaca017fab8d7436a50e3dc09354dc3022)), closes [jwulf/c8ctl-plugin-nano#230](https://github.com/jwulf/c8ctl-plugin-nano/issues/230) [#786](https://github.com/nanobpm/nano-workforce/issues/786) [#786](https://github.com/nanobpm/nano-workforce/issues/786)
+
 ## [0.187.4](https://github.com/nanobpm/nano-workforce/compare/v0.187.3...v0.187.4) (2026-09-14)
 
 ### Bug Fixes

package/SPEC.md

@@ -101,11 +101,17 @@ known at submit time, carried as a process variable and stored on the DB row.
 │    <gateway: status>
 │      ├── converged  → [Mark converged] → (end: converged)
 │      │
-│      ├── addressed  → [Record round] → <event-based gateway: review ready or timeout?>
-│      │                     ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
-│      │                     └── =reviewWaitTimeout (timer catch)                     │
-│      │                          → [Escalate: review stalled] (blocked)              │
-│      │                          → [Wait: wait-answer userTask] ─────────────────────┤
+│      ├── addressed  → [Record round] → [Check progress] (did the PR head advance?)
+│      │                   ├── progressed → <guard: round ≥ maxRounds → escalate "not converged"> │
+│      │                   │                   → <event-based gateway: review ready or timeout?>   │
+│      │                   │      ├── readiness-ready (msg catch, key = prKey) → round++ ─┐
+│      │                   │      └── =reviewWaitTimeout (timer catch)                    │
+│      │                   │           → [Escalate: review stalled] (blocked)             │
+│      │                   │           → [Wait: wait-answer userTask] ────────────────────┤
+│      │                   └── no progress → <husk? no commit AND no terminal instance>   │
+│      │                          ├── husk & retries < MAX → re-enter [Review round] (bypasses the round-cap guard) │
+│      │                          └── no-advance / husk cap → [Escalate: no progress]      │
+│      │                                     → [Wait: wait-answer userTask] ───────────────────┤
 │      │                                                                             │
 │      └── needs_input     [Record escalation]                       │               │
 │          or blocked  →   (kind = question | blocker)               │               │
@@ -124,8 +130,11 @@ step, then retry the same round with the human's `answer`. They differ only by e
 which the UI uses to label the card. Neither ends the run — a human always gets
 a chance to unblock and resume.
 
-Guard: before each Review round, if round > MAX_ROUNDS → force an escalation
-("not converged after N rounds") so a human decides, rather than looping forever.
+Guard: after progress classification, a **progressing** round with round ≥
+MAX_ROUNDS forces an escalation ("not converged after N rounds") so a human
+decides rather than looping forever. The guard sits *after* `check-progress`
+(not before), so a husk auto-retry — which does not consume a round — bypasses
+the cap and is re-tried onto a healthy worker even on the final configured round.
 ```
 
 Notes:
@@ -149,6 +158,59 @@ Notes:
   backstop when even repeated nudges fail.
 - On `needs_input`, the same `round` is retried after the answer (the answer is
   added to the agent's context; the round number does not advance).
+- **No-progress guard + husk classification (issue #786).** Before the review
+  wait, an `addressed` round passes through `pr.progress-check`
+  (`workers/progress-check/worker.ts`, mirrored by `app/roundProgress.ts`): it
+  reads the PR's current head SHA (the branch ref, atomic with the push) and
+  compares it to the **round-entry head** — the head captured by `pr.capture-head`
+  immediately BEFORE `review-round` ran this round, published as the
+  `roundEntryHead` process variable. `pr.capture-head` sits on EVERY entry into
+  `review-round` (the first round from `Start`, a review-loop re-enter, a
+  human-answer resume, and a husk auto-retry), so within any round there is always
+  a baseline captured against the agent's own starting point — closing the
+  no-baseline gap where a FIRST addressed round had no prior-round head to compare
+  against (and either waved a first-round husk through as progress, or risked
+  mis-escalating a straggler push). If `roundEntryHead` is absent — an older
+  in-flight instance whose flow predates `capture-head`, or a capture read that
+  failed open (it publishes the empty string as its "unknown" sentinel) —
+  progress-check falls back to the head persisted from the previous round
+  (`last_round_head`). A round whose head DID advance past the round-entry baseline
+  is real progress and continues to the review-wait gateway. A round whose head did
+  NOT advance pushed no commit, so re-requesting a review would loop on
+  byte-identical code; `gw-progress` routes it to `gw-husk`, which SPLITS it on a
+  corroboration correlated to the COMPLETING `review-round` element-instance (NOT
+  an aggregate terminal count — a same-round human-answered resume is classified on
+  its own fresh attempt):
+    - a **husk** — no commit AND the completing `review-round` attempt is
+      NON-TERMINAL (the producer harness died mid-run, leaving a stuck instance) —
+      is auto-re-run onto a healthy worker up to `MAX_HUSK_RETRIES` (2) before
+      escalating; and
+    - a **no-advance** — the completing attempt ran to a terminal instance but
+      nothing was pushed — (and a husk that exhausts its retries) escalates to the
+      human `wait-answer` task.
+  The agent-instance read is AVAILABILITY-AWARE via a **two-tier probe** and fails
+  SAFE (ADR 0056). `review-round` is an external-agent service task, so a job that
+  husks BEFORE it ever registers an AgentInstance leaves the scoped `review-round`
+  search EMPTY — indistinguishable, on that query alone, from an engine that has no
+  AgentInstance projection at all. The probe therefore resolves an empty
+  `review-round` search against a SECOND, process-wide read:
+    - if the process-wide read also finds NO instance, the **channel is absent**
+      (an engine with no AgentInstance projection) — UNKNOWN, treated as no-advance,
+      never an auto-retry that could duplicate genuinely-completed work;
+    - if the process-wide read finds ANOTHER instance (from `classify-scope`, an
+      earlier round, etc.), the **channel is PRESENT** but this round registered
+      nothing — a genuine **pre-registration husk**, so it is classified as a husk
+      and auto-retried.
+  A head that cannot be read fails OPEN (continue), so a transient GitHub hiccup
+  never fabricates a no-progress escalation. Two supporting invariants keep an
+  auto-retry clean: `pr.persist-round`
+  records a round IDEMPOTENTLY on `(pr_key, round_no, process_instance_key)` — a husk
+  retry (same process instance) updates its row in place, while a resubmission that
+  re-opens the PR at round 1 in a NEW process instance inserts a fresh row and so
+  never clobbers a prior run's durable round history (migration 102) — and the guard flips the PR back to
+  the running `converging` status before a retry re-enters `review-round` so the
+  poller does not solicit a spurious review against the still-running round. The
+  round cap and the review-wait timeout remain the outer safety nets.
 
 
 ## 5. Agent job contract (`senior:pr-review`)

package/app/convergenceEscalationGuard.test.ts

@@ -19,7 +19,8 @@
 //
 // The fix (mirroring the merge loop's `gw-merge-escalated`, PR #331): route EVERY arm that can reach
 // `wait-answer` through the single `gw-escalated` guard, so a `persist-escalation` returning
-// `escalated:false` RE-ENTERS the loop (`gw-guard`) instead of parking a dead wait. This makes the
+// `escalated:false` RE-ENTERS the loop (round processing, `persist-round`) instead of parking a dead
+// wait. This makes the
 // invariant structural — `wait-answer` is reachable ONLY from a `gw-escalated == true` edge, so a
 // "durable answer-wait with no escalation" is unrepresentable.
 //
@@ -77,7 +78,7 @@ test("gw-escalated honours persist-escalation's escalated output for every arm",
   assertStringIncludes(escWait![0], "escalated = true", "the wait arm must be guarded by escalated = true");
   // escalated:false (a non-escalation, e.g. a blank convergeBlockReason) → re-enter the loop, not a dead wait.
   assert(gatewayDefault("gw-escalated", "f_escReenter"), "gw-escalated default must re-enter the loop");
-  assert(flowHasId("f_escReenter", "gw-escalated", "gw-guard"), "the non-escalation arm must re-enter via gw-guard, not park a wait");
+  assert(flowHasId("f_escReenter", "gw-escalated", "persist-round"), "the non-escalation arm must re-enter round processing (persist-round), not park a wait");
 });
 
 test("wait-answer is reachable ONLY from the gw-escalated == true edge (structural invariant)", () => {

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, isNotAPullRequestError, listPrsForHead, type Mergeability, type PrState } from "./github.ts";
 import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol, type RequiredCheck } from "./mergeProtocol.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
@@ -723,3 +723,127 @@ test("checkConclusions: in-flight runs map to '' for both CheckRun and StatusCon
     "legacy-error": "ERROR",
   });
 });
+
+// ── fetchBranchHead — the atomic branch-ref reader (issue #786) ──────────────
+//
+// The no-progress guard reads the branch ref (git/ref/heads/<branch>), updated ATOMICALLY with the
+// push, rather than the PR object's asynchronously-denormalized head.sha, so a lagging PR projection
+// can never fabricate a stale-but-valid no-advance escalation. Force the token transport and stub
+// `globalThis.fetch` to serve the git-ref endpoint.
+async function withRefFetch<T>(
+  serve: (path: string) => { status: number; body: unknown },
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = ((url: string | URL | Request): Promise<Response> => {
+    const path = new URL(String(url)).pathname.replace(/^\/repos\//, "");
+    const { status, body } = serve(path);
+    return Promise.resolve(new Response(JSON.stringify(body), { status }));
+  }) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("fetchBranchHead: returns the branch ref's atomic head SHA", async () => {
+  const sha = await withRefFetch(
+    (path) => {
+      assertEquals(path, "o/r/git/ref/heads/feat/x");
+      return { status: 200, body: { object: { sha: "deadbeef" } } };
+    },
+    () => fetchBranchHead("o/r", "feat/x", "tok"),
+  );
+  assertEquals(sha, "deadbeef");
+});
+
+test("fetchBranchHead: a 404 (branch absent) resolves to null, never throws", async () => {
+  const sha = await withRefFetch(
+    () => ({ status: 404, body: { message: "Not Found" } }),
+    () => fetchBranchHead("o/r", "feat/missing", "tok"),
+  );
+  assertEquals(sha, null);
+});
+
+test("fetchBranchHead: no usable transport (token mode, empty token) resolves to null, never throws", async () => {
+  // The documented contract promises `null` when no transport is usable, matching fetchPrHead /
+  // fetchPrBase — a missing token under the token transport must not surface an exception to callers
+  // relying on the Promise<string | null> shape.
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  try {
+    const sha = await fetchBranchHead("o/r", "feat/x", "");
+    assertEquals(sha, null);
+  } finally {
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+});
+
+// ── fetchPrHead — the PR head reader surfaces the head branch's OWNING repo (issue #786) ─────
+//
+// The no-progress head reader resolves the head ref in `headRepo`, so a cross-repo (fork) PR reads
+// the fork's ref, not a same-named branch in the base repo (which would resolve to an unrelated
+// SHA). These assert the transport-level mapping of the source repository through `fetchPrHead`'s
+// REST branch (forced via the token transport), which the handler-level tests — injecting an
+// already-parsed `{ headRepo }` — do not exercise.
+test("fetchPrHead: REST maps head.repo.full_name to the fork's source repository", async () => {
+  const head = await withRefFetch(
+    (path) => {
+      assertEquals(path, "base/repo/pulls/789");
+      return {
+        status: 200,
+        body: {
+          head: { ref: "feat/x", sha: "cafef00d", repo: { full_name: "fork-owner/repo" } },
+          base: { ref: "main" },
+        },
+      };
+    },
+    () => fetchPrHead("base/repo", 789, "tok"),
+  );
+  assertEquals(head, { headRef: "feat/x", headSha: "cafef00d", baseRef: "main", headRepo: "fork-owner/repo" });
+});
+
+test("fetchPrHead: REST fails open to headRepo=null when the head repo is absent (deleted fork)", async () => {
+  const head = await withRefFetch(
+    () => ({
+      status: 200,
+      body: { head: { ref: "feat/x", sha: "cafef00d", repo: null }, base: { ref: "main" } },
+    }),
+    () => fetchPrHead("base/repo", 789, "tok"),
+  );
+  // A null head repo must surface as headRepo=null (the reader then fails open), never the base repo.
+  assertEquals(head?.headRepo, null);
+});
+
+test("fetchPrHead: no usable transport (token mode, empty token) resolves to null, never throws", async () => {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  try {
+    const head = await fetchPrHead("o/r", 1, "");
+    assertEquals(head, null);
+  } finally {
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+});
+
+// A branch name may legally contain `#`, `?`, or spaces. The reader must percent-encode each ref
+// SEGMENT (preserving `/`) before building the API path/URL — otherwise a `#` starts a URL fragment,
+// the path is truncated to the wrong ref, and the no-progress guard fails open (issue #786).
+test("fetchBranchHead: percent-encodes a special-character branch ref (preserving '/')", async () => {
+  const sha = await withRefFetch(
+    (path) => {
+      // The `#` must survive as %23 inside the path, not truncate it into a URL fragment.
+      assertEquals(path, "o/r/git/ref/heads/feat/x%23123");
+      return { status: 200, body: { object: { sha: "cafef00d" } } };
+    },
+    () => fetchBranchHead("o/r", "feat/x#123", "tok"),
+  );
+  assertEquals(sha, "cafef00d");
+});

package/app/github.ts

@@ -1067,17 +1067,25 @@ export async function fetchPrFiles(
   return paths;
 }
 
-/** The PR head ref/sha for D3's trial-merge gate. `null` when no transport is usable. */
+/** The PR head ref/sha for D3's trial-merge gate. `null` when no transport is usable. `headRepo` is
+ * the head branch's OWNING repository as `owner/repo` — the FORK for a cross-repo PR, else the base
+ * repo — so a caller that resolves the head ref (e.g. the no-progress head reader, #786) queries the
+ * repository the head branch actually lives in, not the base repo (where a same-named branch would
+ * resolve to an unrelated SHA). `null` when the head repository cannot be resolved (e.g. a deleted
+ * fork). */
 export async function fetchPrHead(
   repo: string,
   number: number | string,
   token: string,
-): Promise<{ headRef: string | null; headSha: string | null; baseRef: string | null } | null> {
+): Promise<{ headRef: string | null; headSha: string | null; baseRef: string | null; headRepo: string | null } | null> {
   if (await useGh()) {
-    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid,baseRefName"]);
+    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid,baseRefName,headRepository,headRepositoryOwner"]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null; baseRefName?: string | null };
-    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null, baseRef: j.baseRefName ?? null };
+    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null; baseRefName?: string | null; headRepository?: { name?: string | null } | null; headRepositoryOwner?: { login?: string | null } | null };
+    const owner = j.headRepositoryOwner?.login;
+    const name = j.headRepository?.name;
+    const headRepo = owner && name ? `${owner}/${name}` : null;
+    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null, baseRef: j.baseRefName ?? null, headRepo };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls/${number}`, {
@@ -1085,8 +1093,29 @@ export async function fetchPrHead(
   });
   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 j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null }; base?: { ref?: string | null } };
-  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null, baseRef: j.base?.ref ?? null };
+  const j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null; repo?: { full_name?: string | null } | null }; base?: { ref?: string | null } };
+  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null, baseRef: j.base?.ref ?? null, headRepo: j.head?.repo?.full_name ?? null };
+}
+
+/** The head commit SHA of `branch` on `repo`, read from the git-ref endpoint
+ * (`git/ref/heads/<branch>`) — the ref that GitHub updates ATOMICALLY with the push, unlike a PR
+ * object's `head.sha`, which is an asynchronously-denormalized projection that can briefly report a
+ * stale-but-valid SHA after a push. The no-progress guard (#786) reads this in preference to the PR
+ * head so a lagging PR denormalization can never fabricate a no-advance escalation. `null` when the
+ * branch does not exist (a 404) or no transport is usable; throws only on a genuine transport
+ * failure. */
+export async function fetchBranchHead(
+  repo: string,
+  branch: string,
+  token: string,
+): Promise<string | null> {
+  // Honor the documented no-transport contract at this public boundary, exactly like the sibling
+  // readers `fetchPrHead`/`fetchPrBase`: with no `gh` CLI and no token there is no usable transport,
+  // which is the idle "unknown" case → `null`, NOT an exception. The internal `branchHeadSha` still
+  // throws in that case for `ensureBaseBranch`'s callers, which treat a missing transport as a hard
+  // failure; this wrapper's `Promise<string | null>` contract promises `null` instead.
+  if (!(await useGh()) && !token) return null;
+  return branchHeadSha(repo, branch, token);
 }
 
 /** The PR's current base branch ref — the branch this PR would land *into*. `null` when no
@@ -1483,7 +1512,13 @@ function isEpicBranch(branch: string): boolean {
 /** Resolve the head commit SHA of `branch` on `repo`, or `null` when the branch does not exist
  * (a 404 from the git-ref endpoint). Throws only on a genuine transport failure. */
 async function branchHeadSha(repo: string, branch: string, token: string): Promise<string | null> {
-  const apiPath = `repos/${repo}/git/ref/heads/${branch}`;
+  // Percent-encode each ref SEGMENT (git permits `#`, `?`, spaces, etc. in a branch name) while
+  // preserving the `/` separators that git uses for hierarchical refs (`feat/x`). Interpolating the
+  // raw name would, in the direct `fetch` URL, let a `#` start a fragment (and `?` a query) — the
+  // path is truncated, the wrong ref (or a 404) is read, and the no-progress guard fails open. gh
+  // api receives the same already-encoded path.
+  const encodedBranch = branch.split("/").map(encodeURIComponent).join("/");
+  const apiPath = `repos/${repo}/git/ref/heads/${encodedBranch}`;
   if (await useGh()) {
     try {
       const out = await runGh(["api", apiPath]);

package/app/persist-escalation.test.ts

@@ -4,8 +4,9 @@
 // `addressed` row for this `round`. Re-inserting a `rounds` row there would record one round as
 // both `addressed` and `blocked`, making round history/UI ambiguous. The stalled arm therefore
 // passes `recordRound=false`, which must suppress the round insert while still opening the
-// escalation. The agent-raised / max-rounds arms omit the flag (no prior round row) and must
-// still record the round.
+// escalation. After #786/#789 the max-rounds arm ALSO runs after `persist-round` (the round-cap
+// guard moved downstream of progress classification) and likewise passes `recordRound=false`; an
+// agent-raised arm with no prior round row omits the flag and must still record the round.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import handler from "../workers/persist-escalation/worker.ts";
@@ -49,9 +50,9 @@ test("stalled arm (recordRound=false) does not insert a duplicate rounds row", a
   assertEquals((out as any).escalationId, 42);
 });
 
-test("escalation arm without the flag still records the round", async () => {
+test("an agent-raised arm without the flag still records the round", async () => {
   const { app, inserts } = fakeApp();
-  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "max rounds" } };
+  const job = { variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "needs input" } };
   await handler(job as any, app as any);
   assertEquals(inserts.rounds.length, 1);
   assertEquals((inserts.rounds[0] as any).round_no, 3);
@@ -183,7 +184,8 @@ test("persist-escalation heals from the prKey when repo/prNumber are absent", as
 
 // #333 — the control-flow escalation arms (no-progress / review-stalled / unaddressed-comments /
 // max-rounds) each set an explicit `status="blocked"` + a concrete `question` via `zeebe:input`
-// (recordRound=false for the three that run after `persist-round`). They now route through
+// (recordRound=false on every arm that runs after `persist-round` — which, after #786/#789 moved the
+// round-cap guard downstream of progress classification, now INCLUDES max-rounds). They route through
 // `gw-escalated`, which branches on the worker's `escalated` output. This pins the contract that
 // gateway depends on: a control-flow arm with a real question OPENS an escalation and returns
 // `escalated:true` + the (trimmed) question, so gw-escalated parks a wait carrying that question —

package/app/persist-round.test.ts

@@ -1,11 +1,12 @@
-// Red/green regression for pr.persist-round's round recording + parking behaviour.
+// Red/green regression for pr.persist-round's round recording behaviour.
 //
 // The convergence loop routes both `addressed` (the agent pushed changes) and the new `waiting`
 // (nothing to triage yet — round 1, awaiting the first review) statuses through gw-guard into
-// persist-round. Both must be recorded in `rounds` under their own status and both must park the
-// PR in `waiting_review` so the deterministic poller (app/service.ts) starts soliciting a review.
-// A `waiting` round is what replaced the old failure mode where an agent with nothing to do
-// re-requested the review destructively and escalated `blocked`.
+// persist-round. Both must be recorded in `rounds` under their own status and both must advance the
+// PR's `current_round`. The PARK into `waiting_review` is owned by the downstream pr.progress-check
+// step (the single writer of the post-round wait status), NOT persist-round — persist-round runs
+// before the husk decision, so parking here would let the poller fire a spurious review re-request
+// against a husk-retry round before progress-check resolves it (#786).
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
 import handler from "../workers/persist-round/worker.ts";
@@ -14,6 +15,7 @@ function fakeApp() {
   const inserts: Record<string, unknown[]> = { rounds: [] };
   const updates: Record<string, unknown[]> = { pull_requests: [] };
   const rows: Record<string, Map<string, unknown>> = {};
+  let roundsId = 0;
   const app = {
     data: {
       table(name: string, _key: string) {
@@ -22,14 +24,25 @@ function fakeApp() {
           async get(key: string) {
             return store.get(key);
           },
+          async find(criteria: Record<string, unknown>) {
+            return [...store.values()].filter((r) =>
+              Object.entries(criteria).every(([k, v]) => (r as any)[k] === v),
+            );
+          },
           async insert(row: unknown) {
-            (inserts[name] ??= []).push(row);
             const pk = name === "rounds" ? "id" : "pr_key";
+            // The rounds table has an AUTOINCREMENT id; mint one so find/update can key on it.
+            if (name === "rounds" && (row as any).id === undefined) {
+              (row as any).id = ++roundsId;
+            }
+            (inserts[name] ??= []).push(row);
             store.set((row as any)[pk], row);
             return 1;
           },
-          async update(key: string, patch: unknown) {
+          async update(key: string, patch: Record<string, unknown>) {
             (updates[name] ??= []).push({ key, patch });
+            const existing = store.get(key);
+            if (existing) store.set(key, { ...(existing as object), ...patch });
           },
         };
       },
@@ -39,7 +52,7 @@ function fakeApp() {
 }
 
 for (const status of ["addressed", "waiting"]) {
-  test(`persist-round records a '${status}' round and parks the PR in waiting_review`, async () => {
+  test(`persist-round records a '${status}' round and advances current_round without parking`, async () => {
     const { app, inserts, updates } = fakeApp();
     const job = { variables: { prKey: "o/r#1", round: 1, status, summary: `round was ${status}` } };
     await handler(job as any, app as any);
@@ -51,7 +64,11 @@ for (const status of ["addressed", "waiting"]) {
 
     assertEquals(updates.pull_requests!.length, 1, "the PR is updated once");
     const patch = (updates.pull_requests![0] as any).patch;
-    assertEquals(patch.status, "waiting_review", "the PR parks in waiting_review for the poller");
+    // The park into `waiting_review` is owned by pr.progress-check (the single writer of the
+    // post-round wait status), NOT persist-round — persist-round runs before the husk decision, so
+    // parking here would race the poller against a husk retry (#786). It only advances the round.
+    assertEquals(patch.status, undefined, "persist-round does NOT park the PR in waiting_review");
+    assertEquals(patch.waiting_since, undefined, "persist-round does NOT stamp the review-wait start");
     assertEquals(patch.current_round, 1);
   });
 }
@@ -97,9 +114,11 @@ test("persist-round heals a missing pull_requests parent before recording the ro
   assertEquals(healed.status, "converging", "the healed parent starts in the converging aggregate");
   assertEquals(healed.url, "https://github.com/o/r/pull/7", "URL is derived canonically");
   assertEquals(inserts.rounds.length, 1, "the round is still recorded after the heal");
-  // And the worker still parks the (now-present) PR in waiting_review as its final state.
+  // And the worker advances current_round on the (now-present) PR — but does NOT park it in
+  // waiting_review (that is pr.progress-check's job now, #786).
   assertEquals(updates.pull_requests!.length, 1, "the PR is updated once after the heal");
-  assertEquals((updates.pull_requests![0] as any).patch.status, "waiting_review");
+  assertEquals((updates.pull_requests![0] as any).patch.status, undefined, "no park in persist-round");
+  assertEquals((updates.pull_requests![0] as any).patch.current_round, 3);
 });
 
 // rather than writing a NULL status — the round history stays readable.
@@ -135,3 +154,151 @@ test("persist-round heals from the prKey when repo/prNumber are absent", async (
     "the running agent's abandon token is preserved from abandonUrl, not re-minted",
   );
 });
+
+// Idempotent round recording (issue #786): a husk auto-retry re-enters `review-round` WITHOUT
+// advancing the round counter, so pr.persist-round is reached again for the SAME (pr_key, round_no).
+// The `rounds` table has no UNIQUE(pr_key, round_no), so the worker must UPSERT — update the existing
+// row in place, never manufacture a duplicate history row that would corrupt the durable round
+// history the cockpit and the no-progress guard both read.
+test("persist-round is idempotent on (pr_key, round_no) — a retry updates, never duplicates", async () => {
+  const { app, inserts, updates } = fakeApp();
+  const first = { variables: { prKey: "o/r#1", round: 4, status: "addressed", summary: "first attempt" } };
+  await handler(first as any, app as any);
+  assertEquals(inserts.rounds.length, 1, "the first attempt inserts a round row");
+
+  // A husk retry: same round_no, a fresh summary/transcript.
+  const retry = { variables: { prKey: "o/r#1", round: 4, status: "addressed", summary: "retry attempt" } };
+  await handler(retry as any, app as any);
+  assertEquals(inserts.rounds.length, 1, "the retry does NOT insert a second round row");
+
+  const roundUpdate = (updates.rounds ?? []).at(-1) as any;
+  assertEquals(roundUpdate?.patch.summary, "retry attempt", "the retry updates the existing round in place");
+  assertEquals((inserts.rounds[0] as any).round_no, 4);
+});
+
+// Regression (issue #786): the idempotent upsert must reuse only a row THIS worker wrote — never an
+// escalation row. On a needs_input/blocked escalation, pr.persist-escalation records a `rounds` row
+// (status needs_input/blocked) for the SAME (pr_key, round_no); the human-answered resume re-enters
+// that same numeric round and lands here. Blindly updating the newest matching row would overwrite
+// the escalation row to `addressed`, ERASING the escalation attempt from the durable history. The
+// resume must INSERT a fresh row so both the escalation and its resolution survive.
+test("persist-round does NOT overwrite a same-round escalation row — it inserts the resumed attempt", async () => {
+  const { app, inserts, updates, rows } = fakeApp();
+  // Simulate pr.persist-escalation having recorded a needs_input round row for round 5.
+  const roundsStore = (rows.rounds ??= new Map());
+  roundsStore.set(101, {
+    id: 101,
+    pr_key: "o/r#1",
+    round_no: 5,
+    status: "needs_input",
+    summary: "escalated: which API shape?",
+    transcript: "escalation transcript",
+    started_at: "t0",
+    ended_at: "t0",
+  });
+
+  // The human answers; the same numeric round resumes and reaches persist-round as `addressed`.
+  const resume = { variables: { prKey: "o/r#1", round: 5, status: "addressed", summary: "resumed and pushed" } };
+  await handler(resume as any, app as any);
+
+  assertEquals(inserts.rounds.length, 1, "the resumed attempt inserts a NEW round row");
+  assertEquals((inserts.rounds[0] as any).status, "addressed", "the new row is the addressed resume");
+  // The escalation row is untouched — never updated to `addressed`.
+  const escalationTouched = (updates.rounds ?? []).some((u: any) => u.key === 101);
+  assertEquals(escalationTouched, false, "the needs_input escalation row is preserved, not overwritten");
+  assertEquals((roundsStore.get(101) as any).status, "needs_input", "the escalation row keeps its status");
+});
+
+// But a genuine husk retry (a prior pr.persist-round row, status addressed/waiting) is still reused
+// in place — only escalation rows are excluded, so idempotency for the retry path is preserved even
+// when an escalation row for the same round also exists.
+test("persist-round reuses a prior addressed round-record row while skipping an escalation row", async () => {
+  const { app, inserts, updates, rows } = fakeApp();
+  const roundsStore = (rows.rounds ??= new Map());
+  // An escalation row AND a prior persist-round row for the same round.
+  roundsStore.set(200, { id: 200, pr_key: "o/r#1", round_no: 6, status: "blocked", summary: "blocked earlier" });
+  roundsStore.set(201, { id: 201, pr_key: "o/r#1", round_no: 6, status: "addressed", summary: "first addressed" });
+
+  const retry = { variables: { prKey: "o/r#1", round: 6, status: "addressed", summary: "husk retry" } };
+  await handler(retry as any, app as any);
+
+  assertEquals(inserts.rounds.length, 0, "no new row — the prior addressed row is reused");
+  const roundUpdate = (updates.rounds ?? []).at(-1) as any;
+  assertEquals(roundUpdate?.key, 201, "the addressed round-record row is updated, not the blocked escalation row");
+  assertEquals(roundUpdate?.patch.summary, "husk retry");
+  assertEquals((roundsStore.get(200) as any).status, "blocked", "the escalation row is left intact");
+});
+
+// Regression (issue #786): the idempotent upsert must be scoped to the writing RUN, not inferred
+// from status. `submitPr` re-opens a previously converged/abandoned PR at round 1 WITHOUT deleting
+// `rounds` history, so a fresh convergence run (a NEW process instance) at round 1 finds the prior
+// run's `addressed`/`waiting`/`converged` round-1 row. Reusing it (its status is not human-hold)
+// would clobber another run's canonical summary/transcript/worker/timestamps. Scoping reuse by the
+// writing `process_instance_key` means the new run INSERTS a fresh row and the prior run's history
+// survives verbatim.
+test("persist-round scopes idempotency to the process instance — a resubmission inserts a fresh row", async () => {
+  const { app, inserts, updates, rows } = fakeApp();
+  const roundsStore = (rows.rounds ??= new Map());
+  // A prior run's round-1 row (its own process instance) with real history.
+  roundsStore.set(300, {
+    id: 300,
+    pr_key: "o/r#1",
+    round_no: 1,
+    status: "converged",
+    summary: "prior run summary",
+    transcript: "prior run transcript",
+    worker: "senior",
+    process_instance_key: "proc-OLD",
+    started_at: "t0",
+    ended_at: "t0",
+  });
+
+  // A resubmission: submitPr restarts convergence at round 1 in a NEW process instance.
+  const resubmit = {
+    processInstanceKey: "proc-NEW",
+    variables: { prKey: "o/r#1", round: 1, status: "addressed", summary: "fresh run" },
+  };
+  await handler(resubmit as any, app as any);
+
+  assertEquals(inserts.rounds.length, 1, "the resubmission inserts its OWN round row");
+  assertEquals((inserts.rounds[0] as any).process_instance_key, "proc-NEW", "the new row carries the new run's key");
+  const priorTouched = (updates.rounds ?? []).some((u: any) => u.key === 300);
+  assertEquals(priorTouched, false, "the prior run's round-1 row is never updated");
+  assertEquals((roundsStore.get(300) as any).summary, "prior run summary", "the prior run's history is intact");
+});
+
+// But a husk retry WITHIN the same run (same process instance key, same round_no) is still reused in
+// place — process-instance scoping preserves husk-retry idempotency, it does not disable it.
+test("persist-round reuses the same-process-instance row on a husk retry", async () => {
+  const { app, inserts, updates, rows } = fakeApp();
+  const roundsStore = (rows.rounds ??= new Map());
+  // This run's own round-4 row, plus an UNRELATED prior run's round-4 row.
+  roundsStore.set(400, {
+    id: 400,
+    pr_key: "o/r#1",
+    round_no: 4,
+    status: "addressed",
+    summary: "other run",
+    process_instance_key: "proc-OTHER",
+  });
+  roundsStore.set(401, {
+    id: 401,
+    pr_key: "o/r#1",
+    round_no: 4,
+    status: "addressed",
+    summary: "this run first attempt",
+    process_instance_key: "proc-THIS",
+  });
+
+  const retry = {
+    processInstanceKey: "proc-THIS",
+    variables: { prKey: "o/r#1", round: 4, status: "addressed", summary: "this run husk retry" },
+  };
+  await handler(retry as any, app as any);
+
+  assertEquals(inserts.rounds.length, 0, "no new row — this run's own row is reused");
+  const roundUpdate = (updates.rounds ?? []).at(-1) as any;
+  assertEquals(roundUpdate?.key, 401, "the reused row is THIS run's row, not the other run's");
+  assertEquals(roundUpdate?.patch.summary, "this run husk retry");
+  assertEquals((roundsStore.get(400) as any).summary, "other run", "the unrelated run's row is untouched");
+});

package/app/pullRequestReadModel.test.ts

@@ -33,7 +33,7 @@ import {
 const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
 const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
 
-const READ_MODEL_MIGRATION = "094_pull_requests_read_model.sql";
+const READ_MODEL_MIGRATION = "104_pull_requests_read_model_progress_idempotency.sql";
 
 // The real base `pull_requests` columns, in schema order — DERIVED from the migration chain (not a
 // hand-kept list that could silently omit one), used by both the drift guard and the e2e stand-in.