@nanobpm/nano-workforce 0.103.0 → 0.104.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.104.0](https://github.com/nanobpm/nano-workforce/compare/v0.103.0...v0.104.0) (2026-08-19)
+
+
+### Features
+
+* **durable-resume:** enrolment gate + re-lease world-restore wiring ([#325](https://github.com/nanobpm/nano-workforce/issues/325)) ([#351](https://github.com/nanobpm/nano-workforce/issues/351)) ([b495dfa](https://github.com/nanobpm/nano-workforce/commit/b495dfabfda3e9e0953c6637342b79ca0c8148cc))
+
 # [0.103.0](https://github.com/nanobpm/nano-workforce/compare/v0.102.1...v0.103.0) (2026-08-19)
 
 

package/app/contracts.ts

@@ -402,6 +402,14 @@ export const TYPE_CONTRACTS = {
       "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",
   },
+  DurableResumeRegistry: {
+    category: "type",
+    name: "DurableResumeRegistry",
+    owner: "app/durableResume.ts",
+    semantics:
+      "The `durable-resume` ENROLMENT GATE (issue #325, ADR 0062 Slice 5/5, the INTEGRATION slice). `durable-resume` is a worker attribute declared at enrolment (ADR 0056 §7 — capability gates enrolment, NEVER the routing token `network.role#seat`), recorded per worker instance in `worker_durable_resume` (migration 052). The enrol door (`operations/enrolAgenticWorker.ts`) records it via `recordEnrolment`; `app/service.ts` consults `fleetSupportsDurableResume` before emitting the world-restore `commitSha` (the `io.nanobpm.agentTask.repository` envelope) so a re-leased `senior:pr-review` round RESUMES only on a participating fleet and gracefully DEGRADES (redriven from scratch) otherwise. Consume this ONE module for the durable-resume gate — do not re-declare a synonym or read the flag off a second store.",
+    module: "app/durableResume.ts",
+  },
 } as const satisfies Record<string, TypeContract>;
 
 export const CAPABILITY_URL_CONTRACTS = {

package/app/durableResume.test.ts

@@ -0,0 +1,89 @@
+// Tests for the `durable-resume` enrolment registry (issue #325, ADR 0062 Slice 5/5) against a REAL
+// in-memory SQLite engine with migration 052 applied — so the upsert, the {0,1} flag domain, and the
+// fleet-level participation probe are proven, not mocked.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { memDataFor } from "../test/worldDb.ts";
+import { DurableResumeRegistry, DURABLE_RESUME_ATTR, fleetSupportsDurableResume } from "./durableResume.ts";
+
+const mem = () => memDataFor(["052_worker_durable_resume.sql"]);
+
+test("DURABLE_RESUME_ATTR is the canonical enrolment-attribute name", () => {
+  assertEquals(DURABLE_RESUME_ATTR, "durable-resume");
+});
+
+test("recordEnrolment persists a participant and isParticipant reads it back", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  assertEquals(await reg.isParticipant("w1"), false, "unknown instance is a non-participant (safe default)");
+  await reg.recordEnrolment("w1", true);
+  assertEquals(await reg.isParticipant("w1"), true);
+});
+
+test("recordEnrolment records an explicit non-participant as false", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  await reg.recordEnrolment("w1", false);
+  assertEquals(await reg.isParticipant("w1"), false);
+  assertEquals(await reg.anyParticipant(), false, "a recorded non-participant is not a participant");
+});
+
+test("recordEnrolment is an idempotent upsert — a re-enrol overwrites the flag", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  await reg.recordEnrolment("w1", true);
+  assertEquals(await reg.isParticipant("w1"), true);
+  // A redeploy that drops durable-resume support flips the flag back — no duplicate row, no stale yes.
+  await reg.recordEnrolment("w1", false);
+  assertEquals(await reg.isParticipant("w1"), false);
+  await reg.recordEnrolment("w1", true);
+  assertEquals(await reg.isParticipant("w1"), true);
+});
+
+test("the registry normalises keys and ignores a blank/whitespace instance", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  // A blank or whitespace-only key cannot key a reachable row and must never open the fleet gate.
+  await reg.recordEnrolment("", true);
+  await reg.recordEnrolment("   ", true);
+  assertEquals(await reg.anyParticipant(), false, "a blank/whitespace enrolment is ignored, gate stays closed");
+  assertEquals(await reg.isParticipant("   "), false, "a blank key is never a participant");
+  // A padded key is canonicalised (trimmed) so reads and writes agree on one row — no unreachable dup.
+  await reg.recordEnrolment("  w1  ", true);
+  assertEquals(await reg.isParticipant("w1"), true, "a padded write is readable by the trimmed key");
+  assertEquals(await reg.isParticipant("  w1  "), true, "a padded read normalises to the same row");
+});
+
+test("anyParticipant is the fleet-level existence probe over participants", async () => {
+  const { data } = mem();
+  const reg = new DurableResumeRegistry(data);
+  assertEquals(await reg.anyParticipant(), false, "no enrolment yet");
+  await reg.recordEnrolment("legacy-1", false);
+  await reg.recordEnrolment("legacy-2", false);
+  assertEquals(await reg.anyParticipant(), false, "a fleet of only non-participants does not support resume");
+  await reg.recordEnrolment("modern-1", true);
+  assertEquals(await reg.anyParticipant(), true, "one participant makes the mixed fleet resume-capable");
+});
+
+test("fleetSupportsDurableResume mirrors anyParticipant, and degrades to false without a data layer", async () => {
+  const { data } = mem();
+  assertEquals(await fleetSupportsDurableResume(undefined), false, "no data layer → additive-safe false");
+  assertEquals(await fleetSupportsDurableResume(data), false, "no participant enrolled");
+  await new DurableResumeRegistry(data).recordEnrolment("w1", true);
+  assertEquals(await fleetSupportsDurableResume(data), true);
+});
+
+test("fleetSupportsDurableResume degrades to false on a store read failure (legacy DB predating 052)", async () => {
+  // A DataLayer whose table has no `worker_durable_resume` — the read throws; the gate must degrade to
+  // false (redrive from scratch) rather than blocking a submit/merge on the enrolment registry.
+  const { data } = memDataFor([]);
+  assertEquals(await fleetSupportsDurableResume(data), false);
+});
+
+test("the flag domain is pinned to {0,1} — a participant reads as exactly true", async () => {
+  const { data, db } = mem();
+  await new DurableResumeRegistry(data).recordEnrolment("w1", true);
+  const rows = db.prepare("SELECT durable_resume FROM worker_durable_resume WHERE instance = ?").all("w1");
+  assertEquals(rows.length, 1);
+  assert(rows[0].durable_resume === 1, "true is stored as the integer 1");
+});

