@nanobpm/nano-workforce 0.148.2 → 0.150.0

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/docs/mcp-runbook.md

@@ -0,0 +1,133 @@
+# Configure an agent to drive/debug this workforce over MCP
+
+> Adoption of the Urban runtime-served MCP surface ([ADR 0067](https://github.com/nanobpm/nano-ide/blob/main/docs/adr/0067-runtime-served-mcp-surface.md),
+> nano-ide#488) — first consumer, nano-workforce#567. Written against the
+> [Copilot CLI](https://github.com/github/copilot-cli) (the harness nwf's fleet
+> uses). Claude/Cursor equivalents use the same server entries.
+
+The Urban runtime serves a Streamable-HTTP MCP endpoint at **`/app/mcp`** for every
+hosted app and projects this app's `openapi.yaml` into tools — **zero MCP server code
+in nwf**. An MCP-capable agent gets nwf's operations (submit work, answer escalations,
+read status, and the operator **guide** itself — `GET /app/api/agent`, projected as the
+`getAgentInstructions` read tool), the 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 — all
+namespaced per server entry.
+
+This replaces the SKILL.md instance-probing dance for MCP clients: naming the
+instance (`"drive workforce-merlin"`) makes the wrong-instance mistake structurally
+impossible. The named-instance registry (`NANO_WORKFORCE_INSTANCES` /
+`~/.config/nano-workforce/instances.json`) remains the source for the fallback path
+and a handy list of the entries to register here.
+
+MCP is a **third door**, not a replacement: `GET /app/api/agent` (the live guide) and
+`GET /app/api/agent/skill` are unchanged for agents without MCP — see
+[§5 Fallback](#5-fallback).
+
+## 1. One MCP server entry per instance
+
+In `~/.copilot/mcp-config.json` (user-wide) or `.mcp.json` (repo-scoped):
+
+```json
+{
+  "mcpServers": {
+    "workforce-local": {
+      "type": "http",
+      "url": "http://localhost:3000/app/mcp",
+      "tools": ["*"]
+    },
+    "workforce-merlin": {
+      "type": "http",
+      "url": "http://merlin.local:3000/app/mcp",
+      "headers": { "x-hook-secret": "$NANO_PR_WEBHOOK_SECRET" },
+      "tools": ["*"]
+    },
+    "workforce-remote": {
+      "type": "http",
+      "url": "https://<subdomain>.ngrok.app/app/mcp",
+      "headers": { "x-hook-secret": "$NANO_PR_WEBHOOK_SECRET" },
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+Or from the terminal:
+
+```bash
+copilot mcp add --transport http workforce-local http://localhost:3000/app/mcp
+# add --header for a guarded instance:
+copilot mcp add --transport http workforce-merlin http://merlin.local:3000/app/mcp \
+  --header "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"
+```
+
+Tool calls are namespaced per server entry, so the instance you name is the instance
+you drive.
+
+### Instance behind Basic Auth? You need *both* headers
+
+Two different layers. `x-hook-secret` is the **app's own** guard (checked by nwf in
+the operation handler, only when `NANO_PR_WEBHOOK_SECRET` is set). **Basic Auth** is
+enforced by whatever **fronts** the instance (ngrok edge, console proxy) and 401s
+*before* the request ever reaches nwf:
+
+```json
+"headers": {
+  "Authorization": "Basic <base64(user:pass)>",
+  "x-hook-secret": "..."
+}
+```
+
+Generate the blob with `printf '%s' 'user:pass' | base64` — `echo | base64` appends a
+newline and yields the wrong value. The proxy must forward custom headers for
+`x-hook-secret` to survive (most do by default). Base64 is encoding, not encryption:
+only use Basic Auth over HTTPS. The fallback curl path needs both too:
+`curl -u user:pass -H "x-hook-secret: …"`.
+
+## 2. Verify discovery
+
+New agent session → the `workforce-*` tools appear (app operations + the engine-debug
+family). Ask:
+
+> *"Using workforce-local, show what's in flight and any open escalations."*
+
+The agent should call the status operation tool, not curl.
+
+## 3. Debug a wedged instance
+
+> *"workforce-local: PR nanobpm/nano-workforce#123 looks wedged — find its process
+> instance, compare engine truth against the app's projections, and tell me where
+> it's stuck."*
+
+The agent has: instance search, wait states, variables, incidents (engine truth) +
+the `urban_*` projection reads (app belief) + the operator guide (the
+`getAgentInstructions` tool) for the convergence-loop-specific meaning of each wedge
+shape. A wedge is frequently exactly a disagreement between the two planes.
+
+## 4. Guard posture
+
+When `NANO_PR_WEBHOOK_SECRET` is **unset**, both reads (status, instances, incidents,
+projections, the operator guide) and mutations (cancel/retry/resolve, `start/*`
+operations, answering escalations) work from loopback with no credential. When it **is
+set**, the guard is not mutation-only: that secret is required as an `x-hook-secret`
+header on **both reads and mutations** — read endpoints like `GET /app/api/agent` and
+`GET /app/api/version` also return `401` without it. Put it in the server entry's
+`headers`, never in chat. For a remote fleet,
+`NANO_WORKFORCE_BASE_URL` reachability rules apply unchanged, and LAN exposure of
+`/app/mcp` follows the same `network.bind` manifest setting as the rest of the app's
+HTTP surface.
+
+**Operator-only doors stay operator-only.** The staged delivery-graph lifecycle —
+`stageDeliveryGraph`, `dispatchDeliveryGraph`, `dismissProposal` — is `x-mcp`-excluded
+from the projected tool surface (ADR 0067 §2): the human clicking **Dispatch** in the
+cockpit *is* the approval (ADR 0005 Decision 7), so an agent cannot dispatch a delivery
+graph through MCP. Agents author graphs through the pure `compileDeliveryGraph` /
+`previewDeliveryGraph` doors, which stay exposed.
+
+## 5. Fallback
+
+Agents without MCP are unchanged — resolve the instance, then
+`curl -sS $BASE/agent | jq -r .instructions`, or load the
+[`nano-workforce` skill](../skills/nano-workforce/SKILL.md), which fetches the same
+live guide. `GET /app/api/agent` and `GET /app/api/agent/skill` keep working exactly as
+before.

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
@@ -3133,6 +3134,12 @@ paths:
   /actions/delivery-graph/stage:
     post:
       operationId: stageDeliveryGraph
+      # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only cockpit door, kept OFF the
+      # runtime-projected MCP tool surface. The staged-proposal lifecycle (stage -> dispatch ->
+      # dismiss) is the human approval path (ADR 0005 Decision 7 — the operator's click IS the
+      # approval); agents author graphs through the pure compile/preview doors only, never stage.
+      x-mcp:
+        exclude: true
       summary: UI JSON-paste STAGE — parse a pasted delivery-graph JSON string, compile it and stage it for operator dispatch. (ADR 0005 Decision 7 / #460 / #516)
       description: >-
         The human-facing UI JSON-paste STAGE ingress — the deliberate commit half of the preview/stage
@@ -3166,6 +3173,11 @@ paths:
   /actions/delivery-graph/dispatch:
     post:
       operationId: dispatchDeliveryGraph
+      # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): the canonical operator-only door. Dispatch
+      # approval IS a human clicking Dispatch in the cockpit (ADR 0005 Decision 7) — there is no
+      # replayable token and no agent-facing dispatch handle, so it is never a projected MCP tool.
+      x-mcp:
+        exclude: true
       summary: OPERATOR DISPATCH — launch a staged delivery-graph proposal by its digest (idempotent). (ADR 0005 Decision 7 / #460)
       description: >-
         The OPERATOR-ONLY dispatch door (ADR 0005 Decision 7, issue #460). The cockpit's staged-proposals
@@ -3211,6 +3223,11 @@ paths:
   /actions/delivery-graph/dismiss:
     post:
       operationId: dismissProposal
+      # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only cockpit door — discarding a
+      # staged proposal as noise is a human decision in the same approval class as dispatch, so it
+      # stays off the projected MCP tool surface.
+      x-mcp:
+        exclude: true
       summary: OPERATOR DISMISS — discard a staged delivery-graph proposal by its digest as noise (idempotent). (#520)
       description: >-
         The OPERATOR-ONLY dismiss door (#520). The cockpit's staged-proposals grid posts the `digest` of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.148.2",
+  "version": "0.150.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",
@@ -59,7 +59,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.4.0",
-    "@nanobpm/urban": "^0.83.0",
+    "@nanobpm/urban": "^0.86.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {

package/skills/README.md

@@ -7,9 +7,13 @@ loads on demand when its `description` matches the task.
 ## `nano-workforce`
 
 A **thin bootstrap** that teaches any agent to operate a running Nano Workforce
-instance: it resolves the instance base URL and fetches the instance's *live*
-operator guide (`GET /app/api/agent`), then follows it. It deliberately holds no
-endpoint detail of its own — the live, version-matched guide is the source of truth.
+instance. Where the client supports **MCP**, it registers the instance's `/app/mcp`
+server (its tools appear automatically, including the operator guide as the
+`getAgentInstructions` tool — ADR 0067); where
+it does not, it resolves the instance base URL and fetches the instance's *live*
+operator guide (`GET /app/api/agent`), then follows it. Either way it deliberately holds
+no endpoint detail of its own — the live, version-matched surface is the source of truth.
+See [`docs/mcp-runbook.md`](../docs/mcp-runbook.md) for the MCP server-entry recipes.
 
 ### Install