@nanobpm/nano-workforce 0.100.0 → 0.101.1

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

package/app/world/effect-ledger.test.ts

@@ -0,0 +1,86 @@
+// Tests for the effect ledger + fence (issue #324, ADR 0062 Slice 4/5, the WORLD half). The fence is
+// the guarantee behind the acceptance criterion "no duplicate push/comment (fence holds)": on a
+// resume the post-checkpoint effect tail is replayed, and an already-applied effect must be SKIPPED,
+// never re-executed. These prove the pure fold in isolation (no DB, no git).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { type Effect, type Fence, fenceReplay } from "./effect-ledger.ts";
+
+/** An in-memory fence over a `Set` of applied idempotency keys. */
+function memFence(applied: string[] = []): Fence & { keys: Set<string> } {
+  const keys = new Set(applied);
+  return {
+    keys,
+    isApplied: (k: string) => keys.has(k),
+    markApplied: (e: Effect) => {
+      keys.add(e.idempotencyKey);
+    },
+  };
+}
+
+const push = (sha: string): Effect => ({ kind: "push", idempotencyKey: sha });
+const comment = (id: string): Effect => ({ kind: "pr-comment", idempotencyKey: id });
+
+test("fenceReplay skips an already-applied effect and never re-applies it (the fence holds)", async () => {
+  const fence = memFence(["sha-1", "comment-9"]);
+  const applied: string[] = [];
+  const outcome = await fenceReplay([push("sha-1"), comment("comment-9")], fence, (e) => {
+    applied.push(e.idempotencyKey);
+  });
+  assertEquals(applied, [], "no effect is re-applied — both were already in the fence");
+  assertEquals(
+    outcome.skipped.map((e) => e.idempotencyKey),
+    ["sha-1", "comment-9"],
+    "both effects are reported skipped",
+  );
+  assertEquals(outcome.applied.length, 0);
+});
+
+test("fenceReplay applies only the genuinely-missing tail effect (crash after push, before comment)", async () => {
+  // The replacement activation crashed after the push landed but before its trailing comment: the
+  // push is fenced, the comment is not. Only the comment must replay.
+  const fence = memFence(["sha-1"]);
+  const applied: string[] = [];
+  const outcome = await fenceReplay([push("sha-1"), comment("comment-9")], fence, (e) => {
+    applied.push(e.idempotencyKey);
+  });
+  assertEquals(applied, ["comment-9"], "only the missing comment is applied");
+  assertEquals(outcome.applied.map((e) => e.idempotencyKey), ["comment-9"]);
+  assertEquals(outcome.skipped.map((e) => e.idempotencyKey), ["sha-1"]);
+  assert(fence.keys.has("comment-9"), "the applied effect is now recorded so a later resume skips it");
+});
+
+test("fenceReplay applies effects strictly in order (a comment referencing a push never precedes it)", async () => {
+  const fence = memFence();
+  const order: string[] = [];
+  await fenceReplay([push("sha-1"), comment("c-1"), comment("c-2")], fence, (e) => {
+    order.push(e.idempotencyKey);
+  });
+  assertEquals(order, ["sha-1", "c-1", "c-2"], "the fold preserves recorded order");
+});
+
+test("fenceReplay collapses a duplicate idempotency key within one tail to a single apply", async () => {
+  // Two ledger entries with one key denote ONE real effect; the second is always a skip even before
+  // the durable fence sees it (a malformed tail must not double-apply).
+  const fence = memFence();
+  const applied: string[] = [];
+  const outcome = await fenceReplay([comment("c-1"), comment("c-1")], fence, (e) => {
+    applied.push(e.idempotencyKey);
+  });
+  assertEquals(applied, ["c-1"], "the effect is applied exactly once");
+  assertEquals(outcome.skipped.length, 1, "the duplicate is skipped");
+});
+
+test("a second replay of the same tail is a total no-op — idempotent resume", async () => {
+  const fence = memFence();
+  const tail = [push("sha-1"), comment("c-1")];
+  const applyCount = { n: 0 };
+  await fenceReplay(tail, fence, () => {
+    applyCount.n++;
+  });
+  assertEquals(applyCount.n, 2, "first replay applies both");
+  await fenceReplay(tail, fence, () => {
+    applyCount.n++;
+  });
+  assertEquals(applyCount.n, 2, "second replay applies nothing — the fence holds across resumes");
+});

package/app/world/effect-ledger.ts