package/app/durableResume.ts

@@ -0,0 +1,141 @@
+// nano-workforce — the `durable-resume` ENROLMENT GATE (issue #325, ADR 0062 Slice 5/5).
+//
+// Durable agent-session resume splits into two halves already landed by the earlier slices: the MIND
+// (the harness conversation — Slices 1–3, restored harness-side via `session/load` / native
+// `--resume`) and the WORLD (the git working tree + irreversible effect ledger — Slice 4,
+// `app/world`, restored by inverting the round's `git push` into `git fetch && git checkout <sha>`).
+// This slice is the INTEGRATION that wires both halves into the running orchestration, behind an
+// enrolment gate, so a re-leased `senior:pr-review` round (ADR 0002 lease-expiry redrive) RESUMES at
+// the last push-checkpoint on a participating harness and gracefully DEGRADES — redriven from scratch,
+// exactly as today — on a harness that does not advertise durable-resume.
+//
+// THE GATE (ADR 0056 §7). `durable-resume` is a WORKER ATTRIBUTE declared at ENROLMENT — never a
+// routing token. The routing token `network.role#seat` is unchanged; there is no BPMN change and no
+// job-type change. A worker's harness advertises durable-resume at enrol (the probe result from Slice
+// 2/3); this registry records that per instance so the app can ask, before it emits the world-restore
+// marker, "does the fleet serving this role include a participant?".
+//
+// WHY FLEET-LEVEL. At the moment the app emits the repo-provisioning envelope it does not yet know
+// WHICH worker will lease the `senior:pr-review` job — any worker enrolled for that role may. So the
+// gate is a fleet-level existence probe ({@link DurableResumeRegistry.anyParticipant}). This is
+// well-defined for a MIXED fleet: emitting the world-restore `commitSha` when at least one participant
+// is enrolled lets a participant RESUME, while a non-participant harness simply ignores the marker
+// (the envelope validators are structurally forward-compatible) and clones the head branch tip —
+// redriving from scratch. When NO participant is enrolled the marker is omitted entirely, so nothing
+// regresses: resume is purely additive.
+//
+// Advisory, app-tier only (ADR 0056): this registry NEVER hard-locks or gates a BPMN sequence flow —
+// it only decides whether an OPTIMISATION (world-restore) is offered inside an activation.
+import type { DataLayer } from "@nanobpm/urban";
+
+/**
+ * The canonical name of the durable-resume enrolment attribute. A worker advertises it at enrol; the
+ * registry records it here. It is an ENROLMENT gate (ADR 0056 §7), never a routing token — do not put
+ * it in `network.role#seat`.
+ */
+export const DURABLE_RESUME_ATTR = "durable-resume";
+
+/** A persisted enrolment row (`worker_durable_resume`): one worker instance's durable-resume flag. */
+interface WorkerDurableResumeRow {
+  instance: string;
+  durable_resume: number;
+  updated_at: string;
+}
+
+/** True when `err` is the durable PRIMARY KEY fence firing — a SQLite `UNIQUE constraint failed`
+ * raised because a concurrent/duplicate enrol inserted the SAME instance BETWEEN our `findOne` and our
+ * `insert`. `recordEnrolment` is an upsert, so a collision means "the row now exists" — the same
+ * intended outcome as the update branch, not a surfaced error. Matched on the message substring the
+ * RAD `Table` surface propagates verbatim (mirrors `WorldStore`), because that surface hides the
+ * concrete driver error type. */
+function isFenceCollision(err: unknown): boolean {
+  return err instanceof Error && /UNIQUE constraint failed/i.test(err.message);
+}
+
+/**
+ * The durable registry of per-worker durable-resume participation, over the `worker_durable_resume`
+ * table (`db/migrations/052_worker_durable_resume.sql`). Backed by the app's SQLite DataLayer through
+ * the RAD `Table<T>` surface (`data.table(...)`) — NOT hand-written SQL — mirroring `WorldStore`.
+ */
+export class DurableResumeRegistry {
+  readonly #data: DataLayer;
+
+  constructor(data: DataLayer) {
+    this.#data = data;
+  }
+
+  #table() {
+    return this.#data.table<WorkerDurableResumeRow>("worker_durable_resume", "instance");
+  }
+
+  /** Canonicalise an instance key: trim surrounding whitespace and reject a blank one. The instance is
+   * the table PRIMARY KEY and drives the fleet-wide gate via {@link anyParticipant}, so a whitespace or
+   * differently-trimmed key would create an unreachable row — or, worse, open the gate on a blank key.
+   * Normalising here makes every registry entry point safe by default rather than relying on each call
+   * site to pre-trim. Returns the trimmed key, or `undefined` when it is empty/whitespace. */
+  static #normaliseInstance(instance: string): string | undefined {
+    const trimmed = instance.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  /**
+   * Record a worker's durable-resume participation at enrolment (an idempotent UPSERT keyed by
+   * `instance`). A re-enrol overwrites the flag so a harness that gains — or loses — durable-resume
+   * support across a redeploy is reflected. The `findOne`-then-insert is racy under a concurrent
+   * duplicate enrol, so a PRIMARY KEY fence collision folds into the update path rather than surfacing
+   * as an error (the same end-state either way). A blank/whitespace `instance` is ignored (no-op) — it
+   * cannot key a reachable row and a blank key would let unrelated workers collide on one registry row.
+   */
+  async recordEnrolment(instance: string, durableResume: boolean): Promise<void> {
+    const key = DurableResumeRegistry.#normaliseInstance(instance);
+    if (key === undefined) return;
+    const table = this.#table();
+    const now = new Date().toISOString();
+    const flag = durableResume ? 1 : 0;
+    const existing = await table.findOne({ instance: key });
+    if (existing) {
+      await table.update(key, { durable_resume: flag, updated_at: now });
+      return;
+    }
+    try {
+      await table.insert({ instance: key, durable_resume: flag, updated_at: now });
+    } catch (err) {
+      if (!isFenceCollision(err)) throw err;
+      await table.update(key, { durable_resume: flag, updated_at: now });
+    }
+  }
+
+  /** Whether a specific worker instance is a durable-resume participant. `false` for an unknown
+   * instance (never enrolled) or a blank/whitespace key — the safe default (graceful degradation). */
+  async isParticipant(instance: string): Promise<boolean> {
+    const key = DurableResumeRegistry.#normaliseInstance(instance);
+    if (key === undefined) return false;
+    const row = await this.#table().findOne({ instance: key });
+    return row?.durable_resume === 1;
+  }
+
+  /** Whether the enrolled fleet includes AT LEAST ONE durable-resume participant — the fleet-level
+   * gate the world-restore emission consults. `false` when none is enrolled (nobody advertises
+   * durable-resume), so the resume marker is omitted and the round redrives from scratch. */
+  async anyParticipant(): Promise<boolean> {
+    const row = await this.#table().findOne({ durable_resume: 1 });
+    return row != null;
+  }
+}
+
+/**
+ * Whether the fleet supports durable resume — the app-tier gate for emitting the world-restore
+ * `commitSha` (see `app/service.ts`). Best-effort: any read failure (a legacy DB predating migration
+ * 052, an in-flight desync) degrades to `false`, so the round redrives from scratch rather than
+ * blocking a submit/merge on the enrolment registry. When no data layer is mounted it is likewise
+ * `false` — resume is purely additive, so its absence is always the safe direction.
+ */
+export async function fleetSupportsDurableResume(data: DataLayer | undefined): Promise<boolean> {
+  if (!data) return false;
+  try {
+    return await new DurableResumeRegistry(data).anyParticipant();
+  } catch (err) {
+    console.warn(`[durable-resume] fleet participation read: ${err}`);
+    return false;
+  }
+}

