nudge-ui 0.2.1 → 0.2.2

package/dist/hosts/astro/clientTransport.js

@@ -3,6 +3,7 @@ import { createAstroRuntimeConfig } from "./astroRuntimeConfig.js";
 import { createAstroClientAssetHandler } from "./clientAsset.js";
 import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, createNudgeUiEditorDocument, isNudgeUiEditorDocumentRequest, } from "../../transport/index.js";
 import { startOptionalProjectBridge } from "../projectBridge.js";
+import { automationManifestFields } from "../environment.js";
 const serveClient = createAstroClientAssetHandler();
 /** Serves the prebuilt client and its host-neutral manifest in Astro dev. */
 export function createAstroClientTransportPlugin() {
@@ -77,6 +78,7 @@ async function createManifest(server, request, setBridge) {
             appRoot: server.config.root,
             projectId: runtime.projectId,
             origin,
+            info: (message) => server.config.logger.info(message),
             warn: (message) => server.config.logger.warn(message),
         })
         : null;
@@ -86,6 +88,7 @@ async function createManifest(server, request, setBridge) {
         revision: 0,
         runtime,
         ...(bridge ? { agentBridge: bridge.browser } : {}),
+        ...automationManifestFields(),
     };
 }
 function resolvedRequestOrigin(server, request) {

package/dist/hosts/astro/integration.d.ts

@@ -11,8 +11,8 @@ export interface NudgeUiAstroOptions extends NudgeUiOptions {
 /**
  * Nudge UI host Adapter for Astro dev servers (ADR-0011).
  *
- * Dev-only by contract (ADR-0002): unless `command === "dev"` and
- * `enabled !== false`, the integration registers nothing at all — no Vite
+ * Dev-only by contract (ADR-0002): unless `command === "dev"`,
+ * `enabled !== false`, and `NUDGE_UI` is not `0`, the integration registers nothing at all — no Vite
  * plugins, no injected scripts, no middleware — so `astro build` output is
  * byte-identical to a project without the integration.
  *

package/dist/hosts/astro/integration.js

@@ -2,6 +2,7 @@ import { nudgeUi } from "../vite/index.js";
 import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_MANIFEST_PATH } from "../../transport/index.js";
 import { createAstroClientTransportPlugin, } from "./clientTransport.js";
 import { createProjectContextPlugin } from "./projectContext.js";
+import { isNudgeUiEnabled } from "../environment.js";
 /**
  * Adds the prebuilt client as an external module. The inspector dependency
  * graph therefore never enters Astro's Vite optimizer.
@@ -23,8 +24,8 @@ const MIDDLEWARE_ENTRYPOINT = new URL(import.meta.url.endsWith(".ts") ? "./middl
 /**
  * Nudge UI host Adapter for Astro dev servers (ADR-0011).
  *
- * Dev-only by contract (ADR-0002): unless `command === "dev"` and
- * `enabled !== false`, the integration registers nothing at all — no Vite
+ * Dev-only by contract (ADR-0002): unless `command === "dev"`,
+ * `enabled !== false`, and `NUDGE_UI` is not `0`, the integration registers nothing at all — no Vite
  * plugins, no injected scripts, no middleware — so `astro build` output is
  * byte-identical to a project without the integration.
  *
@@ -37,7 +38,7 @@ const MIDDLEWARE_ENTRYPOINT = new URL(import.meta.url.endsWith(".ts") ? "./middl
  *    identity Module.
  */
 export function nudgeUiAstro(options = {}) {
-    const enabled = options.enabled ?? true;
+    const enabled = isNudgeUiEnabled(options.enabled);
     const sharedOptions = { ...options };
     return {
         name: "nudge-ui",

package/dist/hosts/environment.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `NUDGE_UI` environment switch shared by every development host.
+ *
+ * - `0`, `false`, or `off` disables the host Adapter for that run.
+ * - `1`, `true`, or `on` also opens the editor in automated browsers, which
+ *   otherwise receive the plain application.
+ */
+export type NudgeUiEnvironmentSwitch = "off" | "on" | null;
+export declare function readNudgeUiEnvironmentSwitch(env?: Readonly<Record<string, string | undefined>>): NudgeUiEnvironmentSwitch;
+/** An explicit `enabled: false` or `NUDGE_UI=0` disables the Adapter. */
+export declare function isNudgeUiEnabled(enabled: boolean | undefined, env?: Readonly<Record<string, string | undefined>>): boolean;
+/** Manifest fields derived from the environment at request time. */
+export declare function automationManifestFields(env?: Readonly<Record<string, string | undefined>>): {
+    inspectAutomatedBrowsers?: true;
+};

package/dist/hosts/environment.js

@@ -0,0 +1,16 @@
+export function readNudgeUiEnvironmentSwitch(env = process.env) {
+    const value = env.NUDGE_UI?.trim().toLowerCase();
+    if (value === "0" || value === "false" || value === "off")
+        return "off";
+    if (value === "1" || value === "true" || value === "on")
+        return "on";
+    return null;
+}
+/** An explicit `enabled: false` or `NUDGE_UI=0` disables the Adapter. */
+export function isNudgeUiEnabled(enabled, env = process.env) {
+    return enabled !== false && readNudgeUiEnvironmentSwitch(env) !== "off";
+}
+/** Manifest fields derived from the environment at request time. */
+export function automationManifestFields(env = process.env) {
+    return readNudgeUiEnvironmentSwitch(env) === "on" ? { inspectAutomatedBrowsers: true } : {};
+}

package/dist/hosts/next/sidecar.js

@@ -9,6 +9,7 @@ import { createProjectFileWatcher, } from "../../project/files.js";
 import { createProjectTokenSnapshot } from "../../project/tokens.js";
 import { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, createNudgeUiEditorDocument, isNudgeUiEditorDocumentRequest, } from "../../transport/index.js";
 import { startOptionalProjectBridge } from "../projectBridge.js";
+import { automationManifestFields } from "../environment.js";
 /**
  * Loopback-only manifest/reload sidecar (ADR-0010).
  *
@@ -264,6 +265,7 @@ export async function ensureSidecar(root, options = {}) {
                 ...(options.projectBridgeAllowedOrigins
                     ? { allowedOrigins: options.projectBridgeAllowedOrigins }
                     : {}),
+                info: (message) => console.info(message),
                 warn: (message) => console.warn(message),
             }).then((bridge) => {
                 projectBridge = bridge;
@@ -529,7 +531,11 @@ function respond(req, res, currentManifest, currentGeneration, streams, receiveC
     if (url === NUDGE_UI_MANIFEST_PATH) {
         // The served snapshot carries its revision so clients can reconcile
         // against SSE notifications instead of guessing.
-        const body = `${JSON.stringify({ ...currentManifest(), revision: currentGeneration() })}\n`;
+        const body = `${JSON.stringify({
+            ...currentManifest(),
+            revision: currentGeneration(),
+            ...automationManifestFields(),
+        })}\n`;
         res.writeHead(200, {
             "content-type": "application/json",
             "cache-control": "no-store",

package/dist/hosts/next/wrapper.d.ts

@@ -28,6 +28,8 @@ export interface NudgeUiNextConfig {
 }
 /** Host-specific policy additions passed to the shared source compiler. */
 export interface NudgeUiNextOptions {
+    /** `false` returns the configuration untouched. `NUDGE_UI=0` has the same effect for one run. */
+    readonly enabled?: boolean;
     readonly componentProtocols?: ComponentModuleProtocols;
     /** Authored workspace directories outside the Next.js application root. */
     readonly sourceRoots?: readonly string[];

package/dist/hosts/next/wrapper.js

@@ -4,6 +4,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { ensureSidecar } from "./sidecar.js";
 import { buildManifest } from "./manifest.js";
 import { nudgeUiRepositoryPackagePath } from "./repositoryScope.js";
+import { isNudgeUiEnabled } from "../environment.js";
 import { NUDGE_UI_EDITOR_QUERY_PARAM, NUDGE_UI_EDITOR_QUERY_VALUE, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
 const NAMESPACE_PREFIX = NUDGE_UI_ROUTE_PREFIX.slice(0, -1);
 const SUPPORTED_NEXT_RANGE = ">=15.3 <17";
@@ -104,7 +105,7 @@ export function withNudgeUi(config = {}, options = {}) {
         : () => config;
     return (phase) => {
         const resolved = factory(phase);
-        if (!isDevelopmentEvaluation(phase))
+        if (!isDevelopmentEvaluation(phase) || !isNudgeUiEnabled(options.enabled))
             return resolved;
         return instrumentConfig(resolved, options);
     };

package/dist/hosts/projectBridge.d.ts

@@ -8,6 +8,7 @@ export declare function startOptionalProjectBridge(input: {
     readonly projectId: string;
     readonly origin: string;
     readonly allowedOrigins?: readonly string[];
+    readonly info?: (message: string) => void;
     readonly warn?: (message: string) => void;
 }): Promise<{
     browser: ProjectBridgeBrowserConfig;

package/dist/hosts/projectBridge.js

@@ -53,6 +53,7 @@ async function launchOptionalProjectBridge(input, key) {
             await runtime.close().catch(() => undefined);
             throw new Error("the project bridge returned a different project or origin");
         }
+        input.info?.(`[nudge-ui] project bridge ready for ${input.projectId}`);
         let closed = false;
         return {
             browser: { baseUrl: runtime.browser.bridgeUrl, autoConnect: true },

package/dist/hosts/static/manifest.js

@@ -1,4 +1,5 @@
 import { NUDGE_UI_MANIFEST_VERSION, NUDGE_UI_RELOAD_PATH } from "../../transport/index.js";
+import { automationManifestFields } from "../environment.js";
 export { NUDGE_UI_CLIENT_PATH, NUDGE_UI_EDITOR_PATH, NUDGE_UI_MANIFEST_PATH, NUDGE_UI_MOUNT_ID, NUDGE_UI_RELOAD_PATH, NUDGE_UI_ROUTE_PREFIX, } from "../../transport/index.js";
 /**
  * Creates the first valid static-HTML runtime snapshot.
@@ -39,6 +40,7 @@ export function createStandaloneRuntimeManifest(projectId, tokenSnapshot = empty
             strategy: "reload-document",
             events: ["ready", "reload"],
         },
+        ...automationManifestFields(),
     };
 }
 function emptyTokenSnapshot() {

package/dist/hosts/static/server.js

@@ -157,6 +157,7 @@ export function createStandaloneServer(options) {
                             appRoot: rootDirectory,
                             projectId,
                             origin: address.url.replace(/\/$/, ""),
+                            info: (message) => console.info(message),
                             warn: (message) => console.warn(message),
                         }).then((bridge) => {
                             projectBridge = bridge;

package/dist/hosts/vite/vite.d.ts

@@ -18,6 +18,7 @@ export interface VanillaExtractOptions {
     source?: string;
 }
 export interface NudgeUiOptions extends ReactOptions {
+    /** `false` registers nothing. `NUDGE_UI=0` has the same effect for one run. */
     enabled?: boolean;
     /** Enables experimental DOM parent/child navigation in the Inspector. */
     debug?: boolean;

package/dist/hosts/vite/vite.js

@@ -8,6 +8,7 @@ import { catalogSourcePath, createViteStylesheetArtifact, isHostApplicationSourc
 import { interpretDialects } from "../../css/dialects/index.js";
 import { detectStylingSystem, } from "../../inspector/clientManifest.js";
 import { loopbackOrigin, startOptionalProjectBridge, } from "../projectBridge.js";
+import { automationManifestFields, isNudgeUiEnabled } from "../environment.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -101,7 +102,7 @@ function invalidateHmrModules(server, modules, timestamp) {
  * here has grown a React assumption.
  */
 export function createVitePlugins(options = {}, createFramework = null) {
-    const enabled = options.enabled ?? true;
+    const enabled = isNudgeUiEnabled(options.enabled);
     let root;
     let buildOutputDirectory;
     let command = "serve";
@@ -484,6 +485,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
             revision: 0,
             runtime: buildRuntimeSnapshot(),
             ...(projectBridge ? { agentBridge: projectBridge.browser } : {}),
+            ...automationManifestFields(),
         };
     }
     function startProjectBridge(server) {
@@ -506,6 +508,7 @@ export function createVitePlugins(options = {}, createFramework = null) {
             projectId: options.projectId ?? basename(root),
             origin,
             ...(allowedOrigins.length > 0 ? { allowedOrigins } : {}),
+            info: (message) => server.config.logger.info(message),
             warn: (message) => server.config.logger.warn(message),
         }).then((bridge) => {
             projectBridge = bridge;

package/dist/inspector/agent/McpConnectionDialog.d.ts

@@ -8,6 +8,7 @@ export interface McpConnectionContentProps {
     readonly origin: string;
     readonly snapshot: AgentClientSnapshot;
     readonly onConnect: () => Promise<boolean> | boolean | void;
+    readonly onTakeOver: () => Promise<boolean> | boolean | void;
     readonly onDisconnect: () => void;
     readonly onCheckAgain: () => Promise<void>;
 }
@@ -16,11 +17,11 @@ export interface McpConnectionDialogProps extends McpConnectionContentProps {
     readonly onOpenChange: (open: boolean) => void;
 }
 /** Renders the MCP setup and pairing flow without owning a dialog surface. */
-export declare function McpConnectionContent({ projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }: McpConnectionContentProps): ReactElement;
+export declare function McpConnectionContent({ projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }: McpConnectionContentProps): ReactElement;
 /**
  * Explains and controls the project-scoped MCP companion connection.
  *
  * This compatibility wrapper keeps the existing standalone MCP surface while
  * the shared content is also embedded in the general settings modal.
  */
-export declare function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onDisconnect, onCheckAgain, }: McpConnectionDialogProps): ReactElement;
+export declare function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onTakeOver, onDisconnect, onCheckAgain, }: McpConnectionDialogProps): ReactElement;

package/dist/inspector/agent/McpConnectionDialog.js

@@ -5,6 +5,7 @@ import { IconCheck, IconClipboard, IconExternalLink, IconPlugConnected, IconRefr
 import { getAgentConnectionStatus } from "./connectionStatus.js";
 import { copyToClipboard } from "../prompt/copyToClipboard.js";
 import { Button } from "../ui/Button.js";
+import { Disclosure } from "../ui/Disclosure.js";
 import { SegmentedControl } from "../ui/SegmentedControl.js";
 import { StatusCallout } from "../ui/StatusCallout.js";
 export const MCP_DOCS_URL = "https://github.com/charlessmart/nudge-ui#connect-a-coding-agent";
@@ -21,7 +22,7 @@ function TimelineStep({ number, complete, title, children, }) {
     return (_jsxs("li", { className: `mcp-connection__timeline-step${complete ? " mcp-connection__timeline-step--complete" : ""}`, "data-test": `mcp-step-${number}`, "data-complete": complete ? "true" : "false", children: [_jsx("div", { className: "mcp-connection__timeline-marker", "aria-hidden": "true", children: complete ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 2 }) : number }), _jsxs("section", { className: "mcp-connection__timeline-content", children: [_jsx("h3", { className: "mcp-connection__section-title", children: title }), children] })] }));
 }
 /** Renders the MCP setup and pairing flow without owning a dialog surface. */
-export function McpConnectionContent({ projectId, origin, snapshot, onConnect, onDisconnect, onCheckAgain, }) {
+export function McpConnectionContent({ projectId, origin, snapshot, onConnect, onTakeOver, onDisconnect, onCheckAgain, }) {
     const [checking, setChecking] = useState(false);
     const [setupMethod, setSetupMethod] = useState("ai");
     const [copiedCommand, setCopiedCommand] = useState(false);
@@ -42,10 +43,16 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
     const status = getAgentConnectionStatus(snapshot);
     const canConnect = snapshot.companionReachable
         && !snapshot.paired
+        && !snapshot.pairedElsewhere
         && snapshot.state !== "pairing"
         && snapshot.state !== "working"
         && snapshot.request?.status !== "working";
     const canDisconnect = snapshot.paired || snapshot.request?.status === "working";
+    const canTakeOver = snapshot.companionReachable
+        && snapshot.pairedElsewhere
+        && snapshot.state !== "pairing"
+        && snapshot.state !== "working"
+        && snapshot.request?.status !== "working";
     async function handleCheckAgain() {
         if (checking)
             return;
@@ -97,7 +104,7 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
     return (_jsxs(_Fragment, { children: [_jsxs(StatusCallout, { className: "mcp-connection__status", tone: status.tone, "data-test": "mcp-connection-status", children: [_jsx("span", { className: "mcp-connection__status-label", role: "status", children: status.label }), snapshot.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.error })) : null, checkError ? _jsx("span", { role: "alert", children: checkError }) : null, snapshot.request?.summary ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.summary })) : null, snapshot.request?.error ? (_jsx("span", { className: "mcp-connection__status-detail", children: snapshot.request.error })) : null] }), _jsxs("ol", { className: "mcp-connection__timeline", "data-test": "mcp-connection-timeline", children: [_jsxs(TimelineStep, { number: 1, complete: snapshot.listenerActive || snapshot.request !== null, title: "Set up your agent once", children: [_jsx(SegmentedControl, { "aria-label": "MCP setup method", className: "mcp-connection__setup-tabs", "data-test": "mcp-setup-tabs", value: setupMethod, options: [
                                     { value: "ai", label: "AI instructions", testId: "mcp-setup-tab-ai" },
                                     { value: "terminal", label: "Terminal command", testId: "mcp-setup-tab-terminal" },
-                                ], onChange: setSetupMethod }), setupMethod === "terminal" ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Run this command from the application directory, then start your app normally." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-command", children: setupCommand }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-command", type: "button", onClick: () => void handleCopyCommand(), children: [copiedCommand ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedCommand ? "Copied" : "Copy command"] }) })] })) : (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Copy these setup instructions into your coding agent." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-prompt", children: setupPrompt }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-setup-prompt", type: "button", onClick: () => void handleCopyPrompt(), children: [copiedPrompt ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedPrompt ? "Copied" : "Copy prompt"] }) })] }))] }), _jsxs(TimelineStep, { number: 2, complete: snapshot.listenerActive, title: "Listen in this agent session", children: [_jsx("p", { className: "mcp-connection__copy", children: "Tell your coding agent: \u201CListen to Nudge.\u201D Reload the agent if Nudge tools are unavailable." }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-listener", type: "button", onClick: () => void handleCopyListener(), children: [copiedListener ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedListener ? "Copied" : "Copy listening instruction"] }) })] })] }), _jsxs("details", { className: "mcp-connection__details", children: [_jsx("summary", { children: "Connection details and recovery" }), _jsxs("p", { className: "mcp-connection__copy", children: ["The page connects automatically when the development integration is available. To diagnose setup, run ", _jsx("code", { children: "nudge-ui agent doctor" }), " from the application directory."] }), _jsxs("dl", { className: "mcp-connection__diagnostics", "data-test": "mcp-connection-diagnostics", children: [_jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Project ID" }), _jsx("dd", { "data-test": "mcp-project-id", children: _jsx("code", { children: projectId }) })] }), _jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Origin" }), _jsx("dd", { "data-test": "mcp-origin", children: _jsx("code", { children: origin }) })] })] }), _jsxs("div", { className: "mcp-connection__actions", children: [canConnect ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-connect", type: "button", onClick: () => void onConnect(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Connect"] })) : null, _jsxs(Button, { variant: "quiet", "data-test": "mcp-check-again", type: "button", disabled: checking || snapshot.state === "disabled" || snapshot.state === "pairing", onClick: () => void handleCheckAgain(), children: [_jsx(IconRefresh, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), checking ? "Checking…" : "Check again"] }), canDisconnect ? (_jsxs(Button, { variant: "danger", "data-test": "mcp-disconnect", type: "button", onClick: onDisconnect, children: [_jsx(IconUnlink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), snapshot.paired ? "Disconnect" : "Forget connection"] })) : null] })] }), copyError ? _jsx("p", { className: "mcp-connection__error", role: "alert", children: copyError }) : null, _jsxs("a", { className: "mcp-connection__docs", "data-test": "mcp-docs-link", href: MCP_DOCS_URL, target: "_blank", rel: "noreferrer", children: [_jsx(IconExternalLink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Read the MCP connection guide"] })] }));
+                                ], onChange: setSetupMethod }), setupMethod === "terminal" ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Run this command from the application directory, then start your app normally." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-command", children: setupCommand }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-command", type: "button", onClick: () => void handleCopyCommand(), children: [copiedCommand ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedCommand ? "Copied" : "Copy command"] }) })] })) : (_jsxs(_Fragment, { children: [_jsx("p", { className: "mcp-connection__copy", children: "Copy these setup instructions into your coding agent." }), _jsx("pre", { className: "mcp-connection__command", children: _jsx("code", { "data-test": "mcp-setup-prompt", children: setupPrompt }) }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-setup-prompt", type: "button", onClick: () => void handleCopyPrompt(), children: [copiedPrompt ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedPrompt ? "Copied" : "Copy prompt"] }) })] }))] }), _jsxs(TimelineStep, { number: 2, complete: snapshot.listenerActive, title: "Listen in this agent session", children: [_jsx("p", { className: "mcp-connection__copy", children: "Tell your coding agent: \u201CListen to Nudge.\u201D Reload the agent if Nudge tools are unavailable." }), _jsx("div", { className: "mcp-connection__command-actions", children: _jsxs(Button, { variant: "secondary", "data-test": "mcp-copy-listener", type: "button", onClick: () => void handleCopyListener(), children: [copiedListener ? _jsx(IconCheck, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) : _jsx(IconClipboard, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), copiedListener ? "Copied" : "Copy listening instruction"] }) })] })] }), _jsxs(Disclosure, { className: "mcp-connection__details", title: "Connection details and recovery", children: [_jsxs("p", { className: "mcp-connection__copy", children: ["The page connects automatically when the development integration is available. To diagnose setup, run ", _jsx("code", { children: "nudge-ui agent doctor" }), " from the application directory."] }), _jsxs("dl", { className: "mcp-connection__diagnostics", "data-test": "mcp-connection-diagnostics", children: [_jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Project ID" }), _jsx("dd", { "data-test": "mcp-project-id", children: _jsx("code", { children: projectId }) })] }), _jsxs("div", { className: "mcp-connection__diagnostic", children: [_jsx("dt", { children: "Origin" }), _jsx("dd", { "data-test": "mcp-origin", children: _jsx("code", { children: origin }) })] })] }), _jsxs("div", { className: "mcp-connection__actions", children: [canTakeOver ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-takeover", type: "button", onClick: () => void onTakeOver(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Take over"] })) : null, canConnect ? (_jsxs(Button, { variant: "primary", "data-test": "mcp-connect", type: "button", onClick: () => void onConnect(), children: [_jsx(IconPlugConnected, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Connect"] })) : null, _jsxs(Button, { variant: "quiet", "data-test": "mcp-check-again", type: "button", disabled: checking || snapshot.state === "disabled" || snapshot.state === "pairing", onClick: () => void handleCheckAgain(), children: [_jsx(IconRefresh, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), checking ? "Checking…" : "Check again"] }), canDisconnect ? (_jsxs(Button, { variant: "danger", "data-test": "mcp-disconnect", type: "button", onClick: onDisconnect, children: [_jsx(IconUnlink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), snapshot.paired ? "Disconnect" : "Forget connection"] })) : null] })] }), copyError ? _jsx("p", { className: "mcp-connection__error", role: "alert", children: copyError }) : null, _jsxs("a", { className: "mcp-connection__docs", "data-test": "mcp-docs-link", href: MCP_DOCS_URL, target: "_blank", rel: "noreferrer", children: [_jsx(IconExternalLink, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }), "Read the MCP connection guide"] })] }));
 }
 /**
  * Explains and controls the project-scoped MCP companion connection.
@@ -105,7 +112,7 @@ export function McpConnectionContent({ projectId, origin, snapshot, onConnect, o
  * This compatibility wrapper keeps the existing standalone MCP surface while
  * the shared content is also embedded in the general settings modal.
  */
