@nanobpm/nano-workforce 0.100.0 → 0.101.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.101.0](https://github.com/nanobpm/nano-workforce/compare/v0.100.0...v0.101.0) (2026-08-19)
+
+
+### Features
+
+* **world:** durable world-restore — c8ctl working-tree reconstruction + effect fence ([#324](https://github.com/nanobpm/nano-workforce/issues/324)) ([#337](https://github.com/nanobpm/nano-workforce/issues/337)) ([d2f7655](https://github.com/nanobpm/nano-workforce/commit/d2f76557027eddeed062208ebaeb8136f7b9b922)), closes [#nextSeqOn](https://github.com/nanobpm/nano-workforce/issues/nextSeqOn) [#nextSeqOn](https://github.com/nanobpm/nano-workforce/issues/nextSeqOn) [#nextSeqOn](https://github.com/nanobpm/nano-workforce/issues/nextSeqOn) [#appendEffect](https://github.com/nanobpm/nano-workforce/issues/appendEffect) [#isFenceCollision](https://github.com/nanobpm/nano-workforce/issues/isFenceCollision) [#appendEffect](https://github.com/nanobpm/nano-workforce/issues/appendEffect) [#reconcileApplied](https://github.com/nanobpm/nano-workforce/issues/reconcileApplied) [#nextSeqOn](https://github.com/nanobpm/nano-workforce/issues/nextSeqOn)
+
 # [0.100.0](https://github.com/nanobpm/nano-workforce/compare/v0.99.1...v0.100.0) (2026-08-19)
 
 

package/app/contracts.ts

@@ -354,9 +354,9 @@ export const WIRE_CONTRACTS = {
     name: "io.nanobpm.agentTask.repository",
     owner: "app/service.ts",
     semantics:
-      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`) and the c8ctl worker harness consumes to provision an isolated clone on the PR head branch. Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
+      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`) and the c8ctl worker harness consumes to provision an isolated clone on the PR head branch. Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `commitSha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
     shape:
-      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string }',
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string, commitSha?: string }',
   },
   "epicSet.submit": {
     category: "wire",
@@ -367,6 +367,14 @@ export const WIRE_CONTRACTS = {
     shape:
       '{ epics: Array<{ issue|url: string, baseBranch: string, allowSharedBase?: boolean, confirmDefaultBase?: boolean }>, deps?: Array<{ consumer: string, producer: string, package: string, capabilityRef: string }> }',
   },
+  "world.checkpoint": {
+    category: "wire",
+    name: "world.checkpoint",
+    owner: "app/world/checkpoint.ts",
+    semantics:
+      "The mind/world checkpoint JOIN shape (issue #324, ADR 0062 Slice 4/5, the WORLD half). At each push the app derives ONE `{commitSha, effectLedger}` and records it in the durable world store (`world_checkpoints`/`world_effects`) AND passes the SAME object to the mind's `session.checkpoint(commitSha, effectLedger)` (Slice 1, `@nanobpm/agentic/session`), so mind + world commit at the SAME per-PR monotonic offset — closing the divergence failure (harness thinks it hasn't pushed but the push landed, or vice-versa). `effectLedger` entries carry a fence idempotency key (push→commit SHA, PR comment→comment id, `gh merge`→merge key); on a re-lease `restoreWorld` inverts the push (`git fetch && git checkout <commitSha>`) then fence-replays the tail so an already-applied effect is skipped, not repeated. Consume this ONE shape from app/world — do not re-declare a synonym.",
+    shape: '{ commitSha: string, effectLedger: Array<{ kind: "push"|"pr-comment"|"merge", idempotencyKey: string, description?: string }> }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {
@@ -386,6 +394,14 @@ export const TYPE_CONTRACTS = {
       "One INTER-epic dependency edge (issue #292): dependent epic `plan_key` waits for producer epic `depends_on_plan_key`, gated by the producer's `{ package, capability_ref }` capability descriptor. This ONE row shape backs BOTH the durable `plan_deps` table (materialized by planner lowering S3) AND its FK-free admission-staging twin `admitted_plan_deps` (staged by the S2 door). Set admission (S2), planner lowering (S3), and operator visibility (S4) all import it from app/plan.ts — no re-declared synonym.",
     module: "app/plan.ts",
   },
+  SessionCheckpoint: {
+    category: "type",
+    name: "SessionCheckpoint",
+    owner: "app/world/checkpoint.ts",
+    semantics:
+      "The mind/world checkpoint contract shape (issue #324, ADR 0062 Slice 4/5). `{ commitSha, effectLedger }` — the ONE type both the world marker (recorded in `world_checkpoints`/`world_effects`) and the mind checkpoint (Slice 1's `session.checkpoint`) derive from, so a single derivation feeds both halves and they cannot diverge. Its `effectLedger` is `Effect[]` (the fence-keyed irreversible-action ledger). The world half imports it from app/world; when Slice 1's harness-side `@nanobpm/agentic/session` lands it MUST reuse this shape, not re-declare a synonym.",
+    module: "app/world/checkpoint.ts",
+  },
 } as const satisfies Record<string, TypeContract>;
 
 export const CAPABILITY_URL_CONTRACTS = {

package/app/migration049.test.ts

@@ -0,0 +1,112 @@
+// Regression guard for migration 049 (issue #324, ADR 0062 Slice 4/5, the WORLD half): the durable
+// constraints that MAKE world-restore correct. The `UNIQUE(pr_key, idempotency_key)` on
+// `world_effects` IS the fence — an effect recorded once cannot be double-applied — and the
+// `UNIQUE(pr_key, checkpoint_offset)` on `world_checkpoints` guarantees one world per turn boundary.
+// The tables are deliberately FK-FREE (like the 045 admission-staging twins): a checkpoint may be
+// recorded for an in-flight PR whose `pull_requests` row a store desync momentarily lost.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals, assertThrows } from "#test-assert";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  // Deliberately NO `pull_requests` table — the world tables must apply and accept rows with no PR
+  // parent (FK-free by design).
+  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/049_world_checkpoint.sql", import.meta.url)), "utf8");
+  db.exec(sql);
+  return db;
+}
+
+const insertCheckpoint = (db: DatabaseSync, prKey: string, offset: number, sha: string) =>
+  db
+    .prepare(
+      `INSERT INTO world_checkpoints (pr_key, round_no, checkpoint_offset, commit_sha, created_at)
+       VALUES (?, 1, ?, ?, 't')`,
+    )
+    .run(prKey, offset, sha);
+
+const insertEffect = (db: DatabaseSync, prKey: string, key: string) =>
+  db
+    .prepare(
+      `INSERT INTO world_effects (pr_key, checkpoint_offset, seq, kind, idempotency_key, applied, created_at)
+       VALUES (?, 0, 0, 'push', ?, 1, 't')`,
+    )
+    .run(prKey, key);
+
+test("migration 049 applies cleanly with NO pull_requests table (FK-free) and records a checkpoint", () => {
+  const db = migratedDb();
+  insertCheckpoint(db, "o/r#2", 0, "sha-a"); // no PR parent — must NOT FK-fail
+  const row = db.prepare("SELECT pr_key, commit_sha FROM world_checkpoints WHERE pr_key = ?").get("o/r#2") as {
+    pr_key: string;
+    commit_sha: string;
+  };
+  assertEquals(row.pr_key, "o/r#2");
+  assertEquals(row.commit_sha, "sha-a");
+});
+
+test("world_checkpoints UNIQUE(pr_key, checkpoint_offset): one world per turn boundary", () => {
+  const db = migratedDb();
+  insertCheckpoint(db, "o/r#1", 0, "sha-a");
+  assertThrows(
+    () => insertCheckpoint(db, "o/r#1", 0, "sha-b"),
+    undefined,
+    "UNIQUE constraint failed",
+  );
+  // A different offset for the same PR, and the same offset for a different PR, are both fine.
+  insertCheckpoint(db, "o/r#1", 1, "sha-b");
+  insertCheckpoint(db, "o/r#2", 0, "sha-c");
+  assertEquals(Number((db.prepare("SELECT COUNT(*) c FROM world_checkpoints").get() as { c: number }).c), 3);
+});
+
+test("world_effects UNIQUE(pr_key, idempotency_key) IS the fence: one real effect → one row", () => {
+  const db = migratedDb();
+  insertEffect(db, "o/r#1", "sha-a");
+  assertThrows(
+    () => insertEffect(db, "o/r#1", "sha-a"),
+    undefined,
+    "UNIQUE constraint failed",
+  );
+  // The SAME key under a DIFFERENT PR is a different effect — allowed.
+  insertEffect(db, "o/r#2", "sha-a");
+  const rows = db.prepare("SELECT pr_key FROM world_effects WHERE idempotency_key = ?").all("sha-a");
+  assertEquals(rows.length, 2, "the fence is scoped per PR");
+});
+
+test("world_effects.applied defaults to 0 (a pending tail entry) unless set", () => {
+  const db = migratedDb();
+  db.prepare(
+    `INSERT INTO world_effects (pr_key, checkpoint_offset, seq, kind, idempotency_key, created_at)
+     VALUES ('o/r#1', 0, 0, 'pr-comment', 'c-1', 't')`,
+  ).run();
+  const row = db.prepare("SELECT applied FROM world_effects WHERE idempotency_key = 'c-1'").get() as { applied: number };
+  assertEquals(row.applied, 0, "an effect recorded before it is performed is pending by default");
+  assert(true);
+});
+
+test("world_effects CHECK(applied IN (0,1)): the fence's boolean domain is pinned at the schema", () => {
+  const db = migratedDb();
+  // The fence reads `applied` as "already realised?" — a stray value (a future writer bug or a
+  // corrupt row on this externalised durability boundary) must be rejected, not silently mis-skip
+  // or re-apply an effect on replay.
+  assertThrows(
+    () =>
+      db
+        .prepare(
+          `INSERT INTO world_effects (pr_key, checkpoint_offset, seq, kind, idempotency_key, applied, created_at)
+           VALUES ('o/r#1', 0, 0, 'push', 'sha-bad', 2, 't')`,
+        )
+        .run(),
+    undefined,
+    "CHECK constraint failed",
+  );
+  // The two legal values both insert fine.
+  insertEffect(db, "o/r#1", "sha-applied"); // applied = 1
+  db.prepare(
+    `INSERT INTO world_effects (pr_key, checkpoint_offset, seq, kind, idempotency_key, applied, created_at)
+     VALUES ('o/r#1', 0, 1, 'push', 'sha-pending', 0, 't')`,
+  ).run();
+  assertEquals(Number((db.prepare("SELECT COUNT(*) c FROM world_effects").get() as { c: number }).c), 2);
+});

package/app/service.test.ts

@@ -503,6 +503,22 @@ test("repoEnvelopeVars emits nothing for a malformed repo (not owner/repo)", ()
   }
 });
 
+test("repoEnvelopeVars emits commitSha only for a well-formed 40-hex SHA (world-restore, #324)", () => {
+  const sha = "77ee0993cc6ad4493da0f7551212ef16722135db";
+  const env = (repoEnvelopeVars("owner/repo", "feat/x", "main", sha) as any)["io.nanobpm.agentTask"];
+  assertEquals(env.repository.commitSha, sha, "a valid 40-hex SHA is threaded through as the exact checkout target");
+  // A non-SHA ref, an abbreviated SHA, or a whitespace-tainted value is dropped (no `commitSha` key):
+  // it is forwarded to the harness as an EXACT checkout target, so a bad value could reconstruct to a
+  // moved branch tip or fail provisioning. Omission degrades to the pre-#324 head-branch-tip clone.
+  for (const bad of ["main", "feat/x", "77ee099", `${sha} `, ` ${sha}`, `${sha}\n`, "z".repeat(40), `${sha}0`, ""]) {
+    const r = (repoEnvelopeVars("owner/repo", "feat/x", "main", bad) as any)["io.nanobpm.agentTask"].repository;
+    assertEquals("commitSha" in r, false, `expected no commitSha for "${JSON.stringify(bad)}"`);
+  }
+  // Omitted entirely when there is no checkpoint SHA at all (the common first-activation case).
+  const none = (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"].repository;
+  assertEquals("commitSha" in none, false);
+});
+
 // `parsePr` is total on any input: it is called unguarded from several workers (progress-check,
 // persist-round, persist-escalation, record-dependency) with a process variable that a regression
 // — or an older in-flight instance — could carry as a non-string. `.trim()` on a non-string throws,

package/app/service.ts

@@ -81,6 +81,7 @@ import {
 } from "./userTasks.ts";
 import { deriveWaitGate } from "./waitGate.ts";
 import { waveMergeTargets } from "./waves.ts";
+import { isCommitSha, WorldStore } from "./world/index.ts";
 
 /** The BPMN process that drives review convergence (`resources/processes/convergence-loop.bpmn`). */
 export const PROCESS_ID = "convergence-loop";
@@ -373,8 +374,20 @@ const AGENT_TASK_NS = "io.nanobpm.agentTask";
  * fetching file blobs lazily — small upfront, correct diffs. `--depth 1` is deliberately NOT used:
  * it would drop the merge-base and break `git diff origin/<base>...HEAD`. When the PR base branch
  * is known we also emit `baseRef` so the harness fetches the base tip alongside the head, keeping
- * that base reachable for the diff. */
-export function repoEnvelopeVars(repo: string, ref: string | null, baseRef: string | null = null): Record<string, unknown> {
+ * that base reachable for the diff.
+ *
+ * World-restore (issue #324, ADR 0062 Slice 4/5): when a PR already has a durable push-checkpoint,
+ * `commitSha` is emitted so a REPLACEMENT activation (a fresh worktree after a lease loss)
+ * reconstructs the working tree to the EXACT pushed SHA — the inversion of the round's outbound
+ * `git push` into an inbound `git fetch && git checkout <sha>` — rather than to a branch tip that may
+ * have moved. Omitted (no key) when the PR has no checkpoint yet, so a first activation clones the
+ * head branch normally. */
+export function repoEnvelopeVars(
+  repo: string,
+  ref: string | null,
+  baseRef: string | null = null,
+  commitSha: string | null = null,
+): Record<string, unknown> {
   if (!ref) return {};
   // Defence in depth: every current caller derives `repo` from parsePr/parseIssue (regex-bounded to
   // `owner/repo`), but this is an exported helper the fan-out epic gives many new callers. A repo
@@ -399,11 +412,33 @@ export function repoEnvelopeVars(repo: string, ref: string | null, baseRef: stri
         // The base branch this PR targets — emitted so the harness fetches its tip alongside the
         // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
         ...(baseRef ? { baseRef } : {}),
+        // World-restore (issue #324): the last pushed SHA a replacement activation reconstructs the
+        // working tree to (inverting the round's push into a fetch+checkout). Only emitted when it is
+        // a well-formed 40-hex commit SHA: `commitSha` is forwarded to the harness as an EXACT
+        // checkout target, so a non-SHA ref or a whitespace-tainted value could reconstruct to an
+        // unintended ref (a moved branch tip) or fail provisioning. A malformed value degrades to
+        // omission — the harness then clones the head branch tip, the pre-#324 behaviour. Omitted too
+        // when the PR has no durable push-checkpoint yet.
+        ...(isCommitSha(commitSha) ? { commitSha } : {}),
       },
     },
   };
 }
 
+/** The last durable push-checkpoint SHA for a PR (issue #324, ADR 0062 Slice 4/5), or `null` when it
+ * has none yet. Threaded into `repoEnvelopeVars` so a replacement activation reconstructs the exact
+ * pushed tree. Best-effort: any store read failure (a legacy DB predating migration 049, an in-flight
+ * desync) degrades to `null` — the harness then clones the head branch tip, the pre-#324 behaviour —
+ * rather than blocking a submit/merge on the world store. */
+async function lastPushedSha(data: DataLayer, prKey: string): Promise<string | null> {
+  try {
+    return (await new WorldStore(data).lastCheckpoint(prKey))?.commitSha ?? null;
+  } catch (err) {
+    console.warn(`[world] ${prKey} last-checkpoint read: ${err}`);
+    return null;
+  }
+}
+
 /** Register a PR row (if new) and start the convergence process. Idempotent on prKey. Optional
  * `dependsOn` (explicit refs) is unioned with any `Depends-on:` line parsed from the PR body and
  * recorded as the PR's merge-stage dependency set. */
@@ -508,6 +543,11 @@ export async function submitPr(
     });
   }
   const abUrl = abandonUrl(abandonToken);
+  // World-restore (issue #324, ADR 0062 Slice 4/5): a re-run of convergence for a PR that already
+  // pushed is a resume — carry its last durable push-checkpoint so a replacement activation on a
+  // fresh worktree reconstructs the tree to the EXACT pushed SHA. Absent (null) on a first submit,
+  // which leaves the envelope unchanged.
+  const worldSha = await lastPushedSha(data, parsed.prKey);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: PROCESS_ID,
     variables: {
@@ -533,7 +573,7 @@ export async function submitPr(
       // Host-git provisioning (c8ctl): deliver the repository envelope so the `senior:pr-review`
       // harness clones an isolated workspace checked out on the PR head branch. Spread last so an
       // unresolved head (`{}`) leaves the other vars untouched.
-      ...repoEnvelopeVars(parsed.repo, headRef, baseRef),
+      ...repoEnvelopeVars(parsed.repo, headRef, baseRef, worldSha),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
@@ -580,6 +620,9 @@ export async function startMerge(
   if (!headRef) {
     console.warn(`[startMerge] ${pr.prKey} head branch unresolved — merge-agent workspace won't be provisioned`);
   }
+  // World-restore (issue #324): the merge stage runs on the same durable working tree; carry the
+  // last push-checkpoint so a replacement fix-ci/rebase activation reconstructs the exact SHA.
+  const worldSha = await lastPushedSha(data, pr.prKey);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: MERGE_PROCESS_ID,
     variables: {
@@ -601,7 +644,7 @@ export async function startMerge(
       abandonBrief: renderAbandonBrief(abUrl),
       // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the
       // fix-ci/rebase agents operate on an isolated checkout of the PR head branch.
-      ...repoEnvelopeVars(pr.repo, headRef, baseRef),
+      ...repoEnvelopeVars(pr.repo, headRef, baseRef, worldSha),
     },
   });
   if (processInstanceKey != null) {

package/app/world/checkpoint.test.ts

@@ -0,0 +1,193 @@
+// Tests for the world checkpoint JOIN + RESTORE orchestration (issue #324, ADR 0062 Slice 4/5). These
+// prove the two acceptance criteria at the orchestration level:
+//   - Divergence guard: mind and world always commit at the SAME checkpoint offset (the join hands
+//     the mind the identical checkpoint the world persisted).
+//   - Reconstruction + fence: restore INVERTS the push (`git fetch` + `git checkout <sha>`) and
+//     fence-replays the effect tail so no already-applied effect is repeated.
+import { test } from "node:test";
+import { assert, assertEquals, assertRejects } from "#test-assert";
+import { memWorldData } from "../../test/worldDb.ts";
+import { recordWorldCheckpoint, restoreWorld, type SessionCheckpoint } from "./checkpoint.ts";
+import type { Effect } from "./effect-ledger.ts";
+import type { GitRunner } from "./git.ts";
+import { WorldStore } from "./store.ts";
+
+const PR = "o/r#1";
+
+/** A fake git runner that records the inbound inversion (fetch + checkout) restore performs. */
+function fakeGit(): GitRunner & { fetched: string[]; checkedOut: string[] } {
+  const fetched: string[] = [];
+  const checkedOut: string[] = [];
+  return {
+    fetched,
+    checkedOut,
+    async fetch(remote = "origin") {
+      fetched.push(remote);
+    },
+    async checkout(ref) {
+      checkedOut.push(ref);
+    },
+    async revParse(ref) {
+      return ref;
+    },
+  };
+}
+
+test("recordWorldCheckpoint joins the mind to the world at the SAME offset (divergence guard)", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  const mindSaw: Array<{ offset: number; cp: SessionCheckpoint }> = [];
+  // The mind sink (Slice 1 `session.checkpoint`) — capture what offset it committed at by pairing it
+  // with the world offset returned. Both halves derive from ONE checkpoint object.
+  let lastOffset = -1;
+  const sink = (cp: SessionCheckpoint) => {
+    mindSaw.push({ offset: lastOffset, cp });
+  };
+
+  for (let round = 1; round <= 3; round++) {
+    const res = await recordWorldCheckpoint(store, { prKey: PR, roundNo: round, commitSha: `sha-${round}` }, (cp) => {
+      lastOffset = round - 1; // the offset the world just allocated
+      sink(cp);
+    });
+    assertEquals(res.offset, round - 1, "world offset is the per-PR monotonic counter");
+    // The mind saw the IDENTICAL checkpoint object the world persisted.
+    assertEquals(res.checkpoint.commitSha, `sha-${round}`);
+  }
+  // Divergence guard: every mind checkpoint's offset equals the world checkpoint offset — they never
+  // drift. The last committed offset the mind saw is the store's newest.
+  const last = await store.lastCheckpoint(PR);
+  assertEquals(last?.offset, 2, "world's newest offset");
+  assertEquals(mindSaw.at(-1)?.offset, 2, "mind committed at the SAME offset — no divergence");
+});
+
+test("recordWorldCheckpoint derives one checkpoint fed to both the store and the mind sink", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  const effects: Effect[] = [
+    { kind: "push", idempotencyKey: "sha-1" },
+    { kind: "pr-comment", idempotencyKey: "c-1" },
+  ];
+  let sunk: SessionCheckpoint | null = null;
+  const res = await recordWorldCheckpoint(store, { prKey: PR, roundNo: 1, commitSha: "sha-1", effects }, (cp) => {
+    sunk = cp;
+  });
+  assertEquals(sunk, res.checkpoint, "the sink received the exact object the world persisted");
+  const tail = await store.effectTail(PR, res.offset);
+  assertEquals(tail.map((e) => e.idempotencyKey), ["sha-1", "c-1"], "the same effect ledger is durable");
+});
+
+test("recordWorldCheckpoint works without a sink (world half lands before the mind backend)", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  const res = await recordWorldCheckpoint(store, { prKey: PR, roundNo: 1, commitSha: "sha-1" });
+  assertEquals(res.offset, 0, "the world checkpoint is recorded even with no mind sink");
+});
+
+test("restoreWorld inverts the push: git fetch + checkout <commitSha> to reconstruct the tree", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  await recordWorldCheckpoint(store, { prKey: PR, roundNo: 1, commitSha: "sha-a" });
+  await recordWorldCheckpoint(store, { prKey: PR, roundNo: 2, commitSha: "sha-b" });
+  const git = fakeGit();
+  const res = await restoreWorld(git, store, PR);
+  assertEquals(git.fetched, ["origin"], "fetch runs first so the SHA is reachable");
+  assertEquals(git.checkedOut, ["sha-b"], "the tree is reconstructed to the NEWEST push-checkpoint SHA");
+  assertEquals(res?.offset, 1, "restore reports the checkpoint offset it landed on");
+  assertEquals(res?.commitSha, "sha-b");
+});
+
+test("restoreWorld fence-replays the tail: an already-applied effect is NOT repeated (fence holds)", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  // The round pushed AND commented; both effects are recorded applied on the forward path.
+  await recordWorldCheckpoint(store, {
+    prKey: PR,
+    roundNo: 1,
+    commitSha: "sha-a",
+    effects: [
+      { kind: "push", idempotencyKey: "sha-a" },
+      { kind: "pr-comment", idempotencyKey: "c-1" },
+    ],
+  });
+  const git = fakeGit();
+  const reapplied: string[] = [];
+  const res = await restoreWorld(git, store, PR, { apply: (e) => reapplied.push(e.idempotencyKey) });
+  assertEquals(reapplied, [], "no effect is re-applied — the fence skips both");
+  assertEquals(res?.skipped.map((e) => e.idempotencyKey), ["sha-a", "c-1"], "both are reported skipped");
+  assertEquals(res?.applied.length, 0);
+});
+
+test("restoreWorld re-applies only a genuinely-pending tail effect (crash before it landed)", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  // The push landed (applied) but its trailing comment was only RECORDED as pending (applied=false)
+  // before the worker crashed. Restore must re-apply exactly the comment.
+  await recordWorldCheckpoint(store, { prKey: PR, roundNo: 1, commitSha: "sha-a", effects: [{ kind: "push", idempotencyKey: "sha-a" }] });
+  // Record the pending comment at the NEXT offset (offset 1) via a second store call with
+  // applied=false — `recordCheckpoint` always allocates the next monotonic offset, so this becomes
+  // the newest checkpoint whose tail is the still-pending comment.
+  await store.recordCheckpoint({
+    prKey: PR,
+    roundNo: 1,
+    commitSha: "sha-a2",
+    effects: [{ kind: "pr-comment", idempotencyKey: "c-1" }],
+    applied: false,
+  });
+  const git = fakeGit();
+  const reapplied: string[] = [];
+  const res = await restoreWorld(git, store, PR, { apply: (e) => reapplied.push(e.idempotencyKey) });
+  // The newest checkpoint is offset 1 (commit sha-a2), whose tail is the pending comment.
+  assertEquals(res?.commitSha, "sha-a2");
+  assertEquals(reapplied, ["c-1"], "the pending comment is re-applied exactly once");
+  // A SECOND restore is now a no-op — the fence recorded the comment applied.
+  const reapplied2: string[] = [];
+  await restoreWorld(git, store, PR, { apply: (e) => reapplied2.push(e.idempotencyKey) });
+  assertEquals(reapplied2, [], "the second resume repeats nothing — idempotent");
+});
+
+test("restoreWorld THROWS rather than silently losing a genuinely-pending tail effect when no executor is supplied", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  await recordWorldCheckpoint(store, { prKey: PR, roundNo: 1, commitSha: "sha-a", effects: [{ kind: "push", idempotencyKey: "sha-a" }] });
+  // A trailing comment recorded PENDING (applied=false): the crash landed before it executed.
+  await store.recordCheckpoint({ prKey: PR, roundNo: 1, commitSha: "sha-a2", effects: [{ kind: "pr-comment", idempotencyKey: "c-1" }], applied: false });
+  const git = fakeGit();
+  // With no `apply` executor, marking the pending effect applied would SILENTLY DROP it — so restore
+  // must throw instead of advancing the fence past an un-executed effect.
+  await assertRejects(() => restoreWorld(git, store, PR), Error, "genuinely pending");
+  // The fence was NOT advanced: a later restore WITH an executor still re-applies the comment exactly
+  // once (the effect survived the guarded restore rather than being lost).
+  const reapplied: string[] = [];
+  const res = await restoreWorld(git, store, PR, { apply: (e) => reapplied.push(e.idempotencyKey) });
+  assertEquals(reapplied, ["c-1"], "the pending effect survived and is re-applied once");
+  assertEquals(res?.applied.map((e) => e.idempotencyKey), ["c-1"]);
+});
+
+test("restoreWorld with no executor is fine when every tail effect is already applied (the guard never fires)", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  // Both effects recorded applied on the forward path — nothing pending, so no executor is needed.
+  await recordWorldCheckpoint(store, {
+    prKey: PR,
+    roundNo: 1,
+    commitSha: "sha-a",
+    effects: [
+      { kind: "push", idempotencyKey: "sha-a" },
+      { kind: "pr-comment", idempotencyKey: "c-1" },
+    ],
+  });
+  const git = fakeGit();
+  const res = await restoreWorld(git, store, PR);
+  assertEquals(res?.applied, [], "nothing is applied");
+  assertEquals(res?.skipped.map((e) => e.idempotencyKey), ["sha-a", "c-1"], "both are skipped by the fence");
+});
+
+test("restoreWorld returns null when the PR has no push-checkpoint (nothing to reconstruct)", async () => {
+  const { data } = memWorldData();
+  const store = new WorldStore(data);
+  const git = fakeGit();
+  const res = await restoreWorld(git, store, PR);
+  assertEquals(res, null, "no checkpoint → null; the caller keeps the freshly-provisioned worktree");
+  assertEquals(git.fetched, [], "no git operation runs when there is nothing to restore");
+  assert(git.checkedOut.length === 0);
+});

