@nanobpm/nano-workforce 0.144.0 → 0.145.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.145.1](https://github.com/nanobpm/nano-workforce/compare/v0.145.0...v0.145.1) (2026-08-26)
+
+### Bug Fixes
+
+* bound the merge-loop wait-landed wait so a never-enqueued PR escalates ([#556](https://github.com/nanobpm/nano-workforce/issues/556)) ([#558](https://github.com/nanobpm/nano-workforce/issues/558)) ([0e14578](https://github.com/nanobpm/nano-workforce/commit/0e14578e23d3914f8ae82a9fd84280fbc05c6588))
+
+## [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/contracts.ts

@@ -136,6 +136,13 @@ export const ENV_CONTRACTS = {
     owner: "app/service.ts",
     semantics: "Minutes between review nudges.",
   },
+  NANO_PR_MERGE_LANDED_WAIT_TIMEOUT: {
+    category: "env",
+    name: "NANO_PR_MERGE_LANDED_WAIT_TIMEOUT",
+    owner: "app/service.ts",
+    semantics:
+      "How long the merge loop waits for a queued PR to actually land before escalating (FEEL/ISO-8601 duration).",
+  },
   NANO_PR_AUTO_MERGE: {
     category: "env",
     name: "NANO_PR_AUTO_MERGE",

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

@@ -0,0 +1,39 @@
+// Unit coverage for the merge-queue landing liveness timeout policy. The value is baked into every
+// merge-loop instance's `landedWaitTimeout` process variable and evaluated by the `wait-landed-timeout`
+// timer catch (the timer arm of the `eg-landed` event-based gateway), so a malformed operator env
+// must never deploy an uninterpretable `<bpmn:timeDuration>` — it falls back to the default instead.
+// Run with `node --test`.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { DEFAULT_MERGE_LANDED_WAIT_TIMEOUT, mergeLandedWaitTimeout } from "./mergeLandedWait.ts";
+
+test("mergeLandedWaitTimeout: blank / absent / malformed → default", () => {
+  assert.equal(mergeLandedWaitTimeout(undefined), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+  assert.equal(mergeLandedWaitTimeout(""), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+  assert.equal(mergeLandedWaitTimeout("   "), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+  assert.equal(mergeLandedWaitTimeout("1h"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT); // missing leading P/T
+  assert.equal(mergeLandedWaitTimeout("P"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT); // no component
+  assert.equal(mergeLandedWaitTimeout("PT"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT); // T with no time part
+  assert.equal(mergeLandedWaitTimeout("garbage"), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+});
+
+test("mergeLandedWaitTimeout: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assert.equal(mergeLandedWaitTimeout("PT30M"), "PT30M");
+  assert.equal(mergeLandedWaitTimeout("pt2h"), "PT2H");
+  assert.equal(mergeLandedWaitTimeout("P1D"), "P1D");
+  assert.equal(mergeLandedWaitTimeout("  pt90m  "), "PT90M");
+});
+
+test("mergeLandedWaitTimeout: an explicit fallback is honoured for a bad value", () => {
+  assert.equal(mergeLandedWaitTimeout("nope", "PT10M"), "PT10M");
+  assert.equal(mergeLandedWaitTimeout("PT45M", "PT10M"), "PT45M");
+});
+
+test("the default is itself a well-formed ISO-8601 duration (never an uninterpretable timer)", () => {
+  // Validate the default against the grammar with a *distinct* fallback: if the default were
+  // malformed it would fall through to the sentinel, so equality to itself proves it parses.
+  const sentinel = "PT1S";
+  assert.notEqual(DEFAULT_MERGE_LANDED_WAIT_TIMEOUT, sentinel);
+  assert.equal(mergeLandedWaitTimeout(DEFAULT_MERGE_LANDED_WAIT_TIMEOUT, sentinel), DEFAULT_MERGE_LANDED_WAIT_TIMEOUT);
+});

package/app/mergeLandedWait.ts

@@ -0,0 +1,39 @@
+// Merge-queue landing liveness policy — kept as a pure module (no env, no I/O) so it is trivially
+// testable, mirroring app/agentSla.ts. `app/service.ts` seeds the validated `landedWaitTimeout`
+// process variable when it starts the merge-loop; the merge-loop's `wait-landed-timeout` timer catch
+// (the timer arm of the `eg-landed` event-based gateway, racing `merge-landed` / `merge-evicted`)
+// evaluates its `<bpmn:timeDuration>=landedWaitTimeout` at timer creation (FEEL-expression timer
+// durations, engine-native).
+//
+// This closes the merge-queue landing liveness gap (issue #556): `attempt-merge` classifies a merge
+// as `queued` on an ambiguous "merge queue" signal (or a REST "accepted but not yet landed"
+// fallback) WITHOUT verifying the PR was actually enqueued. On a repo where a plain `gh pr merge`
+// does not enqueue (e.g. Mergify, which needs an explicit `@Mergifyio queue`), the PR is never
+// placed in any queue, yet the loop parks at `wait-landed` awaiting a `merge-landed` that can never
+// be published — ACTIVE, no incident, no escalation, forever. Bounding the wait with a timer arm
+// makes that impossible: when the timeout elapses the token routes to the existing merge escalation
+// so a human is pulled in (add it to the queue / merge it, then reply to retry). It is a durable,
+// in-process backstop — no external watchdog required, mirroring the convergence loop's
+// `wait-review-timeout`.
+
+import { isoDuration } from "./reviewWait.ts";
+
+/** Default merge-queue landing timeout (ISO-8601 duration): how long the merge loop waits for a
+ * `queued` PR to actually land before the timer arm of the `eg-landed` event-based gateway fires and
+ * it escalates to a human. Deliberately generous — a native GitHub merge queue legitimately takes a
+ * while to build the prospective merged commit and run its required checks — while still bounded so a
+ * never-enqueued PR (the Mergify-eligible-but-unqueued wedge, #556) surfaces to a human rather than
+ * hanging forever. */
+export const DEFAULT_MERGE_LANDED_WAIT_TIMEOUT = "PT1H";
+
+/** Validate the operator-supplied merge-queue landing timeout (env
+ * `NANO_PR_MERGE_LANDED_WAIT_TIMEOUT`, ISO-8601 duration), falling back to
+ * {@link DEFAULT_MERGE_LANDED_WAIT_TIMEOUT} when absent, blank, or malformed — a bad env value must
+ * never deploy an uninterpretable timer expression. Derives its validation from the single canonical
+ * {@link isoDuration}. */
+export function mergeLandedWaitTimeout(
+  raw: string | undefined,
+  def: string = DEFAULT_MERGE_LANDED_WAIT_TIMEOUT,
+): string {
+  return isoDuration(raw, def);
+}

package/app/mergeLoopBehaviour.test.ts

@@ -41,6 +41,7 @@ import {
 const MODEL = readFileSync("resources/processes/merge-loop.bpmn", "utf8");
 
 const AGENT_SLA_MS = 30 * 60 * 1000; // matches the PT30M we start instances with
+const LANDED_WAIT_MS = 30 * 60 * 1000; // matches the PT30M landedWaitTimeout we start instances with
 
 type Output = Record<string, unknown>;
 type Responder = Output | Output[] | ((job: { variables: Record<string, unknown> }) => Output);
@@ -80,6 +81,7 @@ const DEFAULT_VARS: Record<string, unknown> = {
   rebaseRound: 0,
   mergeRetryRound: 0,
   agentSlaTimeout: "PT30M",
+  landedWaitTimeout: "PT30M",
   abandonBrief: null,
   failingChecksList: null,
   status: null,
@@ -206,11 +208,36 @@ test("a queued merge parks on the event gateway; the landed message marks it mer
   const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
   await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
   await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
-  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElements("wait-landed", "wait-evicted");
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElements("wait-landed", "wait-evicted", "wait-landed-timeout");
   await engine.publishMessage({ name: "merge-landed", correlationKey: "pr-1" });
   assertThatInstance(engine, byProcessId("merge-loop")).hasCompleted().hasCompletedElements("mark-merged");
 });
 
+test("a queued merge that never lands escalates when the landing timeout fires (#556)", async () => {
+  // The Mergify wedge: `attempt-merge` classifies the merge `queued` on an ambiguous signal, but the
+  // repo never actually enqueued the PR, so `merge-landed` can never be published. Without the timer
+  // arm the token would park at `wait-landed` forever (ACTIVE, no incident). The timer bounds it.
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-landed");
+  await engine.advanceTime(LANDED_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-landed");
+  assert(!completedElementIds(engine).has("mark-merged"), "a never-landed queued merge must not mark-merged");
+  assertStringIncludes(String(escalation(engine).question ?? ""), "did not land within the merge-queue landing timeout", "the escalation must name the landing-timeout trigger");
+});
+
+test("answering the landing-timeout escalation re-arms the merge poller (#556)", async () => {
+  const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
+  await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "ready" } });
+  await engine.advanceTime(LANDED_WAIT_MS + 1);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  await engine.completeUserTask(await mergeAnswerTaskKey(engine), { answer: "queued it manually, retry" });
+  assertThatInstance(engine, byProcessId("merge-loop")).isActive().hasActiveElement("wait-mergeable");
+});
+
 test("an evicted queued merge re-arms the poller rather than completing", async () => {
   const engine = await boot({ responses: { "pr.merge": { mergeStatus: "queued" } } });
   await engine.publishMessage({ name: "deps-cleared", correlationKey: "pr-1" });

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);
+  });
+});