-export function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onDisconnect, onCheckAgain, }) {
+export function McpConnectionDialog({ open, projectId, origin, snapshot, onOpenChange, onConnect, onTakeOver, onDisconnect, onCheckAgain, }) {
     const closeRef = useRef(null);
-    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "mcp-connection__backdrop", "data-test": "mcp-connection-backdrop" }), _jsxs(Dialog.Popup, { className: "mcp-connection__popup", "data-test": "mcp-connection-dialog", initialFocus: closeRef, children: [_jsxs("div", { className: "mcp-connection__header", children: [_jsxs("div", { children: [_jsx(Dialog.Title, { className: "mcp-connection__title", children: "Connect MCP" }), _jsx(Dialog.Description, { className: "mcp-connection__description", children: "Set up your coding agent once, then ask it to listen to Nudge in this worktree." })] }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet mcp-connection__close", "aria-label": "Close MCP connection", "data-test": "mcp-connection-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] }), _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain })] })] }) }));
+    return (_jsx(Dialog.Root, { open: open, onOpenChange: onOpenChange, children: _jsxs(Dialog.Portal, { container: portalContainer(), children: [_jsx(Dialog.Backdrop, { className: "mcp-connection__backdrop", "data-test": "mcp-connection-backdrop" }), _jsxs(Dialog.Popup, { className: "mcp-connection__popup", "data-test": "mcp-connection-dialog", initialFocus: closeRef, children: [_jsxs("div", { className: "mcp-connection__header", children: [_jsxs("div", { children: [_jsx(Dialog.Title, { className: "mcp-connection__title", children: "Connect MCP" }), _jsx(Dialog.Description, { className: "mcp-connection__description", children: "Set up your coding agent once, then ask it to listen to Nudge in this worktree." })] }), _jsx(Dialog.Close, { ref: closeRef, className: "icon-button icon-button--quiet mcp-connection__close", "aria-label": "Close MCP connection", "data-test": "mcp-connection-close", type: "button", children: _jsx(IconX, { size: "var(--icon-size-small)", stroke: 1.8, "aria-hidden": "true" }) })] }), _jsx(McpConnectionContent, { projectId: projectId, origin: origin, snapshot: snapshot, onConnect: onConnect, onTakeOver: onTakeOver, onDisconnect: onDisconnect, onCheckAgain: onCheckAgain })] })] }) }));
 }

