@nanobpm/nano-workforce 0.162.2 → 0.163.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.163.1](https://github.com/nanobpm/nano-workforce/compare/v0.163.0...v0.163.1) (2026-08-30)
+
+### Bug Fixes
+
+* **plan:** taskless plan follows engine liveness, not empty-plan heuristic ([#624](https://github.com/nanobpm/nano-workforce/issues/624)) ([#626](https://github.com/nanobpm/nano-workforce/issues/626)) ([1dbb0d6](https://github.com/nanobpm/nano-workforce/commit/1dbb0d650c955886588a1e4caf3e8af7b150c4ca)), closes [#623](https://github.com/nanobpm/nano-workforce/issues/623) [#623](https://github.com/nanobpm/nano-workforce/issues/623) [#623](https://github.com/nanobpm/nano-workforce/issues/623)
+
+## [0.163.0](https://github.com/nanobpm/nano-workforce/compare/v0.162.2...v0.163.0) (2026-08-30)
+
+### Features
+
+* **reconcile:** engine-reset reconciliation surface for inflight work ([#622](https://github.com/nanobpm/nano-workforce/issues/622)) ([#627](https://github.com/nanobpm/nano-workforce/issues/627)) ([a10ba65](https://github.com/nanobpm/nano-workforce/commit/a10ba650829b15228e35eb45f08ecef98eff69d8)), closes [Magikcraft/nano-bpm#1065](https://github.com/Magikcraft/nano-bpm/issues/1065)
+
 ## [0.162.2](https://github.com/nanobpm/nano-workforce/compare/v0.162.1...v0.162.2) (2026-08-30)
 
 ### Bug Fixes

package/SPEC.md

@@ -283,7 +283,7 @@ child grids and a lazily-loaded transcript. The round/escalation grids are
 read-only audit. Open native user-task escalations are additionally resolved
 app-side from the **Tasks** page (`pages/tasks.page.json`, issue #236) — a nav
 tab whose per-kind `dataGrid`s list every open escalation (feature / plan-review
-/ trial-merge / PR review / blocked-run) off the `user_tasks` read-model and
+/ empty-plan / trial-merge / PR review / blocked-run) off the `user_tasks` read-model and
 submit the typed decision to the canonical human completer — so an operator no
 longer depends on Urban's read-only `taskInbox` stub at `/tasks`.
 
@@ -519,7 +519,19 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
 - **`record-plan`** — app worker `pr.record-plan`. Normalizes the tasks (assigns a
   stable `id`/index), writes one `plan_tasks` row each, sets `plans.task_count` and
   status `dispatched`, and **re-emits** the normalized `tasks` so the fan-out
-  iterates the canonical list.
+  iterates the canonical list. It also emits `taskCount`, which the `gw-plan-empty`
+  gateway reads: a taskful plan proceeds to plan-review; an **empty plan**
+  (`{tasks:[]}`) is neither auto-terminated (which rendered "Done" over a still-live
+  instance, #624) nor fed into the adversarial plan-review loop (a plan↔plan-review
+  livelock, #623) — instead it parks at the **`empty-plan-escalation`** operator user
+  task for a human directive: **Accept** a legitimate no-op epic (→ the terminal
+  `EndTasklessDone` end; the poller reconciles the COMPLETED instance to `done`) or
+  **Revise** (→ back to `plan` to re-plan, folding the operator's `notes` into
+  `planFindings` so the guidance reaches the re-plan's `appendPrompt`, mirroring
+  `plan-review-decision`). An empty plan stays NON-terminal
+  (`planning`) with its planner `note` as the `outcome` while parked — terminal
+  status follows engine liveness via `pollTasklessPlanTermination`, never the
+  empty-plan signal (#624).
 - **`implement`** — service task, job type `senior:feature`, **parallel
   multi-instance** over `=tasks` (`inputElement="task"`,
   `outputCollection="results"`). Its base prompt is delivered via the `feature.md`

package/app/agentCompletion.test.ts

@@ -257,6 +257,35 @@ test("conformance-escalation is HUMAN-completable but NOT agent-completable (iss
   assertEquals(completed[0].variables, { note: "filed follow-up" });
 });
 
+test("empty-plan-escalation is HUMAN-completable but NOT agent-completable (issues #623/#624)", async () => {
+  // The empty-plan operator decision mirrors feature-blocked/conformance: a HUMAN operator adjudicates
+  // whether an empty plan is a legitimate no-op (accept) or needs re-planning (revise), through
+  // `completeEscalationAsHuman`. It stays OUTSIDE the agent surface (`ESCALATION_TASK_ELEMENTS`) — the
+  // fleet must never silently auto-resolve the very "no work was produced" case a human must attend.
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-e", elementId: "empty-plan-escalation" }]);
+
+  const asAgent = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-e",
+    agentId: "bot",
+    variables: { directive: "accept" },
+  });
+  assertEquals(asAgent.ok, false, "the agent completer refuses empty-plan-escalation");
+  assertEquals(asAgent.reason, "not a completable task");
+  assertEquals(completed.length, 0);
+
+  const asHuman = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-e",
+    operatorId: "alice",
+    variables: { directive: "revise", notes: "look again" },
+  });
+  assertEquals(asHuman.ok, true, "the human completer retires empty-plan-escalation");
+  assertEquals(asHuman.elementId, "empty-plan-escalation");
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].variables, { directive: "revise", notes: "look again" });
+});
+
 test("human completer refuses a non-escalation user task and is a no-op for an unknown key", async () => {
   const stores = { task_completions: { rows: [] as any[], key: "id" } };
   const data = memData(stores);
@@ -543,6 +572,10 @@ test("validateEscalationVariables derives its contract from the canonical .form
   // plan-review-decision -> directive required, allowed proceed/revise
   assertEquals(validateEscalationVariables("plan-review-decision", { directive: "proceed" }), null);
   assert(validateEscalationVariables("plan-review-decision", { directive: "" }) !== null);
+  // empty-plan-escalation -> directive required, allowed accept/revise
+  assertEquals(validateEscalationVariables("empty-plan-escalation", { directive: "accept" }), null);
+  assertEquals(validateEscalationVariables("empty-plan-escalation", { directive: "revise" }), null);
+  assert(validateEscalationVariables("empty-plan-escalation", { directive: "" }) !== null);
   // an element with no linked form contract is not enforced
   assertEquals(validateEscalationVariables("some-other-task", { whatever: 1 }), null);
 });

package/app/agentCompletion.ts

@@ -24,7 +24,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
-import { ACP_PERMISSION_ELEMENT } from "./userTasks.ts";
+import { ACP_PERMISSION_ELEMENT, EMPTY_PLAN_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
 
@@ -91,6 +91,14 @@ export const FEATURE_BLOCKED_TASK_ELEMENT = "feature-blocked";
  *  `CONFORMANCE_ESCALATION_ELEMENT` (app/conformance.ts) — one source of truth, no drift surface. */
 export const CONFORMANCE_ESCALATION_TASK_ELEMENT = CONFORMANCE_ESCALATION_ELEMENT;
 
+/** The `empty-plan-escalation` operator user-task element id (plan-fanout.bpmn) — the native decision a
+ *  plan-fanout run parks on when the planner emits an EMPTY plan. Like `feature-blocked` and
+ *  `conformance-escalation` it is a HUMAN-only operator decision (never agent-answerable, or the fleet
+ *  could silently auto-resolve the very "no work was produced" case a human must adjudicate), so it
+ *  lives OUTSIDE `ESCALATION_TASK_ELEMENTS` and only the HUMAN completer accepts it (issues #623/#624).
+ *  Re-exported from the canonical `EMPTY_PLAN_ELEMENT` (app/userTasks.ts) — one source of truth. */
+export const EMPTY_PLAN_TASK_ELEMENT = EMPTY_PLAN_ELEMENT;
+
 /** The user-task `elementId`s a HUMAN operator may complete from the Tasks inbox via the one canonical
  *  `complete-user-task` door: every agent-answerable escalation PLUS the human-only `feature-blocked`
  *  and `conformance-escalation` acknowledgements, PLUS the advisory ACP permission prompt
@@ -104,6 +112,7 @@ export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   ...ESCALATION_TASK_ELEMENTS,
   FEATURE_BLOCKED_TASK_ELEMENT,
   CONFORMANCE_ESCALATION_TASK_ELEMENT,
+  EMPTY_PLAN_TASK_ELEMENT,
   ACP_PERMISSION_ELEMENT,
 ]);
 
@@ -117,6 +126,7 @@ const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
   "wait-answer": "pr-escalation",
   "wait-merge-answer": "pr-escalation",
   "feature-blocked": "feature-blocked",
+  [EMPTY_PLAN_TASK_ELEMENT]: "empty-plan-escalation",
   [CONFORMANCE_ESCALATION_TASK_ELEMENT]: "conformance-escalation",
   // NOTE: the delivery-graph `human` node (`DELIVERY_HUMAN_ELEMENT`, ADR 0005 S3) is intentionally
   // ABSENT here. Unlike the fixed-form escalations above, ONE `delivery-human-task` element is DESIGNED

package/app/enginePreflight.ts

@@ -56,7 +56,21 @@ export function resolveEngineAddress(
  * stock Camunda 8 gateway, which returns the same shape without it.
  */
 export interface TopologyProbe {
-  nano?: { engine?: string; version?: string; falconPath?: string } | null;
+  nano?:
+    | {
+        engine?: string;
+        version?: string;
+        falconPath?: string;
+        /** Monotonic incarnation / epoch id the engine stamps at boot and re-mints on a
+         *  reset/restore/rewind (companion to the versioned snapshot envelope,
+         *  Magikcraft/nano-bpm#1068). The app persists the last-seen value; a REGRESSION is the
+         *  robust "engine was reset → reconcile" signal (issue #622, app/reconcile.ts). */
+        incarnation?: number | string;
+        /** Alias for {@link incarnation} — accepted so the app tolerates either spelling the engine
+         *  status endpoint settles on without a code change. */
+        epoch?: number | string;
+      }
+    | null;
   gatewayVersion?: string;
 }
 

package/app/epicPhase.test.ts

@@ -15,6 +15,8 @@ test("deriveEpicPhase maps each spine element to its domain phase", () => {
   assertEquals(deriveEpicPhase("review-plan"), EPIC_PHASE.REVIEWING);
   assertEquals(deriveEpicPhase("record-plan-review"), EPIC_PHASE.REVIEWING);
   assertEquals(deriveEpicPhase("plan-review-decision"), EPIC_PHASE.REVIEWING);
+  // The empty-plan operator escalation (gw-plan-empty) is a planning-stage decision (Accept/Revise).
+  assertEquals(deriveEpicPhase("empty-plan-escalation"), EPIC_PHASE.PLANNING);
   // Trial-merge band.
   assertEquals(deriveEpicPhase("trial-merge"), EPIC_PHASE.TRIAL_MERGING);
   assertEquals(deriveEpicPhase("record-trial-merge"), EPIC_PHASE.TRIAL_MERGING);

package/app/epicPhase.ts

@@ -107,6 +107,7 @@ const ELEMENT_PHASE: Readonly<Record<string, string>> = {
   "ensure-base-branch": EPIC_PHASE.PLANNING,
   "plan": EPIC_PHASE.PLANNING,
   "record-plan": EPIC_PHASE.REVIEWING,
+  "empty-plan-escalation": EPIC_PHASE.PLANNING,
   "review-plan": EPIC_PHASE.REVIEWING,
   "record-plan-review": EPIC_PHASE.REVIEWING,
   "plan-review-decision": EPIC_PHASE.REVIEWING,

package/app/instanceTracking.ts

@@ -63,6 +63,23 @@ export function activeStatusesFor(table: string): readonly string[] {
   return binding.activeStatuses;
 }
 
+/** A tracked table's engine-instance key column (the `keyField` in nano.app.json — e.g.
+ *  `process_key`), the single source of truth the app-side reconcile probes/orphans by so it can
+ *  never drift from the reconciler's notion of "which column holds the engine instance key". */
+export function keyFieldFor(table: string): string {
+  return trackingBindingFor(table).keyField;
+}
+
+/** Every `instanceTracking` binding — the full registry of ENGINE-BACKED base tables (each row is
+ *  projected off a live engine process instance keyed by `keyField`). The app-side engine-reset
+ *  reconcile (app/reconcile.ts) scans exactly this set: a row whose `statusField` is still in the
+ *  binding's `activeStatuses` and whose `keyField` is populated is non-terminal engine-backed work,
+ *  the only surface reconcile may drive to `orphaned`. Terminal rows and non-engine-backed surfaces
+ *  (presence, append-only audit) are, by construction, not in this set and are never touched. */
+export function engineBackedBindings(): readonly InstanceTracking[] {
+  return INSTANCE_TRACKING_BINDINGS;
+}
+
 /** The managed derived read-model VIEW name + effective-status column for a base table, resolved by
  *  urban's OWN target resolver so the app never drifts from the framework's `<table>__tracking` /
  *  `derived_status` naming (ADR 0065). */

package/app/pollTasklessPlanTermination.test.ts

@@ -0,0 +1,188 @@
+// Coverage for `pollTasklessPlanTermination` (issue #624) — the poll pass that owns a TASKLESS plan's
+// COMPLETED → `done` transition from ENGINE truth, so terminal `plans.status` follows engine instance
+// liveness instead of the retired "record-plan with task_count = 0 ⇒ done" heuristic (which rendered
+// the epic "Done" over a still-active, in fact looping, plan-fanout instance).
+//
+// Booted against the real provisioned SQLite data layer (so the `plans` table exists) with a stubbed
+// `searchProcessInstances`, proving: a taskless plan whose instance is STILL ACTIVE stays non-terminal
+// (the core acceptance guarantee); it flips to `done` only once the instance reads COMPLETED; a
+// TASKFUL plan is never touched (its `record-results` finalizer owns `done`); a plan with no engine
+// instance is skipped; and an already-`done` plan is left alone.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { bootTestApp } from "@nanobpm/urban-testkit";
+import { plans } from "./plan.ts";
+import { pollTasklessPlanTermination } from "./service.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+async function withData(fn: (data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-taskless-term-"));
+  const app = await bootTestApp(APP_ROOT, { env: { NANO_APP_DB_URL: `file:${join(dir, "app.db")}` } });
+  try {
+    await fn(app.db);
+  } finally {
+    await app.stop?.();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const now = () => new Date().toISOString();
+
+async function seedPlan(
+  data: DataLayer,
+  over: { status?: string; process_key?: string | null; task_count?: number; outcome?: string | null } = {},
+) {
+  await plans(data).insert({
+    plan_key: "owner/repo#7",
+    repo: "owner/repo",
+    issue_number: 7,
+    issue_url: "https://github.com/owner/repo/issues/7",
+    title: "Epic",
+    status: over.status ?? "planning",
+    task_count: over.task_count ?? 0,
+    outcome: "outcome" in over ? over.outcome : "planner emitted no tasks",
+    process_key: "process_key" in over ? over.process_key : "pi-1",
+    created_at: now(),
+    updated_at: now(),
+  } as never);
+}
+
+test("pollTasklessPlanTermination leaves a taskless plan NON-terminal while its instance is ACTIVE", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "planning", task_count: 0 });
+    const engine = { searchProcessInstances: async () => [{ processInstanceKey: "pi-1", state: "ACTIVE" }] };
+    await pollTasklessPlanTermination(data, engine as never);
+    // The core acceptance guarantee: a task_count = 0 plan is not terminal while its instance runs.
+    assertEquals((await plans(data).get("owner/repo#7"))?.status, "planning");
+  });
+});
+
+test("pollTasklessPlanTermination flips a taskless plan to done once its instance reads COMPLETED", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "planning", task_count: 0 });
+    const engine = { searchProcessInstances: async () => [{ processInstanceKey: "pi-1", state: "COMPLETED" }] };
+    await pollTasklessPlanTermination(data, engine as never);
+    const row = await plans(data).get("owner/repo#7");
+    assertEquals(row?.status, "done");
+    assertEquals(row?.outcome, "planner emitted no tasks");
+  });
+});
+
+test("pollTasklessPlanTermination matches a numeric engine processInstanceKey against the string process_key", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "planning", task_count: 0, process_key: "12345" });
+    const engine = { searchProcessInstances: async () => [{ processInstanceKey: 12345, state: "COMPLETED" }] };
+    await pollTasklessPlanTermination(data, engine as never);
+    assertEquals((await plans(data).get("owner/repo#7"))?.status, "done");
+  });
+});
+
+test("pollTasklessPlanTermination never touches a TASKFUL plan (record-results owns its done)", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "dispatched", task_count: 3, outcome: null });
+    let called = false;
+    const engine = {
+      searchProcessInstances: async () => {
+        called = true;
+        return [{ processInstanceKey: "pi-1", state: "COMPLETED" }];
+      },
+    };
+    await pollTasklessPlanTermination(data, engine as never);
+    assertEquals(called, false);
+    assertEquals((await plans(data).get("owner/repo#7"))?.status, "dispatched");
+  });
+});
+
+test("pollTasklessPlanTermination skips a taskless plan that has no engine instance yet", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "planning", task_count: 0, process_key: null });
+    let called = false;
+    const engine = {
+      searchProcessInstances: async () => {
+        called = true;
+        return [];
+      },
+    };
+    await pollTasklessPlanTermination(data, engine as never);
+    assertEquals(called, false);
+    assertEquals((await plans(data).get("owner/repo#7"))?.status, "planning");
+  });
+});
+
+test("pollTasklessPlanTermination never re-touches an already-terminal plan", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "done", task_count: 0 });
+    let called = false;
+    const engine = {
+      searchProcessInstances: async () => {
+        called = true;
+        return [];
+      },
+    };
+    await pollTasklessPlanTermination(data, engine as never);
+    // `done` is not in EPIC_LIVE_STATUSES, so the pass never queries the engine for it.
+    assertEquals(called, false);
+  });
+});
+
+// A taskless plan whose instance TERMINATED out of band keeps its base `status = planning` (the
+// worker-owned transient the reconciler no longer overwrites) while the ADR-0065 tracking VIEW folds
+// its `derived_status` to `abandoned`. A base-`status` scan would keep re-querying the engine for that
+// already-dead row every pass forever; the pass MUST read `derived_status` off `plansTracking` and skip
+// it. Modelled with the `withTrackingViews` fake so the base `status` and derived `derived_status`
+// diverge exactly as the real terminated instance produces, without a live engine.
+// biome-ignore lint/suspicious/noExplicitAny: test-only fake over dynamic row shapes.
+function trackedMemData(): DataLayer {
+  // biome-ignore lint/suspicious/noExplicitAny: test-only dynamic row store.
+  const store: any[] = [];
+  const tbl = (_name: string, pk = "plan_key") => ({
+    // biome-ignore lint/suspicious/noExplicitAny: test-only dynamic row.
+    async insert(row: any) {
+      store.push({ ...row });
+      return row[pk];
+    },
+    async get(key: unknown) {
+      return store.find((r) => r[pk] === key);
+    },
+    async find(where: Record<string, unknown>) {
+      return store.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only patch.
+    async update(key: unknown, patch: any) {
+      const r = store.find((x) => x[pk] === key);
+      if (r) Object.assign(r, patch);
+    },
+  });
+  // biome-ignore lint/suspicious/noExplicitAny: test-only fake DataLayer.
+  return { table: withTrackingViews((n: string, pk?: string) => tbl(n, pk)) } as any as DataLayer;
+}
+
+test("pollTasklessPlanTermination skips a derive-only-terminal (TERMINATED) taskless plan without querying the engine", async () => {
+  const data = trackedMemData();
+  // Base `status` still reads live `planning` (frozen transient), but the instance terminated out of
+  // band so the tracking VIEW's `derived_status` is `abandoned`.
+  await plans(data).insert({
+    plan_key: "owner/repo#7",
+    status: "planning",
+    derived_status: "abandoned",
+    task_count: 0,
+    process_key: "pi-1",
+  } as never);
+  let called = false;
+  const engine = {
+    searchProcessInstances: async () => {
+      called = true;
+      return [{ processInstanceKey: "pi-1", state: "COMPLETED" }];
+    },
+  };
+  await pollTasklessPlanTermination(data, engine as never);
+  // The regression guard: a base-status scan would re-query the engine here forever.
+  assertEquals(called, false);
+  assertEquals((await plans(data).get("owner/repo#7"))?.status, "planning");
+});

package/app/reconcile.test.ts

@@ -0,0 +1,212 @@
+// Red/green coverage for the app-side engine-reset reconciliation surface (issue #622).
+//
+// The core scenario the incident (Magikcraft/nano-bpm#1065) demanded a supported remedy for: the
+// engine is reset and its incarnation epoch REGRESSES, while `app.db` still projects engine-backed
+// inflight work (an active `feature_runs`/`delivery_graph_runs`/… row keyed on a now-dead
+// `process_key`). Reconcile must drive exactly those rows to the defined `orphaned` terminal WITH
+// PROVENANCE, leave terminal history + non-engine-backed rows untouched, and be idempotent.
+//
+// These run against the REAL migration set (092 applied to an in-memory SQLite via urban's own
+// `makeGateway`), so the tables/columns/indexes reconcile reads and writes are the shipping schema.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { freshData } from "../test/reconcileDb.ts";
+import {
+  ORPHANED_STATUS,
+  parseEngineEpoch,
+  RECONCILE_ORPHAN_REASON,
+  reconcileEngineBackedWork,
+} from "./reconcile.ts";
+
+const AT = () => new Date("2026-02-02T00:00:00.000Z");
+
+function seedFeatureRun(raw: DatabaseSync, key: string, status: string, processKey: string | null): void {
+  raw
+    .prepare(
+      `INSERT INTO feature_runs (feature_key, repo, issue_number, issue_url, base_branch, status, process_key, created_at, updated_at)
+       VALUES (?, 'o/r', 1, 'https://x', 'main', ?, ?, '2026-01-01', '2026-01-01')`,
+    )
+    .run(key, status, processKey);
+}
+
+function seedDeliveryGraphRun(raw: DatabaseSync, runKey: string, status: string, processKey: string | null): void {
+  raw
+    .prepare(
+      `INSERT INTO delivery_graph_runs (run_key, process_key, digest, status, created_at, updated_at)
+       VALUES (?, ?, 'deadbeef', ?, '2026-01-01', '2026-01-01')`,
+    )
+    .run(runKey, processKey, status);
+}
+
+test("parseEngineEpoch reads nano.incarnation (or its epoch alias), else null", () => {
+  assertEquals(parseEngineEpoch({ nano: { incarnation: 7 } }), 7);
+  assertEquals(parseEngineEpoch({ nano: { epoch: "9" } }), 9);
+  assertEquals(parseEngineEpoch({ nano: { engine: "nano" } }), null);
+  assertEquals(parseEngineEpoch({ gatewayVersion: "8.6" }), null);
+  assertEquals(parseEngineEpoch(null), null);
+});
+
+test("first observation SEEDS the epoch without orphaning anything", async () => {
+  const { data, raw } = freshData();
+  seedFeatureRun(raw, "o/r#1", "running", "pk-1");
+
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 5 }, { now: AT, runId: "run-seed" });
+
+  assertEquals(res.reason, "seed-epoch");
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(row.status, "running");
+  const rec = raw.prepare("SELECT epoch FROM engine_incarnation WHERE id=1").get() as { epoch: number };
+  assertEquals(rec.epoch, 5);
+});
+
+test("RED→GREEN: an epoch regression orphans dangling inflight rows with provenance", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+  seedDeliveryGraphRun(raw, "graph-1", "running", "77");
+
+  // The engine was reset/rewound: its incarnation epoch regressed 10 → 2.
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(res.reason, "epoch-regression");
+  assertEquals(res.orphanedCount, 2);
+
+  const fr = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(fr.status, ORPHANED_STATUS);
+  const dg = raw.prepare("SELECT status FROM delivery_graph_runs WHERE run_key='graph-1'").get() as { status: string };
+  assertEquals(dg.status, ORPHANED_STATUS);
+
+  const prov = raw
+    .prepare("SELECT * FROM reconcile_provenance WHERE source_table='feature_runs'")
+    .get() as Record<string, unknown>;
+  assertEquals(prov.to_status, ORPHANED_STATUS);
+  assertEquals(prov.from_status, "running");
+  assertEquals(prov.reason, RECONCILE_ORPHAN_REASON);
+  assertEquals(prov.observed_epoch, 2);
+  assertEquals(prov.run_id, "run-1");
+  assertEquals(prov.key_value, "41");
+
+  const run = raw.prepare("SELECT reason, orphaned_count FROM reconcile_runs WHERE run_id='run-1'").get() as {
+    reason: string;
+    orphaned_count: number;
+  };
+  assertEquals(run.reason, "epoch-regression");
+  assertEquals(run.orphaned_count, 2);
+  const rec = raw.prepare("SELECT epoch FROM engine_incarnation WHERE id=1").get() as { epoch: number };
+  assertEquals(rec.epoch, 2);
+});
+
+test("terminal history and rows without a process_key are NEVER touched", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "term#1", "merged", "88"); // terminal — not in activeStatuses
+  seedFeatureRun(raw, "await#1", "opened", "89"); // terminal-for-tracking
+  seedFeatureRun(raw, "nokeed#1", "running", null); // active but no engine key
+
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(res.orphanedCount, 0);
+  const statuses = raw.prepare("SELECT feature_key, status FROM feature_runs ORDER BY feature_key").all() as {
+    feature_key: string;
+    status: string;
+  }[];
+  assertEquals(statuses.find((r) => r.feature_key === "term#1")?.status, "merged");
+  assertEquals(statuses.find((r) => r.feature_key === "await#1")?.status, "opened");
+  assertEquals(statuses.find((r) => r.feature_key === "nokeed#1")?.status, "running");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
+
+test("idempotent: a second pass with a matching epoch is a no-op", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+
+  const first = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+  assertEquals(first.orphanedCount, 1);
+
+  const second = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-2" });
+  assertEquals(second.reason, "no-op");
+  assertEquals(second.orphanedCount, 0);
+
+  const provCount = raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number };
+  assertEquals(provCount.c, 1);
+});
+
+test("an unreachable engine is a hard no-op — live work is never orphaned", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+
+  const res = await reconcileEngineBackedWork(data, { reachable: false, epoch: null }, { now: AT, runId: "run-1" });
+  assertEquals(res.reason, "engine-unreachable");
+  assertEquals(res.orphanedCount, 0);
+
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(row.status, "running");
+  const run = raw.prepare("SELECT reason FROM reconcile_runs WHERE run_id='run-1'").get() as { reason: string };
+  assertEquals(run.reason, "engine-unreachable");
+});
+
+test("RED→GREEN: a concurrent terminal transition wins — the guarded UPDATE never clobbers it", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+
+  // Interpose a writer that flips the row to a newer terminal status AFTER reconcile has SELECTed it
+  // as "running" but BEFORE its UPDATE lands — the exact TOCTOU window. With a blind UPDATE-by-pk the
+  // reset would clobber `merged` back to `orphaned` (and write provenance); the guarded UPDATE (status
+  // re-asserted) sees `res.changed === 0` and leaves the terminal history untouched.
+  const gw = data.open();
+  let raced = false;
+  const wrapTx = (t: { query: (...a: unknown[]) => unknown; exec: (sql: string, params?: unknown[]) => unknown }) => ({
+    query: (...a: unknown[]) => t.query(...a),
+    exec: (sql: string, params?: unknown[]) => {
+      if (!raced && /^UPDATE/.test(sql.trim())) {
+        raced = true;
+        raw.prepare("UPDATE feature_runs SET status='merged' WHERE feature_key='o/r#1'").run();
+      }
+      return t.exec(sql, params);
+    },
+  });
+  const wrappedSrc = {
+    query: (...a: unknown[]) => (gw as { query: (...a: unknown[]) => unknown }).query(...a),
+    exec: (sql: string, params?: unknown[]) => (gw as { exec: (sql: string, params?: unknown[]) => unknown }).exec(sql, params),
+    tx: (fn: (t: unknown) => unknown) => (gw as { tx: (f: (t: unknown) => unknown) => unknown }).tx((t) => fn(wrapTx(t as never))),
+  };
+  const wrapped = { open: () => wrappedSrc } as unknown as DataLayer;
+
+  const res = await reconcileEngineBackedWork(wrapped, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(raced, true);
+  assertEquals(res.orphanedCount, 0);
+  const row = raw.prepare("SELECT status FROM feature_runs WHERE feature_key='o/r#1'").get() as { status: string };
+  assertEquals(row.status, "merged");
+  assertEquals((raw.prepare("SELECT COUNT(*) c FROM reconcile_provenance").get() as { c: number }).c, 0);
+});
+
+test("RED→GREEN: orphaning stamps updated_at so the transition timestamp isn't left stale", async () => {
+  const { data, raw } = freshData();
+  await reconcileEngineBackedWork(data, { reachable: true, epoch: 10 }, { now: AT, runId: "run-0" });
+  seedFeatureRun(raw, "o/r#1", "running", "41");
+  seedDeliveryGraphRun(raw, "graph-1", "running", "77");
+
+  // The seeded rows carry updated_at='2026-01-01'; AT() (the reconcile clock) is 2026-02-02. A blind
+  // `SET status='orphaned'` would leave updated_at at the stale seed value, misrepresenting when the
+  // row was orphaned to the UI/audits. The transition must refresh updated_at like every other one.
+  const res = await reconcileEngineBackedWork(data, { reachable: true, epoch: 2 }, { now: AT, runId: "run-1" });
+
+  assertEquals(res.orphanedCount, 2);
+  const at = AT().toISOString();
+  const fr = raw
+    .prepare("SELECT status, updated_at FROM feature_runs WHERE feature_key='o/r#1'")
+    .get() as { status: string; updated_at: string };
+  assertEquals(fr.status, ORPHANED_STATUS);
+  assertEquals(fr.updated_at, at);
+  const dg = raw
+    .prepare("SELECT status, updated_at FROM delivery_graph_runs WHERE run_key='graph-1'")
+    .get() as { status: string; updated_at: string };
+  assertEquals(dg.status, ORPHANED_STATUS);
+  assertEquals(dg.updated_at, at);
+});