@nudge-ui/mcp 0.2.1 → 0.2.2

package/dist/discovery.js

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { realpath } from "node:fs/promises";
-import { resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { ProjectSessionClient } from "./projectSessionClient.js";
-import { readLiveProjectSessions } from "./sessionRegistry.js";
+import { inspectProjectSessions, readLiveProjectSessions } from "./sessionRegistry.js";
 import { matchesApplication, selectProjectSession } from "./sessionSelection.js";
 import { defaultSessionRegistryRoot, resolveWorkspaceRoot, } from "./project.js";
 function publicSession(session) {
@@ -10,15 +10,17 @@ function publicSession(session) {
     return visible;
 }
 export async function discoverProjectSessions(applicationRoot, registryRoot = defaultSessionRegistryRoot()) {
-    const canonicalApplication = await realpath(resolve(applicationRoot));
-    const canonicalWorkspace = await resolveWorkspaceRoot(canonicalApplication);
+    const canonicalApplication = applicationRoot === undefined
+        ? undefined
+        : await realpath(requireAbsoluteWorkspaceRoot(applicationRoot));
+    const canonicalWorkspace = canonicalApplication === undefined ? undefined : await resolveWorkspaceRoot(canonicalApplication);
     const live = await readLiveProjectSessions(resolve(registryRoot));
     return live.map(({ descriptor, health }) => {
         const matchesWorkspace = descriptor.workspaceRoot === canonicalWorkspace;
         return {
             ...publicSession(descriptor),
             matchesWorkspace,
-            matchesApplication: matchesApplication(descriptor, {
+            matchesApplication: canonicalWorkspace !== undefined && canonicalApplication !== undefined && matchesApplication(descriptor, {
                 workspaceRoot: canonicalWorkspace,
                 applicationRoot: canonicalApplication,
             }),
@@ -39,20 +41,34 @@ export class DiscoveredProjectRouter {
     agentId;
     client = null;
     releaseGeneration = 0;
+    connectionQueue = Promise.resolve();
     constructor(workspaceRoot, applicationRoot, registryRoot, agentId) {
         this.workspaceRoot = workspaceRoot;
         this.applicationRoot = applicationRoot;
         this.registryRoot = registryRoot;
         this.agentId = agentId;
     }
+    get selectedSessionId() {
+        return this.client?.descriptor.sessionId;
+    }
+    static forSession(session, registryRoot) {
+        const router = new DiscoveredProjectRouter(session.workspaceRoot, session.appRoot, registryRoot, randomUUID());
+        router.client = new ProjectSessionClient(session, router.agentId);
+        return router;
+    }
     static async create(workspaceRoot, registryRoot = defaultSessionRegistryRoot()) {
-        const applicationRoot = await realpath(resolve(workspaceRoot));
+        const applicationRoot = await realpath(requireAbsoluteWorkspaceRoot(workspaceRoot));
         return new DiscoveredProjectRouter(await resolveWorkspaceRoot(applicationRoot), applicationRoot, resolve(registryRoot), randomUUID());
     }
     async listSessions() {
         return await discoverProjectSessions(this.applicationRoot, this.registryRoot);
     }
-    async connectToSession(sessionId) {
+    connectToSession(sessionId) {
+        const connection = this.connectionQueue.then(() => this.selectSession(sessionId));
+        this.connectionQueue = connection.then(() => undefined, () => undefined);
+        return connection;
+    }
+    async selectSession(sessionId) {
         const live = await readLiveProjectSessions(this.registryRoot);
         const selected = selectProjectSession(live.map(({ descriptor }) => descriptor), {
             workspaceRoot: this.workspaceRoot,
@@ -102,6 +118,7 @@ export class DiscoveredProjectRouter {
     }
     async release() {
         this.releaseGeneration += 1;
+        await this.connectionQueue;
         const client = this.client;
         this.client = null;
         await client?.close();
@@ -110,3 +127,34 @@ export class DiscoveredProjectRouter {
         await this.release();
     }
 }
+/** Returns diagnostic counts, scope, and public paths without exposing registry credentials. */
+export async function diagnoseProjectSessions(applicationRoot, registryRoot = defaultSessionRegistryRoot()) {
+    const resolvedRegistryRoot = resolve(registryRoot);
+    const app = applicationRoot === undefined
+        ? undefined
+        : await realpath(requireAbsoluteWorkspaceRoot(applicationRoot));
+    const workspace = app === undefined ? undefined : await resolveWorkspaceRoot(app);
+    const inspection = await inspectProjectSessions(resolvedRegistryRoot);
+    const matching = (session) => app === undefined || (session.workspaceRoot === workspace && (app === workspace || session.appRoot === app));
+    return {
+        registryRoot: resolvedRegistryRoot,
+        workspaceRoot: workspace,
+        applicationRoot: app,
+        descriptorCount: inspection.descriptorCount,
+        invalidCount: inspection.invalidCount,
+        incompatibleCount: inspection.incompatibleCount,
+        reachableCount: inspection.live.length,
+        matchingReachableCount: inspection.live.filter(({ descriptor }) => matching(descriptor)).length,
+        matchingUnreachableCount: inspection.unreachable.filter(matching).length,
+        guidance: [
+            ...(inspection.invalidCount > 0 ? ["Some session descriptors or authenticated health responses are invalid. Check the adapter and project bridge versions, descriptor permissions, and bridge logs."] : []),
+            ...(inspection.unreachable.some(matching) ? ["Matching descriptors exist but their loopback endpoints are unreachable. The server may have stopped or local networking may be blocked. Retry outside the agent command sandbox; do not treat this as proof that no bridge registered."] : []),
+            ...(inspection.incompatibleCount > 0 ? ["Some registrations use an incompatible protocol. Upgrade the reusable adapter and the project's @nudge-ui/mcp dependency, then restart the development server and agent host."] : []),
+        ],
+    };
+}
+function requireAbsoluteWorkspaceRoot(workspaceRoot) {
+    if (!isAbsolute(workspaceRoot))
+        throw new TypeError("workspaceRoot must be an absolute path.");
+    return workspaceRoot;
+}

package/dist/projectSessionClient.d.ts

@@ -7,6 +7,11 @@ export interface SessionHealth {
     readonly claimed: boolean;
     readonly status: AgentStatusSnapshot;
 }
+/** Represents an HTTP response from a project bridge that could be classified. */
+export declare class ProjectSessionResponseError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
 export declare function readSessionHealth(session: StoredProjectSession, timeoutMs?: number): Promise<SessionHealth>;
 /** Owns one project's claim, heartbeat, and authenticated control requests. */
 export declare class ProjectSessionClient {

package/dist/projectSessionClient.js

@@ -2,6 +2,15 @@ import { randomUUID } from "node:crypto";
 import { AGENT_CONTROL_ENDPOINTS } from "./protocol.js";
 const CONTROL_TIMEOUT_MS = 5_000;
 const CANVAS_TIMEOUT_MS = 65_000;
+/** Represents an HTTP response from a project bridge that could be classified. */
+export class ProjectSessionResponseError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "ProjectSessionResponseError";
+        this.status = status;
+    }
+}
 async function requestJson(session, path, init = {}, { signal, timeoutMs = CONTROL_TIMEOUT_MS } = {}) {
     const response = await fetch(`${session.endpoint}${path}`, {
         ...init,
@@ -14,8 +23,9 @@ async function requestJson(session, path, init = {}, { signal, timeoutMs = CONTR
         },
     });
     const body = await response.json().catch(() => undefined);
-    if (!response.ok)
-        throw new Error(body?.error?.message ?? `Nudge project bridge returned ${response.status}.`);
+    if (!response.ok) {
+        throw new ProjectSessionResponseError(response.status, body?.error?.message ?? `Nudge project bridge returned ${response.status}.`);
+    }
     return body;
 }
 export async function readSessionHealth(session, timeoutMs = CONTROL_TIMEOUT_MS) {

package/dist/protocol.d.ts

@@ -11,6 +11,7 @@ export type { AgentConnectionState, AgentProjectIdentity, AgentPromptRequest, Ag
 export declare const BRIDGE_ENDPOINTS: {
     readonly health: "/health";
     readonly pair: "/pair";
+    readonly takeover: "/takeover";
     readonly events: "/events";
     readonly prompt: "/prompt";
     readonly status: "/status";

package/dist/protocol.js

@@ -10,6 +10,7 @@ export { AGENT_PROTOCOL_LIMITS, AGENT_PROTOCOL_VERSION, CANVAS_COMMAND_TYPES, ca
 export const BRIDGE_ENDPOINTS = {
     health: "/health",
     pair: "/pair",
+    takeover: "/takeover",
     events: "/events",
     prompt: "/prompt",
     status: "/status",

package/dist/server.d.ts

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { AgentProjectIdentity } from "./internal/agent-protocol.js";
 import { type BrowserBridge, type BrowserBridgeOptions, type BridgeAddress } from "./bridge.js";
+import { AdapterRouting } from "./adapterRouting.js";
 import { DiscoveredProjectRouter } from "./discovery.js";
 export declare const MCP_SERVER_NAME = "nudge-ui";
 export declare const MCP_SERVER_VERSION: string;
@@ -29,13 +30,13 @@ export interface AgentCompanion {
 export declare function createAgentCompanion(options: AgentCompanionOptions): AgentCompanion;
 export interface DiscoveredAgentAdapter {
     readonly mcpServer: McpServer;
-    readonly router: DiscoveredProjectRouter;
+    readonly router: DiscoveredProjectRouter | AdapterRouting;
     start(transport?: Transport): Promise<void>;
     close(): Promise<void>;
 }
 /** Creates a stdio MCP adapter that discovers project-owned bridges. */
 export declare function createDiscoveredAgentAdapter(options: {
-    readonly workspaceRoot: string;
+    readonly workspaceRoot?: string;
     readonly registryRoot?: string;
     readonly serverName?: string;
     readonly serverVersion?: string;

package/dist/server.js

@@ -1,9 +1,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { realpath } from "node:fs/promises";
 import { createRequire } from "node:module";
+import { isAbsolute } from "node:path";
 import { z } from "zod";
 import { createLoopbackBridge, } from "./bridge.js";
-import { DiscoveredProjectRouter } from "./discovery.js";
+import { AdapterRouting } from "./adapterRouting.js";
+import { DiscoveredProjectRouter, diagnoseProjectSessions, discoverProjectSessions } from "./discovery.js";
 export const MCP_SERVER_NAME = "nudge-ui";
 export const MCP_SERVER_VERSION = readPackageVersion();
 function readPackageVersion() {
@@ -19,13 +22,14 @@ function readPackageVersion() {
 /** Instructions are sent through MCP initialization for every host. */
 export const MCP_SERVER_INSTRUCTIONS = [
     "Nudge UI is a local browser companion for one exact project workspace or Git worktree.",
-    "Before listening, compare each session's workspaceRoot and appRoot with the checkout and application you will edit; if they differ, rerun Nudge agent setup in the intended checkout.",
+    "Supply workspaceRoot with the absolute checkout or application path you are editing on every tool call. Listing and selecting sessions requires this explicit scope; repeat the same workspaceRoot and sessionId for status, Canvas, and release calls. Never use the MCP process working directory to infer the task workspace.",
     "When the user asks to listen to Nudge, call nudge_list_sessions when that tool is available; if several apps are running, select only a session marked matchesApplication.",
     "Call nudge_listen (or nudge_connect) and keep the call open while waiting for a browser request; the bridge may be running before a listener exists.",
     "After a prompt is delivered, edit the project source using the host's normal approval flow.",
     "Report completed, failed, or interrupted status with nudge_report_status before listening again.",
     "When the user asks to stop listening, call nudge_release when that tool is available so another agent can claim the project session.",
     "Canvas tools operate only on same-origin routes from the paired project.",
+    "Automated browsers such as Playwright and headless Chrome get the plain app without the Nudge editor; add ?nudge-ui=on to a URL only when testing Nudge itself.",
     "No request, prompt, or browser state is persisted by this companion.",
 ].join(" ");
 function textResult(value) {
@@ -70,18 +74,34 @@ function boundedWorkspaceRoot(value) {
         throw new TypeError("workspaceRoot must be a bounded non-empty string");
     return value;
 }
-function installTools(mcpServer, bridge) {
+function installTools(mcpServer, bridge, routing) {
+    const target = async (args) => {
+        if (routing)
+            return await routing.target(args);
+        if (bridge instanceof DiscoveredProjectRouter && args.workspaceRoot !== undefined
+            && await realpath(args.workspaceRoot) !== bridge.applicationRoot) {
+            throw new Error("This legacy MCP configuration is restricted to another application. Rerun agent setup to migrate it to the reusable adapter.");
+        }
+        return bridge;
+    };
+    const workspaceInput = z.string().min(1).max(4096)
+        .refine(isAbsolute, "workspaceRoot must be an absolute path.")
+        .describe("Absolute path of the checkout or application being edited.");
+    const scopeInput = {
+        workspaceRoot: routing ? workspaceInput : workspaceInput.optional(),
+        sessionId: z.string().uuid().optional(),
+    };
     const listen = async (args, extra) => {
         try {
-            return promptResult(await bridge.waitForPrompt(extra.signal, args.sessionId));
+            return promptResult(await (await target(args)).waitForPrompt(extra.signal, args.sessionId));
         }
         catch (error) {
             return errorResult(error);
         }
     };
     const listenDescription = "When the user asks to listen to Nudge, wait for one browser prompt. Keep this standard MCP call open, then call nudge_report_status and listen again after the request ends.";
-    const emptyInput = {};
-    const listenInput = bridge.listSessions ? { sessionId: z.string().uuid().optional() } : emptyInput;
+    const emptyInput = scopeInput;
+    const listenInput = scopeInput;
     mcpServer.registerTool("nudge_listen", {
         title: "Listen for Nudge requests",
         description: listenDescription,
@@ -99,24 +119,39 @@ function installTools(mcpServer, bridge) {
         description: "Read the in-memory browser pairing and request status for this project.",
         inputSchema: emptyInput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async () => textResult(await bridge.getStatus()));
-    if (bridge.listSessions) {
+    }, async (args) => {
+        try {
+            return textResult(await (await target(args)).getStatus());
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    if (routing || bridge?.listSessions) {
         mcpServer.registerTool("nudge_list_sessions", {
             title: "List Nudge project sessions",
-            description: "List live local Nudge sessions. Only sessions marked matchesApplication can be selected by an application-scoped adapter.",
+            description: "List live local Nudge sessions for the supplied checkout or application path. The workspaceRoot value is required so the adapter can select only sessions in that explicit scope.",
             inputSchema: emptyInput,
             annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-        }, async () => textResult(await bridge.listSessions()));
+        }, async (args) => textResult(routing ? await discoverProjectSessions(args.workspaceRoot, routing.registryRoot) : await bridge.listSessions()));
     }
-    if (bridge.release) {
+    if (routing) {
+        mcpServer.registerTool("nudge_diagnose", {
+            title: "Diagnose Nudge discovery",
+            description: "Diagnose Nudge discovery for the supplied checkout or application path. The result includes the resolved registry, workspace, and application scope plus counts for missing registrations, invalid descriptors or health responses, unreachable loopback endpoints, and incompatible bridge protocols; credentials are never exposed.",
+            inputSchema: scopeInput,
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        }, async (args) => textResult(await diagnoseProjectSessions(args.workspaceRoot, routing.registryRoot)));
+    }
+    if (routing || bridge?.release) {
         mcpServer.registerTool("nudge_release", {
             title: "Release Nudge session",
             description: "Stop listening and release this adapter's project-session claim so another agent can connect.",
             inputSchema: emptyInput,
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-        }, async () => {
+        }, async (args) => {
             try {
-                await bridge.release();
+                await (await target(args)).release();
                 return textResult({ released: true });
             }
             catch (error) {
@@ -126,8 +161,9 @@ function installTools(mcpServer, bridge) {
     }
     mcpServer.registerTool("nudge_report_status", {
         title: "Report Nudge request status",
-        description: "Report working, completed, failed, or interrupted status for the prompt currently being handled.",
+        description: "Report working, completed, failed, or interrupted status for the prompt currently being handled. Report completed only after implementing the request; the browser removes its submitted sketches if their revisions are unchanged.",
         inputSchema: {
+            ...scopeInput,
             requestId: z.string().min(1).max(256),
             status: z.enum(["working", "completed", "failed", "interrupted"]),
             summary: z.string().max(32_000).optional(),
@@ -142,8 +178,8 @@ function installTools(mcpServer, bridge) {
             ...(args.error === undefined ? {} : { error: args.error }),
         };
         try {
-            const updated = await bridge.updateRequestStatus(update);
-            return textResult(updated ?? await bridge.getStatus());
+            const updated = await (await target(args)).updateRequestStatus(update);
+            return textResult(updated ?? await (await target(args)).getStatus());
         }
         catch (error) {
             return errorResult(error);
@@ -154,9 +190,9 @@ function installTools(mcpServer, bridge) {
         description: "Read the paired browser's current Canvas groups and focus.",
         inputSchema: emptyInput,
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async () => {
+    }, async (args) => {
         try {
-            return commandResult(await bridge.dispatchCanvasCommand({ type: "read-state" }));
+            return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "read-state" }));
         }
         catch (error) {
             return errorResult(error);
@@ -166,6 +202,7 @@ function installTools(mcpServer, bridge) {
         title: "Present routes in Canvas",
         description: "Append or focus an agent-owned, labeled comparison group of same-origin project routes in Canvas.",
         inputSchema: {
+            ...scopeInput,
             label: z.string().min(1).max(160),
             groupId: z.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/).optional(),
             routes: z.array(z.object({
@@ -177,7 +214,7 @@ function installTools(mcpServer, bridge) {
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, async (args) => {
         try {
-            return commandResult(await bridge.dispatchCanvasCommand({
+            return commandResult(await (await target(args)).dispatchCanvasCommand({
                 type: "present-routes",
                 groupId: args.groupId ?? `agent-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
                 label: args.label,
@@ -191,11 +228,11 @@ function installTools(mcpServer, bridge) {
     mcpServer.registerTool("nudge_focus_canvas_group", {
         title: "Focus Canvas group",
         description: "Focus an existing Canvas comparison group by its stable group ID.",
-        inputSchema: { groupId: z.string().min(1).max(256) },
+        inputSchema: { ...scopeInput, groupId: z.string().min(1).max(256) },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
-            return commandResult(await bridge.dispatchCanvasCommand({ type: "focus-group", groupId: args.groupId }));
+            return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "focus-group", groupId: args.groupId }));
         }
         catch (error) {
             return errorResult(error);
@@ -206,9 +243,9 @@ function installTools(mcpServer, bridge) {
         description: "Fit all current Canvas cards into the browser board.",
         inputSchema: emptyInput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async () => {
+    }, async (args) => {
         try {
-            return commandResult(await bridge.dispatchCanvasCommand({ type: "fit-all" }));
+            return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "fit-all" }));
         }
         catch (error) {
             return errorResult(error);
@@ -217,11 +254,11 @@ function installTools(mcpServer, bridge) {
     mcpServer.registerTool("nudge_remove_canvas_group", {
         title: "Remove agent Canvas group",
         description: "Remove an agent-owned Canvas comparison group. The browser refuses removal of user-owned groups.",
-        inputSchema: { groupId: z.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/) },
+        inputSchema: { ...scopeInput, groupId: z.string().min(1).max(256).regex(/^agent-[A-Za-z0-9._:-]+$/) },
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
         try {
-            return commandResult(await bridge.dispatchCanvasCommand({ type: "remove-group", groupId: args.groupId }));
+            return commandResult(await (await target(args)).dispatchCanvasCommand({ type: "remove-group", groupId: args.groupId }));
         }
         catch (error) {
             return errorResult(error);
@@ -287,18 +324,21 @@ export function createAgentCompanion(options) {
 }
 /** Creates a stdio MCP adapter that discovers project-owned bridges. */
 export async function createDiscoveredAgentAdapter(options) {
-    const router = await DiscoveredProjectRouter.create(options.workspaceRoot, options.registryRoot);
+    const routing = options.workspaceRoot === undefined ? new AdapterRouting(options.registryRoot) : undefined;
+    const router = options.workspaceRoot === undefined
+        ? undefined
+        : await DiscoveredProjectRouter.create(options.workspaceRoot, options.registryRoot);
     const mcpServer = new McpServer({
         name: options.serverName ?? MCP_SERVER_NAME,
         version: options.serverVersion ?? MCP_SERVER_VERSION,
     }, { instructions: MCP_SERVER_INSTRUCTIONS });
-    installTools(mcpServer, router);
+    installTools(mcpServer, router, routing);
     let transport = null;
     let started = false;
     let closePromise = null;
     return {
         mcpServer,
-        router,
+        router: (router ?? routing),
         async start(providedTransport) {
             if (started)
                 return;
@@ -312,7 +352,7 @@ export async function createDiscoveredAgentAdapter(options) {
             if (closePromise)
                 return closePromise;
             closePromise = (async () => {
-                await router.close();
+                await (router ?? routing).close();
                 if (transport)
                     await mcpServer.close().catch(() => undefined);
             })();

package/dist/sessionRegistry.d.ts

@@ -4,5 +4,14 @@ export interface LiveProjectSession {
     readonly descriptor: StoredProjectSession;
     readonly health: SessionHealth;
 }
-/** Reads private registry records and keeps only bridges that answer authenticated probes. */
+export interface SessionInspection {
+    readonly descriptorCount: number;
+    readonly invalidCount: number;
+    readonly incompatibleCount: number;
+    readonly unreachable: readonly Pick<StoredProjectSession, "workspaceRoot" | "appRoot" | "sessionId">[];
+    readonly live: LiveProjectSession[];
+}
+/** Separates absent, invalid, incompatible, and unreachable registrations. */
+export declare function inspectProjectSessions(registryRoot: string): Promise<SessionInspection>;
+/** Keeps only compatible bridges that answer authenticated probes. */
 export declare function readLiveProjectSessions(registryRoot: string): Promise<LiveProjectSession[]>;

package/dist/sessionRegistry.js

@@ -1,15 +1,28 @@
 import { lstat, readFile, readdir, realpath } from "node:fs/promises";
 import { resolve } from "node:path";
 import { AGENT_PROTOCOL_VERSION } from "./internal/agent-protocol.js";
-import { readSessionHealth } from "./projectSessionClient.js";
+import { ProjectSessionResponseError, readSessionHealth } from "./projectSessionClient.js";
 const PROBE_TIMEOUT_MS = 750;
 const MAX_DESCRIPTOR_BYTES = 32 * 1024;
-/** Reads private registry records and keeps only bridges that answer authenticated probes. */
+/** Separates absent, invalid, incompatible, and unreachable registrations. */
+export async function inspectProjectSessions(registryRoot) {
+    const names = (await readRegistryDirectory(registryRoot)).filter((name) => name.endsWith(".json"));
+    const records = await Promise.all(names.map((name) => readDescriptor(resolve(registryRoot, name))));
+    const descriptors = records.filter((record) => typeof record === "object");
+    const probes = await Promise.all(descriptors.map(probeSession));
+    return {
+        descriptorCount: names.length,
+        invalidCount: records.filter((record) => record === undefined).length
+            + probes.filter((probe) => probe.kind === "invalid").length,
+        incompatibleCount: records.filter((record) => record === "incompatible").length,
+        unreachable: descriptors.filter((_, index) => probes[index]?.kind === "unreachable")
+            .map(({ workspaceRoot, appRoot, sessionId }) => ({ workspaceRoot, appRoot, sessionId })),
+        live: probes.flatMap((probe) => probe.kind === "live" ? [probe.session] : []),
+    };
+}
+/** Keeps only compatible bridges that answer authenticated probes. */
 export async function readLiveProjectSessions(registryRoot) {
-    const names = await readRegistryDirectory(registryRoot);
-    const descriptors = await Promise.all(names.filter((name) => name.endsWith(".json")).map((name) => readDescriptor(resolve(registryRoot, name))));
-    const live = await Promise.all(descriptors.filter(isPresent).map(probeSession));
-    return live.filter(isPresent);
+    return (await inspectProjectSessions(registryRoot)).live;
 }
 async function readRegistryDirectory(registryRoot) {
     try {
@@ -33,8 +46,10 @@ async function readDescriptor(path) {
         const parsed = JSON.parse(await readFile(path, "utf8"));
         if (!isStoredSession(parsed))
             return undefined;
+        if (parsed.protocolVersion !== AGENT_PROTOCOL_VERSION)
+            return "incompatible";
         const [workspaceRoot, appRoot] = await Promise.all([realpath(parsed.workspaceRoot), realpath(parsed.appRoot)]);
-        return { ...parsed, workspaceRoot, appRoot };
+        return { ...parsed, protocolVersion: AGENT_PROTOCOL_VERSION, workspaceRoot, appRoot };
     }
     catch {
         // Records can disappear during shutdown or refer to a removed worktree.
@@ -44,17 +59,34 @@ async function readDescriptor(path) {
 async function probeSession(descriptor) {
     try {
         const health = await readSessionHealth(descriptor, PROBE_TIMEOUT_MS);
-        if (health.projectId !== descriptor.projectId || health.available !== true)
-            return undefined;
-        return { descriptor, health };
+        if (!isSessionHealth(health) || health.projectId !== descriptor.projectId)
+            return { kind: "invalid" };
+        return { kind: "live", session: { descriptor, health } };
     }
-    catch {
-        // A stale or unreachable bridge is not a selectable session.
-        return undefined;
+    catch (error) {
+        // An HTTP response proves that the endpoint exists. Network and timeout errors are unreachable.
+        return { kind: error instanceof ProjectSessionResponseError ? "invalid" : "unreachable" };
     }
 }
-function isPresent(value) {
-    return value !== undefined;
+function isSessionHealth(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const health = value;
+    return typeof health.projectId === "string"
+        && health.available === true
+        && typeof health.claimed === "boolean"
+        && isAgentStatusSnapshot(health.status);
+}
+function isAgentStatusSnapshot(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const status = value;
+    return status.protocolVersion === AGENT_PROTOCOL_VERSION
+        && typeof status.projectId === "string"
+        && (status.connection === "offline" || status.connection === "listening" || status.connection === "paired" || status.connection === "working")
+        && typeof status.listenerActive === "boolean"
+        && typeof status.paired === "boolean"
+        && (status.request === null || (typeof status.request === "object" && !Array.isArray(status.request)));
 }
 function isLoopbackEndpoint(value) {
     if (typeof value !== "string")
@@ -74,7 +106,7 @@ function isStoredSession(value) {
         return false;
     const session = value;
     return session.schemaVersion === 1
-        && session.protocolVersion === AGENT_PROTOCOL_VERSION
+        && typeof session.protocolVersion === "number" && Number.isSafeInteger(session.protocolVersion)
         && typeof session.sessionId === "string" && session.sessionId.length > 0
         && typeof session.projectId === "string" && session.projectId.length > 0
         && typeof session.workspaceRoot === "string" && session.workspaceRoot.length > 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nudge-ui/mcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Optional local MCP companion for pairing Nudge UI with coding agents.",
   "license": "MIT",
   "repository": {