@nudge-ui/mcp 0.2.0 → 0.2.2

package/dist/bridge.js

@@ -1,10 +1,12 @@
 import { createServer, } from "node:http";
 import { randomBytes, randomUUID } from "node:crypto";
-import { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, canonicalOrigin, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isSameOriginRoute, validateRoutes, } from "./internal/agent-protocol.js";
-import { BRIDGE_ENDPOINTS } from "./protocol.js";
+import { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, canonicalOrigin, isAgentStatusUpdate, isAllowedOrigin, isCanvasCommand, isCanvasGroup, isCanvasState, isSameOriginRoute, validateSketchAttachments, validateRoutes, } from "./internal/agent-protocol.js";
+import { AGENT_CONTROL_ENDPOINTS, BRIDGE_ENDPOINTS } from "./protocol.js";
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
 const MAX_BODY_BYTES = 256 * 1024;
+const MAX_PROMPT_BODY_BYTES = 12 * 1024 * 1024;
 const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
+const AGENT_CLAIM_TIMEOUT_MS = 30_000;
 const SYSTEM_CLOCK = {
     now: () => Date.now(),
     setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
@@ -85,13 +87,13 @@ function sendError(response, error, origin) {
     }
     sendJson(response, 500, { error: { code: "internal_error", message: "The bridge could not complete the request." } }, origin);
 }
