@nanobpm/nano-workforce 0.119.0 → 0.120.1

package/app/migration064.test.ts

@@ -0,0 +1,176 @@
+// Read-model guard for migration 064's `lineage_thread_view` VIEW (epic #412: retire the
+// worker-maintained `lineage_threads` denormalisation in favour of SQL VIEWs for the parts that are
+// clean rollups). Mirrors the derived-read-model test style of app/migration037.test.ts and
+// app/planWaveSummary.test.ts: apply the migration to a real in-memory SQLite DB and assert the
+// VIEW's output over sample rows — so this exercises the real view, not a re-implementation.
+//
+// The view DERIVES the view-expressible identity columns (`kind`, `issue_url`, and an epic/feature
+// thread's `title`) from the `plans` / `feature_runs` origin joins, and PASSES THROUGH the
+// procedural frontier columns (`stage`/`stage_label`/`process_key`/`pr_keys`/`pr_count`/`active`/
+// timestamps) from `lineage_threads`. It must reproduce EXACTLY what `pollLineage` wrote for the
+// migrated columns, so a future drop of those `lineage_threads` columns is behaviour-preserving.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+const MIGRATION = fileURLToPath(new URL("../db/migrations/064_lineage_thread_view.sql", import.meta.url));
+
+/** A DB with the base shapes the view reads (`lineage_threads`, `plans`, `feature_runs`) plus the
+ *  view applied. The `lineage_threads` schema also models `kind`/`issue_url`, which the view does
+ *  NOT read (it derives them from the `plans`/`feature_runs` origin joins) — they are kept here so
+ *  `addThread` can write exactly what `pollLineage` denormalises. */
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE lineage_threads (
+       root_request_key TEXT PRIMARY KEY, kind TEXT, title TEXT, issue_url TEXT, stage TEXT,
+       stage_label TEXT, process_key TEXT, pr_keys TEXT, pr_count INTEGER, active INTEGER,
+       created_at TEXT, updated_at TEXT);
+     CREATE TABLE plans (plan_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);
+     CREATE TABLE feature_runs (feature_key TEXT PRIMARY KEY, title TEXT, issue_url TEXT);`,
+  );
+  db.exec(readFileSync(MIGRATION, "utf8"));
+  return db;
+}
+
+/** Insert a `lineage_threads` row exactly as `pollLineage` denormalises one. */
+function addThread(
+  db: DatabaseSync,
+  row: {
+    root_request_key: string;
+    kind: string;
+    title: string | null;
+    issue_url: string | null;
+    stage: string;
+    stage_label: string | null;
+    process_key: string | null;
+    pr_keys: string | null;
+    pr_count: number;
+    active: number;
+  },
+): void {
+  db.prepare(
+    `INSERT INTO lineage_threads (root_request_key, kind, title, issue_url, stage, stage_label,
+       process_key, pr_keys, pr_count, active, created_at, updated_at)
+     VALUES (@root_request_key, @kind, @title, @issue_url, @stage, @stage_label, @process_key,
+       @pr_keys, @pr_count, @active, 't0', 't1')`,
+  ).run(row);
+}
+
+test("lineage_thread_view derives kind/issue_url/title for an epic thread from the plans origin", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO plans (plan_key, title, issue_url) VALUES (?, ?, ?)").run(
+    "o/r#2",
+    "Epic: retire projections",
+    "https://github.com/o/r/issues/2",
+  );
+  // pollLineage wrote the same identity values (denormalised) alongside the procedural frontier.
+  addThread(db, {
+    root_request_key: "o/r#2",
+    kind: "epic",
+    title: "Epic: retire projections",
+    issue_url: "https://github.com/o/r/issues/2",
+    stage: "converging",
+    stage_label: "3/5 slices merged, 2 converging",
+    process_key: "P-epic",
+    pr_keys: '["o/r#20","o/r#21"]',
+    pr_count: 5,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#2") as Record<string, unknown>;
+  // Derived from the plans join — identical to what the poller denormalised.
+  assertEquals(v.kind, "epic");
+  assertEquals(v.title, "Epic: retire projections");
+  assertEquals(v.issue_url, "https://github.com/o/r/issues/2");
+  // Procedural frontier columns pass through unchanged from lineage_threads.
+  assertEquals(v.stage, "converging");
+  assertEquals(v.stage_label, "3/5 slices merged, 2 converging");
+  assertEquals(v.process_key, "P-epic");
+  assertEquals(v.pr_keys, '["o/r#20","o/r#21"]');
+  assertEquals(v.pr_count, 5);
+  assertEquals(v.active, 1);
+});
+
+test("lineage_thread_view derives kind/issue_url/title for a feature thread from the feature_runs origin", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO feature_runs (feature_key, title, issue_url) VALUES (?, ?, ?)").run(
+    "o/r#1",
+    "Feature: add widget",
+    "https://github.com/o/r/issues/1",
+  );
+  addThread(db, {
+    root_request_key: "o/r#1",
+    kind: "feature",
+    title: "Feature: add widget",
+    issue_url: "https://github.com/o/r/issues/1",
+    stage: "merged",
+    stage_label: "Merged",
+    process_key: "P-feat",
+    pr_keys: '["o/r#10"]',
+    pr_count: 1,
+    active: 0,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#1") as Record<string, unknown>;
+  assertEquals(v.kind, "feature");
+  assertEquals(v.title, "Feature: add widget");
+  assertEquals(v.issue_url, "https://github.com/o/r/issues/1");
+  assertEquals(v.stage, "merged");
+  assertEquals(v.active, 0);
+});
+
+test("lineage_thread_view self-roots an origin-less PR: kind 'pr', NULL issue_url, title falls back to the poller value", () => {
+  const db = viewDb();
+  // No plans / feature_runs row for this root — it is a human/webhook PR that is its own root.
+  addThread(db, {
+    root_request_key: "o/r#30",
+    kind: "pr",
+    title: "hotfix: bump dep",
+    issue_url: null,
+    stage: "converging",
+    stage_label: "Converging (round 2)",
+    process_key: "P-pr",
+    pr_keys: '["o/r#30"]',
+    pr_count: 1,
+    active: 1,
+  });
+
+  const v = db
+    .prepare("SELECT * FROM lineage_thread_view WHERE root_request_key = ?")
+    .get("o/r#30") as Record<string, unknown>;
+  assertEquals(v.kind, "pr");
+  // issue_url is always NULL for a self-rooted PR, exactly as deriveLineage sets it.
+  assertEquals(v.issue_url, null);
+  // The PR title is the procedural representative-PR pick, so it comes through from lineage_threads.
+  assertEquals(v.title, "hotfix: bump dep");
+  assertEquals(v.stage_label, "Converging (round 2)");
+});
+
+test("lineage_thread_view reproduces the migrated columns for every thread the poller wrote", () => {
+  const db = viewDb();
+  db.prepare("INSERT INTO plans (plan_key, title, issue_url) VALUES ('o/r#2', 'Epic', 'u-epic')").run();
+  db.prepare("INSERT INTO feature_runs (feature_key, title, issue_url) VALUES ('o/r#1', 'Feat', 'u-feat')").run();
+  const rows = [
+    { root_request_key: "o/r#2", kind: "epic", title: "Epic", issue_url: "u-epic", stage: "converging", stage_label: "…", process_key: "a", pr_keys: "[]", pr_count: 2, active: 1 },
+    { root_request_key: "o/r#1", kind: "feature", title: "Feat", issue_url: "u-feat", stage: "merged", stage_label: "Merged", process_key: "b", pr_keys: "[]", pr_count: 1, active: 0 },
+    { root_request_key: "o/r#30", kind: "pr", title: "PR", issue_url: null, stage: "opened", stage_label: "Opened", process_key: null, pr_keys: "[]", pr_count: 1, active: 1 },
+  ];
+  for (const r of rows) addThread(db, r);
+
+  // The view's migrated columns must equal what pollLineage denormalised, for all three kinds.
+  for (const r of rows) {
+    const v = db
+      .prepare("SELECT kind, title, issue_url FROM lineage_thread_view WHERE root_request_key = ?")
+      .get(r.root_request_key) as Record<string, unknown>;
+    assertEquals(v.kind, r.kind);
+    assertEquals(v.title, r.title);
+    assertEquals(v.issue_url, r.issue_url);
+  }
+});

package/app/plan.test.ts

@@ -350,7 +350,7 @@ test("startPlan fails fast when readiness probes are seeded without a probeTimeo
         engine,
         { repo: "owner/repo", number: 292, url: "https://github.com/owner/repo/issues/292", planKey: PLAN_KEY },
         "epic/gate-branch",
-        { readinessProbes: [probe] as any, probeTimeout: "   " },
+        { readinessProbes: [probe] as any, probeTimeout: "   ", probePollEvery: "PT15S" },
       ),
     Error,
     "probeTimeout",

package/app/plan.ts

@@ -964,6 +964,7 @@ function assertAcyclic(adjacency: Map<string, Set<string>>): void {
 export interface StartPlanOptions {
   readinessProbes?: ReadinessProbe[];
   probeTimeout?: string;
+  probePollEvery?: string;
 }
 
 /** Register a plan row (if new) and start the plan-fanout process. Idempotent on
@@ -988,6 +989,13 @@ export async function startPlan(
         "bound. Derive it via readinessTimeout (see planLowering) before starting a gated dependent.",
     );
   }
+  if (probes && (opts.probePollEvery ?? "").trim() === "") {
+    throw new Error(
+      `startPlan(${parsed.planKey}): ${probes.length} readiness probe(s) seeded without a probePollEvery — ` +
+        "the preflight retry timers (=probePollEvery) require a non-blank cadence. Derive it via " +
+        "readinessPollEvery (see planLowering) before starting a gated dependent.",
+    );
+  }
   const table = plans(data);
   const existing = await table.get(parsed.planKey);
   if (existing && !PLAN_TERMINAL_STATUSES.includes(existing.status)) {
@@ -1108,6 +1116,7 @@ export async function startPlan(
       // the variable in that FEEL expression instead of raising an incident.
       readinessProbes: probes,
       probeTimeout: opts.probeTimeout ?? null,
+      probePollEvery: opts.probePollEvery ?? null,
       // The preflight probe worker (`pr.readiness-probe`) requires a non-blank `gateKey` correlation
       // key (it publishes `readiness-ready` on it). The typed `ReadinessProbeIn` envelope projects it
       // from THIS process scope (not task-local ioMapping), so it is seeded here — one per dependent

package/app/planFanoutPreflight.test.ts

@@ -48,21 +48,21 @@ test("the preflight is a multi-instance subprocess over =readinessProbes collect
 });
 
 test("the preflight reuses the pr.readiness-probe worker and the readiness-escalation form (no reinvention)", () => {
-  const sub = flat.match(/<bpmn:subProcess\b[^>]*\bid="readiness-preflight"[\s\S]*?<\/bpmn:subProcess>/)![0];
-  assertStringIncludes(sub, 'type="pr.readiness-probe"', "reuses the existing capability probe worker");
-  assertStringIncludes(sub, 'value="ReadinessProbeIn"', "feeds the shared probe input envelope");
-  assertStringIncludes(sub, 'value="ReadinessProbeOut"', "reads the shared probe output envelope");
-  assertStringIncludes(sub, 'formId="readiness-escalation"', "reuses the existing readiness escalation form");
+  assertStringIncludes(flat, 'type="pr.readiness-probe"', "reuses the existing capability probe worker");
+  assertStringIncludes(flat, 'value="ReadinessProbeIn"', "feeds the shared probe input envelope");
+  assertStringIncludes(flat, 'value="ReadinessProbeOut"', "reads the shared probe output envelope");
+  assertStringIncludes(flat, 'formId="readiness-escalation"', "reuses the existing readiness escalation form");
 });
 
 test("a never-green producer escalates (bounded) without wedging: probe timeout + SLA both settle the gate", () => {
-  const sub = flat.match(/<bpmn:subProcess\b[^>]*\bid="readiness-preflight"[\s\S]*?<\/bpmn:subProcess>/)![0];
-  // The probe carries an interrupting timeout bound (reuses the gate's =probeTimeout), and the human
-  // escalation carries the shared SLA bound — so a stuck producer can never wedge the dependent.
-  assertStringIncludes(sub, "=probeTimeout", "the probe is bounded by the reused =probeTimeout");
-  assertStringIncludes(sub, "=escalationSlaTimeout", "the escalation is bounded by the shared SLA");
-  assert(hasFlow("be_pf_probe_timeout", "readiness-escalation-pf"), "a timed-out probe routes to escalation");
-  assert(hasFlow("pf_gw", "readiness-escalation-pf"), "a not-ready probe routes to escalation");
+  // The probe loop carries an interrupting timeout bound (reuses the gate's =probeTimeout), and the
+  // human escalation carries the shared SLA bound — so a stuck producer can never wedge the dependent.
+  assertStringIncludes(flat, "=probeTimeout", "the probe loop is bounded by the reused =probeTimeout");
+  assertStringIncludes(flat, "=probePollEvery", "retry cadence is driven by the engine timer");
+  assertStringIncludes(flat, "=escalationSlaTimeout", "the escalation is bounded by the shared SLA");
+  assert(hasFlow("be_pf_probe_timeout", "preflight-probe-last-attempt"), "a timed-out loop routes to one last empirical probe");
+  assert(hasFlow("preflight-probe-last-attempt", "pf_gw"), "the last attempt can still take the ready path");
+  assert(hasFlow("pf_gw", "readiness-escalation-pf"), "a not-ready final probe routes to escalation");
   assert(hasFlow("be_pf_sla", "pf_end"), "an elapsed escalation SLA settles the preflight instead of wedging");
 });
 

package/app/planLowering.test.ts

@@ -139,6 +139,7 @@ test("deriveEpicSchedule: a dependent with MULTIPLE inbound edges waits for ALL
   assertEquals(dep.producers.sort(), ["o/r#1", "o/r#2"]);
   assertEquals(dep.probes.length, 2); // one probe per producer — must satisfy both to fan out
   assert(dep.probeTimeout.startsWith("PT") || dep.probeTimeout.startsWith("P"), "an ISO-8601 bound");
+  assert(dep.probePollEvery.startsWith("PT") || dep.probePollEvery.startsWith("P"), "an ISO-8601 cadence");
 });
 
 // ── lowerAdmittedSet ────────────────────────────────────────────────────────────────────────────
@@ -160,6 +161,7 @@ test("lowerAdmittedSet starts roots with no probe and dependents with their seed
   const depProbes = byKey.get("o/r#2")?.["readinessProbes"] as unknown[] | null;
   assert(Array.isArray(depProbes) && depProbes.length === 1, "dependent seeded with one capability probe");
   assert(byKey.get("o/r#2")?.["probeTimeout"] != null, "dependent seeded with a bounded timeout");
+  assert(byKey.get("o/r#2")?.["probePollEvery"] != null, "dependent seeded with a poll cadence");
 
   // Durable edge materialized (after the plans rows exist), and a plans row per epic.
   assertEquals((tables.get("plan_deps") ?? []).length, 1);

package/app/planLowering.ts

@@ -35,7 +35,7 @@ import {
   recordPlanDep,
   startPlan,
 } from "./plan.ts";
-import { type ReadinessProbe, readinessTimeout } from "./readiness.ts";
+import { type ReadinessProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
 
 /** Derive the `capability` readiness probe for ONE inbound inter-epic edge: it goes green when the
  * producer epic (`depends_on_plan_key`) has published a release of `package` whose provenance carries
@@ -64,6 +64,7 @@ export interface DependentGate {
   probes: ReadinessProbe[];
   producers: string[];
   probeTimeout: string;
+  probePollEvery: string;
 }
 
 /** The pure schedule derived from a validated set: the ROOTS to start immediately and the
@@ -104,7 +105,10 @@ export function deriveEpicSchedule(
     const probeTimeout = probes
       .map((p) => readinessTimeout(p, env))
       .reduce((a, b) => (isoLonger(a, b) ? a : b));
-    dependents.push({ planKey, probes, producers: edgesForKey.map((e) => e.depends_on_plan_key), probeTimeout });
+    const probePollEvery = probes
+      .map((p) => readinessPollEvery(p, env))
+      .reduce((a, b) => (isoLonger(a, b) ? b : a));
+    dependents.push({ planKey, probes, producers: edgesForKey.map((e) => e.depends_on_plan_key), probeTimeout, probePollEvery });
   }
   return { roots, dependents };
 }
@@ -161,6 +165,7 @@ export async function lowerAdmittedSet(
     await startPlan(data, engine, parsed, staged.base_branch, {
       readinessProbes: gate?.probes,
       probeTimeout: gate?.probeTimeout,
+      probePollEvery: gate?.probePollEvery,
     });
   }
 

package/app/planWaveSummary.test.ts

@@ -126,10 +126,12 @@ test("epic-detail projects the wave banner, the per-wave summary, and task→rep
   const page = JSON.parse(readFileSync(PAGE, "utf8"));
   const byId = (id: string) => page.nodes.find((n: { id: string }) => n.id === id);
 
-  // 1. The epic-level wave banner: a prose node reading wave_label + epic_phase off `plans`.
+  // 1. The epic-level wave banner: a prose node reading wave_label + epic_phase off the derived
+  //    `plan_read_model` VIEW (epic #412 — retiring the worker-maintained plans.wave_label column;
+  //    the banner now reads the single-source-of-truth view instead of the raw `plans` table).
   const banner = byId("wave-banner");
   assert(banner, "epic detail must show the epic-level wave banner");
-  assertEquals(banner.props.data.table, "plans");
+  assertEquals(banner.props.data.table, "plan_read_model");
   assert(
     banner.props.data.filter.some((f: { field: string; eqParam?: boolean }) => f.field === "plan_key" && f.eqParam),
     "the banner is scoped to this epic",

package/app/plansReadModel.test.ts

@@ -0,0 +1,262 @@
+// Read-model VIEW coverage for the plans-table wave (022) and delivery (029) projections (epic #412
+// — "Retire worker-maintained denormalized projections in favour of SQL VIEWs").
+//
+// Historically `plans.wave_count`/`current_wave`/`wave_label` (022_plan_wave_progress.sql) were
+// written by the wave workers, and `plans.delivery`/`delivery_label` (029_plan_delivery.sql) by
+// `pollDelivery` (app/service.ts) via the pure `deriveDelivery` (app/delivery.ts) — both denormalised
+// onto `plans` only because "Urban's datasource cannot read a SQL VIEW". That constraint is gone
+// (nano-ide#424), so 060/061 express the SAME projections as DERIVED views. This asserts the views
+// reproduce the previous projections' EXACT values — including the pre-formatted `wave_label` /
+// `delivery_label` display strings — over sample `plans` × `plan_tasks` × `pull_requests` rows, so
+// the wave-1 cleanup can drop the worker write-paths + columns with no behavioural change.
+//
+// The delivery assertions cross-check against the real `deriveDelivery` (the single source of truth
+// the poller used), not a re-implementation; the wave assertions pin the frontier derivation that
+// reproduces the workers' `current_wave` (record-plan starts at 0, advances per landed wave, pins to
+// wave_count-1 on completion).
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import { deriveDelivery } from "./delivery.ts";
+
+const MIG = (name: string) => readFileSync(fileURLToPath(new URL(`../db/migrations/${name}`, import.meta.url)), "utf8");
+const PAGE = (name: string) => JSON.parse(readFileSync(fileURLToPath(new URL(`../pages/${name}`, import.meta.url)), "utf8"));
+
+// A DB with the base `plans` / `plan_tasks` / `pull_requests` shapes the views read (the `plans`
+// columns `plan_read_model` projects, and the full `plan_tasks` shape 059's `plan_wave_tasks`
+// reads), plus 059→061 applied in order.
+function viewDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec(
+    `CREATE TABLE plans (
+       plan_key TEXT PRIMARY KEY, repo TEXT, issue_number INTEGER, issue_url TEXT, title TEXT,
+       status TEXT, task_count INTEGER, process_key TEXT, outcome TEXT, created_at TEXT,
+       updated_at TEXT, epic_phase TEXT, base_branch TEXT, wait_gate_label TEXT, bound_artifacts TEXT,
+       promotion_pr TEXT, promotion_state TEXT, list_bucket TEXT, ack_open INTEGER);
+     CREATE TABLE plan_tasks (
+       id INTEGER PRIMARY KEY, plan_key TEXT, task_index INTEGER, task_id TEXT, title TEXT,
+       prompt TEXT, status TEXT, pr_key TEXT, summary TEXT, created_at TEXT, updated_at TEXT,
+       wave INTEGER, open_question TEXT, answer TEXT, draft_pr_key TEXT, corr_key TEXT);
+     CREATE TABLE pull_requests (pr_key TEXT PRIMARY KEY, url TEXT, status TEXT, process_key TEXT);`,
+  );
+  db.exec(MIG("059_plan_wave_summary.sql"));
+  db.exec(MIG("060_plan_wave_rollup.sql"));
+  db.exec(MIG("061_plan_delivery_rollup.sql"));
+  return db;
+}
+
+interface SampleTask {
+  status: string;
+  wave: number | null;
+  pr?: { status: string };
+  // A slice that OPENED a PR (so `pr_key` is set and it counts toward `prs_opened`) but whose
+  // `pull_requests` row is ABSENT — a DB desync. Mirrors `pollDelivery`'s `MISSING_PR_STATUS`
+  // sentinel: the LEFT JOIN yields `status IS NULL`, which `plan_delivery_counts` treats as
+  // in-flight (non-terminal), so it can never wrongly promote an epic to `landed`.
+  danglingPr?: boolean;
+}
+
+// Sentinel mirroring `pollDelivery`'s `MISSING_PR_STATUS` — the status fed to `deriveDelivery` for a
+// `pr_key` with no `pull_requests` row. Any non-terminal string works (it's counted as in-flight); it
+// exists only to keep the `deriveDelivery` cross-check aligned with the view's `status IS NULL` branch.
+const MISSING_PR_STATUS = "missing";
+
+// Insert a plan plus its tasks (and each task's PR, if any). PR keys are derived so the test rows
+// stay terse. Returns the flat `pull_requests.status` list `deriveDelivery` consumes (only tasks
+// that opened a PR), so the delivery assertions can cross-check the view against it.
+function addPlan(db: DatabaseSync, plan_key: string, status: string, tasks: SampleTask[]): string[] {
+  db.prepare(
+    "INSERT INTO plans (plan_key, repo, issue_number, issue_url, status, task_count, updated_at, list_bucket) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+  ).run(plan_key, "o/r", 1, `https://gh/${plan_key}`, status, tasks.length, "2026-01-01T00:00:00Z", "active");
+  const prStatuses: string[] = [];
+  tasks.forEach((t, i) => {
+    const prKey = t.pr || t.danglingPr ? `${plan_key}::pr${i}` : null;
+    db.prepare(
+      "INSERT INTO plan_tasks (plan_key, task_index, task_id, status, pr_key, wave) VALUES (?, ?, ?, ?, ?, ?)",
+    ).run(plan_key, i, `t${i}`, t.status, prKey, t.wave);
+    if (t.danglingPr) {
+      // Opened a PR (pr_key set → counts toward prs_opened) but NO `pull_requests` row: the DB desync
+      // `pollDelivery` feeds to `deriveDelivery` as MISSING_PR_STATUS (in-flight).
+      prStatuses.push(MISSING_PR_STATUS);
+    } else if (t.pr && prKey) {
+      db.prepare("INSERT INTO pull_requests (pr_key, url, status, process_key) VALUES (?, ?, ?, ?)").run(
+        prKey,
+        `https://gh/${prKey}`,
+        t.pr.status,
+        `P${i}`,
+      );
+      prStatuses.push(t.pr.status);
+    }
+  });
+  return prStatuses;
+}
+
+function delivery(db: DatabaseSync, plan_key: string): { delivery: unknown; delivery_label: unknown } {
+  return db.prepare("SELECT delivery, delivery_label FROM plan_delivery WHERE plan_key = ?").get(plan_key) as {
+    delivery: unknown;
+    delivery_label: unknown;
+  };
+}
+
+function counts(db: DatabaseSync, plan_key: string): { prs_opened: number; prs_merged: number; prs_in_flight: number } {
+  const r = db
+    .prepare("SELECT prs_opened, prs_merged, prs_in_flight FROM plan_delivery_counts WHERE plan_key = ?")
+    .get(plan_key) as { prs_opened: number; prs_merged: number; prs_in_flight: number };
+  return { ...r };
+}
+
+function waveLabel(db: DatabaseSync, plan_key: string): Record<string, unknown> | undefined {
+  const r = db.prepare("SELECT wave_count, current_wave, wave_label FROM plan_wave_label WHERE plan_key = ?").get(plan_key) as
+    | Record<string, unknown>
+    | undefined;
+  return r === undefined ? undefined : { ...r };
+}
+
+test("plan_delivery reproduces deriveDelivery exactly (converging / landed / not-done / resolved-not-landed / taskless)", () => {
+  const db = viewDb();
+  // A `done` epic with slices still in flight → converging.
+  const a = addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+    { status: "blocked", wave: 1 },
+  ]);
+  // A `done` epic with every slice PR merged → landed.
+  const b = addPlan(db, "o/r#2", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+  ]);
+  // A `dispatched` (not-done) epic → no positive delivery signal yet, even with an open PR.
+  const c = addPlan(db, "o/r#3", "dispatched", [
+    { status: "opened", wave: 0, pr: { status: "converging" } },
+    { status: "pending", wave: 1 },
+    { status: "pending", wave: 2 },
+  ]);
+  // A `done` epic where every PR is terminal but not all merged (one abandoned) → resolved, NOT landed.
+  const d = addPlan(db, "o/r#4", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "abandoned" } },
+  ]);
+  // A `planning` epic with no tasks → no PRs → null.
+  const e = addPlan(db, "o/r#5", "planning", []);
+
+  for (const [plan_key, status, prStatuses] of [
+    ["o/r#1", "done", a],
+    ["o/r#2", "done", b],
+    ["o/r#3", "dispatched", c],
+    ["o/r#4", "done", d],
+    ["o/r#5", "planning", e],
+  ] as const) {
+    const expected = deriveDelivery(status, prStatuses);
+    const row = delivery(db, plan_key);
+    assertEquals(row.delivery, expected.delivery, `${plan_key}: delivery`);
+    assertEquals(row.delivery_label, expected.label, `${plan_key}: delivery_label`);
+  }
+
+  // Pin the exact pre-formatted strings so a formatting drift can't hide behind the cross-check.
+  assertEquals(delivery(db, "o/r#1").delivery_label, "2/3 slices merged, 1 converging");
+  assertEquals(delivery(db, "o/r#2").delivery_label, "2/2 slices merged");
+  assertEquals(delivery(db, "o/r#4").delivery, null);
+});
+
+test("plan_delivery_counts pins the two subtle predicates: `converged` is terminal, a dangling pr_key is in-flight", () => {
+  const db = viewDb();
+  // `converged` is in TERMINAL_STATUSES (review-only mode): a `done` epic whose only remaining PR is
+  // `converged` (not `merged`) is resolved-not-landed. It must NOT count as in-flight — so delivery is
+  // NULL, never `converging`. This pins the hard-coded terminal set in the view's SQL against
+  // TERMINAL_STATUSES; drop `converged` from either and prs_in_flight becomes 1 here.
+  const conv = addPlan(db, "o/r#c", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "converged" } },
+  ]);
+  assertEquals(counts(db, "o/r#c"), { prs_opened: 2, prs_merged: 1, prs_in_flight: 0 });
+  assertEquals(delivery(db, "o/r#c").delivery, null, "converged is terminal-not-merged → resolved, not landed");
+  assertEquals({ ...delivery(db, "o/r#c") }, { delivery: deriveDelivery("done", conv).delivery, delivery_label: deriveDelivery("done", conv).label });
+
+  // A dangling `pr_key` (task opened a PR but the `pull_requests` row is absent — the poller's
+  // MISSING_PR_STATUS desync). The LEFT JOIN yields `status IS NULL`, which the view's
+  // `p.status IS NULL OR …` branch counts as in-flight — so even though every OTHER PR merged, the
+  // epic stays `converging` and can never be wrongly promoted to `landed`.
+  const dangling = addPlan(db, "o/r#d", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, danglingPr: true },
+  ]);
+  assertEquals(counts(db, "o/r#d"), { prs_opened: 2, prs_merged: 1, prs_in_flight: 1 });
+  assertEquals(delivery(db, "o/r#d").delivery, "converging", "a dangling pr_key keeps the epic in flight (never landed)");
+  assertEquals({ ...delivery(db, "o/r#d") }, {
+    delivery: deriveDelivery("done", dangling).delivery,
+    delivery_label: deriveDelivery("done", dangling).label,
+  });
+});
+
+test("plan_wave_label reproduces the workers' wave_count / current_wave / wave_label projection", () => {
+  const db = viewDb();
+  // Wave 0 fully merged, wave 1 still converging → frontier is wave 1 (the gating wave). "2/2".
+  addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+    { status: "blocked", wave: 1 },
+  ]);
+  // Single wave, all merged → frontier pins to the last index (0). "1/1".
+  addPlan(db, "o/r#2", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+  ]);
+  // Three waves, freshly dispatched (all in flight) → frontier is wave 0. "1/3".
+  addPlan(db, "o/r#3", "dispatched", [
+    { status: "opened", wave: 0, pr: { status: "converging" } },
+    { status: "pending", wave: 1 },
+    { status: "pending", wave: 2 },
+  ]);
+  // No levelized tasks → no wave rollup row (matches the workers leaving a taskless plan NULL).
+  addPlan(db, "o/r#5", "planning", []);
+
+  assertEquals(waveLabel(db, "o/r#1"), { wave_count: 2, current_wave: 1, wave_label: "2/2" });
+  assertEquals(waveLabel(db, "o/r#2"), { wave_count: 1, current_wave: 0, wave_label: "1/1" });
+  assertEquals(waveLabel(db, "o/r#3"), { wave_count: 3, current_wave: 0, wave_label: "1/3" });
+  assertEquals(waveLabel(db, "o/r#5"), undefined);
+});
+
+test("plan_read_model joins the derived wave + delivery projections onto the plans row", () => {
+  const db = viewDb();
+  addPlan(db, "o/r#1", "done", [
+    { status: "opened", wave: 0, pr: { status: "merged" } },
+    { status: "opened", wave: 1, pr: { status: "converging" } },
+  ]);
+  addPlan(db, "o/r#5", "planning", []);
+
+  const row = db.prepare("SELECT * FROM plan_read_model WHERE plan_key = ?").get("o/r#1") as Record<string, unknown>;
+  assertEquals(row.plan_key, "o/r#1");
+  assertEquals(row.status, "done");
+  assertEquals(row.list_bucket, "active");
+  assertEquals(row.wave_label, "2/2");
+  assertEquals(row.wave_count, 2);
+  assertEquals(row.current_wave, 1);
+  assertEquals(row.delivery, "converging");
+  assertEquals(row.delivery_label, "1/2 slices merged, 1 converging");
+
+  // A taskless plan still appears (LEFT JOINs), with the derived columns NULL.
+  const empty = db.prepare("SELECT wave_label, delivery, delivery_label FROM plan_read_model WHERE plan_key = ?").get("o/r#5") as Record<string, unknown>;
+  assertEquals({ ...empty }, { wave_label: null, delivery: null, delivery_label: null });
+});
+
+test("the operator pages read the derived plan_read_model VIEW for the wave/delivery cells", () => {
+  // Overview epics grid — binds the view and still surfaces wave_label + delivery_label.
+  const overview = PAGE("overview.page.json");
+  const epics = (overview.nodes ?? []).find((n: { id: string }) => n.id === "overview-epics");
+  assert(epics, "overview must keep the Active Epics grid");
+  assertEquals(epics.props.data.table, "plan_read_model");
+  const epicCols: string[] = epics.props.columns.map((c: { field: string }) => c.field);
+  assert(epicCols.includes("wave_label") && epicCols.includes("delivery_label"), "overview epics grid surfaces wave_label + delivery_label");
+
+  // Epic-detail wave banner + plan grid both read the view.
+  const detail = PAGE("epic-detail.page.json");
+  const byId = (id: string) => (detail.nodes ?? []).find((n: { id: string }) => n.id === id);
+  assertEquals(byId("wave-banner").props.data.table, "plan_read_model");
+  assertEquals(byId("epic-plan").props.data.table, "plan_read_model");
+  assert(/\{\{\s*wave_label\s*\}\}/.test(byId("wave-banner").props.header), "the banner surfaces wave_label");
+  assertEquals(byId("wave-banner").props.body, "delivery_label", "the banner body is the delivery_label");
+});

