@nanobpm/nano-workforce 0.143.0 → 0.145.0

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

@@ -0,0 +1,142 @@
+// Unit coverage for the ONE canonical progress step axis (app/stepAxis.ts) — the single source of the
+// derived stepper's vocabulary, cell→step mapping, terminal-tier normalization, and the deterministic
+// parallel-frontier reduction (ADR 0006 §4b, issue #541 / S7).
+
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { STAGE_DONE_STATUSES, STAGE_KEYS } from "./stage.ts";
+import {
+  CELL_STEP,
+  DONE_TERMINAL,
+  type FrontierBranch,
+  INITIAL_STEP,
+  reduceFrontier,
+  STEP_KEYS,
+  stepOrdinal,
+  terminalTier,
+  TERMINAL_STEP,
+} from "./stepAxis.ts";
+
+test("STEP_KEYS is SEEDED from STAGE_KEYS — the axis cannot fork across surfaces", () => {
+  assertEquals([...STEP_KEYS], [...STAGE_KEYS]);
+  // The two lifecycle bookends are the head/tail of the shared axis.
+  assertEquals(INITIAL_STEP, STAGE_KEYS[0]);
+  assertEquals(INITIAL_STEP, "Requested");
+  assertEquals(TERMINAL_STEP, STAGE_KEYS[STAGE_KEYS.length - 1]);
+  assertEquals(TERMINAL_STEP, "Done");
+});
+
+test("the explicit cell→step mapping collapses every process cell onto an existing STAGE_KEYS bracket (no new axis entries)", () => {
+  // The three executable cells map to their lifecycle bracket; the interstitial wait/human/escalation
+  // cells HOLD at the host bracket rather than owning a distinct step.
+  assertEquals(CELL_STEP.implement, "Implementing");
+  assertEquals(CELL_STEP.converge, "Converging");
+  assertEquals(CELL_STEP.merge, "Merging");
+  assertEquals(CELL_STEP.wait, "Implementing");
+  assertEquals(CELL_STEP.human, "Converging");
+  assertEquals(CELL_STEP.escalation, "Converging");
+  // Every mapped bracket is a real axis key — v1 adds no stages, so the pipeline renderer is unchanged.
+  for (const step of Object.values(CELL_STEP)) {
+    assert(STEP_KEYS.includes(step), `cell step "${step}" is not a STAGE_KEYS member`);
+  }
+});
+
+test("stepOrdinal gives the axis total order the frontier reduction compares advancement by", () => {
+  assertEquals(stepOrdinal("Requested"), 0);
+  assertEquals(stepOrdinal("Implementing"), 1);
+  assertEquals(stepOrdinal("PR open"), 2);
+  assertEquals(stepOrdinal("Converging"), 3);
+  assertEquals(stepOrdinal("Merging"), 4);
+  assertEquals(stepOrdinal("Done"), 5);
+});
+
+test("terminalTier reuses the shipped stage_state tiers (converged/merged/done→ok, blocked distinct, failed/skipped/abandoned→failed, active→null)", () => {
+  assertEquals(terminalTier("merged"), "ok");
+  assertEquals(terminalTier("converged"), "ok");
+  assertEquals(terminalTier("done"), "ok");
+  assertEquals(terminalTier("blocked"), "blocked");
+  assertEquals(terminalTier("failed"), "failed");
+  assertEquals(terminalTier("skipped"), "failed");
+  assertEquals(terminalTier("abandoned"), "failed");
+  assertEquals(terminalTier("running"), null);
+  assertEquals(terminalTier("converging"), null);
+});
+
+test("terminalTier's partition is DERIVED from STAGE_DONE_STATUSES — every canonical terminal is tiered exactly once (drift guard)", () => {
+  // The stepAxis module already throws at load if the partition drifts from STAGE_DONE_STATUSES; assert
+  // the coupling here too so a reviewer sees the invariant. Every STAGE_DONE_STATUSES member gets a
+  // non-null tier, and the only status tiered OUTSIDE that canonical set is the delivery-graph `done`.
+  for (const status of STAGE_DONE_STATUSES) {
+    assert(terminalTier(status) !== null, `STAGE_DONE_STATUSES member "${status}" must be tiered by terminalTier`);
+  }
+  assertEquals(terminalTier(DONE_TERMINAL), "ok");
+  assert(!STAGE_DONE_STATUSES.includes(DONE_TERMINAL), "`done` is the S7 canonical success value, tiered on top of STAGE_DONE_STATUSES (not a member of it)");
+});
+
+// ── reduceFrontier — the deterministic parallel-frontier rollup (§4b §280-332) ────────────────────
+
+const branch = (nodeId: string, step: FrontierBranch["step"], terminal: string | null = null): FrontierBranch => ({ nodeId, step, terminal });
+
+test("a single branch reduces trivially to itself (the feature + S7 delivery-graph coarse case)", () => {
+  assertEquals(reduceFrontier([branch("n0", "Implementing")]), { step: "Implementing", state: null });
+  assertEquals(reduceFrontier([branch("n0", "Done", "done")]), { step: "Done", state: "ok" });
+  assertEquals(reduceFrontier([branch("n0", "Done", "failed")]), { step: "Done", state: "failed" });
+});
+
+test("all-active frontier reduces to the LEAST-ADVANCED active branch (never further than the slowest in-flight branch)", () => {
+  const r = reduceFrontier([branch("a", "Merging"), branch("b", "Implementing"), branch("c", "Converging")]);
+  assertEquals(r, { step: "Implementing", state: null });
+});
+
+test("all-active ties on step break deterministically by stable node id", () => {
+  const r = reduceFrontier([branch("z", "Converging"), branch("a", "Converging")]);
+  assertEquals(r, { step: "Converging", state: null });
+});
+
+test("MIXED with only SUCCESS terminals + active branches reduces to the least-advanced ACTIVE branch (terminal branches are past, not 'still blocked on')", () => {
+  const r = reduceFrontier([branch("done1", "Done", "merged"), branch("active1", "Converging"), branch("active2", "Merging")]);
+  assertEquals(r, { step: "Converging", state: null });
+});
+
+test("MIXED: a NON-SUCCESS terminal (failed) takes precedence over in-flight siblings — the aggregate renders that branch's step + failed state", () => {
+  const r = reduceFrontier([branch("active", "Implementing"), branch("bad", "Converging", "failed"), branch("done", "Done", "merged")]);
+  assertEquals(r, { step: "Converging", state: "failed" });
+});
+
+test("MIXED: a blocked terminal surfaces as the DISTINCT blocked render state (operator-actionable), not masked by an active sibling", () => {
+  const r = reduceFrontier([branch("active", "Merging"), branch("stuck", "Implementing", "blocked")]);
+  assertEquals(r, { step: "Implementing", state: "blocked" });
+});
+
+test("MULTIPLE non-success terminals tie-break by earliest terminal step, then stable node id", () => {
+  // Two failed branches at different steps → earliest step wins.
+  assertEquals(
+    reduceFrontier([branch("a", "Converging", "failed"), branch("b", "Implementing", "blocked"), branch("act", "Merging")]),
+    { step: "Implementing", state: "blocked" },
+  );
+  // Two non-success terminals at the SAME step → stable node id wins (and its own render state).
+  assertEquals(
+    reduceFrontier([branch("z", "Converging", "failed"), branch("a", "Converging", "blocked")]),
+    { step: "Converging", state: "blocked" },
+  );
+});
+
+test("ALL-TERMINAL, all success → done (the axis tail, ok)", () => {
+  const r = reduceFrontier([branch("a", "Converging", "converged"), branch("b", "Merging", "merged")]);
+  assertEquals(r, { step: "Done", state: "ok" });
+});
+
+test("ALL-TERMINAL with any non-success → earliest non-success terminal step (same tie-break)", () => {
+  const r = reduceFrontier([branch("a", "Merging", "merged"), branch("b", "Converging", "failed"), branch("c", "Implementing", "blocked")]);
+  assertEquals(r, { step: "Implementing", state: "blocked" });
+});
+
+test("reduceFrontier throws on an empty frontier — a unit always has at least its own branch", () => {
+  let threw = false;
+  try {
+    reduceFrontier([]);
+  } catch {
+    threw = true;
+  }
+  assert(threw, "expected reduceFrontier([]) to throw");
+});