package/app/migration052.test.ts

@@ -0,0 +1,66 @@
+// Regression guard for migration 052 (issue #325, ADR 0062 Slice 5/5): the durable `durable-resume`
+// enrolment registry. The table is FK-free (enrolment is per-worker and connection-agnostic, with no
+// `pull_requests`/`plans` parent), the `instance` PRIMARY KEY makes `recordEnrolment` an idempotent
+// upsert, and `CHECK(durable_resume IN (0,1))` pins the gate's boolean domain.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals, assertThrows } from "#test-assert";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  // Deliberately NO parent tables — the enrolment table must apply and accept rows on a bare db.
+  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/052_worker_durable_resume.sql", import.meta.url)), "utf8");
+  db.exec(sql);
+  return db;
+}
+
+const upsert = (db: DatabaseSync, instance: string, flag: number) =>
+  db
+    .prepare(
+      `INSERT INTO worker_durable_resume (instance, durable_resume, updated_at) VALUES (?, ?, 't')
+       ON CONFLICT(instance) DO UPDATE SET durable_resume = excluded.durable_resume`,
+    )
+    .run(instance, flag);
+
+test("migration 052 applies cleanly with NO parent tables (FK-free) and records an enrolment", () => {
+  const db = migratedDb();
+  upsert(db, "w1", 1);
+  const row = db.prepare("SELECT instance, durable_resume FROM worker_durable_resume WHERE instance = ?").get("w1") as {
+    instance: string;
+    durable_resume: number;
+  };
+  assertEquals(row.instance, "w1");
+  assertEquals(row.durable_resume, 1);
+});
+
+test("instance PRIMARY KEY makes a re-enrol an upsert (one row per worker, latest flag wins)", () => {
+  const db = migratedDb();
+  upsert(db, "w1", 1);
+  upsert(db, "w1", 0);
+  const count = Number((db.prepare("SELECT COUNT(*) c FROM worker_durable_resume").get() as { c: number }).c);
+  assertEquals(count, 1, "no duplicate row for one instance");
+  const row = db.prepare("SELECT durable_resume FROM worker_durable_resume WHERE instance = 'w1'").get() as { durable_resume: number };
+  assertEquals(row.durable_resume, 0, "the latest enrolment flag wins");
+});
+
+test("durable_resume defaults to 0 (a non-participant) when unset", () => {
+  const db = migratedDb();
+  db.prepare("INSERT INTO worker_durable_resume (instance, updated_at) VALUES ('w1', 't')").run();
+  const row = db.prepare("SELECT durable_resume FROM worker_durable_resume WHERE instance = 'w1'").get() as { durable_resume: number };
+  assertEquals(row.durable_resume, 0);
+});
+
+test("CHECK(durable_resume IN (0,1)): the gate's boolean domain is pinned at the schema", () => {
+  const db = migratedDb();
+  assertThrows(
+    () => db.prepare("INSERT INTO worker_durable_resume (instance, durable_resume, updated_at) VALUES ('w1', 2, 't')").run(),
+    undefined,
+    "CHECK constraint failed",
+  );
+  upsert(db, "yes", 1);
+  upsert(db, "no", 0);
+  assertEquals(Number((db.prepare("SELECT COUNT(*) c FROM worker_durable_resume").get() as { c: number }).c), 2);
+});

