@nudge-ui/mcp 0.2.1 → 0.2.2

package/dist/cli.mjs

@@ -7479,7 +7479,7 @@ function isCanvasCommand(value) {
 // src/discovery.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { realpath as realpath3 } from "node:fs/promises";
-import { resolve as resolve3 } from "node:path";
+import { isAbsolute as isAbsolute2, resolve as resolve3 } from "node:path";
 
 // src/projectSessionClient.ts
 import { randomUUID } from "node:crypto";
@@ -7488,6 +7488,7 @@ import { randomUUID } from "node:crypto";
 var BRIDGE_ENDPOINTS = {
   health: "/health",
   pair: "/pair",
+  takeover: "/takeover",
   events: "/events",
   prompt: "/prompt",
   status: "/status",
@@ -7508,6 +7509,14 @@ var AGENT_CONTROL_ENDPOINTS = {
 // src/projectSessionClient.ts
 var CONTROL_TIMEOUT_MS = 5e3;
 var CANVAS_TIMEOUT_MS = 65e3;
+var ProjectSessionResponseError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "ProjectSessionResponseError";
+    this.status = status;
+  }
+};
 async function requestJson(session, path, init = {}, { signal, timeoutMs = CONTROL_TIMEOUT_MS } = {}) {
   const response = await fetch(`${session.endpoint}${path}`, {
     ...init,
@@ -7520,7 +7529,12 @@ async function requestJson(session, path, init = {}, { signal, timeoutMs = CONTR
     }
   });
   const body = await response.json().catch(() => void 0);
-  if (!response.ok) throw new Error(body?.error?.message ?? `Nudge project bridge returned ${response.status}.`);
+  if (!response.ok) {
+    throw new ProjectSessionResponseError(
+      response.status,
+      body?.error?.message ?? `Nudge project bridge returned ${response.status}.`
+    );
+  }
   return body;
 }
 async function readSessionHealth(session, timeoutMs = CONTROL_TIMEOUT_MS) {
@@ -7595,13 +7609,21 @@ import { lstat, readFile, readdir, realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 var PROBE_TIMEOUT_MS = 750;
 var MAX_DESCRIPTOR_BYTES = 32 * 1024;
+async function inspectProjectSessions(registryRoot) {
+  const names = (await readRegistryDirectory(registryRoot)).filter((name) => name.endsWith(".json"));
+  const records = await Promise.all(names.map((name) => readDescriptor(resolve(registryRoot, name))));
+  const descriptors = records.filter((record2) => typeof record2 === "object");
+  const probes = await Promise.all(descriptors.map(probeSession));
+  return {
+    descriptorCount: names.length,
+    invalidCount: records.filter((record2) => record2 === void 0).length + probes.filter((probe) => probe.kind === "invalid").length,
+    incompatibleCount: records.filter((record2) => record2 === "incompatible").length,
+    unreachable: descriptors.filter((_, index) => probes[index]?.kind === "unreachable").map(({ workspaceRoot, appRoot, sessionId }) => ({ workspaceRoot, appRoot, sessionId })),
+    live: probes.flatMap((probe) => probe.kind === "live" ? [probe.session] : [])
+  };
+}
 async function readLiveProjectSessions(registryRoot) {
-  const names = await readRegistryDirectory(registryRoot);
-  const descriptors = await Promise.all(
-    names.filter((name) => name.endsWith(".json")).map((name) => readDescriptor(resolve(registryRoot, name)))
-  );
-  const live = await Promise.all(descriptors.filter(isPresent).map(probeSession));
-  return live.filter(isPresent);
+  return (await inspectProjectSessions(registryRoot)).live;
 }
 async function readRegistryDirectory(registryRoot) {
   try {
@@ -7619,8 +7641,9 @@ async function readDescriptor(path) {
     if ((metadata.mode & 63) !== 0) return void 0;
     const parsed = JSON.parse(await readFile(path, "utf8"));
     if (!isStoredSession(parsed)) return void 0;
+    if (parsed.protocolVersion !== AGENT_PROTOCOL_VERSION) return "incompatible";
     const [workspaceRoot, appRoot] = await Promise.all([realpath(parsed.workspaceRoot), realpath(parsed.appRoot)]);
-    return { ...parsed, workspaceRoot, appRoot };
+    return { ...parsed, protocolVersion: AGENT_PROTOCOL_VERSION, workspaceRoot, appRoot };
   } catch {
     return void 0;
   }
@@ -7628,14 +7651,21 @@ async function readDescriptor(path) {
 async function probeSession(descriptor) {
   try {
     const health = await readSessionHealth(descriptor, PROBE_TIMEOUT_MS);
-    if (health.projectId !== descriptor.projectId || health.available !== true) return void 0;
-    return { descriptor, health };
-  } catch {
-    return void 0;
+    if (!isSessionHealth(health) || health.projectId !== descriptor.projectId) return { kind: "invalid" };
+    return { kind: "live", session: { descriptor, health } };
+  } catch (error2) {
+    return { kind: error2 instanceof ProjectSessionResponseError ? "invalid" : "unreachable" };
   }
 }
-function isPresent(value) {
-  return value !== void 0;
+function isSessionHealth(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const health = value;
+  return typeof health.projectId === "string" && health.available === true && typeof health.claimed === "boolean" && isAgentStatusSnapshot(health.status);
+}
+function isAgentStatusSnapshot(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const status = value;
+  return status.protocolVersion === AGENT_PROTOCOL_VERSION && typeof status.projectId === "string" && (status.connection === "offline" || status.connection === "listening" || status.connection === "paired" || status.connection === "working") && typeof status.listenerActive === "boolean" && typeof status.paired === "boolean" && (status.request === null || typeof status.request === "object" && !Array.isArray(status.request));
 }
 function isLoopbackEndpoint(value) {
   if (typeof value !== "string") return false;
@@ -7649,7 +7679,7 @@ function isLoopbackEndpoint(value) {
 function isStoredSession(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const session = value;
-  return session.schemaVersion === 1 && session.protocolVersion === AGENT_PROTOCOL_VERSION && typeof session.sessionId === "string" && session.sessionId.length > 0 && typeof session.projectId === "string" && session.projectId.length > 0 && typeof session.workspaceRoot === "string" && session.workspaceRoot.length > 0 && typeof session.appRoot === "string" && session.appRoot.length > 0 && (session.gitCommonDir === void 0 || typeof session.gitCommonDir === "string") && (session.branch === void 0 || typeof session.branch === "string") && typeof session.origin === "string" && isLoopbackEndpoint(session.endpoint) && typeof session.startedAt === "string" && typeof session.pid === "number" && Number.isSafeInteger(session.pid) && typeof session.controlToken === "string" && session.controlToken.length >= 32 && session.controlToken.length <= 256;
+  return session.schemaVersion === 1 && typeof session.protocolVersion === "number" && Number.isSafeInteger(session.protocolVersion) && typeof session.sessionId === "string" && session.sessionId.length > 0 && typeof session.projectId === "string" && session.projectId.length > 0 && typeof session.workspaceRoot === "string" && session.workspaceRoot.length > 0 && typeof session.appRoot === "string" && session.appRoot.length > 0 && (session.gitCommonDir === void 0 || typeof session.gitCommonDir === "string") && (session.branch === void 0 || typeof session.branch === "string") && typeof session.origin === "string" && isLoopbackEndpoint(session.endpoint) && typeof session.startedAt === "string" && typeof session.pid === "number" && Number.isSafeInteger(session.pid) && typeof session.controlToken === "string" && session.controlToken.length >= 32 && session.controlToken.length <= 256;
 }
 
 // src/sessionSelection.ts
@@ -7985,7 +8015,7 @@ function createLoopbackBridge(options) {
       pageUrl: lastPageUrl
     }, incomingOrigin);
   };
-  const handlePair = async (request, response) => {
+  const readPairRequest = async (request) => {
     if (!loopbackAddress(request.socket.remoteAddress)) {
       throw new BridgeRequestError(403, "loopback_only", "The browser bridge accepts loopback connections only.");
     }
@@ -8006,6 +8036,10 @@ function createLoopbackBridge(options) {
       }
       requestedPageUrl = new URL(body.pageUrl, requestedOrigin).href;
     }
+    return { body, incomingOrigin, requestedPageUrl };
+  };
+  const handlePair = async (request, response) => {
+    const { body, incomingOrigin, requestedPageUrl } = await readPairRequest(request);
     if (sessionToken) {
       if (body.sessionToken !== sessionToken) {
         throw new BridgeRequestError(409, "already_paired", "A browser is already paired with this project.");
@@ -8041,6 +8075,12 @@ function createLoopbackBridge(options) {
     sendJson(response, 200, result, incomingOrigin);
     broadcastStatus();
   };
+  const handleTakeover = async (request, response) => {
+    const { incomingOrigin, requestedPageUrl } = await readPairRequest(request);
+    if (sessionToken) disconnectBrowser(sessionToken);
+    const pairing = pairBrowser(options.projectId, incomingOrigin, requestedPageUrl);
+    sendJson(response, 200, pairing, incomingOrigin);
+  };
   const handleEvents = (request, response, url) => {
     parseProjectId(url.searchParams.get("projectId"), options.projectId);
     const incomingOrigin = requireBrowserRequest(request, url);
@@ -8322,6 +8362,10 @@ function createLoopbackBridge(options) {
         await handlePair(request, response);
         return;
       }
+      if (request.method === "POST" && url.pathname === BRIDGE_ENDPOINTS.takeover) {
+        await handleTakeover(request, response);
+        return;
+      }
       if (request.method === "GET" && url.pathname === BRIDGE_ENDPOINTS.events) {
         handleEvents(request, response, url);
         return;
@@ -8620,15 +8664,15 @@ function publicSession(session) {
   return visible;
 }
 async function discoverProjectSessions(applicationRoot, registryRoot = defaultSessionRegistryRoot()) {
-  const canonicalApplication = await realpath3(resolve3(applicationRoot));
-  const canonicalWorkspace = await resolveWorkspaceRoot(canonicalApplication);
+  const canonicalApplication = applicationRoot === void 0 ? void 0 : await realpath3(requireAbsoluteWorkspaceRoot(applicationRoot));
+  const canonicalWorkspace = canonicalApplication === void 0 ? void 0 : await resolveWorkspaceRoot(canonicalApplication);
   const live = await readLiveProjectSessions(resolve3(registryRoot));
   return live.map(({ descriptor, health }) => {
     const matchesWorkspace = descriptor.workspaceRoot === canonicalWorkspace;
     return {
       ...publicSession(descriptor),
       matchesWorkspace,
-      matchesApplication: matchesApplication(descriptor, {
+      matchesApplication: canonicalWorkspace !== void 0 && canonicalApplication !== void 0 && matchesApplication(descriptor, {
         workspaceRoot: canonicalWorkspace,
         applicationRoot: canonicalApplication
       }),
@@ -8648,14 +8692,23 @@ var DiscoveredProjectRouter = class _DiscoveredProjectRouter {
   agentId;
   client = null;
   releaseGeneration = 0;
+  connectionQueue = Promise.resolve();
   constructor(workspaceRoot, applicationRoot, registryRoot, agentId) {
     this.workspaceRoot = workspaceRoot;
     this.applicationRoot = applicationRoot;
     this.registryRoot = registryRoot;
     this.agentId = agentId;
   }
+  get selectedSessionId() {
+    return this.client?.descriptor.sessionId;
+  }
+  static forSession(session, registryRoot) {
+    const router = new _DiscoveredProjectRouter(session.workspaceRoot, session.appRoot, registryRoot, randomUUID3());
+    router.client = new ProjectSessionClient(session, router.agentId);
+    return router;
+  }
   static async create(workspaceRoot, registryRoot = defaultSessionRegistryRoot()) {
-    const applicationRoot = await realpath3(resolve3(workspaceRoot));
+    const applicationRoot = await realpath3(requireAbsoluteWorkspaceRoot(workspaceRoot));
     return new _DiscoveredProjectRouter(
       await resolveWorkspaceRoot(applicationRoot),
       applicationRoot,
@@ -8666,7 +8719,12 @@ var DiscoveredProjectRouter = class _DiscoveredProjectRouter {
   async listSessions() {
     return await discoverProjectSessions(this.applicationRoot, this.registryRoot);
   }
-  async connectToSession(sessionId) {
+  connectToSession(sessionId) {
+    const connection = this.connectionQueue.then(() => this.selectSession(sessionId));
+    this.connectionQueue = connection.then(() => void 0, () => void 0);
+    return connection;
+  }
+  async selectSession(sessionId) {
     const live = await readLiveProjectSessions(this.registryRoot);
     const selected = selectProjectSession(live.map(({ descriptor }) => descriptor), {
       workspaceRoot: this.workspaceRoot,
@@ -8712,6 +8770,7 @@ var DiscoveredProjectRouter = class _DiscoveredProjectRouter {
   }
   async release() {
     this.releaseGeneration += 1;
+    await this.connectionQueue;
     const client = this.client;
     this.client = null;
     await client?.close();
@@ -8720,6 +8779,33 @@ var DiscoveredProjectRouter = class _DiscoveredProjectRouter {
     await this.release();
   }
 };
+async function diagnoseProjectSessions(applicationRoot, registryRoot = defaultSessionRegistryRoot()) {
+  const resolvedRegistryRoot = resolve3(registryRoot);
+  const app = applicationRoot === void 0 ? void 0 : await realpath3(requireAbsoluteWorkspaceRoot(applicationRoot));
+  const workspace = app === void 0 ? void 0 : await resolveWorkspaceRoot(app);
+  const inspection = await inspectProjectSessions(resolvedRegistryRoot);
+  const matching = (session) => app === void 0 || session.workspaceRoot === workspace && (app === workspace || session.appRoot === app);
+  return {
+    registryRoot: resolvedRegistryRoot,
+    workspaceRoot: workspace,
+    applicationRoot: app,
+    descriptorCount: inspection.descriptorCount,
+    invalidCount: inspection.invalidCount,
+    incompatibleCount: inspection.incompatibleCount,
+    reachableCount: inspection.live.length,
+    matchingReachableCount: inspection.live.filter(({ descriptor }) => matching(descriptor)).length,
+    matchingUnreachableCount: inspection.unreachable.filter(matching).length,
+    guidance: [
+      ...inspection.invalidCount > 0 ? ["Some session descriptors or authenticated health responses are invalid. Check the adapter and project bridge versions, descriptor permissions, and bridge logs."] : [],
+      ...inspection.unreachable.some(matching) ? ["Matching descriptors exist but their loopback endpoints are unreachable. The server may have stopped or local networking may be blocked. Retry outside the agent command sandbox; do not treat this as proof that no bridge registered."] : [],
+      ...inspection.incompatibleCount > 0 ? ["Some registrations use an incompatible protocol. Upgrade the reusable adapter and the project's @nudge-ui/mcp dependency, then restart the development server and agent host."] : []
+    ]
+  };
+}
+function requireAbsoluteWorkspaceRoot(workspaceRoot) {
+  if (!isAbsolute2(workspaceRoot)) throw new TypeError("workspaceRoot must be an absolute path.");
+  return workspaceRoot;
+}
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var external_exports = {};
@@ -22955,7 +23041,64 @@ var StdioServerTransport = class {
 };
 
 // src/server.ts
+import { realpath as realpath5 } from "node:fs/promises";
 import { createRequire } from "node:module";
+import { isAbsolute as isAbsolute4 } from "node:path";
+
+// src/adapterRouting.ts
+import { realpath as realpath4 } from "node:fs/promises";
+import { isAbsolute as isAbsolute3 } from "node:path";
+var AdapterRouting = class {
+  constructor(registryRoot = defaultSessionRegistryRoot()) {
+    this.registryRoot = registryRoot;
+  }
+  closing = false;
+  selections = /* @__PURE__ */ new Map();
+  applications = /* @__PURE__ */ new Map();
+  async target({ workspaceRoot, sessionId }) {
+    if (!workspaceRoot || !isAbsolute3(workspaceRoot)) {
+      throw new Error("Supply workspaceRoot as the absolute path of the checkout or application you are editing.");
+    }
+    const applicationRoot = await realpath4(workspaceRoot);
+    if (this.closing) throw new Error("The MCP adapter is closing.");
+    const key = JSON.stringify([applicationRoot, sessionId]);
+    let selection = this.selections.get(key);
+    if (!selection) {
+      selection = this.select(applicationRoot, sessionId);
+      this.selections.set(key, selection);
+      void selection.catch(() => {
+        if (this.selections.get(key) === selection) this.selections.delete(key);
+      });
+    }
+    return await selection;
+  }
+  async select(applicationRoot, sessionId) {
+    const workspaceRoot = await resolveWorkspaceRoot(applicationRoot);
+    const live = await readLiveProjectSessions(this.registryRoot);
+    if (this.closing) throw new Error("The MCP adapter is closing.");
+    const selected = selectProjectSession(live.map(({ descriptor }) => descriptor), {
+      workspaceRoot,
+      applicationRoot,
+      requestedSessionId: sessionId
+    });
+    const key = selected.sessionId;
+    let router = this.applications.get(key) ?? [...this.applications.values()].find((candidate) => candidate.selectedSessionId === selected.sessionId);
+    if (!router) {
+      router = DiscoveredProjectRouter.forSession(selected, this.registryRoot);
+      this.applications.set(key, router);
+    }
+    return router;
+  }
+  async close() {
+    this.closing = true;
+    await Promise.allSettled(this.selections.values());
+    await Promise.all([...this.applications.values()].map((router) => router.close()));
+    this.selections.clear();
+    this.applications.clear();
+  }
+};
+
+// src/server.ts
 var MCP_SERVER_NAME = "nudge-ui";
 var MCP_SERVER_VERSION = readPackageVersion();
 function readPackageVersion() {
@@ -22967,13 +23110,14 @@ function readPackageVersion() {
 }
 var MCP_SERVER_INSTRUCTIONS = [
   "Nudge UI is a local browser companion for one exact project workspace or Git worktree.",
-  "Before listening, compare each session's workspaceRoot and appRoot with the checkout and application you will edit; if they differ, rerun Nudge agent setup in the intended checkout.",
+  "Supply workspaceRoot with the absolute checkout or application path you are editing on every tool call. Listing and selecting sessions requires this explicit scope; repeat the same workspaceRoot and sessionId for status, Canvas, and release calls. Never use the MCP process working directory to infer the task workspace.",
   "When the user asks to listen to Nudge, call nudge_list_sessions when that tool is available; if several apps are running, select only a session marked matchesApplication.",
   "Call nudge_listen (or nudge_connect) and keep the call open while waiting for a browser request; the bridge may be running before a listener exists.",
   "After a prompt is delivered, edit the project source using the host's normal approval flow.",
   "Report completed, failed, or interrupted status with nudge_report_status before listening again.",
   "When the user asks to stop listening, call nudge_release when that tool is available so another agent can claim the project session.",
   "Canvas tools operate only on same-origin routes from the paired project.",
+  "Automated browsers such as Playwright and headless Chrome get the plain app without the Nudge editor; add ?nudge-ui=on to a URL only when testing Nudge itself.",
   "No request, prompt, or browser state is persisted by this companion."
 ].join(" ");
 function textResult(value) {
@@ -23019,17 +23163,29 @@ function boundedWorkspaceRoot(value) {
   if (value.length === 0 || value.length > 4096) throw new TypeError("workspaceRoot must be a bounded non-empty string");
   return value;
 }
-function installTools(mcpServer, bridge) {
+function installTools(mcpServer, bridge, routing) {
+  const target = async (args) => {
+    if (routing) return await routing.target(args);
+    if (bridge instanceof DiscoveredProjectRouter && args.workspaceRoot !== void 0 && await realpath5(args.workspaceRoot) !== bridge.applicationRoot) {
+      throw new Error("This legacy MCP configuration is restricted to another application. Rerun agent setup to migrate it to the reusable adapter.");
+    }
+    return bridge;
+  };
+  const workspaceInput = external_exports.string().min(1).max(4096).refine(isAbsolute4, "workspaceRoot must be an absolute path.").describe("Absolute path of the checkout or application being edited.");
+  const scopeInput = {
+    workspaceRoot: routing ? workspaceInput : workspaceInput.optional(),
+    sessionId: external_exports.string().uuid().optional()
+  };
   const listen = async (args, extra) => {
     try {
-      return promptResult(await bridge.waitForPrompt(extra.signal, args.sessionId));
+      return promptResult(await (await target(args)).waitForPrompt(extra.signal, args.sessionId));
     } catch (error2) {
       return errorResult(error2);
     }
   };
   const listenDescription = "When the user asks to listen to Nudge, wait for one browser prompt. Keep this standard MCP call open, then call nudge_report_status and listen again after the request ends.";
-  const emptyInput = {};
-  const listenInput = bridge.listSessions ? { sessionId: external_exports.string().uuid().optional() } : emptyInput;
+  const emptyInput = scopeInput;
+  const listenInput = scopeInput;
   mcpServer.registerTool("nudge_listen", {
     title: "Listen for Nudge requests",
     description: listenDescription,
@@ -23047,24 +23203,38 @@ function installTools(mcpServer, bridge) {
     description: "Read the in-memory browser pairing and request status for this project.",
     inputSchema: emptyInput,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
-  }, async () => textResult(await bridge.getStatus()));
-  if (bridge.listSessions) {
+  }, async (args) => {
+    try {
+      return textResult(await (await target(args)).getStatus());
+    } catch (error2) {
+      return errorResult(error2);
+    }
+  });
+  if (routing || bridge?.listSessions) {
     mcpServer.registerTool("nudge_list_sessions", {
       title: "List Nudge project sessions",
-      description: "List live local Nudge sessions. Only sessions marked matchesApplication can be selected by an application-scoped adapter.",
+      description: "List live local Nudge sessions for the supplied checkout or application path. The workspaceRoot value is required so the adapter can select only sessions in that explicit scope.",
       inputSchema: emptyInput,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
-    }, async () => textResult(await bridge.listSessions()));
+    }, async (args) => textResult(routing ? await discoverProjectSessions(args.workspaceRoot, routing.registryRoot) : await bridge.listSessions()));
   }
-  if (bridge.release) {
+  if (routing) {
+    mcpServer.registerTool("nudge_diagnose", {
+      title: "Diagnose Nudge discovery",
+      description: "Diagnose Nudge discovery for the supplied checkout or application path. The result includes the resolved registry, workspace, and application scope plus counts for missing registrations, invalid descriptors or health responses, unreachable loopback endpoints, and incompatible bridge protocols; credentials are never exposed.",
+      inputSchema: scopeInput,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    }, async (args) => textResult(await diagnoseProjectSessions(args.workspaceRoot, routing.registryRoot)));
+  }
+  if (routing || bridge?.release) {
     mcpServer.registerTool("nudge_release", {
       title: "Release Nudge session",
       description: "Stop listening and release this adapter's project-session claim so another agent can connect.",
       inputSchema: emptyInput,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
-    }, async () => {
+    }, async (args) => {
       try {
-        await bridge.release();
+        await (await target(args)).release();
         return textResult({ released: true });
       } catch (error2) {
         return errorResult(error2);
@@ -23073,8 +23243,9 @@ function installTools(mcpServer, bridge) {
   }
   mcpServer.registerTool("nudge_report_status", {
     title: "Report Nudge request status",
-    description: "Report working, completed, failed, or interrupted status for the prompt currently being handled.",
+    description: "Report working, completed, failed, or interrupted status for the prompt currently being handled. Report completed only after implementing the request; the browser removes its submitted sketches if their revisions are unchanged.",
     inputSchema: {
+      ...scopeInput,
       requestId: external_exports.string().min(1).max(256),
       status: external_exports.enum(["working", "completed", "failed", "interrupted"]),
       summary: external_exports.string().max(32e3).optional(),
@@ -23089,8 +23260,8 @@ function installTools(mcpServer, bridge) {
       ...args.error === void 0 ? {} : { error: args.error }
     };
     try {
-      const updated = await bridge.updateRequestStatus(update);
-      return textResult(updated ?? await bridge.getStatus());
+      const updated = await (await target(args)).updateRequestStatus(update);
+      return textResult(updated ?? await (await target(args)).getStatus());
     } catch (error2) {
       return errorResult(error2);
     }
@@ -23100,9 +23271,9 @@ function installTools(mcpServer, bridge) {
     description: "Read the paired browser's current Canvas groups and focus.",
     inputSchema: emptyInput,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
-  }, async () => {
+  }, async (args) => {
     try {
-      return commandResult(await bridge.dispatchCanvasCommand({ type: "read-state" }));
+      return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "read-state" }));
     } catch (error2) {
       return errorResult(error2);
     }
@@ -23111,6 +23282,7 @@ function installTools(mcpServer, bridge) {
     title: "Present routes in Canvas",
     description: "Append or focus an agent-owned, labeled comparison group of same-origin project routes in Canvas.",
     inputSchema: {
+      ...scopeInput,
       label: external_exports.string().min(1).max(160),
       groupId: external_exports.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/).optional(),
       routes: external_exports.array(external_exports.object({
@@ -23122,7 +23294,7 @@ function installTools(mcpServer, bridge) {
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
   }, async (args) => {
     try {
-      return commandResult(await bridge.dispatchCanvasCommand({
+      return commandResult(await (await target(args)).dispatchCanvasCommand({
         type: "present-routes",
         groupId: args.groupId ?? `agent-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
         label: args.label,
@@ -23135,11 +23307,11 @@ function installTools(mcpServer, bridge) {
   mcpServer.registerTool("nudge_focus_canvas_group", {
     title: "Focus Canvas group",
     description: "Focus an existing Canvas comparison group by its stable group ID.",
-    inputSchema: { groupId: external_exports.string().min(1).max(256) },
+    inputSchema: { ...scopeInput, groupId: external_exports.string().min(1).max(256) },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
   }, async (args) => {
     try {
-      return commandResult(await bridge.dispatchCanvasCommand({ type: "focus-group", groupId: args.groupId }));
+      return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "focus-group", groupId: args.groupId }));
     } catch (error2) {
       return errorResult(error2);
     }
@@ -23149,9 +23321,9 @@ function installTools(mcpServer, bridge) {
     description: "Fit all current Canvas cards into the browser board.",
     inputSchema: emptyInput,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
-  }, async () => {
+  }, async (args) => {
     try {
-      return commandResult(await bridge.dispatchCanvasCommand({ type: "fit-all" }));
+      return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "fit-all" }));
     } catch (error2) {
       return errorResult(error2);
     }
@@ -23159,11 +23331,11 @@ function installTools(mcpServer, bridge) {
   mcpServer.registerTool("nudge_remove_canvas_group", {
     title: "Remove agent Canvas group",
     description: "Remove an agent-owned Canvas comparison group. The browser refuses removal of user-owned groups.",
-    inputSchema: { groupId: external_exports.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/) },
+    inputSchema: { ...scopeInput, groupId: external_exports.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/) },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
   }, async (args) => {
     try {
-      return commandResult(await bridge.dispatchCanvasCommand({ type: "remove-group", groupId: args.groupId }));
+      return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "remove-group", groupId: args.groupId }));
     } catch (error2) {
       return errorResult(error2);
     }
@@ -23221,7 +23393,8 @@ function createAgentCompanion(options) {
   };
 }
 async function createDiscoveredAgentAdapter(options) {
-  const router = await DiscoveredProjectRouter.create(options.workspaceRoot, options.registryRoot);
+  const routing = options.workspaceRoot === void 0 ? new AdapterRouting(options.registryRoot) : void 0;
+  const router = options.workspaceRoot === void 0 ? void 0 : await DiscoveredProjectRouter.create(options.workspaceRoot, options.registryRoot);
   const mcpServer = new McpServer(
     {
       name: options.serverName ?? MCP_SERVER_NAME,
@@ -23229,13 +23402,13 @@ async function createDiscoveredAgentAdapter(options) {
     },
     { instructions: MCP_SERVER_INSTRUCTIONS }
   );
-  installTools(mcpServer, router);
+  installTools(mcpServer, router, routing);
   let transport = null;
   let started = false;
   let closePromise = null;
   return {
     mcpServer,
-    router,
+    router: router ?? routing,
     async start(providedTransport) {
       if (started) return;
       if (closePromise) throw new Error("The Nudge MCP adapter is closing.");
@@ -23246,7 +23419,7 @@ async function createDiscoveredAgentAdapter(options) {
     close() {
       if (closePromise) return closePromise;
       closePromise = (async () => {
-        await router.close();
+        await (router ?? routing).close();
         if (transport) await mcpServer.close().catch(() => void 0);
       })();
       return closePromise;
@@ -23309,7 +23482,7 @@ function parseCliArguments(argv = process.argv.slice(2), environment = process.e
   let host = environment.NUDGE_UI_BRIDGE_HOST ?? "127.0.0.1";
   let port = environment.NUDGE_UI_BRIDGE_PORT === void 0 ? DEFAULT_PORT : parseInteger(environment.NUDGE_UI_BRIDGE_PORT, "NUDGE_UI_BRIDGE_PORT", 65535);
   let commandTimeoutMs = environment.NUDGE_UI_COMMAND_TIMEOUT_MS === void 0 ? DEFAULT_COMMAND_TIMEOUT_MS2 : parseInteger(environment.NUDGE_UI_COMMAND_TIMEOUT_MS, "NUDGE_UI_COMMAND_TIMEOUT_MS", 6e4);
-  let workspaceRoot = root;
+  let workspaceRoot = environment.NUDGE_UI_WORKSPACE_ROOT === void 0 ? void 0 : root;
   let help = false;
   let explicitPort = environment.NUDGE_UI_BRIDGE_PORT !== void 0;
   for (let index = 0; index < argumentsToParse.length; index += 1) {
@@ -23366,7 +23539,7 @@ running project unless --origin selects the legacy coupled mode.
 Options:
   --project-id <id>             Stable project pairing identity
   --origin <origin>             Exact app origin required for browser pairing
-  --workspace-root <path>       Project root supplied to the agent
+  --workspace-root <path>       Optional legacy project restriction; omitted for reusable adapters
   --host <loopback>             127.0.0.1, ::1, or localhost
   --port <port>                 Bridge port; default is deterministic per project, 0 is ephemeral
   --command-timeout-ms <ms>     Canvas acknowledgement timeout
@@ -23380,12 +23553,18 @@ async function runCli(argv = process.argv.slice(2), environment = process.env) {
   }
   if (options.command === "doctor") {
     const sessions = await discoverProjectSessions(options.workspaceRoot);
-    const matches = sessions.filter((session) => session.matchesApplication);
+    const matches = sessions.filter((session) => options.workspaceRoot === void 0 || session.matchesApplication);
+    const diagnostics = await diagnoseProjectSessions(options.workspaceRoot);
     process.stdout.write([
-      `[nudge-ui] workspace: ${options.workspaceRoot}`,
+      `[nudge-ui] registry: ${diagnostics.registryRoot}`,
+      `[nudge-ui] workspace: ${diagnostics.workspaceRoot ?? "all projects"}`,
+      `[nudge-ui] application: ${diagnostics.applicationRoot ?? "all applications"}`,
+      `[nudge-ui] descriptors: ${diagnostics.descriptorCount}; invalid: ${diagnostics.invalidCount}; incompatible: ${diagnostics.incompatibleCount}`,
+      `[nudge-ui] matching unreachable descriptors: ${diagnostics.matchingUnreachableCount}`,
+      ...diagnostics.guidance.map((message) => `[nudge-ui] ${message}`),
       `[nudge-ui] live sessions: ${sessions.length}`,
       `[nudge-ui] matching sessions: ${matches.length}`,
-      ...matches.length === 0 ? ["[nudge-ui] no matching project bridge is running; start the development server to make Nudge available"] : matches.map((session) => {
+      ...matches.length === 0 ? ["[nudge-ui] no reachable compatible bridge matches; inspect the diagnostics above or start the development server"] : matches.map((session) => {
         const state = session.status.connection === "working" ? "working" : session.status.listenerActive ? "listening" : "available";
         return `[nudge-ui] ${state}: ${session.projectId} (${session.origin})${session.claimed ? " [claimed]" : ""}`;
       })
@@ -23419,8 +23598,10 @@ async function runCli(argv = process.argv.slice(2), environment = process.env) {
     }
     return;
   }
+  process.stderr.write("[nudge-ui] --origin uses deprecated coupled mode. Rerun agent setup to use project-owned bridges and avoid port collisions.\n");
   const companion = createAgentCompanion({
     ...options,
+    workspaceRoot: options.workspaceRoot ?? resolve4(environment.INIT_CWD ?? process.cwd()),
     onControllerUnavailable: (pageUrl) => openPairedPage(pageUrl).then(() => void 0)
   });
   let stopping = false;

package/dist/discovery.d.ts

@@ -1,13 +1,13 @@
 import type { AgentPromptRequest, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult } from "./internal/agent-protocol.js";
 import type { CanvasCommandInput } from "./bridge.js";
-import { type ProjectSession } from "./project.js";
+import { type ProjectSession, type StoredProjectSession } from "./project.js";
 export interface DiscoveredProjectSession extends ProjectSession {
     readonly matchesWorkspace: boolean;
     readonly matchesApplication: boolean;
     readonly claimed: boolean;
     readonly status: Pick<AgentStatusSnapshot, "connection" | "listenerActive" | "paired">;
 }
-export declare function discoverProjectSessions(applicationRoot: string, registryRoot?: string): Promise<DiscoveredProjectSession[]>;
+export declare function discoverProjectSessions(applicationRoot: string | undefined, registryRoot?: string): Promise<DiscoveredProjectSession[]>;
 /** Routes MCP tools to a live project in the adapter's exact worktree. */
 export declare class DiscoveredProjectRouter {
     readonly workspaceRoot: string;
@@ -16,10 +16,14 @@ export declare class DiscoveredProjectRouter {
     readonly agentId: string;
     private client;
     private releaseGeneration;
+    private connectionQueue;
     private constructor();
+    get selectedSessionId(): string | undefined;
+    static forSession(session: StoredProjectSession, registryRoot: string): DiscoveredProjectRouter;
     static create(workspaceRoot: string, registryRoot?: string): Promise<DiscoveredProjectRouter>;
     listSessions(): Promise<DiscoveredProjectSession[]>;
     private connectToSession;
+    private selectSession;
     waitForPrompt(signal?: AbortSignal, sessionId?: string): Promise<AgentPromptRequest>;
     getStatus(): Promise<AgentStatusSnapshot>;
     updateRequestStatus(update: AgentStatusUpdate): Promise<AgentStatusSnapshot>;
@@ -27,3 +31,16 @@ export declare class DiscoveredProjectRouter {
     release(): Promise<void>;
     close(): Promise<void>;
 }
+/** Returns diagnostic counts, scope, and public paths without exposing registry credentials. */
+export declare function diagnoseProjectSessions(applicationRoot?: string, registryRoot?: string): Promise<{
+    registryRoot: string;
+    workspaceRoot: string | undefined;
+    applicationRoot: string | undefined;
+    descriptorCount: number;
+    invalidCount: number;
+    incompatibleCount: number;
+    reachableCount: number;
+    matchingReachableCount: number;
+    matchingUnreachableCount: number;
+    guidance: string[];
+}>;