@@ -0,0 +1,103 @@
+// nano-workforce — the effect ledger + fence for durable agent-session resume (issue #324, ADR 0062
+// Slice 4/5, the WORLD half).
+//
+// Durable resume reconstructs the git working tree by INVERTING the forward op: the round's outbound
+// `git push` becomes an inbound `git fetch && git checkout <sha>` (see ./checkpoint.ts). But a round
+// also performs OTHER irreversible actions that are NOT captured by the pushed tree — a PR comment, a
+// `gh merge`. Replaying blindly on a resume would DUPLICATE them (a second identical review comment,
+// a re-attempted merge). The fence stops that: every irreversible action is recorded in an EFFECT
+// LEDGER with an idempotency key (the effect's natural identity — a commit SHA, a comment id, a merge
+// key). On restore we replay the post-checkpoint effect tail THROUGH the fence, so an already-applied
+// effect is SKIPPED, not repeated.
+//
+// This module is PURE (no I/O): the durable ledger lives in ./store.ts, the git inversion in
+// ./git.ts, and the orchestration in ./checkpoint.ts. Keeping the fence a pure fold makes the
+// "no duplicate effect on replay" invariant unit-testable without a database or a real git tree.
+
+/** The classes of irreversible action the world-restore fence guards. Each maps to a natural
+ * idempotency key: a `push` to its commit SHA, a `pr-comment` to the comment id, a `merge` to the
+ * merge key. Anything reversible (a scratch file write reconstructed by the checkout) is NOT an
+ * effect — only actions whose re-execution would be observable to the outside world belong here.
+ *
+ * The runtime tuple is the ONE canonical list (derivation over duplication): {@link EffectKind} is
+ * derived from it, and a contract boundary that must validate an externally-supplied kind (e.g. the
+ * `worldMarker` the harness reports) checks membership against it rather than re-listing the values. */
+export const EFFECT_KINDS = ["push", "pr-comment", "merge"] as const;
+export type EffectKind = (typeof EFFECT_KINDS)[number];
+
+/** True when `kind` is one of the known {@link EFFECT_KINDS}. The guard a contract boundary uses to
+ * reject an unexpected effect kind before it enters the durable ledger. */
+export function isEffectKind(kind: unknown): kind is EffectKind {
+  return typeof kind === "string" && EFFECT_KINDS.some((k) => k === kind);
+}
+
+/** True when `sha` is a well-formed 40-hex git commit SHA (a full object name). The world-restore
+ * marker's `commitSha` is used as an EXACT checkout target (`git fetch && git checkout <sha>`), so a
+ * branch name, an abbreviated/short ref, or a whitespace-tainted value could reconstruct to a moved
+ * branch tip or fail restore — undermining the "reconstruct the exact tree at <sha>" contract. Both
+ * the EMIT boundary (`repoEnvelopeVars`) and the READ boundary (`worldMarkerOf`) validate through
+ * this ONE canonical matcher so the two can never drift. */
+export function isCommitSha(sha: unknown): sha is string {
+  return typeof sha === "string" && /^[0-9a-f]{40}$/i.test(sha);
+}
+
+/** One irreversible action in the effect ledger. `idempotencyKey` is the effect's natural identity —
+ * the value that makes "did this already happen?" answerable WITHOUT re-doing it. Two ledger entries
+ * with the same key denote the same real-world effect, so the fence collapses them to one. */
+export interface Effect {
+  readonly kind: EffectKind;
+  /** The effect's natural, stable identity (commit SHA / comment id / merge key). The fence key. */
+  readonly idempotencyKey: string;
+  /** A human audit note (optional) — never load-bearing for fence identity. */
+  readonly description?: string;
+}
+
+/** The durable fence seam the replay folds over. `isApplied` answers "has this effect's idempotency
+ * key already landed?" from the ledger; `markApplied` records that an effect has now been realised so
+ * a LATER resume skips it too. Both are async so a real SQLite-backed ledger (./store.ts) satisfies
+ * them, while an in-memory `Set` satisfies them in tests. */
+export interface Fence {
+  isApplied(idempotencyKey: string): boolean | Promise<boolean>;
+  markApplied(effect: Effect): void | Promise<void>;
+}
+
+/** The breakdown of a fenced replay: which tail effects were (re)applied and which the fence skipped
+ * because they had already landed. `skipped` being the whole already-applied prefix is what makes a
+ * resume idempotent — the acceptance criterion "no duplicate push/comment (fence holds)". */
+export interface FenceOutcome {
+  readonly applied: Effect[];
+  readonly skipped: Effect[];
+}
+
+/**
+ * Replay an ordered effect tail through the fence: for each effect IN ORDER, if the fence already
+ * has its idempotency key it is skipped (never re-applied); otherwise `apply` runs the real side
+ * effect and the fence records it as applied so no later resume repeats it.
+ *
+ * The ordering is load-bearing — effects must replay in the sequence they were recorded (a comment
+ * that references a push must not run before it) — so this is a strict left-fold, never a parallel
+ * map. `apply` is invoked ONLY for genuinely-missing effects, which is the whole point: a replacement
+ * activation that crashed AFTER a push but BEFORE its trailing comment replays only the comment.
+ */
+export async function fenceReplay(
+  effects: readonly Effect[],
+  fence: Fence,
+  apply: (effect: Effect) => void | Promise<void>,
+): Promise<FenceOutcome> {
+  const applied: Effect[] = [];
+  const skipped: Effect[] = [];
+  const seenThisReplay = new Set<string>();
+  for (const effect of effects) {
+    // Guard against a duplicate key WITHIN this tail too (a malformed ledger), not just against the
+    // durable fence — two entries with one key are one effect, so the second is always a skip.
+    if (seenThisReplay.has(effect.idempotencyKey) || (await fence.isApplied(effect.idempotencyKey))) {
+      skipped.push(effect);
+      continue;
+    }
+    await apply(effect);
+    await fence.markApplied(effect);
+    seenThisReplay.add(effect.idempotencyKey);
+    applied.push(effect);
+  }
+  return { applied, skipped };
+}