package/app/world/checkpoint.ts

@@ -0,0 +1,142 @@
+// nano-workforce — world checkpoint JOIN + RESTORE (issue #324, ADR 0062 Slice 4/5, the WORLD half).
+//
+// This is the orchestration that ties the durable store (./store.ts), the effect fence
+// (./effect-ledger.ts) and the git inversion (./git.ts) into the two operations durable resume needs:
+//
+//  1. recordWorldCheckpoint — the JOIN. At each push the app records the world marker `{commitSha,
+//     effects}` AND calls the mind's `session.checkpoint(commitSha, effectLedger)` (Slice 1) with the
+//     SAME derived checkpoint, so mind + world commit at ONE turn boundary (the shared offset). This
+//     closes the divergence failure: the harness can never think it hasn't pushed when the push
+//     landed, or vice-versa, because a single derivation feeds both sides.
+//
+//  2. restoreWorld — the INVERSION. On a re-lease the round's outbound `git push` becomes an inbound
+//     `git fetch && git checkout <commitSha>` that reconstructs the exact tree on a fresh worktree,
+//     then the post-checkpoint effect tail is fence-replayed so an already-applied effect is skipped.
+//     This runs BEFORE the harness mind is resumed (world first, then mind — the tree the replayed
+//     conversation refers to must already exist).
+import { type Effect, type FenceOutcome, fenceReplay } from "./effect-ledger.ts";
+import type { GitRunner } from "./git.ts";
+import type { WorldStore } from "./store.ts";
+
+/**
+ * The mind/world checkpoint contract shape (ADR 0062 §2). Slice 1 owns the harness-side
+ * `session.checkpoint(commitSha, effectLedger)`; this is the one wire shape both halves derive from,
+ * so the world marker recorded here and the mind checkpoint joined to it are the SAME object — a
+ * single source of truth for the resume boundary.
+ */
+export interface SessionCheckpoint {
+  /** The pushed SHA the working tree is reconstructed to on resume (the durable resume boundary). */
+  readonly commitSha: string;
+  /** The irreversible effects performed up to this checkpoint, each carrying its fence idempotency
+   * key — replayed through the fence on restore so none is repeated. */
+  readonly effectLedger: readonly Effect[];
+}
+
+/** The mind-side checkpoint sink — Slice 1's `session.checkpoint(...)`. `recordWorldCheckpoint` calls
+ * it with the SAME `SessionCheckpoint` it persists, so the two halves never diverge. Optional so the
+ * world half can be exercised (and land) before the mind backend is wired in. */
+export type CheckpointSink = (checkpoint: SessionCheckpoint) => void | Promise<void>;
+
+/** The inputs for a world checkpoint at a push. */
+export interface WorldCheckpointInput {
+  readonly prKey: string;
+  readonly roundNo: number;
+  readonly commitSha: string;
+  /** The round's irreversible effects, in order. Defaults to a single `push` effect keyed by the
+   * commit SHA. */
+  readonly effects?: readonly Effect[];
+}
+
+/** The result of recording a world checkpoint: the shared offset (mind + world commit at it) and the
+ * derived checkpoint both halves saw. */
+export interface WorldCheckpointResult {
+  readonly offset: number;
+  readonly checkpoint: SessionCheckpoint;
+}
+
+/**
+ * Record a world checkpoint at a push and JOIN it to the mind checkpoint. Derives ONE
+ * {@link SessionCheckpoint} from the world marker, persists it in the durable store (allocating the
+ * per-PR monotonic offset), and — when a `sink` is supplied — passes the SAME object to the mind's
+ * `session.checkpoint`. Returning the offset lets a caller assert the mind and world committed at one
+ * boundary (the divergence guard).
+ */
+export async function recordWorldCheckpoint(
+  store: WorldStore,
+  input: WorldCheckpointInput,
+  sink?: CheckpointSink,
+): Promise<WorldCheckpointResult> {
+  const effects: readonly Effect[] = input.effects ?? [{ kind: "push", idempotencyKey: input.commitSha }];
+  const checkpoint: SessionCheckpoint = { commitSha: input.commitSha, effectLedger: effects };
+  const offset = await store.recordCheckpoint({
+    prKey: input.prKey,
+    roundNo: input.roundNo,
+    commitSha: input.commitSha,
+    effects,
+  });
+  // The JOIN: hand the mind the identical checkpoint the world just persisted, at the same boundary.
+  // Advisory — a sink failure must not undo the durable world record (the world is authoritative for
+  // the tree), so let it throw to the caller rather than swallowing a half-committed join here.
+  if (sink) await sink(checkpoint);
+  return { offset, checkpoint };
+}
+
+/** The outcome of a world restore: the checkpoint the tree was reconstructed to, plus which tail
+ * effects were (re)applied vs. skipped by the fence. `null` when the PR has no push-checkpoint yet
+ * (nothing to reconstruct). */
+export interface WorldRestoreResult extends FenceOutcome {
+  readonly offset: number;
+  readonly commitSha: string;
+}
+
+/** Options for a world restore. */
+export interface RestoreOptions {
+  /** The remote to fetch the checkpoint SHA from (default `origin`). */
+  readonly remote?: string;
+  /** Runs a fenced tail effect (a `pr-comment`/`merge` that must be re-attempted because it did not
+   * land before the crash). Omit ONLY when the tail cannot contain a genuinely-pending effect (every
+   * effect already applied): with no executor a genuinely-pending effect would be silently dropped,
+   * so `restoreWorld` instead THROWS on one rather than marking it applied without executing it. An
+   * already-applied effect is skipped regardless of this option. */
+  readonly apply?: (effect: Effect) => void | Promise<void>;
+}
+
+/**
+ * Restore the world on a re-lease by INVERTING the forward push: `git fetch` + `git checkout
+ * <commitSha>` reconstructs the exact tree at the last push-checkpoint on the fresh worktree, then
+ * the post-checkpoint effect tail is fence-replayed so an already-applied effect is SKIPPED, not
+ * repeated. Returns the checkpoint restored to (or `null` when the PR never pushed).
+ *
+ * Call this BEFORE resuming the harness mind — the conversation being replayed refers to a tree that
+ * must already exist.
+ */
+export async function restoreWorld(
+  git: GitRunner,
+  store: WorldStore,
+  prKey: string,
+  opts: RestoreOptions = {},
+): Promise<WorldRestoreResult | null> {
+  const last = await store.lastCheckpoint(prKey);
+  if (!last) return null;
+  // The inversion: the round pushed <commitSha> outbound; restore fetches it back and checks the
+  // working tree out to it. Fetch first so the (possibly non-branch-tip) SHA is reachable locally.
+  await git.fetch(opts.remote ?? "origin");
+  await git.checkout(last.commitSha);
+  // Fence-replay the effect tail: already-applied effects skip (idempotent — "no duplicate
+  // push/comment"). A genuinely-pending effect is re-applied via `opts.apply`. When no executor was
+  // supplied, DON'T advance the fence for a pending effect — marking it applied without running it
+  // would silently lose the effect. Instead throw, converting that silent-loss class into a loud,
+  // caught failure. `fenceReplay` invokes `apply` ONLY for genuinely-missing effects, so this guard
+  // never fires when every tail effect is already applied (the safe no-executor case).
+  const tail = await store.effectTail(prKey, last.offset);
+  const fence = store.fenceFor(prKey, last.offset);
+  const apply =
+    opts.apply ??
+    ((effect: Effect): never => {
+      throw new Error(
+        `restoreWorld(${prKey}): no \`apply\` executor supplied, but effect ${effect.kind}:${effect.idempotencyKey} is genuinely pending — refusing to mark it applied without executing it (silent effect loss). Pass \`opts.apply\` to re-apply pending tail effects.`,
+      );
+    });
+  const outcome = await fenceReplay(tail, fence, apply);
+  return { offset: last.offset, commitSha: last.commitSha, ...outcome };
+}