@nanobpm/nano-workforce 0.162.2 → 0.163.1

package/app/reconcile.ts

@@ -0,0 +1,326 @@
+// nano-workforce — the app-side engine-reset reconciliation surface (issue #622).
+//
+// When the Nano engine is reset, restored, or rolled to an incarnation whose key generator has
+// rewound (Magikcraft/nano-bpm#1065), `app.db` keeps projecting ENGINE-BACKED inflight work that no
+// longer exists on the engine: open user tasks pointing at dead instances, active runs keyed on a
+// `process_key` the fresh engine has re-minted for something unrelated (the release-train run
+// recorded `process_key=41`; the fresh engine re-minted 41 for an unrelated probe). Without a
+// supported way to converge, the app silently trusts stale projections — orphaned human gates and
+// key-collision identity confusion.
+//
+// `reconcile` is the first-class remedy. It runs ON STARTUP (main.ts) and ON DEMAND (the
+// `reconcileEngineState` operator command), scoped NARROWLY to claimed inflight work:
+//
+//   • Detection — engine INCARNATION EPOCH (preferred over fragile per-key 404 probing). The engine
+//     stamps a monotonic incarnation id at boot and exposes it on `/v2/topology`; the app persists
+//     the last-seen value (`engine_incarnation`). An epoch REGRESSION (observed < recorded) — the
+//     #1065 rewind signature — or its absence where one was recorded means "engine was reset/rewound
+//     → reconcile", ONE cheap check instead of N per-instance probes.
+//   • Convergence — for every NON-terminal, engine-backed app row (a nano.app.json instanceTracking
+//     binding whose `statusField` is still in its `activeStatuses` set and whose `keyField` is
+//     populated), drive the row to the defined `orphaned` terminal WITH PROVENANCE
+//     (`reconcile_provenance`: the reason, the observed engine epoch, and the reconcile run id) —
+//     instead of trusting a stale projection or silently dropping data.
+//   • Guardrails — TERMINAL rows (done/failed/merged/abandoned/…) and append-only / non-engine-backed
+//     surfaces (presence, audit, provenance) are NEVER mutated: reconcile only touches rows whose
+//     status is in a binding's `activeStatuses`. Every pass is recorded in `reconcile_runs`.
+//   • Idempotent — a second pass with a matching epoch is a no-op (nothing regressed, and every
+//     already-orphaned row has left its `activeStatuses`, so it is not re-scanned). An UNREACHABLE
+//     engine is a no-op too: reconcile NEVER orphans when it could not confirm a reset (a 401/5xx or
+//     a network error yields `reachable:false`, not a false "engine missing").
+//
+// The provenance is app-owned (not urban's `_urban_write_provenance`, which is a domain-free
+// insert-join sidecar written only inside a job): reconcile runs at boot / over HTTP, outside any
+// job, and needs to record the REASON + epoch + run id — which the app-owned `reconcile_provenance`
+// table carries, and the existing `app.db` backup convention makes the whole mutation reversible.
+
+import type { DataLayer, GatewayDataSource as DataSource } from "@nanobpm/urban";
+import type { TopologyProbe } from "./enginePreflight.ts";
+import { activeStatusesFor, baseStatusFieldFor, engineBackedBindings, keyFieldFor } from "./instanceTracking.ts";
+
+/** The defined terminal state a reset-orphaned engine-backed row is driven to. Deliberately DISTINCT
+ *  from a binding's natural terminal (`abandoned`/`failed`/…) so an operator can tell a row that was
+ *  orphaned by an engine reset apart from one that drained normally. Not in any binding's
+ *  `activeStatuses`, so an orphaned row is never re-scanned (idempotency) nor re-polled by the urban
+ *  instance-tracking reconciler. */
+export const ORPHANED_STATUS = "orphaned";
+
+/** The provenance reason stamped on every orphaned transition: the engine was reset/rewound and the
+ *  recorded incarnation epoch regressed (the #1065 signature). */
+export const RECONCILE_ORPHAN_REASON = "engine-reset/epoch-regression";
+
+/** The single-row epoch ledger + its append-only run/provenance sidecars (migration 092). */
+const INCARNATION_TABLE = "engine_incarnation";
+const RUNS_TABLE = "reconcile_runs";
+const PROVENANCE_TABLE = "reconcile_provenance";
+/** The conventional last-touched timestamp column stamped on every status transition; orphaning
+ *  refreshes it too, but only on the tables that actually declare it (introspected per binding). */
+const UPDATED_AT_COLUMN = "updated_at";
+
+/** What a `/v2/topology` epoch probe observed. `reachable:false` means the engine could not be
+ *  confirmed (network error, or a non-2xx like 401/5xx) — reconcile then does NOTHING, so a
+ *  transient outage can never be mistaken for a reset and orphan live work. `reachable:true` with a
+ *  null `epoch` means the engine answered but exposes no incarnation id (e.g. a stock Camunda 8
+ *  gateway, or before Magikcraft/nano-bpm#1068 ships). That null is a no-op ONLY when no epoch was
+ *  ever recorded; if a concrete epoch WAS recorded, a now-null observation reads as a regression
+ *  ("the epoch disappeared" — the reset signature), so reconcile orphans inflight work. See the
+ *  decision table on {@link reconcileEngineBackedWork}. */
+export interface EngineEpochObservation {
+  reachable: boolean;
+  epoch: number | null;
+}
+
+/** Why a reconcile pass acted (or did not). */
+export type ReconcileReason = "epoch-regression" | "seed-epoch" | "no-op" | "engine-unreachable";
+
+/** One orphaned engine-backed row. */
+export interface OrphanedRow {
+  table: string;
+  pk: string;
+  key: string | null;
+  fromStatus: string;
+}
+
+/** The outcome of one reconcile pass — the same shape the run row records and the operator command
+ *  returns. */
+export interface ReconcileResult {
+  runId: string;
+  reason: ReconcileReason;
+  observedEpoch: number | null;
+  recordedEpoch: number | null;
+  orphanedCount: number;
+  orphaned: OrphanedRow[];
+}
+
+export interface ReconcileLog {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+export interface ReconcileOptions {
+  /** Injectable clock (defaults to `Date`), so tests are deterministic. */
+  now?: () => Date;
+  /** Injectable run id (defaults to a random UUID). */
+  runId?: string;
+  /** The data source name to reconcile (defaults to the DataLayer's default source). */
+  sourceName?: string;
+  log?: ReconcileLog;
+}
+
+/** Read the incarnation epoch out of a `/v2/topology` body — `nano.incarnation` (or its `epoch`
+ *  alias), coerced from a number or a numeric string. Any other shape (absent, non-numeric) yields
+ *  null: "the engine exposes no epoch". A null is a no-op ONLY when no epoch was previously recorded;
+ *  when one WAS recorded, reconcile reads a now-null observation as a regression ("epoch disappeared"),
+ *  not a no-op — see the decision table on {@link reconcileEngineBackedWork}. */
+export function parseEngineEpoch(body: TopologyProbe | null | undefined): number | null {
+  const raw = body?.nano?.incarnation ?? body?.nano?.epoch;
+  if (raw == null) return null;
+  const n = typeof raw === "number" ? raw : Number(raw);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Probe `/v2/topology` for the engine incarnation epoch. Never throws: a network error or a non-2xx
+ *  yields `reachable:false` (reconcile then does nothing), so an outage can never orphan live work. */
+export async function probeEngineEpoch(
+  restAddress: string,
+  opts: { token?: string; fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<EngineEpochObservation> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const url = `${restAddress.replace(/\/+$/, "")}/topology`;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (opts.token) headers.authorization = `Bearer ${opts.token}`;
+  try {
+    const res = await fetchImpl(url, {
+      headers,
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 3000),
+    });
+    if (!res.ok) return { reachable: false, epoch: null };
+    const body: TopologyProbe = await res.json();
+    return { reachable: true, epoch: parseEngineEpoch(body) };
+  } catch {
+    return { reachable: false, epoch: null };
+  }
+}
+
+/** Double-quote a SQL identifier (table/column) so a manifest-declared name is safe to interpolate. */
+function q(id: string): string {
+  return `"${id.replace(/"/g, '""')}"`;
+}
+
+/** The schema of `table` we need to orphan a row: its primary-key column (the first `pk`-flagged
+ *  column from `PRAGMA table_info`, or `rowid` when the table declares none — so provenance always
+ *  records a stable row identity) and whether it carries an `updated_at` column to stamp. */
+async function tableShape(src: DataSource, table: string): Promise<{ pkCol: string; hasUpdatedAt: boolean }> {
+  const cols = await src.query<{ name: string; pk: number }>(`PRAGMA table_info(${q(table)})`);
+  const pk = cols.find((c) => Number(c.pk) > 0);
+  return { pkCol: pk?.name ?? "rowid", hasUpdatedAt: cols.some((c) => c.name === UPDATED_AT_COLUMN) };
+}
+
+/** The recorded last-seen epoch, or null when none was ever recorded (no row, or a null epoch). */
+async function readRecordedEpoch(src: DataSource): Promise<number | null> {
+  const rows = await src.query<{ epoch: number | null }>(
+    `SELECT epoch FROM ${INCARNATION_TABLE} WHERE id = 1`,
+  );
+  const epoch = rows.length ? rows[0].epoch : null;
+  return epoch == null ? null : Number(epoch);
+}
+
+/** Persist (seed or advance) the last-seen epoch. Only ever called with a concrete number, so a
+ *  recorded epoch always means "an epoch was actually observed". */
+async function persistEpoch(src: DataSource, epoch: number, at: string): Promise<void> {
+  await src.exec(
+    `INSERT INTO ${INCARNATION_TABLE} (id, epoch, observed_at) VALUES (1, ?, ?) ` +
+      `ON CONFLICT(id) DO UPDATE SET epoch = excluded.epoch, observed_at = excluded.observed_at`,
+    [epoch, at],
+  );
+}
+
+/** Orphan every NON-terminal, engine-backed row across all instanceTracking bindings, recording one
+ *  `reconcile_provenance` row per transition. Runs inside the caller's transaction. */
+async function orphanEngineBackedRows(
+  src: DataSource,
+  runId: string,
+  observedEpoch: number | null,
+  at: string,
+): Promise<OrphanedRow[]> {
+  const orphaned: OrphanedRow[] = [];
+  for (const binding of engineBackedBindings()) {
+    const table = binding.table;
+    // A binding with no active-status selector cannot classify "in-flight" — skip it rather than
+    // guess (activeStatusesFor would throw; we tolerate a selector-less binding).
+    if (!binding.activeStatuses?.length) continue;
+    const active = activeStatusesFor(table);
+    const statusField = baseStatusFieldFor(table);
+    const keyField = keyFieldFor(table);
+    const { pkCol, hasUpdatedAt } = await tableShape(src, table);
+    const placeholders = active.map(() => "?").join(", ");
+    const rows = await src.query<{ __pk: unknown; __key: unknown; __status: unknown }>(
+      `SELECT ${q(pkCol)} AS __pk, ${q(keyField)} AS __key, ${q(statusField)} AS __status ` +
+        `FROM ${q(table)} WHERE ${q(statusField)} IN (${placeholders}) AND ${q(keyField)} IS NOT NULL`,
+      [...active],
+    );
+    for (const row of rows) {
+      const pk = String(row.__pk);
+      const key = row.__key == null ? null : String(row.__key);
+      const fromStatus = String(row.__status);
+      // GUARDED update: re-assert the exact status we read AND a populated key, so a writer that
+      // flipped the row to a newer terminal status (or cleared its key) between the SELECT above and
+      // this UPDATE wins the race — we never clobber that terminal history back to `orphaned`. Only a
+      // row we actually transitioned (`res.changed > 0`) gets provenance and is counted. We also stamp
+      // `updated_at` (when the table has one) so the transition to `orphaned` refreshes the row's
+      // timestamp the same way every other status transition in the codebase does — leaving it stale
+      // would misrepresent the orphaning moment to the UI/audits.
+      const res = await src.exec(
+        `UPDATE ${q(table)} SET ${q(statusField)} = ?` +
+          (hasUpdatedAt ? `, ${q(UPDATED_AT_COLUMN)} = ?` : "") +
+          ` WHERE ${q(pkCol)} = ? AND ${q(statusField)} = ? AND ${q(keyField)} IS NOT NULL`,
+        hasUpdatedAt
+          ? [ORPHANED_STATUS, at, row.__pk, fromStatus]
+          : [ORPHANED_STATUS, row.__pk, fromStatus],
+      );
+      if (res.changed <= 0) continue;
+      await src.exec(
+        `INSERT INTO ${PROVENANCE_TABLE} ` +
+          `(run_id, source_table, pk_value, key_value, from_status, to_status, reason, observed_epoch, at) ` +
+          `VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        [runId, table, pk, key, fromStatus, ORPHANED_STATUS, RECONCILE_ORPHAN_REASON, observedEpoch, at],
+      );
+      orphaned.push({ table, pk, key, fromStatus });
+    }
+  }
+  return orphaned;
+}
+
+/**
+ * Reconcile the app's engine-backed projections against one epoch observation. Pure of I/O beyond the
+ * data layer (the topology probe is {@link probeEngineEpoch}, injected as `observation`), so the
+ * red/green test drives it with a seeded row + a regressed epoch directly.
+ *
+ * Decision table (engine reachable):
+ *   • recorded != null AND (observed == null OR observed < recorded)  → REGRESSION: orphan inflight.
+ *   • recorded == null AND observed != null                          → SEED: first epoch learned.
+ *   • otherwise                                                       → NO-OP (incl. a matching epoch).
+ * The epoch is persisted whenever a concrete one was observed (seed, advance, or the fresh
+ * post-rewind incarnation), so the very next pass with that same epoch is a pure no-op.
+ *
+ * This surface is deliberately EPOCH-SCOPED: it only ever acts on the epoch signal. An engine that
+ * is reachable but exposes NO epoch and for which none was ever recorded (observed == null AND
+ * recorded == null) is, by contract, an intentional no-op — we have no reset signal to act on, and
+ * we never orphan live work speculatively. Converging engine-backed rows against an engine with no
+ * epoch support (e.g. via a per-instance existence probe) is out of contract for this surface.
+ */
+export async function reconcileEngineBackedWork(
+  data: DataLayer,
+  observation: EngineEpochObservation,
+  opts: ReconcileOptions = {},
+): Promise<ReconcileResult> {
+  const src = data.open(opts.sourceName);
+  const at = (opts.now?.() ?? new Date()).toISOString();
+  const runId = opts.runId ?? crypto.randomUUID();
+
+  // An unreachable engine is a hard no-op: we could not confirm a reset, so we NEVER orphan.
+  if (!observation.reachable) {
+    const recorded = await readRecordedEpoch(src);
+    await recordRun(src, { runId, at, observedEpoch: null, recordedEpoch: recorded, reason: "engine-unreachable", orphanedCount: 0 });
+    opts.log?.warn("reconcile: engine unreachable — skipped (no rows orphaned; live work left intact).");
+    return { runId, reason: "engine-unreachable", observedEpoch: null, recordedEpoch: recorded, orphanedCount: 0, orphaned: [] };
+  }
+
+  const observedEpoch = observation.epoch;
+  const recordedEpoch = await readRecordedEpoch(src);
+  const regression = recordedEpoch != null && (observedEpoch == null || observedEpoch < recordedEpoch);
+
+  const result = await src.tx(async (t) => {
+    let orphaned: OrphanedRow[] = [];
+    let reason: ReconcileReason;
+    if (regression) {
+      orphaned = await orphanEngineBackedRows(t, runId, observedEpoch, at);
+      reason = "epoch-regression";
+    } else if (recordedEpoch == null && observedEpoch != null) {
+      reason = "seed-epoch";
+    } else {
+      reason = "no-op";
+    }
+    if (observedEpoch != null) await persistEpoch(t, observedEpoch, at);
+    await recordRun(t, { runId, at, observedEpoch, recordedEpoch, reason, orphanedCount: orphaned.length });
+    return { reason, orphaned };
+  });
+
+  if (result.reason === "epoch-regression") {
+    opts.log?.warn(
+      `reconcile: engine epoch regressed ${recordedEpoch} → ${observedEpoch} (reset/rewind) — ` +
+        `orphaned ${result.orphaned.length} inflight row(s) [run ${runId}].`,
+    );
+  } else if (result.reason === "seed-epoch") {
+    opts.log?.info(`reconcile: recorded engine epoch ${observedEpoch} (first observation) [run ${runId}].`);
+  } else {
+    opts.log?.info(`reconcile: engine epoch ${observedEpoch ?? "n/a"} unchanged — no-op [run ${runId}].`);
+  }
+
+  return { runId, reason: result.reason, observedEpoch, recordedEpoch, orphanedCount: result.orphaned.length, orphaned: result.orphaned };
+}
+
+async function recordRun(
+  src: DataSource,
+  run: { runId: string; at: string; observedEpoch: number | null; recordedEpoch: number | null; reason: ReconcileReason; orphanedCount: number },
+): Promise<void> {
+  await src.exec(
+    `INSERT INTO ${RUNS_TABLE} (run_id, started_at, observed_epoch, recorded_epoch, reason, orphaned_count) ` +
+      `VALUES (?, ?, ?, ?, ?, ?)`,
+    [run.runId, run.at, run.observedEpoch, run.recordedEpoch, run.reason, run.orphanedCount],
+  );
+}
+
+/** Probe the engine's incarnation epoch, then reconcile — the wiring both startup (main.ts) and the
+ *  `reconcileEngineState` operator command share, so the two paths can never diverge. */
+export async function runEngineReconcile(
+  data: DataLayer,
+  engineRest: { restAddress: string; token?: string },
+  opts: ReconcileOptions & { fetchImpl?: typeof fetch } = {},
+): Promise<ReconcileResult> {
+  const observation = await probeEngineEpoch(engineRest.restAddress, {
+    token: engineRest.token,
+    fetchImpl: opts.fetchImpl,
+  });
+  return reconcileEngineBackedWork(data, observation, opts);
+}

package/app/service.ts

@@ -68,6 +68,7 @@ import {
   type Plan,
   planReviews,
   plans,
+  plansTracking,
   planTaskDeps,
   planTaskNeeds,
   planTasks,
@@ -2383,6 +2384,57 @@ export async function pollEpicPhase(
   }
 }
 
+/** Poll pass (issue #624): own the taskless plan's COMPLETED → `done` transition from ENGINE truth.
+ *
+ * A taskless plan (`task_count = 0`, the planner emitted no tasks) is NO LONGER collapsed to terminal
+ * `done` by `record-plan` — "the planner produced nothing this pass" is an INTERMEDIATE state, not an
+ * ended process (the plan-fanout instance is still live and may re-plan, escalate, or be cancelled).
+ * So the plan stays non-terminal (`planning`) until its process instance ACTUALLY ends, and terminal
+ * `plans.status` follows engine instance liveness rather than the empty-plan heuristic that rendered
+ * the epic "Done" over a live (in fact looping) instance.
+ *
+ * This pass owns the COMPLETED → `done` edge for such plans, mirroring the delivery-graph
+ * COMPLETED → `done` transition ({@link pollDeliveryGraphPhase}): `instanceTracking`'s `onTerminated`
+ * edge reconciles only TERMINATED (→ `abandoned` on `derived_status`), never COMPLETED, so a taskless
+ * plan whose instance ends GREEN would otherwise stay `planning` forever. A taskful plan reaches
+ * `done` through its own `record-results` finalizer, so this pass is scoped to `task_count = 0` and to
+ * the live rows only. Liveness is read off the ADR-0065 derived tracking VIEW (`plansTracking`'s
+ * `derived_status`), NOT the base `plans.status`: a taskless plan whose instance TERMINATED out of
+ * band keeps base `status = planning`/`dispatched` while `derived_status` folds to `abandoned`, so a
+ * base-status scan would re-query the engine for that already-dead row every pass forever. Skipping
+ * rows whose `derived_status` is no longer live confines the engine read to genuinely-live plans and
+ * never races a worker-owned terminal. Best-effort +
+ * idempotent: writes only on a real COMPLETED read, so a steady-state pass over a still-active
+ * instance is a no-op (the acceptance guarantee — a taskless plan is never terminal while active). */
+export async function pollTasklessPlanTermination(
+  data: DataLayer,
+  engine: Pick<EngineClient, "searchProcessInstances">,
+) {
+  for (const status of EPIC_LIVE_STATUSES) {
+    for (const plan of await plansTracking(data).find({ status })) {
+      if (plan.task_count !== 0 || !plan.process_key) continue;
+      // Base `status` is live, but the instance may have TERMINATED out of band (folding
+      // `derived_status` → `abandoned`); skip such derive-only-terminal rows so the pass only
+      // queries the engine for genuinely-live plans (ADR-0065).
+      if (!EPIC_LIVE_STATUSES.some((s) => s === plan.derived_status)) continue;
+      const processKey = plan.process_key;
+      try {
+        const snapshots = await engine.searchProcessInstances({ processInstanceKeys: [processKey] });
+        const state = snapshots.find((s) => String(s.processInstanceKey) === processKey)?.state ?? null;
+        if (state === "COMPLETED") {
+          await plans(data).update(plan.plan_key, {
+            status: "done",
+            outcome: plan.outcome ?? "planner emitted no tasks",
+            updated_at: now(),
+          });
+        }
+      } catch (err) {
+        console.error(`[poller] taskless plan termination ${plan.plan_key}: ${err}`);
+      }
+    }
+  }
+}
+
 /** Poll pass (ADR 0005 slice S5): reconcile each RUNNING delivery-graph run's derived phase from
  * engine truth, and complete it when its instance ends. A delivery graph is a DYNAMIC compiled
  * process with no happy-path host worker, so — unlike `plans`/`feature_runs`, whose spine workers
@@ -2622,6 +2674,7 @@ export async function pollOnce(
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
   await pollEpicPhase(data, engine);
+  await pollTasklessPlanTermination(data, engine);
   await pollDeliveryGraphPhase(data, engine);
   await pollDeliveryProposals(data);
   if (engineRest) {

package/app/userTasks.ts

@@ -30,6 +30,13 @@ const now = () => new Date().toISOString();
  *  when the adversarial review loop exhausts its budget without approval. */
 export const PLAN_REVIEW_ELEMENT = "plan-review-decision";
 
+/** The empty-plan operator escalation user task (plan-fanout.bpmn) — a human directive (accept/revise)
+ *  when the planner emits an EMPTY plan (`{tasks:[]}`). Instead of auto-terminating the run from an
+ *  intermediate signal (which rendered "Done" over a still-live instance, #624) or feeding the empty
+ *  plan into the adversarial plan-review loop (a plan↔plan-review livelock, #623), the run parks here
+ *  for operator attention: Accept a legitimate no-op epic (→ terminal done) or Revise (→ re-plan). */
+export const EMPTY_PLAN_ELEMENT = "empty-plan-escalation";
+
 /** The trial-merge escalation user task (plan-fanout.bpmn) — a human decision (proceed/rebase/abandon)
  *  when a wave's trial merge comes back red. */
 export const TRIAL_MERGE_ELEMENT = "trial-merge-decision";
@@ -87,6 +94,7 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [FEATURE_ESCALATION_ELEMENT]: "Feature escalation",
   [FEATURE_BLOCKED_ELEMENT]: "Blocked feature run",
   [PLAN_REVIEW_ELEMENT]: "Plan review",
+  [EMPTY_PLAN_ELEMENT]: "Empty plan",
   [TRIAL_MERGE_ELEMENT]: "Trial merge",
   [PR_WAIT_ANSWER_ELEMENT]: "PR review",
   [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",

package/db/migrations/092_engine_reconcile.sql

@@ -0,0 +1,53 @@
+-- Engine-reset reconciliation surface (issue #622).
+--
+-- When the Nano engine is reset, restored, or rolled to an incarnation whose key generator has
+-- rewound (Magikcraft/nano-bpm#1065), `app.db` keeps projecting engine-backed inflight work that no
+-- longer exists on the engine. These three sidecars give the app a first-class, idempotent,
+-- provenance-stamped `reconcile` surface (app/reconcile.ts) that runs on startup and on demand:
+--
+--   • engine_incarnation  — the single-row last-seen engine incarnation/epoch id. The engine stamps
+--     a monotonic incarnation id at boot (companion to the versioned snapshot envelope,
+--     Magikcraft/nano-bpm#1068) and exposes it on `/v2/topology`. An epoch REGRESSION (the observed
+--     epoch is lower than the recorded one) — or its absence where one was recorded — is the cheap,
+--     robust "engine was reset/rewound → reconcile" signal, one check instead of N per-instance probes.
+--   • reconcile_runs      — one row per reconcile pass: the observed vs recorded epoch, the outcome
+--     reason, and how many rows were orphaned. The append-only audit of every convergence.
+--   • reconcile_provenance— one row per orphaned transition: which engine-backed app row
+--     (source_table, pk_value, its engine instance key) moved from which status to `orphaned`, why
+--     (engine-reset/epoch-regression), the observed engine epoch, and the owning reconcile run id.
+--     This is the provenance that makes each mutation legible and reversible instead of a silent drop.
+--
+-- These are app-owned bookkeeping surfaces; reconcile itself never mutates append-only audit or
+-- already-terminal history — only NON-terminal, engine-backed rows (nano.app.json instanceTracking
+-- bindings) whose status is still in the binding's activeStatuses set.
+
+CREATE TABLE IF NOT EXISTS engine_incarnation (
+  id INTEGER PRIMARY KEY CHECK (id = 1), -- single-row table: the app only tracks one engine
+  epoch INTEGER,                          -- last-seen engine incarnation/epoch id (NULL until the engine exposes one)
+  observed_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS reconcile_runs (
+  run_id TEXT PRIMARY KEY,
+  started_at TEXT NOT NULL,
+  observed_epoch INTEGER,   -- the engine epoch observed on this run (NULL when the engine exposes none)
+  recorded_epoch INTEGER,   -- the previously-recorded epoch (NULL on the first ever run)
+  reason TEXT NOT NULL,     -- 'epoch-regression' | 'seed-epoch' | 'no-op' | 'engine-unreachable'
+  orphaned_count INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS reconcile_provenance (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT NOT NULL,
+  source_table TEXT NOT NULL,  -- the engine-backed base table the orphaned row lives in
+  pk_value TEXT NOT NULL,      -- the row's primary-key value
+  key_value TEXT,              -- the engine instance key (keyField, e.g. process_key) the row projected
+  from_status TEXT,            -- the non-terminal status the row carried before reconcile
+  to_status TEXT NOT NULL,     -- always the defined 'orphaned' terminal
+  reason TEXT NOT NULL,        -- 'engine-reset/epoch-regression'
+  observed_epoch INTEGER,      -- the engine epoch observed when the row was orphaned
+  at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS ix_reconcile_provenance_run ON reconcile_provenance (run_id);
+CREATE INDEX IF NOT EXISTS ix_reconcile_provenance_row ON reconcile_provenance (source_table, pk_value);

package/e2e/plan-fanout.e2e.ts

@@ -241,27 +241,30 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     );
   });
 
-  // Empty-plan short-circuit (issue #623 — regression for Merlin instance-46 / epic #1067). A
+  // Empty-plan escalation (issues #623/#624 — regression for Merlin instance-46 / epic #1067). A
   // planner that legitimately emits `{tasks:[]}` (meta/tracking epic, or all sub-issues closed) must
-  // reach a terminal state WITHOUT entering the adversarial plan-review loop — feeding an empty plan
-  // into review caused a plan↔plan-review livelock (it can neither be approved nor produce findings).
-  test("empty plan short-circuits to the taskless-done end, never entering plan-review (issue #623)", async () => {
+  // NOT enter the adversarial plan-review loop (feeding an empty plan into review caused a
+  // plan↔plan-review livelock — it can neither be approved nor produce findings), and must NOT
+  // auto-terminate from an intermediate signal while the instance is still live (#624). Instead it is
+  // parked for OPERATOR ATTENTION at the `empty-plan-escalation` user task; a human then Accepts
+  // (no-op done) or Revises (re-plan).
+  test("empty plan parks at the operator escalation (non-terminal), never entering plan-review (issues #623/#624)", async () => {
     let reviewCalls = 0;
     await withApp(
       {
         "senior:plan": () => ({ tasks: [], note: "all sub-issues closed" }),
-        // If this ever fires, the short-circuit failed and the empty plan entered the review loop.
+        // If this ever fires, the empty plan wrongly entered the review loop.
         "senior:plan-review": () => {
           reviewCalls += 1;
           return { approved: false, findings: "" };
         },
         "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
       },
-      async ({ app, planKey }) => {
+      async ({ app, planKey, processKey }) => {
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("gw-plan-empty->EndTasklessDone"),
-          `empty plan routed to the taskless-done end (flows: ${flows.join(", ")})`,
+          flows.includes("gw-plan-empty->empty-plan-escalation"),
+          `empty plan routed to the operator escalation (flows: ${flows.join(", ")})`,
         );
         assert.ok(
           !flows.includes("gw-plan-empty->review-plan"),
@@ -269,11 +272,83 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
         );
         assert.equal(reviewCalls, 0, "the plan-review agent must never run for an empty plan");
 
-        const plan = await app.db
+        // The instance is parked at the operator user task — a completable escalation exists.
+        const task = await openTask(app, processKey, "empty-plan-escalation");
+        assert.ok(task.userTaskKey, "the empty-plan escalation carries a completable userTaskKey");
+
+        // While parked, the plan is NON-terminal: the instance is still live (#624), so terminal
+        // `done` is owned by the poller on COMPLETED, not written here from the empty-plan signal.
+        const parked = await app.db
           .table<{ plan_key: string; status: string; outcome: string | null }>("plans", "plan_key")
           .findOne({ plan_key: planKey });
-        assert.equal(plan?.status, "done", "the empty plan reached a terminal done state");
-        assert.equal(plan?.outcome, "all sub-issues closed", "the planner note was recorded as the outcome");
+        assert.equal(parked?.status, "planning", "a parked empty plan stays non-terminal (planning)");
+        assert.equal(parked?.outcome, "all sub-issues closed", "the planner note was recorded as the outcome");
+      },
+    );
+  });
+
+  test("empty-plan escalation: accept routes to the taskless-done end (no-op epic)", async () => {
+    await withApp(
+      {
+        "senior:plan": () => ({ tasks: [], note: "all sub-issues closed" }),
+        "senior:plan-review": () => ({ approved: true, findings: "" }),
+        "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
+      },
+      async ({ app, processKey }) => {
+        const task = await openTask(app, processKey, "empty-plan-escalation");
+        await app.engine.completeUserTask(task.userTaskKey, { directive: "accept", notes: "meta epic" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-empty-plan-answer->EndTasklessDone"),
+          `accept routed to the taskless-done end (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("gw-empty-plan-answer->plan"),
+          "the revise (default) flow was NOT taken",
+        );
+      },
+    );
+  });
+
+  test("empty-plan escalation: revise re-plans, re-parking a still-empty plan at the operator (never auto-terminating)", async () => {
+    let reviewCalls = 0;
+    const planPrompts: Array<string | undefined> = [];
+    await withApp(
+      {
+        "senior:plan": (job) => {
+          planPrompts.push((job.variables as Record<string, unknown>).appendPrompt as string | undefined);
+          return { tasks: [], note: "all sub-issues closed" };
+        },
+        "senior:plan-review": () => {
+          reviewCalls += 1;
+          return { approved: true, findings: "" };
+        },
+        "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
+      },
+      async ({ app, processKey }) => {
+        const task = await openTask(app, processKey, "empty-plan-escalation");
+        await app.engine.completeUserTask(task.userTaskKey, { directive: "revise", notes: "look again" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-empty-plan-answer->plan"),
+          `revise routed back to the planner (flows: ${flows.join(", ")})`,
+        );
+        // The operator's revision guidance must actually reach the re-plan: `empty-plan-escalation`
+        // folds `notes` into `planFindings`, which the `plan` task renders into its `appendPrompt`.
+        const rePlanPrompt = planPrompts.at(-1);
+        assert.ok(
+          rePlanPrompt?.includes("look again"),
+          `operator revise notes were delivered to the re-plan appendPrompt (got: ${JSON.stringify(rePlanPrompt)})`,
+        );
+        // The re-plan is still empty, so it re-parks at a fresh operator escalation — it neither
+        // enters plan-review nor auto-terminates.
+        const reparked = await openTask(app, processKey, "empty-plan-escalation");
+        assert.ok(reparked.userTaskKey, "a still-empty re-plan re-parks at the operator escalation");
+        assert.equal(reviewCalls, 0, "the plan-review agent must never run for an empty plan");
       },
     );
   });

package/main.ts

@@ -22,6 +22,7 @@ import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urba
 import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
 import { makeElementInstanceResolver } from "./app/agentic/element-instance.ts";
 import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
+import { runEngineReconcile } from "./app/reconcile.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
 
@@ -102,6 +103,30 @@ if (httpServer instanceof Server) {
   app.log.warn("agentic channel not mounted: app.httpServer is not a node:http Server on this host");
 }
 
+// Engine-reset reconciliation (issue #622). On boot, compare the engine's incarnation epoch against
+// the last-seen value; on a REGRESSION (the engine was reset/restored/rewound and re-minted its keys,
+// Magikcraft/nano-bpm#1065) drive every dangling engine-backed inflight row to the defined `orphaned`
+// terminal WITH PROVENANCE — BEFORE the pollers below start projecting off stale, dead instances.
+// Guarded: an unreachable engine is a no-op (it never orphans live work), and any failure degrades to
+// a warn so reconcile can never block boot.
+if (app.data) {
+  try {
+    const reconciled = await runEngineReconcile(
+      app.data,
+      { restAddress: engineAddress.restAddress, token: process.env.CAMUNDA_TOKEN },
+      { log: { info: (m) => app.log.info(m), warn: (m) => app.log.warn(m) } },
+    );
+    if (reconciled.orphanedCount > 0) {
+      app.log.warn(
+        `startup reconcile: engine reset detected — orphaned ${reconciled.orphanedCount} engine-backed ` +
+          `inflight row(s) [run ${reconciled.runId}].`,
+      );
+    }
+  } catch (err) {
+    app.log.warn(`startup reconcile skipped: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 // Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
 // overlap two passes (which could double-signal `readiness-ready`); the next pass is scheduled
 // only after the previous one settles.