@nanobpm/nano-workforce 0.82.0 → 0.83.0

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

@@ -12,7 +12,7 @@ import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
 import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
-import { deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureRuns } from "./feature.ts";
+import { backfillFeatureStages, deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
   coalesceTitle,
@@ -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,16 +1642,34 @@ 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). */
+/** One-shot guard so the feature-stage backfill (`backfillFeatureStages`) runs at most once per
+ * process, on the first `pollOnce`. Idempotent regardless, but there is no need to re-scan every row
+ * on every poll. */
+let featureStagesBackfilled = false;
+
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
   token: string,
   engineRest?: { restAddress: string; token?: string },
 ) {
+  // One-shot: re-project any pre-#254 feature_runs rows whose pipeline columns are still NULL. The
+  // gateway keeps every future write fresh, so this only needs to run once per process and is safe to
+  // re-run (it re-derives from each row's own stored fields).
+  if (!featureStagesBackfilled) {
+    // Only arm the one-shot guard AFTER a successful backfill: setting it first would swallow a
+    // transient failure (e.g. a DB blip) and leave legacy rows unprojected forever, since every later
+    // pass would skip. On a throw the guard stays false and the next `pollOnce` retries.
+    await backfillFeatureStages(data);
+    featureStagesBackfilled = true;
+  }
   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 +1677,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/app/stage.test.ts

@@ -0,0 +1,107 @@
+// Unit tests for the canonical feature-run pipeline stage model (issue #254 §1). `deriveStage` is the
+// ONE source of truth the feature_runs gateway projects onto the stored pipeline columns, so the
+// mapping must be TOTAL and DETERMINISTIC over every FEATURE_RUN_STATUS and emit the urban 0.53.0
+// `kind:"pipeline"` renderer's EXACT vocabulary (state `ok|failed|blocked|null`).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { deriveListBucket, deriveStage, type StageInput } from "./stage.ts";
+
+const base = (over: Partial<StageInput> & { status: string }): StageInput => ({
+  pr_key: null,
+  converge: 1,
+  auto_merge: 1,
+  escalation_question: null,
+  escalation_user_task_key: null,
+  blocked_user_task_key: null,
+  ...over,
+});
+
+test("deriveStage is TOTAL: every one of the 11 statuses maps to a defined stage and state", () => {
+  assertEquals(FEATURE_RUN_STATUSES.length, 11);
+  for (const status of FEATURE_RUN_STATUSES) {
+    const d = deriveStage(base({ status }));
+    assert(d.stage !== undefined, `stage undefined for ${status}`);
+    assert(
+      ["Requested", "Implementing", "PR open", "Converging", "Merging", "Done"].includes(d.stage),
+      `stage out of range for ${status}: ${d.stage}`,
+    );
+    // state is one of the renderer's exact values (null allowed)
+    assert([null, "ok", "failed", "blocked"].includes(d.state), `state out of range for ${status}: ${d.state}`);
+  }
+});
+
+test("status -> stage mapping (each row)", () => {
+  // Terminal tier → Done.
+  for (const status of ["merged", "converged", "blocked", "failed", "skipped", "abandoned"]) {
+    assertEquals(deriveStage(base({ status })).stage, "Done", status);
+  }
+  // Live/parked tier.
+  assertEquals(deriveStage(base({ status: "converging" })).stage, "Converging");
+  assertEquals(deriveStage(base({ status: "opened" })).stage, "PR open");
+  assertEquals(deriveStage(base({ status: "running", pr_key: "o/r#9" })).stage, "PR open");
+  assertEquals(deriveStage(base({ status: "running" })).stage, "Implementing");
+  // The pre-start/created initial state (unknown non-terminal, no pr_key) → Requested.
+  assertEquals(deriveStage(base({ status: "created" })).stage, "Requested");
+});
+
+test("state: the three non-null values plus the null in-progress case", () => {
+  assertEquals(deriveStage(base({ status: "merged" })).state, "ok");
+  assertEquals(deriveStage(base({ status: "converged" })).state, "ok");
+  assertEquals(deriveStage(base({ status: "failed" })).state, "failed");
+  assertEquals(deriveStage(base({ status: "skipped" })).state, "failed");
+  assertEquals(deriveStage(base({ status: "abandoned" })).state, "failed");
+  assertEquals(deriveStage(base({ status: "blocked" })).state, "blocked");
+  // Every non-terminal status → null (in-progress).
+  for (const status of ["running", "opened", "converging", "escalated", "awaiting_operator"]) {
+    assertEquals(deriveStage(base({ status })).state, null, status);
+  }
+});
+
+test("state emits 'failed' (not 'fail') so the renderer does not degrade a failure to active", () => {
+  assertEquals(deriveStage(base({ status: "failed" })).state, "failed");
+});
+
+test("skipped: the three converge/auto_merge cases", () => {
+  // converge off → skip both.
+  assertEquals(deriveStage(base({ status: "running", converge: 0, auto_merge: 0 })).skipped, "Converging Merging");
+  // converge on, auto_merge off → skip Merging only.
+  assertEquals(deriveStage(base({ status: "running", converge: 1, auto_merge: 0 })).skipped, "Merging");
+  // both on → empty.
+  assertEquals(deriveStage(base({ status: "running", converge: 1, auto_merge: 1 })).skipped, "");
+});
+
+test("attention: blocked, escalation, none", () => {
+  assertEquals(deriveStage(base({ status: "awaiting_operator", blocked_user_task_key: "ut-1" })).attention, "blocked");
+  assertEquals(deriveStage(base({ status: "escalated", escalation_user_task_key: "ut-2" })).attention, "⚠");
+  assertEquals(deriveStage(base({ status: "escalated", escalation_question: "which base?" })).attention, "⚠");
+  assertEquals(deriveStage(base({ status: "running" })).attention, null);
+});
+
+// The three parked-status rows called out by the plan review.
+test("escalated WITH pr_key → PR open / null", () => {
+  const d = deriveStage(base({ status: "escalated", pr_key: "o/r#5" }));
+  assertEquals(d.stage, "PR open");
+  assertEquals(d.state, null);
+});
+
+test("escalated WITHOUT pr_key → Implementing / null", () => {
+  const d = deriveStage(base({ status: "escalated", pr_key: null }));
+  assertEquals(d.stage, "Implementing");
+  assertEquals(d.state, null);
+});
+
+test("awaiting_operator WITHOUT pr_key → Implementing / null, attention 'blocked' when parked", () => {
+  const d = deriveStage(base({ status: "awaiting_operator", pr_key: null, blocked_user_task_key: "ut-3" }));
+  assertEquals(d.stage, "Implementing");
+  assertEquals(d.state, null);
+  assertEquals(d.attention, "blocked");
+});
+
+test("deriveListBucket: history iff terminal AND acknowledged, else active", () => {
+  assertEquals(deriveListBucket("merged", null), "active");
+  assertEquals(deriveListBucket("merged", "2024-01-01T00:00:00Z"), "history");
+  // A non-terminal status is always active, even if (spuriously) acknowledged.
+  assertEquals(deriveListBucket("running", "2024-01-01T00:00:00Z"), "active");
+  assertEquals(deriveListBucket("blocked", "2024-01-01T00:00:00Z"), "history");
+});

package/app/stage.ts

@@ -0,0 +1,111 @@
+// Canonical feature-run pipeline stage model (issue #254 §1) — the ONE source of truth for the
+// derived pipeline surface the Feature view renders. Mirrors the single-source-of-truth style of
+// `deriveDelivery` (app/delivery.ts) and `classifyEscalation` (app/escalationTaxonomy.ts): a PURE,
+// read-only function with no data access. The feature_runs gateway (app/feature.ts) projects its
+// output onto the stored `stage`/`stage_state`/`stage_skipped`/`attention` columns at write time,
+// exactly as `delivery_label` is projected — so the declarative dataGrid page consumes ready, stored
+// columns (bound by `{"field":…}`) and never has to call TS or express OR/null in its flat filter DSL.
+//
+// The mapping is TOTAL and DETERMINISTIC over all 11 FEATURE_RUN_STATUSES, computed from ONLY the
+// fields stored on the row — never a "previous"/"underlying" stage, because a FeatureRun stores only
+// its CURRENT status (any prior stage was overwritten on transition). Do NOT duplicate this mapping
+// anywhere (not in SQL, not in the page, not in each poller/worker): every writer flows through the
+// gateway, which is the single caller.
+
+/** The canonical pipeline stage keys, in path order. `Merging` is a path/visual stage the renderer
+ * fills as upcoming — no status maps to it as the ACTIVE stage (intentional). */
+export const STAGE_KEYS = ["Requested", "Implementing", "PR open", "Converging", "Merging", "Done"] as const;
+export type StageKey = (typeof STAGE_KEYS)[number];
+
+/** The active stage's render state, in the urban 0.53.0 `kind:"pipeline"` column's EXACT vocabulary:
+ * `ok` (Done ✓ success), `failed` (Done ✕ failure), `blocked` (blocked glyph), or `null` (in-progress
+ * → the renderer treats it as `active`). Any OTHER string silently degrades to `active` in the
+ * renderer, so a failed run MUST emit `'failed'` (not `'fail'`) to render as a failure. */
+export type StageState = "ok" | "failed" | "blocked" | null;
+
+/** The 6 TRULY-terminal statuses that map to the `Done` stage. Distinct from
+ * `FEATURE_TERMINAL_STATUSES` (app/feature.ts), which is the redispatch-settled set and also counts
+ * `opened`/`converging` as terminal — those are LIVE pipeline stages (`PR open`/`Converging`), NOT
+ * Done, so this list must stay separate. Also the basis of the `list_bucket` history partition. */
+export const STAGE_DONE_STATUSES: readonly string[] = [
+  "merged",
+  "converged",
+  "blocked",
+  "failed",
+  "skipped",
+  "abandoned",
+];
+
+/** The subset of a FeatureRun `deriveStage` reads. FeatureRun (app/feature.ts) structurally satisfies
+ * this; keeping the input structural avoids a stage.ts ↔ feature.ts import cycle. */
+export interface StageInput {
+  status: string;
+  pr_key?: string | null;
+  converge?: number | boolean | null;
+  auto_merge?: number | boolean | null;
+  escalation_question?: string | null;
+  escalation_user_task_key?: string | null;
+  blocked_user_task_key?: string | null;
+}
+
+/** The derived pipeline projection for one run. `skipped` is a space-separated set of stage keys not
+ * in this row's path (bound to the renderer's `notInPathField`). */
+export interface DerivedStage {
+  stage: StageKey;
+  state: StageState;
+  skipped: string;
+  attention: string | null;
+}
+
+const truthy = (v: number | boolean | null | undefined): boolean => v === true || (typeof v === "number" && v !== 0);
+
+/** Derive the canonical pipeline stage, its render state, its not-in-path set, and its attention badge
+ * for one feature run. Pure and read-only — TOTAL over all 11 statuses (never returns undefined). */
+export function deriveStage(run: StageInput): DerivedStage {
+  const { status } = run;
+
+  // TERMINAL tier — the 6 truly-terminal statuses collapse to Done. Unconditional: terminal `blocked`
+  // is the issue §1 'Done ✕' row (state `blocked`), NOT Implementing.
+  let stage: StageKey;
+  let state: StageState;
+  if (STAGE_DONE_STATUSES.includes(status)) {
+    stage = "Done";
+    state =
+      status === "merged" || status === "converged"
+        ? "ok"
+        : status === "blocked"
+          ? "blocked"
+          : "failed"; // failed / skipped / abandoned
+  } else {
+    // LIVE/PARKED tier — one shared rule for every non-terminal status. `escalated`/`awaiting_operator`
+    // are parked but their stored fields still describe WHERE in the pipeline they stalled, so they run
+    // through the same rule as a live run; their attention comes from the badge (below), not the stage.
+    if (status === "converging") stage = "Converging";
+    else if ((run.pr_key ?? "") !== "" || status === "opened") stage = "PR open";
+    else if (status === "running" || status === "escalated" || status === "awaiting_operator") stage = "Implementing";
+    else stage = "Requested";
+    state = null;
+  }
+
+  // `skipped`: stages not in this row's path, purely from converge/auto_merge.
+  const converge = truthy(run.converge);
+  const autoMerge = truthy(run.auto_merge);
+  const skippedKeys: StageKey[] = !converge ? ["Converging", "Merging"] : !autoMerge ? ["Merging"] : [];
+
+  // `attention`: a short badge for the active stage (the renderer colours it from `state`). This is how
+  // a parked `awaiting_operator`/`escalated` run surfaces as attention WITHOUT altering its stage.
+  const attention = run.blocked_user_task_key
+    ? "blocked"
+    : run.escalation_user_task_key || run.escalation_question
+      ? "⚠"
+      : null;
+
+  return { stage, state, skipped: skippedKeys.join(" "), attention };
+}
+
+/** The Active/History partition label (§5), maintained at write time so the flat-DSL page tabs filter
+ * on a stored `list_bucket` column with only `in` clauses. `history` iff the row is in a truly-terminal
+ * status AND acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). */
+export function deriveListBucket(status: string, acknowledgedAt: string | null | undefined): "active" | "history" {
+  return STAGE_DONE_STATUSES.includes(status) && acknowledgedAt != null ? "history" : "active";
+}

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;