package/app/service.test.ts

@@ -7,7 +7,10 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
+import { memDataFor } from "../test/worldDb.ts";
+import { DurableResumeRegistry } from "./durableResume.ts";
+import { WorldStore } from "./world/index.ts";
+import { parsePr, pollCapabilityGatesImpl, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr, worldRestoreSha } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -519,6 +522,35 @@ test("repoEnvelopeVars emits commitSha only for a well-formed 40-hex SHA (world-
   assertEquals("commitSha" in none, false);
 });
 
+// Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5): `worldRestoreSha` — the seam
+// `submitPr`/`startMerge` thread into `repoEnvelopeVars` — hands the harness the last push-checkpoint
+// ONLY when the enrolled fleet advertises `durable-resume`. With no participant it degrades to null,
+// so the round redrives from scratch (exactly as today). Proven against a REAL in-memory SQLite db
+// with the world (049) + enrolment (052) schemas applied.
+test("worldRestoreSha is gated on the durable-resume enrolment: participant → SHA, none → null", async () => {
+  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql"]);
+  const PR = "owner/repo#7";
+  const sha = "77ee0993cc6ad4493da0f7551212ef16722135db";
+  await new WorldStore(data).recordCheckpoint({ prKey: PR, roundNo: 1, commitSha: sha });
+
+  // No participant enrolled yet — graceful degradation: no resume marker even though a checkpoint exists.
+  assertEquals(await worldRestoreSha(data, PR), null, "no participant → redrive from scratch");
+
+  // A non-participant enrolment still does not open the gate (a fleet of only non-participants).
+  await new DurableResumeRegistry(data).recordEnrolment("legacy-1", false);
+  assertEquals(await worldRestoreSha(data, PR), null, "only non-participants → still scratch");
+
+  // One participant makes the mixed fleet resume-capable: the checkpoint SHA is now emitted.
+  await new DurableResumeRegistry(data).recordEnrolment("modern-1", true);
+  assertEquals(await worldRestoreSha(data, PR), sha, "a participant → resume at the checkpoint SHA");
+});
+
+test("worldRestoreSha is null when a participant is enrolled but the PR has no checkpoint yet", async () => {
+  const { data } = memDataFor(["049_world_checkpoint.sql", "052_worker_durable_resume.sql"]);
+  await new DurableResumeRegistry(data).recordEnrolment("modern-1", true);
+  assertEquals(await worldRestoreSha(data, "owner/repo#8"), null, "nothing to reconstruct on a first activation");
+});
+
 // `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