package/dist/inspector/agent/client.d.ts

@@ -18,6 +18,8 @@ export interface AgentClientSnapshot {
     /** Whether the last valid discovery response came from the local companion. */
     readonly companionReachable: boolean;
     readonly paired: boolean;
+    /** Whether another browser currently owns this project's pairing. */
+    readonly pairedElsewhere: boolean;
     readonly request: AgentRequestSnapshot | null;
     readonly error?: string;
 }
@@ -51,6 +53,7 @@ export declare class AgentClient {
     private listenerActive;
     private companionReachable;
     private paired;
+    private pairedElsewhere;
     private lastError;
     private readonly autoConnect;
     private autoConnectSuppressed;
@@ -70,6 +73,9 @@ export declare class AgentClient {
     reconnect(): void;
     /** Pairs the browser with a reachable companion, including an idle agent. */
     connect(): Promise<boolean>;
+    /** Replaces an existing browser pairing after an explicit user action. */
+    takeOver(): Promise<boolean>;
+    private pairWith;
     private openEvents;
     /**
      * Dispatches one immutable prompt revision. The request enters `working`

package/dist/inspector/agent/client.js

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useSyncExternalStore } from "react";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
 import { isDemoRuntime } from "../runtime/runtimeConfig.js";
-import { HttpAgentBridgeTransport, shouldAutoConnectAgentBridge } from "./httpTransport.js";
+import { AgentBridgeHttpError, HttpAgentBridgeTransport, shouldAutoConnectAgentBridge, } from "./httpTransport.js";
 import { AGENT_PROTOCOL_VERSION, } from "./protocol.js";
 const DISABLED_SNAPSHOT = Object.freeze({
     state: "disabled",
@@ -9,6 +9,7 @@ const DISABLED_SNAPSHOT = Object.freeze({
     listenerActive: false,
     companionReachable: false,
     paired: false,
+    pairedElsewhere: false,
     request: null,
 });
 const DEFAULT_DISCOVERY_INTERVAL_MS = 2_000;
@@ -154,6 +155,7 @@ export class AgentClient {
     listenerActive = false;
     companionReachable = false;
     paired = false;
+    pairedElsewhere = false;
     lastError;
     autoConnect;
     autoConnectSuppressed = false;
@@ -211,6 +213,7 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.publish();
     }
     async restoreOrDiscover() {
@@ -291,12 +294,22 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.lastError = undefined;
         this.publish();
         void this.restoreOrDiscover();
     }
     /** Pairs the browser with a reachable companion, including an idle agent. */
     async connect() {
+        return this.pairWith((request, signal) => this.transport.pair(request, signal));
+    }
+    /** Replaces an existing browser pairing after an explicit user action. */
+    async takeOver() {
+        if (!this.transport.takeOver)
+            return false;
+        return this.pairWith((request, signal) => this.transport.takeOver(request, signal));
+    }
+    async pairWith(pair) {
         if (!this.enabled || !this.started || this.pairingAbort || this.paired || !this.companionReachable)
             return false;
         this.autoConnectSuppressed = false;
@@ -317,7 +330,7 @@ export class AgentClient {
         this.discoveryAbort?.abort();
         this.pairingAbort = abortController;
         try {
-            const pairing = await this.transport.pair(request, abortController.signal);
+            const pairing = await pair(request, abortController.signal);
             if (!this.started || abortController.signal.aborted)
                 return false;
             if (pairing.protocolVersion !== undefined && pairing.protocolVersion !== AGENT_PROTOCOL_VERSION) {
@@ -333,6 +346,7 @@ export class AgentClient {
             this.connection = "paired";
             this.listenerActive = pairing.status.listenerActive;
             this.paired = true;
+            this.pairedElsewhere = false;
             if (this.discoveryTimer !== null) {
                 clearTimeout(this.discoveryTimer);
                 this.discoveryTimer = null;
@@ -351,6 +365,9 @@ export class AgentClient {
             this.listenerActive = idleListenerActive;
             this.connection = idleListenerActive ? "listening" : "offline";
             this.paired = false;
+            this.pairedElsewhere = error instanceof AgentBridgeHttpError
+                && error.status === 409
+                && error.code === "already_paired";
             this.publish(idleListenerActive ? "available" : "disconnected");
             return false;
         }
@@ -467,6 +484,7 @@ export class AgentClient {
         this.connection = "offline";
         this.listenerActive = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.lastError = reason === "reconnect" || reason === "browser_disconnected" ? undefined : reason;
         this.publish();
         if (token) {
@@ -503,12 +521,13 @@ export class AgentClient {
                         // pairing, so do not adopt `paired` until this tab restores the
                         // shared token. The next poll runs restore first in case a sibling
                         // tab has just stored that token.
+                        const pairedElsewhere = status.paired && !this.sessionToken;
                         this.applyStatus(status.paired ? {
                             ...status,
                             connection: status.listenerActive ? "listening" : "offline",
                             paired: false,
                             request: null,
-                        } : status);
+                        } : status, pairedElsewhere);
                         if (this.autoConnect
                             && !status.paired
                             && !this.autoConnectSuppressed
@@ -522,6 +541,7 @@ export class AgentClient {
                 this.listenerActive = false;
                 this.companionReachable = false;
                 this.paired = false;
+                this.pairedElsewhere = false;
                 this.lastError = undefined;
                 this.publish();
             }
@@ -532,6 +552,7 @@ export class AgentClient {
                 this.listenerActive = false;
                 this.companionReachable = false;
                 this.paired = false;
+                this.pairedElsewhere = false;
                 // Discovery failures are expected while the companion is not running;
                 // retain a quiet disconnected state rather than flashing an error.
                 this.lastError = undefined;
@@ -624,11 +645,12 @@ export class AgentClient {
             // bounded timeout and reports any expired command to its agent host.
         }
     }
-    applyStatus(status) {
+    applyStatus(status, pairedElsewhere = false) {
         this.companionReachable = true;
         this.lastError = undefined;
         this.listenerActive = status.listenerActive;
         this.paired = status.paired;
+        this.pairedElsewhere = pairedElsewhere;
         this.connection = statusForConnection(status);
         if (status.paired && this.discoveryTimer !== null) {
             clearTimeout(this.discoveryTimer);
@@ -661,6 +683,7 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.publish();
     }
     applyRequestStatus(status, requestId, summary, error, changeRevision, clientDispatchId, sketches) {
@@ -712,7 +735,15 @@ export class AgentClient {
         this.listenerActive = false;
         this.companionReachable = false;
         this.paired = false;
+        this.pairedElsewhere = false;
         this.lastError = reason;
+        if (reason === "browser_disconnected") {
+            // A remote takeover deliberately invalidates this browser's token. Do
+            // not immediately race the new browser by auto-pairing again.
+            this.autoConnectSuppressed = true;
+            if (this.autoConnect)
+                setAutoConnectDisabled(this.projectId, true);
+        }
         this.publish();
         this.scheduleReconnect();
     }
@@ -725,6 +756,7 @@ export class AgentClient {
             listenerActive: this.listenerActive,
             companionReachable: this.companionReachable,
             paired: this.paired,
+            pairedElsewhere: this.pairedElsewhere,
             request: request ? {
                 requestId: request.requestId,
                 ...(request.changeRevision === undefined ? {} : { changeRevision: request.changeRevision }),

package/dist/inspector/agent/connectionStatus.d.ts

@@ -1,12 +1,12 @@
 import type { AgentClientSnapshot } from "./client.js";
-export type AgentConnectionStatusKind = "unavailable" | "connecting" | "working-disconnected" | "working" | "not-found" | "ready-to-connect" | "connected-not-listening" | "listening";
+export type AgentConnectionStatusKind = "unavailable" | "connecting" | "working-disconnected" | "working" | "paired-elsewhere" | "not-found" | "ready-to-connect" | "connected-not-listening" | "listening";
 export interface AgentConnectionStatus {
     readonly kind: AgentConnectionStatusKind;
     readonly label: string;
     readonly tone: "neutral" | "accent" | "warning" | "danger";
     readonly action?: {
-        readonly kind: "connect" | "setup";
-        readonly label: "Connect" | "Set up";
+        readonly kind: "connect" | "takeover";
+        readonly label: "Connect" | "Take over";
     };
 }
 /** Returns the user-facing connection state shared by the prompt UI and MCP panel. */

package/dist/inspector/agent/connectionStatus.js

@@ -6,6 +6,14 @@ export function getAgentConnectionStatus(snapshot) {
     if (snapshot.state === "pairing") {
         return { kind: "connecting", label: "Connecting…", tone: "accent" };
     }
+    if (snapshot.pairedElsewhere) {
+        return {
+            kind: "paired-elsewhere",
+            label: "MCP active in another tab or window",
+            tone: "warning",
+            action: { kind: "takeover", label: "Take over" },
+        };
+    }
     if (!snapshot.paired && (snapshot.state === "working" || snapshot.request?.status === "working")) {
         return { kind: "working-disconnected", label: "Disconnected · Last work status unknown", tone: "warning" };
     }
@@ -17,7 +25,6 @@ export function getAgentConnectionStatus(snapshot) {
             kind: "connected-not-listening",
             label: "Project connected · Ask agent to listen",
             tone: "accent",
-            action: { kind: "setup", label: "Set up" },
         };
     }
     if (!snapshot.companionReachable) {

package/dist/inspector/agent/httpTransport.d.ts

@@ -1,6 +1,11 @@
 import { type AgentBridgeTransport, type AgentBridgeEndpointConfig, type AgentDiscoveryRequest, type AgentEventHandlers, type AgentEventSubscription, type AgentEventsRequest, type AgentPairRequest, type AgentPromptDispatch, type AgentDisconnectRequest, type AgentCanvasAcknowledgementRequest, type AgentSessionRequest, type AgentStatusSnapshot, type PairingResponse, type PromptDispatchResponse } from "./protocol.js";
 /** Returns whether the dev host supplied a trusted project bridge endpoint. */
 export declare function shouldAutoConnectAgentBridge(): boolean;
+export declare class AgentBridgeHttpError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(status: number, message: string, code?: string);
+}
 /**
  * HTTP/SSE browser adapter for the companion's canonical endpoints.
  *
@@ -13,6 +18,7 @@ export declare class HttpAgentBridgeTransport implements AgentBridgeTransport {
     constructor(config?: AgentBridgeEndpointConfig);
     discover(request: AgentDiscoveryRequest, signal?: AbortSignal): Promise<AgentStatusSnapshot | null>;
     pair(request: AgentPairRequest, signal?: AbortSignal): Promise<PairingResponse>;
+    takeOver(request: AgentPairRequest, signal?: AbortSignal): Promise<PairingResponse>;
     restore(request: AgentSessionRequest, signal?: AbortSignal): Promise<AgentStatusSnapshot | null>;
     openEvents(request: AgentEventsRequest, handlers: AgentEventHandlers): AgentEventSubscription;
     dispatch(request: AgentPromptDispatch, signal?: AbortSignal): Promise<PromptDispatchResponse>;