@nanobpm/nano-workforce 0.191.1 → 0.193.0

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, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, type GhReview, type Mergeability, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, compareCommits, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, updateBranchRef, type GhReview, 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]`
@@ -956,3 +956,225 @@ test("fetchBranchHead: percent-encodes a special-character branch ref (preservin
   );
   assertEquals(sha, "cafef00d");
 });
+
+// ── No-advance self-heal transports (issue #818) ────────────────────────────
+// The self-heal's compare (`compareCommits`) and NON-force ref move (`updateBranchRef`) are
+// safety-critical: a regression in the ahead/behind parsing or the `force:false` / 422-refusal
+// handling silently changes whether a recovery mutates a PR head. These pin the token transport of
+// both — a request-capturing fetch stub so the method/body/path and the refusal branch are covered.
+async function withCapturingFetch<T>(
+  serve: (req: { path: string; method: string; body: unknown }) => { status: number; statusText?: string; 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, init?: RequestInit): Promise<Response> => {
+    const path = new URL(String(url)).pathname.replace(/^\/repos\//, "");
+    const method = (init?.method ?? "GET").toUpperCase();
+    const body = typeof init?.body === "string" ? JSON.parse(init.body) : undefined;
+    const { status, statusText, body: resp } = serve({ path, method, body });
+    return Promise.resolve(new Response(JSON.stringify(resp), { status, statusText }));
+  }) 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("compareCommits: parses an 'ahead' fast-forward response and encodes the compare refs", async () => {
+  const cmp = await withCapturingFetch(
+    ({ path, method }) => {
+      assertEquals(method, "GET");
+      // Each ref segment is percent-encoded (`#` → %23) around the compare API's own `...` separator.
+      assertEquals(path, "o/r/compare/feat/x%23123...deadbeef");
+      return { status: 200, body: { status: "ahead", ahead_by: 3, behind_by: 0 } };
+    },
+    () => compareCommits("o/r", "feat/x#123", "deadbeef", "tok"),
+  );
+  assertEquals(cmp, { status: "ahead", aheadBy: 3, behindBy: 0 });
+});
+
+test("compareCommits: coerces an unknown status to 'diverged' and defaults missing counts to 0", async () => {
+  const cmp = await withCapturingFetch(
+    () => ({ status: 200, body: { status: "wat" } }),
+    () => compareCommits("o/r", "base", "head", "tok"),
+  );
+  assertEquals(cmp, { status: "diverged", aheadBy: 0, behindBy: 0 });
+});
+
+// Reject COERCED/UNSAFE compare counts at the transport boundary (Copilot review of #819). A bare
+// `Number(...)` would turn a malformed/tampered response into a spurious ancestry proof — a string
+// `"1"` or boolean `true` coerces to `1`, and an unsafe magnitude passes `Number.isInteger` — either
+// of which could fast-forward the ref WITHOUT a genuine GitHub proof. A present count must be a real,
+// non-negative SAFE integer number; anything else throws so the self-heal escalates rather than heals.
+test("compareCommits: rejects a string-coerced count (throws, never a spurious integer proof)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: "1", behind_by: 0 } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid ahead_by",
+  );
+});
+
+test("compareCommits: rejects a boolean-coerced count", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: 1, behind_by: true } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid behind_by",
+  );
+});
+
+test("compareCommits: rejects an unsafe-magnitude integer count (passes Number.isInteger but is not a safe integer)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: 1e21, behind_by: 0 } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid ahead_by",
+  );
+});
+
+test("compareCommits: rejects a negative count", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: -3, behind_by: 0 } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid ahead_by",
+  );
+});
+
+test("compareCommits: no token → null (idle transport, never a throw)", async () => {
+  const cmp = await withCapturingFetch(
+    () => {
+      throw new Error("fetch must not be called without a token");
+    },
+    () => compareCommits("o/r", "base", "head", ""),
+  );
+  assertEquals(cmp, null);
+});
+
+test("compareCommits: a non-2xx transport response throws (an outage is not a silent 'diverged')", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 500, statusText: "Server Error", body: {} }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "500",
+  );
+});
+
+test("updateBranchRef: a successful fast-forward PATCHes force:false and returns true", async () => {
+  let seen: { path: string; method: string; body: unknown } | undefined;
+  const moved = await withCapturingFetch(
+    (req) => {
+      seen = req;
+      return { status: 200, body: { ref: "refs/heads/feat/x", object: { sha: "deadbeef" } } };
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok"),
+  );
+  assertEquals(moved, true);
+  assertEquals(seen?.method, "PATCH", "the ref move is a PATCH");
+  assertEquals(seen?.path, "o/r/git/refs/heads/feat/x", "targeting the head ref");
+  // The whole point of the self-heal transport: it NEVER force-updates — GitHub must be free to
+  // refuse a non-fast-forward. A regression flipping this to force:true would rewrite history.
+  assertEquals(seen?.body, { sha: "deadbeef", force: false });
+});
+
+test("updateBranchRef: GitHub's 422 non-fast-forward refusal returns false, never throws", async () => {
+  const moved = await withCapturingFetch(
+    () => ({ status: 422, statusText: "Unprocessable Entity", body: { message: "Update is not a fast forward" } }),
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok"),
+  );
+  assertEquals(moved, false, "a refused non-fast-forward is a safe false (→ the caller escalates)");
+});
+
+test("updateBranchRef: a non-422 transport error throws (a real outage is not a silent refusal)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 500, statusText: "Server Error", body: { message: "boom" } }),
+        () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok"),
+      ),
+    Error,
+    "500",
+  );
+});
+
+test("updateBranchRef: no token in token mode throws (no usable transport to move the ref)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => {
+          throw new Error("fetch must not be called without a token");
+        },
+        () => updateBranchRef("o/r", "feat/x", "deadbeef", ""),
+      ),
+    Error,
+    "no GitHub transport available",
+  );
+});
+
+// ── updateBranchRef compare-and-swap (Copilot review on #819) ────────────────
+// When `expectedSha` is given the move is a CAS on the ref's prior value: read the ref right before
+// the PATCH and refuse unless it still equals the validated base, so a head advanced/replaced by a
+// concurrent (superseded) run after the caller's fast-forward proof is never PATCHed.
+test("updateBranchRef: CAS advances when the ref still equals expectedSha (reads then PATCHes)", async () => {
+  const seen: string[] = [];
+  const moved = await withCapturingFetch(
+    (req) => {
+      seen.push(`${req.method} ${req.path}`);
+      if (req.method === "GET") return { status: 200, body: { object: { sha: "basebase" } } };
+      return { status: 200, body: { ref: "refs/heads/feat/x", object: { sha: "deadbeef" } } };
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok", "basebase"),
+  );
+  assertEquals(moved, true, "the ref still pointed at the validated base, so the fast-forward applied");
+  assertEquals(
+    seen,
+    ["GET o/r/git/ref/heads/feat/x", "PATCH o/r/git/refs/heads/feat/x"],
+    "the CAS reads the ref before mutating it",
+  );
+});
+
+test("updateBranchRef: CAS refuses (false, no PATCH) when the ref has moved off expectedSha", async () => {
+  const methods: string[] = [];
+  const moved = await withCapturingFetch(
+    (req) => {
+      methods.push(req.method);
+      if (req.method === "GET") return { status: 200, body: { object: { sha: "movedmoved" } } };
+      throw new Error("must not PATCH once the compare-and-swap has lost");
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok", "basebase"),
+  );
+  assertEquals(moved, false, "a ref moved off the validated base refuses the move (→ the caller escalates)");
+  assertEquals(methods, ["GET"], "a lost CAS never issues the PATCH");
+});
+
+test("updateBranchRef: CAS refuses (false) when the ref is absent/unreadable (null)", async () => {
+  const moved = await withCapturingFetch(
+    (req) => {
+      if (req.method === "GET") return { status: 404, statusText: "Not Found", body: { message: "Not Found" } };
+      throw new Error("must not PATCH when the base ref is gone");
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok", "basebase"),
+  );
+  assertEquals(moved, false, "a deleted/unreadable base ref is not the validated state, so the move is refused");
+});

package/app/github.ts

@@ -1658,6 +1658,128 @@ async function branchHeadSha(repo: string, branch: string, token: string): Promi
   return j.object?.sha ?? null;
 }
 
+/** The ancestry relationship between two commits on `repo`, from GitHub's compare endpoint
+ * (`compare/<base>...<head>`). `status` is GitHub's verdict — `"ahead"` (head strictly descends
+ * base — a fast-forward from base to head is possible), `"behind"`, `"identical"`, or `"diverged"` —
+ * and `aheadBy`/`behindBy` are the commit counts either side of the merge-base. The no-advance
+ * self-heal (#818) uses this to prove a recorded push-checkpoint SHA is a *strict fast-forward*
+ * descendant of the PR head (`status === "ahead"`, `behindBy === 0`, `aheadBy > 0`) before it moves
+ * the head — a diverged/behind checkpoint is NOT safe to fast-forward onto and must escalate instead.
+ * `null` when no transport is usable (idle); throws only on a genuine transport failure. */
+export interface CommitComparison {
+  readonly status: "ahead" | "behind" | "identical" | "diverged";
+  readonly aheadBy: number;
+  readonly behindBy: number;
+}
+
+export async function compareCommits(
+  repo: string,
+  base: string,
+  head: string,
+  token: string,
+): Promise<CommitComparison | null> {
+  // Encode each ref/SHA so a branch name containing git-legal-but-URL-significant characters
+  // (`#`, `?`, spaces) can't truncate the path (same hazard branchHeadSha guards). The `...`
+  // three-dot separator between the two encoded refs is the compare API's own syntax, not a ref char.
+  const enc = (r: string) => r.split("/").map(encodeURIComponent).join("/");
+  const apiPath = `repos/${repo}/compare/${enc(base)}...${enc(head)}`;
+  const parse = (body: string): CommitComparison => {
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const j = JSON.parse(body) as { status?: unknown; ahead_by?: unknown; behind_by?: unknown };
+    const status = j.status === "ahead" || j.status === "behind" || j.status === "identical" || j.status === "diverged" ? j.status : "diverged";
+    // Validate the commit counts at THIS transport boundary rather than lean on the downstream
+    // `Number.isInteger` gate (Copilot review of #819). A bare `Number(j.ahead_by ?? 0)` silently
+    // COERCES a malformed value into a spurious ancestry proof: `Number("1")`/`Number(true)` === `1`,
+    // and `Number.isInteger(1e21)` is `true` for an unsafe magnitude — any of which would pass the
+    // self-heal's `Number.isInteger`/`aheadBy > 0` fast-forward check and PATCH the ref WITHOUT a
+    // genuine GitHub ancestry proof. A MISSING count is a legitimate zero (GitHub omits it), but a
+    // PRESENT value must be a real, non-negative SAFE integer NUMBER; anything else (string, boolean,
+    // float, unsafe magnitude) is a corrupt/tampered response we reject by throwing — `compareCommits`
+    // fails, the self-heal's `catch` degrades to `{ healed: false }`, and the round escalates instead
+    // of fast-forwarding on unproven data.
+    const count = (v: unknown, field: string): number => {
+      if (v === undefined || v === null) return 0;
+      if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0) {
+        throw new Error(`github compare returned an invalid ${field}: ${JSON.stringify(v)}`);
+      }
+      return v;
+    };
+    return { status, aheadBy: count(j.ahead_by, "ahead_by"), behindBy: count(j.behind_by, "behind_by") };
+  };
+  if (await useGh()) {
+    const out = await runGh(["api", apiPath, "-H", "Accept: application/vnd.github+json"]);
+    return parse(out);
+  }
+  if (!token) return null;
+  const r = await fetch(`https://api.github.com/${apiPath}`, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json" },
+  });
+  if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
+  return parse(await r.text());
+}
+
+/** Fast-forward `refs/heads/<branch>` on `repo` to `sha` (a NON-force ref update — GitHub itself
+ * rejects a non-fast-forward with `422`, a hard backstop beneath the caller's own compare check).
+ * Returns `true` when the ref now points at `sha`, `false` when GitHub refused the move as
+ * non-fast-forward (`422`) — or, when `expectedSha` is given, when the ref no longer points at it
+ * (the compare-and-swap below lost). The no-advance self-heal (#818) uses this to advance a PR head
+ * onto a reachable push-checkpoint SHA that the harness pushed but left off the head. `force` is
+ * never set: the whole point is to move the head ONLY when it is a safe fast-forward, never to
+ * rewrite history.
+ *
+ * `expectedSha` (optional) makes the move a COMPARE-AND-SWAP on the ref's prior value: read the ref
+ * immediately before the PATCH and refuse (`false`) unless it still equals `expectedSha`. The
+ * self-heal passes the exact head SHA its fast-forward proof was computed against (`currentHead`), so
+ * the mutation's precondition is BOUND TO the validated state instead of being trusted from a
+ * separate, earlier ownership read (Copilot review on #819): if a concurrent run advanced/replaced
+ * the head after the proof — a superseded straggler that raced past the late `stillOwns()` guard, or
+ * any other writer — the ref no longer equals `expectedSha` and the straggler PATCHes nothing.
+ * GitHub's ref API exposes no server-side expected-old-value precondition, so this read-verify is the
+ * tightest fence the platform allows; combined with the non-force fast-forward invariant (the head
+ * can only ever move FORWARD, never rewrite) the residual window is bounded and fail-safe. */
+export async function updateBranchRef(
+  repo: string,
+  branch: string,
+  sha: string,
+  token: string,
+  expectedSha?: string,
+): Promise<boolean> {
+  const encodedBranch = branch.split("/").map(encodeURIComponent).join("/");
+  const apiPath = `repos/${repo}/git/refs/heads/${encodedBranch}`;
+  const isNonFastForward = (msg: string) => /\b422\b|not a fast forward|fast[- ]forward/i.test(msg);
+  // COMPARE-AND-SWAP precondition: refuse the move unless the ref still points at the SHA the caller
+  // validated against. Read as late as possible (right before the PATCH) so the window between the
+  // check and the mutation is minimal; a mismatch (or an unreadable/deleted ref → `null`) means the
+  // validated base is gone, so the move is refused rather than applied against unproven state.
+  if (expectedSha !== undefined) {
+    const current = await branchHeadSha(repo, branch, token);
+    if (current !== expectedSha) return false;
+  }
+  if (await useGh()) {
+    try {
+      await runGh(["api", apiPath, "-X", "PATCH", "-f", `sha=${sha}`, "-F", "force=false"]);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isNonFastForward(msg)) return false;
+      throw err;
+    }
+    return true;
+  }
+  if (!token) throw new Error(`no GitHub transport available to update ${apiPath}`);
+  const r = await fetch(`https://api.github.com/${apiPath}`, {
+    method: "PATCH",
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: "application/vnd.github+json",
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({ sha, force: false }),
+  });
+  if (r.ok) return true;
+  if (r.status === 422) return false; // non-fast-forward — refused, as intended
+  throw new Error(`github ${r.status} ${r.statusText}: ${(await r.text()).slice(0, 300)}`.trim());
+}
+
 /** Create `refs/heads/<branch>` pointing at `sha`. Idempotent: a concurrent create / re-plan
  * that already made the ref (GitHub `422 Reference already exists`) is treated as a no-op.
  * Returns `true` when this call actually created the ref, `false` when it lost the race and the

package/app/roundProgress.test.ts

@@ -185,6 +185,7 @@ function fakeApp(
     // exercises the AVAILABILITY-AWARE default reader unless it injects its own readAgentWork or a
     // non-empty instance list.
     engine: { searchAgentInstances },
+    log: { info() {}, warn() {}, error() {}, debug() {} },
     data: {
       table(_name: string, _key: string) {
         return {
@@ -211,9 +212,23 @@ async function makeUnderTest(
     round: number,
     priorWatermark?: string | null,
   ) => Promise<boolean | null | { work: boolean | null; consumedKey?: string | null }>,
+  selfHeal?: (
+    app: unknown,
+    repo: string,
+    prNumber: number,
+    prKey: string,
+    currentHead: string,
+    roundNo: number,
+    processKey: string | null,
+    stillOwns: () => Promise<boolean>,
+  ) => Promise<{ healed: boolean; sha?: string; reason?: string }>,
 ) {
   const { makeHandler } = await import("../workers/progress-check/worker.ts");
-  return makeHandler(readAgentWork ? { readHead, readAgentWork } : { readHead });
+  // Default the self-heal OFF (always `{ healed: false }`) so the existing escalation tests keep
+  // escalating without touching the real WorldStore/GitHub deps; the #818 tests inject a healing stub.
+  const heal = selfHeal ?? (async () => ({ healed: false }));
+  // biome-ignore lint/suspicious/noExplicitAny: test double for the injectable worker deps.
+  return makeHandler({ readHead, ...(readAgentWork ? { readAgentWork } : {}), selfHeal: heal as any });
 }
 
 test("progress-check: a non-addressed round records the baseline and consumes the attempt watermark but never escalates", async () => {
@@ -312,6 +327,98 @@ test("progress-check: an unchanged head with a terminal agent-instance escalates
   assertStringIncludes(String(out.noProgressQuestion), "PR head did not advance");
 });
 
+test("progress-check: a no-advance round self-heals to a reachable push-checkpoint and continues instead of escalating (#818)", async () => {
+  // The head did NOT advance and the agent-instance corroborates a real no-advance (terminal
+  // instance) — normally an immediate escalation. But a recorded push-checkpoint fast-forward-
+  // descends the head (a producer harness pushed the fix to a fallback branch, off the PR head), so
+  // the self-heal advances the head onto it and the loop continues as real progress.
+  let healArgs: unknown[] = [];
+  let healStillOwns: (() => Promise<boolean>) | null = null;
+  const handler = await makeUnderTest(
+    async () => "sha-1",
+    async () => true,
+    async (_app, repo, prNumber, prKey, currentHead, roundNo, processKey, stillOwns) => {
+      healArgs = [repo, prNumber, prKey, currentHead, roundNo, processKey];
+      healStillOwns = stillOwns;
+      return { healed: true, sha: "healed-sha" };
+    },
+  );
+  const { app, updates } = fakeApp({ last_round_head: "sha-1", process_key: "pik" });
+  const out = await handler(
+    { processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 3, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(out, { progressed: true, huskRetries: 0 }, "a healed round continues as real progress");
+  assertEquals(
+    healArgs,
+    ["o/r", 1, "o/r#1", "sha-1", 3, "pik"],
+    "self-heal is called with the repo/number/prKey, the current head as compare base, the round, and THIS run's process key (#819)",
+  );
+  assertEquals(typeof healStillOwns, "function", "a late ownership guard is threaded into the heal (#819)");
+  assertEquals(await (healStillOwns as unknown as () => Promise<boolean>)(), true, "the owning run's guard reports ownership");
+  // The healed head becomes the new baseline and the round parks at wait-review (one atomic write).
+  assertEquals(updates.length, 1, "the healed head is rebaselined and parked in one atomic write");
+  assertEquals(updates[0]!.patch.last_round_head, "healed-sha", "the baseline advances to the healed head");
+  assertEquals(updates[0]!.patch.status, "waiting_review", "a healed round parks for the next review");
+});
+
+test("progress-check: self-heal is NOT attempted on a progressed round (only before an escalation)", async () => {
+  let healCalls = 0;
+  const handler = await makeUnderTest(
+    async () => "sha-2", // head advanced → progressed, no escalation
+    undefined,
+    async () => (healCalls++, { healed: true, sha: "x" }),
+  );
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler(
+    { processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 2 } } as any,
+    app as any,
+  );
+  assertEquals(out.progressed, true);
+  assertEquals(healCalls, 0, "a genuinely-progressing round never consults the self-heal");
+});
+
+test("progress-check: a no-advance round with no recoverable checkpoint still escalates (#818)", async () => {
+  // The self-heal declines (no reachable fast-forward checkpoint) → the round escalates exactly as
+  // before the self-heal existed.
+  const handler = await makeUnderTest(
+    async () => "sha-1",
+    async () => true,
+    async () => ({ healed: false, reason: "no-checkpoint" }),
+  );
+  const { app } = fakeApp({ last_round_head: "sha-1" });
+  const out = await handler(
+    { processInstanceKey: "pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 3, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(out.progressed, false, "an unrecoverable no-advance still escalates");
+  assertEquals(out.noProgressReason, "no-advance");
+  assertStringIncludes(String(out.noProgressQuestion), "PR head did not advance");
+});
+
+test("progress-check: a SUPERSEDED straggler never invokes the self-heal — no stale ref mutation on a reopened PR (#818 fence)", async () => {
+  // A delayed progress-check from an OLD convergence instance can reach the no-advance branch after
+  // `submitPr` reopened the PR under a NEW `process_key`. The commit fence already drops its DB write,
+  // but the self-heal PATCHes the GitHub head — an irreversible side effect. So the worker must
+  // re-check ownership BEFORE the ref mutation and skip the heal entirely when superseded, else a
+  // straggler's stale checkpoint resurrects old work on the reopened PR.
+  let healCalls = 0;
+  const handler = await makeUnderTest(
+    async () => "sha-1",
+    async () => true,
+    async () => (healCalls++, { healed: true, sha: "stale-sha" }),
+  );
+  // The row is owned by a DIFFERENT (newer) instance than this straggler job's processInstanceKey.
+  const { app, updates } = fakeApp({ last_round_head: "sha-1", process_key: "new-pik" });
+  const out = await handler(
+    { processInstanceKey: "old-pik", variables: { prKey: "o/r#1", status: "addressed", repo: "o/r", prNumber: 1, round: 3, huskRetries: 0 } } as any,
+    app as any,
+  );
+  assertEquals(healCalls, 0, "a superseded straggler must NOT mutate the GitHub head via self-heal");
+  assertEquals(updates.length, 0, "and the commit fence drops its DB write too (ack without persisting)");
+  assertEquals(out.progressed, false, "the straggler still returns its escalation verdict to ack the job");
+});
+
 test("progress-check: an addressed round whose head advanced reports progressed:true and rebaselines", async () => {
   const handler = await makeUnderTest(async () => "sha-2");
   const { app, updates } = fakeApp({ last_round_head: "sha-1" });

package/app/service.test.ts

@@ -338,7 +338,136 @@ test("re-submit advances process_key BEFORE resetting adjudications (fence order
   });
 });
 
-// Red/green regression (Copilot review): the durable adjudication RESET runs AFTER the new instance is
+// Red/green regression (Copilot review of #819): the reopen must publish the fresh run's identity
+// (`process_key`) in the SAME write that flips the row to `converging`/round 1. If the status flip
+// landed while `process_key` still named the OLD instance, a delayed old-run `pr.progress-check`
+// straggler would read its own key as the current owner, pass `isSuperseded`/`stillOwns`, and
+// fast-forward the PR head onto its stale checkpoint under the fresh run's identity. Asserting the
+// atomic write closes that "converging-but-old-owner" window.
+test("re-submit flips status to converging and advances process_key in the SAME write (no old-owner window, #819)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#42";
+    const patches: Array<Record<string, unknown>> = [];
+    const stores: Record<string, { rows: any[]; key: string }> = {
+      pull_requests: {
+        rows: [{ pr_key: PR_KEY, repo: "owner/repo", number: 42, url: "https://github.com/owner/repo/pull/42", title: "t", status: "converged", process_key: "PI-OLD" }],
+        key: "pr_key",
+      },
+      escalations: { rows: [], key: "id" },
+      pr_adjudications: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    };
+    const wrap = (name: string, key: string) => {
+      const t = memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key);
+      return {
+        ...t,
+        update: (k: any, patch: any) => {
+          if (name === "pull_requests") patches.push({ ...patch });
+          return t.update(k, patch);
+        },
+      };
+    };
+    const data = { table: withTrackingViews(wrap), open: () => memOpen(stores) } as any;
+    const engine = { createInstance: () => Promise.resolve({ processInstanceKey: "PI-NEW" }) } as any;
+
+    await submitPr(data, engine, { repo: "owner/repo", number: 42, url: "https://github.com/owner/repo/pull/42", prKey: PR_KEY });
+
+    // No update may set status to "converging" while leaving process_key at (or below) the old key.
+    const convergingPatch = patches.find((p) => p.status === "converging");
+    assertEquals(convergingPatch !== undefined, true, "the reopen flips the row to converging");
+    assertEquals(convergingPatch?.process_key, "PI-NEW", "the SAME write that flips to converging advances the owner to the new run");
+    assertEquals(
+      patches.some((p) => p.status === "converging" && p.process_key === "PI-OLD"),
+      false,
+      "the row never presents as the fresh run while still owned by the old instance",
+    );
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.status, "converging");
+    assertEquals(pr.current_round, 1);
+    assertEquals(pr.process_key, "PI-NEW");
+  });
+});
+
+// Red/green regression (Copilot review of #819, follow-up): deferring the terminal→`converging`
+// transition until AFTER `createInstance()` (the atomic-reopen fix above) left the row in its OLD
+// terminal shape across the create await. A second `submitPr` for the same PR racing that await would
+// read the still-terminal row, pass the RESUBMITTABLE idempotency gate, and create a SECOND
+// convergence instance for one PR. `submitPr` serializes its create→reopen critical section per
+// `prKey`, so the loser observes the winner's claim (`converging` + the new key, derived-active) and
+// returns `alreadyRunning` — exactly one instance is created. Without the lock both concurrent calls
+// enter `createInstance` (calls === 2) and this fails.
+test("concurrent submitPr for one reopened PR mints only ONE convergence instance (#819 follow-up)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#42";
+    const stores: Record<string, { rows: any[]; key: string }> = {
+      pull_requests: {
+        rows: [{ pr_key: PR_KEY, repo: "owner/repo", number: 42, url: "https://github.com/owner/repo/pull/42", title: "t", status: "converged", current_round: 3, process_key: "PI-OLD" }],
+        key: "pr_key",
+      },
+      escalations: { rows: [], key: "id" },
+      pr_adjudications: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    };
+    const data = { table: withTrackingViews((name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)), open: () => memOpen(stores) } as any;
+    let calls = 0;
+    const engine = {
+      createInstance: async () => {
+        const id = ++calls;
+        // Hold the critical section open long enough for a racing submit to interleave at this await.
+        await new Promise((r) => setTimeout(r, 5));
+        return { processInstanceKey: `PI-${id}` };
+      },
+    } as any;
+    const parsed = { repo: "owner/repo", number: 42, url: "https://github.com/owner/repo/pull/42", prKey: PR_KEY };
+
+    const results = await Promise.all([submitPr(data, engine, parsed), submitPr(data, engine, parsed)]);
+
+    assertEquals(calls, 1, "concurrent submits of the same PR create exactly one convergence instance");
+    assertEquals(
+      results.filter((r: any) => r.alreadyRunning === true).length,
+      1,
+      "the second concurrent submit observes the first's claim and short-circuits at the alreadyRunning gate",
+    );
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.status, "converging");
+    assertEquals(pr.process_key, "PI-1", "the single created instance owns the reopened row");
+  });
+});
+
+// A distinct key must never block another PR's submit — the per-`prKey` lock serializes only same-PR
+// calls, so two DIFFERENT PRs submitted concurrently both proceed and each mints its own instance.
+test("submitPr serialization is per-prKey — different PRs never block each other (#819 follow-up)", async () => {
+  await withGithubOff(async () => {
+    const mkStores = (n: number): Record<string, { rows: any[]; key: string }> => ({
+      pull_requests: { rows: [{ pr_key: `owner/repo#${n}`, repo: "owner/repo", number: n, url: `https://github.com/owner/repo/pull/${n}`, title: "t", status: "converged", current_round: 1, process_key: `PI-OLD-${n}` }], key: "pr_key" },
+      escalations: { rows: [], key: "id" },
+      pr_adjudications: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    });
+    const s1 = mkStores(1);
+    const s2 = mkStores(2);
+    const mkData = (s: Record<string, { rows: any[]; key: string }>) => ({ table: withTrackingViews((name: string, key: string) => memTable(s[name]?.rows ?? [], s[name]?.key ?? key)), open: () => memOpen(s) } as any);
+    let calls = 0;
+    const engine = {
+      createInstance: async () => {
+        const id = ++calls;
+        await new Promise((r) => setTimeout(r, 5));
+        return { processInstanceKey: `PI-${id}` };
+      },
+    } as any;
+
+    await Promise.all([
+      submitPr(mkData(s1), engine, { repo: "owner/repo", number: 1, url: "https://github.com/owner/repo/pull/1", prKey: "owner/repo#1" }),
+      submitPr(mkData(s2), engine, { repo: "owner/repo", number: 2, url: "https://github.com/owner/repo/pull/2", prKey: "owner/repo#2" }),
+    ]);
+
+    assertEquals(calls, 2, "two different PRs each mint their own convergence instance");
+    assertEquals(s1.pull_requests.rows[0].status, "converging");
+    assertEquals(s2.pull_requests.rows[0].status, "converging");
+  });
+});
+
+
 // created and `process_key` is advanced. If the reset DELETE fails, the new convergence instance is
 // already live while the OLD adjudications remain — and because the new instance is ACTIVE the
 // `alreadyRunning` idempotency gate short-circuits every retry, so the reset is never re-run and the
@@ -1024,7 +1153,7 @@ test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#
 // so the round redrives from scratch (exactly as today). Proven against a REAL in-memory SQLite db
 // with the world (049) + enrolment (052) schemas applied.
 test("worldRestoreSha is gated on the durable-resume enrolment: participant → SHA, none → null", async () => {
-  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql"]);
+  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql", "115_world_checkpoint_process_key.sql"]);
   const PR = "owner/repo#7";
   const sha = "77ee0993cc6ad4493da0f7551212ef16722135db";
   await new WorldStore(data).recordCheckpoint({ prKey: PR, roundNo: 1, commitSha: sha });
@@ -1042,7 +1171,7 @@ test("worldRestoreSha is gated on the durable-resume enrolment: participant →
 });
 
 test("worldRestoreSha is null when a participant is enrolled but the PR has no checkpoint yet", async () => {
-  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql"]);
+  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql", "115_world_checkpoint_process_key.sql"]);
   await new DurableResumeRegistry(data).recordEnrolment("modern-1", true);
   assertEquals(await worldRestoreSha(data, "owner/repo#8"), null, "nothing to reconstruct on a first activation");
 });