@nudge-ui/mcp 0.2.1 → 0.2.3

package/README.md

@@ -1,99 +1,127 @@
-# `@nudge-ui/mcp`
+# @nudge-ui/mcp
 
-> **Early alpha:** This integration can make breaking changes while host
-> support and the setup workflow stabilize.
+Send design changes from Nudge UI directly to your coding agent.
+`@nudge-ui/mcp` connects the browser editor to an MCP-capable agent so it can
+receive your edits, comments, and sketches, implement them, and report progress
+back to the editor.
 
-`@nudge-ui/mcp` connects a local Nudge inspector to an MCP-capable coding
-agent. The development server owns the browser bridge. The agent host starts a
-small stdio adapter that discovers live bridges in the current checkout or Git
-worktree.
+It also lets the agent present app routes as labeled comparison groups in
+Canvas. For example, ask it to create design variations and show them side by
+side for review.
 
-## Configure an agent
+This package is an optional companion to
+[`nudge-ui`](https://www.npmjs.com/package/nudge-ui). You can use Nudge's copied
+prompts without installing it.
 
-The Nudge initializer can install the dependency and configure supported agent
-hosts. A manual project-scoped configuration uses this command:
+> **Early alpha:** Host support and setup are still evolving. Expect breaking
+> changes and differences in how agent hosts handle long-running listening calls.
 
-```sh
-node ./node_modules/@nudge-ui/mcp/dist/cli.mjs --workspace-root /path/to/project
-```
-
-The adapter does not need an origin, port, project ID, or branch. A running
-development integration registers those values in a private per-user runtime
-directory. Restart the agent host after changing its MCP configuration, then
-ask it to **Listen to Nudge**. Agent configuration contains absolute checkout
-and application paths, so rerun agent setup in each clone or Git worktree that
-you intend the agent to edit.
+## Get started
 
-Run diagnostics without starting MCP stdio framing:
+If Nudge UI is already installed, run this from the application directory:
 
 ```sh
-node ./node_modules/@nudge-ui/mcp/dist/cli.mjs doctor --workspace-root /path/to/project
+npx nudge-ui agent setup
 ```
 
-The doctor reports live and exact-workspace session counts. It never prints
-control credentials.
+For a new Nudge installation, run `npm create nudge-ui@latest` and choose to
+connect a coding agent. To configure only the agent integration, use:
 
-## Project integration
+```sh
+npm create nudge-ui@latest -- --agent-only
+```
 
-Framework adapters start and stop the project bridge with the development
-server:
+Then:
+
+1. Fully restart your coding-agent host to load the MCP configuration.
+2. Start your app's development server and open Nudge in the browser.
+3. Ask the agent to **listen to Nudge in this workspace**.
+4. Make visual edits, add comments or sketches, and send the request from Nudge.
+
+The agent receives the request, applies it using its normal permissions and
+approval flow, verifies the result, reports status, and listens for the next
+request. Keep that agent turn active while sending changes. Delivery confirms
+that the agent received a request; it does not confirm implementation.
+
+## How it connects
+
+Setup installs two parts:
+
+- **Project bridge:** A local `@nudge-ui/mcp` development dependency. The Nudge
+  framework integration starts the bridge with your development server.
+- **Agent adapter:** A reusable MCP stdio process under `~/.nudge-ui/adapters/`,
+  registered globally with your selected agent hosts.
+
+The adapter discovers running apps through a private local session registry.
+It can serve multiple checkouts and Git worktrees without a separate agent
+registration for each one. Each app still needs its Nudge integration and
+bridge dependency. Setup requires npm for the reusable adapter, even if the app
+uses pnpm, Yarn, or Bun. The package requires Node.js 20 or later.
+
+## MCP tools
+
+| Tool | Purpose |
+| --- | --- |
+| `nudge_list_sessions` | Discover running apps in the requested workspace. |
+| `nudge_listen` | Wait for the next implementation request. `nudge_connect` is an alias. |
+| `nudge_get_status` | Read connection and request status. |
+| `nudge_report_activity` | Highlight Canvas frames associated with a file read or edit. |
+| `nudge_report_status` | Report working, completed, failed, or interrupted status. |
+| `nudge_read_canvas` | Read Canvas groups and focus. |
+| `nudge_present_routes` | Present same-origin app routes in a labeled comparison group. |
+| `nudge_focus_canvas_group` | Focus a comparison group. |
+| `nudge_fit_canvas` | Fit all frames into view. |
+| `nudge_remove_canvas_group` | Remove an agent-owned comparison group. |
+| `nudge_diagnose` | Diagnose local session discovery and connectivity. |
+| `nudge_release` | Stop listening and release the session for another agent. |
+
+Supply `workspaceRoot` on every tool call, using the absolute path of the
+checkout or application being edited. For example, call `nudge_list_sessions`
+with:
+
+```json
+{
+  "workspaceRoot": "/absolute/path/to/my-app"
+}
+```
 
-```ts
-import { startProjectBridge } from "@nudge-ui/mcp/project";
+If multiple sessions match, select the app's `sessionId` and include it on
+subsequent calls alongside `workspaceRoot`. The adapter does not infer the
+current project from its working directory or select a different checkout as
+a fallback. One adapter can claim a session at a time.
 
-const runtime = await startProjectBridge({
-  workspaceRoot: process.cwd(),
-  appRoot: process.cwd(),
-  projectId: "my-app",
-  origin: "http://localhost:5173",
-  allowedOrigins: ["http://127.0.0.1:5173"],
-});
+## Troubleshooting
 
-// Give browser code only these non-secret values.
-console.log(runtime.browser.bridgeUrl, runtime.browser.projectId);
+Run diagnostics from the app directory:
 
-await runtime.close();
+```sh
+npx nudge-ui agent doctor
 ```
 
-`origin` must be the actual canonical development origin after the framework
-chooses its port. `workspaceRoot` defaults to the Git worktree root when one is
-available and otherwise defaults to `appRoot`. `appRoot` distinguishes several
-applications running from one monorepo.
-
-Each live bridge registers a random session ID, canonical workspace and app
-paths, optional Git common directory and branch metadata, origin, and loopback
-endpoint. The descriptor is mode `0600` inside a mode `0700` registry. It also
-contains a private random credential used only between the bridge and adapter.
-
-The adapter lists all live local sessions through `nudge_list_sessions`, but it
-can listen only to sessions whose canonical workspace and configured
-application path match. An adapter configured at the worktree root can select
-any app in that worktree explicitly. A branch name or shared Git common
-directory never causes fallback to another worktree. When several apps run in
-one workspace, pass the chosen `sessionId` to `nudge_listen`. The adapter keeps
-that app selection across a bridge restart and does not replay old requests.
+Diagnostics report the registry path, workspace scope, reachable sessions, and
+invalid, unreachable, or incompatible registrations. If another agent owns the
+session, ask it to stop listening and call `nudge_release`.
 
-One adapter owns a selected project session until it closes. Other adapters
-receive a claimed-session error instead of taking browser work. A heartbeat
-allows the bridge to recover a claim after an adapter process is killed. Call
-`nudge_release` when the user stops listening so another adapter can claim the
-session without restarting the MCP host.
+After updating the adapter, fully restart the agent host. Updating the project's bridge dependency alone does not update the
+managed adapter. Update Nudge UI and rerun agent setup, or use the latest
+initializer's `--agent-only` mode to update the agent integration.
 
-## Legacy coupled mode
+The MCP adapter delivers requests through an active tool call. It cannot start
+a new agent turn after the host has ended the conversation or stopped waiting.
+If a listening call times out, ask the agent to listen again and adjust the
+host's MCP timeout if supported.
 
-Passing `--origin` retains the previous behavior in which the MCP process also
-owns its browser bridge:
+## Custom integrations
 
-```sh
-pnpm exec nudge-mcp \
-  --project-id my-app \
-  --origin http://localhost:5173 \
-  --workspace-root /path/to/my-app
-```
+Guided setup handles standard framework and agent integrations. For manual
+stdio configuration, the `startProjectBridge` API, local tarball testing,
+and OpenCode configuration, see
+the [coding-agent guide](https://github.com/charlessmart/nudge-ui/blob/main/docs/agent-integration.md).
 
-This mode remains available for custom integrations during migration. New
-framework integrations should use the project-owned bridge.
+## Links
 
-The agent calls `nudge_listen`, applies the delivered prompt, reports the
-result through `nudge_report_status`, and listens again. Canvas tools remain
-limited to routes from the paired application origin and agent-owned groups.
+[Nudge UI](https://www.npmjs.com/package/nudge-ui) ·
+[Initializer](https://www.npmjs.com/package/create-nudge-ui) ·
+[Repository](https://github.com/charlessmart/nudge-ui) ·
+[Issues](https://github.com/charlessmart/nudge-ui/issues) ·
+[MIT license](https://github.com/charlessmart/nudge-ui/blob/main/LICENSE)

package/dist/adapterRouting.d.ts

@@ -0,0 +1,16 @@
+import { DiscoveredProjectRouter } from "./discovery.js";
+export interface ProjectTarget {
+    readonly workspaceRoot?: string;
+    readonly sessionId?: string;
+}
+/** Keeps each explicit project selection independent for the lifetime of an MCP connection. */
+export declare class AdapterRouting {
+    readonly registryRoot: string;
+    private closing;
+    private readonly selections;
+    private readonly applications;
+    constructor(registryRoot?: string);
+    target({ workspaceRoot, sessionId }: ProjectTarget): Promise<DiscoveredProjectRouter>;
+    private select;
+    close(): Promise<void>;
+}

package/dist/adapterRouting.js

@@ -0,0 +1,59 @@
+import { realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { DiscoveredProjectRouter } from "./discovery.js";
+import { defaultSessionRegistryRoot, resolveWorkspaceRoot } from "./project.js";
+import { readLiveProjectSessions } from "./sessionRegistry.js";
+import { selectProjectSession } from "./sessionSelection.js";
+/** Keeps each explicit project selection independent for the lifetime of an MCP connection. */
+export class AdapterRouting {
+    registryRoot;
+    closing = false;
+    selections = new Map();
+    applications = new Map();
+    constructor(registryRoot = defaultSessionRegistryRoot()) {
+        this.registryRoot = registryRoot;
+    }
+    async target({ workspaceRoot, sessionId }) {
+        if (!workspaceRoot || !isAbsolute(workspaceRoot)) {
+            throw new Error("Supply workspaceRoot as the absolute path of the checkout or application you are editing.");
+        }
+        const applicationRoot = await realpath(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();
+    }
+}

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import { type Server } from "node:http";
-import type { AgentDeliveredPrompt, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "./internal/agent-protocol.js";
+import type { AgentActivity, AgentDeliveredPrompt, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "./internal/agent-protocol.js";
 /** A clock port keeps command timeout tests deterministic. */
 export interface BridgeClock {
     now(): number;
@@ -51,9 +51,11 @@ export interface BrowserBridge {
     start(): Promise<BridgeAddress>;
     close(): Promise<void>;
     /** Blocks until a paired browser dispatches a prompt. */
-    waitForPrompt(signal?: AbortSignal): Promise<AgentDeliveredPrompt>;
+    waitForPrompt(signal?: AbortSignal, sessionId?: string, agentClientName?: string): Promise<AgentDeliveredPrompt>;
     /** Marks the agent-side listener as stopped without ending the project. */
     cancelListener(reason?: string): void;
+    /** Emits temporary source attribution for the currently working request. */
+    reportActivity(activity: AgentActivity): void;
     /** Reports the terminal result for the currently running browser request. */
     updateRequestStatus(update: AgentStatusUpdate | AgentRequestOutcome): void;
     /** Sends a Canvas command to the browser and waits for one bounded ack. */

package/dist/bridge.js

@@ -1,6 +1,6 @@
 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, validateSketchAttachments, validateRoutes, } from "./internal/agent-protocol.js";
+import { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, canonicalOrigin, isAgentStatusUpdate, isAgentActivity, 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;
@@ -165,7 +165,7 @@ function connectionFor(listenerActive, paired, request) {
         return "listening";
     return "offline";
 }
-function statusWith(projectId, listenerActive, paired, request, pageUrl) {
+function statusWith(projectId, listenerActive, paired, request, pageUrl, agentClientName) {
     return {
         protocolVersion: AGENT_PROTOCOL_VERSION,
         projectId,
@@ -173,6 +173,7 @@ function statusWith(projectId, listenerActive, paired, request, pageUrl) {
         listenerActive,
         paired,
         pageUrl,
+        ...(agentClientName === undefined ? {} : { agentClientName }),
         request,
     };
 }
@@ -225,9 +226,10 @@ export function createLoopbackBridge(options) {
     let closePromise = null;
     let startPromise = null;
     let agentOwner = null;
+    let agentClientName;
     let agentOwnerSeenAt = 0;
     let agentOwnerExpiry = null;
-    const getStatus = () => statusWith(options.projectId, listener !== null, sessionToken !== null, currentRequest, lastPageUrl);
+    const getStatus = () => statusWith(options.projectId, listener !== null, sessionToken !== null, currentRequest, lastPageUrl, agentClientName);
     const broadcast = (event) => {
         if (!sessionToken)
             return;
@@ -310,7 +312,7 @@ export 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.");
         }
@@ -332,6 +334,10 @@ 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) {
             if (body.sessionToken !== sessionToken) {
                 throw new BridgeRequestError(409, "already_paired", "A browser is already paired with this project.");
@@ -367,6 +373,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);
@@ -523,6 +538,7 @@ export function createLoopbackBridge(options) {
             clock.clearTimeout(agentOwnerExpiry);
         agentOwnerExpiry = null;
         agentOwner = null;
+        agentClientName = undefined;
         agentOwnerSeenAt = 0;
         cancelListener(reason);
         if (currentRequest?.status === "working") {
@@ -539,6 +555,7 @@ export function createLoopbackBridge(options) {
                 error: { code: "agent_released", message: reason },
             });
         }
+        broadcastStatus();
     };
     const scheduleAgentOwnerExpiry = () => {
         if (agentOwnerExpiry !== null)
@@ -587,7 +604,8 @@ export function createLoopbackBridge(options) {
         requireAgentOwner(request, body);
         const abort = new AbortController();
         response.once("close", () => abort.abort());
-        const prompt = await waitForPrompt(abort.signal);
+        const clientName = typeof body.agentClientName === "string" ? body.agentClientName.trim().slice(0, 120) : undefined;
+        const prompt = await waitForPrompt(abort.signal, undefined, clientName);
         sendJson(response, 200, prompt, null);
     };
     const handleAgentReportStatus = async (request, response) => {
@@ -599,6 +617,14 @@ export function createLoopbackBridge(options) {
         updateRequestStatus(body.update);
         sendJson(response, 200, getStatus(), null);
     };
+    const handleAgentActivity = async (request, response) => {
+        const body = await readJsonBody(request);
+        requireAgentOwner(request, body);
+        if (!isAgentActivity(body.activity))
+            throw new BridgeRequestError(400, "invalid_activity", "activity must identify a workspace-relative source file.");
+        reportActivity(body.activity);
+        sendJson(response, 200, { accepted: true }, null);
+    };
     const handleAgentCanvas = async (request, response) => {
         const body = await readJsonBody(request);
         requireAgentOwner(request, body);
@@ -645,6 +671,10 @@ export function createLoopbackBridge(options) {
                 await handleAgentReportStatus(request, response);
                 return;
             }
+            if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.activity) {
+                await handleAgentActivity(request, response);
+                return;
+            }
             if (request.method === "POST" && url.pathname === AGENT_CONTROL_ENDPOINTS.canvas) {
                 await handleAgentCanvas(request, response);
                 return;
@@ -661,6 +691,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;
@@ -731,13 +765,14 @@ export function createLoopbackBridge(options) {
         pending.reject(new BridgeRequestError(409, "listener_cancelled", reason));
         broadcastStatus();
     };
-    const waitForPrompt = (signal) => {
+    const waitForPrompt = (signal, _sessionId, clientName) => {
         if (lifecycle === "closed")
             return Promise.reject(new Error("The browser bridge is closed."));
         if (listener)
             return Promise.reject(new Error("A listening call is already active for this project."));
         if (currentRequest?.status === "working")
             return Promise.reject(new Error("A request is already in flight for this project."));
+        agentClientName = clientName?.trim().slice(0, 120) || undefined;
         // Keep the terminal outcome visible until the agent explicitly rearms its
         // listening call. Rearming is the lifecycle boundary for the old request.
         if (currentRequest)
@@ -786,6 +821,14 @@ export function createLoopbackBridge(options) {
         }
         broadcastStatus();
     };
+    const reportActivity = (activity) => {
+        if (!isAgentActivity(activity))
+            throw new TypeError("Invalid agent activity");
+        if (!currentRequest || currentRequest.requestId !== activity.requestId || currentRequest.status !== "working") {
+            throw new BridgeRequestError(409, "inactive_request", "Activity requires the currently working request.");
+        }
+        broadcast({ type: "activity", activity });
+    };
     const dispatchCanvasCommand = (input) => {
         if (lifecycle === "closed")
             return Promise.reject(new Error("The browser bridge is closed."));
@@ -904,6 +947,7 @@ export function createLoopbackBridge(options) {
             clock.clearTimeout(agentOwnerExpiry);
         agentOwnerExpiry = null;
         agentOwner = null;
+        agentClientName = undefined;
         agentOwnerSeenAt = 0;
         cancelListener("bridge_closed");
         if (pendingCanvas) {
@@ -945,6 +989,7 @@ export function createLoopbackBridge(options) {
         waitForPrompt,
         cancelListener,
         updateRequestStatus,
+        reportActivity,
         dispatchCanvasCommand,
         pairBrowser,
         disconnectBrowser,

package/dist/cli.d.ts

@@ -3,7 +3,7 @@ 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;
@@ -32,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 [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>       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,7 @@ 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 { discoverProjectSessions } from "./discovery.js";
+import { diagnoseProjectSessions, discoverProjectSessions } from "./discovery.js";
 import { createAgentCompanion, createDiscoveredAgentAdapter, } from "./server.js";
 const DEFAULT_PORT = 0;
 const DEFAULT_COMMAND_TIMEOUT_MS = 5_000;
@@ -73,7 +73,7 @@ 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 < argumentsToParse.length; index += 1) {
@@ -133,7 +133,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
@@ -148,13 +148,19 @@ export async function runCli(argv = process.argv.slice(2), environment = process
     }
     if (options.command === "doctor") {
         const sessions = await discoverProjectSessions(options.workspaceRoot);
-        const matches = sessions.filter((session) => session.matchesApplication);
+        const matches = sessions.filter((session) => options.workspaceRoot === undefined || 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"]
+                ? ["[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"
@@ -195,8 +201,10 @@ export async function runCli(argv = process.argv.slice(2), environment = process
         }
         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;