@nanobpm/nano-workforce 0.191.1 → 0.192.0

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" });
+});

package/app/world/selfHeal.ts

@@ -0,0 +1,194 @@
+// No-advance self-heal (issue #818, the Layer 2 durable fix for the agent PR-head push-divergence
+// class — jwulf/c8ctl-plugin-nano#270).
+//
+// The convergence loop escalates an `addressed` round whose PR head did NOT advance (see
+// app/roundProgress.ts). But the round's work is often ALREADY pushed and reachable on the
+// remote — just not on the PR head. A producer harness that provisions the review shape wrong cuts a
+// throwaway `nano/agent-work/*` fallback branch and pushes the fix THERE, so the agent's "pushed"
+// claim is true while the PR head never moves (this stranded nanobpm/nano-coder#26/#28, recovered by
+// hand). Layer 1 (jwulf/c8ctl-plugin-nano#270) fixes the harness to push the PR head directly AND to
+// report the pushed SHA as a `worldMarker`, which `pr.persist-round` records as a durable
+// push-checkpoint (`world_checkpoints`). This module closes the loop: BEFORE escalating a no-advance
+// round, reconcile that recorded checkpoint SHA against the PR head — if it is a STRICT
+// fast-forward descendant of the head, advance the head onto it and continue the loop as real
+// progress instead of parking a human.
+//
+// It keys off the recorded SHA (canonical world state), not any branch-naming convention, so it heals
+// the whole class: any producer that leaves the round's work reachable-but-off-the-head. Every step
+// fails SAFE — an absent checkpoint, an unreadable comparison, a non-fast-forward (diverged) tip, a
+// cross-repo fork head, or a refused ref update all yield `{ healed: false }`, so the caller escalates
+// exactly as it did before. It is purely additive to the existing no-advance path.
+
+/** The push-checkpoint reader — the newest durable `{ commitSha }` recorded by a SPECIFIC RUN of a PR
+ * AT A SPECIFIC ROUND, or `null` when that run/round pushed nothing (so there is nothing to
+ * reconcile). Scoped by the convergence RUN's `processKey` AND `roundNo` so a heal is anchored to THIS
+ * attempt's own checkpoint and can never fast-forward the head onto a stale checkpoint from a prior
+ * run — `round_no` alone does not identify a run, since a reopen resets `current_round` while the old
+ * run's checkpoints survive (#819). Backed by {@link ../world/store.ts}'s
+ * `WorldStore.lastCheckpointForRun`; injectable for tests. */
+export type CheckpointReader = (
+  prKey: string,
+  processKey: string | null,
+  roundNo: number,
+) => Promise<{ commitSha: string } | null>;
+
+/** The PR-head reader — the head branch name + repo of a PR, so the self-heal knows WHICH ref to
+ * advance and whether it lives in THIS repo (a fork head is unpushable from the base token). Backed
+ * by `fetchPrHead`; injectable for tests. */
+export type PrHeadReader = (
+  repo: string,
+  prNumber: number,
+) => Promise<{ headRef: string | null; headRepo: string | null } | null>;
+
+/** The ancestry comparator — proves the checkpoint SHA strictly fast-forward-descends the PR head.
+ * Backed by `compareCommits`; injectable for tests. `null` means the comparison was unavailable. */
+export type CommitComparator = (
+  repo: string,
+  base: string,
+  head: string,
+) => Promise<{ status: "ahead" | "behind" | "identical" | "diverged"; aheadBy: number; behindBy: number } | null>;
+
+/** The fast-forward ref mover — advances the PR head branch to the checkpoint SHA. Backed by
+ * `updateBranchRef` (a NON-force update, so GitHub itself refuses a non-fast-forward). The 4th
+ * argument is the COMPARE-AND-SWAP precondition: the exact head SHA the fast-forward proof was
+ * computed against (`currentHead`); the mover refuses (`false`) unless the ref still equals it at
+ * mutation time, so a head advanced/replaced by a concurrent (superseded) run after the proof is
+ * never PATCHed. Returns `false` when the move was refused (non-fast-forward OR lost CAS). Injectable
+ * for tests. */
+export type HeadAdvancer = (repo: string, branch: string, sha: string, expectedSha: string) => Promise<boolean>;
+
+export interface SelfHealDeps {
+  readonly lastCheckpoint: CheckpointReader;
+  readonly prHead: PrHeadReader;
+  readonly compare: CommitComparator;
+  readonly advanceHead: HeadAdvancer;
+  /** A LATE ownership guard, re-checked immediately BEFORE the (irreversible) ref mutation to close
+   * the check-to-mutation TOCTOU (Copilot review on #819). The worker's pre-call `isSuperseded()`
+   * read is not a fence across the async heal: after it returns, this function still awaits the
+   * checkpoint lookup, PR-head read, and compare before `advanceHead`, and `submitPr` can install a
+   * new `process_key` (a fresh run) in that window. Returns `true` while this run still owns the PR
+   * row; when it returns `false` the heal is abandoned WITHOUT touching the ref, so a superseded
+   * straggler can never PATCH the branch. Optional — omitted (or absent) means "assume ownership"
+   * (the fail-open convention the worker's `isSuperseded` already uses when the identity is unknown),
+   * so a caller with no supersession concept keeps the pure #818 behaviour. */
+  readonly stillOwns?: () => Promise<boolean>;
+}
+
+/** Why a no-advance round did or did not self-heal — `healed` drives the routing (continue vs.
+ * escalate); `sha`/`reason` are for the operator log so a skipped heal is diagnosable. */
+export interface SelfHealResult {
+  readonly healed: boolean;
+  /** The SHA the PR head was advanced to (only when `healed`). */
+  readonly sha?: string;
+  /** A short machine-readable reason a heal was skipped (only when NOT `healed`). */
+  readonly reason?:
+    | "no-checkpoint"
+    | "already-at-head"
+    | "no-head-ref"
+    | "fork-head"
+    | "compare-unavailable"
+    | "not-fast-forward"
+    | "superseded"
+    /** The ref move was refused: GitHub rejected the non-fast-forward, OR the compare-and-swap lost
+     * (the head no longer equals the `currentHead` the fast-forward proof was validated against — a
+     * concurrent run moved it). */
+    | "advance-refused";
+}
+
+/** Attempt to self-heal a no-advance round by fast-forwarding the PR head onto a recorded
+ * push-checkpoint SHA. Returns `{ healed: true, sha }` ONLY when a recorded checkpoint strictly
+ * fast-forward-descends the current head AND the head was moved onto it; every other outcome is a
+ * safe `{ healed: false, reason }` (→ the caller escalates). Never throws: a rejected promise from
+ * any dep is caught and degrades to `{ healed: false }` so a transient GitHub/DB outage can never
+ * fabricate a heal (or crash the guard).
+ *
+ * @param currentHead the PR head SHA the no-advance decision was made against (the compare base). It
+ *   is non-null at the escalation point — a null/unreadable head fails OPEN upstream (continues) and
+ *   never reaches here — so the comparison is always anchored on the real head.
+ * @param roundNo the round being reconciled; the checkpoint lookup is scoped to it (and to
+ *   `processKey`) so the heal can only fast-forward onto THIS run's own pushed SHA, never a stale
+ *   prior-run/later-round one.
+ * @param processKey the convergence RUN (process instance) reconciling the round. Scopes the
+ *   checkpoint lookup to this run so a reopened PR (whose `current_round` reset to 1 while the prior
+ *   run's checkpoints survive) can never select the old run's checkpoint (#819). */
+export async function attemptNoAdvanceSelfHeal(
+  deps: SelfHealDeps,
+  repo: string,
+  prNumber: number,
+  prKey: string,
+  currentHead: string,
+  roundNo: number,
+  processKey: string | null,
+): Promise<SelfHealResult> {
+  try {
+    const checkpoint = await deps.lastCheckpoint(prKey, processKey, roundNo);
+    if (!checkpoint) return { healed: false, reason: "no-checkpoint" };
+    const sha = checkpoint.commitSha;
+    // The head is already at the checkpoint — nothing stranded, nothing to move. (A no-advance round
+    // reaching here with head === checkpoint would be a benign no-op; treat it as "nothing to heal".)
+    if (sha === currentHead) return { healed: false, reason: "already-at-head" };
+
+    const head = await deps.prHead(repo, prNumber);
+    const headRef = head?.headRef;
+    if (!headRef) return { healed: false, reason: "no-head-ref" };
+    // Require a KNOWN, same-repo head before touching any ref. A fork-based PR's head branch lives in
+    // ANOTHER repo, and an UNRESOLVABLE head repo (`headRepo == null`, e.g. a deleted fork) is equally
+    // unhealable: `fetchPrHead` reports `null` when it cannot resolve the head's owner/name, yet
+    // `headRef` can still be a same-named branch that also exists in the base repo. Treating `null` as
+    // "in the base repo" would PATCH that unrelated base-repo branch, so classify any non-match (a real
+    // fork OR an unresolved head) as an unhealable `fork-head` and escalate instead of risking a
+    // cross-repo / wrong-branch ref write. Compare NORMALIZED (case-insensitive) identities: `parsePr`
+    // preserves the caller's `owner/repo` spelling while GitHub returns the repo's canonical
+    // `head.repo.full_name`, so a valid same-repo PR submitted as `Owner/Repo#7` would otherwise
+    // mismatch the canonical `owner/repo`, be misclassified `fork-head`, and silently skip every
+    // self-heal (Copilot review of #819). GitHub owner/repo names are case-insensitive, so lowercasing
+    // both sides is the correct identity test while retaining the null rejection.
+    if (head.headRepo == null || head.headRepo.toLowerCase() !== repo.toLowerCase()) {
+      return { healed: false, reason: "fork-head" };
+    }
+
+    // Prove the checkpoint STRICTLY fast-forward-descends the current head before moving anything: a
+    // `behind`/`identical`/`diverged` checkpoint is NOT a safe fast-forward and must escalate. Anchor
+    // the compare base on `currentHead` (the SHA the no-advance verdict used), not the branch name,
+    // so a mid-check head move can't make us fast-forward onto the wrong baseline.
+    const cmp = await deps.compare(repo, currentHead, sha);
+    if (!cmp) return { healed: false, reason: "compare-unavailable" };
+    // Validate the compare COUNTS before trusting the fast-forward proof: a malformed compare
+    // response can coerce `ahead_by`/`behind_by` to `NaN` (`Number("not-a-number")`), and because
+    // `NaN <= 0` and `NaN !== 0` are BOTH false, a bare `aheadBy <= 0 || behindBy !== 0` gate would
+    // let a `{status:"ahead", behindBy:0, aheadBy:NaN}` response slip through and PATCH the ref onto
+    // an unproven SHA. Require finite INTEGER counts (a strict fast-forward is `behindBy === 0` AND
+    // `aheadBy > 0`); any non-integer count is a corrupt proof and must escalate, not heal.
+    if (
+      cmp.status !== "ahead" ||
+      !Number.isInteger(cmp.aheadBy) ||
+      !Number.isInteger(cmp.behindBy) ||
+      cmp.behindBy !== 0 ||
+      cmp.aheadBy <= 0
+    ) {
+      return { healed: false, reason: "not-fast-forward" };
+    }
+
+    // LATE OWNERSHIP FENCE (Copilot review on #819). Everything above only READ GitHub/DB state; the
+    // ONLY irreversible act is the ref move below. Two guards bind it to THIS run's validated state:
+    // (1) the late `stillOwns()` re-check — right before the move — abandons a run that was superseded
+    // DURING the awaits above (a concurrent `submitPr` installed a new `process_key`), instead of
+    // moving the head and only then being discarded by the downstream `commit` fence (which guards the
+    // DB write, not a ref mutation already made). Absent guard ⇒ assume ownership (the same fail-open
+    // the worker's `isSuperseded` uses when identity is unknown). (2) the move itself is a
+    // COMPARE-AND-SWAP keyed on `currentHead` — the exact base the fast-forward proof was computed
+    // against — so the mutation's precondition is BOUND TO the validated state rather than trusted from
+    // the separate `stillOwns()` read: a straggler that races past (1) still PATCHes nothing unless the
+    // ref is verifiably still at `currentHead` at mutation time. GitHub exposes no server-side
+    // expected-old-value precondition, so the CAS is the tightest fence the platform allows; the
+    // non-force fast-forward invariant makes the bounded residual window fail-safe (head only ever
+    // moves forward onto this run's own reachable checkpoint, never a rewrite).
+    if (deps.stillOwns && !(await deps.stillOwns())) return { healed: false, reason: "superseded" };
+
+    const advanced = await deps.advanceHead(repo, headRef, sha, currentHead);
+    if (!advanced) return { healed: false, reason: "advance-refused" };
+    return { healed: true, sha };
+  } catch {
+    return { healed: false };
+  }
+}

