@nanobpm/nano-workforce 0.191.1 → 0.193.0

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.193.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",

package/test/worldDb.ts

@@ -118,5 +118,5 @@ export function memDataFor(migrationFiles: readonly string[]): { data: DataLayer
 
 /** A `DataLayer` stub over a fresh in-memory db with the world schema applied. */
 export function memWorldData(): { data: DataLayer; db: DatabaseSync } {
-  return memDataFor(["049_world_checkpoint.sql"]);
+  return memDataFor(["049_world_checkpoint.sql", "115_world_checkpoint_process_key.sql"]);
 }

package/workers/persist-round/worker.ts

@@ -202,6 +202,12 @@ const handler: AppJobHandler<In> = async (job, app) => {
         prKey,
         roundNo: round,
         commitSha: marker.commitSha,
+        // Bind the checkpoint to THIS convergence run (issue #819): the no-advance self-heal scopes
+        // its lookup by `(process_key, round_no)` so it can never fast-forward the head onto a prior
+        // run's stale checkpoint. `processInstanceKey` is this run's instance key — the same value
+        // `submitPr` advances into `pull_requests.process_key` and the self-heal's ownership guard
+        // compares against.
+        processKey: processInstanceKey,
         ...(marker.effects ? { effects: marker.effects } : {}),
       });
     } catch (err) {

package/workers/progress-check/worker.ts

@@ -17,9 +17,11 @@
 // transient GitHub hiccup can never fabricate a no-progress escalation.
 import type { AgentInstanceSummary, AppApi, AppJobHandler } from "@nanobpm/urban";
 import { type HeadReader, makeDefaultReadHead } from "../../app/currentHead.ts";
-import { fetchBranchHead, fetchPrHead } from "../../app/github.ts";
+import { compareCommits, fetchBranchHead, fetchPrHead, updateBranchRef } from "../../app/github.ts";
 import { decideProgress, isAddressedStatus } from "../../app/roundProgress.ts";
 import { parsePr } from "../../app/service.ts";
+import { WorldStore } from "../../app/world/index.ts";
+import { attemptNoAdvanceSelfHeal, type SelfHealResult } from "../../app/world/selfHeal.ts";
 import type { WorkerInputs, WorkerOutputs } from "../../nano-generated/worker-io.d.ts";
 
 // Input/output typed off the model data envelopes (`PrProgressCheckIn` / `PrProgressCheckOut` in
@@ -75,6 +77,45 @@ export { type HeadReader, makeDefaultReadHead };
 
 const defaultReadHead: HeadReader = makeDefaultReadHead({ fetchPrHead, fetchBranchHead });
 
+/** Attempt the no-advance self-heal (#818): reconcile a recorded push-checkpoint against the PR head
+ * and fast-forward the head onto it when safe. Injectable so tests never touch git/network; the
+ * default binds the real `WorldStore` (over `app.data`) + GitHub transport with the env credential
+ * (the same `process.env.GITHUB_TOKEN` default the head reader uses). See {@link
+ * ../../app/world/selfHeal.ts}. */
+export type SelfHealFn = (
+  app: AppApi,
+  repo: string,
+  prNumber: number,
+  prKey: string,
+  currentHead: string,
+  roundNo: number,
+  processKey: string | null,
+  stillOwns: () => Promise<boolean>,
+) => Promise<SelfHealResult>;
+
+const defaultSelfHeal: SelfHealFn = (app, repo, prNumber, prKey, currentHead, roundNo, processKey, stillOwns) => {
+  const tok = process.env.GITHUB_TOKEN ?? "";
+  const store = new WorldStore(app.data);
+  return attemptNoAdvanceSelfHeal(
+    {
+      lastCheckpoint: (pk, run, rn) => store.lastCheckpointForRun(pk, run, rn),
+      prHead: async (r, n) => {
+        const h = await fetchPrHead(r, n, tok);
+        return h ? { headRef: h.headRef, headRepo: h.headRepo } : null;
+      },
+      compare: (r, base, head) => compareCommits(r, base, head, tok),
+      advanceHead: (r, branch, sha, expected) => updateBranchRef(r, branch, sha, tok, expected),
+      stillOwns,
+    },
+    repo,
+    prNumber,
+    prKey,
+    currentHead,
+    roundNo,
+    processKey,
+  );
+};
+
 /** An agent-instance is "durable work" for husk purposes once it has reached a terminal state — it
  * carries a `completionDate`, or a terminal lifecycle status. A husked instance never closes (it is
  * stuck `THINKING` with null dates — jwulf/c8ctl-plugin-nano#230), so it is NOT counted. */
@@ -203,6 +244,7 @@ function agentWorkFromEngine(engine: AppApi["engine"]): AgentWorkReader {
 export function makeHandler(deps: {
   readHead: HeadReader;
   readAgentWork?: AgentWorkReader;
+  selfHeal?: SelfHealFn;
 }): AppJobHandler<In, Out> {
   return async (job, app) => {
     const { prKey, status, repo, prNumber, round, huskRetries, roundEntryHead } = job.variables;
@@ -241,25 +283,30 @@ export function makeHandler(deps: {
     // the single writer of the review-wait park (#786) — persist-round no longer sets
     // `waiting_review`, so the row rests on its running `converging` status until exactly one write
     // here resolves it, and the poller never sees a transient `waiting_review` for a husk-retry round.
+    // PROCESS-INSTANCE FENCE (Copilot #789). A straggler progress-check from a SUPERSEDED
+    // convergence instance can slip past the replay guard (its idempotency stamp was cleared when
+    // `submitPr` re-opened the PR) and reach here AFTER `submitPr` has reset the per-run fields and
+    // started a NEW convergence instance. Its stale baseline / status / watermark / result must not
+    // clobber the fresh run (which could be parked on `waiting_review` or replay stale output) — nor
+    // may it mutate GitHub with the old run's checkpoint (see the self-heal fence below).
+    // Re-read the row's CURRENT owner and report whether this job's own `processInstanceKey` no
+    // longer owns the row — the straggler's token lives in a terminated instance. Fail open (not
+    // superseded) when either key is absent (an older instance, or a row whose `process_key` is not
+    // yet seeded) so normal single-run behaviour is untouched. Compare as strings — `process_key` is
+    // persisted via `String(processInstanceKey)`, and a job key can arrive numeric.
+    const isSuperseded = async (): Promise<boolean> => {
+      const currentOwner = (await prs.get(prKey))?.process_key ?? null;
+      const jobOwner = job.processInstanceKey ?? null;
+      return currentOwner !== null && jobOwner !== null && String(currentOwner) !== String(jobOwner);
+    };
     const commit = async (
       out: Out,
       opts: { head?: string | null; status?: "waiting_review" | "converging"; agentWatermark?: string | null },
     ): Promise<Out> => {
       const ts = new Date().toISOString();
-      // PROCESS-INSTANCE FENCE (Copilot #789). A straggler progress-check from a SUPERSEDED
-      // convergence instance can slip past the replay guard (its idempotency stamp was cleared when
-      // `submitPr` re-opened the PR) and reach here AFTER `submitPr` has reset the per-run fields and
-      // started a NEW convergence instance. Its stale baseline / status / watermark / result must not
-      // clobber the fresh run (which could be parked on `waiting_review` or replay stale output).
-      // Re-read the row's CURRENT owner immediately before the write and drop the write when this
-      // job's own `processInstanceKey` no longer owns the row — the straggler's token lives in a
-      // terminated instance, so acking without persisting is correct. Fail open when either key is
-      // absent (an older instance, or a row whose `process_key` is not yet seeded) so normal
-      // single-run behaviour is untouched. Compare as strings — `process_key` is persisted via
-      // `String(processInstanceKey)`, and a job key can arrive numeric.
-      const currentOwner = (await prs.get(prKey))?.process_key ?? null;
-      const jobOwner = job.processInstanceKey ?? null;
-      if (currentOwner && jobOwner && String(currentOwner) !== String(jobOwner)) {
+      // Re-check ownership immediately before the write and drop it when this job no longer owns the
+      // row — acking without persisting is correct (the straggler's token is in a terminated instance).
+      if (await isSuperseded()) {
         return out;
       }
       await prs.update(prKey, {
@@ -386,9 +433,61 @@ export function makeHandler(deps: {
       // once the husk retry has been ruled out, so a husk-retry round never transits `waiting_review`.
       return commit(out, { head: currentHead, status: "waiting_review", agentWatermark });
     }
-    // The remaining outcome (progressed:false, huskRetry:false) escalates to a human; the
-    // persist-escalation-noprogress worker owns the status, so leave it unset — but still advance the
-    // baseline and stamp the idempotency record so a redelivered escalation replays instead of
+
+    // NO-ADVANCE SELF-HEAL (#818, Layer 2). Before escalating to a human, reconcile the round's work
+    // against the remote: a producer harness that provisioned the review shape wrong pushed the fix
+    // to a throwaway fallback branch, so it IS reachable on the remote (recorded as a durable
+    // push-checkpoint via the harness's `worldMarker`) but left the PR head un-advanced. If that
+    // checkpoint SHA STRICTLY fast-forward-descends the current head, advance the head onto it and
+    // continue the loop as real progress instead of parking a human — auto-recovering the exact
+    // divergence that stranded nanobpm/nano-coder#26/#28. `currentHead` is non-null here (a null head
+    // fails OPEN upstream via decideProgress and never reaches this escalation). Every non-heal
+    // outcome (no checkpoint, not a fast-forward, a fork head, an unreadable/refused move) degrades
+    // to escalation exactly as before — the self-heal is purely additive.
+    if (currentHead) {
+      // FENCE THE REF MUTATION (Copilot review on #818 / #819). The self-heal PATCHes the PR head on
+      // GitHub — an irreversible side effect the atomic `commit` fence below can only guard for the
+      // DB write, NOT for a mutation already made. A straggler from a SUPERSEDED instance (its stale
+      // checkpoint would resurrect old work on a PR `submitPr` has since reopened under a new
+      // `process_key`) must not move the head. Two layers guard this: (1) the run-scoped checkpoint
+      // lookup — the self-heal reads `lastCheckpointForRun(prKey, jobProcessKey, roundNo)`, so a fresh
+      // run never even sees the prior run's checkpoint; and (2) a cheap early-out here PLUS a LATE
+      // ownership re-check threaded INTO the heal (`isSuperseded` inverted → `stillOwns`), evaluated
+      // immediately before the ref PATCH, closing the check-to-mutation TOCTOU where a concurrent
+      // `submitPr` supersedes this run DURING the heal's awaits. A skipped/abandoned heal falls
+      // through to the escalation `commit`, which the same fence turns into a harmless ack-without-write.
+      const jobProcessKey = job.processInstanceKey != null ? String(job.processInstanceKey) : null;
+      if (!(await isSuperseded())) {
+        const heal = await (deps.selfHeal ?? defaultSelfHeal)(
+          app,
+          ghRepo,
+          ghNumber,
+          prKey,
+          currentHead,
+          roundNo,
+          jobProcessKey,
+          async () => !(await isSuperseded()),
+        ).catch((): SelfHealResult => ({ healed: false }));
+        if (heal.healed && heal.sha) {
+          app.log.info("no-advance self-heal advanced PR head to a reachable push-checkpoint", {
+            prKey,
+            round: roundNo,
+            from: currentHead,
+            to: heal.sha,
+          });
+          // Advance the baseline to the newly-pushed head and park at wait-review as genuine progress
+          // (husk counter reset), so the poller solicits the next Copilot review against the healed head.
+          return commit(
+            { progressed: true, huskRetries: 0 },
+            { head: heal.sha, status: "waiting_review", agentWatermark },
+          );
+        }
+      }
+    }
+
+    // The remaining outcome (progressed:false, huskRetry:false, no self-heal) escalates to a human;
+    // the persist-escalation-noprogress worker owns the status, so leave it unset — but still advance
+    // the baseline and stamp the idempotency record so a redelivered escalation replays instead of
     // recomputing.
     return commit(out, { head: currentHead, agentWatermark });
   };