@nanobpm/nano-workforce 0.149.0 → 0.150.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.150.1](https://github.com/nanobpm/nano-workforce/compare/v0.150.0...v0.150.1) (2026-08-28)
+
+### Bug Fixes
+
+* **startFeature:** thread probePollEvery through the readiness gate ([#579](https://github.com/nanobpm/nano-workforce/issues/579)) ([#582](https://github.com/nanobpm/nano-workforce/issues/582)) ([d8f7739](https://github.com/nanobpm/nano-workforce/commit/d8f773907e1c66292fa6799f70e8d957f6f5f626)), closes [#295](https://github.com/nanobpm/nano-workforce/issues/295)
+
+## [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

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/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/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

@@ -3134,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
@@ -3167,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
@@ -3212,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/operations/startFeature.readiness.integration.test.ts

@@ -0,0 +1,195 @@
+// Integration coverage for the intake READINESS gate (issue #295) driven through the operation EDGE —
+// `startFeature` → `parseFeatureReadiness` → the started run's variables. The unit tests in
+// app/featureReadiness.test.ts already prove the parser derives `probes`/`probeTimeout`/`probePollEvery`
+// correctly in isolation, and app/feature.test.ts proves `startFeature` seeds them onto the run. What
+// nothing asserted — and what regressed in issue #579 — is that the OPERATION threads the parser's
+// output through to `startFeature` intact: a too-narrow local dropped `probePollEvery` on the floor, so
+// every gated start (`blockedOn`/`readiness`) 500'd on startFeature's invariant. This file locks the
+// composed door behaviour: a gated start returns 202 and the run it fans out carries non-blank bounds.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { resetDefaultBranchCache } from "../app/github.ts";
+import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import startFeature from "./startFeature.ts";
+
+// ── in-memory github model (default branch = main, so `confirmDefaultBase` is required) ───────────
+function githubFetch(repo: string) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    const json = (obj: unknown, status = 200) =>
+      new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+    if (method === "GET" && path === `/repos/${repo}`) return Promise.resolve(json({ default_branch: "main" }));
+    const refPrefix = `/repos/${repo}/git/ref/heads/`;
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      if (branch !== "main") return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(json({ ref: `refs/heads/${branch}`, object: { sha: `${branch}-sha` } }));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(repo: string, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "tok";
+  resetDefaultBranchCache();
+  globalThis.fetch = githubFetch(repo) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    resetDefaultBranchCache();
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+}
+
+// ── in-memory app (data + engine) ────────────────────────────────────────────
+// `started` records each engine.createInstance call so a test can assert the run's seeded variables.
+function makeApp() {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  const started: { processDefinitionId?: string; variables?: Record<string, unknown> }[] = [];
+  const table = (name: string, key: string) => {
+    const rows = tables.get(name) ?? (() => {
+      const fresh: Record<string, unknown>[] = [];
+      tables.set(name, fresh);
+      return fresh;
+    })();
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      findOne: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const app = {
+    data: { table: withTrackingViews(table) },
+    engine: {
+      createInstance: (req: { processDefinitionId?: string; variables?: Record<string, unknown> }) => {
+        started.push(req);
+        return Promise.resolve({ processInstanceKey: "PI-F1" });
+      },
+    },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, started };
+}
+
+function input(body: unknown) {
+  return {
+    req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+const REPO = "owner/repo";
+const GATED_BASE = { baseBranch: "main", confirmDefaultBase: true } as const;
+
+// ── the #579 regression: a gated start must reach 202 AND thread the bounds through ───────────────
+
+test("blockedOn gate → 202 and the started run carries non-blank probeTimeout + probePollEvery", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [`${REPO}#578`] }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+    const v = started[0].variables as Record<string, unknown>;
+    // The regressed field: it was dropped by a too-narrow local, so the run seeded a blank cadence and
+    // startFeature's invariant threw → 500. Both bounds must arrive non-blank.
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+    assertEquals(Array.isArray(v.readinessProbes) && (v.readinessProbes as unknown[]).length === 1, true);
+  });
+});
+
+test("explicit readiness descriptor list → 202 with both bounds threaded to the run", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({
+        issue: `${REPO}#577`,
+        ...GATED_BASE,
+        readiness: [{ kind: "command", target: "gh api repos/owner/repo/issues/578 --jq .state", match: { stdoutIncludes: "closed" } }],
+      }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+  });
+});
+
+test("blockedOn + consumerPackage (capability edge) → 202 with both bounds threaded", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [`${REPO}#578`], consumerPackage: "@nanobpm/engine-wasm" }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+    const probes = v.readinessProbes as { kind?: string }[];
+    assertEquals(probes[0]?.kind, "capability");
+  });
+});
+
+// ── regression: an UNGATED start still passes null/absent for both bounds (gate skipped) ──────────
+
+test("no readiness ⇒ 202 and the run seeds null probeTimeout + probePollEvery (gate skipped)", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(input({ issue: `${REPO}#577`, ...GATED_BASE }), app)) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals(v.probeTimeout, null);
+    assertEquals(v.probePollEvery, null);
+    assertEquals(v.readinessProbes, null);
+  });
+});
+
+// ── a malformed gate is a caller-meaningful 400, never a 500 ──────────────────────────────────────
+
+test("malformed readiness descriptor → 400 at the edge (never a 500)", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [""] }),
+      app,
+    )) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+  });
+});

