@nifrajs/cli 2.10.0 → 2.12.0

package/dist/mcp.js

@@ -25,24 +25,31 @@
  *   - `nifra_inspect` - read the running dev server's recent request traces (method/path/status/
  *     duration/ISR) from the DevTools plugin: what your requests ACTUALLY did, not a guess.
  *
- * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]`, run in the
- * project root. The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
+ * Wire it into a client (e.g. Claude Desktop / Cursor) as: command `nifra`, args `["mcp"]` (or
+ * `["mcp", "<dir>"]` to pin the project directory explicitly). The server does NOT silently trust its
+ * spawn directory: the root is resolved via `./mcp-root.ts` (marker walk-up, the client's MCP `roots`,
+ * fail-closed tools when no nifra project is found) and announced in `initialize` + on every project
+ * tool result. The protocol is hand-rolled (newline-delimited JSON-RPC 2.0 over stdio), including
  * standard MCP progress notifications and request cancellation - no SDK dependency, the same
  * minimal-surface choice as the rest of nifra. The pure dispatch lives in `./mcp-protocol.ts`; this
  * module is the I/O shell (stdin loop, tool wiring, the run subprocess).
  */
+import { realpathSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
-import { basename, resolve, sep } from "node:path";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { reflectRoutes } from "@nifrajs/core/reflection";
 import { Glob } from "bun";
+import { collectContractProof } from "./contract-proof.js";
 import { loadDocsCorpus } from "./docs-search.js";
 import { loadExamplesCorpus } from "./examples.js";
 import { describeProject } from "./introspect.js";
 import { detectMonorepo, loadMonorepoApps } from "./load.js";
 import { docsTools } from "./mcp-docs-tools.js";
 import { createMcpProtocolState, handleRpc, rpcError, } from "./mcp-protocol.js";
+import { applyClientRoots, detectToolingDrift, driftNote, pathsFromRootsResult, resolveRootState, rootInstructions, rootVerdict, } from "./mcp-root.js";
 import { loadTypesCorpus } from "./types-search.js";
+import { collectProjectWorkGraph } from "./work-graph.js";
 /** Path to a sibling child entry (`mcp-run` / `mcp-render` / `mcp-ws`), resolved next to this module (`.ts` in
  * dev, `.js` once built). Each runs in a FRESH subprocess per call so the project's current code loads. */
 function childPath(name) {
@@ -552,7 +559,35 @@ export function resolveProjectDir(root, dir) {
     if (dir === undefined || dir === "")
         return root;
     const target = resolve(root, dir);
-    return target === root || target.startsWith(root + sep) ? target : null;
+    let canonicalRoot;
+    try {
+        canonicalRoot = realpathSync(root);
+    }
+    catch {
+        const lexical = relative(root, target);
+        return lexical === "" || (!lexical.startsWith("..") && !isAbsolute(lexical)) ? target : null;
+    }
+    let probe = target;
+    const missing = [];
+    while (true) {
+        try {
+            const canonicalProbe = realpathSync(probe);
+            const rel = relative(canonicalRoot, canonicalProbe);
+            if (rel.startsWith("..") || isAbsolute(rel))
+                return null;
+            return missing.length === 0 ? canonicalProbe : resolve(canonicalProbe, ...missing.reverse());
+        }
+        catch {
+            const parent = resolve(probe, "..");
+            if (parent === probe)
+                return null;
+            // `basename`, not a slice past `parent`: when `parent` is the filesystem root its trailing
+            // separator is part of it, so `parent.length + 1` eats the first character of the segment and
+            // the path gets rebuilt wrong.
+            missing.push(basename(probe));
+            probe = parent;
+        }
+    }
 }
 /** Consistent error string for a `dir` that escapes the project root. */
 function dirError(dir) {
@@ -563,6 +598,100 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
     const warmRun = createWarmHandler("mcp-run", cwd, "run");
     const warmRender = createWarmHandler("mcp-render", cwd, "render");
     return [
+        {
+            name: "nifra_contract_proof",
+            description: "Compare the current route contract with its snapshot and join each changed route to its route-assurance and capability evidence. Returns hasBreaking as the gate. The typed-contract check is lazy and runs only when check is true.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    baseline: {
+                        type: "string",
+                        description: "Snapshot path relative to the selected project directory. Defaults to api-snapshot.json.",
+                    },
+                    check: {
+                        type: "boolean",
+                        description: "Also run the typed-contract check. Default false to keep the diff lazy.",
+                    },
+                    dir: {
+                        type: "string",
+                        description: "Project subdirectory to inspect.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const raw = args;
+                if (raw.dir !== undefined && typeof raw.dir !== "string") {
+                    return JSON.stringify({ ok: false, error: "dir must be a string" }, null, 2);
+                }
+                if (raw.baseline !== undefined && typeof raw.baseline !== "string") {
+                    return JSON.stringify({ ok: false, error: "baseline must be a string" }, null, 2);
+                }
+                const dir = raw.dir;
+                const baseline = raw.baseline;
+                const target = resolveProjectDir(cwd, dir);
+                if (target === null)
+                    return dirError(dir);
+                if (baseline !== undefined && baseline.trim() === "") {
+                    return JSON.stringify({ ok: false, error: "baseline must not be empty" }, null, 2);
+                }
+                try {
+                    return JSON.stringify(await collectContractProof(target, {
+                        ...(baseline === undefined ? {} : { baselinePath: baseline }),
+                        ...(raw.check === undefined ? {} : { check: raw.check === true }),
+                    }), null, 2);
+                }
+                catch (error) {
+                    return JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }, null, 2);
+                }
+            },
+        },
+        {
+            name: "nifra_prove",
+            description: "Build the static verification work graph for this project. Pass changed files to get only impacted routes and the cheapest proof plan. The result includes a serializable evidence bundle and a machine-checkable stop condition. Requires a fresh build and never probes a running application.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Project-relative changed files. Omit for a graph overview.",
+                    },
+                    minLevel: {
+                        type: "integer",
+                        minimum: 0,
+                        maximum: 4,
+                        description: "Required proof level for the stop condition. Defaults to 1.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const files = args.files;
+                const minLevel = args.minLevel;
+                if ((files !== undefined &&
+                    (!Array.isArray(files) || files.some((file) => typeof file !== "string"))) ||
+                    (minLevel !== undefined &&
+                        (typeof minLevel !== "number" ||
+                            !Number.isInteger(minLevel) ||
+                            minLevel < 0 ||
+                            minLevel > 4))) {
+                    return JSON.stringify({
+                        ok: false,
+                        error: "files must be strings and minLevel must be an integer from 0 to 4",
+                    }, null, 2);
+                }
+                try {
+                    return JSON.stringify(await collectProjectWorkGraph(cwd, {
+                        ...(files === undefined ? {} : { changedFiles: files }),
+                        ...(minLevel === undefined ? {} : { minLevel }),
+                    }), null, 2);
+                }
+                catch (error) {
+                    return JSON.stringify({ ok: false, error: error instanceof Error ? error.message : "work graph failed" }, null, 2);
+                }
+            },
+        },
         {
             name: "nifra_context",
             description: "Get this nifra project's surface. Call it once UNFILTERED for a tight INDEX: the route list (API routes as `METHOD path`, page routes as `pattern → file`) + framework conventions + a pointer - cheap even on a big app, no per-route schema dump. Then pass `path` (a route prefix like /api/orders) and/or `kind` (api|pages) to fetch the FULL contract for that slice (body/query/response TS shapes + the exact typed-client call form).",
@@ -916,7 +1045,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
         },
         {
             name: "nifra_check",
-            description: 'Run the project\'s drift gate and return a structured result { ok, typecheck, diagnostics[] }: typecheck (the frontend↔backend contract), plus lints for hand-rolled fetch() to your own API, untyped client("…") calls missing <typeof app>, and server-only imports in routes/. Pass lintsOnly:true for a near-instant lint pass while iterating; run the full gate (default) to confirm the work is done - fix every diagnostic before finishing.',
+            description: 'Run the project\'s drift gate and return a structured result { ok, typecheck, diagnostics[], pipeline? }: typecheck (the frontend↔backend contract), plus lints for hand-rolled fetch() to your own API, untyped client("…") calls missing <typeof app>, and server-only imports in routes/. `pipeline` answers "which bundler does this app run on" (bun|vite, for dev AND build alike) without starting a server, and its `pipeline` diagnostics catch the hazards of having two: a plugin in the slot the other bundler reads (accepted, then never called), a dev toolchain imported by the file `nifra build` bundles into the production server, and `conditions` that cannot reach Bun\'s dev client bundle. Read it before adding a plugin or a compiler. Pass lintsOnly:true for a near-instant lint pass while iterating; run the full gate (default) to confirm the work is done - fix every diagnostic before finishing.',
             inputSchema: {
                 type: "object",
                 properties: {
@@ -937,14 +1066,17 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                 const target = resolveProjectDir(cwd, opts.dir);
                 if (target === null)
                     return dirError(opts.dir);
-                return JSON.stringify(await collectCheckResult(target, {
+                const result = await collectCheckResult(target, {
                     lintsOnly: opts.lintsOnly ?? false,
                     signal: context.signal,
                     // Bound the result so a large project can't emit an MCP message big enough to break the stdio
                     // transport (`-32000: Connection closed`). If `truncated` comes back, fix the shown diagnostics
                     // and re-run. The scan already skips gitignored trees (walkSource), so this is the safety net.
                     maxDiagnostics: 100,
-                }), null, 2);
+                });
+                return JSON.stringify(result.structuredDiagnostics === undefined
+                    ? result
+                    : { ...result, diagnostics: result.structuredDiagnostics }, null, 2);
             },
         },
         {
@@ -952,14 +1084,20 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
             description: "Automatically fix diagnostic lints (such as rewriting hand-rolled fetch() calls to the typed nifra client, adding generic types to client factory calls, and resolving dependency drift in package.json). Runs diagnostics, applies all mechanical edit suggestions, applies doctor dependency fixes, and returns the remaining unresolved diagnostics.",
             inputSchema: {
                 type: "object",
-                properties: {},
+                properties: {
+                    code: {
+                        type: "string",
+                        description: "Apply the registered recipe for one stable diagnostic code when available.",
+                    },
+                },
                 additionalProperties: false,
             },
-            handler: async (_args, context) => {
+            handler: async (args, context) => {
                 const { collectCheckResult } = await import("./check.js");
+                const { applyDiagnosticRecipe } = await import("./fix-recipes.js");
                 const { applyDoctorAutoFix } = await import("./doctor.js");
+                const { resolveInsideProject } = await import("./project-path.js");
                 const { writeFile, readFile } = await import("node:fs/promises");
-                const { resolve } = await import("node:path");
                 let doctorResult = null;
                 try {
                     doctorResult = await applyDoctorAutoFix(cwd);
@@ -972,6 +1110,15 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                     signal: context.signal,
                     maxDiagnostics: 100,
                 });
+                const requestedCode = args.code;
+                const recipeFixed = [];
+                if (typeof requestedCode === "string") {
+                    for (const diagnostic of checkResult.structuredDiagnostics ?? []) {
+                        if (diagnostic.code !== requestedCode)
+                            continue;
+                        recipeFixed.push(...(await applyDiagnosticRecipe(cwd, diagnostic)));
+                    }
+                }
                 const fixed = [];
                 for (const diag of checkResult.diagnostics) {
                     if (diag.file && diag.line && diag.suggestion?.kind === "edit" && diag.suggestion.diff) {
@@ -980,7 +1127,9 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                             const beforeLine = diffLines.find((l) => l.startsWith("-"))?.slice(1);
                             const afterLine = diffLines.find((l) => l.startsWith("+"))?.slice(1);
                             if (beforeLine !== undefined && afterLine !== undefined) {
-                                const filePath = resolve(cwd, diag.file);
+                                const filePath = await resolveInsideProject(cwd, diag.file);
+                                if (filePath === undefined)
+                                    continue;
                                 const content = await readFile(filePath, "utf-8");
                                 const lines = content.split("\n");
                                 const idx = diag.line - 1;
@@ -1008,6 +1157,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                 return JSON.stringify({
                     ok: finalResult.ok,
                     fixed,
+                    recipeFixed,
                     doctorFixed: doctorResult?.fixed ?? [],
                     remainingDiagnostics: finalResult.diagnostics,
                 }, null, 2);
@@ -1023,6 +1173,22 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                         type: "string",
                         description: "Config path relative to the selected project directory. Default: nifra.assurance.ts.",
                     },
+                    bundle: {
+                        type: "boolean",
+                        description: "Return the single gate bundle with verdict and explicit skipped gates.",
+                    },
+                    strict: {
+                        type: "boolean",
+                        description: "Treat warning diagnostics as failures in the bundle.",
+                    },
+                    hydration: {
+                        type: "boolean",
+                        description: "Run the hydration assurance gate.",
+                    },
+                    interact: {
+                        type: "boolean",
+                        description: "Run declared hydration probes after the client mounts.",
+                    },
                     dir: {
                         type: "string",
                         description: 'Evaluate this project subdirectory (relative to the MCP root), e.g. "apps/api". Default: the project root.',
@@ -1039,10 +1205,62 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
                 if (config !== undefined && config !== target && !config.startsWith(target + sep)) {
                     return JSON.stringify({ ok: false, error: "config must stay inside the selected project directory" }, null, 2);
                 }
-                const { collectAssuranceReport } = await import("./assure.js");
+                const { collectAssuranceReport, collectAssureBundle } = await import("./assure.js");
+                if (opts.bundle === true || opts.strict === true || opts.hydration === true) {
+                    return JSON.stringify(await collectAssureBundle(target, {
+                        ...(config === undefined ? {} : { config }),
+                        ...(opts.strict === undefined ? {} : { strict: opts.strict }),
+                        ...(opts.hydration === undefined ? {} : { hydration: opts.hydration }),
+                        ...(opts.interact === undefined ? {} : { interact: opts.interact }),
+                    }), null, 2);
+                }
                 return JSON.stringify(await collectAssuranceReport(target, config), null, 2);
             },
         },
+        {
+            name: "nifra_hydrate",
+            description: "Run the hydration assurance gate and return stable NF-H diagnostics.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    dir: { type: "string", description: "Project subdirectory to inspect." },
+                    interact: { type: "boolean", description: "Run declared hydration probes." },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const opts = args;
+                const target = resolveProjectDir(cwd, opts.dir);
+                if (target === null)
+                    return dirError(opts.dir);
+                const { runHydrationAssurance } = await import("./assure-hydration.js");
+                return JSON.stringify(await runHydrationAssurance(target, { interact: opts.interact === true }), null, 2);
+            },
+        },
+        {
+            name: "nifra_replay",
+            description: "Validate and dispatch a token-only replay metadata file.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file: { type: "string", description: "Replay file relative to the project root." },
+                },
+                required: ["file"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const file = args.file;
+                if (typeof file !== "string" || file.trim() === "")
+                    return JSON.stringify({ ok: false, error: "file is required" });
+                const { runReplay } = await import("./replay.js");
+                try {
+                    return JSON.stringify(await runReplay(cwd, file), null, 2);
+                }
+                catch (error) {
+                    return JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }, null, 2);
+                }
+            },
+        },
         {
             name: "nifra_levels",
             description: "Compute this project's verification ladder and return { achieved, levels[] }, where each level carries { level, name, ok, reasons[] }. The ladder is cumulative: L0 typed contract (nifra check), L1 route assurance, L2 reviewed capability lockfile, L3 route trust manifest in sync, L4 contract invariants, so a level only holds when every level below it holds, and `achieved` is -1 when even L0 fails. This is the single gate that reports what a change actually proves: run it after finishing work, and treat any `reasons` on a level the project already claimed as a regression to fix.",
@@ -1085,7 +1303,7 @@ export function projectTools(cwd, loadAppCached = createCachedAppLoader(cwd)) {
         },
         {
             name: "nifra_doctor",
-            description: "Check this project for packages imported in source but NOT declared in package.json - the Bun-workspace trap where an import resolves at runtime (hoisting/workspace) so tests pass and `bun install` says no changes, yet tsc fails and a fresh/standalone install can't resolve it. Returns { ok, ran, findings[], fixed?, skippedFixes? }. Pass autoFix:true to update package.json only when the dependency version can be inferred locally from an ancestor package.json or installed package metadata; otherwise the tool returns the exact bun add command to run.",
+            description: "Check this project for packages imported in source but NOT declared in package.json - the Bun-workspace trap where an import resolves at runtime (hoisting/workspace) so tests pass and `bun install` says no changes, yet tsc fails and a fresh/standalone install can't resolve it. Also reports `pipeline`: which bundler (bun|vite) this app's dev AND build phases run on and why, plus config hazards that only exist because there are two - a plugin sitting in the slot the other bundler reads (accepted, then never called), a dev toolchain imported by the file `nifra build` bundles into the production server (builds clean, dies at startup), and `conditions` that cannot reach the client bundle Bun's dev server serves. Returns { ok, ran, findings[], pipeline?, fixed?, skippedFixes? }. Pass autoFix:true to update package.json only when the dependency version can be inferred locally from an ancestor package.json or installed package metadata; otherwise the tool returns the exact bun add command to run.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1261,12 +1479,17 @@ async function appDeclaredTools(loader) {
         return [];
     }
 }
-/** Run the stdio MCP server: read newline-delimited JSON-RPC from stdin, write responses to stdout. */
-export async function runMcpServer(cwd, version) {
-    let features;
-    const monorepo = await detectMonorepo(cwd);
+/** Tool names that never touch the project - they serve the bundled docs/examples/types corpus, so
+ * they stay available (and unstamped) whatever the root state is. */
+const PROJECT_FREE_TOOLS = new Set(["nifra_docs", "nifra_example", "nifra_types", "nifra_learn"]);
+/** The id of this server's own `roots/list` request to the client. A fixed, namespaced string: the
+ * server only ever has one roots request in flight, and no response to a CLIENT-initiated request can
+ * carry it (clients pick their own ids; this one is recognisably ours). */
+const ROOTS_REQUEST_ID = "nifra:roots/list";
+async function createProjectContext(root) {
+    const monorepo = await detectMonorepo(root);
     if (monorepo) {
-        const appEntries = await loadMonorepoApps(cwd, monorepo);
+        const appEntries = await loadMonorepoApps(root, monorepo);
         const allResources = [];
         const allPrompts = [];
         for (const { name, cwd: appCwd } of appEntries) {
@@ -1275,22 +1498,118 @@ export async function runMcpServer(cwd, version) {
             allResources.push(...(ns.features.resources ?? []));
             allPrompts.push(...(ns.features.prompts ?? []));
         }
-        features = { resources: allResources, prompts: allPrompts };
+        return {
+            monorepo,
+            features: { resources: allResources, prompts: allPrompts },
+            loadAppCached: createCachedAppLoader(root),
+        };
     }
-    else {
-        const loadAppCached = createCachedAppLoader(cwd);
-        features = await backendFeatures(loadAppCached, projectFeatures(cwd, loadAppCached));
+    const loadAppCached = createCachedAppLoader(root);
+    return {
+        monorepo,
+        features: await backendFeatures(loadAppCached, projectFeatures(root, loadAppCached)),
+        loadAppCached,
+    };
+}
+/**
+ * Wrap every project-scoped tool with the root guard: a bad root ({@link rootVerdict} `blocked`) makes
+ * the tool refuse with the remediation message instead of answering about whatever directory the
+ * server happened to start in; a good root stamps the result with `[nifra] project root: …` so the
+ * agent (and the human reading its transcript) can see WHICH project answered. Docs tools pass
+ * through untouched - they serve the bundled corpus, not the project.
+ */
+export function guardTools(tools, verdict) {
+    return tools.map((tool) => {
+        if (PROJECT_FREE_TOOLS.has(tool.name))
+            return tool;
+        return {
+            ...tool,
+            handler: async (args, context) => {
+                if (verdict.blocked !== undefined) {
+                    return { content: [{ type: "text", text: verdict.blocked }], isError: true };
+                }
+                const result = await tool.handler(args, context);
+                const note = { type: "text", text: verdict.note };
+                if (typeof result === "string") {
+                    return { content: [{ type: "text", text: result }, note] };
+                }
+                return { ...result, content: [...(result.content ?? []), note] };
+            },
+        };
+    });
+}
+/** Whether the client's `initialize` params declare the `roots` capability - the precondition for
+ * this server sending it a `roots/list` request. */
+export function clientSupportsRoots(params) {
+    const capabilities = params?.capabilities;
+    if (typeof capabilities !== "object" || capabilities === null)
+        return false;
+    const roots = capabilities.roots;
+    return typeof roots === "object" && roots !== null;
+}
+/**
+ * Run the stdio MCP server: read newline-delimited JSON-RPC from stdin, write responses to stdout.
+ *
+ * The project root is resolved defensively rather than assumed (`./mcp-root.ts`): explicit
+ * `nifra mcp <dir>` beats a cwd guess, a cwd guess walks up to the nearest nifra marker, the client's
+ * MCP `roots` (requested after the handshake, re-requested on `roots/list_changed`) can correct an
+ * unambiguous wrong guess, and anything still unresolved fails closed per tool call. The effective
+ * root is announced in the `initialize` instructions and stamped on every project tool result.
+ */
+export async function runMcpServer(cwd, version, explicitDir) {
+    const requested = explicitDir !== undefined ? resolve(cwd, explicitDir) : cwd;
+    if (explicitDir !== undefined && !(await stat(requested).catch(() => null))?.isDirectory()) {
+        throw new Error(`nifra mcp: directory not found: ${requested}`);
     }
-    const loadAppCached = createCachedAppLoader(cwd);
+    let rootState = await resolveRootState(requested, explicitDir !== undefined);
+    let ctx = await createProjectContext(rootState.root);
+    // The CLI answering may not be the nifra the project builds with (a globally installed server, a
+    // stale agent config). Recomputed whenever the root moves, since a different project can install a
+    // different version.
+    let drift = await detectToolingDrift(rootState.root, version);
     const serverInfo = { name: "nifra", version };
     const state = createMcpProtocolState();
     const send = (message) => {
         process.stdout.write(`${JSON.stringify(message)}\n`);
     };
+    let rootsSupported = false;
+    const requestRoots = () => {
+        if (!rootsSupported)
+            return;
+        process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: ROOTS_REQUEST_ID, method: "roots/list" })}\n`);
+    };
+    const onRootsAnswer = async (message) => {
+        const result = message.result;
+        // An error response (or a malformed one) carries no roots: keep the current state - the absence
+        // of workspace data is not a mismatch, and never a reason to move the root.
+        if (result === undefined)
+            return;
+        const next = await applyClientRoots(rootState, pathsFromRootsResult(result));
+        if (next.root !== rootState.root) {
+            ctx = await createProjectContext(next.root);
+            drift = await detectToolingDrift(next.root, version);
+        }
+        rootState = next;
+    };
+    // Root updates are serialized against tool dispatch: a message read AFTER the client's roots answer
+    // must see the adopted root, even though dispatches themselves run concurrently.
+    let rootsUpdate = Promise.resolve();
     const dispatch = async (message) => {
+        // The client's answer to OUR `roots/list` request - a response (id, no method), which the pure
+        // dispatch would reject as an unknown method. Intercept it before handleRpc ever sees it.
+        if (message.method === undefined && message.id === ROOTS_REQUEST_ID) {
+            // Swallow failures: a bad answer must not poison the chain and 500 every later dispatch.
+            rootsUpdate = onRootsAnswer(message).catch(() => { });
+            await rootsUpdate;
+            return;
+        }
+        await rootsUpdate;
+        if (message.method === "initialize") {
+            rootsSupported = clientSupportsRoots(message.params);
+        }
         let activeTools;
-        if (monorepo) {
-            const appEntries = await loadMonorepoApps(cwd, monorepo);
+        if (ctx.monorepo) {
+            const appEntries = await loadMonorepoApps(rootState.root, ctx.monorepo);
             const allTools = [];
             for (const { name, cwd: appCwd } of appEntries) {
                 const loader = createCachedAppLoader(appCwd);
@@ -1302,16 +1621,30 @@ export async function runMcpServer(cwd, version) {
         }
         else {
             activeTools = [
-                ...projectTools(cwd, loadAppCached),
-                ...(await appDeclaredTools(loadAppCached)),
+                ...projectTools(rootState.root, ctx.loadAppCached),
+                ...(await appDeclaredTools(ctx.loadAppCached)),
             ];
         }
+        const verdict = await rootVerdict(rootState);
+        activeTools = guardTools(activeTools, drift === undefined || verdict.blocked !== undefined
+            ? verdict
+            : { ...verdict, note: `${verdict.note}\n${driftNote(drift)}` });
+        const features = {
+            ...ctx.features,
+            instructions: rootInstructions(rootState, drift),
+        };
         const response = await handleRpc(message, activeTools, serverInfo, features, {
             state,
             sendNotification: send,
         });
         if (response)
             send(response);
+        // Ask for the client's workspace roots once the handshake completes, and again whenever the
+        // client says they changed. The answer comes back through the interception above.
+        if (message.method === "notifications/initialized" ||
+            message.method === "notifications/roots/list_changed") {
+            requestRoots();
+        }
     };
     const decoder = new TextDecoder();
     let buffer = "";