@@ -22,6 +22,7 @@ import {
   UnresolvableCapabilityRefError,
 } from "./capabilityNeed.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { fleetSupportsDurableResume } from "./durableResume.ts";
 import { backfillFeatureStages, deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
@@ -441,6 +442,19 @@ async function lastPushedSha(data: DataLayer, prKey: string): Promise<string | n
   }
 }
 
+/** The world-restore SHA to emit into the repo-provisioning envelope for a PR, GATED on the
+ * `durable-resume` enrolment (issue #325, ADR 0062 Slice 5/5). Only when the enrolled fleet includes a
+ * durable-resume participant (`fleetSupportsDurableResume`) do we hand the harness the last
+ * push-checkpoint so a replacement activation RESUMES by reconstructing the exact pushed tree
+ * (inverting `git push` → `git fetch && git checkout <sha>`). With no participant the marker is
+ * omitted (`null`), so the round redrives from scratch — graceful degradation, exactly as today.
+ * Resume is purely additive: gating on the enrolment attribute, not a sequence flow, keeps the
+ * engine/C8 job protocol untouched (ADR 0056 boundary). */
+export async function worldRestoreSha(data: DataLayer, prKey: string): Promise<string | null> {
+  if (!(await fleetSupportsDurableResume(data))) return null;
+  return lastPushedSha(data, prKey);
+}
+
 /** 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. */