package/app/world/git.ts

@@ -0,0 +1,53 @@
+// nano-workforce — the git seam for world-restore (issue #324, ADR 0062 Slice 4/5, the WORLD half).
+//
+// World-restore INVERTS the round's forward `git push`: on a replacement activation the outbound push
+// of a SHA becomes an INBOUND `git fetch && git checkout <sha>` that reconstructs the exact working
+// tree on a fresh worktree. This module is the thin, INJECTABLE git port that inversion runs over —
+// `restoreWorld` (./checkpoint.ts) depends on the `GitRunner` interface, never on `child_process`
+// directly, so the restore orchestration is unit-testable against a fake runner (no real repo).
+//
+// The production runner shells out to the host `git` with an argument VECTOR (no shell), mirroring
+// `app/github.ts` `runGh` — a `pr_key`/SHA from the datastore is passed as an argv element and can
+// never inject a command.
+
+/** The minimal git surface world-restore needs — the inbound half of the push→pull inversion. */
+export interface GitRunner {
+  /** Fetch refs (and their objects) from `remote` so a subsequently-named SHA is reachable locally.
+   * The forward op pushed to this remote; fetching is its inverse. */
+  fetch(remote?: string): Promise<void>;
+  /** Check the working tree out to an exact commit SHA — the reconstruction step. Detaches HEAD at
+   * `<sha>`, which is precisely the durable resume boundary the round pushed. */
+  checkout(ref: string): Promise<void>;
+  /** Resolve a ref to its commit SHA (e.g. to confirm HEAD landed on the expected checkpoint). */
+  revParse(ref: string): Promise<string>;
+}
+
+/** Run the host `git` with the given args in `cwd` (no shell — args are an argv vector, so a
+ * datastore-sourced SHA cannot inject a command). Resolves stdout, rejects on non-zero exit with
+ * stderr as the message. Mirrors `app/github.ts` `runGh`. */
+async function runGit(args: string[], cwd?: string): Promise<string> {
+  const { execFile } = await import("node:child_process");
+  return await new Promise<string>((resolve, reject) => {
+    execFile("git", args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) reject(new Error(String(stderr || "").trim() || err.message));
+      else resolve(String(stdout));
+    });
+  });
+}
+
+/** The production `GitRunner` over the host `git`, operating in `cwd` (the provisioned worktree).
+ * `fetch` requests the objects for a subsequent `checkout <sha>`; a bare SHA (not on a branch tip)
+ * is fetchable when the remote allows it, which is the reconstruct-to-exact-SHA case. */
+export function execGitRunner(cwd?: string): GitRunner {
+  return {
+    async fetch(remote = "origin") {
+      await runGit(["fetch", remote], cwd);
+    },
+    async checkout(ref) {
+      await runGit(["checkout", "--detach", ref], cwd);
+    },
+    async revParse(ref) {
+      return (await runGit(["rev-parse", ref], cwd)).trim();
+    },
+  };
+}

package/app/world/index.ts

@@ -0,0 +1,26 @@
+// nano-workforce — the WORLD half of durable agent-session resume (issue #324, ADR 0062 Slice 4/5).
+// Barrel over the world-restore surface: the effect ledger + fence, the durable store, the git
+// inversion seam, and the checkpoint JOIN + RESTORE orchestration.
+
+export {
+  type CheckpointSink,
+  type RestoreOptions,
+  recordWorldCheckpoint,
+  restoreWorld,
+  type SessionCheckpoint,
+  type WorldCheckpointInput,
+  type WorldCheckpointResult,
+  type WorldRestoreResult,
+} from "./checkpoint.ts";
+export {
+  EFFECT_KINDS,
+  type Effect,
+  type EffectKind,
+  type Fence,
+  type FenceOutcome,
+  fenceReplay,
+  isCommitSha,
+  isEffectKind,
+} from "./effect-ledger.ts";
+export { execGitRunner, type GitRunner } from "./git.ts";
+export { type LastCheckpoint, type RecordCheckpointInput, WorldStore } from "./store.ts";