@nanobpm/nano-workforce 0.187.4 → 0.187.6

package/app/github.ts

@@ -23,6 +23,10 @@ export interface GhReview {
   id: number;
   state: string;
   submitted_at?: string;
+  /** The commit SHA the review was submitted against (GitHub's `commit_id`). Used to detect a
+   * review that predates the PR's current HEAD — a STALE review whose advisories are about code the
+   * head has since moved past (issue #799). Absent on data GitHub did not carry a `commit_id` for. */
+  commit_id?: string | null;
 }
 
 export type GithubTransport = "gh" | "token" | "auto";
@@ -61,7 +65,12 @@ function isGhAvailable(): Promise<boolean> {
 }
 
 /** Fetch the reviews for one PR via the configured transport. Throws on transport failure so
- * the caller can log-and-continue; returns `null` when no transport is usable (idle). */
+ * the caller can log-and-continue; returns `null` when no transport is usable (idle). Pages the
+ * FULL (oldest→newest) reviews list — the poller picks the newest fresh review by id, so reading
+ * only the first `per_page=100` page would, on a >100-review convergence loop, surface the OLDEST
+ * 100 and miss the genuinely newest review (repeatedly nudging while a current-head review sits on a
+ * later page, or classifying an old review as stale). This mirrors {@link fetchLatestCopilotReview}'s
+ * paging so both readers agree on which review is newest. */
 export async function fetchPrReviews(
   repo: string,
   number: number | string,
@@ -71,17 +80,43 @@ export async function fetchPrReviews(
   const useGh = mode === "gh" || (mode === "auto" && (await isGhAvailable()));
   const path = `repos/${repo}/pulls/${number}/reviews?per_page=100`;
   if (useGh) {
-    const out = await runGh(["api", path, "-H", "Accept: application/vnd.github+json"]);
+    // `--paginate --slurp` walks EVERY page of the (oldest→newest) reviews array, so a >100-review
+    // convergence loop still surfaces the genuinely newest review rather than the oldest 100. Plain
+    // `--paginate` concatenates one JSON array PER PAGE (multiple documents) which `JSON.parse`
+    // cannot read; `--slurp` wraps the pages in an outer array we flatten one level (mirrors
+    // {@link githubReleasesCommand}/{@link parseReleases}).
+    const out = await runGh([
+      "api", "--paginate", "--slurp", path, "-H", "Accept: application/vnd.github+json",
+    ]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    return JSON.parse(out) as GhReview[];
+    return (JSON.parse(out) as GhReview[][]).flat();
   }
   if (!token) return null; // token mode with no token → poller idles
-  const r = await fetch(`https://api.github.com/${path}`, {
-    headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
-  });
-  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
-  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  return (await r.json()) as GhReview[];
+  // Page the token transport the same way; 20×100 reviews is far past any real convergence loop, and
+  // a genuinely deeper history we can't reach is unverifiable → fail CLOSED (throw) rather than
+  // return a partial list the poller would treat as complete (selecting an older review, re-nudging).
+  const reviews: GhReview[] = [];
+  const MAX_PAGES = 20;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const r = await fetch(`https://api.github.com/${path}&page=${page}`, {
+      headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+    });
+    if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const batch = (await r.json()) as GhReview[];
+    reviews.push(...batch);
+    // A short final page means we've read every review — the list is complete.
+    if (batch.length < 100) return reviews;
+    // A full page on the last allowed page is only truncated if GitHub says there's more; trust the
+    // `Link` header's `rel="next"` (mirrors {@link fetchPrFiles}) so an exact multiple of 100 isn't a
+    // false positive, and throw when the cap genuinely truncates rather than under-reading history.
+    if (page === MAX_PAGES && /<[^>]*>;\s*rel="next"/.test(r.headers.get("link") ?? "")) {
+      throw new Error(
+        `github pr reviews truncated: ${repo}#${number} exceeds ${MAX_PAGES * 100}-review paging cap`,
+      );
+    }
+  }
+  return reviews;
 }
 
 // ── Review-comment convergence gate (don't converge with unaddressed comments) ──────────────
@@ -279,36 +314,73 @@ export function pickLatestCopilotReviewBody(
   reviews: { user?: { login?: string }; body?: string }[],
   truncated: boolean,
 ): string | null {
+  const picked = pickLatestCopilotReview(reviews, truncated);
+  return picked === null ? null : picked.body;
+}
+
+/** Pick the newest Copilot review — body AND the commit SHA it was submitted against — from a
+ * reviews list (GitHub returns them oldest→newest). Semantics mirror {@link pickLatestCopilotReviewBody}
+ * exactly: `truncated = true` fails CLOSED (`null`, unverifiable); a verified-complete read with no
+ * Copilot review returns `{ body: "", commitId: null }` (a verified "no advisories"). The `commitId`
+ * lets a caller detect a review that predates the PR's current HEAD — a STALE review whose advisories
+ * are about code the head has since moved past (issue #799). Pure; unit-tested. */
+export function pickLatestCopilotReview(
+  reviews: { user?: { login?: string }; body?: string; commit_id?: string | null }[],
+  truncated: boolean,
+): { body: string; commitId: string | null } | null {
   if (truncated) return null;
   const copilot = reviews.filter((rv) => isCopilot(rv.user?.login));
-  return copilot[copilot.length - 1]?.body ?? "";
+  const latest = copilot[copilot.length - 1];
+  return { body: latest?.body ?? "", commitId: latest?.commit_id ?? null };
 }
 
 /** Fetch the latest Copilot review body for a PR (the newest review authored by the automated
  * Copilot reviewer). Returns `null` ONLY when no transport is usable (unverifiable → the worker
  * fails closed); returns `""` when transport is usable but the PR has no Copilot review yet (a
  * verified "no suppressed advisories"). Throws on a genuine transport failure. This split keeps
- * `null` from conflating "unverifiable" with "empty" and fail-OPENing the advisory dimension. */
+ * `null` from conflating "unverifiable" with "empty" and fail-OPENing the advisory dimension.
+ * Thin wrapper over {@link fetchLatestCopilotReview} (the single fetch implementation). */
 export async function fetchLatestCopilotReviewBody(
   repo: string,
   number: number | string,
   token: string,
 ): Promise<string | null> {
+  const picked = await fetchLatestCopilotReview(repo, number, token);
+  return picked === null ? null : picked.body;
+}
+
+/** Fetch the latest Copilot review — body AND the commit SHA it was submitted against — for a PR.
+ * Same null/`""`-vs-unverifiable semantics as {@link fetchLatestCopilotReviewBody} (which delegates
+ * here): `null` ONLY when no transport is usable (unverifiable → fail closed); a verified read with
+ * no Copilot review yet returns `{ body: "", commitId: null }`. The `commitId` lets the convergence
+ * gate detect a review that predates the PR's current HEAD — a STALE review whose advisories are
+ * about code the head has since moved past (issue #799) — and re-solicit a fresh review rather than
+ * block/escalate against the obsolete body. Throws on a genuine transport failure. */
+export async function fetchLatestCopilotReview(
+  repo: string,
+  number: number | string,
+  token: string,
+): Promise<{ body: string; commitId: string | null } | null> {
   const mode = githubTransport();
   const useGh = mode === "gh" || (mode === "auto" && (await isGhAvailable()));
   const basePath = `repos/${repo}/pulls/${number}/reviews?per_page=100`;
   interface Review {
     user?: { login?: string };
     body?: string;
+    commit_id?: string | null;
   }
   if (useGh) {
-    // `--paginate` merges EVERY page of the (oldest→newest) reviews array, so a >100-review
+    // `--paginate --slurp` walks EVERY page of the (oldest→newest) reviews array, so a >100-review
     // convergence loop still surfaces the genuinely newest Copilot review rather than the oldest
-    // 100 — reading only the first page here would fail-OPEN the advisory dimension.
-    const out = await runGh(["api", "--paginate", basePath, "-H", "Accept: application/vnd.github+json"]);
+    // 100 — reading only the first page here would fail-OPEN the advisory dimension. Plain
+    // `--paginate` concatenates one JSON array PER PAGE (multiple documents) which `JSON.parse`
+    // cannot read; `--slurp` wraps the pages in an outer array we flatten one level.
+    const out = await runGh([
+      "api", "--paginate", "--slurp", basePath, "-H", "Accept: application/vnd.github+json",
+    ]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const reviews = JSON.parse(out) as Review[];
-    return pickLatestCopilotReviewBody(reviews, false);
+    const reviews = (JSON.parse(out) as Review[][]).flat();
+    return pickLatestCopilotReview(reviews, false);
   }
   if (!token) return null;
   // Page the token transport the same way; 20×100 reviews is far past any real convergence loop, and
@@ -324,14 +396,14 @@ export async function fetchLatestCopilotReviewBody(
     const batch = (await r.json()) as Review[];
     reviews.push(...batch);
     // A short page means we've read every review — the list is complete.
-    if (batch.length < 100) return pickLatestCopilotReviewBody(reviews, false);
+    if (batch.length < 100) return pickLatestCopilotReview(reviews, false);
     // A full page on the last allowed page is only truncated if GitHub says there's more; trust the
     // `Link` header's `rel="next"` so an exact multiple of 100 isn't a false positive.
     if (page === MAX_PAGES && /<[^>]*>;\s*rel="next"/.test(r.headers.get("link") ?? "")) {
-      return pickLatestCopilotReviewBody(reviews, true);
+      return pickLatestCopilotReview(reviews, true);
     }
   }
-  return pickLatestCopilotReviewBody(reviews, false);
+  return pickLatestCopilotReview(reviews, false);
 }
 
 /** Raw GraphQL response shape for the review-threads query. */
@@ -1067,17 +1139,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 +1165,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 +1584,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");
+});