-async function readJsonBody(request) {
+async function readJsonBody(request, maxBytes = MAX_BODY_BYTES) {
     const chunks = [];
     let total = 0;
     for await (const chunk of request) {
         const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
         total += buffer.length;
-        if (total > MAX_BODY_BYTES) {
+        if (total > maxBytes) {
             throw new BridgeRequestError(413, "body_too_large", "The bridge request body is too large.");
         }
         chunks.push(buffer);
@@ -110,6 +112,37 @@ async function readJsonBody(request) {
     }
     return parsed;
 }
+function pngDimensions(bytes) {
+    if (bytes.length < 24
+        || !bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+        || bytes.toString("ascii", 12, 16) !== "IHDR")
+        return null;
+    return {
+        width: bytes.readUInt32BE(16),
+        height: bytes.readUInt32BE(20),
+    };
+}
+function parseSketchAttachments(value) {
+    let attachments;
+    try {
+        attachments = validateSketchAttachments(value);
+    }
+    catch (error) {
+        throw new BridgeRequestError(400, "invalid_sketches", error instanceof Error ? error.message : "Sketch attachments are invalid.");
+    }
+    for (const [index, attachment] of attachments.entries()) {
+        const bytes = Buffer.from(attachment.data, "base64");
+        if (bytes.length !== attachment.byteSize || bytes.toString("base64") !== attachment.data) {
+            throw new BridgeRequestError(400, "invalid_sketches", `attachments[${index}] is not canonical base64 PNG data.`);
+        }
+        const dimensions = pngDimensions(bytes);
+        if (!dimensions || dimensions.width !== attachment.width || dimensions.height !== attachment.height
+            || dimensions.width > 2_048 || dimensions.height > 2_048) {
+            throw new BridgeRequestError(400, "invalid_sketches", `attachments[${index}] has invalid PNG dimensions.`);
+        }
+    }
+    return attachments;
+}
 function createEnvelope(projectId, sessionToken, event) {
     return {
         protocolVersion: AGENT_PROTOCOL_VERSION,
@@ -165,7 +198,10 @@ export function createLoopbackBridge(options) {
     if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000) {
         throw new TypeError("commandTimeoutMs must be between 1 and 60000 milliseconds");
     }
-    const allowedOrigins = (options.allowedOrigins ?? (configuredOrigin ? [configuredOrigin] : [])).map((candidate) => canonicalOrigin(candidate));
+    const allowedOrigins = [
+        ...(configuredOrigin ? [configuredOrigin] : []),
+        ...(options.allowedOrigins ?? []),
+    ].map((candidate) => canonicalOrigin(candidate));
     if (allowedOrigins.some((candidate) => candidate === null)) {
         throw new TypeError("allowedOrigins must contain canonical HTTP(S) origins");
     }
@@ -173,6 +209,10 @@ export function createLoopbackBridge(options) {
     const clock = options.clock ?? SYSTEM_CLOCK;
     const tokenFactory = options.tokenFactory ?? randomToken;
     const idFactory = options.idFactory ?? randomId;
+    const agentControlToken = options.agentControlToken;
+    if (agentControlToken !== undefined && (agentControlToken.length < 32 || agentControlToken.length > 256)) {
+        throw new TypeError("agentControlToken must contain between 32 and 256 characters");
+    }
     let lifecycle = "created";
     let currentAddress = null;
     let sessionToken = null;
@@ -184,6 +224,9 @@ export function createLoopbackBridge(options) {
     let pendingCanvas = null;
     let closePromise = null;
     let startPromise = null;
+    let agentOwner = null;
+    let agentOwnerSeenAt = 0;
+    let agentOwnerExpiry = null;
     const getStatus = () => statusWith(options.projectId, listener !== null, sessionToken !== null, currentRequest, lastPageUrl);
     const broadcast = (event) => {
         if (!sessionToken)
@@ -261,13 +304,13 @@ export function createLoopbackBridge(options) {
         sendJson(response, 200, {
             protocolVersion: AGENT_PROTOCOL_VERSION,
             projectId: options.projectId,
-            origin: configuredOrigin ?? pairedOrigin,
+            origin: incomingOrigin,
             status: getStatus(),
             sessionRequired: true,
             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.");
         }
@@ -278,7 +321,7 @@ export function createLoopbackBridge(options) {
         const body = await readJsonBody(request);
         parseProjectId(typeof body.projectId === "string" ? body.projectId : null, options.projectId);
         const requestedOrigin = canonicalOrigin(body.origin);
-        if (!requestedOrigin || requestedOrigin !== incomingOrigin || (configuredOrigin !== null && requestedOrigin !== configuredOrigin)) {
+        if (!requestedOrigin || requestedOrigin !== incomingOrigin) {
             throw new BridgeRequestError(403, "origin_mismatch", "Pairing requires an explicitly configured project origin.");
         }
         let requestedPageUrl;
@@ -289,8 +332,25 @@ export 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) {
-            throw new BridgeRequestError(409, "already_paired", "A browser is already paired with this project.");
+            if (body.sessionToken !== sessionToken) {
+                throw new BridgeRequestError(409, "already_paired", "A browser is already paired with this project.");
+            }
+            lastPageUrl = requestedPageUrl ?? lastPageUrl;
+            const existing = {
+                protocolVersion: AGENT_PROTOCOL_VERSION,
+                projectId: options.projectId,
+                origin: pairedOrigin,
+                sessionToken,
+                ...(lastPageUrl === null ? {} : { pageUrl: lastPageUrl }),
+                status: getStatus(),
+            };
+            sendJson(response, 200, existing, incomingOrigin);
+            return;
         }
         sessionToken = tokenFactory();
         if (!sessionToken || sessionToken.length > AGENT_PROTOCOL_LIMITS.sessionToken) {
@@ -303,7 +363,7 @@ export function createLoopbackBridge(options) {
         const result = {
             protocolVersion: AGENT_PROTOCOL_VERSION,
             projectId: options.projectId,
-            origin: configuredOrigin ?? pairedOrigin,
+            origin: pairedOrigin,
             sessionToken,
             ...(lastPageUrl === null ? {} : { pageUrl: lastPageUrl }),
             status: getStatus(),
@@ -311,6 +371,15 @@ export function createLoopbackBridge(options) {
         sendJson(response, 200, result, incomingOrigin);
         broadcastStatus();
     };
+    const handleTakeover = async (request, response) => {
+        const { incomingOrigin, requestedPageUrl } = await readPairRequest(request);
+        // Takeover is intentionally separate from normal pairing. The caller has
+        // made an explicit UI choice to revoke the existing browser session.
+        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);
@@ -338,7 +407,7 @@ export function createLoopbackBridge(options) {
         sendJson(response, 200, getStatus(), incomingOrigin);
     };
     const handlePrompt = async (request, response) => {
-        const body = await readJsonBody(request);
+        const body = await readJsonBody(request, MAX_PROMPT_BODY_BYTES);
         const incomingOrigin = requireBrowserRequest(request, new URL("http://bridge.invalid"), body.sessionToken);
         parseProjectId(typeof body.projectId === "string" ? body.projectId : null, options.projectId);
         if (typeof body.prompt !== "string" || body.prompt.length === 0 || body.prompt.length > AGENT_PROTOCOL_LIMITS.prompt) {
@@ -348,6 +417,13 @@ export function createLoopbackBridge(options) {
             && (!Number.isSafeInteger(body.changeRevision) || body.changeRevision < 0)) {
             throw new BridgeRequestError(400, "invalid_revision", "changeRevision must be a non-negative safe integer");
         }
+        if (body.clientDispatchId !== undefined
+            && (typeof body.clientDispatchId !== "string"
+                || body.clientDispatchId.length === 0
+                || body.clientDispatchId.length > AGENT_PROTOCOL_LIMITS.clientDispatchId)) {
+            throw new BridgeRequestError(400, "invalid_dispatch_id", "clientDispatchId must be a bounded non-empty string");
+        }
+        const attachments = parseSketchAttachments(body.attachments);
         if (!listener) {
             throw new BridgeRequestError(409, "listener_unavailable", "The agent has not opened a listening call.");
         }
@@ -359,13 +435,19 @@ export function createLoopbackBridge(options) {
             projectId: options.projectId,
             prompt: body.prompt,
             ...(body.changeRevision === undefined ? {} : { changeRevision: body.changeRevision }),
+            ...(body.clientDispatchId === undefined ? {} : { clientDispatchId: body.clientDispatchId }),
+            ...(attachments.length === 0 ? {} : { sketches: attachments.map(({ data: _data, ...metadata }) => metadata) }),
+        };
+        const delivered = {
+            ...prompt,
+            ...(attachments.length === 0 ? {} : { attachments }),
         };
         const pending = listener;
         listener = null;
         if (pending.abortHandler && pending.signal)
             pending.signal.removeEventListener("abort", pending.abortHandler);
         currentRequest = { ...prompt, status: "working" };
-        pending.resolve(prompt);
+        pending.resolve(delivered);
         const result = { request: prompt, status: "working" };
         sendJson(response, 202, result, incomingOrigin);
         broadcastStatus();
@@ -426,9 +508,160 @@ export function createLoopbackBridge(options) {
         disconnectBrowser(body.sessionToken);
         sendJson(response, 200, { disconnected: true }, incomingOrigin);
     };
+    const requireAgentControl = (request, bodyAgentId) => {
+        if (!agentControlToken || !loopbackAddress(request.socket.remoteAddress)) {
+            throw new BridgeRequestError(403, "agent_control_unavailable", "Private agent control is unavailable.");
+        }
+        if (headerValue(request, "authorization") !== `Bearer ${agentControlToken}`) {
+            throw new BridgeRequestError(401, "invalid_agent_credential", "The agent control credential is invalid.");
+        }
+        if (bodyAgentId === undefined)
+            return null;
+        if (typeof bodyAgentId !== "string" || bodyAgentId.length === 0 || bodyAgentId.length > 256) {
+            throw new BridgeRequestError(400, "invalid_agent_id", "agentId must be a bounded non-empty string.");
+        }
+        return bodyAgentId;
+    };
+    const requireAgentOwner = (request, body) => {
+        const agentId = requireAgentControl(request, body.agentId);
+        if (!agentId || agentOwner !== agentId) {
+            throw new BridgeRequestError(409, "agent_not_owner", "This MCP adapter does not own the project session.");
+        }
+        agentOwnerSeenAt = clock.now();
+        scheduleAgentOwnerExpiry();
+        return agentId;
+    };
+    const releaseAgentOwner = (reason) => {
+        if (agentOwnerExpiry !== null)
+            clock.clearTimeout(agentOwnerExpiry);
+        agentOwnerExpiry = null;
+        agentOwner = null;
+        agentOwnerSeenAt = 0;
+        cancelListener(reason);
+        if (currentRequest?.status === "working") {
+            currentRequest = { ...currentRequest, status: "interrupted", error: reason };
+            broadcastStatus();
+        }
+        if (pendingCanvas) {
+            const pendingCommand = pendingCanvas;
+            pendingCanvas = null;
+            clock.clearTimeout(pendingCommand.timeout);
+            pendingCommand.resolve({
+                commandId: pendingCommand.command.commandId,
+                ok: false,
+                error: { code: "agent_released", message: reason },
+            });
+        }
+    };
+    const scheduleAgentOwnerExpiry = () => {
+        if (agentOwnerExpiry !== null)
+            clock.clearTimeout(agentOwnerExpiry);
+        const expectedOwner = agentOwner;
+        if (!expectedOwner) {
+            agentOwnerExpiry = null;
+            return;
+        }
+        const expireIfStale = () => {
+            agentOwnerExpiry = null;
+            if (agentOwner !== expectedOwner)
+                return;
+            const remaining = AGENT_CLAIM_TIMEOUT_MS - (clock.now() - agentOwnerSeenAt);
+            if (remaining > 0) {
+                agentOwnerExpiry = clock.setTimeout(expireIfStale, remaining);
+                return;
+            }
+            releaseAgentOwner("The MCP adapter claim expired.");
+        };
+        agentOwnerExpiry = clock.setTimeout(expireIfStale, AGENT_CLAIM_TIMEOUT_MS);
+    };
+    const handleAgentClaim = async (request, response) => {
+        const body = await readJsonBody(request);
+        const agentId = requireAgentControl(request, body.agentId);
+        if (!agentId)
+            throw new BridgeRequestError(400, "invalid_agent_id", "agentId is required.");
+        if (agentOwner && agentOwner !== agentId && clock.now() - agentOwnerSeenAt <= AGENT_CLAIM_TIMEOUT_MS) {
+            throw new BridgeRequestError(409, "session_claimed", "Another MCP adapter owns this project session.");
+        }
+        if (agentOwner && agentOwner !== agentId)
+            releaseAgentOwner("The previous MCP adapter claim expired.");
+        agentOwner = agentId;
+        agentOwnerSeenAt = clock.now();
+        scheduleAgentOwnerExpiry();
+        sendJson(response, 200, { claimed: true }, null);
+    };
+    const handleAgentRelease = async (request, response) => {
+        const body = await readJsonBody(request);
+        const agentId = requireAgentOwner(request, body);
+        releaseAgentOwner(`Agent ${agentId} released the project session.`);
+        sendJson(response, 200, { released: true }, null);
+    };
+    const handleAgentListen = async (request, response) => {
+        const body = await readJsonBody(request);
+        requireAgentOwner(request, body);
+        const abort = new AbortController();
+        response.once("close", () => abort.abort());
+        const prompt = await waitForPrompt(abort.signal);
+        sendJson(response, 200, prompt, null);
+    };
+    const handleAgentReportStatus = async (request, response) => {
+        const body = await readJsonBody(request);
+        requireAgentOwner(request, body);
+        if (!isAgentStatusUpdate(body.update)) {
+            throw new BridgeRequestError(400, "invalid_status", "update must be a valid agent status update.");
+        }
+        updateRequestStatus(body.update);
+        sendJson(response, 200, getStatus(), null);
+    };
+    const handleAgentCanvas = async (request, response) => {
+        const body = await readJsonBody(request);
+        requireAgentOwner(request, body);
+        if (!isCanvasCommand(body.command)) {
+            throw new BridgeRequestError(400, "invalid_canvas_command", "command must be a valid Canvas command.");
+        }
+        sendJson(response, 200, await dispatchCanvasCommand(body.command), null);
+    };
     const httpServer = createServer((request, response) => {
         void (async () => {
             const url = new URL(request.url ?? "/", `http://${host}:${port}`);
+            if (request.method === "GET" && url.pathname === AGENT_CONTROL_ENDPOINTS.health) {
+                requireAgentControl(request);
+                sendJson(response, 200, { projectId: options.projectId, available: true, claimed: agentOwner !== null, status: getStatus() }, null);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.claim) {
+                await handleAgentClaim(request, response);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.release) {
+                await handleAgentRelease(request, response);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.heartbeat) {
+                const body = await readJsonBody(request);
+                requireAgentOwner(request, body);
+                sendJson(response, 200, { alive: true }, null);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.listen) {
+                await handleAgentListen(request, response);
+                return;
+            }
+            if (request.method === "GET" && url.pathname === AGENT_CONTROL_ENDPOINTS.status) {
+                const agentId = url.searchParams.get("agentId");
+                requireAgentControl(request, agentId);
+                if (agentOwner !== agentId)
+                    throw new BridgeRequestError(409, "agent_not_owner", "This MCP adapter does not own the project session.");
+                sendJson(response, 200, getStatus(), null);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.reportStatus) {
+                await handleAgentReportStatus(request, response);
+                return;
+            }
+            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.canvas) {
+                await handleAgentCanvas(request, response);
+                return;
+            }
             if (request.method === "OPTIONS") {
                 handleOptions(request, response);
                 return;
@@ -441,6 +674,10 @@ export 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;
@@ -508,7 +745,7 @@ export function createLoopbackBridge(options) {
         listener = null;
         if (pending.abortHandler && pending.signal)
             pending.signal.removeEventListener("abort", pending.abortHandler);
-        pending.reject(new Error(reason));
+        pending.reject(new BridgeRequestError(409, "listener_cancelled", reason));
         broadcastStatus();
     };
     const waitForPrompt = (signal) => {
@@ -618,9 +855,6 @@ export function createLoopbackBridge(options) {
         // This method is the explicit host-side approval path. A bridge without
         // an HTTP allow-list can still be paired by trusted host code, while all
         // browser-originated requests remain closed until that approval exists.
-        if (configuredOrigin !== null && requestCanonicalOrigin !== configuredOrigin) {
-            throw new Error("Browser origin does not match this bridge");
-        }
         if (canonicalAllowedOrigins.length > 0 && !originIsAllowed(requestCanonicalOrigin)) {
             throw new Error("Browser origin is not in the configured allow-list");
         }
@@ -683,6 +917,11 @@ export function createLoopbackBridge(options) {
         if (closePromise)
             return closePromise;
         lifecycle = "closed";
+        if (agentOwnerExpiry !== null)
+            clock.clearTimeout(agentOwnerExpiry);
+        agentOwnerExpiry = null;
+        agentOwner = null;
+        agentOwnerSeenAt = 0;
         cancelListener("bridge_closed");
         if (pendingCanvas) {
             clock.clearTimeout(pendingCanvas.timeout);

package/dist/cli.d.ts

@@ -1,8 +1,9 @@
 import { type ChildProcess } from "node:child_process";
 export interface CliOptions {
+    readonly command: "serve" | "doctor";
     readonly projectId: string;
     readonly origin?: string;
-    readonly workspaceRoot: string;
+    readonly workspaceRoot?: string;
     readonly host: "127.0.0.1" | "::1" | "localhost";
     readonly port: number;
     readonly commandTimeoutMs: number;
@@ -31,6 +32,6 @@ export interface PageLaunchDependencies {
 export declare function openPairedPage(pageUrl: string, dependencies?: PageLaunchDependencies): Promise<boolean>;
 /** Parses only project-scoped, host-neutral CLI options. */
 export declare function parseCliArguments(argv?: readonly string[], environment?: CliEnvironment): CliOptions;
-export declare const CLI_USAGE = "Usage: nudge-mcp [options]\n\nStarts a project-scoped standard MCP stdio server and loopback browser bridge.\n\nOptions:\n  --project-id <id>             Stable project pairing identity\n  --origin <origin>             Exact app origin required for browser pairing\n  --workspace-root <path>       Project root supplied to the agent\n  --host <loopback>             127.0.0.1, ::1, or localhost\n  --port <port>                 Bridge port; default is deterministic per project, 0 is ephemeral\n  --command-timeout-ms <ms>     Canvas acknowledgement timeout\n  --help                        Show this message\n";
+export declare const CLI_USAGE = "Usage: nudge-mcp [doctor] [options]\n\nStarts a standard MCP stdio adapter. It discovers the bridge owned by the\nrunning project unless --origin selects the legacy coupled mode.\n\nOptions:\n  --project-id <id>             Stable project pairing identity\n  --origin <origin>             Exact app origin required for browser pairing\n  --workspace-root <path>       Optional legacy project restriction; omitted for reusable adapters\n  --host <loopback>             127.0.0.1, ::1, or localhost\n  --port <port>                 Bridge port; default is deterministic per project, 0 is ephemeral\n  --command-timeout-ms <ms>     Canvas acknowledgement timeout\n  --help                        Show this message\n";
 /** Runs the CLI until the stdio MCP connection closes or the process stops. */
 export declare function runCli(argv?: readonly string[], environment?: CliEnvironment): Promise<void>;

package/dist/cli.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { basename, resolve } from "node:path";
 import { defaultBridgePort } from "./internal/agent-protocol.js";
-import { createAgentCompanion } from "./server.js";
+import { diagnoseProjectSessions, discoverProjectSessions } from "./discovery.js";
+import { createAgentCompanion, createDiscoveredAgentAdapter, } from "./server.js";
 const DEFAULT_PORT = 0;
 const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
 const PAGE_PROBE_TIMEOUT_MS = 1_500;
@@ -59,6 +60,8 @@ function parseInteger(value, flag, maximum) {
 }
 /** Parses only project-scoped, host-neutral CLI options. */
 export function parseCliArguments(argv = process.argv.slice(2), environment = process.env) {
+    const command = argv[0] === "doctor" ? "doctor" : "serve";
+    const argumentsToParse = command === "doctor" ? argv.slice(1) : argv;
     const root = resolve(environment.NUDGE_UI_WORKSPACE_ROOT ?? environment.INIT_CWD ?? process.cwd());
     let projectId = environment.NUDGE_UI_PROJECT_ID ?? projectIdFor(root);
     let origin = environment.NUDGE_UI_ORIGIN;
@@ -70,30 +73,30 @@ export function parseCliArguments(argv = process.argv.slice(2), environment = pr
     let commandTimeoutMs = environment.NUDGE_UI_COMMAND_TIMEOUT_MS === undefined
         ? DEFAULT_COMMAND_TIMEOUT_MS
         : parseInteger(environment.NUDGE_UI_COMMAND_TIMEOUT_MS, "NUDGE_UI_COMMAND_TIMEOUT_MS", 60_000);
-    let workspaceRoot = root;
+    let workspaceRoot = environment.NUDGE_UI_WORKSPACE_ROOT === undefined ? undefined : root;
     let help = false;
     let explicitPort = environment.NUDGE_UI_BRIDGE_PORT !== undefined;
-    for (let index = 0; index < argv.length; index += 1) {
-        const argument = argv[index];
+    for (let index = 0; index < argumentsToParse.length; index += 1) {
+        const argument = argumentsToParse[index];
         switch (argument) {
             case "--help":
             case "-h":
                 help = true;
                 break;
             case "--project-id":
-                projectId = valueAfter(argv, index, argument);
+                projectId = valueAfter(argumentsToParse, index, argument);
                 index += 1;
                 break;
             case "--origin":
-                origin = valueAfter(argv, index, argument);
+                origin = valueAfter(argumentsToParse, index, argument);
                 index += 1;
                 break;
             case "--workspace-root":
-                workspaceRoot = resolve(valueAfter(argv, index, argument));
+                workspaceRoot = resolve(valueAfter(argumentsToParse, index, argument));
                 index += 1;
                 break;
             case "--host": {
-                const candidate = valueAfter(argv, index, argument);
+                const candidate = valueAfter(argumentsToParse, index, argument);
                 if (candidate !== "127.0.0.1" && candidate !== "::1" && candidate !== "localhost") {
                     throw new TypeError("--host must be 127.0.0.1, ::1, or localhost");
                 }
@@ -102,12 +105,12 @@ export function parseCliArguments(argv = process.argv.slice(2), environment = pr
                 break;
             }
             case "--port":
-                port = parseInteger(valueAfter(argv, index, argument), argument, 65_535);
+                port = parseInteger(valueAfter(argumentsToParse, index, argument), argument, 65_535);
                 explicitPort = true;
                 index += 1;
                 break;
             case "--command-timeout-ms":
-                commandTimeoutMs = parseInteger(valueAfter(argv, index, argument), argument, 60_000);
+                commandTimeoutMs = parseInteger(valueAfter(argumentsToParse, index, argument), argument, 60_000);
                 if (commandTimeoutMs === 0)
                     throw new TypeError("--command-timeout-ms must be greater than zero");
                 index += 1;
@@ -120,16 +123,17 @@ export function parseCliArguments(argv = process.argv.slice(2), environment = pr
         throw new TypeError("--project-id must be a bounded non-empty string");
     if (!explicitPort)
         port = defaultBridgePort(projectId);
-    return { projectId, origin, workspaceRoot, host, port, commandTimeoutMs, help };
+    return { command, projectId, origin, workspaceRoot, host, port, commandTimeoutMs, help };
 }
-export const CLI_USAGE = `Usage: nudge-mcp [options]
+export const CLI_USAGE = `Usage: nudge-mcp [doctor] [options]
 
-Starts a project-scoped standard MCP stdio server and loopback browser bridge.
+Starts a standard MCP stdio adapter. It discovers the bridge owned by the
+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
@@ -142,8 +146,65 @@ export async function runCli(argv = process.argv.slice(2), environment = process
         process.stdout.write(CLI_USAGE);
         return;
     }
+    if (options.command === "doctor") {
+        const sessions = await discoverProjectSessions(options.workspaceRoot);
+        const matches = sessions.filter((session) => options.workspaceRoot === undefined || session.matchesApplication);
+        const diagnostics = await diagnoseProjectSessions(options.workspaceRoot);
+        process.stdout.write([
+            `[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 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]" : ""}`;
+                })),
+        ].join("\n") + "\n");
+        return;
+    }
+    if (!options.origin) {
+        const adapter = await createDiscoveredAgentAdapter({ workspaceRoot: options.workspaceRoot });
+        let stopping = false;
+        let resolveAdapterWait = null;
+        const stop = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            void adapter.close();
+            resolveAdapterWait?.();
+        };
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        try {
+            await adapter.start();
+            await new Promise((resolveAdapter) => {
+                const finish = () => resolveAdapter();
+                // Keep a direct resolver so signal handlers terminate even though
+                // installing a signal handler suppresses Node's default process exit.
+                resolveAdapterWait = finish;
+                process.stdin.once("end", finish);
+                process.once("exit", finish);
+            });
+        }
+        finally {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+            await adapter.close();
+        }
+        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 ?? resolve(environment.INIT_CWD ?? process.cwd()),
         onControllerUnavailable: (pageUrl) => openPairedPage(pageUrl).then(() => undefined),
     });
     let stopping = false;