package/app/readiness.test.ts

@@ -37,6 +37,7 @@ import {
   type ProbeExec,
   type PrObservation,
   prViewCommand,
+  readinessPollEvery,
   readinessTimeout,
   readinessTimeoutMs,
   redactString,
@@ -585,6 +586,14 @@ test("readinessTimeoutMs: the ms twin of readinessTimeout — same precedence, n
   );
 });
 
+
+test("readinessPollEvery: derives the engine retry cadence from descriptor/env/default with clamp", () => {
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x", poll: { everyMs: 1500 } }), {}), "PT2S");
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x" }), { NANO_READINESS_POLL_EVERY_MS: "2500" }), "PT3S");
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x", poll: { everyMs: MAX_EVERY_MS + 1 } }), {}), msToIsoDuration(MAX_EVERY_MS));
+  assertEquals(readinessPollEvery(parseProbe({ kind: "http", target: "x" }), { NANO_READINESS_POLL_EVERY_MS: "bad" }), msToIsoDuration(DEFAULT_EVERY_MS));
+});
+
 test("probeBudgetMs: prefers the seeded probeTimeout (the gate timer's bound), falling back to the env twin", () => {
   const probe = parseProbe({ kind: "http", target: "x" });
   // The seeded probeTimeout wins over the ambient env — binding worker and engine to ONE per-instance

package/app/readiness.ts

@@ -776,6 +776,31 @@ export function readinessTimeout(
   return isoDuration(readEnvOr("NANO_READINESS_POLL_TIMEOUT", DEFAULT_READINESS_TIMEOUT, env), DEFAULT_READINESS_TIMEOUT);
 }
 
+/** The poll cadence (an ISO-8601 duration) seeded onto a readiness-gate instance as `probePollEvery`:
+ * the descriptor's `poll.everyMs` when present, else `NANO_READINESS_POLL_EVERY_MS`, else the built-in
+ * {@link DEFAULT_EVERY_MS}, clamped to {@link MAX_EVERY_MS}. Since Option A (#428), the engine — not the
+ * worker — owns the retry cadence: the `wait-poll` timers in `readiness-gate.bpmn` (and the preflight
+ * loops in `feature.bpmn`/`plan-fanout.bpmn`) read `=probePollEvery`, re-activating the now single-shot
+ * `pr.readiness-probe` once per interval. Derived here so whoever seeds a gate derives the cadence from
+ * ONE place (mirroring {@link readinessTimeout} for the bound), and worker/engine can never drift.
+ * `msToIsoDuration` rounds up (via `Math.ceil`) to a whole second, with a one-second minimum, so the
+ * timer never rounds to an immediately-refiring zero-length duration (which would reintroduce a
+ * busy-spin — the very defect Option A removes). */
+export function readinessPollEvery(
+  probe: ReadinessProbe,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const declared = probe.poll?.everyMs;
+  const ms =
+    typeof declared === "number" && declared >= 1
+      ? Math.min(Math.trunc(declared), MAX_EVERY_MS)
+      : (() => {
+          const envEvery = Number(readEnvOr("NANO_READINESS_POLL_EVERY_MS", String(DEFAULT_EVERY_MS), env));
+          return Number.isFinite(envEvery) && envEvery >= 1 ? Math.min(Math.trunc(envEvery), MAX_EVERY_MS) : DEFAULT_EVERY_MS;
+        })();
+  return msToIsoDuration(ms);
+}
+
 /** The effective gate budget in **milliseconds** — the ms twin of {@link readinessTimeout}, resolved
  * by the SAME precedence (descriptor `poll.timeoutMs`, else `NANO_READINESS_POLL_TIMEOUT`, else the
  * built-in default) and sharing its env key + default. The worker's local poll budget MUST use this