@nanobpm/nano-workforce 0.144.0 → 0.145.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.145.0](https://github.com/nanobpm/nano-workforce/compare/v0.144.0...v0.145.0) (2026-08-25)
+
+### Features
+
+* **stepper:** live element-instance epic-phase projection (S8, [#542](https://github.com/nanobpm/nano-workforce/issues/542)) ([#554](https://github.com/nanobpm/nano-workforce/issues/554)) ([fdc3ccc](https://github.com/nanobpm/nano-workforce/commit/fdc3ccc8ffe3797954c8502385634f7c0937571e)), closes [#464](https://github.com/nanobpm/nano-workforce/issues/464) [#541](https://github.com/nanobpm/nano-workforce/issues/541) [#546](https://github.com/nanobpm/nano-workforce/issues/546) [nano-ide#473](https://github.com/nanobpm/nano-ide/issues/473)
+
 ## [0.144.0](https://github.com/nanobpm/nano-workforce/compare/v0.143.0...v0.144.0) (2026-08-25)
 
 ### Features

package/app/deliveryGraphRun.test.ts

@@ -115,7 +115,7 @@ test("pollDeliveryGraphPhase: a numeric engine processInstanceKey still matches
     // The engine can yield a NUMERIC key; the poller compares against the string process_key.
     const engine = {
       searchProcessInstances: async () => [{ processInstanceKey: 12345, state: "COMPLETED" }],
-      searchUserTasks: async () => [],
+      searchElementInstanceWaitStates: async () => [],
     };
     await pollDeliveryGraphPhase(data, engine as never);
     assertEquals((await runs.get("rk"))?.status, "done");

package/app/epicPhase.test.ts

@@ -5,7 +5,7 @@
 // epic view can show WHICH phase an epic is in — not only the process-instance terminal status.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { deriveEpicPhase, EPIC_PHASE, implementingPhase } from "./epicPhase.ts";
+import { deriveEpicPhase, deriveEpicPhaseLive, deriveTerminalEpicPhase, EPIC_PHASE, implementingPhase } from "./epicPhase.ts";
 
 test("deriveEpicPhase maps each spine element to its domain phase", () => {
   // Planning genesis + hand-off into Reviewing when the plan is recorded.
@@ -20,8 +20,10 @@ test("deriveEpicPhase maps each spine element to its domain phase", () => {
   assertEquals(deriveEpicPhase("record-trial-merge"), EPIC_PHASE.TRIAL_MERGING);
   assertEquals(deriveEpicPhase("trial-merge-decision"), EPIC_PHASE.TRIAL_MERGING);
   assertEquals(deriveEpicPhase("resolve-trial-attention"), EPIC_PHASE.TRIAL_MERGING);
-  // Finalize step's lasting result is the "Fleet dispatched" terminal.
-  assertEquals(deriveEpicPhase("record-results"), EPIC_PHASE.DISPATCHED);
+  // Finalize step ("Finalize plan") reads Finalizing while its token is ACTIVE; the terminal
+  // "Fleet dispatched" phase is derived from the terminal status, not this element (see
+  // deriveTerminalEpicPhase), so Finalizing is reachable and Dispatched is not raced off a live token.
+  assertEquals(deriveEpicPhase("record-results"), EPIC_PHASE.FINALIZING);
 });
 
 test("deriveEpicPhase wave-labels the Implementing band from the levelize records", () => {
@@ -59,4 +61,85 @@ test("implementingPhase clamps the 1-based label to the total and degrades grace
   assertEquals(implementingPhase(0, 0), "Implementing");
   assertEquals(implementingPhase(undefined, undefined), "Implementing");
   assertEquals(implementingPhase("x", "y"), "Implementing");
+  // A NULL `current_wave` (unknown wave) with a known `wave_count` is ABSENT, not wave 0 — it must
+  // NOT mislabel as "wave 1/t" (`Number(null)` is 0). Missing wave data stays missing.
+  assertEquals(implementingPhase(null, 3), "Implementing");
+  assertEquals(implementingPhase(null, null), "Implementing");
+});
+
+test("deriveEpicPhaseLive reads Finalizing from an ACTIVE finalizer token", () => {
+  // The finalize step is Finalizing while its token is ACTIVE — the phase is reachable in the live
+  // model (it is the furthest spine element short of the terminal Dispatched marker).
+  assertEquals(
+    deriveEpicPhaseLive([{ elementId: "record-results", state: "ACTIVE" }]),
+    EPIC_PHASE.FINALIZING,
+  );
+  // Finalizing (ordinal) outranks a still-live trial-merge token.
+  assertEquals(
+    deriveEpicPhaseLive([
+      { elementId: "trial-merge", state: "ACTIVE" },
+      { elementId: "record-results", state: "ACTIVE" },
+    ]),
+    EPIC_PHASE.FINALIZING,
+  );
+});
+
+test("deriveTerminalEpicPhase reads Dispatched only from a done epic that dispatched a fleet", () => {
+  // A done epic that opened ≥1 slice reaches the terminal "Fleet dispatched" phase.
+  assertEquals(deriveTerminalEpicPhase("done", 3), EPIC_PHASE.DISPATCHED);
+  assertEquals(deriveTerminalEpicPhase("done", 1), EPIC_PHASE.DISPATCHED);
+  // A taskless done (planner emitted no tasks — nothing dispatched) and non-done terminals are NOT
+  // Dispatched, so the caller leaves the last live phase untouched.
+  assertEquals(deriveTerminalEpicPhase("done", 0), null);
+  assertEquals(deriveTerminalEpicPhase("failed", 3), null);
+  assertEquals(deriveTerminalEpicPhase("abandoned", 3), null);
+  assertEquals(deriveTerminalEpicPhase("dispatched", 3), null);
+});
+
+// ── deriveEpicPhaseLive: the S8 live element-instance derivation (#542) ────────────────────────────
+test("deriveEpicPhaseLive projects the FURTHEST active spine element onto its phase", () => {
+  // A pre-PR Reviewing epic: the plan is recorded (COMPLETED) and the review-plan agent is running.
+  assertEquals(
+    deriveEpicPhaseLive([
+      { elementId: "record-plan", state: "COMPLETED" },
+      { elementId: "review-plan", state: "ACTIVE" },
+    ]),
+    EPIC_PHASE.REVIEWING,
+  );
+  // The implement multi-instance keeps select-wave/record-wave AND per-child implement-task tokens
+  // live at once; a later trial-merge token, once reached, is the epic's true furthest position.
+  assertEquals(
+    deriveEpicPhaseLive([
+      { elementId: "implement-task", state: "ACTIVE" },
+      { elementId: "record-wave", state: "ACTIVE" },
+      { elementId: "trial-merge", state: "ACTIVE" },
+    ]),
+    EPIC_PHASE.TRIAL_MERGING,
+  );
+});
+
+test("deriveEpicPhaseLive wave-labels a live Implementing token from the wave context", () => {
+  assertEquals(
+    deriveEpicPhaseLive([{ elementId: "implement-task", state: "ACTIVE" }], { current: 1, total: 3 }),
+    "Implementing (wave 2/3)",
+  );
+  // Mid-cell fidelity (S8): an active implement job with no wave numbers yet still reads Implementing.
+  assertEquals(
+    deriveEpicPhaseLive([{ elementId: "implement-task", state: "ACTIVE" }]),
+    EPIC_PHASE.IMPLEMENTING,
+  );
+});
+
+test("deriveEpicPhaseLive ignores non-ACTIVE tokens and non-spine plumbing, returning null when nothing marks a phase", () => {
+  // COMPLETED/TERMINATED tokens are past, not the live position — an all-completed set marks nothing.
+  assertEquals(
+    deriveEpicPhaseLive([
+      { elementId: "plan", state: "COMPLETED" },
+      { elementId: "review-plan", state: "TERMINATED" },
+    ]),
+    null,
+  );
+  // A token parked only on non-spine plumbing (no ELEMENT_PHASE entry) leaves the phase untouched.
+  assertEquals(deriveEpicPhaseLive([{ elementId: "some-gateway", state: "ACTIVE" }]), null);
+  assertEquals(deriveEpicPhaseLive([]), null);
 });

package/app/epicPhase.ts

@@ -1,4 +1,22 @@
-// app/epicPhase.ts — reify the epic's own domain lifecycle as a derived `epic_phase` (issue #261).
+// app/epicPhase.ts — reify the epic's own domain lifecycle as a derived `epic_phase` (issue #261,
+// S8 #542 / ADR 0006 §4b).
+//
+// LIVE READ-MODEL DERIVATION (S8, #542). The epic phase is now a PURE read-model derivation off the
+// live engine element-instance model — the write-time provenance stamp (each spine worker stamping
+// the phase it enters) is RETIRED. `deriveEpicPhaseLive` reads the plan-fanout instance's live
+// element instances (`EngineClient.searchElementInstances`, nano-ide#473) and projects the
+// FURTHEST-REACHED active element onto the same structural `ELEMENT_PHASE` map the write-stamp used
+// (derive-don't-duplicate: one structural source, two consumers retired to one). This lifts S7's
+// coarse lifecycle-stage fidelity to true per-cell / mid-cell position — an active `implement` job or
+// a pre-PR `review-plan` agent is read live from the token position, ahead of any work-table row.
+// The `pollEpicPhase` poll pass (app/service.ts) owns the write, so no worker stamps `epic_phase`.
+//
+// Because plan-fanout.bpmn runs the WHOLE epic spine (`plan` → `review-plan` → the `implement`
+// multi-instance subProcess → `trial-merge` → `record-results`) as ONE process instance — the
+// `implement` fan-out is an embedded subProcess, not a callActivity child instance — a single
+// element-instance search over the plan's `process_key` sees every spine cell. (When S4 callActivity
+// composition lands, the same derivation extends to child instances via the engine's native
+// parent/root keys, Magikcraft/nano-bpm#977 — the #464 option-B correlation decision.)
 //
 // `plans.status` only distinguishes `planning` / `dispatched` / `done` / `failed` / `abandoned` —
 // and `dispatched` is the `plan-fanout.bpmn` PROCESS-INSTANCE terminal ("fan-out job done"), not the
@@ -42,6 +60,9 @@ export const EPIC_PHASE = {
  *  `toWave` coercion the wave workers already apply, so a NaN/absent counter degrades to an
  *  unlabelled `Implementing` rather than emitting `wave NaN/…`. */
 const toWave = (v: unknown): number | null => {
+  // `null`/`undefined` are ABSENT, not zero: `Number(null)` is `0`, which would otherwise label a
+  // missing `current_wave` as `wave 1/t`. Treat them as unusable so missing wave data stays missing.
+  if (v === null || v === undefined) return null;
   const n = Math.trunc(Number(v));
   return Number.isFinite(n) && n >= 0 ? n : null;
 };
@@ -74,8 +95,10 @@ export function implementingPhase(current: unknown, total: unknown): string {
  *   • `select-wave` ("Select wave") → Implementing: it dispatches the wave and is the last host write
  *     before the write-silent `implement` MI, so it durably marks the implementation phase for the
  *     wave it launches (wave-labelled via {@link implementingPhase} at the call site).
- *   • `record-results` ("Finalize plan") → Dispatched: the finalize step's lasting result is the
- *     "Fleet dispatched" terminal end event.
+ *   • `record-results` ("Finalize plan") → Finalizing: while the finalizer token is ACTIVE the epic
+ *     is finalizing. Its TERMINAL "Fleet dispatched" phase is NOT read from this (fleeting) live
+ *     token — a completion marker has no ACTIVE element to read once the instance ends — but derived
+ *     from the durable terminal status (see {@link deriveTerminalEpicPhase}).
  * `record-wave`'s next phase is data-dependent (trial-merge vs. next wave vs. finalize), so it is
  * resolved at its call site rather than from the element id alone; its structural fallback here is
  * the wave it just landed.
@@ -97,7 +120,7 @@ const ELEMENT_PHASE: Readonly<Record<string, string>> = {
   "record-trial-merge": EPIC_PHASE.TRIAL_MERGING,
   "trial-merge-decision": EPIC_PHASE.TRIAL_MERGING,
   "resolve-trial-attention": EPIC_PHASE.TRIAL_MERGING,
-  "record-results": EPIC_PHASE.DISPATCHED,
+  "record-results": EPIC_PHASE.FINALIZING,
 };
 
 /** Optional wave context for a wave-bearing phase, sourced from the wave/levelize records. */
@@ -123,3 +146,74 @@ export function deriveEpicPhase(
   if (base === EPIC_PHASE.IMPLEMENTING) return implementingPhase(wave?.current, wave?.total);
   return base;
 }
+
+/** The epic spine's phase ORDER — the total order `deriveEpicPhaseLive` compares "furthest reached"
+ *  by. It IS the declaration order of {@link EPIC_PHASE} (Planning → Reviewing → Implementing → Trial
+ *  merging → Finalizing → Dispatched), the epic's natural forward spine, so the ordinal cannot drift
+ *  from the phase vocabulary. */
+const EPIC_PHASE_ORDER: readonly string[] = Object.values(EPIC_PHASE);
+
+/** Constant-time phase→ordinal lookup for {@link deriveEpicPhaseLive}'s hot loop — precomputed once
+ *  from {@link EPIC_PHASE_ORDER} so the per-element "furthest reached" compare is O(1) instead of a
+ *  linear `indexOf` per ACTIVE instance (avoids O(n·k) on high-fanout epics; #542 review). */
+const EPIC_PHASE_ORDINAL: ReadonlyMap<string, number> = new Map(
+  EPIC_PHASE_ORDER.map((phase, ordinal) => [phase, ordinal]),
+);
+
+/** The finest-grained element-instance signal `deriveEpicPhaseLive` reads — the structural subset of
+ *  urban's `ElementInstanceSummary` it needs (the element's BPMN id and whether a token is currently
+ *  AT it). Kept structural (not the full binding type) so the derivation unit-tests in isolation. */
+export interface EpicElementInstance {
+  readonly elementId: string;
+  readonly state: string;
+}
+
+/**
+ * Derive the epic phase LIVE from the plan-fanout instance's element instances (S8 #542) — the pure
+ * read-model derivation that RETIRES the write-time stamp. Among the ACTIVE element instances (a token
+ * currently sitting AT the element — a running agent job, an open human gate, a readiness-probe loop),
+ * pick the one mapping FURTHEST along the epic spine ({@link EPIC_PHASE_ORDER}) and project it via the
+ * SAME structural {@link deriveEpicPhase} map — so the live derivation and the (now retired) stamp
+ * share one source. Returns `null` when no active element marks a phase (e.g. the instance is parked
+ * only on non-spine plumbing), so the caller leaves the last known phase untouched rather than
+ * clobbering it. A wave-bearing phase (`Implementing`) is wave-labelled from {@link WaveContext}.
+ *
+ * "Furthest reached" (max spine ordinal), not "least advanced": the `implement` multi-instance
+ * subProcess keeps `select-wave`/`record-wave` and per-child `implement-task` tokens live at once, all
+ * mapping to `Implementing`; a later `trial-merge` token, once reached, is the epic's true position, so
+ * the max is the faithful "where has this epic got to" read.
+ */
+export function deriveEpicPhaseLive(
+  elements: readonly EpicElementInstance[],
+  wave?: WaveContext,
+): string | null {
+  let bestBase: string | null = null;
+  let bestOrdinal = -1;
+  for (const el of elements) {
+    if (el.state !== "ACTIVE") continue;
+    const base = deriveEpicPhase(el.elementId);
+    if (base === null) continue;
+    const ordinal = EPIC_PHASE_ORDINAL.get(base) ?? -1;
+    if (ordinal > bestOrdinal) {
+      bestOrdinal = ordinal;
+      bestBase = base;
+    }
+  }
+  if (bestBase === null) return null;
+  return bestBase === EPIC_PHASE.IMPLEMENTING ? implementingPhase(wave?.current, wave?.total) : bestBase;
+}
+
+/**
+ * Derive the epic's TERMINAL phase from its durable status — the completion-marker counterpart to the
+ * live derivation (S8 #542 review). The "Fleet dispatched" phase is reached only when the plan-fanout
+ * instance ENDS, at which point there is no ACTIVE element to read; live-observing the fleeting ACTIVE
+ * `record-results` token via a coarse (default 60s) poll would miss it on nearly every fast finalize,
+ * freezing the row at the last live phase. So `Dispatched` is derived from the durable read-model
+ * (`plans.status`) instead: a `done` epic that dispatched ≥1 slice (`taskCount > 0`) reads Dispatched.
+ * Returns `null` for a taskless `done` (planner emitted no tasks — nothing was dispatched) and for any
+ * non-`done` terminal (`failed`/`abandoned`), so those never mislabel as Dispatched and the caller
+ * leaves the last live phase untouched.
+ */
+export function deriveTerminalEpicPhase(status: string, taskCount: number): string | null {
+  return status === "done" && taskCount > 0 ? EPIC_PHASE.DISPATCHED : null;
+}

package/app/pollEpicPhase.test.ts

@@ -0,0 +1,159 @@
+// Coverage for `pollEpicPhase` (S8, #542 / ADR 0006 §4b) — the poll pass that reconciles the epic's
+// `plans.epic_phase` from the LIVE engine element-instance model, the pure read-model derivation that
+// RETIRED the write-time stamp the spine workers used to write. Booted against the real provisioned
+// SQLite data layer (so the `plans` table and the `plan_wave_progress` wave-frontier VIEW exist) with
+// a stubbed `searchElementInstances`, proving: a live plan's phase advances to the furthest active
+// spine element; the wave label rides the wave-progress rollup; a steady-state pass is a no-op; and a
+// terminal (non-live) plan is never touched.
+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 { EPIC_PHASE } from "./epicPhase.ts";
+import { plans, planTasks } from "./plan.ts";
+import { pollEpicPhase } from "./service.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+
+async function withData(fn: (data: DataLayer) => Promise<void>): Promise<void> {
+  const dir = mkdtempSync(join(tmpdir(), "nwf-epicphase-"));
+  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;
+    epic_phase?: string | null;
+    task_count?: number;
+  } = {},
+) {
+  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 ?? "dispatched",
+    task_count: over.task_count ?? 0,
+    epic_phase: over.epic_phase ?? EPIC_PHASE.PLANNING,
+    process_key: "process_key" in over ? over.process_key : "pi-1",
+    created_at: now(),
+    updated_at: now(),
+  } as never);
+}
+
+test("pollEpicPhase advances a live epic's phase to the furthest ACTIVE spine element", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { epic_phase: EPIC_PHASE.PLANNING });
+    // The plan is recorded (COMPLETED) and the review-plan agent is running → Reviewing.
+    const engine = {
+      searchElementInstances: async () => [
+        { elementInstanceKey: "e1", processInstanceKey: "pi-1", elementId: "record-plan", state: "COMPLETED" },
+        { elementInstanceKey: "e2", processInstanceKey: "pi-1", elementId: "review-plan", state: "ACTIVE" },
+      ],
+    };
+    await pollEpicPhase(data, engine as never);
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, EPIC_PHASE.REVIEWING);
+  });
+});
+
+test("pollEpicPhase wave-labels a live Implementing token from the plan_wave_progress rollup", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { epic_phase: EPIC_PHASE.REVIEWING });
+    // Two levelized waves (0,1); wave 0 is settled (skipped → not in-flight) and wave 1 is still in
+    // flight, so the frontier is wave 1 → current_wave 1, wave_count 2 → "Implementing (wave 2/2)".
+    await planTasks(data).insert({ id: 1, plan_key: "owner/repo#7", task_index: 0, task_id: "a", status: "skipped", wave: 0, created_at: now(), updated_at: now() } as never);
+    await planTasks(data).insert({ id: 2, plan_key: "owner/repo#7", task_index: 1, task_id: "b", status: "pending", wave: 1, created_at: now(), updated_at: now() } as never);
+    const engine = {
+      searchElementInstances: async () => [
+        { elementInstanceKey: "e3", processInstanceKey: "pi-1", elementId: "implement-task", state: "ACTIVE" },
+      ],
+    };
+    await pollEpicPhase(data, engine as never);
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, "Implementing (wave 2/2)");
+  });
+});
+
+test("pollEpicPhase is a no-op when the derived phase is unchanged, and leaves the phase when nothing marks one", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { epic_phase: EPIC_PHASE.REVIEWING });
+    // Only non-spine plumbing is active → derivation returns null → the last phase is untouched.
+    const engine = {
+      searchElementInstances: async () => [
+        { elementInstanceKey: "e4", processInstanceKey: "pi-1", elementId: "some-gateway", state: "ACTIVE" },
+      ],
+    };
+    await pollEpicPhase(data, engine as never);
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, EPIC_PHASE.REVIEWING);
+  });
+});
+
+test("pollEpicPhase never touches a terminal (non-live) epic", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "done", epic_phase: EPIC_PHASE.DISPATCHED });
+    let called = false;
+    const engine = {
+      searchElementInstances: async () => {
+        called = true;
+        return [];
+      },
+    };
+    await pollEpicPhase(data, engine as never);
+    assertEquals(called, false);
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, EPIC_PHASE.DISPATCHED);
+  });
+});
+
+test("pollEpicPhase freezes a done epic that dispatched a fleet at the terminal Dispatched phase", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "done", task_count: 2, epic_phase: EPIC_PHASE.TRIAL_MERGING });
+    let called = false;
+    const engine = {
+      searchElementInstances: async () => {
+        called = true;
+        return [];
+      },
+    };
+    await pollEpicPhase(data, engine as never);
+    // Derived from the terminal status, not the (skipped) live element search.
+    assertEquals(called, false);
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, EPIC_PHASE.DISPATCHED);
+  });
+});
+
+test("pollEpicPhase never labels a taskless done epic Dispatched", async () => {
+  await withData(async (data) => {
+    // A done epic that dispatched nothing (planner emitted no tasks) must NOT read Dispatched.
+    await seedPlan(data, { status: "done", task_count: 0, epic_phase: EPIC_PHASE.PLANNING });
+    await pollEpicPhase(data, { searchElementInstances: async () => [] } as never);
+    assertEquals((await plans(data).get("owner/repo#7"))?.epic_phase, EPIC_PHASE.PLANNING);
+  });
+});
+
+test("pollEpicPhase skips a live epic that has no engine instance yet", async () => {
+  await withData(async (data) => {
+    await seedPlan(data, { status: "planning", process_key: null, epic_phase: EPIC_PHASE.PLANNING });
+    let called = false;
+    const engine = {
+      searchElementInstances: async () => {
+        called = true;
+        return [];
+      },
+    };
+    await pollEpicPhase(data, engine as never);
+    assertEquals(called, false);
+  });
+});

