@nanobpm/nano-workforce 0.191.0 → 0.192.0

package/app/service.ts

@@ -32,7 +32,7 @@ import { isUniqueConstraintFence } from "./dbFence.ts";
 import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
-import { deliveryHumanContextQuestion, isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { deliveryHumanContextQuestion, deliveryHumanContextUrl, isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
 import { deriveFeatureCompletion, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns, featureRunsTracking, foldCompletedFeatureRun } from "./feature.ts";
@@ -514,9 +514,45 @@ export async function isPrSettled(data: DataLayer, prKey: string): Promise<boole
   return !!existing && TERMINAL_STATUSES.includes(existing.derived_status);
 }
 
+// Per-`prKey` in-process serialization for `submitPr` (Copilot review of #819). `submitPr` reads the
+// PR row, decides `alreadyRunning`, `createInstance`s, and reopens the row across several `await`s.
+// Two `submitPr` calls for the SAME PR (a poll pass racing a delivery-connector redelivery, a
+// record-wave enrollment, …) could otherwise interleave at the `createInstance` await: both read the
+// pre-submit terminal row, both pass the idempotency gate (a terminal row is RESUBMITTABLE), and both
+// create a convergence instance for one PR. Serializing the whole create→reopen critical section per
+// `prKey` makes the second caller observe the row the first already claimed (`converging` + the new
+// `process_key`, derived-active) and short-circuit at the `alreadyRunning` gate instead of minting a
+// duplicate instance. The lock is deliberately IN-PROCESS, never a durable DB claim: every `submitPr`
+// caller — the poller, record-wave, delivery-connector, converge-feature — runs in THIS one Node
+// process (main.ts hosts the poller and the job workers on a single engine client) against one SQLite
+// store, so an in-memory chain fully serializes them; and an in-memory lock evaporates on crash, so a
+// half-done submit recovers through the existing terminal→resubmittable derive path. A durable non-null
+// claim would instead strand a keyed `converging` row `alreadyRunning` FOREVER on a create-instance
+// crash — exactly the #704/#497 phantom the keyless-row guard above exists to avoid. Distinct keys
+// never block each other. This composes with the atomic reopen below (which fences the old-run
+// straggler): the lock removes the duplicate-instance race, the atomic write removes the stale-owner
+// race, and neither reintroduces the other.
+const submitChains = new Map<string, Promise<unknown>>();
+function withPrSubmitLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const prev = submitChains.get(key) ?? Promise.resolve();
+  // Chain after the previous holder SETTLES (fulfilled OR rejected — both handlers are `fn`), so one
+  // failed/throwing submit never wedges the key for the PR's next submit.
+  const run = prev.then(fn, fn);
+  // The stored tail is error-swallowed so the chain survives a rejection; bound the map by dropping
+  // the key once this tail settles and no later caller has replaced it as the chain's end.
+  const tail = run.then(() => undefined, () => undefined);
+  submitChains.set(key, tail);
+  tail.then(() => {
+    if (submitChains.get(key) === tail) submitChains.delete(key);
+  });
+  return run;
+}
+
 /** Register a PR row (if new) and start the convergence process. Idempotent on prKey. Optional
  * `dependsOn` (explicit refs) is unioned with any `Depends-on:` line parsed from the PR body and
- * recorded as the PR's merge-stage dependency set. */
+ * recorded as the PR's merge-stage dependency set. Concurrent calls for the SAME PR are serialized
+ * (see {@link withPrSubmitLock}) so a poll pass racing a worker redelivery can't mint two convergence
+ * instances for one PR; the loser observes the winner's claim and returns `alreadyRunning`. */
 export async function submitPr(
   data: DataLayer,
   engine: EngineClient,
@@ -525,6 +561,20 @@ export async function submitPr(
   maxRounds: number = MAX_ROUNDS,
   convergeOnly = false,
   rootRequestKey: string | null = null,
+) {
+  return withPrSubmitLock(parsed.prKey, () =>
+    submitPrCritical(data, engine, parsed, dependsOn, maxRounds, convergeOnly, rootRequestKey),
+  );
+}
+
+async function submitPrCritical(
+  data: DataLayer,
+  engine: EngineClient,
+  parsed: ParsedPr,
+  dependsOn: string[] = [],
+  maxRounds: number = MAX_ROUNDS,
+  convergeOnly = false,
+  rootRequestKey: string | null = null,
 ) {
   const table = prs(data);
   const existing = await table.get(parsed.prKey);
@@ -604,44 +654,16 @@ export async function submitPr(
     // while `process_key` still names the OLD instance leaves a window where a delayed old-instance
     // answer job still passes the worker's staleness gate and reinserts its adjudication into the fresh
     // run (Copilot review of #806). Advancing the run identity FIRST, then clearing, fences that job.
-    // Re-open a previously converged/abandoned/merged PR for a fresh convergence run.
-    await table.update(parsed.prKey, {
-      status: "converging",
-      current_round: 1,
-      url: parsed.url,
-      // Coalesce to the key so `pull_requests.title` stays non-blank for the title-led grids
-      // (issue #248): a fresh fetch wins, else the prior title, else the `owner/repo#N` key.
-      // A blank/whitespace title counts as missing (matches the 036 backfill), so an empty
-      // external title never lands as an unlabeled row.
-      title: coalesceTitle(title, existing.title, parsed.prKey),
-      waiting_since: null,
-      last_review_id: null,
-      last_nudge_at: null,
-      // Clear the no-progress head baseline: it is scoped to the PRIOR convergence run, and a fresh
-      // run at round 1 must compare its first addressed round against a clean slate. Leaving a stale
-      // `last_round_head` lets a resubmission whose branch changed read `currentHead !== previousHead`
-      // on its first husked round, mis-route it as progress, and bypass the bounded husk retry (#786).
-      last_round_head: null,
-      // Clear the attempt watermark too: it is scoped to the prior convergence run's `review-round`
-      // instances (Copilot #789). A fresh run mints new, higher-keyed instances so a carried-over
-      // watermark would still be below them, but clearing keeps the per-run husk-correlation state
-      // unambiguous and self-contained.
-      last_progress_agent_watermark: null,
-      // Clear the at-least-once REPLAY stamp too (Copilot PR #789). The idempotency guard replays a
-      // recorded outcome whenever a redelivered job key matches this row; if the stamp survived a
-      // re-open, an OLD `pr.progress-check` delivery redelivered after the NEW convergence instance
-      // starts would still match its job key here and replay a stale escalation/progress effect into
-      // the fresh run. Clearing it makes the new run treat any such straggler as an unknown key (a
-      // normal, freshly-computed decision) rather than replaying the prior run's outcome.
-      last_progress_job_key: null,
-      last_progress_result: null,
-      outcome: null,
-      converged_at: null,
-      merged_at: null,
-      abandon_token: abandonToken,
-      root_request_key: effectiveRoot,
-      updated_at: ts,
-    });
+    // Re-open a previously converged/abandoned/merged PR for a fresh convergence run. The row-reset
+    // that flips the PR to `converging`/round 1 is DEFERRED and applied ATOMICALLY WITH the
+    // `process_key` advance below (after `createInstance`), never here. Flipping the row to the fresh
+    // run's shape while `process_key` still names the OLD (now-superseded) instance opens a window in
+    // which a delayed old-run `pr.progress-check` straggler reads its own key as the CURRENT owner,
+    // passes both `isSuperseded` and the late `stillOwns` guard, and fast-forwards the PR head onto
+    // its own stale checkpoint under the fresh run's identity (Copilot review of #819). Publishing the
+    // new run identity in the SAME write that resets the row eliminates that "converging-but-old-owner"
+    // window: the old generation is invalidated the instant the row becomes the new run's, so no
+    // straggler is ever accepted as owner of a row that already presents as the fresh run.
   } else {
     await table.insert({
       pr_key: parsed.prKey,
@@ -701,18 +723,67 @@ export async function submitPr(
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
-  // The `process_key` advance and the adjudication reset below are the two writes that MAKE the new
-  // run authoritative. If EITHER throws, the newly created instance is already live but the reopen is
-  // only half-committed — and a retry would short-circuit at the `alreadyRunning` idempotency gate
-  // (the new instance is ACTIVE, so `derived_status` is non-terminal), never re-running the reset. A
-  // failed reset would then leave the fresh run replaying STALE adjudication memory indefinitely
-  // (Copilot review). So roll the just-created run back on failure: terminate it and rethrow, so the
-  // submission is NOT treated as started. Terminating flips the PR's derived tracking status to a
-  // terminal edge (`abandoned`) via the `instanceTracking` reconciler, making the PR resubmittable so
-  // a retry re-creates a fresh instance and re-runs the reset cleanly — no orphaned run auto-applies
-  // stale decisions in the meantime.
+  // The reopen row-reset, the `process_key` advance, and the adjudication reset below are the writes
+  // that MAKE the new run authoritative. If ANY throws, the newly created instance is already live but
+  // the reopen is only half-committed — and a retry would short-circuit at the `alreadyRunning`
+  // idempotency gate (the new instance is ACTIVE, so `derived_status` is non-terminal), never
+  // re-running them. A failed reset would then leave the fresh run replaying STALE adjudication memory
+  // indefinitely (Copilot review). So roll the just-created run back on failure: terminate it and
+  // rethrow, so the submission is NOT treated as started. Terminating flips the PR's derived tracking
+  // status to a terminal edge (`abandoned`) via the `instanceTracking` reconciler, making the PR
+  // resubmittable so a retry re-creates a fresh instance and re-runs everything cleanly — no orphaned
+  // run auto-applies stale decisions, and (crucially) the row stays in its OLD terminal shape until
+  // the atomic reopen write lands, so no straggler ever sees a fresh-run row still owned by the old
+  // instance.
   try {
-    if (processKey != null) {
+    if (existing) {
+      // ATOMIC REOPEN (Copilot review of #819): reset the row to the fresh run's shape AND publish the
+      // new run identity (`process_key`) in a SINGLE write, so the row never presents as `converging`
+      // round 1 while still owned by the OLD instance. A delayed old-run straggler is therefore never
+      // accepted as the current owner of a row that already belongs to the fresh run.
+      await table.update(parsed.prKey, {
+        status: "converging",
+        current_round: 1,
+        url: parsed.url,
+        // Coalesce to the key so `pull_requests.title` stays non-blank for the title-led grids
+        // (issue #248): a fresh fetch wins, else the prior title, else the `owner/repo#N` key.
+        // A blank/whitespace title counts as missing (matches the 036 backfill), so an empty
+        // external title never lands as an unlabeled row.
+        title: coalesceTitle(title, existing.title, parsed.prKey),
+        waiting_since: null,
+        last_review_id: null,
+        last_nudge_at: null,
+        // Clear the no-progress head baseline: it is scoped to the PRIOR convergence run, and a fresh
+        // run at round 1 must compare its first addressed round against a clean slate. Leaving a stale
+        // `last_round_head` lets a resubmission whose branch changed read `currentHead !== previousHead`
+        // on its first husked round, mis-route it as progress, and bypass the bounded husk retry (#786).
+        last_round_head: null,
+        // Clear the attempt watermark too: it is scoped to the prior convergence run's `review-round`
+        // instances (Copilot #789). A fresh run mints new, higher-keyed instances so a carried-over
+        // watermark would still be below them, but clearing keeps the per-run husk-correlation state
+        // unambiguous and self-contained.
+        last_progress_agent_watermark: null,
+        // Clear the at-least-once REPLAY stamp too (Copilot PR #789). The idempotency guard replays a
+        // recorded outcome whenever a redelivered job key matches this row; if the stamp survived a
+        // re-open, an OLD `pr.progress-check` delivery redelivered after the NEW convergence instance
+        // starts would still match its job key here and replay a stale escalation/progress effect into
+        // the fresh run. Clearing it makes the new run treat any such straggler as an unknown key (a
+        // normal, freshly-computed decision) rather than replaying the prior run's outcome.
+        last_progress_job_key: null,
+        last_progress_result: null,
+        outcome: null,
+        converged_at: null,
+        merged_at: null,
+        abandon_token: abandonToken,
+        root_request_key: effectiveRoot,
+        // Publish the fresh run's identity in the SAME write as the status flip (may be null if the
+        // instance could not be created — a phantom row a retry re-enrolls, as on first submit).
+        process_key: processKey,
+        updated_at: ts,
+      });
+    } else if (processKey != null) {
+      // First submit: the row was INSERTED keyless before `createInstance` (the phantom-row pattern,
+      // #704/#497); publish its `process_key` now that the instance exists.
       await table.update(parsed.prKey, { process_key: processKey });
     }
     // Invalidate this PR's durable adjudication memory for the fresh run (issue #806, Copilot review) —
@@ -721,8 +792,7 @@ export async function submitPr(
     // rejected by the worker's staleness gate (its `processInstanceKey` no longer matches the advanced
     // `process_key`), so it cannot reinsert a stale adjudication after the reset; and the worker reads
     // `process_key` as late as possible so it observes this advance. The insert-if-absent record then
-    // re-learns the operator's new answer for the new run. Runs unconditionally (even if `processKey` is
-    // null: the memory must still be clean for the fresh run). The wipe is a SINGLE atomic `DELETE`
+    // re-learns the operator's new answer for the new run. The wipe is a SINGLE atomic `DELETE`
     // (`resetAdjudications`), never a row-by-row loop, so a crash mid-reset cannot leave a partially
     // cleared memory (Copilot review of #806).
     if (existing) {
@@ -3041,11 +3111,16 @@ export async function pollUserTasks(
     // A delivery-graph `human` node's user-task id is inlined per node (`delivery-human-task__<node>`
     // and its `…__esc` twin), so it can't be a static `case` above (issue #772). Fill its "Decision
     // context" from the run's stamped `human_labels` — otherwise the panel is blank and, because this
-    // surface seeds no form variables, the operator has no idea what the run is waiting on.
+    // surface seeds no form variables, the operator has no idea what the run is waiting on. A URL the
+    // author embedded in the node instruction is lifted onto `subject_url` so the row's "Link" column /
+    // detail link is clickable (issue #813); a delivery run carries no other subject URL (`subj.url` is
+    // null), so this is the only link a delivery human task can offer.
+    let deliverySubjectUrl: string | null = null;
     if (question === null && isDeliveryHumanElement(elementId)) {
       question = deliveryHumanContextQuestion(subj?.humanLabels, elementId);
+      deliverySubjectUrl = deliveryHumanContextUrl(subj?.humanLabels, elementId);
     }
-    return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? null, question, processKey: processInstanceKey, formKey: resolvedFormKey };
+    return { userTaskKey, elementId, subjectType, subjectKey, subjectTitle: subj?.title ?? null, subjectUrl: subj?.url ?? deliverySubjectUrl, question, processKey: processInstanceKey, formKey: resolvedFormKey };
   };
 
   // Desired set, deduped by completable key (a task is open at most once; guard a page overlap / a

package/app/world/checkpoint.ts

@@ -45,6 +45,10 @@ export interface WorldCheckpointInput {
   /** The round's irreversible effects, in order. Defaults to a single `push` effect keyed by the
    * commit SHA. */
   readonly effects?: readonly Effect[];
+  /** The convergence RUN (process instance) recording this checkpoint — persisted so the no-advance
+   * self-heal can prove the checkpoint belongs to THIS run and never heals onto a prior run's stale
+   * checkpoint (issue #819). `null`/omitted when the recording job has no process instance. */
+  readonly processKey?: string | null;
 }
 
 /** The result of recording a world checkpoint: the shared offset (mind + world commit at it) and the
@@ -73,6 +77,7 @@ export async function recordWorldCheckpoint(
     roundNo: input.roundNo,
     commitSha: input.commitSha,
     effects,
+    processKey: input.processKey ?? null,
   });
   // The JOIN: hand the mind the identical checkpoint the world just persisted, at the same boundary.
   // Advisory — a sink failure must not undo the durable world record (the world is authoritative for

package/app/world/selfHeal.test.ts

@@ -0,0 +1,296 @@
+// Tests for the no-advance self-heal (issue #818, Layer 2). The orchestration is proven against
+// injected primitives (checkpoint reader / PR-head reader / commit comparator / head advancer) so no
+// git or network is touched — mirroring the injectable-deps style of the progress-check worker. The
+// invariant under test: heal ONLY when a recorded checkpoint STRICTLY fast-forward-descends the PR
+// head AND the head was moved; every other outcome degrades safely to `{ healed: false }`.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { attemptNoAdvanceSelfHeal, type SelfHealDeps } from "./selfHeal.ts";
+
+const REPO = "o/r";
+const PR_NUM = 7;
+const PR_KEY = "o/r#7";
+const HEAD = "a".repeat(40);
+const AHEAD = "b".repeat(40);
+const ROUND = 3;
+const PROC = "9001"; // the convergence run (process instance) reconciling the round (#819)
+
+/** Build deps with per-test overrides; every primitive defaults to the happy-path fast-forward. */
+function deps(over: Partial<SelfHealDeps> = {}): SelfHealDeps {
+  return {
+    lastCheckpoint: async () => ({ commitSha: AHEAD }),
+    prHead: async () => ({ headRef: "feat/x", headRepo: REPO }),
+    compare: async () => ({ status: "ahead", aheadBy: 1, behindBy: 0 }),
+    advanceHead: async () => true,
+    ...over,
+  };
+}
+
+test("heals: a checkpoint that strictly fast-forwards the head advances it and continues", async () => {
+  const calls: Array<[string, string, string, string]> = [];
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({ advanceHead: async (r, b, s, expected) => (calls.push([r, b, s, expected]), true) }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: true, sha: AHEAD });
+  assertEquals(
+    calls,
+    [[REPO, "feat/x", AHEAD, HEAD]],
+    "advances the PR head branch to the checkpoint SHA, compare-and-swapping on the validated head",
+  );
+});
+
+test("does NOT heal when the PR has no recorded checkpoint (nothing was pushed)", async () => {
+  const res = await attemptNoAdvanceSelfHeal(deps({ lastCheckpoint: async () => null }), REPO, PR_NUM, PR_KEY, HEAD, ROUND, PROC);
+  assertEquals(res, { healed: false, reason: "no-checkpoint" });
+});
+
+test("does NOT heal when the checkpoint already equals the head (nothing stranded)", async () => {
+  const res = await attemptNoAdvanceSelfHeal(deps({ lastCheckpoint: async () => ({ commitSha: HEAD }) }), REPO, PR_NUM, PR_KEY, HEAD, ROUND, PROC);
+  assertEquals(res, { healed: false, reason: "already-at-head" });
+});
+
+test("does NOT heal a diverged checkpoint — a non-fast-forward must escalate, never rewrite history", async () => {
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({ compare: async () => ({ status: "diverged", aheadBy: 2, behindBy: 3 }) }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: false, reason: "not-fast-forward" });
+});
+
+test("does NOT heal a behind/identical checkpoint (aheadBy 0 or behindBy > 0)", async () => {
+  const behind = await attemptNoAdvanceSelfHeal(
+    deps({ compare: async () => ({ status: "behind", aheadBy: 0, behindBy: 4 }) }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(behind, { healed: false, reason: "not-fast-forward" });
+  const identical = await attemptNoAdvanceSelfHeal(
+    deps({ compare: async () => ({ status: "identical", aheadBy: 0, behindBy: 0 }) }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(identical, { healed: false, reason: "not-fast-forward" });
+});
+
+test("does NOT heal a cross-repo fork head — the base token cannot move a fork's ref", async () => {
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({ prHead: async () => ({ headRef: "feat/x", headRepo: "someone-else/r" }) }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: false, reason: "fork-head" });
+});
+
+test("does NOT heal an UNRESOLVED head repo (null) even with a same-named ref — never PATCH the base repo's branch", async () => {
+  // `fetchPrHead` reports `headRepo: null` when it cannot resolve the head's owner/name (e.g. a
+  // deleted fork). A still-present `headRef` can coincide with a same-named branch in the base repo,
+  // so treating `null` as "in the base repo" would advance an UNRELATED branch. It must classify as
+  // an unhealable fork-head and escalate — never move a ref against an unknown head repository.
+  const advanceCalls: string[] = [];
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({
+      prHead: async () => ({ headRef: "feat/x", headRepo: null }),
+      advanceHead: async (_r, b) => (advanceCalls.push(b), true),
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: false, reason: "fork-head" });
+  assertEquals(advanceCalls, []);
+});
+
+test("does NOT heal when the PR head ref is unknown", async () => {
+  const res = await attemptNoAdvanceSelfHeal(deps({ prHead: async () => ({ headRef: null, headRepo: REPO }) }), REPO, PR_NUM, PR_KEY, HEAD, ROUND, PROC);
+  assertEquals(res, { healed: false, reason: "no-head-ref" });
+});
+
+test("heals a same-repo head whose CASING differs from the caller's spelling (normalized identity, #819)", async () => {
+  // `parsePr` preserves the caller's `owner/repo` spelling while GitHub returns the canonical
+  // `head.repo.full_name`, so a valid same-repo PR can arrive with a different case (`O/R` vs `o/r`).
+  // The identity test is case-insensitive (GitHub owner/repo names are), so this must still heal —
+  // not be misclassified `fork-head` and silently skip every self-heal.
+  const advanceCalls: string[] = [];
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({
+      prHead: async () => ({ headRef: "feat/x", headRepo: REPO.toUpperCase() }),
+      advanceHead: async (_r, b) => (advanceCalls.push(b), true),
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: true, sha: AHEAD });
+  assertEquals(advanceCalls, ["feat/x"]);
+});
+
+test("does NOT heal when the comparison is unavailable (idle transport)", async () => {
+  const res = await attemptNoAdvanceSelfHeal(deps({ compare: async () => null }), REPO, PR_NUM, PR_KEY, HEAD, ROUND, PROC);
+  assertEquals(res, { healed: false, reason: "compare-unavailable" });
+});
+
+test("does NOT heal (and never crashes) when GitHub refuses the fast-forward ref update", async () => {
+  const res = await attemptNoAdvanceSelfHeal(deps({ advanceHead: async () => false }), REPO, PR_NUM, PR_KEY, HEAD, ROUND, PROC);
+  assertEquals(res, { healed: false, reason: "advance-refused" });
+});
+
+test("fails safe (never throws) when a dependency rejects — a transient outage can't fabricate a heal", async () => {
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({
+      compare: async () => {
+        throw new Error("boom");
+      },
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: false });
+});
+
+test("does not advance the head when the comparison is not a fast-forward", async () => {
+  let advanced = false;
+  await attemptNoAdvanceSelfHeal(
+    deps({
+      compare: async () => ({ status: "diverged", aheadBy: 1, behindBy: 1 }),
+      advanceHead: async () => ((advanced = true), true),
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(advanced, false, "the ref is never moved unless the checkpoint strictly fast-forwards the head");
+});
+
+test("scopes the checkpoint lookup to the CURRENT run AND round — never heals onto a prior-run checkpoint (#819)", async () => {
+  // The reader must be asked for THIS run's THIS round's checkpoint, not the newest across all
+  // runs/rounds: a reopen resets `current_round` to 1 while the prior run's higher-offset checkpoints
+  // survive, so a `round_no`-only lookup would resurrect stale work if it descended the (reset) head.
+  // Prove BOTH the run generation (`processKey`) and the `roundNo` are threaded into the reader.
+  const seen: Array<[string | null, number]> = [];
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({
+      lastCheckpoint: async (_pk, run, rn) => {
+        seen.push([run, rn]);
+        return run === PROC && rn === ROUND ? { commitSha: AHEAD } : null;
+      },
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(seen, [[PROC, ROUND]], "the checkpoint reader is scoped to the run + round being reconciled");
+  assertEquals(res, { healed: true, sha: AHEAD });
+});
+
+test("does NOT mutate the ref when the run was SUPERSEDED during the heal — the late ownership fence wins (#819)", async () => {
+  // The pre-call `isSuperseded()` read is not a fence across the heal's awaits: a concurrent
+  // `submitPr` can install a new `process_key` AFTER it, between the checkpoint/compare reads and the
+  // ref PATCH. The late `stillOwns` guard, evaluated immediately before `advanceHead`, must abandon
+  // the heal WITHOUT touching the ref, so a superseded straggler can never resurrect old work.
+  let advanced = false;
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({
+      // Ownership was valid at the outer check but is lost by the time we reach the ref mutation.
+      stillOwns: async () => false,
+      advanceHead: async () => ((advanced = true), true),
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: false, reason: "superseded" });
+  assertEquals(advanced, false, "a superseded run never PATCHes the PR head");
+});
+
+test("heals normally when the late ownership fence still reports ownership", async () => {
+  // The guard is only a fence for a LOST ownership — a run that still owns the row heals as before.
+  let advanced = false;
+  const res = await attemptNoAdvanceSelfHeal(
+    deps({
+      stillOwns: async () => true,
+      advanceHead: async () => ((advanced = true), true),
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(res, { healed: true, sha: AHEAD });
+  assertEquals(advanced, true, "an owning run advances the head");
+});
+
+test("does NOT heal on a malformed compare — a non-integer aheadBy/behindBy can't bypass the fast-forward gate", async () => {
+  // A malformed compare response coerces to NaN (`Number("not-a-number")`); since `NaN <= 0` and
+  // `NaN !== 0` are both false, a bare count gate would let `{ahead, behindBy:0, aheadBy:NaN}` PATCH
+  // the ref. Reject any non-integer count as a corrupt proof and escalate instead.
+  let advanced = false;
+  const nanAhead = await attemptNoAdvanceSelfHeal(
+    deps({
+      compare: async () => ({ status: "ahead", aheadBy: Number("not-a-number"), behindBy: 0 }),
+      advanceHead: async () => ((advanced = true), true),
+    }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(nanAhead, { healed: false, reason: "not-fast-forward" });
+  assertEquals(advanced, false, "a NaN ahead count never reaches the ref mutation");
+  // A non-integer (fractional) count is equally a corrupt proof.
+  const frac = await attemptNoAdvanceSelfHeal(
+    deps({ compare: async () => ({ status: "ahead", aheadBy: 1.5, behindBy: 0 }) }),
+    REPO,
+    PR_NUM,
+    PR_KEY,
+    HEAD,
+    ROUND,
+    PROC,
+  );
+  assertEquals(frac, { healed: false, reason: "not-fast-forward" });
+});