@nanobpm/nano-workforce 0.129.1 → 0.131.0

package/app/deliveryUnitStatus.test.ts

@@ -0,0 +1,143 @@
+// Coverage for ADR 0006 slice S1 — the ONE canonical delivery-unit status union and the per-shape
+// derivations that map each bespoke source union into it (app/deliveryUnitStatus.ts).
+//
+// Guards THREE things:
+//   1. TOTALITY — every member of each source union (feature / plan aggregate / plan-task node /
+//      delivery-graph run) maps to a valid canonical member, and the compiled `fnFor` agrees with the
+//      declared map object (so the DSL derivation and the TS map cannot drift).
+//   2. TERMINALITY PRECEDENCE — a source SETTLED/terminal status always maps to a canonical
+//      settled/terminal status, so a reconciler reading the union never mistakes a finished unit for a
+//      live one (or vice-versa).
+//   3. FRAMEWORK PARITY — for each of the four read models, `assertReadModelParity` proves the SQL VIEW
+//      lowering and the TS `fnFor` lowering agree over the full source-status matrix.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { assertReadModelParity, type ParityDb, type ParitySample } from "@nanobpm/urban";
+import { assert, assertEquals } from "#test-assert";
+import { DELIVERY_GRAPH_RUN_STATUSES, DELIVERY_GRAPH_TERMINAL_STATUSES } from "./deliveryGraphRun.ts";
+import {
+  DELIVERY_GRAPH_STATUS_TO_UNIT,
+  DELIVERY_STATUS_COLUMN,
+  DELIVERY_UNIT_SETTLED_STATUSES,
+  DELIVERY_UNIT_STATUSES,
+  DELIVERY_UNIT_TERMINAL_STATUSES,
+  type DeliveryUnitStatus,
+  deliveryGraphDeliveryStatus,
+  FEATURE_STATUS_TO_UNIT,
+  featureDeliveryStatus,
+  isDeliveryUnitSettled,
+  isDeliveryUnitTerminal,
+  PLAN_STATUS_TO_UNIT,
+  PLAN_STATUSES,
+  PLAN_TASK_STATUS_TO_UNIT,
+  planDeliveryStatus,
+  planTaskDeliveryStatus,
+  toDeliveryUnitStatus,
+} from "./deliveryUnitStatus.ts";
+import { FEATURE_RUN_STATUSES, FEATURE_TERMINAL_STATUSES } from "./feature.ts";
+import { PLAN_TASK_STATUSES, PLAN_TERMINAL_STATUSES } from "./plan.ts";
+
+const CANONICAL = new Set<string>(DELIVERY_UNIT_STATUSES);
+
+// ── Type-level No-Drift guard (issue #464 review) ────────────────────────────────────────────────
+// `PLAN_STATUSES` is DERIVED from `EPIC_LIVE_STATUSES` (app/delivery.ts) + `PLAN_TERMINAL_STATUSES`
+// (app/plan.ts). If either source is declared as a widened `readonly string[]` instead of an `as const`
+// literal tuple, `(typeof PLAN_STATUSES)[number]` collapses to `string`, `PLAN_STATUS_TO_UNIT` degrades
+// to `Record<string, …>`, and the exhaustiveness guard silently evaporates — `tsc` would no longer fail
+// when the plan vocabulary gains a member without a canonical mapping. This assertion fails to COMPILE
+// if that widening ever returns (the `false` branch makes `true` unassignable).
+type _IsLiteralUnion<T extends string> = string extends T ? false : true;
+const _planStatusesAreLiteral: _IsLiteralUnion<(typeof PLAN_STATUSES)[number]> = true;
+void _planStatusesAreLiteral;
+
+// A `ParityDb` over node:sqlite's `DatabaseSync` for `assertReadModelParity` (which needs positional
+// exec/all/run, whereas `DatabaseSync` exposes query methods on prepared statements).
+function parityDb(db: DatabaseSync): ParityDb {
+  return {
+    exec: (sql) => db.exec(sql),
+    all: <T = Record<string, unknown>>(sql: string, params: unknown[] = []) =>
+      db.prepare(sql).all(...(params as never[])) as T[],
+    run: (sql, params: unknown[] = []) => {
+      const r = db.prepare(sql).run(...(params as never[]));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+  };
+}
+
+const shapes = [
+  { name: "feature", model: featureDeliveryStatus, sources: FEATURE_RUN_STATUSES, map: FEATURE_STATUS_TO_UNIT },
+  { name: "plan", model: planDeliveryStatus, sources: PLAN_STATUSES, map: PLAN_STATUS_TO_UNIT },
+  { name: "plan-task", model: planTaskDeliveryStatus, sources: PLAN_TASK_STATUSES, map: PLAN_TASK_STATUS_TO_UNIT },
+  { name: "delivery-graph", model: deliveryGraphDeliveryStatus, sources: DELIVERY_GRAPH_RUN_STATUSES, map: DELIVERY_GRAPH_STATUS_TO_UNIT },
+] as const;
+
+test("TOTALITY: every source status maps to a valid canonical member, and fnFor agrees with the declared map", () => {
+  for (const { name, model, sources, map } of shapes) {
+    for (const source of sources) {
+      const declared = (map as Record<string, DeliveryUnitStatus>)[source];
+      assert(declared !== undefined, `${name}: source status "${source}" has no canonical mapping`);
+      assert(CANONICAL.has(declared), `${name}: "${source}" maps to non-canonical "${declared}"`);
+      // The DSL-compiled TS lowering must produce the SAME canonical value as the declared map object.
+      assertEquals(toDeliveryUnitStatus(model, source), declared, `${name}: fnFor drift for "${source}"`);
+    }
+    // An out-of-band status is NULL (never an invented member), matching the VIEW's ELSE NULL.
+    assertEquals(toDeliveryUnitStatus(model, "not-a-real-status"), null, `${name}: unmapped status must be null`);
+    assertEquals(toDeliveryUnitStatus(model, null), null, `${name}: null status must be null`);
+  }
+});
+
+test("TERMINALITY PRECEDENCE: a source SETTLED/terminal status maps to a canonical settled/terminal status", () => {
+  // Feature counts opened/converging as SETTLED-for-redispatch (live PR stages), so check against the
+  // settled set; the plan aggregate and delivery-graph terminals are truly DONE, so check the done tier.
+  for (const s of FEATURE_TERMINAL_STATUSES) {
+    assert(isDeliveryUnitSettled(FEATURE_STATUS_TO_UNIT[s]), `feature terminal "${s}" must map to a settled canonical status`);
+  }
+  for (const s of PLAN_TERMINAL_STATUSES as readonly (keyof typeof PLAN_STATUS_TO_UNIT)[]) {
+    assert(isDeliveryUnitTerminal(PLAN_STATUS_TO_UNIT[s]), `plan terminal "${s}" must map to a done-tier canonical status`);
+  }
+  for (const s of DELIVERY_GRAPH_TERMINAL_STATUSES) {
+    assert(isDeliveryUnitTerminal(DELIVERY_GRAPH_STATUS_TO_UNIT[s]), `graph terminal "${s}" must map to a done-tier canonical status`);
+  }
+  // The non-terminal parked waits must NOT be classified terminal (a reconciler must keep polling them).
+  for (const nonTerminal of ["escalated", "awaiting_operator", "waiting", "running", "requested"] as DeliveryUnitStatus[]) {
+    assert(!isDeliveryUnitTerminal(nonTerminal), `"${nonTerminal}" must be non-terminal`);
+  }
+});
+
+test("NODE-VS-AGGREGATE decision (ADR 0006 §4): a plan-task node maps into the SAME union; its lane wait becomes the canonical `waiting`", () => {
+  assertEquals(PLAN_TASK_STATUS_TO_UNIT["waiting-for-lane"], "waiting", "the node lane/dependency wait is the canonical `waiting`");
+  assertEquals(PLAN_TASK_STATUS_TO_UNIT.pending, "requested", "a queued (not-yet-run) node is pre-dispatch `requested`");
+  // Every node status resolves to a member of the one canonical union — no separate node vocabulary.
+  for (const s of PLAN_TASK_STATUSES) {
+    assert(CANONICAL.has(PLAN_TASK_STATUS_TO_UNIT[s]), `node status "${s}" must be a canonical member`);
+  }
+});
+
+test("the settled set is exactly the terminal (done-tier) set plus the two live PR resting stages", () => {
+  assertEquals(
+    [...DELIVERY_UNIT_SETTLED_STATUSES].sort(),
+    [...DELIVERY_UNIT_TERMINAL_STATUSES, "opened", "converging"].sort(),
+    "settled = terminal ∪ {opened, converging}",
+  );
+  for (const t of DELIVERY_UNIT_TERMINAL_STATUSES) assert(isDeliveryUnitSettled(t), `terminal "${t}" is settled`);
+});
+
+test("no dead canonical members: every DELIVERY_UNIT_STATUSES value is reachable from at least one source mapping", () => {
+  const reached = new Set<string>();
+  for (const { map } of shapes) for (const v of Object.values(map)) reached.add(v as string);
+  for (const canonical of DELIVERY_UNIT_STATUSES) {
+    assert(reached.has(canonical), `canonical "${canonical}" is unreachable — a dead member or a missing mapping`);
+  }
+});
+
+test("FRAMEWORK PARITY: each per-shape delivery_status model's SQL and TS lowerings agree over the full source-status matrix", () => {
+  for (const { name, model, sources } of shapes) {
+    const samples: ParitySample[] = sources.map((status) => ({ baseRow: { status } }));
+    // Also exercise the ELSE NULL arm with an out-of-band value.
+    samples.push({ baseRow: { status: "out-of-band" } });
+    const db = new DatabaseSync(":memory:");
+    assertReadModelParity(model, parityDb(db), samples, { columns: [DELIVERY_STATUS_COLUMN] });
+    db.close();
+    assert(true, `${name} parity holds`);
+  }
+});

package/app/deliveryUnitStatus.ts

@@ -0,0 +1,242 @@
+// The ONE delivery-unit status union — ADR 0006 slice **S1** (status lifecycle).
+//
+// Background (ADR 0006, issue #464). nano-workforce models the same aggregate — a *scheduled unit of
+// work driven to a delivery outcome* — in three separate representations, each with its OWN bespoke
+// status union:
+//
+//   * feature   — `FEATURE_RUN_STATUSES` (11: running/escalated/opened/converging/awaiting_operator/
+//                 merged/converged/blocked/skipped/failed/abandoned) — app/feature.ts
+//   * epic      — the `plans` aggregate (`planning`/`dispatched`/`done`/`failed`/`abandoned`, the union
+//                 of `EPIC_LIVE_STATUSES` + `PLAN_TERMINAL_STATUSES`, app/delivery.ts + app/plan.ts)
+//                 AND its `plan_tasks` NODE status `PLAN_TASK_STATUSES` (7) — app/plan.ts
+//   * graph     — `DELIVERY_GRAPH_RUN_STATUSES` (5: awaiting-approval/running/done/failed/abandoned)
+//                 — app/deliveryGraphRun.ts
+//
+// A change to "what states a unit of work can be in" therefore has to be made, by hand, in three (four,
+// counting the epic's two levels) places that can silently drift — exactly the "No drift surfaces /
+// derivation over duplication" hazard this repo treats as a defect class (AGENTS.md).
+//
+// This module is S1's deliverable: it defines the SINGLE canonical aggregate union
+// ({@link DELIVERY_UNIT_STATUSES}) and, via ADR-0065's `defineReadModel`, the per-shape derivations that
+// map each bespoke union INTO it — declared ONCE and compiled to BOTH the SQLite VIEW select-list
+// (`sqlSelectFor`, for S2's `delivery_units`-backed VIEWs) AND the runtime TS oracle (`fnFor`, for the
+// reconcilers). There is nothing to keep in lockstep: the two lowerings fall out of the same closed-DSL
+// AST, and `assertReadModelParity` (app/deliveryUnitStatus.test.ts) proves they agree.
+//
+// SCOPE (S1). This slice OWNS the canonical vocabulary, the per-shape mapping, the terminal/settled
+// precedence, and the node-vs-aggregate decision (below). It does NOT repoint any existing VIEW or move
+// any writer/`instanceTracking` binding onto the new union — the legacy tables stay the physical write
+// target through S2, and the `instanceTracking` bindings + `senior:*` doors collapse in S3 (ADR 0006
+// rollout). The derivations here are the single source those later slices reference, not a second
+// projection alongside them.
+
+import { caseWhen, col, defineReadModel, type Expr, eq, lit, type ReadModel, when } from "@nanobpm/urban";
+import { EPIC_LIVE_STATUSES } from "./delivery.ts";
+import type { DeliveryGraphRunStatus } from "./deliveryGraphRun.ts";
+import type { FeatureRunStatus } from "./feature.ts";
+import { PLAN_TERMINAL_STATUSES, type PlanTaskStatus } from "./plan.ts";
+
+/**
+ * The ONE canonical delivery-unit status union — the single source of truth for "what state a unit of
+ * work is in", replacing the three bespoke unions. A superset that preserves every source union's
+ * distinctions without loss (feature is the reference shape, so its members pass through by name):
+ *
+ *  - `requested`         — created, not yet dispatched to an executor (no live engine instance yet).
+ *  - `running`           — an executor (agent/probe/connector) is actively working the unit.
+ *  - `escalated`         — NON-terminal: parked awaiting a HUMAN answer (an open escalation user task).
+ *  - `awaiting_operator` — NON-terminal: parked awaiting an OPERATOR acknowledgement (blocked wait).
+ *  - `waiting`           — NON-terminal: parked on a lane / dependency gate (a wave barrier).
+ *  - `opened`            — a PR was raised and the unit rests here (convergence was not requested).
+ *  - `converging`        — the opened PR is in its review-convergence loop.
+ *  - `converged`         — TERMINAL: review converged but the PR did not merge (auto-merge off).
+ *  - `merged`            — TERMINAL: the PR landed (the win).
+ *  - `done`              — TERMINAL: an aggregate settled successfully WITHOUT a single-PR terminal
+ *                          (an epic/graph whose members all landed) — the PR-less success outcome.
+ *  - `skipped`           — TERMINAL: nothing to do.
+ *  - `blocked`           — TERMINAL: could not proceed / gave up (distinct from the non-terminal
+ *                          `awaiting_operator` wait — a `blocked` unit is settled, not parked).
+ *  - `failed`            — TERMINAL: an unexpected failure.
+ *  - `abandoned`         — TERMINAL: the PR was abandoned, or the process instance was cancelled.
+ */
+export const DELIVERY_UNIT_STATUSES = [
+  "requested",
+  "running",
+  "escalated",
+  "awaiting_operator",
+  "waiting",
+  "opened",
+  "converging",
+  "converged",
+  "merged",
+  "done",
+  "skipped",
+  "blocked",
+  "failed",
+  "abandoned",
+] as const;
+export type DeliveryUnitStatus = (typeof DELIVERY_UNIT_STATUSES)[number];
+
+/**
+ * The TRULY-terminal ("done tier") statuses — a unit in one of these has settled to a final outcome and
+ * will not advance again. Mirrors the union of the source terminal sets (`FEATURE_TERMINAL_STATUSES`
+ * minus its live PR stages, `PLAN_TERMINAL_STATUSES`, `DELIVERY_GRAPH_TERMINAL_STATUSES`). Distinct from
+ * {@link DELIVERY_UNIT_SETTLED_STATUSES}: `opened`/`converging` are settled FOR RE-DISPATCH but are LIVE
+ * pipeline stages, not `done`.
+ */
+export const DELIVERY_UNIT_TERMINAL_STATUSES: readonly DeliveryUnitStatus[] = [
+  "converged",
+  "merged",
+  "done",
+  "skipped",
+  "blocked",
+  "failed",
+  "abandoned",
+];
+
+/**
+ * The SETTLED-FOR-RE-DISPATCH statuses — {@link DELIVERY_UNIT_TERMINAL_STATUSES} plus the two live PR
+ * resting stages (`opened`/`converging`) a unit stops at without a further wave restart. Mirrors
+ * `FEATURE_TERMINAL_STATUSES` (app/feature.ts), which likewise counts `opened`/`converging` as terminal
+ * for re-dispatch gating even though they are LIVE (not `done`). A re-dispatch of the same unit
+ * short-circuits IFF its prior run is in one of these; the NON-terminal parked waits
+ * (`escalated`/`awaiting_operator`/`waiting`) and `running`/`requested` are excluded, so a live or
+ * parked unit is never orphaned by a parallel restart.
+ */
+export const DELIVERY_UNIT_SETTLED_STATUSES: readonly DeliveryUnitStatus[] = [
+  ...DELIVERY_UNIT_TERMINAL_STATUSES,
+  "opened",
+  "converging",
+];
+
+/** True iff `status` is a truly-terminal ("done tier") delivery-unit status. */
+export const isDeliveryUnitTerminal = (status: DeliveryUnitStatus): boolean =>
+  DELIVERY_UNIT_TERMINAL_STATUSES.includes(status);
+
+/** True iff `status` is settled for RE-DISPATCH (terminal, or a live PR resting stage). */
+export const isDeliveryUnitSettled = (status: DeliveryUnitStatus): boolean =>
+  DELIVERY_UNIT_SETTLED_STATUSES.includes(status);
+
+/**
+ * The plan AGGREGATE lifecycle values — the union of the two existing sources (`EPIC_LIVE_STATUSES` +
+ * `PLAN_TERMINAL_STATUSES`), NOT re-listed here, so this stays a derived view of them and cannot drift.
+ */
+export const PLAN_STATUSES = [...EPIC_LIVE_STATUSES, ...PLAN_TERMINAL_STATUSES] as const;
+
+// ── Per-shape mappings — declared ONCE, keyed by the SOURCE union so `tsc` fails if a source union
+//    gains a member without a canonical mapping (the type-level No-Drift guard). ──────────────────────
+
+/**
+ * Feature is the REFERENCE shape: every `FEATURE_RUN_STATUSES` member has a same-named canonical member,
+ * so the map is the identity. The distinct feature waits survive intact — `escalated` (human),
+ * `awaiting_operator` (operator), and the terminal `blocked` (gave up) stay three different states.
+ */
+export const FEATURE_STATUS_TO_UNIT: Record<FeatureRunStatus, DeliveryUnitStatus> = {
+  running: "running",
+  escalated: "escalated",
+  opened: "opened",
+  converging: "converging",
+  awaiting_operator: "awaiting_operator",
+  merged: "merged",
+  converged: "converged",
+  blocked: "blocked",
+  skipped: "skipped",
+  failed: "failed",
+  abandoned: "abandoned",
+};
+
+/**
+ * Plan AGGREGATE → canonical. `planning` (decomposing, no fan-out yet) is pre-dispatch ⇒ `requested`;
+ * `dispatched` (fan-out running) ⇒ `running`; the three terminals pass through. Keyed by the plan
+ * aggregate value (a bare string in `Plan.status`), covering every {@link PLAN_STATUSES} member.
+ */
+export const PLAN_STATUS_TO_UNIT: Record<(typeof PLAN_STATUSES)[number], DeliveryUnitStatus> = {
+  planning: "requested",
+  dispatched: "running",
+  done: "done",
+  failed: "failed",
+  abandoned: "abandoned",
+};
+
+/**
+ * Plan-task NODE → canonical. **Node-vs-aggregate decision (ADR 0006 §4):** a node is a DEGENERATE
+ * delivery unit, so its status maps into the SAME canonical union rather than carrying a separate node
+ * contract — there is ONE vocabulary. The node-specific lane/dependency wait (`waiting-for-lane`) is
+ * expressed by the canonical `waiting` member (a state the aggregate level never enters); `pending`
+ * (queued, not yet run in its wave) is pre-dispatch ⇒ `requested`.
+ */
+export const PLAN_TASK_STATUS_TO_UNIT: Record<PlanTaskStatus, DeliveryUnitStatus> = {
+  pending: "requested",
+  opened: "opened",
+  blocked: "blocked",
+  skipped: "skipped",
+  escalated: "escalated",
+  "waiting-for-lane": "waiting",
+  abandoned: "abandoned",
+};
+
+/**
+ * Delivery-graph RUN → canonical. `awaiting-approval` (reserved, pre-dispatch: no live instance, parked
+ * before launch — issue #460) ⇒ `requested`; `running` passes through; the three terminals pass through.
+ */
+export const DELIVERY_GRAPH_STATUS_TO_UNIT: Record<DeliveryGraphRunStatus, DeliveryUnitStatus> = {
+  "awaiting-approval": "requested",
+  running: "running",
+  done: "done",
+  failed: "failed",
+  abandoned: "abandoned",
+};
+
+/**
+ * Build the canonical `delivery_status` derivation for one shape as a closed-DSL {@link Expr}: a
+ * `CASE` over the base row's `status` column, one `WHEN status = '<source>' THEN '<canonical>'` per map
+ * entry. The map is TOTAL over its source union, so the `ELSE` is unreachable in practice; it falls back
+ * to `null` (never an invented status) so an out-of-band source value surfaces as NULL rather than a
+ * silent mis-map. Both backends (`sqlSelectFor` VIEW body, `fnFor` runtime) fall out of this one AST.
+ */
+export const deliveryStatusExpr = (map: Readonly<Record<string, DeliveryUnitStatus>>): Expr =>
+  caseWhen(
+    Object.entries(map).map(([source, unit]) => when(eq(col("status"), lit(source)), lit(unit))),
+    lit(null),
+  );
+
+/** The single derived column every per-shape delivery-unit read model exposes. */
+export const DELIVERY_STATUS_COLUMN = "delivery_status";
+
+/** The base alias the managed VIEWs give each source table — pinned so emitted SQL is stable/testable. */
+export const DELIVERY_UNIT_STATUS_BASE_ALIAS = "du";
+
+const statusReadModel = (name: string, baseTable: string, map: Readonly<Record<string, DeliveryUnitStatus>>): ReadModel =>
+  defineReadModel({
+    name,
+    baseTable,
+    selectBaseColumns: false,
+    derive: { [DELIVERY_STATUS_COLUMN]: deliveryStatusExpr(map) },
+  });
+
+/**
+ * The four per-shape derivations of the ONE canonical union, each a `defineReadModel` exposing a single
+ * `delivery_status` column over its source table. S2 provisions these as VIEWs over `delivery_units`;
+ * the reconcilers consume `fnFor(DELIVERY_STATUS_COLUMN)`. They all target {@link DELIVERY_UNIT_STATUSES}
+ * — the union is single-sourced; only the per-shape MAPPING differs.
+ */
+export const featureDeliveryStatus: ReadModel = statusReadModel("feature_delivery_status", "feature_runs", FEATURE_STATUS_TO_UNIT);
+export const planDeliveryStatus: ReadModel = statusReadModel("plan_delivery_status", "plans", PLAN_STATUS_TO_UNIT);
+export const planTaskDeliveryStatus: ReadModel = statusReadModel("plan_task_delivery_status", "plan_tasks", PLAN_TASK_STATUS_TO_UNIT);
+export const deliveryGraphDeliveryStatus: ReadModel = statusReadModel("delivery_graph_delivery_status", "delivery_graph_runs", DELIVERY_GRAPH_STATUS_TO_UNIT);
+
+/** All four per-shape delivery-status read models, for bulk registration/validation by later slices. */
+export const DELIVERY_STATUS_READ_MODELS: readonly ReadModel[] = [
+  featureDeliveryStatus,
+  planDeliveryStatus,
+  planTaskDeliveryStatus,
+  deliveryGraphDeliveryStatus,
+];
+
+/**
+ * Map a source status to the canonical union in-process (the TS backend of {@link deliveryStatusExpr},
+ * via the compiled `fnFor`) — the reconciler-facing helper. Returns `null` for an unmapped value,
+ * matching the VIEW's `ELSE NULL`.
+ */
+export const toDeliveryUnitStatus = (model: ReadModel, status: string | null): DeliveryUnitStatus | null =>
+  // biome-ignore lint/plugin: runtime/framework contract boundary — `fnFor` returns `unknown`; the derived column yields one of its declared `lit(...)` canonical statuses (or null on the ELSE arm).
+  model.fnFor(DELIVERY_STATUS_COLUMN)({ status }) as DeliveryUnitStatus | null;

package/app/plan.ts

@@ -445,7 +445,7 @@ export const MAX_PLAN_REVIEW_ROUNDS = positiveIntEnv("NANO_PLAN_REVIEW_ROUNDS",
 
 /** A plan is "done" in exactly these states; everything else (planning, dispatched)
  * is in flight. The cancel guard and the active view key off this. */
-export const PLAN_TERMINAL_STATUSES: readonly string[] = ["done", "failed", "abandoned"];
+export const PLAN_TERMINAL_STATUSES = ["done", "failed", "abandoned"] as const;
 
 export interface ParsedIssue {
   repo: string;
@@ -591,7 +591,7 @@ export async function findActivePlansByBase(
   base: string,
 ): Promise<Plan[]> {
   const rows = await plans(data).find({ repo, base_branch: base });
-  return rows.filter((p) => !PLAN_TERMINAL_STATUSES.includes(p.status));
+  return rows.filter((p) => !PLAN_TERMINAL_STATUSES.some((s) => s === p.status));
 }
 
 /** Options gating the confirm-default (rule 3) and shared-base (rule 4) admission rules. Both
@@ -926,7 +926,7 @@ export async function startPlan(
   }
   const table = plans(data);
   const existing = await table.get(parsed.planKey);
-  if (existing && !PLAN_TERMINAL_STATUSES.includes(existing.status)) {
+  if (existing && !PLAN_TERMINAL_STATUSES.some((s) => s === existing.status)) {
     return { planKey: parsed.planKey, alreadyRunning: true };
   }
   const base = normalizeBaseBranch(baseBranch);

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -225,6 +225,31 @@ resume cannot double-fire.
 - **Non-npm emit facts** (OCI/github-release) and behavioural edges beyond the `command` escape hatch —
   added when a real case lands.
 
+> **Amendment (issue #492): conditional (guarded) edges landed (S7).** The "behavioural edges" deferral
+> above is **partially lifted**: an edge may now carry an optional guard — `when: "<node>.<fact>"` +
+> `equals: <scalar>` — or be the split's single `default: true` else-branch. A node whose out-edges
+> carry guards is an **exclusive** (data-based) split instead of the default parallel fan-out; its guarded branches compile to a BPMN `exclusiveGateway` (`gwx<i>`) with one FEEL
+> `conditionExpression` per guarded flow (`=<producerElement>_<fact> = <literal>`) and a named default
+> flow, and where those branches re-converge they merge on an **exclusive** gateway (`gwm<i>`,
+> first-token-proceeds) rather than the parallel AND-join that would deadlock the untaken branch. The
+> validator enforces the guard's shape and closes the deadlock/ambiguity classes: a guard must
+> reference a **scalar** fact **declared by the edge's own producer** (`bad-when`), carry an `equals`
+> whose type matches the fact (`guard-missing-equals` / `guard-type-mismatch`), never combine `when`
+> with `default` (`guard-default-conflict`); a split must not **mix** guarded and plain out-edges
+> (`mixed-fan-out`) nor declare **two** defaults (`multiple-defaults`), must be **exhaustive** — a
+> `default`, unless a single boolean fact is guarded on both `true` and `false` (`non-exhaustive-split`)
+> — and a plain (parallel) AND-join may not be fed by an exclusive-split branch (`exclusive-merge-parity`),
+> including the implicit **End sink**: the terminal nodes may not mix a conditional (exclusive-split)
+> tail with an always-firing one, which would deadlock the End join or double-fire its exclusive merge.
+> The exclusive-split topology (both the validator's parity analysis and the compiler's gateway
+> selection) is derived from the **guarded (`when`) edges fanning out to \>=2 distinct downstream
+> targets only** — a lone `default: true` edge with no guarded sibling always fires, and a node whose
+> guarded + `default` edges all converge on **one** downstream target has no real fan-out, so in
+> either case its producer is **not** a split and must not mark downstream nodes/leaves conditional;
+> the per-node mixing/exhaustiveness checks still apply to any `default`.
+> Determinism is preserved: gateway ids are positional over id-sorted nodes, so a graph with no guards
+> compiles byte-for-byte as before.
+
 ## Open questions
 
 - **Compiler target for the first cut** — confirm compile-to-native (diagram + native scheduling) vs a

package/openapi.yaml

@@ -1502,7 +1502,9 @@ components:
         `from` is either a bare `<nodeId>` (wait for the upstream node's completion fact) or a
         qualified `<nodeId>.<fact>` referencing a declared `emits` fact of that node. Both endpoints
         must resolve to a node in the graph, the referenced fact must be declared, and the whole edge
-        set must be a DAG — all enforced by `validateDeliveryGraph`.
+        set must be a DAG — all enforced by `validateDeliveryGraph`. An OPTIONAL `when`/`equals` guard
+        (or a `default` else-branch) makes the edge CONDITIONAL, turning its producer into an
+        exclusive split (ADR 0005 S7) — a node's out-edges are then ALL guarded or ALL unconditional.
       type: object
       additionalProperties: false
       required:
@@ -1517,6 +1519,33 @@ components:
           type: string
           minLength: 1
           description: The dependent node's id — proceeds once `from` is observed.
+        when:
+          type: string
+          minLength: 1
+          description: >-
+            OPTIONAL guard reference `<nodeId>.<fact>` naming a SCALAR emitted fact (`string`,
+            `number`, or `boolean`) of the `from`-adjacent producer (ADR 0005 S7). Its presence makes
+            this a GUARDED edge and turns the producer into an exclusive-split point: the edge is taken
+            only when that runtime fact `equals` the literal below. Equality-only — no arbitrary
+            expressions (the trust boundary). Mutually exclusive with `default`.
+        equals:
+          description: >-
+            The literal value `when`'s fact must equal for this guarded edge to be taken (ADR 0005 S7).
+            REQUIRED iff `when` is present, and its JSON type must match the referenced fact's declared
+            type (`string`/`number`/`boolean`).
+          oneOf:
+            - type: string
+            - type: number
+            - type: boolean
+        default:
+          type: boolean
+          enum: [true]
+          description: >-
+            OPTIONAL — marks this edge as the ELSE branch of the exclusive split (taken when no guarded
+            edge matches at runtime). A FLAG: only `true` is meaningful, so it is constrained to `true`
+            (omit the field entirely for a non-default edge — `default: false` is not a valid wire
+            value). At most one `default` edge per split node. Mutually exclusive with `when`/`equals`
+            (ADR 0005 S7).
     DeliveryCompileError:
       description: >-
         One semantic-validation or compile failure, path-qualified at the offending input
@@ -1749,6 +1778,19 @@ components:
         fromFact:
           type: string
           description: The referenced emitted fact, when the edge `from` was qualified.
+        when:
+          type: string
+          description: The guard reference (`<nodeId>.<fact>`) verbatim, present only on a guarded edge (ADR 0005 S7).
+        equals:
+          description: The literal the guard fact must equal, present only on a guarded edge (ADR 0005 S7).
+          oneOf:
+            - type: string
+            - type: number
+            - type: boolean
+        default:
+          type: boolean
+          enum: [true]
+          description: True when this is the exclusive split's default (else) branch; a FLAG, only ever `true` and omitted otherwise (ADR 0005 S7).
     ResolvedDeliveryGraph:
       description: >-
         The normalised graph the compiler resolved from the input (ADR 0005 slice S1) — nodes and

package/package.json

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

package/pages/cockpit/cockpit.css

@@ -173,6 +173,18 @@
   border-radius: 6px;
 }
 
+/* The "connected — waiting for output" status note under the terminal (blank-terminal defect fix):
+   hidden until a live drill is connected-but-quiet, so a blank panel reads as "waiting" not "broken". */
+.cockpit-terminal-note {
+  margin: 8px 0 0;
+  font-size: 0.85em;
+  color: #7c8794;
+  font-style: italic;
+}
+.cockpit-terminal-note[data-terminal-note="none"] {
+  display: none;
+}
+
 /* ── Past sessions (H3 read path / #222): the captured-session history + replay. ──────────────── */
 
 .cockpit-past-header {

package/pages/cockpit/mount.js

@@ -72,6 +72,7 @@ function workerView(worker, staleAfterMs, byJobKey) {
     host: worker.host ?? "\u2014",
     jobKeys,
     jobs: jobKeys.length,
+    drillable: jobKeys.length > 0,
     correlations,
     liveness: liveness(worker, staleAfterMs),
     staleMs: worker.staleMs,
@@ -141,12 +142,18 @@ function workerRow(doc, worker, onDrill, onOpenWorker) {
   button.setAttribute("data-stream", worker.stream);
   if (onOpenWorker) button.addEventListener("click", () => onOpenWorker(worker.instance));
   nameCell.appendChild(button);
-  const drill = el(doc, "button", "cockpit-worker-drill", "terminal");
-  drill.setAttribute("type", "button");
-  drill.setAttribute("data-instance", worker.instance);
-  drill.setAttribute("data-stream", worker.stream);
-  if (onDrill) drill.addEventListener("click", () => onDrill(worker.stream));
-  nameCell.appendChild(drill);
+  // The inline live-terminal drill — ONLY for a worker that currently holds a job. An idle worker's
+  // `stream` is its bare instance id, which no producer writes to, so drilling it opens a permanently
+  // blank "live" terminal. Suppress the affordance when there is nothing live to stream (mirrors
+  // app/agentic/cockpit/supply-render.ts).
+  if (worker.drillable) {
+    const drill = el(doc, "button", "cockpit-worker-drill", "terminal");
+    drill.setAttribute("type", "button");
+    drill.setAttribute("data-instance", worker.instance);
+    drill.setAttribute("data-stream", worker.stream);
+    if (onDrill) drill.addEventListener("click", () => onDrill(worker.stream));
+    nameCell.appendChild(drill);
+  }
   row.appendChild(nameCell);
 
   row.appendChild(el(doc, "td", "cockpit-td cockpit-supply-family", worker.family));
@@ -494,6 +501,12 @@ export function mountCockpit(host, opts = {}) {
   const terminalHost = el(doc, "div", "cockpit-terminal-host");
   terminalHost.setAttribute("data-terminal", "host");
   terminalPanel.appendChild(terminalHost);
+  // Status note under the terminal, shown while a LIVE drill has connected but no output has arrived
+  // yet (a quiet job between frames), so a blank panel reads as "waiting" not "broken". Cleared on
+  // the first frame and on every mode change (mirrors app/agentic/cockpit/supply-boot.ts).
+  const terminalNote = el(doc, "p", "cockpit-terminal-note");
+  terminalNote.setAttribute("data-terminal-note", "none");
+  terminalPanel.appendChild(terminalNote);
   shell.appendChild(listRegion);
   shell.appendChild(pastRegion);
   shell.appendChild(terminalPanel);
@@ -524,6 +537,19 @@ export function mountCockpit(host, opts = {}) {
     if (next === "live") terminalTitle.textContent = "Worker terminal — live";
     else if (next === "replay") terminalTitle.textContent = "Worker terminal — replay (past session)";
     else terminalTitle.textContent = "Worker terminal";
+    // Any mode change replaces what's behind the panel, so the prior "waiting" note is stale — clear
+    // it. A live drill re-arms it once its fresh terminal is mounted.
+    setNote(undefined);
+  }
+
+  function setNote(text) {
+    if (text == null) {
+      terminalNote.textContent = "";
+      terminalNote.setAttribute("data-terminal-note", "none");
+      return;
+    }
+    terminalNote.textContent = text;
+    terminalNote.setAttribute("data-terminal-note", "waiting");
   }
 
   function teardownTerminal() {
@@ -586,8 +612,19 @@ export function mountCockpit(host, opts = {}) {
     teardownTerminal();
     try {
       terminalHost.replaceChildren();
-      const sink = xtermSink(terminalHost);
-      terminal = sink;
+      const rawSink = xtermSink(terminalHost);
+      terminal = rawSink;
+      // Wrap the sink so the first byte of live output clears the "waiting" note (mirrors supply-boot).
+      let cleared = false;
+      const sink = {
+        write: (chunk) => {
+          if (!cleared) {
+            cleared = true;
+            setNote(undefined);
+          }
+          rawSink.write(chunk);
+        },
+      };
       let session;
       const client = new RelayChannelClient({
         connect: connectRelay,
@@ -599,6 +636,8 @@ export function mountCockpit(host, opts = {}) {
       client.open();
       drill = { stream, client };
       setMode("live", stream);
+      // Arm the "waiting for output" note (after setMode, which clears it) until the first frame.
+      setNote("Connected — waiting for live output…");
     } catch (err) {
       // The new terminal failed to build after the prior one was torn down: reset the region to idle
       // (and drop any partially-built terminal) so the UI never shows a stale "live"/"replay"