package/app/service.ts

@@ -27,11 +27,12 @@ import {
   conformanceEscalationQuestion,
 } from "./conformance.ts";
 import { isUniqueConstraintFence } from "./dbFence.ts";
-import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { deriveDelivery, EPIC_LIVE_STATUSES, TERMINAL_STATUSES } from "./delivery.ts";
 import { sweepExpiredProposals } from "./deliveryGraphProposals.ts";
 import { deliveryGraphRuns, deriveDeliveryPhase, parseHumanLabels } from "./deliveryGraphRun.ts";
 import { isDeliveryHumanElement } from "./deliveryHuman.ts";
 import { fleetSupportsDurableResume } from "./durableResume.ts";
+import { deriveEpicPhaseLive, deriveTerminalEpicPhase } from "./epicPhase.ts";
 import { deriveFeatureDelivery, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRunStatus, featureEscalations, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
@@ -2309,6 +2310,65 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
  * completed task's row is deleted (answered here, via the task inbox, or out-of-band) and `showCount`
  * reflects live pending work. Best-effort + idempotent — per-instance failures are isolated so one bad
  * instance never stalls the pass. */
+/** Poll pass (S8, #542 / ADR 0006 §4b): reconcile each LIVE epic's `plans.epic_phase` from the engine
+ * element-instance model — the PURE read-model derivation that RETIRES the write-time stamp the spine
+ * workers used to write. For each plan still live (`EPIC_LIVE_STATUSES`) with a running instance, read
+ * its element instances (`searchElementInstances`, nano-ide#473) and project the furthest-reached
+ * active spine element onto its domain phase (`deriveEpicPhaseLive`, app/epicPhase.ts — the SAME
+ * `ELEMENT_PHASE` structural map the stamp used). The wave label rides the `plan_wave_progress` rollup
+ * VIEW (the single wave-frontier source, 060/082), so the Implementing band reads `wave n/t` without a
+ * second wave derivation. Writes only on a real change (a steady-state pass is a no-op) and leaves the
+ * last phase untouched when nothing active marks one (`null`), so a plan parked on non-spine plumbing
+ * never clobbers to blank. The terminal `Dispatched` phase is a COMPLETION marker (no ACTIVE token to
+ * read once the instance ends), so a second pass derives it from the durable terminal status
+ * (`deriveTerminalEpicPhase` over `done` epics) rather than the fleeting ACTIVE `record-results` token
+ * a coarse poll would miss. Best-effort + idempotent — a per-plan failure is isolated. */
+export async function pollEpicPhase(
+  data: DataLayer,
+  engine: Pick<EngineClient, "searchElementInstances">,
+) {
+  const waveByPlan = new Map<string, { current: number | null; total: number | null }>();
+  for (const w of await data
+    .table<{ plan_key: string; wave_count: number | null; current_wave: number | null }>(
+      "plan_wave_progress",
+      "plan_key",
+    )
+    .all()) {
+    // Coerce SQL NULL to `null` so a missing `current_wave`/`wave_count` stays MISSING through the
+    // wave label — a wave number that coerced to `0` would otherwise mislabel an unknown wave as
+    // `wave 1/t` (the derivation guards this too, see `toWave`, which treats `null`/`undefined` alike).
+    waveByPlan.set(w.plan_key, {
+      current: w.current_wave ?? null,
+      total: w.wave_count ?? null,
+    });
+  }
+  for (const status of EPIC_LIVE_STATUSES) {
+    for (const plan of await plans(data).find({ status })) {
+      if (!plan.process_key) continue;
+      try {
+        const elements = await engine.searchElementInstances({ processInstanceKey: plan.process_key });
+        const phase = deriveEpicPhaseLive(elements, waveByPlan.get(plan.plan_key) ?? undefined);
+        if (phase !== null && phase !== plan.epic_phase) {
+          await plans(data).update(plan.plan_key, { epic_phase: phase, updated_at: now() });
+        }
+      } catch (err) {
+        console.error(`[poller] epic phase ${plan.plan_key}: ${err}`);
+      }
+    }
+  }
+  // Terminal "Fleet dispatched" phase: a COMPLETION marker, derived from the durable terminal status
+  // rather than a fleeting ACTIVE `record-results` token a coarse poll would miss (#542 review). A
+  // `done` epic that dispatched ≥1 slice freezes at Dispatched; a taskless `done` and any non-`done`
+  // terminal are left untouched (`deriveTerminalEpicPhase` returns null). Idempotent — writes only on
+  // a real change, so a steady-state pass over already-Dispatched rows is a no-op.
+  for (const plan of await plans(data).find({ status: "done" })) {
+    const phase = deriveTerminalEpicPhase(plan.status, plan.task_count);
+    if (phase !== null && phase !== plan.epic_phase) {
+      await plans(data).update(plan.plan_key, { epic_phase: phase, updated_at: now() });
+    }
+  }
+}
+
 /** 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
@@ -2316,22 +2376,25 @@ async function sweepOpenEscalationTasks(base: string, headers: Record<string, st
  * transition (instanceTracking's `onTerminated` edge reconciles only TERMINATED, never COMPLETED, so
  * a graph that ends normally would otherwise stay `running` forever). Generalises the `epic_phase`
  * derived-phase machinery to a graph whose element ids aren't known ahead of time: the parked-node
- * label is derived from the run row's stamped `human_labels` + the instance's OPEN user tasks. Scoped
- * to `running` rows (an `awaiting-approval` run has no instance yet), so it stays O(in-flight). */
+ * label is derived from the run row's stamped `human_labels` + the instance's live USER_TASK parks.
+ * The parked node is now sourced from the unified element-instance wait-state channel
+ * (`searchElementInstanceWaitStates`, nano-ide#473) rather than a separate user-task search, folding
+ * this read onto the same live element-instance model the epic derivation uses (S8, #542). Scoped to
+ * `running` rows (an `awaiting-approval` run has no instance yet), so it stays O(in-flight). */
 export async function pollDeliveryGraphPhase(
   data: DataLayer,
-  engine: Pick<EngineClient, "searchProcessInstances" | "searchUserTasks">,
+  engine: Pick<EngineClient, "searchProcessInstances" | "searchElementInstanceWaitStates">,
 ) {
   for (const run of await deliveryGraphRuns(data).find({ status: "running" })) {
     if (!run.process_key) continue;
     const processKey = run.process_key;
     try {
-      const [snapshots, tasks] = await Promise.all([
+      const [snapshots, parks] = await Promise.all([
         engine.searchProcessInstances({ processInstanceKeys: [processKey] }),
-        engine.searchUserTasks({ processInstanceKey: processKey, state: "CREATED" }),
+        engine.searchElementInstanceWaitStates({ processInstanceKey: processKey, waitStateType: "USER_TASK" }),
       ]);
       const state = snapshots.find((s) => String(s.processInstanceKey) === processKey)?.state ?? null;
-      const projection = deriveDeliveryPhase(state, tasks, parseHumanLabels(run.human_labels));
+      const projection = deriveDeliveryPhase(state, parks, parseHumanLabels(run.human_labels));
       if (run.status !== projection.status || run.phase !== projection.phase || run.phase_node_id !== projection.phase_node_id) {
         await deliveryGraphRuns(data).update(run.run_key, {
           status: projection.status,
@@ -2538,6 +2601,7 @@ export async function pollOnce(
   await pollFeatureDelivery(data);
   await pollLineage(data);
   await pollUserTasks(data, engine, engineRest);
+  await pollEpicPhase(data, engine);
   await pollDeliveryGraphPhase(data, engine);
   await pollDeliveryProposals(data);
   if (engineRest) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.144.0",
+  "version": "0.145.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",
@@ -64,7 +64,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
-    "@nanobpm/urban-testkit": "^0.13.1",
+    "@nanobpm/urban-testkit": "^0.14.0",
     "@nanobpm/workflow": "^0.14.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.0",

package/workers/record-plan/worker.ts

@@ -17,7 +17,6 @@
 // in that case (the edges were invalid).
 import type { AppJobHandler } from "@nanobpm/urban";
 import { type CapabilityNeed, parseCapabilityNeeds } from "../../app/capabilityNeed.ts";
-import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { plans, planTaskDeps, planTaskNeeds, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
@@ -147,11 +146,6 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     // denormalises it onto the `plans` row.
     updated_at: ts,
   };
-  // Domain-phase projection (#261): recording the plan hands the epic to the `review-plan` agent,
-  // so it enters the Reviewing phase (derived structurally from this worker's BPMN element id).
-  // Guard against a null derivation (element id absent) clobbering the genesis phase.
-  const epicPhase = deriveEpicPhase(job.elementId);
-  if (epicPhase) patch.epic_phase = epicPhase;
   if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
   await plans(app.data).update(planKey, patch);
 

package/workers/record-results/worker.ts

@@ -13,7 +13,6 @@
 
 import type { AppJobHandler } from "@nanobpm/urban";
 import { BpmnError } from "@nanobpm/urban";
-import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { plans, planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -50,16 +49,16 @@ const handler: AppJobHandler<In> = async (job, app) => {
     throw new BpmnError("NO_WORK_DISPATCHED", `${planKey}: ${outcome}`);
   }
 
-  // Domain-phase projection (#261): the finalizer landed with opened PRs — the epic reaches its
-  // terminal "Fleet dispatched" phase (derived structurally from this worker's BPMN element id).
-  // The failed/no-work path above leaves epic_phase untouched: its terminal signal is status +
-  // outcome, and stamping "Dispatched" against a failed epic would misread. A null derivation
-  // (element id absent) must not clobber the last implementing phase.
-  const epicPhase = deriveEpicPhase(job.elementId);
+  // The epic's terminal "Fleet dispatched" phase is no longer stamped here (S8, #542). While this
+  // finalizer's token is ACTIVE the epic reads `Finalizing` from the live element-instance model
+  // (`pollEpicPhase` → `deriveEpicPhaseLive`); the terminal `Dispatched` is then derived from this
+  // `done` status by `pollEpicPhase` (`deriveTerminalEpicPhase`) — a completion marker with no live
+  // token to read, so it is taken from the durable terminal status, not a fleeting ACTIVE token. The
+  // failed/no-work path above likewise stamps no phase — its terminal signal is status + outcome, and
+  // a `failed` epic is deliberately never labelled Dispatched.
   await plans(app.data).update(planKey, {
     status: "done",
     outcome: `${opened} PR(s) dispatched to convergence`,
-    ...(epicPhase ? { epic_phase: epicPhase } : {}),
     updated_at: ts,
   });
 

package/workers/record-wave/worker.test.ts

@@ -145,8 +145,9 @@ test("record-wave retries the same wave when a task is still pending", async ()
   // Wave progress (current_wave/wave_label) was retired as a stored projection (epic #412) — derived
   // from `plan_tasks` by the plan_wave_label VIEW — so record-wave no longer writes it.
   assertEquals("current_wave" in (planUpdates[0].patch as Record<string, unknown>), false);
-  // Domain-phase projection (#261): more waves remain, so the epic stays Implementing (wave n/t).
-  assertEquals((planUpdates[0].patch as Record<string, unknown>).epic_phase, "Implementing (wave 2/2)");
+  // Domain-phase projection is no longer stamped by this worker (S8, #542) — the epic phase is a pure
+  // read-model derivation off the live element-instance model (`pollEpicPhase`, app/service.ts).
+  assertEquals("epic_phase" in (planUpdates[0].patch as Record<string, unknown>), false);
 });
 
 test("record-wave pins current_wave to the last index and clears gate_wave on the final wave", async () => {
@@ -178,9 +179,9 @@ test("record-wave pins current_wave to the last index and clears gate_wave on th
   assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, null);
   assertEquals("current_wave" in (planUpdates[0].patch as Record<string, unknown>), false);
   assertEquals("wave_label" in (planUpdates[0].patch as Record<string, unknown>), false);
-  // Domain-phase projection (#261): the final wave landed with no successor and no trial merge, so
-  // the epic enters Finalizing (record-results then advances to the Dispatched terminal).
-  assertEquals((planUpdates[0].patch as Record<string, unknown>).epic_phase, "Finalizing");
+  // Domain-phase projection is no longer stamped by this worker (S8, #542) — the epic phase is a pure
+  // read-model derivation off the live element-instance model (`pollEpicPhase`, app/service.ts).
+  assertEquals("epic_phase" in (planUpdates[0].patch as Record<string, unknown>), false);
 });
 
 test("record-wave writes no wave-progress columns for a taskless plan (waveCount 0)", async () => {

package/workers/record-wave/worker.ts

@@ -15,7 +15,6 @@
 // and, crucially, so a later wave's `dependsOn` can reference the PR keys earlier waves produced.
 import type { AppJobHandler } from "@nanobpm/urban";
 import { appendEntry } from "../../app/blackboard.ts";
-import { EPIC_PHASE, implementingPhase } from "../../app/epicPhase.ts";
 import { fetchPrFiles, fetchPrHead } from "../../app/github.ts";
 import { deriveExclusions, recordExclusions } from "../../app/mergeExclusion.ts";
 import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
@@ -302,25 +301,11 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const nextWave = stillPendingCurrentWave ? currentWave : currentWave + 1;
   const hasMoreWaves = stillPendingCurrentWave || nextWave < waveCount;
 
-  // Wave index the epic is now on (issue #137): while more waves remain, the wave about to run; on
-  // the final wave, pinned to the last index so a finished epic reads N/N (nextWave would be
-  // waveCount, one past the last band). This is a LOCAL value only — it is used below to derive the
-  // `epic_phase` (Implementing wave n/t) and the domain phase.
-  const projectedCurrentWave = hasMoreWaves ? nextWave : Math.max(0, waveCount - 1);
-  // Operator-visibility wave progress (current_wave / wave_label) was RETIRED as a stored projection
-  // (epic #412) — it is now derived from `plan_tasks` by the `plan_wave_label` / `plan_read_model`
-  // VIEWs (060/061), so this worker no longer denormalises it (select-wave no longer writes it
-  // either). `projectedCurrentWave` above is not persisted; it only feeds the phase derivation.
-
-  // Domain-phase projection (#261): the wave landed — stamp the phase the epic is ENTERING next,
-  // which is data-dependent here (unlike the structural spine writers). A trial merge runs → Trial
-  // merging; another wave follows → Implementing (next wave n/t); otherwise the finalizer runs →
-  // Finalizing (record-results then advances to the Dispatched terminal).
-  const epicPhase = runTrialMerge
-    ? EPIC_PHASE.TRIAL_MERGING
-    : hasMoreWaves
-      ? implementingPhase(projectedCurrentWave, waveCount)
-      : EPIC_PHASE.FINALIZING;
+  // The epic's domain phase is no longer stamped here (S8, #542) — it is a pure read-model derivation
+  // off the live element-instance model (`pollEpicPhase` → `deriveEpicPhaseLive`, app/epicPhase.ts),
+  // which reads the live token position (a running `implement` fan-out, `trial-merge`, or the
+  // finalizer) directly rather than this worker projecting the phase it is ABOUT to enter. This write
+  // now only arms the durable wave-merge barrier marker.
 
   // Wave-merge barrier: when another wave follows, park the plan-fanout instance at the
   // `wait-wave-merged` catch event until THIS wave's opened PRs have MERGED (not merely opened).
@@ -334,7 +319,6 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   try {
     await plans(app.data).update(planKey, {
       gate_wave: hasMoreWaves ? currentWave : null,
-      epic_phase: epicPhase,
       updated_at: ts,
     });
   } catch (err) {

package/workers/select-wave/worker.test.ts

@@ -83,9 +83,10 @@ test("select-wave dispatches the active wave without writing wave-progress colum
   assertEquals(plans[0].current_wave, undefined);
   assertEquals(plans[0].wave_count, undefined);
   assertEquals(plans[0].wave_label, undefined);
-  // Domain-phase projection (#261): dispatching the wave marks the epic Implementing (wave n/t),
-  // derived from this worker's BPMN element id + the levelize records.
-  assertEquals(plans[0].epic_phase, "Implementing (wave 2/2)");
+  // Domain-phase projection is no longer stamped by this worker (S8, #542) — the epic phase is now a
+  // pure read-model derivation off the live element-instance model (`pollEpicPhase`, app/service.ts),
+  // so select-wave introduces no `epic_phase` onto the plan row.
+  assertEquals(plans[0].epic_phase, undefined);
 });
 
 test("select-wave captures the preflight's resolvedArtifacts onto plans.bound_artifacts (#292 S4)", async () => {

package/workers/select-wave/worker.ts

@@ -16,7 +16,6 @@
 // immediately (the same 0-task path the flat fan-out already relied on).
 import type { AppJobHandler } from "@nanobpm/urban";
 import type { CapabilityNeed } from "../../app/capabilityNeed.ts";
-import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { plans, planTaskDeps, planTaskNeeds, planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -52,20 +51,6 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const statusById = new Map<string, string>();
   for (const r of rows) statusById.set(r.task_id, r.status);
 
-  // Operator-visibility projection (issue #137): mark this as the wave the fleet is now
-  // implementing, so the epics-index can show wave X/N at a glance. wave_count is derivable from
-  // the levelized rows (max wave + 1), so the "X/N" label stays correct even if a re-levelize
-  // changed the total. Best-effort + idempotent (a retry re-writes the same value) and
-  // display-only — it must never gate control flow, which stays driven by the process
-  // `currentWave`/`waveCount`/`gate_wave` state.
-  const waveCount = rows.reduce((m, r) => Math.max(m, r.wave ?? 0), -1) + 1;
-  // Domain-phase projection (#261): select-wave dispatches this wave and is the last host write
-  // before the write-silent `implement` MI, so it durably marks the implementation phase for the
-  // wave it launches — `Implementing (wave n/t)` from the levelize records (job.elementId +
-  // current/total waves). A null derivation (element id absent) must not clobber the phase.
-  const epicPhase = waveCount > 0
-    ? deriveEpicPhase(job.elementId, { current: currentWave, total: waveCount })
-    : null;
   // Inter-epic gate projection (#292 slice S4): reaching select-wave proves this epic's leading
   // capability PREFLIGHT (S3) already went GREEN, so capture the `resolvedArtifacts` the preflight
   // bound — the exact `pkg@version`s first carrying each producer's awaited capability — onto the
@@ -76,20 +61,21 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const boundArtifacts = Array.isArray(job.variables.resolvedArtifacts)
     ? job.variables.resolvedArtifacts.filter((v): v is string => typeof v === "string" && v.trim().length > 0)
     : [];
-  try {
-    await plans(app.data).update(planKey, {
-      // Operator-visibility wave progress (current_wave / wave_count / wave_label) was RETIRED as a
-      // stored projection (epic #412) — it is now derived from `plan_tasks` by the `plan_wave_label`
-      // / `plan_read_model` VIEWs (060/061), so select-wave no longer denormalises it. This write
-      // still stamps the derived domain phase and the inter-epic gate's bound artifacts.
-      ...(epicPhase ? { epic_phase: epicPhase } : {}),
-      ...(boundArtifacts.length > 0 ? { bound_artifacts: JSON.stringify(boundArtifacts) } : {}),
-      updated_at: ts,
-    });
-  } catch (err) {
-    app.log.error(`select-wave: projecting plan row (epic phase / bound artifacts) failed for ${planKey}`, {
-      err: String(err),
-    });
+  // The epic's Implementing (wave n/t) phase is no longer stamped here (S8, #542) — it is a pure
+  // read-model derivation off the live element-instance model (`pollEpicPhase`, app/service.ts), which
+  // reads the running `implement` fan-out directly. This write now only carries the inter-epic gate's
+  // bound artifacts, so it is skipped entirely when there are none.
+  if (boundArtifacts.length > 0) {
+    try {
+      await plans(app.data).update(planKey, {
+        bound_artifacts: JSON.stringify(boundArtifacts),
+        updated_at: ts,
+      });
+    } catch (err) {
+      app.log.error(`select-wave: projecting plan row (bound artifacts) failed for ${planKey}`, {
+        err: String(err),
+      });
+    }
   }
 
   const deps = await planTaskDeps(app.data).find({ plan_key: planKey });