@nanobpm/nano-workforce 0.148.2 → 0.149.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.149.0](https://github.com/nanobpm/nano-workforce/compare/v0.148.2...v0.149.0) (2026-08-27)
+
+### Features
+
+* **delivery-graph:** epic 'fully merged' wait kind + dispatch fact-bound wait[pr] targets ([#572](https://github.com/nanobpm/nano-workforce/issues/572)) ([91e9ad8](https://github.com/nanobpm/nano-workforce/commit/91e9ad8f5d1e7079859937e245c01ceb0497be84)), closes [#570](https://github.com/nanobpm/nano-workforce/issues/570) [#548](https://github.com/nanobpm/nano-workforce/issues/548) [#568](https://github.com/nanobpm/nano-workforce/issues/568) [#570](https://github.com/nanobpm/nano-workforce/issues/570) [#568](https://github.com/nanobpm/nano-workforce/issues/568) [#548](https://github.com/nanobpm/nano-workforce/issues/548)
+
 ## [0.148.2](https://github.com/nanobpm/nano-workforce/compare/v0.148.1...v0.148.2) (2026-08-27)
 
 ### Bug Fixes

package/app/deliveryGraphCompiler.test.ts

@@ -152,6 +152,57 @@ test("late-binding: a fact-qualified edge threads a boundFacts input into the co
   assert(boundInput, `boundFacts is a single-quoted FEEL list literal, got: ${r.bpmn.match(/source='[^']*' target="boundFacts"/)?.[0] ?? r.bpmn.match(/source="[^"]*" target="boundFacts"/)?.[0]}`);
 });
 
+test("#568 epic wait kind: an `epic` wait node compiles to a readiness gate and seeds its probe verbatim", async () => {
+  // A new `wait` kind `epic` (issue #568) gates a graph on an nwf plan-fanout epic reaching "fully
+  // merged", keyed by its planKey. It reuses the SAME readiness-gate machinery as `pr` (Decision 3 —
+  // never a second wait loop), so it compiles through with no BPMN branch: the node delegates to
+  // `pr.readiness-probe` and seeds `nodeInputs.<el>.probe` (the whole descriptor) verbatim.
+  const graph = {
+    name: "epic gate",
+    nodes: [
+      { id: "gate-epic", kind: "wait", wait: { kind: "epic", target: "nanobpm/nano-ide#488", match: { epicState: "merged" }, onTimeout: "escalate" } },
+      { id: "start-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "implement #567" } },
+    ],
+    edges: [{ from: "gate-epic", to: "start-b" }],
+  };
+  const r = await compileOk(graph);
+  const types = new Set([...r.bpmn.matchAll(/<zeebe:taskDefinition type="([^"]+)"/g)].map((m) => m[1]));
+  assert(types.has("pr.readiness-probe"), "the epic wait delegates to the shared readiness-probe gate");
+  // The epic wait's element (n0 — sorted node id `gate-epic` precedes `start-b`) seeds its probe.
+  assert(r.bpmn.includes('source="=nodeInputs.n0.probe" target="probe"'), "the epic wait seeds its probe descriptor verbatim");
+});
+
+test("#572 epic prCount emit: a wait[epic] node's `prCount` fact publishes from the epic-match `prCount` bind, not the probe detail", async () => {
+  // matchEpic binds `{ prCount }` on a fully-merged match, but the probe-loop only lifted
+  // ready/detail/resolvedArtifact/mergedSha/observed out of the gate scope, and factSourceVar mapped
+  // a non-mergedSha/non-artifact fact to `detail` — so a documented `emits: [{name:"prCount"}]` wait
+  // node published the detail STRING instead of the count. Thread prCount end-to-end (Copilot #572).
+  const graph = {
+    name: "epic count gate",
+    nodes: [
+      {
+        id: "gate-epic",
+        kind: "wait",
+        wait: { kind: "epic", target: "nanobpm/nano-ide#488", match: { epicState: "merged" }, onTimeout: "escalate" },
+        emits: [{ name: "prCount", type: "number" }],
+      },
+      { id: "start-b", kind: "agent", agent: { jobType: "senior:feature", prompt: "implement #567" } },
+    ],
+    edges: [{ from: "gate-epic.prCount", to: "start-b" }],
+  };
+  const r = await compileOk(graph);
+  // The probe-loop subProcess must lift `prCount` out of the gate scope (alongside mergedSha).
+  assert(
+    r.bpmn.includes('source="=if (is defined(prCount)) then prCount else null" target="prCount"'),
+    "the probe loop lifts the prCount bind out of the gate scope",
+  );
+  // The wait node's emit output must SOURCE prCount from the `prCount` variable, not `detail`.
+  assert(
+    r.bpmn.includes('source="=if (is defined(prCount)) then prCount else null" target="n0_prCount"'),
+    "the prCount emit publishes from the prCount bind variable, not the probe detail",
+  );
+});
+
 test("#499 human context: the human user-task seeds prompt/nodeId/emit context so its generic form is not contextless", async () => {
   const r = await compileOk(RELEASE_RUNBOOK);
   // The human node's subProcess ioMapping must thread the authored prompt + node identity + emit

package/app/deliveryGraphCompiler.ts

@@ -151,9 +151,10 @@ function byCodeUnit(a: string, b: string): number {
 
 /** The engine variable a producer node's OUTPUT mapping reads to publish a declared emitted `fact`
  * (S4 late-binding). Each node kind's real body exposes the observed value under a canonical name:
- *   • `wait` (readiness-gate) — a `mergedSha` fact reads the merge oid; an `artifact` fact reads the
- *     `resolvedArtifact` bind (mirroring the `capability`/`pr` probe binds); anything else reads the
- *     probe's `detail`.
+ *   • `wait` (readiness-gate) — a `mergedSha` fact reads the merge oid; a `prCount` fact reads the
+ *     epic-match `prCount` bind (how many slice PRs a `wait[epic]` landed); an `artifact` fact reads
+ *     the `resolvedArtifact` bind (mirroring the `capability`/`pr` probe binds); anything else reads
+ *     the probe's `detail`.
  *   • `human` (delivery-human) — an `artifact` fact reads `humanEmitArtifact`; anything else reads
  *     `humanEmitValue` (the generic typed-emit form's captured value).
  *   • `agent`/`connector` — the body's job worker returns the value under the fact's own name.
@@ -161,7 +162,13 @@ function byCodeUnit(a: string, b: string): number {
 function factSourceVar(kind: DeliveryNode["kind"], fact: DeliveryFact): string {
   switch (kind) {
     case "wait":
-      return fact.name === "mergedSha" ? "mergedSha" : fact.type === "artifact" ? "resolvedArtifact" : "detail";
+      return fact.name === "mergedSha"
+        ? "mergedSha"
+        : fact.name === "prCount"
+          ? "prCount"
+          : fact.type === "artifact"
+            ? "resolvedArtifact"
+            : "detail";
     case "human":
       return fact.type === "artifact" ? "humanEmitArtifact" : "humanEmitValue";
     case "agent":
@@ -1013,6 +1020,7 @@ function waitBodyLines(el: string, node: Extract<DeliveryNode, { kind: "wait" }>
     '            <zeebe:output source="=if (is defined(detail)) then detail else null" target="detail" />',
     '            <zeebe:output source="=if (is defined(resolvedArtifact)) then resolvedArtifact else null" target="resolvedArtifact" />',
     '            <zeebe:output source="=if (is defined(mergedSha)) then mergedSha else null" target="mergedSha" />',
+    '            <zeebe:output source="=if (is defined(prCount)) then prCount else null" target="prCount" />',
     '            <zeebe:output source="=if (is defined(observed)) then observed else null" target="observed" />',
     "          </zeebe:ioMapping>",
     "        </bpmn:extensionElements>",

package/app/deliveryRunner.test.ts

@@ -362,3 +362,33 @@ test("runDeliveryGraph coerces a numeric engine processInstanceKey to a string h
   assertEquals(r.handle.processInstanceKey, "987654321");
   assertEquals(typeof r.handle.processInstanceKey, "string");
 });
+
+test("the canonical `agent → converge-merge → wait[pr merged]` graph DISPATCHES with a fact-bound wait target (#570)", async () => {
+  // Regression for #570: a `wait[pr]` node whose `target` is a fact reference (`open.pr`, the #548
+  // late-binding shape the guide documents as canonical) COMPILED+staged but threw at dispatch —
+  // `buildNodeInput`'s wait case eagerly `parseProbe`'d the fact-ref target as a literal `owner/repo#N`
+  // and aborted the whole launch. It must now LAUNCH (the target is resolved at runtime by the
+  // readiness-probe worker), while a genuinely malformed literal still fails loudly (see the
+  // deliveryRunner sibling assertion + readiness.test.ts).
+  const graph: DeliveryGraph = {
+    name: "canonical land shape",
+    nodes: [
+      { id: "open", kind: "agent", agent: { jobType: "senior:feature", prompt: "open a PR" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "converge-merge", kind: "connector", connector: { target: "converge-merge", payload: { pr: "open.pr" } } },
+      { id: "merged", kind: "wait", wait: { kind: "pr", target: "open.pr", match: { prState: "merged" }, onTimeout: "escalate" } },
+    ],
+    edges: [
+      { from: "open.pr", to: "converge-merge" },
+      { from: "open.pr", to: "merged" },
+    ],
+  };
+  // Dispatch through the full launch path (prepare → deploy → createInstance). Before the fix this
+  // threw synchronously inside buildNodeInput; now it launches.
+  const engine = {
+    deployResources: async () => [],
+    createInstance: async () => ({ processInstanceKey: "555" }),
+  };
+  const r = await runDeliveryGraph(engine, graph);
+  assert(r.ok, `expected the canonical fact-bound wait[pr] graph to launch, got ${JSON.stringify(r)}`);
+  assertEquals(r.handle.processInstanceKey, "555");
+});

package/app/deliveryRunner.ts

@@ -276,7 +276,7 @@ function buildNodeInput(
       return { jobType: node.agent.jobType, appendPrompt: renderIdempotencyPreamble() + basePrompt + renderEmitContract(emits), timeout: isoDuration(node.agent.timeout, ctx.nodeTimeout) };
     }
     case "wait": {
-      const probe = parseProbe(node.wait);
+      const probe = parseProbe(node.wait, { allowLateBoundTarget: true });
       // Only a VALID, positive per-node budget overrides the run level. Match the `>= 1` predicate
       // `readinessTimeout`/`readinessPollEvery` apply internally, rather than a bare JS-truthiness
       // check on `poll.timeoutMs`/`everyMs`: a negative (`-1`) value is truthy, so a truthiness gate

package/app/readiness.test.ts

@@ -18,6 +18,7 @@ import {
   MAX_EVERY_MS,
   matchCapability,
   matchCommand,
+  matchEpic,
   matchGithubCheck,
   matchHttp,
   matchNpm,
@@ -28,6 +29,10 @@ import {
   normalizePoll,
   parseProbe,
   parsePrTarget,
+  epicLineageUrl,
+  type EpicObservation,
+  isFactRefTarget,
+  parseEpicLineage,
   summariseCapabilityCandidates,
   parsePrView,
   parseReleases,
@@ -468,6 +473,141 @@ test("parseProbe: a valid pr probe round-trips its prState", () => {
   assertEquals(p.match?.prState, "mergeable");
 });
 
+// ── #570: a fact-bound pr/epic target DISPATCHES (late-binding), a malformed literal still fails ──
+test("parseProbe: a FACT-BOUND pr target (`<node>.<fact>`) parses (resolved at dispatch, not a literal here) — #570", () => {
+  // The documented canonical `agent → converge-merge → wait[pr merged]` shape wires the wait's
+  // `target` to the upstream node's emitted `pr` fact (`open.pr`). It is NOT an `owner/repo#N`
+  // literal at parse/dispatch time — the compiler rewrites it to the OBSERVED PR — so parseProbe must
+  // accept it (WITH the delivery-graph opt-in) rather than throw and abort the whole dispatch.
+  const p = parseProbe({ kind: "pr", target: "open.pr", match: { prState: "merged" } }, { allowLateBoundTarget: true });
+  assertEquals(p.kind, "pr");
+  assertEquals(p.target, "open.pr");
+});
+
+test("parseProbe: a fact-bound pr target is REJECTED without the delivery-graph opt-in (non-delivery-graph surfaces have no resolver, must fail loudly at submit)", () => {
+  // `app/featureReadiness.ts` parses probes with NO late-binding compiler rewrite, so a fact-ref
+  // target there could never resolve. Default-off keeps the loud submit-time failure (Copilot #572).
+  assertThrows(() => parseProbe({ kind: "pr", target: "open.pr", match: { prState: "merged" } }), Error, "owner/repo#<number>");
+});
+
+test("parseProbe: a genuinely malformed (dot-free) pr literal still throws — #570 keeps the loud failure", () => {
+  assertThrows(() => parseProbe({ kind: "pr", target: "foo" }), Error, "owner/repo#<number>");
+});
+
+test("isFactRefTarget: distinguishes a `<node>.<fact>` reference from a literal handle", () => {
+  assert(isFactRefTarget("open.pr"), "a dotted, hash-free ref is a fact reference");
+  assert(isFactRefTarget("converge-merge.mergedSha"), "a hyphenated node id with a fact");
+  assert(!isFactRefTarget("nanobpm/nano-workforce#377"), "a literal PR handle carries a #number");
+  assert(!isFactRefTarget("foo"), "a dot-free bare word is not a fact reference");
+  assert(!isFactRefTarget("open."), "a trailing dot is not a fact reference");
+  assert(!isFactRefTarget(".pr"), "a leading dot is not a fact reference");
+});
+
+// ── parseProbe: epic kind (#568 — planKey target + validated epicState) ───────────────────────────
+test("parseProbe: accepts an owner/repo#NN epic probe (keyed by planKey) and defaults onTimeout to escalate", () => {
+  const p = parseProbe({ kind: "epic", target: "nanobpm/nano-ide#488", match: { epicState: "merged" } });
+  assertEquals(p.kind, "epic");
+  assertEquals(p.onTimeout, "escalate");
+  assertEquals(p.match?.epicState, "merged");
+});
+
+test("parseProbe: an epic probe whose target is no planKey throws (never resolvable)", () => {
+  assertThrows(() => parseProbe({ kind: "epic", target: "nanobpm/nano-ide" }), Error, "planKey");
+});
+
+test("parseProbe: an epic probe with an unknown match.epicState throws (mistyped state fails loudly)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "epic", target: "o/r#1", match: { epicState: "landed" } }),
+    Error,
+    "invalid match.epicState",
+  );
+});
+
+test("parseProbe: a FACT-BOUND epic target parses WITH the delivery-graph opt-in (late-binding, same as pr)", () => {
+  const p = parseProbe({ kind: "epic", target: "plan.epic" }, { allowLateBoundTarget: true });
+  assertEquals(p.target, "plan.epic");
+});
+
+test("parseProbe: a fact-bound epic target is REJECTED without the delivery-graph opt-in (fails loudly at submit)", () => {
+  assertThrows(() => parseProbe({ kind: "epic", target: "plan.epic" }), Error, "planKey");
+});
+
+// ── matchEpic (pure — operates on an already-fetched epic observation) ────────────────────────────
+function epicObs(over: Partial<EpicObservation> = {}): EpicObservation {
+  return { present: true, stage: "converging", active: true, prCount: 3, ...over };
+}
+
+test("matchEpic: green once the epic settles on a fully-merged aggregate, binding prCount", () => {
+  const r = matchEpic({ epicState: "merged" }, epicObs({ stage: "merged", active: false, prCount: 5 }));
+  assert(r.ready, "a fully-merged epic is ready");
+  assertEquals(r.bind?.prCount, "5");
+});
+
+test("matchEpic: not-ready while the epic is still in flight", () => {
+  const r = matchEpic({ epicState: "merged" }, epicObs({ stage: "converging", active: true }));
+  assert(!r.ready, "an in-flight epic is not ready");
+});
+
+test("matchEpic: a failed/abandoned epic is NOT ready (routes via onTimeout, never a false-green)", () => {
+  // A settled-but-not-merged epic (abandoned/resolved) never reports ready, so the bounded wait routes
+  // to onTimeout rather than hanging OR falsely proceeding — issue #568 acceptance.
+  for (const stage of ["abandoned", "resolved", "converged"]) {
+    const r = matchEpic({ epicState: "merged" }, epicObs({ stage, active: false }));
+    assert(!r.ready, `a '${stage}' epic must not be ready`);
+    assertStringIncludes(r.detail, "onTimeout");
+  }
+});
+
+test("matchEpic: an as-yet-unobserved planKey is not ready (keep waiting)", () => {
+  const r = matchEpic(undefined, { present: false, stage: "", active: false, prCount: 0 });
+  assert(!r.ready);
+});
+
+test("parseEpicLineage: reads the matching thread from a `/lineage?root=` response", () => {
+  const payload = { count: 1, threads: [{ rootRequestKey: "o/r#7", stage: "merged", active: false, prCount: 4 }] };
+  const obs = parseEpicLineage(payload, "o/r#7");
+  assertEquals(obs, { present: true, stage: "merged", active: false, prCount: 4 });
+});
+
+test("parseEpicLineage: an unknown/empty root yields an absent observation (not ready, no throw)", () => {
+  assertEquals(parseEpicLineage({ count: 0, threads: [] }, "o/r#9"), { present: false, stage: "", active: false, prCount: 0 });
+  assertEquals(parseEpicLineage("garbage", "o/r#9"), { present: false, stage: "", active: false, prCount: 0 });
+});
+
+test("epicLineageUrl: builds the app lineage read-model URL from the base + planKey", () => {
+  assertEquals(epicLineageUrl("o/r#12", "http://host:3000/"), "http://host:3000/app/api/lineage?root=o%2Fr%2312");
+});
+
+test("probeOnce: an epic probe reads the app lineage endpoint and goes green when fully merged", async () => {
+  const capture: { url?: string } = {};
+  const exec: ProbeExec = {
+    async httpGet(url) {
+      capture.url = url;
+      return { status: 200, body: JSON.stringify({ count: 1, threads: [{ rootRequestKey: "o/r#7", stage: "merged", active: false, prCount: 2 }] }) };
+    },
+    async run() {
+      return { code: 0, stdout: "", stderr: "" };
+    },
+  };
+  const probe = parseProbe({ kind: "epic", target: "o/r#7" });
+  const r = await probeOnce(probe, exec, { NANO_WORKFORCE_BASE_URL: "http://host:3000" });
+  assert(r.ready, "a fully-merged epic goes green");
+  assertStringIncludes(capture.url ?? "", "/app/api/lineage?root=o%2Fr%237");
+});
+
+test("probeOnce: an epic probe stays not-ready on a non-2xx lineage read (transient → keep waiting)", async () => {
+  const exec: ProbeExec = {
+    async httpGet() {
+      return { status: 503, body: "" };
+    },
+    async run() {
+      return { code: 0, stdout: "", stderr: "" };
+    },
+  };
+  const r = await probeOnce(parseProbe({ kind: "epic", target: "o/r#7" }), exec, {});
+  assert(!r.ready, "a failed read is not ready, never a throw");
+});
+
 // ── matchPr (pure — operates on an already-fetched PR observation) ────────────────────────────────
 function prObs(over: Partial<PrObservation> = {}): PrObservation {
   return {

package/app/readiness.ts

@@ -30,7 +30,7 @@ import { isoDuration, isoDurationToMs } from "./reviewWait.ts";
  * merge loop (`app/mergeProtocol.ts` / `app/github.ts`) into a first-class probe so "watch an
  * in-flight PR reach a declared state" is a graph edge, not logic buried in the merge-loop node
  * body — the ACTION (landing the PR) stays in that node body; this kind only OBSERVES. */
-export type ProbeKind = "http" | "command" | "npm" | "github-check" | "capability" | "pr";
+export type ProbeKind = "http" | "command" | "npm" | "github-check" | "capability" | "pr" | "epic";
 
 /** The declared PR state a `pr` probe waits for (ADR 0005 §2). Each is a discovered fact about an
  * in-flight PR, read from its live GitHub state and evaluated by {@link matchPr}:
@@ -41,16 +41,26 @@ export type ProbeKind = "http" | "command" | "npm" | "github-check" | "capabilit
  *   • `checks-green` — every head check run is complete with none failing (required checks green). */
 export type PrCondition = "ready" | "merged" | "mergeable" | "checks-green";
 
+/** The declared epic (plan-fanout) state an `epic` probe waits for (issue #568). An nwf epic fans out
+ * many slice PRs across waves whose numbers are unknown at compose time, so this kind gates on the
+ * app's AGGREGATE ("all slices merged"), not a single PR. Both values mean the same terminal —
+ * "fully merged" — and are read from the app's lineage read-model (`stage === "merged"`, i.e. every
+ * opened slice landed): `merged` is the canonical name; `done` is accepted as a synonym for the plan
+ * aggregate reaching `done`. A failed/abandoned/mixed epic never reports this stage, so it never goes
+ * ready and the bounded wait routes to `onTimeout` rather than hanging. */
+export type EpicCondition = "merged" | "done";
+
 /** What the gate does when the bounded wait times out (the engine timer arm fires). */
 export type OnTimeout = "escalate" | "fail" | "continue";
 
 /** Backoff policy between poll attempts. */
 export type Backoff = "fixed" | "exponential";
 
-const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr"];
+const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr", "epic"];
 const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
 const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
 const PR_CONDITIONS: readonly PrCondition[] = ["ready", "merged", "mergeable", "checks-green"];
+const EPIC_CONDITIONS: readonly EpicCondition[] = ["merged", "done"];
 
 /** The per-kind readiness predicate. Every field is optional; each kind reads only the ones it
  * understands and applies a sensible default when a field is absent (see the matchers below). */
@@ -84,6 +94,10 @@ export interface ProbeMatch {
   /** pr: the declared PR state the probe waits for (default `merged`). One of {@link PrCondition} —
    * `ready` (out of draft), `merged`, `mergeable`, or `checks-green`. */
   readonly prState?: PrCondition;
+  /** epic: the declared epic (plan-fanout) aggregate state the probe waits for (default `merged`).
+   * One of {@link EpicCondition} — `merged`/`done` both mean "fully merged" (every opened slice
+   * landed). Issue #568. */
+  readonly epicState?: EpicCondition;
 }
 
 /** The poll cadence: how often to re-probe, how long to keep trying, and the backoff shape. */
@@ -195,8 +209,17 @@ function isRecord(v: unknown): v is Record<string, unknown> {
  * Throws a descriptive error on an unknown/missing `kind`, a blank `target`, an invalid
  * `onTimeout`/`backoff`, or a `credentialEnv` on a non-`http` kind — a malformed probe must fail
  * loudly at the worker, never silently wait forever (nor let a caller believe a subprocess probe is
- * authenticated when its credential is silently ignored). */
-export function parseProbe(raw: unknown): ReadinessProbe {
+ * authenticated when its credential is silently ignored).
+ *
+ * `opts.allowLateBoundTarget` opts a caller into accepting a fact-bound `<nodeId>.<fact>` target for
+ * the `pr`/`epic` kinds — the #548/#570 late-binding reference the delivery-graph compiler rewrites
+ * to the observed handle at dispatch. It is OFF by default: only the delivery-graph dispatch path
+ * (`app/deliveryRunner.ts`) sets it. Every other surface (e.g. feature-intake readiness in
+ * `app/featureReadiness.ts`) has no such compiler rewrite, so a fact-ref target there could never
+ * resolve — keeping it off means a mis-declared gate fails loudly at submit rather than degrading
+ * into a runtime timeout/escalation. */
+export function parseProbe(raw: unknown, opts?: { allowLateBoundTarget?: boolean }): ReadinessProbe {
+  const allowLateBoundTarget = opts?.allowLateBoundTarget === true;
   if (!isRecord(raw)) throw new Error("readiness probe: descriptor must be an object");
   const kind = str(raw.kind).trim();
   if (!isProbeKind(kind)) {
@@ -233,12 +256,28 @@ export function parseProbe(raw: unknown): ReadinessProbe {
     }
   }
   // A pr edge whose target names no numeric PR id can never resolve — fail loudly at parse (mirroring
-  // the capability ref guard) rather than surface it as a timeout much later. `owner/repo#123`.
-  if (kind === "pr" && !parsePrTarget(target)) {
+  // the capability ref guard) rather than surface it as a timeout much later. `owner/repo#123`. A
+  // FACT-BOUND target (`<nodeId>.<fact>`, e.g. `open.pr`) is exempt: it is a #548 late-binding
+  // reference the compiler rewrites to the OBSERVED PR at dispatch and the readiness-probe worker
+  // resolves at runtime — it is legitimately not a literal here, so validating it as one would reject
+  // the documented canonical `agent → converge-merge → wait[pr merged]` shape (issue #570). A
+  // genuinely malformed literal (dot-free, e.g. `foo`) is not fact-ref-shaped, so it still fails. The
+  // exemption is gated on `allowLateBoundTarget`: a non-delivery-graph caller (default OFF) has no
+  // compiler rewrite, so a fact-ref target there can never resolve — it must fail loudly at submit.
+  if (kind === "pr" && !(allowLateBoundTarget && isFactRefTarget(target)) && !parsePrTarget(target)) {
     throw new Error(
       `readiness probe (pr): 'target' ('${target}') must be an 'owner/repo#<number>' PR reference (e.g. 'nanobpm/nano-workforce#377')`,
     );
   }
+  // An epic edge is keyed by the durable `planKey` (`owner/repo#NN`, the epic issue) — the stable
+  // business id, so a resubmit/replay still resolves (issue #568). Validate it as a literal planKey,
+  // exempting a fact-bound reference for the same #548 late-binding reason as `pr` above (and gated
+  // on the same `allowLateBoundTarget` opt-in, so a non-delivery-graph caller still fails loudly).
+  if (kind === "epic" && !(allowLateBoundTarget && isFactRefTarget(target)) && !parsePrTarget(target)) {
+    throw new Error(
+      `readiness probe (epic): 'target' ('${target}') must be an 'owner/repo#<number>' planKey (the epic issue, e.g. 'nanobpm/nano-workforce#374')`,
+    );
+  }
   const poll = isRecord(raw.poll) ? parsePoll(raw.poll) : undefined;
   const credentialEnv = str(raw.credentialEnv).trim() || undefined;
   if (credentialEnv !== undefined && !isEnvKey(credentialEnv)) {
@@ -292,9 +331,47 @@ function parseMatch(raw: Record<string, unknown>): ProbeMatch {
     package: str(raw.package).trim() || undefined,
     verifyCommand: str(raw.verifyCommand).trim() || undefined,
     prState: parsePrCondition(raw.prState),
+    epicState: parseEpicCondition(raw.epicState),
   };
 }
 
+/** Narrow a raw `match.epicState` to an {@link EpicCondition}, throwing on a non-empty unknown value so
+ * a mistyped state fails loudly at parse rather than waiting forever. An absent/blank value yields
+ * undefined — {@link matchEpic} then applies the `merged` default. */
+function parseEpicCondition(raw: unknown): EpicCondition | undefined {
+  const s = str(raw).trim();
+  if (s === "") return undefined;
+  if (!isEpicCondition(s)) {
+    throw new Error(`readiness probe (epic): invalid match.epicState '${s}' (expected one of ${EPIC_CONDITIONS.join(", ")})`);
+  }
+  return s;
+}
+
+function isEpicCondition(v: string): v is EpicCondition {
+  for (const c of EPIC_CONDITIONS) if (c === v) return true;
+  return false;
+}
+
+// A late-binding probe `target` is a `<nodeId>.<fact>` reference to an upstream node's emitted fact
+// (#548) — the compiler rewrites it to the OBSERVED value at dispatch via a FEEL `context put`, and
+// the readiness-probe worker resolves it at runtime, so it is legitimately NOT a literal
+// `owner/repo#N` at parse time (issue #570). A literal PR/epic handle always carries a `#<number>` and
+// never this dotted, hash-free shape, so the two are unambiguous. Splits on the LAST dot, mirroring
+// the graph's `resolveFrom` (a node id MAY contain dots; a fact name — matched by FACT_REF_FACT — may
+// not), so a dot-free malformed literal is not fact-ref-shaped and still fails its kind's validation.
+const FACT_REF_NODE_ID = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+const FACT_REF_FACT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Whether `target` is a `<nodeId>.<fact>` late-binding fact reference (issue #548/#570) rather than a
+ * literal `owner/repo#<number>` handle. See the note above. */
+export function isFactRefTarget(target: string): boolean {
+  const t = target.trim();
+  if (t === "" || t.includes("#")) return false;
+  const dot = t.lastIndexOf(".");
+  if (dot <= 0 || dot === t.length - 1) return false;
+  return FACT_REF_NODE_ID.test(t.slice(0, dot)) && FACT_REF_FACT.test(t.slice(dot + 1));
+}
+
 /** Narrow a raw `match.prState` to a {@link PrCondition}, throwing on a non-empty unknown value so a
  * mistyped state (`"landed"` for `"merged"`) fails loudly at parse rather than waiting forever. An
  * absent/blank value yields undefined — `matchPr` then applies the `merged` default. */
@@ -693,6 +770,83 @@ export function prViewCommand(repo: string, number: string): string {
   return `gh pr view ${shellQuote(number)} --repo ${shellQuote(repo)} --json ${shellQuote("state,mergedAt,mergeStateStatus,statusCheckRollup,isDraft,headRefOid,mergeCommit")}`;
 }
 
+// ── Epic / plan-fanout probe (issue #568 — gate a graph on an epic reaching "fully merged") ──────
+
+/** A live epic (plan-fanout) observation, reduced to the fields {@link matchEpic} reads. An nwf epic
+ * fans out many slice PRs across waves, so "fully merged" is an AGGREGATE, read from the app's own
+ * lineage read-model (`/lineage?root=<planKey>`, {@link parseEpicLineage}) rather than any single PR.
+ * `stage`/`active` are the lineage thread's already-derived frontier: an epic reaches `stage:"merged"`
+ * (and `active:false`) EXACTLY when every opened slice landed (`app/lineage.ts`), while a
+ * failed/abandoned/mixed epic settles on `abandoned`/`resolved` — never `merged` — so it never goes
+ * ready and the bounded wait routes to `onTimeout`. Kept separate from I/O so the matcher stays
+ * pure/unit-testable, exactly like {@link PrObservation}. */
+export interface EpicObservation {
+  /** Whether the planKey resolved to a known lineage thread at all (an as-yet-unknown/never-started
+   * epic yields `present:false` → not ready, keep waiting). */
+  readonly present: boolean;
+  /** The lineage thread's derived frontier stage (e.g. `converging`, `merged`, `resolved`). */
+  readonly stage: string;
+  /** Whether the arc still has an active frontier (false once every stage has settled). */
+  readonly active: boolean;
+  /** Count of slice PRs on the epic — bound downstream as a fact (parity with the `pr` kind's
+   * `mergedSha`), so a consumer can pin how many PRs the epic landed. */
+  readonly prCount: number;
+}
+
+/** Parse a raw `/lineage?root=<planKey>` response (already JSON-decoded) into an {@link EpicObservation}
+ * for `planKey`. The endpoint returns `{ count, threads: [thread] }` (or `threads: []` for an unknown
+ * root); this reads the thread whose `rootRequestKey` matches `planKey`. Tolerant: a malformed/empty
+ * payload yields an absent observation, so a transient read degrades to "not ready" (keep waiting),
+ * never a throw. */
+export function parseEpicLineage(payload: unknown, planKey: string): EpicObservation {
+  const j = isRecord(payload) ? payload : {};
+  const threads = Array.isArray(j.threads) ? j.threads : [];
+  const key = planKey.trim();
+  const thread = threads.find((t) => isRecord(t) && str(t.rootRequestKey).trim() === key);
+  if (!isRecord(thread)) return { present: false, stage: "", active: false, prCount: 0 };
+  const prCount = num(thread.prCount);
+  return {
+    present: true,
+    stage: str(thread.stage).trim().toLowerCase(),
+    active: thread.active === true,
+    prCount: typeof prCount === "number" ? prCount : 0,
+  };
+}
+
+/** epic readiness (issue #568): does the observed epic satisfy the declared `match.epicState`
+ * (default `merged`)? PURE — it operates on an already-fetched {@link EpicObservation} and NEVER
+ * throws, so a transient/garbled read is simply "not ready yet". "Fully merged" means the lineage
+ * thread settled on `stage:"merged"` — every opened slice landed. A failed/abandoned/mixed epic
+ * settles on another terminal (`abandoned`/`resolved`/`converged`), so it stays not-ready and the
+ * bounded wait routes to `onTimeout` rather than hanging. A `merged` match binds `{ prCount }` so a
+ * downstream edge can pin how many slice PRs the epic landed (parity with the `pr` kind's
+ * `mergedSha`). Both `merged` and `done` map to the same "fully merged" terminal. */
+export function matchEpic(match: ProbeMatch | undefined, epic: EpicObservation): ProbeResult {
+  const want: EpicCondition = match?.epicState ?? "merged";
+  if (!epic.present) return { ready: false, detail: `epic (${want}): planKey not observed yet (not ready)` };
+  if (epic.stage === "merged" && !epic.active) {
+    return { ready: true, detail: `epic fully merged (${epic.prCount} slices)`, bind: { prCount: String(epic.prCount) } };
+  }
+  const settled = !epic.active;
+  return {
+    ready: false,
+    detail: settled
+      ? `epic settled on '${epic.stage}' (not fully merged) — routing via onTimeout`
+      : `epic in flight (stage '${epic.stage || "unknown"}', not merged yet)`,
+    observed: `stage=${epic.stage || "unknown"} active=${epic.active} prCount=${epic.prCount}`,
+  };
+}
+
+/** Build the app's lineage read-model URL for an epic's `planKey`. The app mounts its OpenAPI paths
+ * under `/app/api` (mirroring `abandonUrl`/`blackboardUrl` in `app/blackboard.ts`), and `?root=`
+ * accepts a `plan_key`. `base` is the ONE `NANO_WORKFORCE_BASE_URL` env contract (never a second
+ * name), read through the typed schema — so an epic gate is observed over the SAME reachable base a
+ * remote fleet already uses for the abandon/blackboard hooks. */
+export function epicLineageUrl(planKey: string, base: string): string {
+  const b = base.trim().replace(/\/+$/, "") || readEnvOr("NANO_WORKFORCE_BASE_URL");
+  return `${b}/app/api/lineage?root=${encodeURIComponent(planKey.trim())}`;
+}
+
 
 // ── Single probe attempt (does I/O via the injected {@link ProbeExec}) ──────────────────────────
 
@@ -735,6 +889,17 @@ export async function probeOnce(
       if (out.code !== 0) return { ready: false, detail: "pr: gh pr view failed (not ready)" };
       return matchPr(probe.match, parsePrView(parseJson(out.stdout)));
     }
+    case "epic": {
+      // "Fully merged" is the app's AGGREGATE, not a GitHub read — observe it over the app's own
+      // lineage read-model (level-triggered, same poll machinery as `pr`). A fact-bound target that is
+      // still unresolved (`<node>.<fact>`) is not a literal planKey, so treat it as "not ready" and
+      // keep waiting rather than issue a malformed request.
+      if (!parsePrTarget(probe.target)) return { ready: false, detail: "epic: unresolved/unparseable planKey (not ready)" };
+      const url = epicLineageUrl(probe.target, readEnvOr("NANO_WORKFORCE_BASE_URL", "", env));
+      const resp = await exec.httpGet(url, { accept: "application/json" });
+      if (resp.status < 200 || resp.status >= 300) return { ready: false, detail: `epic: lineage read HTTP ${resp.status} (not ready)` };
+      return matchEpic(probe.match, parseEpicLineage(parseJson(resp.body), probe.target));
+    }
   }
 }
 

package/docs/agent-guide.md

@@ -433,18 +433,29 @@ layer schedules, it does not re-implement execution):
 | kind | config | what it does | may `emits`? |
 |---|---|---|---|
 | `agent` | `agent: { jobType, prompt? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** | yes |
-| `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`. Read-only. | yes (binds observed facts) |
+| `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`, `epic`. Read-only. | yes (binds observed facts) |
 | `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
 | `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Two **real targets** ship today — **`converge`** and **`converge-merge`** (§9.4); other targets are a forward-declared stub. | yes |
 
 A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
 intake uses): `{ kind, target, onTimeout?, match?, poll? }`. The **`pr` kind** watches an
 in-flight PR — `target: "owner/repo#123"`, `match.prState ∈ ready|merged|mergeable|checks-green`
-(default `merged`) — and on a merged match binds `mergedSha` as an output fact.
+(default `merged`) — and on a merged match binds `mergedSha` as an output fact. The **`epic`
+kind** (issue #568) gates on an **nwf plan-fanout epic reaching "fully merged"** — `target:
+"owner/repo#NN"` is the epic's durable **`planKey`** (the epic issue, *not* the engine
+`processInstanceKey`, so a resubmit/replay still resolves), `match.epicState ∈ merged|done`
+(default `merged`, both mean "every opened slice landed"). It observes the app's own aggregate
+(the lineage read-model), so a **failed/abandoned/mixed** epic never reports merged and the
+bounded wait routes to **`onTimeout`** rather than hanging; on a fully-merged match it binds
+`prCount` (how many slice PRs landed) as an output fact. Both `pr` and `epic` targets may also
+be a **`<nodeId>.<fact>` late-binding reference** the compiler resolves at dispatch (§9.4),
+rather than a literal handle.
 
 A **typed fact** (`emits[]` entry) is `{ name, type, description? }` where
-`type ∈ string|number|boolean|artifact|version|url` (`artifact` = a `pkg@version` handle,
-`version` = a bare version). `name` matches `^[A-Za-z_][A-Za-z0-9_]*$` and is referenced
+`type ∈ string|number|boolean|artifact|version|url|pr` (`artifact` = a `pkg@version` handle,
+`version` = a bare version, `pr` = a PR reference `owner/repo#N` an `agent` node emits for the
+PR it opened, late-bound by a downstream `wait[pr]`/`connector[converge*]` target — issue #548).
+`name` matches `^[A-Za-z_][A-Za-z0-9_]*$` and is referenced
 downstream as `<nodeId>.<name>`. A "click done" human node or a pass-through node declares
 no facts.
 
@@ -635,3 +646,39 @@ ways to name the target PR:
 `senior:feature` already returns the PR it opened, so declaring `emits: [{ "name": "pr", "type": "pr" }]`
 on the agent node is all it takes to publish it (issue #548).
 
+### 9.5 Gate a graph on an epic reaching "fully merged" (`wait[epic]`)
+
+Sometimes the thing you must wait for is not one PR but a **whole epic** — an nwf
+`plan-fanout` that fans many slice PRs across waves whose numbers are unknown at compose
+time. The **`wait` kind `epic`** (issue #568) gates on that epic reaching **"fully merged"**
+(every opened slice landed), keyed by its durable **`planKey`** (`owner/repo#NN` — the epic
+issue), so *"start feature B once epic A has fully landed"* is an automated edge, not a human
+babysitting a `confirm` gate.
+
+```json
+{
+  "name": "start #567 once epic #488 has fully merged",
+  "nodes": [
+    { "id": "gate-epic", "kind": "wait",
+      "wait": { "kind": "epic", "target": "nanobpm/nano-ide#488",
+                "match": { "epicState": "merged" }, "onTimeout": "escalate" },
+      "emits": [ { "name": "prCount", "type": "number" } ] },
+    { "id": "start-b", "kind": "agent",
+      "agent": { "jobType": "senior:feature", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
+  ],
+  "edges": [ { "from": "gate-epic", "to": "start-b" } ]
+}
+```
+
+Semantics:
+
+- **`target` is the `planKey`** (`owner/repo#NN`, the epic issue) — the *stable business id*,
+  not the engine `processInstanceKey` (`64200`), so a resubmit/replay still resolves.
+- **`match.epicState`** is `merged` (default) or its synonym `done` — both mean "every opened
+  slice landed". The gate reads the app's own **aggregate** (the lineage read-model over
+  `NANO_WORKFORCE_BASE_URL`), so it is level-triggered like `pr` (no missed edge).
+- **A failed/abandoned/mixed epic never reports merged**, so it never falsely releases the
+  gate; the **bounded** wait elapses and routes via **`onTimeout`** (`escalate`/`continue`) —
+  it does **not** hang.
+- On a fully-merged match it binds **`prCount`** (how many slice PRs the epic landed) as an
+  output fact, so a downstream node can consume it (parity with the `pr` kind's `mergedSha`).

package/openapi.yaml

@@ -1245,12 +1245,12 @@ components:
       properties:
         kind:
           type: string
-          enum: [http, command, npm, github-check, capability, pr]
-          description: The readiness source. `command` is the escape hatch; `capability` resolves a cross-repo published-artifact edge; `pr` watches an in-flight PR's merge state (ADR 0005 §2).
+          enum: [http, command, npm, github-check, capability, pr, epic]
+          description: The readiness source. `command` is the escape hatch; `capability` resolves a cross-repo published-artifact edge; `pr` watches an in-flight PR's merge state (ADR 0005 §2); `epic` gates on an nwf plan-fanout epic reaching "fully merged", keyed by its `planKey` (issue #568).
         target:
           type: string
           minLength: 1
-          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, or an `owner/repo#123` PR reference for the `pr` kind).
+          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue #548/#570); this rewrite exists ONLY on the delivery-graph dispatch path — other surfaces (e.g. feature-intake readiness) have no such resolver, so they must supply a literal handle.
         onTimeout:
           type: string
           enum: [escalate, fail, continue]
@@ -1274,6 +1274,7 @@ components:
             package: { type: string, description: "capability: the package whose releases are scanned for provenance." }
             verifyCommand: { type: string, description: "capability: optional empirical verifier run once at the gate boundary." }
             prState: { type: string, enum: [ready, merged, mergeable, checks-green], description: "pr: the declared PR state to wait for (default merged)." }
+            epicState: { type: string, enum: [merged, done], description: "epic: the declared plan-fanout aggregate state to wait for (default merged) — both mean 'fully merged' (issue #568)." }
         poll:
           type: object
           additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.148.2",
+  "version": "0.149.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",