@nudge-ui/mcp 0.2.0 → 0.2.1

package/README.md

@@ -1,62 +1,88 @@
 # `@nudge-ui/mcp`
 
-> **Early alpha:** This integration is still under heavy testing. Expect
-> breaking changes, incomplete host compatibility, and other rough edges. Do
-> not rely on it for production workflows yet.
+> **Early alpha:** This integration can make breaking changes while host
+> support and the setup workflow stabilize.
 
-`@nudge-ui/mcp` connects a local Nudge UI inspector to an MCP-capable coding
-agent. It combines a standard MCP stdio server with a project-scoped loopback
-browser bridge. The browser does not speak MCP directly.
+`@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.
 
-## Install
+## Configure an agent
+
+The Nudge initializer can install the dependency and configure supported agent
+hosts. A manual project-scoped configuration uses this command:
 
 ```sh
-pnpm add -D @nudge-ui/mcp@0.2.0
+node ./node_modules/@nudge-ui/mcp/dist/cli.mjs --workspace-root /path/to/project
 ```
 
-### Configure automatically
+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.
 
-From the application project root, use [`add-mcp`](https://github.com/neon-solutions/add-mcp) to detect supported coding agents and write each host's native configuration format:
+Run diagnostics without starting MCP stdio framing:
 
 ```sh
-npx add-mcp \
-  'npx -y @nudge-ui/mcp@0.2.0 --project-id my-app --origin http://localhost:5173 --workspace-root .' \
-  --name nudge_ui
+node ./node_modules/@nudge-ui/mcp/dist/cli.mjs doctor --workspace-root /path/to/project
 ```
 
-The command prompts for detected project agents. Use `-a codex` (or another
-supported agent name) to target one host, or `-y` to skip the prompt and use
-the detected project agents. Keep this project-scoped; do not use `-g` unless
-the configuration intentionally targets one fixed project.
+The doctor reports live and exact-workspace session counts. It never prints
+control credentials.
+
+## Project integration
+
+Framework adapters start and stop the project bridge with the development
+server:
 
-`--origin` must exactly match the development application's browser origin.
-The `--project-id` value must match the ID used by the Nudge host integration.
-For standard Vite and Astro projects, `my-app` normally matches the project
-directory name. Next.js and standalone HTML projects use host-specific IDs, so
-retain the explicit ID from their integration configuration.
+```ts
+import { startProjectBridge } from "@nudge-ui/mcp/project";
 
-The generated command pins the published `@nudge-ui/mcp@0.2.0` package through
-`npx` for reproducible tool versions. Update the version deliberately when
-upgrading the MCP integration. After configuration, restart or reload the
-agent host so it refreshes its MCP tool catalog.
+const runtime = await startProjectBridge({
+  workspaceRoot: process.cwd(),
+  appRoot: process.cwd(),
+  projectId: "my-app",
+  origin: "http://localhost:5173",
+  allowedOrigins: ["http://127.0.0.1:5173"],
+});
 
-The package has no install-time project mutation. The manual configuration
-below remains useful when an agent host is not supported by `add-mcp` or when
-you need an explicit custom command.
+// Give browser code only these non-secret values.
+console.log(runtime.browser.bridgeUrl, runtime.browser.projectId);
+
+await runtime.close();
+```
 
-After adding or changing the host configuration, restart or reload the MCP
-server, or start a fresh agent task. Open **Connect MCP** from the inspector's
-prompt menu for setup instructions, connection status, and explicit pairing.
-You can pair a page before the agent starts listening. Ask the agent to call
-`nudge_listen` and keep it active to enable sending. **Copy prompt** remains
-available while the agent is idle; prompts are not queued.
+`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.
 
-For Codex desktop, confirm that `nudge_ui` appears in the current task after
-the MCP restart. For Codex CLI, `codex mcp list` verifies the project entry.
-Restart a long-running OpenCode service after adding or changing its MCP
-configuration so it refreshes its tool catalog.
+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.
 
-## Run manually
+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.
+
+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.
+
+## Legacy coupled mode
+
+Passing `--origin` retains the previous behavior in which the MCP process also
+owns its browser bridge:
 
 ```sh
 pnpm exec nudge-mcp \
@@ -65,17 +91,9 @@ pnpm exec nudge-mcp \
   --workspace-root /path/to/my-app
 ```
 
-Pass the exact application origin with `--origin` (or
-`NUDGE_UI_ORIGIN`). The bridge rejects browser origins that are not explicitly
-configured; it never trusts the first origin that connects. The bridge chooses
-a deterministic loopback port from the project ID so the inspector can find
-it without a port file. Use `--port 0` for an ephemeral test port.
-
-For integrations that establish the browser origin out of band, trusted host
-code can use the `pairBrowser` API as an explicit manual approval path. An
-unconfigured bridge does not accept HTTP pairing requests.
+This mode remains available for custom integrations during migration. New
+framework integrations should use the project-owned bridge.
 
-The agent should call `nudge_listen` immediately, apply the delivered prompt
-through its normal source-editing workflow, call `nudge_report_status`, and
-listen again. Canvas tools are limited to same-origin routes and agent-owned
-groups.
+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.

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
 import { type Server } from "node:http";
-import type { AgentPromptRequest, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "./internal/agent-protocol.js";
+import type { AgentDeliveredPrompt, AgentRequestOutcome, AgentStatusSnapshot, AgentStatusUpdate, CanvasCommandResult, PairingResponse } from "./internal/agent-protocol.js";
 /** A clock port keeps command timeout tests deterministic. */
 export interface BridgeClock {
     now(): number;
@@ -22,6 +22,8 @@ export interface BrowserBridgeOptions {
     readonly tokenFactory?: () => string;
     /** Test seam; production defaults to random UUIDs. */
     readonly idFactory?: () => string;
+    /** Private credential for a separately running MCP adapter. */
+    readonly agentControlToken?: string;
     /**
      * Best-effort hook used by the CLI to reopen the last paired page when an
      * agent rearms listening but no browser controller stream is attached.
@@ -49,7 +51,7 @@ export interface BrowserBridge {
     start(): Promise<BridgeAddress>;
     close(): Promise<void>;
     /** Blocks until a paired browser dispatches a prompt. */
-    waitForPrompt(signal?: AbortSignal): Promise<AgentPromptRequest>;
+    waitForPrompt(signal?: AbortSignal): Promise<AgentDeliveredPrompt>;
     /** Marks the agent-side listener as stopped without ending the project. */
     cancelListener(reason?: string): void;
     /** Reports the terminal result for the currently running browser request. */

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,7 +304,7 @@ 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,
@@ -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;
@@ -290,7 +333,20 @@ export function createLoopbackBridge(options) {
             requestedPageUrl = new URL(body.pageUrl, requestedOrigin).href;
         }
         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 +359,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(),
@@ -338,7 +394,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 +404,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 +422,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 +495,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;
@@ -508,7 +728,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 +838,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 +900,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,5 +1,6 @@
 import { type ChildProcess } from "node:child_process";
 export interface CliOptions {
+    readonly command: "serve" | "doctor";
     readonly projectId: string;
     readonly origin?: string;
     readonly workspaceRoot: string;
@@ -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>       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";
 /** Runs the CLI until the stdio MCP connection closes or the process stops. */
 export declare function runCli(argv?: readonly string[], environment?: CliEnvironment): Promise<void>;