package/app/world/store.test.ts

@@ -33,6 +33,55 @@ test("lastCheckpoint returns the newest push-checkpoint (max offset), or null wh
   assertEquals(last, { offset: 1, commitSha: "sha-b", roundNo: 2 }, "the newest checkpoint wins");
 });
 
+test("lastCheckpointForRun scopes to one RUN's round newest checkpoint (never a stale prior-run round, #819)", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  const RUN_A = "1001";
+  const RUN_B = "2002";
+  assertEquals(await store.lastCheckpointForRun(PR, RUN_A, 1), null, "no checkpoint for the run/round yet");
+  // Prior run A pushes round 1 and round 2 checkpoints.
+  await store.recordCheckpoint({ prKey: PR, roundNo: 1, commitSha: "sha-a", processKey: RUN_A });
+  await store.recordCheckpoint({ prKey: PR, roundNo: 2, commitSha: "sha-b", processKey: RUN_A });
+  // The PR is reopened: a FRESH run B starts at round 1 and re-pushes (a NEW, higher-offset row).
+  await store.recordCheckpoint({ prKey: PR, roundNo: 1, commitSha: "sha-c", processKey: RUN_B });
+  assertEquals(
+    await store.lastCheckpointForRun(PR, RUN_B, 1),
+    { offset: 2, commitSha: "sha-c", roundNo: 1 },
+    "run B's round-1 checkpoint wins — never run A's same-numbered round-1 checkpoint",
+  );
+  assertEquals(
+    await store.lastCheckpointForRun(PR, RUN_A, 1),
+    { offset: 0, commitSha: "sha-a", roundNo: 1 },
+    "run A still resolves to its OWN round-1 checkpoint, not run B's",
+  );
+  assertEquals(
+    await store.lastCheckpointForRun(PR, RUN_A, 2),
+    { offset: 1, commitSha: "sha-b", roundNo: 2 },
+    "run A round 2 resolves to its own checkpoint",
+  );
+  // A fresh run at round 1 that has pushed NOTHING never inherits a prior run's checkpoint.
+  assertEquals(
+    await store.lastCheckpointForRun(PR, "3003", 1),
+    null,
+    "a run with no checkpoint of its own can never heal onto a prior run's stale checkpoint",
+  );
+  assertEquals(await store.lastCheckpointForRun(PR, RUN_A, 3), null, "a round that pushed nothing has no checkpoint");
+  // A null process key (a job with no process instance) is un-attributable — it matches nothing.
+  assertEquals(await store.lastCheckpointForRun(PR, null, 1), null, "a null process key can never resolve a checkpoint");
+});
+
+test("lastCheckpointForRun never returns a NULL-process_key (pre-#819 / un-attributable) checkpoint", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  // A checkpoint recorded without a process key (a legacy row, or a job with no process instance).
+  await store.recordCheckpoint({ prKey: PR, roundNo: 1, commitSha: "sha-legacy" });
+  assertEquals(
+    await store.lastCheckpointForRun(PR, "1001", 1),
+    null,
+    "an un-attributable checkpoint is never healed onto — it degrades to a safe escalation",
+  );
+});
+
 test("recordCheckpoint defaults to a single push effect keyed by the commit SHA", async () => {
   const { data } = memWorldData();
   const store = new WorldStore(data);

package/app/world/store.ts

@@ -20,6 +20,11 @@ interface WorldCheckpointRow {
   round_no: number;
   checkpoint_offset: number;
   commit_sha: string;
+  /** The convergence RUN (process instance) that recorded this checkpoint — `String(processInstanceKey)`
+   * of the `pr.persist-round` job. NULL on pre-#819 rows or a job without a `processInstanceKey`. The
+   * run-scoped self-heal lookup ({@link WorldStore.lastCheckpointForRun}) requires an EXACT non-null
+   * match, so a NULL-keyed checkpoint is never attributed to a run and can never heal (issue #819). */
+  process_key: string | null;
   created_at: string;
 }
 
@@ -58,6 +63,12 @@ export interface RecordCheckpointInput {
    * a checkpoint records what a round already DID). A pending tail effect (recorded before it is
    * performed, for crash-precise replay) is recorded with `applied: false`. */
   readonly applied?: boolean;
+  /** The convergence RUN (process instance) recording this checkpoint — `String(processInstanceKey)`
+   * of the persist-round job. Persisted so the no-advance self-heal can prove a checkpoint belongs to
+   * THIS run and never fast-forwards the head onto a prior run's stale checkpoint (issue #819).
+   * Omitted/`null` for a job without a process instance (the checkpoint is then un-attributable and
+   * the run-scoped lookup skips it — a safe escalation, not a heal). */
+  readonly processKey?: string | null;
 }
 
 /** A durable store over the `world_checkpoints` + `world_effects` tables. */
@@ -143,6 +154,7 @@ export class WorldStore {
     prKey: string,
     roundNo: number,
     commitSha: string,
+    processKey: string | null,
     now: string,
   ): Promise<number> {
     const offset = await WorldStore.#nextOffsetOn(checkpoints, prKey);
@@ -152,6 +164,7 @@ export class WorldStore {
         round_no: roundNo,
         checkpoint_offset: offset,
         commit_sha: commitSha,
+        process_key: processKey,
         created_at: now,
       });
       return offset;
@@ -188,6 +201,7 @@ export class WorldStore {
    */
   async recordCheckpoint(input: RecordCheckpointInput): Promise<number> {
     const { prKey, roundNo, commitSha } = input;
+    const processKey = input.processKey ?? null;
     const effects: readonly Effect[] = input.effects ?? [{ kind: "push", idempotencyKey: commitSha }];
     const applied = input.applied ?? true;
     const now = new Date().toISOString();
@@ -197,7 +211,7 @@ export class WorldStore {
       const existing = await checkpoints.findOne({ pr_key: prKey, commit_sha: commitSha });
       const offset = existing
         ? existing.checkpoint_offset
-        : await WorldStore.#insertCheckpointFenced(checkpoints, prKey, roundNo, commitSha, now);
+        : await WorldStore.#insertCheckpointFenced(checkpoints, prKey, roundNo, commitSha, processKey, now);
       let seq = await WorldStore.#nextSeqOn(effectsTable, prKey, offset);
       for (const effect of effects) {
         await WorldStore.#appendEffect(effectsTable, prKey, offset, seq++, effect, applied, now);
@@ -258,6 +272,28 @@ export class WorldStore {
     return { offset: newest.checkpoint_offset, commitSha: newest.commit_sha, roundNo: newest.round_no };
   }
 
+  /** The newest push-checkpoint recorded by a SPECIFIC RUN of a PR at a SPECIFIC ROUND, or `null` when
+   * that run/round pushed nothing. Unlike {@link lastCheckpoint} (newest across ALL runs/rounds), this
+   * proves the checkpoint belongs to the attempt being reconciled: the no-advance self-heal (#818,
+   * #819) must NOT fast-forward the head onto a checkpoint left by a PRIOR run. `round_no` alone does
+   * not identify a run — `submitPr` resets a reopened PR's `current_round` to 1 while the prior run's
+   * checkpoints survive, so a fresh run at round 1 would select the OLD run's round-1 checkpoint and
+   * could resurrect stale work if it descends the (reset) head. Scoping to the convergence RUN's
+   * `process_key` (the instance key advanced on every reopen) AND `round_no` anchors the heal to THIS
+   * run's own pushed SHA. A `null` `processKey` (a job with no process instance) matches NOTHING and
+   * yields `null`, and a checkpoint row with a `NULL` `process_key` (pre-#819, or an un-attributable
+   * record) is likewise never returned — both degrade to a safe escalation, never a heal. Still
+   * newest-by-offset within the match, so a genuine re-push of the same round wins. */
+  async lastCheckpointForRun(prKey: string, processKey: string | null, roundNo: number): Promise<LastCheckpoint | null> {
+    if (processKey == null) return null;
+    const rows = (await this.#checkpoints().find({ pr_key: prKey })).filter(
+      (r) => r.process_key === processKey && r.round_no === roundNo,
+    );
+    if (rows.length === 0) return null;
+    const newest = rows.reduce((a, b) => (b.checkpoint_offset > a.checkpoint_offset ? b : a));
+    return { offset: newest.checkpoint_offset, commitSha: newest.commit_sha, roundNo: newest.round_no };
+  }
+
   /** The effect tail recorded at a checkpoint offset, in `seq` order — the sequence the restore path
    * fence-replays after checking the working tree out to that checkpoint's SHA. `seq` is the intended
    * order, but it is allocated by a racy read-max-plus-one (`#nextSeqOn`) and the schema has no

package/db/migrations/115_world_checkpoint_process_key.sql

@@ -0,0 +1,22 @@
+-- 115_world_checkpoint_process_key.sql — issue #819 (Copilot review): bind a push-checkpoint to the
+-- convergence RUN that produced it, so the no-advance self-heal can prove a checkpoint belongs to the
+-- CURRENT run and never fast-forwards the PR head onto a stale checkpoint left by a PRIOR run.
+--
+-- WHY. The no-advance self-heal (app/world/selfHeal.ts, #818) reconciles a recorded push-checkpoint
+-- against the PR head. #819 scoped that lookup to the current `round_no`, but `round_no` alone does
+-- NOT identify a run: `submitPr` (app/service.ts) resets a reopened PR's `current_round` to 1 while
+-- leaving the prior run's `world_checkpoints` rows in place, so a fresh run at round 1 would still
+-- select the previous run's round-1 checkpoint — and if the branch was reset behind that old SHA the
+-- fast-forward compare passes and the heal resurrects stale work. The convergence instance key
+-- (`pull_requests.process_key`, advanced to the new run on every reopen) is the run generation, so
+-- recording it on each checkpoint lets the self-heal scope by `(process_key, round_no)` — proving the
+-- checkpoint is THIS run's own pushed SHA.
+--
+-- EXPAND (additive) phase: one nullable column, no default, nothing dropped or renamed. `NULL` on the
+-- pre-existing rows (and on any checkpoint recorded by a job without a `processInstanceKey`) is the
+-- SAFE value: the run-scoped lookup requires an EXACT non-null match, so a NULL-keyed checkpoint is
+-- never attributed to a run and can never heal — it degrades to escalation, exactly as an absent
+-- checkpoint does. Numbered after the current highest prefix on origin/main (114). The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+ALTER TABLE world_checkpoints ADD COLUMN process_key TEXT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.191.1",
+  "version": "0.192.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",