@nanobpm/nano-workforce 0.191.0 → 0.192.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/docs/adr/0001-cross-repo-epics-and-artifact-wait-gates.md

@@ -5,7 +5,7 @@ Date: 2026-08-13.
 
 > **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app's* agent
 > workforce decomposes and integrates epics. The platform-wide ADRs live in
-> `Magikcraft/nano-bpm/docs/adr` (referenced here by their number + repo, e.g. "nano-bpm ADR 0056").
+> `nanobpm/nano-bpm/docs/adr` (referenced here by their number + repo, e.g. "nano-bpm ADR 0056").
 > nano-workforce's own decisions start their own series here at 0001.
 
 Relates to:

package/docs/adr/0002-escalations-are-user-tasks-and-forms.md

@@ -4,7 +4,7 @@ Status: **Proposed.**
 Date: 2026-08-13.
 
 > **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app's* agent workforce
-> models human (and agent) decision points. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr`
+> models human (and agent) decision points. Platform-wide ADRs live in `nanobpm/nano-bpm/docs/adr`
 > (referenced by number + repo, e.g. "nano-bpm ADR 0026"). nano-workforce's own series continues here
 > after ADR 0001.
 

package/docs/adr/0003-epic-base-branch-admission.md

@@ -4,7 +4,7 @@ Status: **Proposed.**
 Date: 2026-08-13.
 
 > **Scope note.** A **nano-workforce-local** ADR — it governs how *this app* admits an epic for
-> execution. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr` (referenced by number + repo).
+> execution. Platform-wide ADRs live in `nanobpm/nano-bpm/docs/adr` (referenced by number + repo).
 > Continues nano-workforce's series after ADR 0001 (ADR 0002 is planned but not yet written; see below).
 
 Relates to:

package/docs/adr/0004-shared-contract-coordination.md

@@ -5,7 +5,7 @@ Date: 2026-08-14.
 
 > **Scope note.** A **nano-workforce-local** ADR — it governs how *this app* coordinates cross-cutting
 > contracts across parallel/sliced agent work. Platform-wide ADRs live in
-> `Magikcraft/nano-bpm/docs/adr` (referenced by number + repo). Continues nano-workforce's series after
+> `nanobpm/nano-bpm/docs/adr` (referenced by number + repo). Continues nano-workforce's series after
 > ADR 0001–0003.
 
 Relates to:

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -5,7 +5,7 @@ Date: 2026-08-20.
 
 > **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app* runs
 > heterogeneous cross-repo delivery work that mixes automated and human steps. Platform-wide ADRs live
-> in `Magikcraft/nano-bpm/docs/adr` (referenced by number + repo, e.g. "nano-bpm ADR 0051").
+> in `nanobpm/nano-bpm/docs/adr` (referenced by number + repo, e.g. "nano-bpm ADR 0051").
 > nano-workforce's own series continues here after ADR 0004.
 
 Relates to:

package/docs/adr/0006-delivery-units-one-representation.md

@@ -4,7 +4,7 @@ Status: **Proposed.**
 Date: 2026-08-22.
 
 > **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app* represents a
-> unit of delivery work internally. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr`
+> unit of delivery work internally. Platform-wide ADRs live in `nanobpm/nano-bpm/docs/adr`
 > (referenced by number + repo). nano-workforce's own series continues here after ADR 0005.
 
 Relates to:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.191.0",
+  "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",

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/merge/worker.test.ts

@@ -80,8 +80,8 @@ test("pr.merge short-circuits an already-merged PR without re-running the land p
     const out = (await handler(
       {
         variables: {
-          prKey: "Magikcraft/nano-bpm#723",
-          repo: "Magikcraft/nano-bpm",
+          prKey: "nanobpm/nano-bpm#723",
+          repo: "nanobpm/nano-bpm",
           prNumber: 723,
         },
       } as any,

package/workers/merge/worker.ts

@@ -6,7 +6,7 @@
 //   • blocked — GitHub refused (conflict / failing gate / perms) → escalate to a human, who
 //               resolves it and replies to retry (the process re-arms and re-polls).
 // HOW it lands is governed by the target repo's published merge protocol (#43): a `mergify-queue`
-// repo (e.g. Magikcraft/nano-bpm, auto-merge OFF) is landed by posting `@mergifyio queue` and
+// repo (e.g. nanobpm/nano-bpm, auto-merge OFF) is landed by posting `@mergifyio queue` and
 // waiting for the queue, NOT a direct `gh pr merge` — which that repo refuses. The actual gh/API
 // calls live in app/github.ts; this worker records the attempt in the `merges` audit table and
 // shapes the escalation payload on a block.

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) {