@@ -547,9 +561,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);
+  // fresh worktree reconstructs the tree to the EXACT pushed SHA. GATED (issue #325, Slice 5/5) on the
+  // fleet advertising `durable-resume`: with no participant it stays null, so the round redrives from
+  // scratch (graceful degradation). Absent (null) on a first submit, which leaves the envelope
+  // unchanged.
+  const worldSha = await worldRestoreSha(data, parsed.prKey);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: PROCESS_ID,
     variables: {
@@ -623,8 +639,10 @@ export async function startMerge(
     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);
+  // last push-checkpoint so a replacement fix-ci/rebase activation reconstructs the exact SHA. GATED
+  // (issue #325, Slice 5/5) on the fleet advertising `durable-resume` — otherwise null, so the merge
+  // agents redrive from scratch (graceful degradation).
+  const worldSha = await worldRestoreSha(data, pr.prKey);
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: MERGE_PROCESS_ID,
     variables: {

package/db/migrations/052_worker_durable_resume.sql

@@ -0,0 +1,35 @@
+-- 052_worker_durable_resume.sql — issue #325 (ADR 0062, Slice 5/5): the ENROLMENT GATE for durable
+-- agent-session resume. Slices 1–4 built the mind (harness conversation) and world (git tree + effect
+-- ledger) halves; this slice wires them into the running orchestration behind a `durable-resume`
+-- enrolment gate so a re-leased `senior:pr-review` round RESUMES at the last push-checkpoint on a
+-- participating harness, and gracefully DEGRADES (redriven from scratch, exactly as today) on one
+-- that does not advertise it.
+--
+-- `durable-resume` is a WORKER ATTRIBUTE declared at enrolment (ADR 0056 §7 — capability gates
+-- enrolment, it is NEVER in the routing token `network.role#seat`). The registry records, per worker
+-- instance, whether that worker's harness advertises durable-resume (the probe result from Slice
+-- 2/3). The world-restore `commitSha` is emitted into the repo-provisioning envelope ONLY when the
+-- fleet includes a participant; a fleet with no participant emits no resume marker and clones the
+-- head branch tip — the pre-#324 behaviour. Resume is purely additive, never a new sequence-flow
+-- gate (ADR 0056 boundary): the engine/C8 job protocol is untouched.
+--
+-- One FK-free table keyed by the worker instance (`register.instance` / the enrol `instance`). It is
+-- FK-free by design — enrolment is per-worker and connection-agnostic, with no `pull_requests`/`plans`
+-- parent to reference. EXPAND (additive) phase: one new table + its index; nothing is dropped or
+-- renamed. Numbered after the current highest prefix on origin/main (051). The runner wraps each file
+-- in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE TABLE IF NOT EXISTS worker_durable_resume (
+  instance       TEXT PRIMARY KEY,            -- the worker instance id (enrol `instance` / register.instance)
+  durable_resume INTEGER NOT NULL DEFAULT 0,  -- 1 when the worker's harness advertises durable-resume, else 0
+  updated_at     TEXT NOT NULL,
+  -- `durable_resume` is a strict boolean domain — the gate reads it as "does this worker participate?",
+  -- so a stray value (a future writer bug, a corrupt row on this externalised enrolment boundary) would
+  -- make the gate mis-decide whether to emit the resume marker. Pin it to {0,1} at the schema.
+  CHECK (durable_resume IN (0, 1))
+);
+
+-- The gate asks "does the fleet include a durable-resume participant?" — an existence probe over the
+-- participants. Index the flag so that lookup is a covered scan, not a table walk.
+CREATE INDEX IF NOT EXISTS idx_worker_durable_resume_flag
+  ON worker_durable_resume(durable_resume);

package/openapi.yaml

@@ -386,6 +386,15 @@ components:
         instance:
           type: string
           description: The worker instance id, echoed back for provenance (optional).
+        durableResume:
+          type: boolean
+          description: >-
+            Whether this worker's harness advertises durable-resume (issue #325, ADR 0062 Slice 5/5)
+            — an ENROLMENT attribute, never a routing token. Recorded per instance so the app emits
+            the world-restore marker only to a fleet with a participant; a harness that omits it (or
+            sets false) redrives a re-leased round from scratch. Recorded only when `instance` is
+            a non-blank string — a missing, empty, or whitespace-only `instance` is echoed back for
+            provenance but the flag is not persisted.
     EnrolledRole:
       type: object
       description: One matched role in an enrolment resolution — provenance for the resolved SERVE set.
@@ -411,6 +420,14 @@ components:
         instance:
           type: string
           description: The worker instance id, echoed from the request when supplied.
+        durableResume:
+          type: boolean
+          description: >-
+            Echo of the request's durable-resume declaration (issue #325, ADR 0062 Slice 5/5).
+            Present only when the request supplied it. This reflects the value the worker sent, not a
+            guarantee of durable persistence — recording into the durable-resume registry is
+            best-effort (skipped when `instance` is absent/blank, and a registry write hiccup is
+            logged without failing enrolment).
         serve:
           type: array
           description: The SERVE token set — sorted, de-duplicated leaf tokens the worker may serve.

package/operations/enrolAgenticWorker.test.ts

@@ -2,6 +2,8 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { memDataFor } from "../test/worldDb.ts";
+import { DurableResumeRegistry } from "../app/durableResume.ts";
 import { noopLog } from "../test/log.ts";
 import handler from "./enrolAgenticWorker.ts";
 
@@ -69,6 +71,68 @@ test("rejects non-finite capability.weight (NaN/Infinity) as 400", async () => {
   assertEquals(infWeight.status, 400);
 });
 
+// Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5).
+test("echoes durableResume back in the result when the worker declares it", async () => {
+  const on = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), app)) as any;
+  assertEquals(on.status, 200);
+  assertEquals(on.body.durableResume, true);
+  const off = (await handler(input({ capability: { cognition: "decide" }, instance: "w2", durableResume: false }), app)) as any;
+  assertEquals(off.body.durableResume, false);
+});
+
+test("omits durableResume from the result when the worker does not declare it", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), app)) as any;
+  assertEquals(res.status, 200);
+  assertEquals("durableResume" in res.body, false);
+});
+
+test("rejects a non-boolean durableResume as 400", async () => {
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: "yes" }), app)) as any;
+  assertEquals(res.status, 400);
+});
+
+test("records durable-resume participation in the registry when a data layer + instance are present", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), true);
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), true);
+});
+
+test("a re-enrol omitting durableResume persists an explicit false, clearing a stale true (degrade to scratch)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  // First enrol advertises durable-resume.
+  await handler(input({ capability: { cognition: "decide" }, instance: "w1", durableResume: true }), withData);
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), true);
+  // Re-enrol WITHOUT the field (downgrade/rollback/client bug) must clear the stale flag.
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "w1" }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals("durableResume" in res.body, false, "still omitted from the echo");
+  assertEquals(await new DurableResumeRegistry(data).isParticipant("w1"), false, "stale true cleared");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false);
+});
+
+test("a declaration without an instance is echoed but not persisted (enrolment is per-instance)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.durableResume, true, "still echoed");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false, "nothing recorded without an instance key");
+});
+
+test("a blank/whitespace instance is echoed but not persisted (avoids a shared registry-row collision)", async () => {
+  const { data } = memDataFor(["052_worker_durable_resume.sql"]);
+  const withData = { log: noopLog(), data } as unknown as AppApi;
+  const res = (await handler(input({ capability: { cognition: "decide" }, instance: "   ", durableResume: true }), withData)) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.instance, "   ", "still echoed verbatim");
+  assertEquals(res.body.durableResume, true, "still echoed");
+  assertEquals(await new DurableResumeRegistry(data).anyParticipant(), false, "nothing recorded for a blank instance key");
+});
+
 test("enforces the shared secret when NANO_PR_WEBHOOK_SECRET is set", async () => {
   // The module captures the secret at load, so re-import a cache-busted copy with the env var set to
   // exercise the guarded 401 path and the authorized 200 path.

package/operations/enrolAgenticWorker.ts

@@ -12,13 +12,14 @@
 // NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header. Unset → open.
 import type { Capability } from "@nanobpm/agentic/protocol";
 import { resolveEnrolment } from "../app/agentic/vocab/enrol.ts";
+import { DurableResumeRegistry } from "../app/durableResume.ts";
 import { envVar } from "../app/version.ts";
 import type { EnrolResult } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
-export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
+export default defineOperation("enrolAgenticWorker", async ({ req, body }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     app.log.warn("enrolAgenticWorker rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
@@ -65,6 +66,13 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
       body: { error: "`capability.weight` must be a finite number when provided" },
     };
   }
+  // The durable-resume enrolment attribute (issue #325, ADR 0062 Slice 5/5) — a boolean the harness
+  // advertises. A directly-invoked delegate bypasses the OpenAPI runtime validation, so guard the type
+  // here (a non-boolean would corrupt the {0,1} enrolment flag the world-restore gate reads).
+  if (body.durableResume !== undefined && typeof body.durableResume !== "boolean") {
+    app.log.warn("enrolAgenticWorker rejected: non-boolean durableResume");
+    return { status: 400, body: { error: "`durableResume` must be a boolean when provided" } };
+  }
 
   // Fold a top-level `host` into the capability when the capability didn't carry its own — a worker
   // may declare its host either on the capability or beside it (ADR 0059 `{ capability, host }`).
@@ -74,6 +82,26 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
       : body.capability;
 
   const resolved = resolveEnrolment(capability);
+
+  // Durable-resume enrolment gate (issue #325, ADR 0062 Slice 5/5): record whether this worker's
+  // harness advertises durable-resume so the world-restore marker is emitted only to a fleet with a
+  // participant. Recorded per instance (ADR 0056 §7 — an enrolment attribute, never a routing token),
+  // so it needs a non-blank `instance`; a declaration without one — or with a blank/whitespace
+  // string — is echoed but not persisted (a blank key would let unrelated workers collide on the
+  // same registry row and wrongly open/close the fleet-wide durable-resume gate). Omission of the
+  // field on a re-enrol persists an explicit `false` (degrade to scratch), so a harness that previously
+  // advertised durable-resume and later re-enrols without the field clears its stale `true` rather than
+  // leaving `fleetSupportsDurableResume()` true indefinitely. Best-effort — the enrolment resolution
+  // must not fail on a registry write hiccup.
+  const instanceKey = body.instance?.trim();
+  if (app.data && instanceKey) {
+    try {
+      await new DurableResumeRegistry(app.data).recordEnrolment(instanceKey, body.durableResume ?? false);
+    } catch (err) {
+      app.log.warn("enrolAgenticWorker: durable-resume record failed", { instance: instanceKey, err: String(err) });
+    }
+  }
+
   const result: EnrolResult = {
     serve: [...resolved.serve],
     roles: resolved.roles.map((role) => {
@@ -85,6 +113,7 @@ export default defineOperation("enrolAgenticWorker", ({ req, body }, app) => {
     leaseTtl: resolved.leaseTtl,
   };
   if (body.instance !== undefined) result.instance = body.instance;
+  if (body.durableResume !== undefined) result.durableResume = body.durableResume;
 
   app.log.info("agentic enrol resolved", { instance: body.instance, serve: result.serve, family: capability.family });
   return { status: 200, body: result };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.103.0",
+  "version": "0.104.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/test/worldDb.ts

@@ -89,15 +89,27 @@ function openDataSource(db: DatabaseSync): MemDataSource {
   return ds;
 }
 
-/** A `DataLayer` stub over a fresh in-memory db with the world schema applied. */
-export function memWorldData(): { data: DataLayer; db: DatabaseSync } {
+/** A `DataLayer` stub over a fresh in-memory db with the given migration files applied (in order).
+ * The generic factory behind {@link memWorldData} — reused by tests that need a different durable
+ * table (e.g. `worker_durable_resume`, migration 052) without re-authoring the gateway/tx shim. */
+export function memDataFor(migrationFiles: readonly string[]): { data: DataLayer; db: DatabaseSync } {
   const db = new DatabaseSync(":memory:");
   openDbs.add(db);
-  const sql = readFileSync(fileURLToPath(new URL("../db/migrations/049_world_checkpoint.sql", import.meta.url)), "utf8");
-  db.exec(sql);
+  // SQLite disables FK enforcement by default; enable it so migrations with foreign keys are
+  // exercised (and FK violations surface) exactly as the migration-specific tests do.
+  db.exec("PRAGMA foreign_keys = ON;");
+  for (const file of migrationFiles) {
+    const sql = readFileSync(fileURLToPath(new URL(`../db/migrations/${file}`, import.meta.url)), "utf8");
+    db.exec(sql);
+  }
   const data = {
     table: (name: string, pk = "id") => gateway(db, name, pk),
     open: () => openDataSource(db),
   } as unknown as DataLayer;
   return { data, db };
 }
+
+/** A `DataLayer` stub over a fresh in-memory db with the world schema applied. */
+export function memWorldData(): { data: DataLayer; db: DatabaseSync } {
+  return memDataFor(["049_world_checkpoint.sql"]);
+}