@nanobpm/nano-workforce 0.100.0 → 0.101.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.101.1](https://github.com/nanobpm/nano-workforce/compare/v0.101.0...v0.101.1) (2026-08-19)
+
+
+### Bug Fixes
+
+* **merge-loop:** abandon a closed-not-merged PR instead of escalating ([#342](https://github.com/nanobpm/nano-workforce/issues/342)) ([#343](https://github.com/nanobpm/nano-workforce/issues/343)) ([10ea6be](https://github.com/nanobpm/nano-workforce/commit/10ea6be0e23c9315dfb71a6c94958826a1795a8c)), closes [#350](https://github.com/nanobpm/nano-workforce/issues/350)
+
+# [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/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead } from "./github.ts";
+import { BaseBranchMustExistError, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchIssueTitle, fetchPrFiles, isNotAPullRequestError, listPrsForHead, type PrState } from "./github.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
 // files (named `f{index}`), setting a `Link: rel="next"` header whenever a later page exists.
@@ -428,3 +428,38 @@ test("ensurePromotionPr: creates when none exists, then reuses on a re-run (idem
   assertEquals(second?.number, 500);
   assertEquals(state.creates.length, 1);
 });
+// The shared PR-liveness gate (#342) maps live GitHub state onto one of {open, merged, closed,
+// unknown} so neither durable loop (merge/convergence) can escalate against a non-open PR. A closed
+// PR is terminal (abandon), a merged PR completes, and a null read stays conservative (unknown →
+// proceed as before). `merged` wins over `state` because a merged PR also reports state="closed".
+function prState(over: Partial<PrState>): PrState {
+  return {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "CLEAN",
+    failingChecks: 0,
+    failingCheckNames: [],
+    presentCheckNames: [],
+    totalChecks: 0,
+    isDraft: false,
+    headRefOid: null,
+    ...over,
+  };
+}
+
+test("classifyPrLiveness: an open PR proceeds", () => {
+  assertEquals(classifyPrLiveness(prState({ state: "open" })), "open");
+});
+
+test("classifyPrLiveness: a merged PR completes (merged wins over a closed state)", () => {
+  assertEquals(classifyPrLiveness(prState({ merged: true, state: "closed" })), "merged");
+  assertEquals(classifyPrLiveness(prState({ merged: true, state: "merged" })), "merged");
+});
+
+test("classifyPrLiveness: a closed-not-merged PR is terminal (abandon)", () => {
+  assertEquals(classifyPrLiveness(prState({ merged: false, state: "closed" })), "closed");
+});
+
+test("classifyPrLiveness: a null read (transport hiccup) is unknown — never abandons blind", () => {
+  assertEquals(classifyPrLiveness(null), "unknown");
+});

package/app/github.ts

@@ -484,6 +484,11 @@ export function coalesceTitle(...candidates: (string | null | undefined)[]): str
  * failing gates (empty in token mode) so the CI-fix agent knows what to make green. */
 export interface PrState {
   merged: boolean;
+  /** GitHub's high-level PR lifecycle state, normalised to `"open" | "closed" | "merged"`. A PR
+   * closed *without* merging reports `"closed"` (GitHub also reports a merged PR as `"closed"` on
+   * the REST list, but `merged` disambiguates it). Lets a caller gate on PR liveness — see
+   * `classifyPrLiveness` — so neither loop escalates against a non-open PR (#342). */
+  state: "open" | "closed" | "merged";
   mergeStateStatus: string;
   failingChecks: number;
   failingCheckNames: string[];
@@ -584,8 +589,10 @@ export async function fetchPrState(
     };
     const rollup = j.statusCheckRollup ?? [];
     const names = failingCheckNames(rollup);
+    const merged = j.state === "MERGED" || !!j.mergedAt;
     return {
-      merged: j.state === "MERGED" || !!j.mergedAt,
+      merged,
+      state: merged ? "merged" : (j.state ?? "").toUpperCase() === "CLOSED" ? "closed" : "open",
       mergeStateStatus: (j.mergeStateStatus || "UNKNOWN").toUpperCase(),
       failingChecks: names.length,
       failingCheckNames: names,
@@ -604,14 +611,19 @@ export async function fetchPrState(
   const j = (await r.json()) as {
     merged?: boolean;
     merged_at?: string | null;
+    state?: string;
     mergeable_state?: string;
     draft?: boolean;
     head?: { sha?: string | null };
   };
+  const restMerged = !!j.merged || !!j.merged_at;
   return {
     // The single-PR GET returns a `merged` boolean (unlike the list endpoint); we also honour
     // `merged_at` so this mirrors the gh branch's `state === "MERGED" || mergedAt` rule.
-    merged: !!j.merged || !!j.merged_at,
+    merged: restMerged,
+    // REST reports a merged PR as `state:"closed"` too, so `merged` disambiguates: a `closed` PR
+    // here is genuinely closed WITHOUT merging (e.g. superseded) — the #342 abandon case.
+    state: restMerged ? "merged" : (j.state ?? "").toLowerCase() === "closed" ? "closed" : "open",
     mergeStateStatus: normalizeMergeState(j.mergeable_state ?? "unknown"),
     failingChecks: -1, // REST here doesn't enumerate checks → classifier treats BLOCKED as "wait"
     failingCheckNames: [], // …and the CI-fix agent gets no per-check list in token mode
@@ -622,6 +634,27 @@ export async function fetchPrState(
   };
 }
 
+/** Map a PR's live GitHub state to one **liveness** verdict shared by both durable loops (merge +
+ * convergence), so neither can ever escalate against a non-open PR (#342):
+ *
+ *   • `open`     — proceed with the normal protocol.
+ *   • `merged`   — already landed (out-of-band); complete the loop as merged.
+ *   • `closed`   — closed on GitHub WITHOUT merging (e.g. superseded); the PR can never merge, so
+ *                  the loop must **abandon** (terminate) it — NOT escalate a merge no human can
+ *                  complete. This is terminal state, not a human decision.
+ *   • `unknown`  — a transport hiccup left us without live state (`fetchPrState` returned null);
+ *                  stay conservative and fall through to the normal path rather than abandoning a
+ *                  PR we could not read.
+ *
+ * Deriving all three from one source keeps a single canonical liveness gate instead of each loop
+ * re-implementing `pre?.merged`/closed checks against drifting field names. */
+export function classifyPrLiveness(pre: PrState | null): "open" | "merged" | "closed" | "unknown" {
+  if (!pre) return "unknown";
+  if (pre.merged) return "merged";
+  if (pre.state === "closed") return "closed";
+  return "open";
+}
+
 /** The changed file paths of a PR (for the D2 conflict-scan, #58). `gh` returns them directly;
  * the token transport pages `/pulls/{n}/files` (100/page, capped). Returns `null` when no
  * transport is usable (idle), an empty array for a PR with no files. */

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

@@ -11,6 +11,7 @@ import { queuedVerdict } from "./service.ts";
 function st(over: Partial<PrState>): PrState {
   return {
     merged: false,
+    state: "open",
     mergeStateStatus: "CLEAN",
     failingChecks: 0,
     failingCheckNames: [],

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

@@ -25,6 +25,7 @@ import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
 import { backfillFeatureStages, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
+  classifyPrLiveness,
   coalesceTitle,
   ensureFreshHeadRun,
   ensurePromotionPr,
@@ -81,6 +82,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 +375,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 +413,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 +544,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 +574,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 +621,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 +645,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) {
@@ -882,7 +926,8 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
     try {
       const st = await fetchPrState(repo, number, token);
       if (st === null) continue; // no transport → skip this PR (others may still advance)
-      if (st.merged) {
+      const liveness = classifyPrLiveness(st);
+      if (liveness === "merged") {
         // Landed out-of-band (a maintainer clicked Merge, a mergify queue merged it, etc.). The
         // instance is parked at `wait-mergeable`, which subscribes to `merge-ready` — NOT
         // `merge-landed` (that catch, `wait-landed`, only exists later, after we enqueue). Publishing
@@ -898,6 +943,21 @@ async function pollMerges(data: DataLayer, engine: EngineClient, token: string)
         console.log(`[poller] already merged -> ${prKey}`);
         continue;
       }
+      if (liveness === "closed") {
+        // Closed on GitHub WITHOUT merging (e.g. superseded by a newer PR — #350). The PR can never
+        // land, so it must NOT be classified as blocked/conflict and escalated (that orphans the
+        // process on a dead PR, #342). Route it through the same canonical `merge-ready` → `ready` →
+        // `attempt-merge` path as the merged case; the merge worker's closed short-circuit records a
+        // terminal `abandoned` audit row and drives the loop down its terminate/abandon end event.
+        // One canonical abandon implementation lives in the worker — the poller only routes to it.
+        await flipToMergingThenPublish(data, engine, prKey, "waiting_merge", {
+          name: "merge-ready",
+          correlationKey: prKey,
+          variables: { mergeState: "ready", failingChecks: 0, failingChecksList: "" },
+        });
+        console.log(`[poller] closed without merging -> ${prKey}`);
+        continue;
+      }
       const verdict = classifyMergeability(st);
       if (verdict === "waiting") {
         // Frugal-CI remedy (#43): when the repo publishes a merge protocol that wants a fresh