package/operations/startFeature.ts

@@ -13,7 +13,7 @@
 // confirm-default / shared-base rules, with the same typed-error → HTTP mapping.
 
 import { startFeature } from "../app/feature.ts";
-import { parseFeatureReadiness } from "../app/featureReadiness.ts";
+import { type FeatureReadiness, parseFeatureReadiness } from "../app/featureReadiness.ts";
 import { BaseBranchMustExistError } from "../app/github.ts";
 import {
   admitPlan,
@@ -23,7 +23,6 @@ import {
   parseIssue,
   SharedBaseError,
 } from "../app/plan.ts";
-import type { ReadinessProbe } from "../app/readiness.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startFeature", async ({ body }, app) => {
@@ -126,7 +125,12 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // `blockedOn` shorthand (resolved against `consumerPackage`) into the probes + bound the run parks
   // on before implementing. A malformed gate (bad descriptor, unparseable handle, blank package) is a
   // 400 at the edge — it must never wait forever at runtime.
-  let readiness: { probes: ReadinessProbe[]; probeTimeout: string | null };
+  // Type the local as the parser's OWN return type (not a hand-written subset): `parseFeatureReadiness`
+  // derives `probes`, `probeTimeout` AND `probePollEvery` together, and all three must be threaded to
+  // the run. A narrower local silently drops a field the parser produced (issue #579: `probePollEvery`
+  // was dropped, so every gated start 500'd on startFeature's invariant) without TypeScript flagging it,
+  // because the narrower shape is structurally assignable from the wider return.
+  let readiness: FeatureReadiness;
   try {
     readiness = parseFeatureReadiness({
       readiness: "readiness" in body ? body.readiness : undefined,
@@ -138,6 +142,31 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     app.log.warn("start-feature rejected: invalid readiness gate", { message });
     return { status: 400, body: { error: message } };
   }
+  // Validate the gate's timing bounds at the EDGE, before dispatch: a non-empty probe set is
+  // load-bearing together with a non-blank `probeTimeout` (preflight escalation timers + pr.readiness-probe)
+  // and `probePollEvery` (preflight retry cadence). `parseFeatureReadiness` always derives all three
+  // together, so this only fires for a mis-derived/hand-seeded gate — but validating here turns that
+  // into a caller-meaningful 400 rather than a bare-Error 500 from startFeature's internal invariant.
+  if (readiness.probes.length > 0) {
+    const missingBounds: string[] = [];
+    if ((readiness.probeTimeout ?? "").trim() === "") missingBounds.push("a timeout");
+    if ((readiness.probePollEvery ?? "").trim() === "") missingBounds.push("a poll cadence");
+    if (missingBounds.length > 0) {
+      app.log.warn("start-feature rejected: readiness gate missing timing bound", {
+        missing: missingBounds,
+        probes: readiness.probes.length,
+      });
+      return {
+        status: 400,
+        body: {
+          error:
+            `readiness gate is malformed: ${readiness.probes.length} probe(s) but the request did not ` +
+            `resolve to ${missingBounds.join(" and ")}. A gated start (readiness/blockedOn) must resolve ` +
+            `to a non-blank timeout and poll cadence`,
+        },
+      };
+    }
+  }
   const result = await startFeature(
     app.data,
     app.engine,
@@ -146,7 +175,7 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     converge,
     autoMerge,
     customInstructions,
-    { probes: readiness.probes, probeTimeout: readiness.probeTimeout },
+    { probes: readiness.probes, probeTimeout: readiness.probeTimeout, probePollEvery: readiness.probePollEvery },
   );
   app.log.info("feature run started", {
     featureKey: parsed.planKey,

package/package.json

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

package/skills/nano-workforce/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nano-workforce
-description: Drive and debug a running Nano Workforce instance — submit PRs for review convergence, submit issues/epics for plan→implement→converge, submit agent-authored delivery graphs (ADR 0005), answer escalations, and unstick stuck instances. Use when the user asks to operate, drive, submit work to, or debug their Nano Workforce.
+description: Drive and debug a running Nano Workforce instance — submit PRs for review convergence, submit issues/epics for plan→implement→converge, submit agent-authored delivery graphs (ADR 0005), answer escalations, and unstick stuck instances. Prefer the instance's MCP server (add it → its tools appear); fall back to the live operator guide. Use when the user asks to operate, drive, submit work to, or debug their Nano Workforce.
 ---
 
 # Nano Workforce operator skill
@@ -12,27 +12,88 @@ implements → converges** them across a fleet of coding agents, and runs
 DAGs — ADR 0005).
 
 **This skill is a thin bootstrap by design.** It does not describe the endpoints.
-Every running nwf instance serves its own operator guide, *live*, keyed to that
-instance's URLs and matched to its deployed version. Your job is to fetch that
-guide and follow it — never to work from a cached copy, which drifts across
-versions and instances.
+Every running nwf instance is self-describing — over **MCP** where your client
+supports it, and over its **live operator guide** everywhere else. Your job is to
+reach that live surface and follow it, never to work from a cached copy that drifts
+across versions and instances.
+
+There are two paths. **Prefer MCP (§A).** If your client has no MCP support, use the
+fetch-the-live-guide fallback (§B). Both talk to the same app; MCP is a projection of
+the same OpenAPI contract, not a different system (ADR 0067).
+
+## A. Preferred — drive over MCP
+
+The Urban runtime serves a Streamable-HTTP MCP endpoint at **`/app/mcp`** for every
+instance, with **zero app-side MCP code**: the app's operations are projected into
+tools from its OpenAPI spec, alongside a framework-owned engine-debug tool family
+(process instances, wait states, variables, incidents) and the app's projection
+reads. The operator **guide** (the same guide as §B) is itself one of those projected
+tools — `GET /app/api/agent` becomes the `getAgentInstructions` read tool — so the
+workflow knowledge (orient first, preview before dispatch, escalations are for humans)
+is discoverable over the same channel as the drive tools; the runtime additionally
+serves its derived **system brief** as an MCP resource plus an orientation prompt.
+
+**Register one MCP server entry per instance.** Naming the instance
+(`"drive workforce-merlin"`) makes the wrong-instance mistake structurally
+impossible — tool calls are namespaced per server entry. For the Copilot CLI, 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": ["*"]
+    }
+  }
+}
+```
+
+Or from the terminal:
+`copilot mcp add --transport http workforce-local http://localhost:3000/app/mcp`
+(add `--header` for a guarded instance). Claude/Cursor use the same server entries.
+
+Then: start a session, confirm the `workforce-*` tools appear, and ask the agent to
+use a **named** instance (`"Using workforce-local, show what's in flight and any open
+escalations"`). It should call the status operation tool, not curl.
 
-## 1. Confirm which instance you are driving — always
+**Guard posture.** When `NANO_PR_WEBHOOK_SECRET` is **unset**, both reads (status,
+instances, incidents, projections, the operator guide) and mutations (submit work,
+answer escalations, cancel/retry/resolve) work from loopback with no credential. When it
+**is set**, that secret is required as an `x-hook-secret` header on **both reads and
+mutations** — read endpoints like `getAgentInstructions`/`getVersion` also return `401`
+without it — put it in the server entry's `headers`, never in chat. **Operator-only doors stay operator-only:** the delivery-graph
+dispatch/dismiss lifecycle (the human clicking Dispatch *is* the approval, ADR 0005)
+is `x-mcp`-excluded and is **not** a tool — dispatch stays a human action in the
+cockpit.
 
-A user typically runs **several** Nano Workforce instances — e.g. a local dev copy,
-one on the LAN (`http://merlin.local:3000/app/api`), and a public tunnel
-(an ngrok URL) when off the LAN. Every action here is **side-effecting** —
-submitting work, answering escalations, merging PRs — so targeting the wrong
-instance is a real mistake, not a harmless one. **Never silently default to a
-base URL.**
+The full server-entry recipes (multiple instances, Basic-Auth-fronted instances,
+LAN exposure) live in the **agent-configuration runbook** — see the repo README
+("Configure an agent over MCP") and [`docs/mcp-runbook.md`](../../docs/mcp-runbook.md).
 
-### Sources of candidate instances
+## B. Fallback — no MCP client? Fetch the live guide
 
-Gather candidates from, in order:
+Agents without MCP are unchanged: resolve the instance, then fetch and follow its
+live guide.
 
-1. **A named-instance registry** the user maintains — first of these that exists:
-   `$NANO_WORKFORCE_INSTANCES` (JSON object of `name → base URL`), or
-   `~/.config/nano-workforce/instances.json` (same shape). Example:
+### B.1 Confirm which instance you are driving — always
+
+A user typically runs **several** instances — a local dev copy, one on the LAN
+(`http://merlin.local:3000/app/api`), and a public tunnel (ngrok) when off the LAN.
+Every action is **side-effecting**, so targeting the wrong instance is a real
+mistake. **Never silently default to a base URL.** Gather candidates, in order:
+
+1. A named-instance registry the user maintains — first that exists:
+   `$NANO_WORKFORCE_INSTANCES` (JSON `name → base URL`) or
+   `~/.config/nano-workforce/instances.json` (same shape). This is also the source
+   for the per-instance MCP server names in §A. Example:
 
    ```json
    { "local": "http://localhost:3000/app/api",
@@ -40,33 +101,25 @@ Gather candidates from, in order:
      "remote": "https://<subdomain>.ngrok.app/app/api" }
    ```
 
-2. `$NANO_WORKFORCE_URL`, if set (a single default; accept as-is, append `/app/api`
-   only if it is a bare origin).
+2. `$NANO_WORKFORCE_URL`, if set (a single default; append `/app/api` only if it is
+   a bare origin).
 3. Any URL the user names in the conversation.
 4. Local fallback: `http://localhost:3000/app/api` (port `PR_REVIEW_PORT`, default `3000`).
 
-### Choosing
-
-- If the user **named an instance** (by name from the registry, or by URL), use it.
-- Otherwise, **probe the candidates for reachability** and ask the user which to
-  use, offering the candidates as choices and marking which are live. Reachability
-  disambiguates the common case — off the LAN, `merlin.local` won't resolve, so the
-  tunnel instance is the live one:
+If the user named an instance, use it. Otherwise probe candidates for reachability
+and ask which to use, marking which are live:
 
-  ```bash
-  # For each candidate base, a fast liveness + identity check:
-  curl -sS --max-time 3 \
-    ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
-    "$BASE/version" | jq '{appVersion, gitSha, uptimeSeconds}'
-  ```
-
-- Only skip the question when exactly **one** candidate exists and is reachable —
-  and even then, **name the instance you're about to drive** before acting.
+```bash
+curl -sS --max-time 3 \
+  ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
+  "$BASE/version" | jq '{appVersion, gitSha, uptimeSeconds}'
+```
 
-Some instances guard the agent endpoints with a shared secret. If the user has
-`$NANO_PR_WEBHOOK_SECRET` set, send it as `x-hook-secret` on every request below.
+Only skip the question when exactly **one** candidate exists and is reachable — and
+even then, name the instance you're about to drive before acting. If the user has
+`$NANO_PR_WEBHOOK_SECRET` set, send it as `x-hook-secret` on every request.
 
-## 2. Fetch the live guide — this is your real playbook
+### B.2 Fetch the live guide — your real playbook
 
 ```bash
 curl -sS ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"} \
@@ -74,53 +127,47 @@ curl -sS ${NANO_PR_WEBHOOK_SECRET:+-H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET"}
 ```
 
 `GET /app/api/agent` (`getAgentInstructions`) returns
-`{ format, appVersion, generatedAt, baseUrl, engineBase, instructions }`. The
-`instructions` markdown is the authoritative, version-matched operator guide, with
-every example already keyed to this instance's `baseUrl`/`engineBase`. Read it in
-full and follow it for everything that follows — orientation, submitting work,
-answering escalations, and debugging.
-
-**Always re-fetch the guide at the start of a session.** It is the source of truth;
-this skill only tells you how to find it.
-
-## 3. Orient before acting
+`{ format, appVersion, generatedAt, baseUrl, engineBase, instructions }` — the
+authoritative, version-matched operator guide, every example keyed to this
+instance. Read it in full and follow it for orientation, submitting work, answering
+escalations, and debugging. **Re-fetch it at the start of every session.** (This is
+the same prose the `getAgentInstructions` MCP tool serves in §A.)
 
-The guide's first steps confirm what is live and what is in flight:
+### B.3 Orient before acting
 
 ```bash
 curl -sS "$BASE/version" | jq   # app/urban version, git sha, uptime
 curl -sS "$BASE/status"  | jq   # every PR/instance in flight + open escalations
 ```
 
-`/status` is the primary situational-awareness endpoint — check it before you
-submit or unstick anything.
+`/status` is the primary situational-awareness endpoint — check it before you submit
+or unstick anything.
 
-## 4. What you can drive (all detailed in the live guide)
+### B.4 What you can drive (all detailed in the live guide)
 
 - **Submit a PR** for review convergence — `POST $BASE/actions/start/convergence-loop`.
-- **Submit an issue/epic** for plan → implement → converge across the fleet —
-  `POST $BASE/actions/start/plan-fanout`.
-- **Submit a delivery graph** (ADR 0005) — propose → preview → approve → dispatch.
-  Compile/preview is a pure, side-effect-free tool; only the start door dispatches.
-  The live guide documents the exact operations once the instance exposes them.
-- **Answer an escalation** (a durable user task the workforce parked on) —
-  `POST $BASE/actions/complete-user-task`, or the agent hook
-  `POST $BASE/hooks/agent-complete` (`agentCompleteEscalation`).
-- **Debug**: relate an in-flight PR to its engine process instance via `processKey`
-  from `/status`, then use the engine REST base (`engineBase` from the guide) to
-  inspect and unstick it.
+- **Submit an issue/epic** for plan → implement → converge — `POST $BASE/actions/start/plan-fanout`.
+- **Submit a delivery graph** (ADR 0005) — propose → preview → approve → **dispatch**.
+  Compile/preview is a pure, side-effect-free path; **dispatch is an operator action
+  in the cockpit**, not an agent door.
+- **Answer an escalation** — `POST $BASE/actions/complete-user-task`, or the agent
+  hook `POST $BASE/hooks/agent-complete` (`agentCompleteEscalation`).
+- **Debug** — relate an in-flight PR to its engine process instance via `processKey`
+  from `/status`, then inspect and unstick it against the engine REST base
+  (`engineBase` from the guide).
 
 ## Principles
 
-- **Discover, don't declare.** Prefer the live guide and live `/status` over any
-  assumption baked into this file. If this skill and the guide disagree, the guide
-  wins.
-- **Confirm the target instance.** Never run a side-effecting call against an
-  assumed base URL. Know — and when ambiguous, ask — which instance you're driving.
-- **Preview before dispatch.** For delivery graphs and any bulk action, use the
-  pure preview/validate path first and show the user the plan before the
-  side-effecting start call.
-- **Idempotency.** Submissions carry dedupe keys; re-submitting the same work must
-  not double-dispatch. The guide documents the keys — honour them.
-- **Escalations are for humans.** When the workforce parks on a human node, surface
-  it to the user with options; don't silently auto-answer design/product decisions.
+- **Discover, don't declare.** Prefer the live surface (MCP tools including the
+  operator-guide tool, or the live guide and `/status`) over any assumption baked into
+  this file. If this skill and the live surface disagree, the live surface wins.
+- **Confirm the target instance.** Never run a side-effecting call against an assumed
+  base URL. With MCP, name the server entry; with the fallback, know — and when
+  ambiguous, ask — which instance you're driving.
+- **Preview before dispatch.** For delivery graphs and any bulk action, use the pure
+  preview/validate path first and show the user the plan before the side-effecting
+  start. Dispatch itself is the operator's call.
+- **Idempotency.** Submissions carry dedupe keys; re-submitting the same work must not
+  double-dispatch. Honour the keys the guide documents.
+- **Escalations are for humans.** When the workforce parks on a human node, surface it
+  with options; don't silently auto-answer design/product decisions.