@nanobpm/nano-workforce 0.148.2 → 0.150.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.150.0](https://github.com/nanobpm/nano-workforce/compare/v0.149.0...v0.150.0) (2026-08-28)
+
+### Features
+
+* adopt Urban MCP surface — x-mcp exclusions, runbook, MCP-first skill ([#575](https://github.com/nanobpm/nano-workforce/issues/575)) ([44e89e4](https://github.com/nanobpm/nano-workforce/commit/44e89e40b6cbff0e4c7de32dad76d35f6d534cc6)), closes [nano-ide#488](https://github.com/nanobpm/nano-ide/issues/488) [nano-ide#488](https://github.com/nanobpm/nano-ide/issues/488) [#567](https://github.com/nanobpm/nano-workforce/issues/567) [#567](https://github.com/nanobpm/nano-workforce/issues/567) [nano-ide#488](https://github.com/nanobpm/nano-ide/issues/488)
+
+## [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/README.md

@@ -282,7 +282,7 @@ agent at that URL to author, compile, and submit a graph unaided. See
 | `NANO_PR_GITHUB_TRANSPORT` | `auto` | how the poller reads GitHub: `gh` (host CLI), `token` (`GITHUB_TOKEN` over HTTP), or `auto` |
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
 | `NANO_PR_MAX_ROUNDS` | `20` | default cap: escalate after N rounds (per-submit override via the form / the `maxRounds` field on `start/convergence-loop`; clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`X-Hook-Secret`) for guarded operations (e.g. `POST /app/api/agent`, `/app/api/version`, `/app/api/status`); unset = open |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`x-hook-secret`) for guarded operations (e.g. `GET /app/api/agent`, `/app/api/version`, `/app/api/status`); unset = open |
 | `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only). Per-submit override via the `convergeOnly` field on `start/convergence-loop` (`true` forces review-only for that PR) |
 | `NANO_PR_MERGE_METHOD` | `squash` | merge method: `squash`, `merge`, or `rebase` |
 | `NANO_PR_MERGE_ADMIN` | `0` | pass `--admin` to override failing non-required checks (use with care) |
@@ -452,9 +452,42 @@ curl -sS http://localhost:3000/app/api/agent | jq -r .instructions
 ```
 
 Like `/version` and `/status`, this endpoint honours the optional
-`NANO_PR_WEBHOOK_SECRET` guard (`X-Hook-Secret` header): when that secret is set it
+`NANO_PR_WEBHOOK_SECRET` guard (`x-hook-secret` header): when that secret is set it
 returns `401` without the matching header; unset = open. The source lives in
-`resources/agent-guide.md`.
+`docs/agent-guide.md`.
+
+### Configure an agent over MCP
+
+Where your agent supports **MCP**, prefer it over the curl path above. The Urban
+runtime serves a Streamable-HTTP MCP endpoint at **`/app/mcp`** for every instance and
+projects this app's `openapi.yaml` into tools with **zero MCP code in nwf** — the app
+operations (including the operator guide, projected from `GET /app/api/agent` as the
+`getAgentInstructions` read tool), a framework-owned engine-debug tool family (process
+instances, wait states, variables, incidents), the `urban_*` projection reads, and the
+runtime's derived **system brief** as an MCP resource plus an orientation prompt
+(ADR 0067, nano-ide#488). Register one server entry per instance and name
+it when you drive — tool calls are namespaced per entry, so the wrong-instance mistake
+becomes impossible:
+
+```bash
+copilot mcp add --transport http workforce-local http://localhost:3000/app/mcp
+# guarded instance: add the app secret as a header (never in chat)
+copilot mcp add --transport http workforce-merlin http://merlin.local:3000/app/mcp \
+  --header "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"
+```
+
+When `NANO_PR_WEBHOOK_SECRET` is unset, reads and mutations both work from loopback with
+no credential; when it is set, that secret is required as an `x-hook-secret` header on
+**both** — read endpoints like `GET /app/api/agent` and `GET /app/api/version` also
+return `401` without it. **Operator-only doors stay operator-only** —
+delivery-graph **dispatch** (and the stage/dismiss lifecycle) is `x-mcp`-excluded, so the
+human clicking Dispatch in the cockpit remains the approval (ADR 0005). MCP is a **third
+door**: `GET /app/api/agent` and `GET /app/api/agent/skill` are unchanged for agents
+without it.
+
+The full recipe — multiple instances, Basic-Auth-fronted instances, LAN exposure,
+verification and wedged-instance debugging prompts — is the **agent-configuration
+runbook**: [`docs/mcp-runbook.md`](docs/mcp-runbook.md).
 
 ---
 

package/SPEC.md

@@ -492,7 +492,7 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `GITHUB_TOKEN` | — | GitHub API (poller + agent) |
 | `NANO_PR_POLL_MS` | 60000 | poll interval |
 | `NANO_PR_MAX_ROUNDS` | 20 | default round cap (per-submit `maxRounds` override, clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`X-Hook-Secret`) for guarded operations (e.g. `/app/api/agent`, `/app/api/version`, `/app/api/status`) |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`x-hook-secret`) for guarded operations (e.g. `/app/api/agent`, `/app/api/version`, `/app/api/status`) |
 | `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `convergeOnly: true` override) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |

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/mcpExclusions.test.ts

@@ -0,0 +1,83 @@
+// Authoring guard for the `x-mcp` MCP tool-exclusion switch (ADR 0067 §2, nano-ide#488 slice 3;
+// adopted here as slice 4, issue #567).
+//
+// The runtime-served MCP surface (`/app/mcp`) projects every non-excluded `openapi.yaml` operation
+// into an MCP tool. An operation opts OUT with the `x-mcp` extension — `x-mcp: false` or
+// `x-mcp: { exclude: true }`; any other value (or its absence) leaves it exposed. That switch is
+// security-relevant: it is the one authoring control that keeps an operator-only door off the
+// agent-facing tool surface, so this test pins the intended exclusion set at the spec level.
+//
+// Derivation over duplication (AGENTS.md): we do NOT re-implement the exclusion rule or the
+// path×method walk. We read the projection from the SAME `@nanobpm/urban` walker the runtime MCP
+// module builds its live tool list from — `parseSpec` + `collectOperations`, whose `mcpExcluded`
+// flag IS `isMcpExcluded` applied at parse time (openapi/spec.ts). This app-side test is therefore
+// the authoring assertion that OUR operator doors carry the switch and that no agent-facing
+// operation was excluded by accident, checked against the exact rule the runtime honours — no
+// second source of truth to drift from it.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { collectOperations, parseSpec } from "@nanobpm/urban/toolkit";
+import { assert, assertEquals } from "#test-assert";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SPEC_PATH = join(REPO_ROOT, "openapi.yaml");
+
+// Every operation the runtime projection enumerates, with its `x-mcp` exclusion flag — read from
+// the framework walker so this test and the live tool surface can never diverge.
+function projectedOperations() {
+  return collectOperations(parseSpec(readFileSync(SPEC_PATH, "utf8")));
+}
+
+// The operator-only cockpit doors: the staged delivery-graph lifecycle (stage -> dispatch ->
+// dismiss) whose approval is a human click in the cockpit (ADR 0005 Decision 7). These — and ONLY
+// these — must be excluded from the projected MCP tool surface.
+const EXPECTED_EXCLUDED = ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal"];
+
+// A representative set of agent-facing operations that MUST stay exposed as tools — the drive doors
+// (submit PR / epic / delivery-graph set), the pure compile/preview doors, and the read/orientation
+// surface an agent debugging a wedged instance relies on.
+const EXPECTED_EXPOSED = [
+  "startConvergenceLoop",
+  "startPlanFanout",
+  "startEpicSet",
+  "compileDeliveryGraph",
+  "previewDeliveryGraph",
+  "listStagedProposals",
+  "listActivePrs",
+  "getAgentInstructions",
+  "getVersion",
+];
+
+test("x-mcp excludes exactly the operator-only delivery-graph lifecycle doors", () => {
+  const excluded = projectedOperations()
+    .filter((op) => op.mcpExcluded)
+    .map((op) => op.operationId)
+    .sort();
+  assertEquals(excluded, [...EXPECTED_EXCLUDED].sort());
+});
+
+test("x-mcp leaves the agent-facing drive/preview/read operations exposed", () => {
+  const byId = new Map(projectedOperations().map((op) => [op.operationId, op]));
+  for (const id of EXPECTED_EXPOSED) {
+    const op = byId.get(id);
+    assert(op, `expected operation ${id} to exist in openapi.yaml`);
+    assertEquals(op.mcpExcluded, false, `operation ${id} must NOT be x-mcp excluded`);
+  }
+});
+
+// The operator guide (workflow knowledge) is discoverable over MCP as the projected
+// `getAgentInstructions` READ tool — a safe GET, so the runtime projects it as a read tool
+// (not `x-mcp`-excluded) on loopback, instance-keyed by the same `resolveApiBase` rewriting
+// as its HTTP route. ("Read tool" describes the projected verb, not an auth posture: the
+// route still honours the app's optional `x-hook-secret` guard when `NANO_PR_WEBHOOK_SECRET`
+// is set.) This is how the guide's prose reaches an MCP agent; the framework separately
+// serves its derived system brief as a resource. Pin the projection facts so an accidental
+// exclusion (or a verb change that would flip it into a mutation) fails CI.
+test("the operator guide is projected as a read tool (GET, not x-mcp excluded) over MCP", () => {
+  const op = projectedOperations().find((o) => o.operationId === "getAgentInstructions");
+  assert(op, "getAgentInstructions must exist in openapi.yaml");
+  assertEquals(op.mcpExcluded, false, "the operator guide must stay exposed over MCP");
+  assertEquals(op.method, "get", "the operator guide must be a safe GET so it projects as a read tool");
+});

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 {