@nanobpm/nano-workforce 0.81.0 → 0.82.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.82.1](https://github.com/nanobpm/nano-workforce/compare/v0.82.0...v0.82.1) (2026-08-17)
+
+
+### Bug Fixes
+
+* **plan-fanout:** make the wave-merge barrier level-triggered ([#262](https://github.com/nanobpm/nano-workforce/issues/262)) ([#264](https://github.com/nanobpm/nano-workforce/issues/264)) ([ae939d8](https://github.com/nanobpm/nano-workforce/commit/ae939d8e96f136f820fcae9149c120806ddc6f1b))
+
+# [0.82.0](https://github.com/nanobpm/nano-workforce/compare/v0.81.0...v0.82.0) (2026-08-17)
+
+
+### Features
+
+* reify epic domain lifecycle as derived plans.epic_phase ([#261](https://github.com/nanobpm/nano-workforce/issues/261)) ([#265](https://github.com/nanobpm/nano-workforce/issues/265)) ([4cc9dee](https://github.com/nanobpm/nano-workforce/commit/4cc9deee86b800206d264d96269e6a98e8753883)), closes [#266](https://github.com/nanobpm/nano-workforce/issues/266) [nwf#245](https://github.com/nwf/issues/245) [nano-ide#254](https://github.com/nano-ide/issues/254)
+
 # [0.81.0](https://github.com/nanobpm/nano-workforce/compare/v0.80.0...v0.81.0) (2026-08-17)
 
 

package/SPEC.md

@@ -530,6 +530,17 @@ History: done/failed/abandoned) with a `plan_tasks` child grid showing each task
 status and the PR it produced (`pr_key` cross-references the Pull requests grid for
 convergence status).
 
+**Epic domain phase** (issue #261): `plans.status` only distinguishes the process-instance
+terminal (`dispatched` = "fan-out job done"), not the epic's *domain* lifecycle. The read model
+therefore also carries a derived, display-only `plans.epic_phase` — **Planning → Reviewing →
+Implementing (wave n/t) → Trial merging → Finalizing → Dispatched** — projected at write time from
+`plan-fanout.bpmn`'s named activities via each spine worker's BPMN element id (`app/epicPhase.ts`,
+the single binding; nwf is the first consumer of the urban phase-projection primitive, nano-ide#266).
+The `Implementing` band is wave-labelled from the levelize records (`plan_tasks` waves). The epic /
+epic-detail pages surface it as a **Phase** column. It never gates control flow (that stays driven by
+the process `currentWave`/`waveCount`/`gate_wave`); a post-dispatch cross-instance rollup into
+Converging/Merging is a later seam (nwf#245 / nano-ide#254).
+
 ### 13.1 Dependency waves + merge barrier (issues #20, #26, release-notes-concierge)
 
 The flat `implement → record-results` shape above evolved into a **wave loop**. The
@@ -554,11 +565,14 @@ the loop runs one parallel `implement` MI fan-out per wave:
   `dependsOn`), and advances `currentWave`.
 - **Wave-merge barrier** (`wait-wave-merged`): when a wave has a successor,
   `record-wave` sets `plans.gate_wave` to that wave's index and the process parks at
-  the `wait-wave-merged` catch event. The poller's `pollWaveGates` pass publishes the
-  `wave-merged` message (correlated on `planKey`) once **every opened PR in that wave
-  has merged** (`app/waves.ts` `waveMergeTargets` selects the PRs to wait on;
-  `blocked`/`skipped`/keyless tasks clear vacuously), then clears `gate_wave`
-  single-shot. So a `dependsOn` means the dependent wave is not **implemented** until
+  the `wait-wave-merged` catch event. The poller's `pollWaveGatesImpl` pass is
+  **level-triggered**: it publishes the `wave-merged` message (correlated on `planKey`)
+  once **every opened PR in that wave has merged** (`app/waves.ts` `waveMergeTargets`
+  selects the PRs to wait on; `blocked`/`skipped`/keyless tasks clear vacuously) **and**
+  it observes an OPEN `wait-wave-merged` subscription for the plan — so a merge that
+  lands while the token is still upstream can't drop the signal. The poller **never**
+  clears `gate_wave`; `record-wave` owns the marker's lifecycle (re-arming it to the next
+  wave, or clearing it to NULL on the final wave). So a `dependsOn` means the dependent wave is not **implemented** until
   its prerequisites have **landed on the base branch** — not merely opened. This lets
   a blocking prerequisite (e.g. app scaffolding) fully converge and merge before the
   next wave builds on it. `gate_wave` lives in `db/migrations/007_wave_gate.sql`.

package/app/epicPhase.test.ts

@@ -0,0 +1,62 @@
+// Read-model derivation test for the epic domain phase (issue #261). `deriveEpicPhase` /
+// `implementingPhase` are the single source of truth for the write-time projection each spine
+// worker stamps onto `plans.epic_phase`. The projection binds structurally to plan-fanout.bpmn's
+// named activities via the job's BPMN element id (mirroring the urban #266 phase primitive), so the
+// 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";
+
+test("deriveEpicPhase maps each spine element to its domain phase", () => {
+  // Planning genesis + hand-off into Reviewing when the plan is recorded.
+  assertEquals(deriveEpicPhase("plan"), EPIC_PHASE.PLANNING);
+  assertEquals(deriveEpicPhase("ensure-base-branch"), EPIC_PHASE.PLANNING);
+  assertEquals(deriveEpicPhase("record-plan"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("review-plan"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("record-plan-review"), EPIC_PHASE.REVIEWING);
+  assertEquals(deriveEpicPhase("plan-review-decision"), EPIC_PHASE.REVIEWING);
+  // Trial-merge band.
+  assertEquals(deriveEpicPhase("trial-merge"), EPIC_PHASE.TRIAL_MERGING);
+  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);
+});
+
+test("deriveEpicPhase wave-labels the Implementing band from the levelize records", () => {
+  // select-wave / record-wave / the implement MI + wait-wave-merged all read as Implementing,
+  // labelled with the 1-based wave from the wave/levelize records (0-based `current`).
+  assertEquals(
+    deriveEpicPhase("select-wave", { current: 0, total: 3 }),
+    "Implementing (wave 1/3)",
+  );
+  assertEquals(
+    deriveEpicPhase("record-wave", { current: 2, total: 3 }),
+    "Implementing (wave 3/3)",
+  );
+  assertEquals(
+    deriveEpicPhase("wait-wave-merged", { current: 1, total: 3 }),
+    "Implementing (wave 2/3)",
+  );
+  assertEquals(deriveEpicPhase("implement-task", { current: 0, total: 1 }), "Implementing (wave 1/1)");
+});
+
+test("deriveEpicPhase returns null for a non-spine element so a stray write never clobbers", () => {
+  assertEquals(deriveEpicPhase(undefined), null);
+  assertEquals(deriveEpicPhase(null), null);
+  assertEquals(deriveEpicPhase(""), null);
+  assertEquals(deriveEpicPhase("some-unrelated-element"), null);
+});
+
+test("implementingPhase clamps the 1-based label to the total and degrades gracefully", () => {
+  assertEquals(implementingPhase(0, 2), "Implementing (wave 1/2)");
+  // A `current` at/over the last index (record-wave pins current_wave to waveCount-1 on the final
+  // wave) never reads past n/n.
+  assertEquals(implementingPhase(5, 3), "Implementing (wave 3/3)");
+  // Unusable wave numbers (taskless plan / NaN counter) degrade to a bare Implementing — never
+  // "wave NaN/…".
+  assertEquals(implementingPhase(0, 0), "Implementing");
+  assertEquals(implementingPhase(undefined, undefined), "Implementing");
+  assertEquals(implementingPhase("x", "y"), "Implementing");
+});

package/app/epicPhase.ts

@@ -0,0 +1,125 @@
+// app/epicPhase.ts — reify the epic's own domain lifecycle as a derived `epic_phase` (issue #261).
+//
+// `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
+// epic's domain phase. `plan-fanout.bpmn` already models the rich lifecycle as named activities
+// (Ensure base branch → Plan → Review plan → Select wave → Implement task → Trial merge → Finalize
+// → "Fleet dispatched"); this module reifies that lifecycle as a stored, display-only projection so
+// the epic view can show which phase the epic is in.
+//
+// Convention over declaration: the phases ARE the activities plan-fanout.bpmn already names. Each
+// spine worker derives its projection from its OWN BPMN element id (`job.elementId`) — no annotation
+// map on the model, no second reconciliation pass — mirroring the urban structural phase-projection
+// primitive (nano-ide#266), which derives the phase from the furthest element reached in
+// write-provenance. This module is the single binding (nwf is #266's first consumer).
+//
+// Write-time projection: because the phase only advances when a worker writes, each spine worker
+// stamps the phase the epic is ENTERING as a result of its write — the write points ARE the phase
+// boundaries. Two structural defaults are coarsened where the raw activity label would mislead
+// (documented on `ELEMENT_PHASE` below): `select-wave` reads as `Implementing (wave n/t)` because it
+// dispatches and durably marks the (write-silent) `implement` multi-instance subProcess, and
+// `record-results` reads as the `Dispatched` terminal ("Fleet dispatched").
+//
+// Cross-instance rollup (later): post-dispatch, the epic's effective phase extends into the
+// convergence/merge loops carried on separate top-level instances correlated by lineage
+// (`rootRequestKey`, nwf#245 / nano-ide#254). Once #266's Tier-2 rollup lands, `epic_phase` can
+// advance past `Dispatched` into Converging/Merging with no new wiring here — the seam is this
+// module's derivation staying the single source.
+
+/** The epic's domain phases — the vocabulary the derivation projects onto `plans.epic_phase`.
+ *  Shared with the feature-view stage vocabulary (nwf#254), which uses the same stored-projection
+ *  pattern. `Implementing` is wave-labelled at derivation time (see {@link implementingPhase}). */
+export const EPIC_PHASE = {
+  PLANNING: "Planning",
+  REVIEWING: "Reviewing",
+  IMPLEMENTING: "Implementing",
+  TRIAL_MERGING: "Trial merging",
+  FINALIZING: "Finalizing",
+  DISPATCHED: "Dispatched",
+} as const;
+
+/** Coerce a wave index/count to a non-negative integer, or null when it isn't one. Mirrors the
+ *  `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 => {
+  const n = Math.trunc(Number(v));
+  return Number.isFinite(n) && n >= 0 ? n : null;
+};
+
+/**
+ * `Implementing (wave n/t)` — special-cased from the wave/levelize records (`plan_tasks` waves),
+ * NOT the raw multi-instance counter. `current` is the 0-based wave index carried on the process
+ * (`currentWave` / the projected `current_wave`); the label is 1-based and clamped to `total` so a
+ * final wave reads `n/n`. Falls back to a bare `Implementing` when the wave numbers aren't usable
+ * (e.g. a taskless plan with `total` 0), so the phase never renders `wave NaN`.
+ */
+export function implementingPhase(current: unknown, total: unknown): string {
+  const t = toWave(total);
+  const c = toWave(current);
+  if (t !== null && t > 0 && c !== null) {
+    const n = Math.min(c + 1, t);
+    return `${EPIC_PHASE.IMPLEMENTING} (wave ${n}/${t})`;
+  }
+  return EPIC_PHASE.IMPLEMENTING;
+}
+
+/**
+ * Structural binding: `plan-fanout.bpmn` element id → the domain phase the epic is IN while that
+ * element (or the write-silent agent step it hands off to) runs. Complete over the epic's spine, so
+ * the projection is derivable from provenance alone (the urban #266 semantics). Two entries are
+ * deliberately COARSENED from their raw activity label because the structural default misleads:
+ *   • `record-plan` ("Record plan & levelize") → Reviewing: recording the plan hands the epic to the
+ *     `review-plan` agent, so the review phase should already read while that (write-silent) agent
+ *     runs. `record-plan-review` re-affirms Reviewing on each round/escalation.
+ *   • `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-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.
+ */
+const ELEMENT_PHASE: Readonly<Record<string, string>> = {
+  "ensure-base-branch": EPIC_PHASE.PLANNING,
+  "plan": EPIC_PHASE.PLANNING,
+  "record-plan": EPIC_PHASE.REVIEWING,
+  "review-plan": EPIC_PHASE.REVIEWING,
+  "record-plan-review": EPIC_PHASE.REVIEWING,
+  "plan-review-decision": EPIC_PHASE.REVIEWING,
+  "select-wave": EPIC_PHASE.IMPLEMENTING,
+  "implement": EPIC_PHASE.IMPLEMENTING,
+  "implement-task": EPIC_PHASE.IMPLEMENTING,
+  "feature-escalation": EPIC_PHASE.IMPLEMENTING,
+  "record-wave": EPIC_PHASE.IMPLEMENTING,
+  "wait-wave-merged": EPIC_PHASE.IMPLEMENTING,
+  "trial-merge": EPIC_PHASE.TRIAL_MERGING,
+  "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,
+};
+
+/** Optional wave context for a wave-bearing phase, sourced from the wave/levelize records. */
+export interface WaveContext {
+  current?: unknown;
+  total?: unknown;
+}
+
+/**
+ * Derive the epic phase for a spine element from its BPMN element id, or `null` when the element
+ * doesn't mark a phase — so a non-spine write (e.g. a poller reconcile pass) never clobbers
+ * `epic_phase`. A wave-bearing phase (`Implementing`) is wave-labelled from {@link WaveContext} when
+ * supplied. This is the single structural deriver; workers pass `job.elementId` so the phase name is
+ * never hardcoded at the call site.
+ */
+export function deriveEpicPhase(
+  elementId: string | undefined | null,
+  wave?: WaveContext,
+): string | null {
+  if (!elementId) return null;
+  const base = ELEMENT_PHASE[elementId];
+  if (base === undefined) return null;
+  if (base === EPIC_PHASE.IMPLEMENTING) return implementingPhase(wave?.current, wave?.total);
+  return base;
+}

package/app/plan.ts

@@ -11,6 +11,7 @@
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
+import { EPIC_PHASE } from "./epicPhase.ts";
 import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
 import { coalesceTitle, ensureBaseBranch, fetchDefaultBranch, fetchIssueTitle } from "./github.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
@@ -82,6 +83,12 @@ export interface Plan {
   // in app/service.ts); `delivery_label` is the human rollup for the epic detail view. Display-only.
   delivery: string | null;
   delivery_label: string | null;
+  // Derived epic domain phase (038_plan_epic_phase.sql, #261): the epic's own lifecycle phase —
+  // Planning / Reviewing / Implementing (wave n/t) / Trial merging / Finalizing / Dispatched —
+  // projected at write time from plan-fanout.bpmn's named activities (app/epicPhase.ts), so the epic
+  // view can show which phase the epic is IN rather than only the process-instance terminal status.
+  // Display-only; NULL until the lifecycle first stamps it (grandfathers pre-#261 rows).
+  epic_phase: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -436,6 +443,9 @@ export async function startPlan(
       issue_url: parsed.url,
       title,
       outcome: null,
+      // Genesis of the domain lifecycle (#261): the epic re-enters Planning. Cleared of any stale
+      // terminal phase from the prior run so the re-plan reads correctly from the first pass.
+      epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
       updated_at: ts,
@@ -449,6 +459,8 @@ export async function startPlan(
       title,
       status: "planning",
       task_count: 0,
+      // Genesis of the domain lifecycle (#261): a fresh epic starts in Planning.
+      epic_phase: EPIC_PHASE.PLANNING,
       blackboard_token: token,
       base_branch: base,
       created_at: ts,

package/app/service.test.ts

@@ -7,7 +7,7 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { parsePr, pollIncidentsImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
+import { parsePr, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -502,3 +502,190 @@ test("parsePr still resolves a well-formed prKey and PR URL", () => {
   assertEquals(parsePr("  owner/repo#42  ")?.number, 42);
   assertEquals(parsePr("https://github.com/owner/repo/pull/7")?.repo, "owner/repo");
 });
+
+// Red/green regression for the level-triggered wave-merge barrier (issue #262). The barrier is
+// armed (`plans.gate_wave = W`) at wave handoff, long BEFORE the token traverses the slow
+// `trial-merge` agent job and finally opens the `wait-wave-merged` subscription. The old
+// `pollWaveGates` was edge-triggered: the first pass that saw wave W's PRs merged cleared
+// `gate_wave` and published `wave-merged` EXACTLY ONCE. If that happened while the token was still
+// upstream (no open subscription), the message was dropped and — with `gate_wave` now null — never
+// republished, so the epic wedged forever once the token arrived. The fix reconciles the merged
+// state against the engine's OPEN-subscription state every pass, publishing only into an open
+// subscription and never clearing `gate_wave` optimistically.
+//
+// Stubs `/message-subscriptions/search` (keyed by processInstanceKey) so the subscription can be
+// toggled open between passes, and forces the GitHub transport off — the wave's PRs are tracked
+// `merged` rows, so `isDepMerged` resolves them from the DB with no network.
+function subscriptionFetch(open: Set<string>) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/message-subscriptions/search")) {
+      throw new Error(`unexpected fetch: ${u}`);
+    }
+    const body = JSON.parse(String(init?.body ?? "{}")) as {
+      filter?: { processInstanceKey?: string };
+    };
+    const pik = body.filter?.processInstanceKey ?? "";
+    const items = open.has(pik)
+      ? [{ messageName: "wave-merged", correlationKey: "owner/repo#67", messageSubscriptionState: "CREATED" }]
+      : [];
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+test("pollWaveGatesImpl is level-triggered: PRs merged before the token arrives never lose the wave-merged signal (#262)", async () => {
+  await withGithubOff(async () => {
+    const PLAN_KEY = "owner/repo#67";
+    const PI = "PI-13794";
+    // Wave 1 opened two PRs; both are already MERGED (tracked rows → isDepMerged resolves from DB).
+    const plan = {
+      plan_key: PLAN_KEY,
+      process_key: PI,
+      gate_wave: 1 as number | null,
+      updated_at: "t0",
+    };
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      plans: { rows: [plan], key: "plan_key" },
+      plan_tasks: {
+        rows: [
+          { id: "owner/repo#67:a", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#68" },
+          { id: "owner/repo#67:b", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#69" },
+        ],
+        key: "id",
+      },
+      pull_requests: {
+        rows: [
+          { pr_key: "owner/repo#68", status: "merged" },
+          { pr_key: "owner/repo#69", status: "merged" },
+        ],
+        key: "pr_key",
+      },
+    };
+    const data = {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    } as any;
+
+    const published: { name: string; correlationKey?: string }[] = [];
+    const engine = {
+      publishMessage: (input: { name: string; correlationKey?: string }) => {
+        published.push(input);
+        return Promise.resolve();
+      },
+    } as any;
+    const headers = { "content-type": "application/json" };
+
+    const openSubs = new Set<string>(); // token still upstream of wait-wave-merged → NO open subscription
+    const prevFetch = globalThis.fetch;
+
+    // Pass 1 — the losing ordering: wave 1's PRs are all merged, but the token is parked upstream on
+    // the slow `trial-merge` job, so there is no open `wait-wave-merged` subscription yet. The old
+    // single-shot barrier would publish-into-the-void and CLEAR `gate_wave`, stranding the epic.
+    globalThis.fetch = subscriptionFetch(openSubs) as typeof fetch;
+    try {
+      await pollWaveGatesImpl(data, engine, "", "http://engine/v2", headers);
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+    // The signal must NOT have been fired into the void, and the gate must remain armed (not stranded).
+    assertEquals(published.length, 0, "must not publish wave-merged with no open subscription");
+    assertEquals(plan.gate_wave, 1, "gate_wave must stay armed until the barrier is actually released");
+
+    // Pass 2 — the token has now advanced to `wait-wave-merged`, opening the subscription. The
+    // level-triggered barrier re-publishes and correlates, releasing the token into wave 2.
+    openSubs.add(PI);
+    globalThis.fetch = subscriptionFetch(openSubs) as typeof fetch;
+    try {
+      await pollWaveGatesImpl(data, engine, "", "http://engine/v2", headers);
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+    assertEquals(published.length, 1, "must publish wave-merged once the subscription is open");
+    assertEquals(published[0]?.name, "wave-merged");
+    assertEquals(published[0]?.correlationKey, PLAN_KEY);
+  });
+});
+
+// Guards the false-positive failure class flagged in review: `waveMergedSubscriptionOpen` must treat
+// a search item with a missing/null/mismatched `messageName`, `correlationKey`, or
+// `messageSubscriptionState` as NOT-open. Defaulting an unverifiable field to its expected value
+// would publish `wave-merged` into a subscription we never confirmed open — buffering a message that
+// trips a LATER wave's barrier, i.e. re-introducing the exact #262 wedge this change prevents. A
+// false negative only costs a retry next pass; a false positive is a wedge, so unknown ⇒ don't match.
+function ambiguousSubscriptionFetch(items: unknown[]) {
+  return (url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/message-subscriptions/search")) {
+      throw new Error(`unexpected fetch: ${u}`);
+    }
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+test("pollWaveGatesImpl never releases the barrier on an unverifiable subscription item (missing/null/mismatched fields)", async () => {
+  await withGithubOff(async () => {
+    const PLAN_KEY = "owner/repo#67";
+    const PI = "PI-13794";
+    const plan = {
+      plan_key: PLAN_KEY,
+      process_key: PI,
+      gate_wave: 1 as number | null,
+      updated_at: "t0",
+    };
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      plans: { rows: [plan], key: "plan_key" },
+      plan_tasks: {
+        rows: [
+          { id: "owner/repo#67:a", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#68" },
+          { id: "owner/repo#67:b", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#69" },
+        ],
+        key: "id",
+      },
+      pull_requests: {
+        rows: [
+          { pr_key: "owner/repo#68", status: "merged" },
+          { pr_key: "owner/repo#69", status: "merged" },
+        ],
+        key: "pr_key",
+      },
+    };
+    const data = {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    } as any;
+
+    const published: { name: string; correlationKey?: string }[] = [];
+    const engine = {
+      publishMessage: (input: { name: string; correlationKey?: string }) => {
+        published.push(input);
+        return Promise.resolve();
+      },
+    } as any;
+    const headers = { "content-type": "application/json" };
+    const prevFetch = globalThis.fetch;
+
+    // Each of these items is ambiguous — it omits or mismatches a field the barrier requires. None
+    // may be treated as an OPEN subscription for THIS plan, so none may release wave 1's gate.
+    const ambiguousItems: unknown[][] = [
+      [{}], // empty item — no fields at all
+      [{ messageName: "wave-merged", correlationKey: PLAN_KEY }], // missing state
+      [{ messageName: "wave-merged", correlationKey: PLAN_KEY, messageSubscriptionState: null }], // null state
+      [{ correlationKey: PLAN_KEY, messageSubscriptionState: "CREATED" }], // missing messageName
+      [{ messageName: "some-other-message", correlationKey: PLAN_KEY, messageSubscriptionState: "CREATED" }],
+      [{ messageName: "wave-merged", messageSubscriptionState: "CREATED" }], // missing correlationKey
+      [{ messageName: "wave-merged", correlationKey: "owner/repo#999", messageSubscriptionState: "CREATED" }],
+    ];
+    for (const items of ambiguousItems) {
+      globalThis.fetch = ambiguousSubscriptionFetch(items) as typeof fetch;
+      try {
+        await pollWaveGatesImpl(data, engine, "", "http://engine/v2", headers);
+      } finally {
+        globalThis.fetch = prevFetch;
+      }
+    }
+    assertEquals(published.length, 0, "must not publish wave-merged on an unverifiable subscription item");
+    assertEquals(plan.gate_wave, 1, "gate_wave must stay armed while no OPEN subscription is confirmed");
+  });
+});

package/app/service.ts

@@ -1141,17 +1141,104 @@ export async function pollIncidentsImpl(
   }
 }
 
-/** Wave-merge barrier poll pass. After `record-wave` hands off a wave that has a successor, the
- * plan-fanout instance parks at the `wait-wave-merged` catch event and `plans.gate_wave` records
- * that wave's index. Here we check whether every OPENED PR in that wave has MERGED and, if so,
- * publish `wave-merged` (correlated on the plan key) to release the next wave's implementation.
+/** The `wave-merged` message name (`resources/processes/plan-fanout.bpmn`): the `wait-wave-merged`
+ * catch event opens a subscription for it (correlated on `=planKey`) once the token arrives, and
+ * the poller publishes it to release the next wave. Single source of truth for the string shared by
+ * the publish and the subscription probe. */
+const WAVE_MERGED_MESSAGE = "wave-merged";
+
+/** The subset of a Camunda-8 `/v2/message-subscriptions/search` result item this app reads to tell
+ * whether the plan-fanout instance is *currently parked* at `wait-wave-merged`. `messageName` is the
+ * awaited message; `correlationKey` is the plan key the catch event binds; `messageSubscriptionState`
+ * is `CREATED` while the subscription is open (waiting) and `CORRELATED`/`DELETED` once consumed. */
+interface MessageSubscriptionSearchItem {
+  messageName?: string;
+  correlationKey?: string | null;
+  messageSubscriptionState?: string;
+}
+
+/** Is the plan-fanout instance `processKey` right now parked at `wait-wave-merged` with an OPEN
+ * (`CREATED`) subscription correlated on `planKey`? Reads the engine's Camunda-8
+ * `/v2/message-subscriptions/search` (the same raw-REST search surface `pollIncidents`/
+ * `pollJobActivation` use). Returns `true` (open — safe to release), `false` (no open subscription —
+ * the token is either upstream of the wait or has already passed through it), or `null` (transport
+ * unhappy / unparseable body — "unknown", so the caller neither publishes nor acts on a guess and
+ * simply retries next tick). This is the load-bearing check that makes the barrier level-triggered:
+ * we only ever publish `wave-merged` into a subscription we've observed OPEN, so a signal can never
+ * be dropped into the void (the #262 wedge) nor buffered to trip a *later* wave's barrier. */
+async function waveMergedSubscriptionOpen(
+  base: string,
+  headers: Record<string, string>,
+  processKey: string,
+  planKey: string,
+): Promise<boolean | null> {
+  try {
+    const res = await fetch(`${base}/message-subscriptions/search`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        filter: {
+          processInstanceKey: processKey,
+          messageName: WAVE_MERGED_MESSAGE,
+          messageSubscriptionState: "CREATED",
+        },
+        page: { limit: 20 },
+      }),
+    });
+    if (!res.ok) return null; // engine unhappy → "unknown", retry next pass
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const body = (await res.json()) as { items?: MessageSubscriptionSearchItem[] };
+    // Re-filter defensively in case the engine ignores a filter field: an OPEN (`CREATED`)
+    // subscription for the `wave-merged` message, correlated on THIS plan key, is the barrier we may
+    // publish into. Every field must be PRESENT and match explicitly — we never default a
+    // missing/null `messageName`, `correlationKey`, or `messageSubscriptionState` to its expected
+    // value. Doing so would treat an unverifiable item as OPEN and re-introduce the exact #262
+    // failure class (publishing into a subscription we never confirmed open, buffering a message that
+    // trips a later wave's barrier). An item that omits a field is "unknown", so we simply don't
+    // match it: a false negative only costs a retry next pass, whereas a false positive is a wedge.
+    // State is compared case-insensitively so a future casing tweak can't silently drop the match.
+    return (body.items ?? []).some(
+      (it) =>
+        it.messageName === WAVE_MERGED_MESSAGE &&
+        it.correlationKey === planKey &&
+        typeof it.messageSubscriptionState === "string" &&
+        it.messageSubscriptionState.toUpperCase() === "CREATED",
+    );
+  } catch (err) {
+    console.error(`[poller] wave-merged subscription ${planKey}: ${err}`);
+    return null; // transport threw → "unknown", retry next pass
+  }
+}
+
+/** Wave-merge barrier poll pass (issue #262). After `record-wave` hands off a wave that has a
+ * successor, the plan-fanout instance eventually parks at the `wait-wave-merged` catch event and
+ * `plans.gate_wave` records that wave's index. Here we reconcile, on EVERY pass and idempotently,
+ * the external GitHub fact "every OPENED PR in that wave has MERGED" against the engine fact "is
+ * there an OPEN `wait-wave-merged` subscription for this plan right now?", publishing `wave-merged`
+ * (correlated on the plan key) to release the next wave's implementation whenever BOTH hold.
  *
- * `gate_wave` is cleared single-shot BEFORE publishing (and restored if the publish fails —
- * mirroring `flipToMergingThenPublish`) so a slow pass can't double-signal and a later wave's
- * barrier can't be tripped by a stale message reusing the same plan-key correlation. A wave whose
- * tasks all ended `blocked`/`skipped` (no opened PR to wait on) clears vacuously — there is
- * nothing to merge, and that failure has already cascaded to dependents in `select-wave`. */
-async function pollWaveGates(data: DataLayer, engine: EngineClient, token: string) {
+ * This is deliberately LEVEL-triggered, not the old single-shot edge trigger. The gate is armed at
+ * wave handoff — long before the token traverses `select-wave → trial-merge (a slow agent job) →
+ * … → wait-wave-merged` and opens the subscription. If the wave's PRs merged while the token was
+ * still upstream, the old code published its one `wave-merged` into NO open subscription (dropped)
+ * AND cleared `gate_wave`, so it never republished and the epic wedged forever once the token
+ * finally arrived (#262). We fix the class:
+ *   • We publish ONLY when {@link waveMergedSubscriptionOpen} confirms the token is parked at the
+ *     wait — never into the void — so a merged-before-arrival wave simply waits, and a later pass
+ *     (once the token arrives) republishes and correlates.
+ *   • We NEVER clear `gate_wave` here. `record-wave` owns its lifecycle (it re-arms it to the next
+ *     wave, or clears it to `null` on the final wave), so a signal published into the void can't
+ *     strand the gate, and double-advance is guarded by the open-subscription check — which, by the
+ *     handoff ordering, always matches the wave whose wait is currently open — not by a premature
+ *     clear. A wave whose tasks all ended `blocked`/`skipped` (no opened PR to wait on) has an empty
+ *     merge-target set and so is treated as merged; `record-wave` advances it on the next pass. */
+export async function pollWaveGatesImpl(
+  data: DataLayer,
+  engine: EngineClient,
+  token: string,
+  base: string,
+  headers: Record<string, string>,
+) {
   for (const plan of await plans(data).all()) {
     const gateWave = plan.gate_wave;
     if (gateWave == null) continue;
@@ -1165,18 +1252,14 @@ async function pollWaveGates(data: DataLayer, engine: EngineClient, token: strin
           break;
         }
       }
-      if (!allMerged) continue;
-      await plans(data).update(planKey, { gate_wave: null, updated_at: now() });
-      try {
-        await engine.publishMessage({ name: "wave-merged", correlationKey: planKey, variables: {} });
-      } catch (err) {
-        try {
-          await plans(data).update(planKey, { gate_wave: gateWave, updated_at: now() });
-        } catch (revertErr) {
-          console.error(`[poller] revert wave-gate ${planKey} -> ${gateWave} failed: ${revertErr}`);
-        }
-        throw err;
-      }
+      if (!allMerged) continue; // wave not landed yet → leave the gate armed, retry next pass
+      // The wave has landed on GitHub. Release the barrier ONLY if the token is actually parked at
+      // `wait-wave-merged` (an OPEN subscription for this plan): otherwise publishing would be a
+      // silent no-op that the old code paired with a gate clear — the edge-triggered wedge (#262).
+      if (!plan.process_key) continue; // no instance key to correlate against yet
+      const open = await waveMergedSubscriptionOpen(base, headers, plan.process_key, planKey);
+      if (open !== true) continue; // not parked here yet / already released / unknown → NEVER clear the gate; retry next pass
+      await engine.publishMessage({ name: WAVE_MERGED_MESSAGE, correlationKey: planKey, variables: {} });
       console.log(`[poller] wave ${gateWave} merged -> ${planKey}`);
     } catch (err) {
       console.error(`[poller] wave-gate ${planKey}: ${err}`);
@@ -1559,7 +1642,11 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
 
 /** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and
  * (when the engine REST endpoint is supplied) the job-activation visibility pass and the
- * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`. */
+ * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`.
+ *
+ * The wave-merge barrier is now level-triggered and probes the engine's message-subscription state
+ * over the same raw-REST search surface, so it runs only when `engineRest` is supplied (as in
+ * production — `main.ts` always passes it). */
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
@@ -1568,7 +1655,6 @@ export async function pollOnce(
 ) {
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
-  await pollWaveGates(data, engine, token);
   await pollDelivery(data);
   await pollFeatureDelivery(data);
   await pollLineage(data);
@@ -1576,6 +1662,10 @@ export async function pollOnce(
   await pollFeatureBlocked(data, engine);
   await pollUserTasks(data, engine);
   if (engineRest) {
+    const base = engineRest.restAddress.replace(/\/+$/, "");
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (engineRest.token) headers.authorization = `Bearer ${engineRest.token}`;
+    await pollWaveGatesImpl(data, engine, token, base, headers);
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);
   }

package/db/migrations/007_wave_gate.sql

@@ -10,7 +10,10 @@
 --
 -- `plans.gate_wave` is the durable marker for the barrier: when `record-wave` hands
 -- off a wave that has a successor, it records that wave's index here and the process
--- parks at the `wait-wave-merged` catch event. The poller (`pollWaveGates`) clears it
--- and publishes `wave-merged` once every opened PR in that wave has merged. NULL means
--- the plan is not currently parked at the wave barrier.
+-- parks at the `wait-wave-merged` catch event. The poller (`pollWaveGatesImpl`) is
+-- level-triggered: it publishes `wave-merged` once every opened PR in that wave has
+-- merged AND it observes an OPEN `wait-wave-merged` subscription for the plan, and it
+-- NEVER clears `gate_wave` — `record-wave` owns the marker's lifecycle (re-arming it to
+-- the next wave, or clearing it to NULL on the final wave). NULL means the plan is not
+-- currently parked at the wave barrier.
 ALTER TABLE plans ADD COLUMN gate_wave INTEGER;

package/db/migrations/038_plan_epic_phase.sql

@@ -0,0 +1,12 @@
+-- 038_plan_epic_phase.sql — issue #261: reify the epic's own domain lifecycle as a derived,
+-- write-time-projected `epic_phase`, so the epic/plan view can show WHICH phase an epic is in —
+-- Planning / Reviewing / Implementing (wave n/t) / Trial merging / Finalizing / Dispatched —
+-- instead of only the process-instance terminal status (`plans.status`, whose `dispatched` is the
+-- `plan-fanout.bpmn` fan-out terminal, not the epic's domain phase).
+--
+-- Forward-only, additive (expand): a nullable TEXT column, display-only. NULL until the plan
+-- lifecycle first stamps it (grandfathering pre-#261 rows), so it never gates control flow. The
+-- value is derived structurally from `plan-fanout.bpmn`'s named activities via each spine worker's
+-- BPMN element id (`app/epicPhase.ts`) and written through the existing plan write path — mirroring
+-- the wave-progress / delivery display projections already on this table.
+ALTER TABLE plans ADD COLUMN epic_phase TEXT;

package/package.json

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

package/pages/epic-detail.page.json

@@ -57,6 +57,7 @@
         },
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "34%", "linkField": "issue_url" },
+          { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "wave_label", "header": "Wave" },

package/pages/epic.page.json

@@ -75,6 +75,7 @@
         ],
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "plan_key", "truncate": true, "width": "34%", "link": { "kind": "page", "page": "epic-detail", "keyField": "plan_key" } },
+          { "field": "epic_phase", "header": "Phase" },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "delivery", "header": "Delivery" },
           { "field": "base_branch", "header": "Base branch" },

package/workers/record-plan/worker.ts

@@ -16,6 +16,7 @@
 // warning; the ordering is lost but every task still runs. No `plan_task_deps` are recorded
 // in that case (the edges were invalid).
 import type { AppJobHandler } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { planTaskDeps, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
@@ -127,6 +128,11 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     wave_label: tasks.length > 0 ? `1/${waveCount}` : null,
     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 app.data.table("plans", "plan_key").update(planKey, patch);
 

package/workers/record-results/worker.ts

@@ -13,6 +13,7 @@
 
 import type { AppJobHandler } from "@nanobpm/urban";
 import { BpmnError } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -49,9 +50,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);
   await app.data.table("plans", "plan_key").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

@@ -144,6 +144,8 @@ test("record-wave retries the same wave when a task is still pending", async ()
   assertEquals((planUpdates[0].patch as Record<string, unknown>).gate_wave, 1);
   // Retry keeps the projection on the same (still-pending) wave.
   assertEquals((planUpdates[0].patch as Record<string, unknown>).current_wave, 1);
+  // 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)");
 });
 
 test("record-wave pins current_wave to the last index and clears gate_wave on the final wave", async () => {
@@ -174,6 +176,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((planUpdates[0].patch as Record<string, unknown>).current_wave, 2);
   assertEquals((planUpdates[0].patch as Record<string, unknown>).wave_label, "3/3");
+  // 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");
 });
 
 test("record-wave keeps all wave-progress fields NULL for a taskless plan (waveCount 0)", async () => {

package/workers/record-wave/worker.ts

@@ -15,6 +15,7 @@
 // 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";
@@ -280,11 +281,23 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   const currentWaveProjection = waveCount > 0 ? projectedCurrentWave : null;
   const waveLabel = waveCount > 0 ? `${projectedCurrentWave + 1}/${waveCount}` : null;
 
+  // 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;
+
   // 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).
-  // `gate_wave` is that durable marker; the poller (`pollWaveGates`) clears it and publishes
-  // `wave-merged` once the wave has landed. Clear it on the final wave so a re-planned issue can't
-  // inherit a stale gate. Best-effort: a failed marker write must not fail the wave (the poller
+  // `gate_wave` is that durable marker; the level-triggered poller (`pollWaveGatesImpl`) publishes
+  // `wave-merged` once the wave has landed AND it observes an OPEN subscription, but NEVER clears
+  // `gate_wave` — record-wave owns the marker's lifecycle. Re-arm it to the next wave here, or
+  // clear it on the final wave so a re-planned issue can't inherit a stale gate. Best-effort: a
+  // failed marker write must not fail the wave (the poller
   // reconciles from `plan_tasks`/`pull_requests`), but the loop still relies on it to know which
   // wave to watch, so we log a failure loudly.
   try {
@@ -292,6 +305,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       gate_wave: hasMoreWaves ? currentWave : null,
       current_wave: currentWaveProjection,
       wave_label: waveLabel,
+      epic_phase: epicPhase,
       updated_at: ts,
     });
   } catch (err) {

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

@@ -67,7 +67,7 @@ test("select-wave projects the active wave onto plans.current_wave", async () =>
   ];
   const plans: Record<string, unknown>[] = [{ plan_key: "owner/repo#63", current_wave: 0 }];
   const out = await handler(
-    { variables: { planKey: "owner/repo#63", currentWave: 1 } } as any,
+    { variables: { planKey: "owner/repo#63", currentWave: 1 }, elementId: "select-wave" } as any,
     fakeApp(rows, [], plans),
   );
   assertEquals((out as { waveTasks: unknown[] }).waveTasks.length, 1);
@@ -76,6 +76,9 @@ test("select-wave projects the active wave onto plans.current_wave", async () =>
   // is pre-formatted for the epics-index at-a-glance column.
   assertEquals(plans[0].wave_count, 2);
   assertEquals(plans[0].wave_label, "2/2");
+  // 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)");
 });
 
 test("select-wave nulls all three progress fields when there are no levelized rows", async () => {

package/workers/select-wave/worker.ts

@@ -15,6 +15,7 @@
 // Emitting an empty `waveTasks` is fine: the MI activity over an empty collection completes
 // immediately (the same 0-task path the flat fan-out already relied on).
 import type { AppJobHandler } from "@nanobpm/urban";
+import { deriveEpicPhase } from "../../app/epicPhase.ts";
 import { plans, planTaskDeps, planTasks } from "../../app/plan.ts";
 import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
@@ -53,6 +54,13 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // 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;
   try {
     await plans(app.data).update(planKey, {
       // Keep the three progress fields consistent: with no levelized rows (waveCount 0) there is
@@ -60,6 +68,7 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
       current_wave: waveCount > 0 ? currentWave : null,
       wave_count: waveCount > 0 ? waveCount : null,
       wave_label: waveCount > 0 ? `${currentWave + 1}/${waveCount}` : null,
+      ...(epicPhase ? { epic_phase: epicPhase } : {}),
       updated_at: ts,
     });
   } catch (err) {