@nanobpm/nano-workforce 0.158.1 → 0.159.1

package/.github/workflows/ci.yml

@@ -72,6 +72,14 @@ jobs:
       - name: Check contract registry (no synonyms / undeclared keys)
         run: npm run check:contracts
 
+      # MCP tool-schema gate (epic #605, S0): every projected (non-`x-mcp`) request-body operation
+      # must carry a self-contained, `$ref`-free inline `body` schema — the runtime projector copies
+      # it VERBATIM into the tool `inputSchema`, so a leaked `$ref` is unresolvable in a standard MCP
+      # client (nano-ide#502). The inline bodies are DERIVED from `components.schemas` by
+      # scripts/inline-mcp-bodies.ts; this fails if a source component changed without regenerating.
+      - name: Check MCP tool-body schemas (inline, $ref-free)
+        run: npm run check:mcp-bodies
+
       # Runs the full *.test.ts suite under Node's built-in test runner (node:test), which strips
       # TypeScript types on the fly (Node >= 22.6) — no build step.
       - name: Test (Node)

package/.github/workflows/invariants.yml

@@ -77,6 +77,13 @@ jobs:
       - name: Check navigation index freshness
         run: npm run sync:nav:check
 
+      # Projected MCP tool bodies (openapi.yaml) are a checked-in derived artifact too (epic #605 S0):
+      # each is DERIVED from `components.schemas` by scripts/inline-mcp-bodies.ts. Two branches can
+      # each edit a source component and its inline body in isolation yet leave the merged tree stale;
+      # re-assert freshness on the merged tree so a $ref cannot silently re-leak into the tool surface.
+      - name: Check MCP tool-body schemas freshness
+        run: npm run check:mcp-bodies
+
       # Backstop: catch ANY other committed generated file that the merged sources render stale, even
       # one without its own `--check` script above. A clean tree is the whole-repo invariant.
       - name: No stale committed artifacts on the merged tree

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.159.1](https://github.com/nanobpm/nano-workforce/compare/v0.159.0...v0.159.1) (2026-08-29)
+
+### Bug Fixes
+
+* **delivery-graph:** read-after-write consistency for listStagedProposals (S2) ([#617](https://github.com/nanobpm/nano-workforce/issues/617)) ([bd0246c](https://github.com/nanobpm/nano-workforce/commit/bd0246cc81241041320aa483b0a0789f5e372031)), closes [#608](https://github.com/nanobpm/nano-workforce/issues/608)
+
+## [0.159.0](https://github.com/nanobpm/nano-workforce/compare/v0.158.1...v0.159.0) (2026-08-29)
+
+### Features
+
+* **openapi:** self-contained, $ref-free projected MCP tool schemas (S0) ([#614](https://github.com/nanobpm/nano-workforce/issues/614)) ([2018020](https://github.com/nanobpm/nano-workforce/commit/2018020a290c2f416e703e3584b27f92ccf27753)), closes [#605](https://github.com/nanobpm/nano-workforce/issues/605) [nano-ide#501](https://github.com/nanobpm/nano-ide/issues/501) [503/#504](https://github.com/503/nano-workforce/issues/504) [#606](https://github.com/nanobpm/nano-workforce/issues/606)
+
 ## [0.158.1](https://github.com/nanobpm/nano-workforce/compare/v0.158.0...v0.158.1) (2026-08-29)
 
 ### Bug Fixes

package/app/deliveryGraphProposals.test.ts

@@ -15,6 +15,7 @@ import {
   DELIVERY_PROPOSAL_TTL_MS,
   deliveryGraphProposals,
   getStagedProposal,
+  isLiveStaged,
   isProposalExpired,
   markProposalDismissed,
   markProposalDispatched,
@@ -82,6 +83,21 @@ test("isProposalExpired: past → true, future → false, blank/corrupt → true
   assertEquals(isProposalExpired("garbage", at), true);
 });
 
+test("isLiveStaged: the ONE liveness predicate — only a `staged`, not-yet-expired row is live (#608)", () => {
+  const at = new Date("2024-06-01T00:00:00.000Z");
+  const live = row({ createdAt: "2024-05-31T23:00:00.000Z" }); // staged, TTL a day out → live
+  assertEquals(isLiveStaged(live, at), true);
+  // A future-created staged row is trivially live too (TTL further out).
+  assertEquals(isLiveStaged(row(), new Date()), true);
+  // Every non-`staged` status is NOT live, regardless of TTL.
+  for (const status of ["superseded", "dispatched", "expired", "dismissed"] as const) {
+    assertEquals(isLiveStaged({ ...live, status }, at), false);
+  }
+  // A `staged` row whose TTL has elapsed is NOT live (mirrors isProposalExpired, fail-closed).
+  assertEquals(isLiveStaged({ ...live, expires_at: "2024-05-30T00:00:00.000Z" }, at), false);
+  assertEquals(isLiveStaged({ ...live, expires_at: "" }, at), false);
+});
+
 test("proposalReviewUrl: a navigational deep-link to the cockpit page — NOT a dispatch endpoint", () => {
   const url = proposalReviewUrl("abc123", "https://cockpit.example");
   assertEquals(url, "https://cockpit.example/app/pages/delivery-graphs#proposal-abc123");

package/app/deliveryGraphProposals.ts

@@ -207,9 +207,25 @@ export async function stageProposal(data: DataLayer, row: DeliveryGraphProposal)
   return toWrite;
 }
 
-/** Load a proposal that is live and dispatchable RIGHT NOW: it exists, is `staged` (not superseded or
- * already dispatched), and has not aged out of its TTL. Returns null otherwise, so the cockpit
- * dispatch action refuses a stale/unknown/already-dispatched digest cleanly. */
+/** The ONE definition of "a live, dispatchable-RIGHT-NOW staged proposal" (issue #608): the row is
+ * `staged` (not superseded / dispatched / expired / dismissed) AND has not aged out of its TTL. This is
+ * the SINGLE SOURCE OF TRUTH the digest read (`getStagedProposal`), the list read
+ * (`listStagedProposals`), and — through them — the cockpit App-View, the dispatch/preview/dismiss
+ * doors, and the MCP `listStagedProposals` tool all resolve liveness through, so no two readers can ever
+ * drift on which rows are live (AGENTS.md "Derivation over duplication"). A read-after-write from
+ * `compileDeliveryGraph` is trustworthy because this predicate is evaluated over the SAME durable
+ * `delivery_graph_proposals` store the compile door commits the row to (the app's single default
+ * `app.data` source) — a freshly staged row (`status: 'staged'`, `expires_at` a full TTL in the future)
+ * is live by construction, with no projection/read-model between the write and the read to lag behind. */
+export function isLiveStaged(row: DeliveryGraphProposal, at: Date = new Date()): boolean {
+  return row.status === "staged" && !isProposalExpired(row.expires_at, at);
+}
+
+/** Load a proposal that is live and dispatchable RIGHT NOW: it exists and satisfies {@link isLiveStaged}
+ * (it is `staged` — not superseded or already dispatched — and has not aged out of its TTL). Returns
+ * null otherwise, so the cockpit dispatch action refuses a stale/unknown/already-dispatched digest
+ * cleanly. Reads the authoritative `delivery_graph_proposals` row by primary key from the same
+ * `app.data` store the compile door stages into — a read-your-writes lookup, no read-model in between. */
 export async function getStagedProposal(
   data: DataLayer,
   digest: string,
@@ -217,24 +233,28 @@ export async function getStagedProposal(
 ): Promise<DeliveryGraphProposal | null> {
   const row = await deliveryGraphProposals(data).get(digest);
   if (!row) return null;
-  if (row.status !== "staged") return null;
-  if (isProposalExpired(row.expires_at, at)) return null;
-  return row;
+  return isLiveStaged(row, at) ? row : null;
 }
 
-/** Every LIVE staged proposal — `status = 'staged'` AND not aged out of its TTL — newest first. The
- * staged App-View (`pages/delivery-graphs/staged.mount.js`) polls this to render the Preview-DI +
- * Dispatch list. Mirrors `getStagedProposal`'s freshness guard (`isProposalExpired`) so an
- * expired-but-not-yet-swept row is never offered for preview/dispatch, unlike a raw
- * `status = 'staged'` datasource filter which cannot express a `expires_at > now` cutoff and so lingers
- * an aged-out row until the sweep realises the TTL. Read-only; no write. */
+/** Every LIVE staged proposal — {@link isLiveStaged} (`status = 'staged'` AND not aged out of its TTL) —
+ * newest first. The staged App-View (`pages/delivery-graphs/staged.mount.js`) and the MCP
+ * `listStagedProposals` tool both poll THIS door to render/answer the Preview-DI + Dispatch list.
+ *
+ * READ-AFTER-WRITE GUARANTEE (issue #608). The list is served by a fresh query against the authoritative
+ * `delivery_graph_proposals` table on the app's single default `app.data` source — the SAME store, in
+ * the SAME scope, the `compileDeliveryGraph`/`stageProposal` write commits to. There is no
+ * projection/read-model or cache between the write and this read, so a digest `compileDeliveryGraph`
+ * just returned is listed on the very next call with NO intervening delay (the write is committed before
+ * the compile door responds). Liveness is decided by the shared {@link isLiveStaged} predicate — NOT a
+ * second `status = 'staged'` datasource filter, which cannot express an `expires_at > now` cutoff and so
+ * would linger an aged-out row until the poller's sweep realises the TTL. Read-only; no write. */
 export async function listStagedProposals(
   data: DataLayer,
   at: Date = new Date(),
 ): Promise<DeliveryGraphProposal[]> {
   const rows = await deliveryGraphProposals(data).find({ status: "staged" });
   return rows
-    .filter((row) => !isProposalExpired(row.expires_at, at))
+    .filter((row) => isLiveStaged(row, at))
     .sort((a, b) => b.created_at.localeCompare(a.created_at));
 }
 

package/docs/mcp-runbook.md

@@ -124,6 +124,24 @@ cockpit *is* the approval (ADR 0005 Decision 7), so an agent cannot dispatch a d
 graph through MCP. Agents author graphs through the pure `compileDeliveryGraph` /
 `previewDeliveryGraph` doors, which stay exposed.
 
+**Projected tool schemas are self-contained (epic #605, S0).** The projector copies each
+operation's request-body schema *verbatim* into the tool's `inputSchema.properties.body`
+and does **not** resolve `$ref`s, so every projected (non-`x-mcp`) request-body operation
+in `openapi.yaml` presents an inline `type: object` body with no `$ref`; the two graph doors
+additionally carry a worked `example` — an agent discovers the body shape (and calls the tool
+with a real object, not a
+stringified one) from the surface alone. The two graph doors split by convention:
+`compileDeliveryGraph` takes the **structured `DeliveryGraph` object** (and *stages*);
+`previewDeliveryGraph` takes the **text shape `{ "graphJson": "<serialized DeliveryGraph>" }`**
+(and is *pure*). Every validation failure returns `issues`/`errors` as `[{ path, message }]`.
+The inline bodies are **derived** from `components.schemas` by
+`scripts/inline-mcp-bodies.ts` (single source of truth; run `npm run gen:mcp-bodies` after
+editing a component), and `npm run check:mcp-bodies` + `test/mcp-tool-schemas.test.ts` (which
+runs the real projector) fail CI if a `$ref` ever re-leaks. The upstream projector fix that
+would make this mitigation unnecessary is tracked in
+[nano-ide#501](https://github.com/nanobpm/nano-ide/issues/501) (#502 self-contained schemas,
+#503 faithful object-body transport, #504 real-spec conformance guard).
+
 ## 5. Fallback
 
 Agents without MCP are unchanged — resolve the instance, then
@@ -131,3 +149,31 @@ Agents without MCP are unchanged — resolve the instance, then
 [`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.
+
+## 6. Regression harness — pin the MCP surface from nwf's side
+
+The MCP projection layer (schema shape, argument encoding, session handshake) is
+covered end-to-end by a reusable e2e harness (epic #605 slice S1, issue #607):
+`e2e/support/mcp-harness.ts`. It boots a hermetic in-process instance and drives
+the **real** `/app/mcp` endpoint over the full Streamable-HTTP client handshake —
+`initialize` → capture `Mcp-Session-Id` → `notifications/initialized` →
+`tools/list` → `tools/call` — asserting the client-visible contract every agent
+depends on:
+
+- every projected tool schema is `$ref`-free with an explicit `type` (a leaked
+  `$ref` is unresolvable in the MCP context);
+- an object argument arrives **as an object**, never coerced to a string;
+- validation failures answer uniformly with `issues[{path,message}]`;
+- side-effecting calls stage nothing, so the suite is safe to re-run.
+
+It runs in CI under `npm run e2e` (hermetic — no socket, no GitHub), so a
+reintroduced `$ref` or a stringified object body fails the build instead of
+reaching an agent.
+
+**Extending it (new per-tool case).** Import `bootMcpHarness` from
+`e2e/support/mcp-harness.ts` in your own `e2e/<slice>.e2e.ts` and drive
+`harness.listTools()` / `harness.callTool(name, args)` — the handshake, session
+management and teardown are owned by the harness, so you add a `test(...)`, never
+a second transport. The module header documents the seam and the exported
+assertion helpers (`assertSchemaSelfContained`, `assertObjectBodyAccepted`,
+`assertValidationIssues`) in full; `e2e/mcp-surface.e2e.ts` is the worked example.

package/e2e/delivery-graph-read-after-write.e2e.ts

@@ -0,0 +1,132 @@
+// Delivery-graph read-after-write regression net (epic #605 slice S2, issue #608).
+//
+// PINS the acceptance guarantee: immediately after `compileDeliveryGraph` returns a staged `digest`,
+// `listStagedProposals` returns THAT digest — with NO intervening delay. In the evidence session
+// (issue #608) a `compileDeliveryGraph` that returned `status:"ready"` with `digest:"ca8fb90a1b0c"`
+// was followed by a `listStagedProposals` that answered `{"count":0,"proposals":[]}` — the read and
+// the write had disagreed, so an agent could not confirm its own staging. The fix serves both from a
+// single source of truth: the read (`listStagedProposals` / `getStagedProposal`, unified through the
+// one `isLiveStaged` predicate) queries the SAME `delivery_graph_proposals` store, in the SAME scope,
+// that the compile/stage write commits to — no read-model or cache in between.
+//
+// This case is RUNNABLE VIA THE SLICE S1 HARNESS (`e2e/support/mcp-harness.ts`): it imports
+// `bootMcpHarness` and drives the REAL runtime-served `/app/mcp` surface over the client handshake —
+// the exact transport an agent uses — so a regression that reintroduces the disagreement (a lagging
+// projection, a divergent read filter, a supersede that drops the just-written row) fails the build.
+// It does NOT re-implement the handshake (see the harness module header's EXTENSION SEAM).
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import { assertObjectBodyAccepted, bootMcpHarness, type McpHarness } from "./support/mcp-harness.ts";
+
+/** A minimal side-effecting graph — `compileDeliveryGraph` STAGES it (unlike the pure `previewDelivery
+ *  Graph`), which is exactly the write whose visibility we verify. Two agent nodes → two side effects. */
+const STAGES_A_PROPOSAL = {
+  name: "S2 read-after-write A",
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [{ from: "open", to: "cut" }],
+};
+
+/** A dedicated logical key for the supersede test, distinct from the first test's key so the case is
+ *  SELF-CONTAINED — it stages BOTH its own V1 and V2 in-test and asserts per-logical-key, rather than
+ *  depending on an earlier test having staged a predecessor. */
+const SUPERSEDE_KEY = "S2 supersede key";
+
+/** V1 for the supersede test — the predecessor that staging V2 must retire. */
+const SUPERSEDE_V1 = {
+  name: SUPERSEDE_KEY,
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [{ from: "open", to: "cut" }],
+};
+
+/** V2 — a STRUCTURALLY different graph (an extra node → different compiled BPMN → different content
+ *  digest) sharing the SAME `name` (logical key) as V1, so staging it supersedes V1. The read after it
+ *  must show the SECOND digest (the one the compile just returned), never the superseded first. */
+const SUPERSEDE_V2 = {
+  name: SUPERSEDE_KEY,
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "un-draft + merge #B" } },
+    { id: "notes", kind: "agent", agent: { jobType: "senior:demo", prompt: "draft the release notes" } },
+    { id: "cut", kind: "agent", agent: { jobType: "senior:demo", prompt: "cut the release" } },
+  ],
+  edges: [
+    { from: "open", to: "notes" },
+    { from: "notes", to: "cut" },
+  ],
+};
+
+interface StagedRow { digest: string; title: string | null }
+interface ListBody { count: number; proposals: StagedRow[] }
+
+/** Compile a graph over MCP and return the staged digest the door reports (asserting it staged). */
+async function compileAndStage(h: McpHarness, graph: unknown): Promise<string> {
+  const res = await h.callTool("compileDeliveryGraph", { body: graph });
+  assertObjectBodyAccepted(res, "compileDeliveryGraph"); // the object body was NOT stringified
+  assert.ok(!res.isError, `compileDeliveryGraph must stage a valid graph: ${res.text}`);
+  const json = res.json as { status?: string; digest?: string } | undefined;
+  assert.equal(json?.status, "ready", `compileDeliveryGraph must report status:"ready": ${res.text}`);
+  assert.ok(typeof json?.digest === "string" && json.digest.length > 0, `a staged digest is required: ${res.text}`);
+  return json.digest;
+}
+
+/** The current live staged list, read over the SAME MCP surface. */
+async function listStaged(h: McpHarness): Promise<ListBody> {
+  const res = await h.callTool("listStagedProposals", {});
+  assert.ok(!res.isError, `listStagedProposals must not error: ${res.text}`);
+  const json = res.json as ListBody | undefined;
+  assert.ok(json && Array.isArray(json.proposals), `listStagedProposals must return a proposals array: ${res.text}`);
+  return json;
+}
+
+describe("S2 — listStagedProposals read-after-write is trustworthy (#608)", () => {
+  let h: McpHarness;
+  before(async () => { h = await bootMcpHarness(); });
+  after(async () => { await h.stop(); });
+
+  test("a digest compileDeliveryGraph just returned is listed on the very next call — no delay", async () => {
+    const digest = await compileAndStage(h, STAGES_A_PROPOSAL);
+    // The immediate read — no sleep, no retry, no poll — must show the write.
+    const list = await listStaged(h);
+    const digests = list.proposals.map((p) => p.digest);
+    assert.ok(
+      digests.includes(digest),
+      `the digest ${digest} compileDeliveryGraph just returned must appear in listStagedProposals ` +
+        `immediately (got ${JSON.stringify(digests)})`,
+    );
+  });
+
+  test("supersede keeps read-after-write honest: the read shows the LATEST returned digest, not the superseded one", async () => {
+    // SELF-CONTAINED: stage V1 then V2 for the SAME logical key inside this test — V2 supersedes V1. The
+    // read must reflect the digest THIS compile returned (the live one) and the superseded predecessor
+    // must be gone, with no dependence on any other test having staged first.
+    const digestV1 = await compileAndStage(h, SUPERSEDE_V1);
+    const digestV2 = await compileAndStage(h, SUPERSEDE_V2);
+    assert.notEqual(digestV1, digestV2, "V1 and V2 must differ in content so V2 genuinely supersedes V1");
+    const list = await listStaged(h);
+    const digests = list.proposals.map((p) => p.digest);
+    assert.ok(
+      digests.includes(digestV2),
+      `after superseding, listStagedProposals must show the latest digest ${digestV2} (got ${JSON.stringify(digests)})`,
+    );
+    assert.ok(
+      !digests.includes(digestV1),
+      `the superseded predecessor digest ${digestV1} must be gone from listStagedProposals (got ${JSON.stringify(digests)})`,
+    );
+    // Exactly one live proposal FOR THIS logical key — filter by title so the assertion is per-logical-key
+    // and does not couple to how many other proposals exist in the shared store.
+    const forLogicalKey = list.proposals.filter((p) => p.title === SUPERSEDE_KEY);
+    assert.equal(
+      forLogicalKey.length,
+      1,
+      `exactly one live staged proposal must remain for the logical key ${JSON.stringify(SUPERSEDE_KEY)} (got ${JSON.stringify(forLogicalKey.map((p) => p.digest))})`,
+    );
+    assert.equal(forLogicalKey[0]?.digest, digestV2, "the sole remaining live proposal must be the latest digest");
+  });
+});

package/e2e/mcp-surface.e2e.ts

@@ -0,0 +1,235 @@
+// MCP surface end-to-end regression net (epic #605 slice S1, issue #607).
+//
+// Drives the app's REAL runtime-served MCP endpoint (`/app/mcp`, ADR 0067) over the full
+// Streamable-HTTP client handshake — `initialize` → `Mcp-Session-Id` → `notifications/initialized`
+// → `tools/list` → `tools/call` — against a hermetic in-process instance, via the reusable
+// `e2e/support/mcp-harness.ts` module. It PINS the client-visible contract the S0 defect broke:
+//
+//   • every projected tool schema is `$ref`-free with an explicit `type` (S0 / nano-ide#502);
+//   • an object argument arrives AS AN OBJECT, never coerced to a string (S0 / nano-ide#503);
+//   • validation failures answer uniformly with `issues[{path,message}]`;
+//   • the reads parse; the mutating framework tools are gated; side-effecting calls leave NO live
+//     staged proposal behind (safe to run repeatedly).
+//
+// It is the harness siblings extend: S2 (#608), S4 (#610) and S5 (#611) add their own per-tool case
+// by importing `bootMcpHarness` — they do NOT re-implement the handshake. See the module header of
+// `support/mcp-harness.ts` for the extension seam.
+//
+// Run with `npm run e2e`.
+import assert from "node:assert/strict";
+import { after, before, describe, test } from "node:test";
+import {
+  assertObjectBodyAccepted,
+  assertSchemaSelfContained,
+  assertValidationIssues,
+  bootMcpHarness,
+  type McpHarness,
+  type McpTool,
+  MINIMAL_VALID_GRAPH,
+  schemaHasRef,
+  STRINGIFIED_BODY_MESSAGE,
+} from "./support/mcp-harness.ts";
+
+// The read tools the surface must expose and answer (issue #607 scope). Each is safe and repeatable.
+const READ_TOOLS = [
+  "getVersion",
+  "getAgentInstructions",
+  "listActivePrs",
+  "listStagedProposals",
+  "getLineage",
+] as const;
+
+// The object-body doors covered by a `tools/call` (issue #607 scope). `previewDeliveryGraph` is the
+// PURE positive proof (a valid graph, nothing staged). The rest are side-EFFECTING (they stage a
+// proposal or start a process on a VALID body), so the harness drives them with a deliberately
+// INVALID — but object-shaped — body: validation rejects it, which (a) proves the object argument
+// reached the door AS AN OBJECT and (b) persists nothing, keeping the harness repeatable.
+const OBJECT_BODY_DOORS = [
+  "compileDeliveryGraph",
+  "startConvergenceLoop",
+  "startPlanFanout",
+  "startEpicSet",
+  "startFeature",
+  "agentCompleteEscalation",
+  "appendBlackboard",
+] as const;
+
+// S0-PENDING self-containment allowlist (issue #606 / upstream nano-ide#502).
+// --------------------------------------------------------------------------
+// S1 (this harness) and S0 (openapi.yaml restructuring) are the two WAVE-0 scaffold slices and land
+// in parallel — so this test must be GREEN on `main` whether or not S0 has merged yet. On the
+// pre-S0 spec these object-body tools still project a leaked `$ref` (`body: { $ref: <component> }`);
+// S0 inlines them. For each, the audit tolerates EITHER the self-contained shape (post-S0) OR
+// EXACTLY the one known pre-S0 `$ref` (this map's value) — and FAILS on any OTHER `$ref` shape (a
+// novel leak, a wrong target). Once S0 lands, delete the graduated entries here so they fall under
+// the hard self-containment assertion like every other tool. A tool NOT in this map is hard-asserted
+// self-contained NOW — so reintroducing a `$ref` into any clean tool (or a sibling's NEW tool) fails
+// the build immediately.
+const KNOWN_PENDING_S0: Readonly<Record<string, string>> = {
+  compileDeliveryGraph: "#/components/schemas/DeliveryGraph",
+  previewDeliveryGraph: "#/components/schemas/DeliveryGraphPreviewSubmit",
+  startConvergenceLoop: "#/components/schemas/ConvergenceStart",
+  startPlanFanout: "#/components/schemas/PlanStart",
+  startEpicSet: "#/components/schemas/EpicSetStart",
+  startFeature: "#/components/schemas/FeatureStart",
+  agentCompleteEscalation: "#/components/schemas/AgentCompleteRequest",
+  appendBlackboard: "#/components/schemas/BlackboardAppendRequest",
+  saveToLibrary: "#/components/schemas/SaveToLibrarySubmit",
+  importToLibrary: "#/components/schemas/ImportToLibrarySubmit",
+  previewProposalBpmn: "#/components/schemas/DeliveryGraphProposalBpmnRequest",
+  enrolAgenticWorker: "#/components/schemas/EnrolRequest",
+  revertEscalationCompletion: "#/components/schemas/RevertCompletionRequest",
+};
+
+/** Collect every `$ref` string anywhere in a parsed JSON Schema. */
+function collectRefs(schema: unknown, acc: string[] = []): string[] {
+  if (Array.isArray(schema)) {
+    for (const item of schema) collectRefs(item, acc);
+  } else if (schema && typeof schema === "object") {
+    for (const [key, value] of Object.entries(schema as Record<string, unknown>)) {
+      if (key === "$ref" && typeof value === "string") acc.push(value);
+      else collectRefs(value, acc);
+    }
+  }
+  return acc;
+}
+
+/** Audit one tool's projected schema against the S0 self-containment contract, tolerating exactly
+ *  the one documented pre-S0 leak for a {@link KNOWN_PENDING_S0} tool (see that map's comment). */
+function auditToolSchema(tool: McpTool): void {
+  const pendingRef = KNOWN_PENDING_S0[tool.name];
+  if (pendingRef === undefined) {
+    // Not pending an S0 fix → the schema must already be self-contained. This is the live guard that
+    // fails the build the moment a `$ref` is (re)introduced into a clean or newly-added tool.
+    assertSchemaSelfContained(tool.inputSchema, tool.name);
+    return;
+  }
+  // Pending an S0 fix: accept the post-S0 clean shape, OR the exact known pre-S0 `$ref`.
+  if (!schemaHasRef(tool.inputSchema)) {
+    assertSchemaSelfContained(tool.inputSchema, tool.name);
+    return;
+  }
+  const refs = collectRefs(tool.inputSchema);
+  const unexpected = refs.filter((r) => r !== pendingRef);
+  assert.equal(
+    unexpected.length,
+    0,
+    `tool "${tool.name}": unexpected \`$ref\`(s) ${JSON.stringify(unexpected)} — only the known ` +
+      `pre-S0 leak "${pendingRef}" is tolerated (issue #606 / nano-ide#502). Any other \`$ref\` is a defect.`,
+  );
+}
+
+describe("MCP surface e2e — the runtime-served /app/mcp handshake, per tool (S1 / #607)", () => {
+  let h: McpHarness;
+  let tools: McpTool[];
+  let toolNames: Set<string>;
+
+  before(async () => {
+    h = await bootMcpHarness();
+    tools = await h.listTools();
+    toolNames = new Set(tools.map((t) => t.name));
+  });
+
+  after(async () => {
+    await h?.stop();
+  });
+
+  test("initialize handshake succeeds and tools/list projects the covered tools", () => {
+    assert.ok(h.sessionId, "the initialize handshake must yield an Mcp-Session-Id");
+    assert.ok(tools.length > 0, "tools/list must project at least one tool");
+    for (const name of [...READ_TOOLS, ...OBJECT_BODY_DOORS, "previewDeliveryGraph"]) {
+      assert.ok(toolNames.has(name), `tools/list must expose "${name}"`);
+    }
+    // The operator-only doors stay OFF the MCP surface (ADR 0067 §2 — `x-mcp` excluded).
+    for (const excluded of ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal"]) {
+      assert.ok(!toolNames.has(excluded), `"${excluded}" is operator-only and must NOT be projected`);
+    }
+  });
+
+  test("every projected tool schema is $ref-free with an explicit type (S0 contract)", () => {
+    for (const tool of tools) auditToolSchema(tool);
+  });
+
+  test("read tools answer with parseable responses", async () => {
+    for (const name of READ_TOOLS) {
+      const res = await h.callTool(name, {});
+      assert.ok(!res.isError, `read "${name}" must not error: ${res.text}`);
+      assert.ok(res.text.length > 0, `read "${name}" must return content`);
+      // Every read but the markdown guide answers JSON; the guide answers a non-empty string.
+      if (name !== "getAgentInstructions") {
+        assert.notEqual(res.json, undefined, `read "${name}" must return parseable JSON: ${res.text.slice(0, 120)}`);
+      }
+    }
+  });
+
+  test("previewDeliveryGraph accepts a structured object body and stays pure (nothing staged)", async () => {
+    const res = await h.callTool("previewDeliveryGraph", { body: { graphJson: JSON.stringify(MINIMAL_VALID_GRAPH) } });
+    assertObjectBodyAccepted(res, "previewDeliveryGraph");
+    assert.ok(!res.isError, `previewDeliveryGraph must compile a valid graph: ${res.text}`);
+    const json = res.json as { ok?: boolean; staged?: boolean } | undefined;
+    assert.equal(json?.ok, true, `previewDeliveryGraph must report ok:true: ${res.text}`);
+    assert.equal(json?.staged, false, "previewDeliveryGraph is a PURE preview — it must never stage");
+  });
+
+  test("object-body doors receive the argument as an object, not a string (uniform validation)", async () => {
+    // A deliberately-invalid-but-object body per door: validation rejects it (persisting nothing),
+    // which proves the object argument reached the door AS AN OBJECT — never the S0 stringified body.
+    for (const name of OBJECT_BODY_DOORS) {
+      const args = name === "appendBlackboard" ? { token: "harness-invalid", body: {} } : { body: {} };
+      const res = await h.callTool(name, args);
+      assert.ok(res.isError, `door "${name}" must reject an empty body with a validation error`);
+      assertValidationIssues(res, name); // also asserts the object body was NOT stringified
+    }
+  });
+
+  test("mutating framework tools are gated without the shared secret (set-variables)", async () => {
+    const res = await h.callTool("urban_debug_set_variables", { processInstanceKey: "1", variables: {} });
+    assert.ok(res.isError, "urban_debug_set_variables must refuse a credential-free mutation");
+    assert.match(
+      res.text,
+      /shared secret|allowMutations/i,
+      `the refusal must name the guard: ${res.text}`,
+    );
+  });
+
+  // The falsifiable core (issue #607 acceptance): DELIBERATELY reintroducing either half of the S0
+  // defect makes the harness fail. These pin the detector's teeth independently of whether S0 has
+  // landed — so the guard cannot silently rot into a no-op.
+  describe("reintroducing the S0 defect fails the build", () => {
+    test("a $ref in a tool schema is caught by the self-containment assertion", () => {
+      const good = { type: "object", properties: { body: { type: "object", properties: { n: { type: "number" } } } } };
+      assert.doesNotThrow(() => assertSchemaSelfContained(good, "synthetic-clean"));
+      const withRef = { type: "object", properties: { body: { $ref: "#/components/schemas/DeliveryGraph" } }, required: ["body"] };
+      assert.throws(() => assertSchemaSelfContained(withRef, "synthetic-ref"), /\$ref/, "a reintroduced $ref must throw");
+    });
+
+    test("a typeless schema is caught by the self-containment assertion", () => {
+      const typeless = { properties: { body: { type: "object" } } };
+      assert.throws(() => assertSchemaSelfContained(typeless, "synthetic-typeless"), /type/, "a typeless schema must throw");
+    });
+
+    test("a stringified object body is rejected by the door and caught by assertObjectBodyAccepted", async () => {
+      // Simulate the S0 client coercion: send the body as a JSON STRING instead of an object.
+      const res = await h.callTool("compileDeliveryGraph", { body: JSON.stringify(MINIMAL_VALID_GRAPH) });
+      assert.ok(res.isError, "a stringified object body must be rejected by the door");
+      assert.ok(
+        res.text.includes(STRINGIFIED_BODY_MESSAGE),
+        `the door must report "${STRINGIFIED_BODY_MESSAGE}": ${res.text}`,
+      );
+      // The harness's guard must recognize that signature as a failure.
+      assert.throws(
+        () => assertObjectBodyAccepted(res, "compileDeliveryGraph"),
+        /stringified/,
+        "assertObjectBodyAccepted must flag a stringified-body result",
+      );
+    });
+  });
+
+  test("side-effecting calls leave no live staged proposals behind (repeatable)", async () => {
+    const res = await h.callTool("listStagedProposals", {});
+    assert.ok(!res.isError, `listStagedProposals must not error: ${res.text}`);
+    const json = res.json as { count?: number; proposals?: unknown[] } | undefined;
+    assert.equal(json?.count, 0, `the harness must stage nothing: ${res.text}`);
+    assert.deepEqual(json?.proposals, [], "no live staged proposals may remain");
+  });
+});