@nanobpm/nano-workforce 0.95.0 → 0.96.0

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 { backfillFeatureStages, 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, featureEscalations, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
   coalesceTitle,
@@ -33,12 +33,20 @@ import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
-import { backfillPlanBuckets, planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
+import {
+  backfillPlanBuckets,
+  inboundPlanDeps,
+  planReviews,
+  plans,
+  planTaskDeps,
+  planTasks,
+} from "./plan.ts";
 import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
 import {
   buildUserTaskRow,
+  latestFeatureEscalationQuestion,
   latestOpenEscalationQuestion,
   latestPlanReviewFindings,
   latestTrialMergeQuestion,
@@ -51,6 +59,7 @@ import {
   type UserTaskRow,
   userTasks,
 } from "./userTasks.ts";
+import { deriveWaitGate } from "./waitGate.ts";
 import { waveMergeTargets } from "./waves.ts";
 
 /** The BPMN process that drives review convergence (`resources/processes/convergence-loop.bpmn`). */
@@ -1350,6 +1359,40 @@ export async function pollDelivery(data: DataLayer) {
   }
 }
 
+/** Idempotent read-model pass (issue #292 slice S4): project each DEPENDENT epic's inter-epic gate
+ * state onto its `plans` row so the epic index/detail views can show — as flat columns — which
+ * producer/package a parked dependent is blocked on, its poll cadence + escalation deadline, and the
+ * bound `pkg@version` once green. Mirrors `pollDelivery`: joins each plan against its inbound
+ * `plan_deps` edges (the S1 read API) and stamps the pure `deriveWaitGate` (app/waitGate.ts) result,
+ * writing only when the projection actually changes so a steady-state pass is a no-op. Read-only over
+ * the state S1–S3 produce — it NEVER touches admission, scheduling, or `plan.status`.
+ *
+ * A ROOT epic (no inbound edge) derives `{ null, null }` — no wait-gate; any stale projection left by
+ * a prior edge (e.g. an edge later removed) is cleared defensively so the read model never keeps a
+ * phantom gate. */
+export async function pollWaitGate(data: DataLayer) {
+  for (const plan of await plans(data).all()) {
+    try {
+      const edges = await inboundPlanDeps(data, plan.plan_key);
+      const { wait_gate, wait_gate_label } = deriveWaitGate(edges, {
+        status: plan.status,
+        current_wave: plan.current_wave,
+        bound_artifacts: plan.bound_artifacts,
+        created_at: plan.created_at,
+      });
+      if (plan.wait_gate !== wait_gate || plan.wait_gate_label !== wait_gate_label) {
+        await plans(data).update(plan.plan_key, {
+          wait_gate,
+          wait_gate_label,
+          updated_at: now(),
+        });
+      }
+    } catch (err) {
+      console.error(`[poller] wait-gate ${plan.plan_key}: ${err}`);
+    }
+  }
+}
+
 /** Idempotent promotion pass (issue #299): open — and then track — the `epic/* → <default>`
  * promotion PR for every epic that has LANDED on a custom integration branch. This is the missing
  * counterpart to `ensureBaseBranch`: that creates the `epic/*` branch slices merge into; this
@@ -1619,6 +1662,13 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
       if (featureSeen.has(run.feature_key)) continue;
       featureSeen.add(run.feature_key);
       if (run.escalation_user_task_key) {
+        // Source the question from the canonical append-only `feature_escalations` audit log (issue
+        // #305) — the surviving table `record-feature-escalation` writes — falling back to the legacy
+        // denormalised `feature_runs.escalation_question` while both coexist (expand phase). This is the
+        // feature analogue of the plan-review/trial-merge/PR-loop question enrichment below, and lets the
+        // denormalised column be dropped in the contract phase without the Tasks grid losing the text.
+        const question = latestFeatureEscalationQuestion(await featureEscalations(data).find({ feature_key: run.feature_key })) ??
+          run.escalation_question;
         push(
           buildUserTaskRow(
             {
@@ -1628,7 +1678,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
               subjectKey: run.feature_key,
               subjectTitle: run.title,
               subjectUrl: run.issue_url,
-              question: run.escalation_question,
+              question,
               processKey: run.process_key,
             },
             at,
@@ -1804,6 +1854,7 @@ export async function pollOnce(
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollDelivery(data);
+  await pollWaitGate(data);
   await pollPromotion(data, engine, token);
   await pollFeatureDelivery(data);
   await pollLineage(data);

package/app/userTasks.test.ts

@@ -11,6 +11,7 @@ import {
   buildUserTaskRow,
   PLAN_REVIEW_ELEMENT,
   PR_WAIT_ANSWER_ELEMENT,
+  latestFeatureEscalationQuestion,
   latestOpenEscalationQuestion,
   latestPlanReviewFindings,
   latestTrialMergeQuestion,
@@ -230,3 +231,16 @@ test("latestOpenEscalationQuestion: null when there is no open escalation", () =
   assertEquals(latestOpenEscalationQuestion([esc({ id: 1, status: "answered" })]), null);
   assertEquals(latestOpenEscalationQuestion([]), null);
 });
+
+test("latestFeatureEscalationQuestion: picks the newest audit row (highest id), not a positional [0]", () => {
+  const rows = [
+    { id: 3, feature_key: "o/r#1", question: "stale", created_at: "t0", job_key: "j0" },
+    { id: 8, feature_key: "o/r#1", question: "newest", created_at: "t1", job_key: "j1" },
+    { id: 5, feature_key: "o/r#1", question: "middle", created_at: "t2", job_key: "j2" },
+  ];
+  assertEquals(latestFeatureEscalationQuestion(rows), "newest");
+});
+
+test("latestFeatureEscalationQuestion: null when the feature has no recorded escalation", () => {
+  assertEquals(latestFeatureEscalationQuestion([]), null);
+});

package/app/userTasks.ts

@@ -18,7 +18,7 @@
 // tasks visible; a completed task's row is removed on the next pass when the engine no longer reports
 // it open.
 import type { DataLayer } from "@nanobpm/urban";
-import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT } from "./feature.ts";
+import { FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, type FeatureEscalationRow } from "./feature.ts";
 import type { PlanReview } from "./plan.ts";
 import type { TrialMergeAuditRow } from "./trialMerge.ts";
 
@@ -233,3 +233,17 @@ export function latestOpenEscalationQuestion(rows: readonly PrEscalationRow[]):
   }
   return latest?.question ?? null;
 }
+
+/** Pure: the question for the still-open `feature-escalation`, sourced from the append-only
+ *  `feature_escalations` audit log (migration 048) — the feature analogue of `latestOpenEscalationQuestion`.
+ *  `record-feature-escalation` appends one row per escalation entry, so the newest row (highest `id`) is
+ *  the live question the operator is being asked; a run that escalated, was answered, then re-escalated
+ *  with a fresh question is covered because the later entry has the higher `id`. `null` when the feature
+ *  has no recorded escalation (the poller then falls back to the legacy `feature_runs` column). */
+export function latestFeatureEscalationQuestion(rows: readonly FeatureEscalationRow[]): string | null {
+  let latest: FeatureEscalationRow | undefined;
+  for (const r of rows) {
+    if (!latest || r.id > latest.id) latest = r;
+  }
+  return latest?.question ?? null;
+}

package/app/waitGate.test.ts

@@ -0,0 +1,176 @@
+// Adversarial unit coverage for the inter-epic gate projection (issue #292, slice S4) — the pure
+// `deriveWaitGate` that turns a dependent's inbound `plan_deps` edges + its own lifecycle into the
+// operator-visible `wait_gate` / `wait_gate_label` columns. No data/engine/network: pure derivation,
+// exactly like app/delivery.test.ts.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { PlanDep } from "./plan.ts";
+import {
+  deriveWaitGate,
+  humanizeMs,
+  parseBoundArtifacts,
+  type WaitGateLifecycle,
+} from "./waitGate.ts";
+
+const T0 = "2026-01-01T00:00:00.000Z";
+const T0_MS = Date.parse(T0);
+
+const edge = (
+  consumer: string,
+  producer: string,
+  pkg = "@scope/pkg",
+  capRef = producer,
+): PlanDep => ({
+  plan_key: consumer,
+  depends_on_plan_key: producer,
+  package: pkg,
+  capability_ref: capRef,
+  created_at: T0,
+});
+
+const plan = (over: Partial<WaitGateLifecycle> = {}): WaitGateLifecycle => ({
+  status: "planning",
+  current_wave: null,
+  bound_artifacts: null,
+  created_at: T0,
+  ...over,
+});
+
+// ── root ───────────────────────────────────────────────────────────────────────────────────────
+test("a root epic (no inbound edge) has NO wait-gate", () => {
+  const got = deriveWaitGate([], plan(), { nowMs: T0_MS });
+  assertEquals(got, { wait_gate: null, wait_gate_label: null });
+});
+
+// ── waiting (parked at the preflight) ────────────────────────────────────────────────────────────
+test("a parked dependent is 'waiting' and names exactly which producer/package it is blocked on", () => {
+  const got = deriveWaitGate([edge("o/r#2", "o/r#1", "@scope/api")], plan(), {
+    nowMs: T0_MS + 1000,
+  });
+  assertEquals(got.wait_gate, "waiting");
+  assert(got.wait_gate_label!.includes("o/r#1 @ @scope/api"), "names the producer#N @ package");
+  assert(got.wait_gate_label!.includes("re-checks every"), "shows the poll cadence");
+  assert(got.wait_gate_label!.includes("escalates by"), "shows the escalation deadline");
+});
+
+test("a fan-in dependent waits on ALL its producers, capping the visible list", () => {
+  const edges = [
+    edge("o/r#9", "o/r#1", "@p/one"),
+    edge("o/r#9", "o/r#2", "@p/two"),
+    edge("o/r#9", "o/r#3", "@p/three"),
+    edge("o/r#9", "o/r#4", "@p/four"),
+  ];
+  const got = deriveWaitGate(edges, plan(), { nowMs: T0_MS + 1000 });
+  assertEquals(got.wait_gate, "waiting");
+  assert(got.wait_gate_label!.includes("o/r#1 @ @p/one"), "shows the first producer");
+  assert(got.wait_gate_label!.includes("+1 more"), "caps the fan-in list");
+});
+
+// ── ready (preflight went green) ─────────────────────────────────────────────────────────────────
+test("a dependent that has fanned out (current_wave set) is 'ready'", () => {
+  const got = deriveWaitGate([edge("o/r#2", "o/r#1")], plan({ current_wave: 0 }), {
+    nowMs: T0_MS + 1000,
+  });
+  assertEquals(got.wait_gate, "ready");
+});
+
+test("a satisfied dependent shows its BOUND version, not merely 'ready'", () => {
+  const got = deriveWaitGate(
+    [edge("o/r#2", "o/r#1")],
+    plan({ current_wave: 1, bound_artifacts: JSON.stringify(["@scope/api@1.4.0"]) }),
+    { nowMs: T0_MS + 1000 },
+  );
+  assertEquals(got.wait_gate, "ready");
+  assert(got.wait_gate_label!.includes("@scope/api@1.4.0"), "surfaces the exact bound pkg@version");
+});
+
+test("a dispatched/done dependent with no captured version still reads 'ready' (green, gate passed)", () => {
+  for (const status of ["dispatched", "done"]) {
+    const got = deriveWaitGate([edge("o/r#2", "o/r#1")], plan({ status }), { nowMs: T0_MS + 1000 });
+    assertEquals(got.wait_gate, "ready", `status=${status}`);
+  }
+});
+
+test("a bound version wins even before a wave is stamped (green the instant the preflight resolves)", () => {
+  const got = deriveWaitGate(
+    [edge("o/r#2", "o/r#1")],
+    plan({ bound_artifacts: JSON.stringify(["@scope/api@2.0.0"]) }),
+    { nowMs: T0_MS + 1000 },
+  );
+  assertEquals(got.wait_gate, "ready");
+});
+
+// ── escalated (bounded timeout / terminal failure) ───────────────────────────────────────────────
+test("a still-gated dependent past its bounded timeout is 'escalated', never a silent stall", () => {
+  const got = deriveWaitGate([edge("o/r#2", "o/r#1")], plan(), {
+    // Well past the default readiness timeout (30m) with no publish.
+    nowMs: T0_MS + 48 * 60 * 60 * 1000,
+  });
+  assertEquals(got.wait_gate, "escalated");
+  assert(got.wait_gate_label!.includes("escalated"), "labels the escalation");
+  assert(got.wait_gate_label!.includes("o/r#1 @ @scope/pkg"), "still names the blocking producer");
+});
+
+test("a terminal FAILED dependent that never went green surfaces as 'escalated'", () => {
+  for (const status of ["failed", "abandoned"]) {
+    const got = deriveWaitGate([edge("o/r#2", "o/r#1")], plan({ status }), { nowMs: T0_MS + 1000 });
+    assertEquals(got.wait_gate, "escalated", `status=${status}`);
+  }
+});
+
+test("a FAILED dependent that DID go green (bound) stays 'ready' — the gate resolved before the failure", () => {
+  const got = deriveWaitGate(
+    [edge("o/r#2", "o/r#1")],
+    plan({ status: "failed", bound_artifacts: JSON.stringify(["@scope/pkg@1.0.0"]) }),
+    { nowMs: T0_MS + 1000 },
+  );
+  assertEquals(got.wait_gate, "ready");
+});
+
+// ── defensive parsing / formatting ───────────────────────────────────────────────────────────────
+test("parseBoundArtifacts tolerates null/garbage/non-array/non-string, never throwing", () => {
+  assertEquals(parseBoundArtifacts(null), []);
+  assertEquals(parseBoundArtifacts(""), []);
+  assertEquals(parseBoundArtifacts("not json"), []);
+  assertEquals(parseBoundArtifacts('{"a":1}'), []);
+  assertEquals(parseBoundArtifacts('["@a/b@1.0.0", 3, "", null]'), ["@a/b@1.0.0"]);
+});
+
+test("a green dependent whose bound_artifacts is garbage still reads 'ready' (via the wave signal)", () => {
+  const got = deriveWaitGate(
+    [edge("o/r#2", "o/r#1")],
+    plan({ current_wave: 0, bound_artifacts: "garbage" }),
+    { nowMs: T0_MS + 1000 },
+  );
+  assertEquals(got.wait_gate, "ready");
+  assertEquals(got.wait_gate_label, "ready", "no phantom version from an unparseable value");
+});
+
+test("humanizeMs renders compact human spans", () => {
+  assertEquals(humanizeMs(30_000), "30s");
+  assertEquals(humanizeMs(90_000), "1m 30s");
+  assertEquals(humanizeMs(30 * 60 * 1000), "30m");
+  assertEquals(humanizeMs(0), "0s");
+});
+
+test("the waiting label reflects the exponential backoff cadence, not a flat interval", () => {
+  const got = deriveWaitGate([edge("o/r#2", "o/r#1", "@scope/api")], plan(), { nowMs: T0_MS + 1000 });
+  assertEquals(got.wait_gate, "waiting");
+  assert(
+    got.wait_gate_label!.includes("(exponential backoff)"),
+    "names the default exponential backoff so 'every N' can't imply a fixed cadence",
+  );
+});
+
+test("the waiting label is stable regardless of inbound edge order (no idempotent-poll churn)", () => {
+  const a = edge("o/r#9", "o/r#1", "@p/one");
+  const b = edge("o/r#9", "o/r#2", "@p/two");
+  const c = edge("o/r#9", "o/r#3", "@p/three");
+  const forward = deriveWaitGate([a, b, c], plan(), { nowMs: T0_MS + 1000 });
+  const shuffled = deriveWaitGate([c, a, b], plan(), { nowMs: T0_MS + 1000 });
+  assertEquals(shuffled.wait_gate_label, forward.wait_gate_label, "order-independent label");
+});
+
+test("parseBoundArtifacts drops whitespace-only entries, not just empty strings", () => {
+  assertEquals(parseBoundArtifacts('["@a/b@1.0.0", "   ", "\\t"]'), ["@a/b@1.0.0"]);
+});

package/app/waitGate.ts

@@ -0,0 +1,199 @@
+// app/waitGate.ts — operator visibility for the inter-epic gate (issue #292, slice S4).
+//
+// S1 landed the durable inter-epic edge (`plan_deps`): one row per "dependent epic B waits on
+// producer epic A's published {package, capabilityRef}". S3 lowers each dependent behind a LEADING
+// `capability` readiness PREFLIGHT (resources/processes/plan-fanout.bpmn): the dependent fans out NO
+// wave until every producer publishes the awaited `pkg@version`, and a never-publishing producer
+// ESCALATES (bounded) rather than wedging the set. Until S4, a parked dependent was a SILENT stall —
+// the epic views showed no wave, no delivery, no reason it hadn't started.
+//
+// This module is the pure derivation half of S4: given a dependent's inbound `plan_deps` edges plus
+// its own lifecycle signals, it projects the epic's GATE STATE — is it waiting on a producer, has it
+// gone green (bound to a concrete version), or has its bounded timeout elapsed (escalated)? — as the
+// two flat, display-only `plans` columns (`wait_gate` / `wait_gate_label`) the declarative epic
+// index/detail dataGrids read. `pollWaitGate` (app/service.ts) is the idempotent projection pass that
+// joins each plan against its edges and stamps the result; this file holds NO data/engine access so
+// it stays unit-testable, mirroring `deriveDelivery` (app/delivery.ts) / `deriveEpicPhase`
+// (app/epicPhase.ts). It NEVER changes admission or scheduling — read-only over the state S1–S3
+// produce.
+//
+// The gate's poll cadence and bounded timeout are NOT re-invented here: the probe is derived from the
+// edge by the SAME `capabilityProbeForEdge` (app/planLowering.ts) S3 lowers with, and its cadence /
+// budget come from the SAME `normalizePoll` / `readinessTimeoutMs` (app/readiness.ts) the worker and
+// gate timers use — so the projected "re-checks every N / escalates by T" can never drift from the
+// real gate.
+
+import type { PlanDep } from "./plan.ts";
+import { capabilityProbeForEdge } from "./planLowering.ts";
+import { normalizePoll, readinessTimeoutMs } from "./readiness.ts";
+
+/** The dependent epic's derived gate state. A ROOT epic (no inbound edge) has NO gate → `null`.
+ *   • waiting   — parked at the preflight, blocked on ≥1 producer's capability, timeout not yet spent.
+ *   • ready     — the preflight went green: the epic has fanned out, bound to a concrete version.
+ *   • escalated — the gate's bounded timeout elapsed with the capability still unpublished. */
+export type WaitGateState = "waiting" | "ready" | "escalated";
+
+/** The lifecycle signals `deriveWaitGate` reads off the dependent's own `plans` row to tell whether
+ * its preflight has already passed (green) or failed. All are the ordinary projections S1–S3 already
+ * maintain — this derivation only READS them. */
+export interface WaitGateLifecycle {
+  /** The plan lifecycle status (`planning` | `dispatched` | `done` | `failed` | `abandoned`). */
+  status: string;
+  /** The 0-based wave the fleet is implementing, stamped by `select-wave` once fan-out begins — so a
+   *  non-null value proves the leading preflight already went green. NULL while still gated. */
+  current_wave: number | null;
+  /** JSON array (`["@scope/pkg@1.4.0", …]`) of the versions the preflight bound, stamped by
+   *  `select-wave` from the `resolvedArtifacts` process variable. NULL until green / for roots. */
+  bound_artifacts: string | null;
+  /** When the dependent's plan instance was created — the reference point the bounded gate timeout is
+   *  measured from (the preflight is the epic's very first step). */
+  created_at: string;
+}
+
+/** The flat projection `pollWaitGate` stamps onto the `plans` row. Both NULL for a root epic. */
+export interface WaitGateProjection {
+  wait_gate: WaitGateState | null;
+  wait_gate_label: string | null;
+}
+
+export interface WaitGateOptions {
+  /** Injectable clock (ms epoch) for deterministic tests; defaults to `Date.now()`. */
+  nowMs?: number;
+  /** Injectable env for the readiness timeout/poll defaults (mirrors `readinessTimeoutMs`). */
+  env?: Record<string, string | undefined>;
+}
+
+/** Terminal plan states in which a dependent that never went green has effectively given up on its
+ * gate — surfaced as `escalated` so the operator sees a blocked epic, never a silent dead end. */
+const FAILED_STATES = new Set(["failed", "abandoned"]);
+
+/** Parse the stored `bound_artifacts` JSON into a clean list of `pkg@version` strings. Defensive: a
+ * malformed / non-array / non-string-element value degrades to an empty list rather than throwing, so
+ * a bad row can never break the whole projection pass. */
+export function parseBoundArtifacts(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((v): v is string => typeof v === "string" && v.trim().length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/** Human-readable duration for a millisecond span, e.g. `90000 → "1m 30s"`, `1800000 → "30m"`. Used
+ * only for the display label; keeps the projection readable without pulling in a date library. */
+export function humanizeMs(ms: number): string {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  const parts: string[] = [];
+  if (h > 0) parts.push(`${h}h`);
+  if (m > 0) parts.push(`${m}m`);
+  if (s > 0 || parts.length === 0) parts.push(`${s}s`);
+  return parts.join(" ");
+}
+
+/** Format one producer/package the dependent is blocked on: the producer plan key already carries its
+ * issue handle (`owner/repo#N`), so `owner/repo#12 @ @scope/pkg` reads as "waiting on #12 @ pkg". */
+function waitingOnTarget(edge: PlanDep): string {
+  return `${edge.depends_on_plan_key} @ ${edge.package}`;
+}
+
+/** Join the producers a dependent still waits on into a compact clause, capping the visible list so a
+ * fan-in of many producers stays a one-line label ("…, +3 more"). */
+function waitingOnClause(edges: readonly PlanDep[]): string {
+  const MAX = 3;
+  const shown = edges.slice(0, MAX).map(waitingOnTarget);
+  const rest = edges.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")}, +${rest} more` : shown.join(", ");
+}
+
+/**
+ * Derive a dependent epic's gate projection from its inbound inter-epic edges and its own lifecycle.
+ *
+ *   • No inbound edge → ROOT → `{ null, null }`: the epic shows no wait-gate and starts immediately.
+ *   • Green (the preflight passed — the epic fanned out (`current_wave` set) / dispatched, or already
+ *     carries `bound_artifacts`) → `ready`, labelled with the bound `pkg@version`s.
+ *   • Still gated and the bounded timeout has elapsed (`now ≥ created_at + gate timeout`), or the
+ *     epic reached a terminal FAILED state without going green → `escalated`.
+ *   • Otherwise → `waiting`, labelled with which producer/package it is blocked on plus the gate's
+ *     own poll cadence and escalation deadline, so a parked dependent is never a silent stall.
+ *
+ * Pure: the cadence/timeout come from the SAME readiness helpers the gate itself uses (derived off the
+ * edge via `capabilityProbeForEdge`), so the projection can never drift from the real schedule.
+ */
+export function deriveWaitGate(
+  edges: readonly PlanDep[],
+  plan: WaitGateLifecycle,
+  opts: WaitGateOptions = {},
+): WaitGateProjection {
+  // A root epic has no inbound edge — nothing to wait on, so no gate projection at all.
+  if (edges.length === 0) return { wait_gate: null, wait_gate_label: null };
+
+  const bound = parseBoundArtifacts(plan.bound_artifacts);
+  // The leading preflight is the epic's FIRST step, so ANY downstream progress proves it went green:
+  // `select-wave` stamped a wave, the fan-out dispatched, or a bound version was already captured.
+  const green = bound.length > 0 ||
+    plan.current_wave != null ||
+    plan.status === "dispatched" ||
+    plan.status === "done";
+
+  if (green) {
+    const detail = bound.length > 0 ? ` · bound ${bound.join(", ")}` : "";
+    return { wait_gate: "ready", wait_gate_label: `ready${detail}` };
+  }
+
+  // Not green. Order the edges deterministically before deriving anything display-facing: the poller
+  // re-runs this derivation every pass, and `plan_deps.find` gives no ordering guarantee, so an
+  // unstable order would rewrite the same label (and `updated_at`) pass after pass. Sort by producer
+  // then package so the clause, probe list and cadence are stable across passes.
+  const orderedEdges = [...edges].sort(
+    (a, b) =>
+      a.depends_on_plan_key.localeCompare(b.depends_on_plan_key) ||
+      a.package.localeCompare(b.package),
+  );
+  // Derive the gate's own bounded timeout from the edge (the same probe S3 lowers) so the projected
+  // deadline matches the engine timer. Every edge yields the same default budget; take the max
+  // defensively in case a future edge overrides it.
+  const env = opts.env;
+  const nowMs = opts.nowMs ?? Date.now();
+  const polls = orderedEdges.map(capabilityProbeForEdge).map((p) => ({
+    ...normalizePoll(p.poll),
+    timeoutMs: readinessTimeoutMs(p, env),
+  }));
+  const timeoutMs = Math.max(...polls.map((p) => p.timeoutMs));
+  const everyMs = Math.min(...polls.map((p) => p.everyMs));
+  // The probe cadence is not a fixed interval unless every probe uses `fixed` backoff — the default
+  // is exponential, so a flat "every N" would misrepresent the schedule. Reflect the real shape so the
+  // operator label can't claim a cadence the gate doesn't keep.
+  const exponential = polls.some((p) => p.backoff === "exponential");
+  const startMs = Date.parse(plan.created_at);
+  const deadlineMs = Number.isFinite(startMs) ? startMs + timeoutMs : NaN;
+
+  const clause = waitingOnClause(orderedEdges);
+
+  // A terminal FAILED epic that never went green, or one whose bounded timeout has elapsed, has
+  // effectively escalated — surface it so the operator sees a blocked epic rather than a silent stall.
+  const timedOut = Number.isFinite(deadlineMs) && nowMs >= deadlineMs;
+  if (timedOut || FAILED_STATES.has(plan.status)) {
+    return {
+      wait_gate: "escalated",
+      wait_gate_label: `escalated · still waiting on ${clause} after ${humanizeMs(timeoutMs)}`,
+    };
+  }
+
+  const deadline = Number.isFinite(deadlineMs)
+    ? ` · escalates by ${new Date(deadlineMs).toISOString()}`
+    : "";
+  // `re-checks every N` for a fixed cadence; for the default exponential ramp N is only the FIRST
+  // interval, so say so rather than implying a flat cadence the gate never keeps.
+  const cadence = exponential
+    ? `re-checks every ${humanizeMs(everyMs)}+ (exponential backoff)`
+    : `re-checks every ${humanizeMs(everyMs)}`;
+  return {
+    wait_gate: "waiting",
+    wait_gate_label: `waiting on ${clause} · ${cadence}${deadline}`,
+  };
+}