@atezer/figma-mcp-bridge 1.7.28 → 1.7.30

package/dist/core/plugin-bridge-server.js

@@ -6,9 +6,14 @@
  * (e.g. Figma Desktop + FigJam browser + Figma browser — all on one port).
  * Each connected plugin identifies itself with a fileKey; requests are routed accordingly.
  *
- * Port strategy: graceful takeover. If the configured port is busy with another
- * F-MCP instance, the server sends a /shutdown request to the old bridge and
- * retries after it exits. Stale ports get one automatic retry after a short delay.
+ * Port strategy: smart auto-increment with coexistence.
+ * - If the preferred port (default 5454) is occupied by a HEALTHY F-MCP bridge
+ *   (active clients), the server skips to the next port (5455, 5456, …).
+ * - If the port is occupied by a STALE F-MCP bridge (0 clients, uptime ≥ 30s),
+ *   the server sends a /shutdown request and takes over.
+ * - If the port is occupied by a non-F-MCP service or unresponsive process,
+ *   the server skips to the next port.
+ * - The Figma plugin scans all ports 5454–5470 automatically.
  */
 import { WebSocketServer } from "ws";
 import { createServer, get as httpGet, request as httpRequest } from "http";
@@ -21,6 +26,8 @@ const MIN_PORT = 5454;
 const MAX_PORT = 5470;
 const STALE_PORT_RETRY_DELAY_MS = 1500;
 const SHUTDOWN_TAKEOVER_DELAY_MS = 2000;
+/** Bridges with 0 clients AND uptime below this are considered freshly started, not stale. */
+const FRESH_BRIDGE_UPTIME_THRESHOLD_S = 30;
 export class PluginBridgeServer {
     constructor(port, options) {
         this.wss = null;
@@ -86,7 +93,7 @@ export class PluginBridgeServer {
         }
         this.startError = null;
         this.detectClientNameAsync();
-        this.tryListenFixed(this.preferredPort, false);
+        this.tryListenWithAutoIncrement(this.preferredPort);
     }
     /** Get last startup error (null if running fine). */
     getStartError() {
@@ -101,15 +108,16 @@ export class PluginBridgeServer {
         this.startError = null;
         return this.tryListenAsync(clamped);
     }
-    /** Async listen attempt — resolves when port binds successfully or fails. */
+    /** Async listen attempt — resolves when port binds successfully or all ports exhausted. */
     tryListenAsync(port) {
         return new Promise((resolve) => {
-            const TIMEOUT_MS = 5000;
+            // 30s timeout covers worst case: 17 ports × ~2s probe each
+            const TIMEOUT_MS = 30000;
             const timer = setTimeout(() => {
                 this._listenResolve = null;
-                resolve({ success: false, port, error: this.startError || `Port ${port} bind timeout (${TIMEOUT_MS}ms)` });
+                resolve({ success: false, port, error: this.startError || `Port bind timeout (${TIMEOUT_MS}ms)` });
             }, TIMEOUT_MS);
-            // Store original callback so tryListenFixed can notify us
+            // Store callback so tryListenWithAutoIncrement/setupBridgeOnServer can notify us
             this._listenResolve = (success) => {
                 clearTimeout(timer);
                 if (success) {
@@ -119,13 +127,17 @@ export class PluginBridgeServer {
                     resolve({ success: false, port, error: this.startError || "Port bind failed" });
                 }
             };
-            this.tryListenFixed(port, false);
+            this.tryListenWithAutoIncrement(port);
         });
     }
     /** Currently listening port (or preferred port if not yet listening). */
     getPort() {
         return this.port;
     }
+    /** User/config preferred port before auto-increment fallback. */
+    getPreferredPort() {
+        return this.preferredPort;
+    }
     /** Whether WebSocket server is actively listening. */
     isListening() {
         return this.wss !== null;
@@ -158,6 +170,23 @@ export class PluginBridgeServer {
         }
         return this.getDefaultClient();
     }
+    /**
+     * Wait for a client to become ready (fileKey populated via "ready" message).
+     * Polls at 200ms intervals. Used to handle the race between plugin connection
+     * and the first incoming MCP request.
+     */
+    async waitForClient(fileKey, timeoutMs = 2000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const client = this.resolveClient(fileKey);
+            if (client && client.ws.readyState === 1) {
+                if (!fileKey || client.fileKey === fileKey)
+                    return client;
+            }
+            await new Promise(r => setTimeout(r, 200));
+        }
+        return this.resolveClient(fileKey);
+    }
     removeClient(clientId, reason) {
         const info = this.clients.get(clientId);
         if (!info)
@@ -185,9 +214,71 @@ export class PluginBridgeServer {
             req.on("timeout", () => { req.destroy(); resolve("dead"); });
         });
     }
+    /**
+     * Probe a live F-MCP bridge's /status endpoint to get its health info.
+     * Returns { clients, uptime } or { -1, -1 } if the endpoint is unavailable
+     * (e.g. older bridge version without /status).
+     */
+    probeStatus(port, host) {
+        return new Promise((resolve) => {
+            const req = httpGet({ hostname: host, port, path: "/status", timeout: 1000 }, (res) => {
+                let body = "";
+                res.on("data", (chunk) => { body += chunk; });
+                res.on("end", () => {
+                    try {
+                        const data = JSON.parse(body);
+                        resolve({
+                            clients: typeof data.clients === "number" ? data.clients : -1,
+                            uptime: typeof data.uptime === "number" ? data.uptime : -1,
+                        });
+                    }
+                    catch {
+                        resolve({ clients: -1, uptime: -1 });
+                    }
+                });
+            });
+            req.on("error", () => resolve({ clients: -1, uptime: -1 }));
+            req.on("timeout", () => { req.destroy(); resolve({ clients: -1, uptime: -1 }); });
+        });
+    }
+    /**
+     * Send a POST /shutdown to an old F-MCP bridge. Calls onAccepted if the bridge
+     * responds with 200, or onRefused otherwise. On error/timeout, assumes the bridge
+     * may have already exited and calls onAccepted.
+     */
+    sendShutdownRequest(port, host, onAccepted, onRefused) {
+        console.error(`   Sending shutdown request to old F-MCP bridge on port ${port}…\n`);
+        const req = httpRequest({ hostname: host, port, path: "/shutdown", method: "POST", timeout: 3000 }, (res) => {
+            let body = "";
+            res.on("data", (chunk) => { body += chunk; });
+            res.on("end", () => {
+                if (res.statusCode === 200) {
+                    console.error(`   Old bridge accepted shutdown. Retaking port ${port} in ${SHUTDOWN_TAKEOVER_DELAY_MS}ms…\n`);
+                    onAccepted();
+                }
+                else {
+                    console.error(`\n⚠️  Old bridge refused shutdown (status ${res.statusCode}). Trying next port…\n`);
+                    logger.warn({ port, statusCode: res.statusCode }, "Old bridge refused shutdown");
+                    onRefused();
+                }
+            });
+        });
+        req.on("error", () => {
+            // Old bridge unreachable — might have already exited
+            console.error(`   Old bridge unreachable after shutdown request. Retrying port ${port}…\n`);
+            onAccepted();
+        });
+        req.on("timeout", () => {
+            req.destroy();
+            console.error(`   Shutdown request timed out. Retrying port ${port}…\n`);
+            onAccepted();
+        });
+        req.end();
+    }
     /**
      * Send a POST /shutdown to an old F-MCP bridge on the given port,
      * wait for it to exit, then retry binding to the same port.
+     * @deprecated Legacy method — kept for backward compatibility. New code uses sendShutdownRequest + tryListenWithAutoIncrement.
      */
     requestShutdownAndRetry(port, host) {
         console.error(`   Sending shutdown request to old F-MCP bridge on port ${port}…\n`);
@@ -223,18 +314,36 @@ export class PluginBridgeServer {
         });
         req.end();
     }
-    tryListenFixed(port, isRetry) {
-        const server = createServer((req, res) => {
+    // ──────────────────────────────────────────────────────────────────────
+    // HTTP server factory (shared between tryListenFixed and tryListenWithAutoIncrement)
+    // ──────────────────────────────────────────────────────────────────────
+    /** Create an HTTP server with /shutdown, /status, and default F-MCP marker endpoints. */
+    createBridgeHttpServer() {
+        return createServer((req, res) => {
             // Graceful shutdown endpoint: a new bridge instance requests this old one to exit
             if (req.method === "POST" && req.url === "/shutdown") {
                 res.writeHead(200, { "Content-Type": "text/plain" });
                 res.end("shutting down\n");
                 logger.info("Received /shutdown request from new bridge instance — stopping gracefully");
                 console.error("\n⚠️  Received shutdown request from new F-MCP bridge instance. Stopping…\n");
-                // Defer stop to let the response flush
                 setTimeout(() => this.stop(), 500);
                 return;
             }
+            // Health check endpoint — used by new instances to decide coexistence vs takeover
+            if (req.method === "GET" && req.url === "/status") {
+                const body = JSON.stringify({
+                    clients: this.connectedClientCount(),
+                    uptime: Math.round(process.uptime()),
+                    version: FMCP_VERSION,
+                });
+                res.writeHead(200, {
+                    "Content-Type": "application/json",
+                    "Access-Control-Allow-Origin": "*",
+                });
+                res.end(body);
+                return;
+            }
+            // Default F-MCP marker (used by probePort to detect F-MCP bridges)
             res.writeHead(200, {
                 "Content-Type": "text/plain",
                 "Access-Control-Allow-Origin": "*",
@@ -242,6 +351,268 @@ export class PluginBridgeServer {
             });
             res.end("F-MCP ATezer Bridge (connect via WebSocket)\n");
         });
+    }
+    /**
+     * Set up WebSocket server, heartbeat, client handling on a successfully bound HTTP server.
+     * Called from both tryListenFixed and tryListenWithAutoIncrement on bind success.
+     */
+    setupBridgeOnServer(server, port, bindHost) {
+        this.port = port;
+        process.env.FIGMA_PLUGIN_BRIDGE_PORT = String(port);
+        process.env.FIGMA_MCP_BRIDGE_PORT = String(port);
+        console.error(`F-MCP bridge listening on ws://${bindHost}:${port}\n`);
+        this.httpServer = server;
+        this.wss = new WebSocketServer({ server });
+        this.wss.on("connection", (ws) => {
+            const clientId = this.generateClientId();
+            const clientInfo = {
+                ws,
+                clientId,
+                fileKey: null,
+                fileName: null,
+                alive: true,
+                missedHeartbeats: 0,
+                connectedAt: Date.now(),
+            };
+            this.clients.set(clientId, clientInfo);
+            logger.info({ port: this.port, clientId, totalClients: this.clients.size }, "Plugin bridge: new plugin connected");
+            auditPlugin(this.auditLogPath, "plugin_connect");
+            ws.on("message", (data) => {
+                clientInfo.alive = true;
+                try {
+                    const msg = JSON.parse(data.toString());
+                    if (msg.type === "ready") {
+                        const incomingFileKey = msg.fileKey || null;
+                        const incomingFileName = msg.fileName || null;
+                        if (incomingFileKey) {
+                            const existing = this.findClientByFileKey(incomingFileKey);
+                            if (existing && existing.clientId !== clientId) {
+                                logger.info({ oldClientId: existing.clientId, newClientId: clientId, fileKey: incomingFileKey }, "Plugin bridge: replacing existing client for same fileKey");
+                                this.removeClient(existing.clientId, "Replaced by new connection for same file");
+                                try {
+                                    existing.ws.close();
+                                }
+                                catch { /* ignore */ }
+                            }
+                        }
+                        clientInfo.fileKey = incomingFileKey;
+                        clientInfo.fileName = incomingFileName;
+                        logger.info({ clientId, fileKey: incomingFileKey, fileName: incomingFileName }, "Plugin bridge: client registered (fileKey=%s, fileName=%s)", incomingFileKey, incomingFileName);
+                        ws.send(JSON.stringify({
+                            type: "welcome",
+                            bridgeVersion: FMCP_VERSION,
+                            port: this.port,
+                            clientId,
+                            multiClient: true,
+                            clientName: this.clientName,
+                        }));
+                        return;
+                    }
+                    if (msg.type === "pong" || msg.type === "keepalive") {
+                        return;
+                    }
+                    if (msg.type === "setToken" && typeof msg.token === "string") {
+                        const token = msg.token;
+                        if (token) {
+                            this.setFigmaRestToken(token);
+                            logger.info({ clientId }, "Plugin bridge: REST API token set via plugin UI");
+                        }
+                        return;
+                    }
+                    if (msg.type === "clearToken") {
+                        this.clearFigmaRestToken();
+                        logger.info({ clientId }, "Plugin bridge: REST API token cleared via plugin UI");
+                        return;
+                    }
+                    if (msg.id && this.pending.has(msg.id)) {
+                        const p = this.pending.get(msg.id);
+                        this.pending.delete(msg.id);
+                        clearTimeout(p.timeout);
+                        const durationMs = Date.now() - p.startTime;
+                        if (msg.error) {
+                            auditTool(this.auditLogPath, p.method, false, msg.error, durationMs);
+                            p.reject(new Error(msg.error));
+                        }
+                        else {
+                            if (msg.result === undefined) {
+                                logger.warn({ method: p.method, msgId: msg.id }, "Plugin bridge: response has no result and no error");
+                            }
+                            auditTool(this.auditLogPath, p.method, true, undefined, durationMs);
+                            p.resolve(msg.result);
+                        }
+                    }
+                }
+                catch (err) {
+                    logger.warn({ err }, "Plugin bridge: invalid message from plugin");
+                }
+            });
+            ws.on("close", () => {
+                this.removeClient(clientId, "WebSocket closed");
+            });
+            ws.on("error", (err) => {
+                logger.warn({ err, clientId }, "Plugin bridge: client error");
+            });
+        });
+        logger.info({ port: this.port, host: bindHost }, "Plugin bridge server listening (ws://%s:%s) — multi-client enabled", bindHost, this.port);
+        // Notify async restart() / tryListenAsync() that binding succeeded
+        this._listenResolve?.(true);
+        this._listenResolve = null;
+        const heartbeat = () => {
+            for (const [cId, info] of this.clients) {
+                if (info.ws.readyState !== 1) {
+                    this.removeClient(cId, "WebSocket not open");
+                    continue;
+                }
+                if (!info.alive) {
+                    info.missedHeartbeats++;
+                    if (info.missedHeartbeats >= 3) {
+                        logger.warn({ clientId: cId, fileKey: info.fileKey }, "Plugin bridge: client not responding to heartbeat, terminating");
+                        try {
+                            info.ws.terminate();
+                        }
+                        catch { /* ignore */ }
+                        this.removeClient(cId, "Heartbeat timeout");
+                        continue;
+                    }
+                }
+                else {
+                    info.missedHeartbeats = 0;
+                    info.alive = false;
+                }
+                try {
+                    info.ws.send(JSON.stringify({ type: "ping" }));
+                }
+                catch { /* ignore */ }
+            }
+            this.heartbeatTimer = setTimeout(heartbeat, HEARTBEAT_INTERVAL_MS);
+        };
+        this.heartbeatTimer = setTimeout(heartbeat, HEARTBEAT_INTERVAL_MS);
+    }
+    // ──────────────────────────────────────────────────────────────────────
+    // Smart auto-increment port binding (primary startup path)
+    // ──────────────────────────────────────────────────────────────────────
+    /**
+     * Try to bind starting from `port`, auto-incrementing through the valid range.
+     * - Healthy F-MCP bridges (active clients) are skipped.
+     * - Stale F-MCP bridges (0 clients, uptime ≥ 30s) are taken over.
+     * - Freshly started bridges (0 clients, uptime < 30s) are skipped.
+     * - Unknown/old-version bridges and non-F-MCP services are skipped.
+     *
+     * `_listenResolve` is called exactly once: on success or when all ports are exhausted.
+     */
+    tryListenWithAutoIncrement(port) {
+        if (port > MAX_PORT) {
+            const msg = `All ports ${MIN_PORT}–${MAX_PORT} are in use. Cannot start bridge. Free a port or restart a stale instance.`;
+            this.startError = msg;
+            console.error(`\n⚠️  ${msg}\n`);
+            logger.error(msg);
+            this._listenResolve?.(false);
+            this._listenResolve = null;
+            return;
+        }
+        const bindHost = process.env.FIGMA_BRIDGE_HOST || "127.0.0.1";
+        const server = this.createBridgeHttpServer();
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                server.close();
+                const probeHost = bindHost === "0.0.0.0" ? "127.0.0.1" : bindHost;
+                this.probePort(port, probeHost).then(async (status) => {
+                    if (status === "fmcp") {
+                        // F-MCP bridge detected — check health
+                        const { clients, uptime } = await this.probeStatus(port, probeHost);
+                        if (clients > 0) {
+                            // HEALTHY bridge with active clients — coexist, skip to next port
+                            logger.info({ port, clients }, "Port %d: healthy F-MCP bridge (%d clients), skipping to next port", port, clients);
+                            console.error(`   Port ${port}: healthy bridge (${clients} client(s)), trying ${port + 1}…\n`);
+                            this.tryListenWithAutoIncrement(port + 1);
+                        }
+                        else if (clients === 0 && uptime >= 0 && uptime < FRESH_BRIDGE_UPTIME_THRESHOLD_S) {
+                            // FRESHLY STARTED bridge (no clients yet, uptime < 30s) — skip, don't takeover
+                            logger.info({ port, uptime }, "Port %d: freshly started F-MCP bridge (uptime %ds), skipping to next port", port, uptime);
+                            console.error(`   Port ${port}: freshly started bridge (${uptime}s uptime), trying ${port + 1}…\n`);
+                            this.tryListenWithAutoIncrement(port + 1);
+                        }
+                        else if (clients === 0 && uptime >= FRESH_BRIDGE_UPTIME_THRESHOLD_S) {
+                            // STALE bridge (0 clients, uptime ≥ 30s) — takeover
+                            logger.info({ port, uptime }, "Port %d: stale F-MCP bridge (0 clients, %ds uptime), requesting shutdown", port, uptime);
+                            console.error(`\n⚠️  Port ${port}: stale bridge (0 clients, ${uptime}s uptime). Requesting shutdown…\n`);
+                            this.sendShutdownRequest(port, probeHost, () => {
+                                // Shutdown accepted — retry same port after delay
+                                setTimeout(() => {
+                                    const retryServer = this.createBridgeHttpServer();
+                                    retryServer.on("error", (retryErr) => {
+                                        if (retryErr.code === "EADDRINUSE") {
+                                            retryServer.close();
+                                            // Takeover failed — move to next port
+                                            logger.warn({ port }, "Port %d still busy after takeover, trying next", port);
+                                            this.tryListenWithAutoIncrement(port + 1);
+                                            return;
+                                        }
+                                        logger.error({ err: retryErr }, "Plugin bridge server error");
+                                    });
+                                    retryServer.listen(port, bindHost, () => {
+                                        this.setupBridgeOnServer(retryServer, port, bindHost);
+                                    });
+                                }, SHUTDOWN_TAKEOVER_DELAY_MS);
+                            }, () => {
+                                // Shutdown refused — move to next port
+                                this.tryListenWithAutoIncrement(port + 1);
+                            });
+                        }
+                        else {
+                            // Unknown health (old bridge version without /status, or probe failed)
+                            // Safe choice: skip, don't kill
+                            logger.info({ port, clients, uptime }, "Port %d: F-MCP bridge with unknown health (clients=%d, uptime=%d), skipping", port, clients, uptime);
+                            console.error(`   Port ${port}: F-MCP bridge (unknown health), trying ${port + 1}…\n`);
+                            this.tryListenWithAutoIncrement(port + 1);
+                        }
+                    }
+                    else if (status === "dead") {
+                        // Port held by stale/unresponsive process — retry after delay
+                        console.error(`\n⚠️  Port ${port} is busy but not responding. Retrying in ${STALE_PORT_RETRY_DELAY_MS}ms…\n`);
+                        setTimeout(() => {
+                            const retryServer = this.createBridgeHttpServer();
+                            retryServer.on("error", (retryErr) => {
+                                if (retryErr.code === "EADDRINUSE") {
+                                    retryServer.close();
+                                    // Still busy — move to next port
+                                    this.tryListenWithAutoIncrement(port + 1);
+                                    return;
+                                }
+                                logger.error({ err: retryErr }, "Plugin bridge server error");
+                            });
+                            retryServer.listen(port, bindHost, () => {
+                                this.setupBridgeOnServer(retryServer, port, bindHost);
+                            });
+                        }, STALE_PORT_RETRY_DELAY_MS);
+                    }
+                    else {
+                        // Non-F-MCP service — skip to next port
+                        logger.info({ port }, "Port %d occupied by non-F-MCP service, skipping", port);
+                        console.error(`   Port ${port}: non-F-MCP service, trying ${port + 1}…\n`);
+                        this.tryListenWithAutoIncrement(port + 1);
+                    }
+                }).catch(() => {
+                    // Probe failed — skip to next port
+                    this.tryListenWithAutoIncrement(port + 1);
+                });
+                return;
+            }
+            logger.error({ err }, "Plugin bridge server error");
+        });
+        server.listen(port, bindHost, () => {
+            this.setupBridgeOnServer(server, port, bindHost);
+        });
+    }
+    // ──────────────────────────────────────────────────────────────────────
+    // Legacy fixed-port binding (kept for backward compatibility)
+    // ──────────────────────────────────────────────────────────────────────
+    /**
+     * @deprecated Legacy method — new startup uses tryListenWithAutoIncrement().
+     * Kept for backward compatibility with requestShutdownAndRetry retry path.
+     */
+    tryListenFixed(port, isRetry) {
+        const server = this.createBridgeHttpServer();
         const bindHost = process.env.FIGMA_BRIDGE_HOST || "127.0.0.1";
         server.on("error", (err) => {
             if (err.code === "EADDRINUSE") {
@@ -290,136 +661,7 @@ export class PluginBridgeServer {
             logger.error({ err }, "Plugin bridge server error");
         });
         server.listen(port, bindHost, () => {
-            this.port = port;
-            process.env.FIGMA_PLUGIN_BRIDGE_PORT = String(port);
-            process.env.FIGMA_MCP_BRIDGE_PORT = String(port);
-            console.error(`F-MCP bridge listening on ws://${bindHost}:${port}\n`);
-            this.httpServer = server;
-            this.wss = new WebSocketServer({ server });
-            this.wss.on("connection", (ws) => {
-                const clientId = this.generateClientId();
-                const clientInfo = {
-                    ws,
-                    clientId,
-                    fileKey: null,
-                    fileName: null,
-                    alive: true,
-                    missedHeartbeats: 0,
-                    connectedAt: Date.now(),
-                };
-                this.clients.set(clientId, clientInfo);
-                logger.info({ port: this.port, clientId, totalClients: this.clients.size }, "Plugin bridge: new plugin connected");
-                auditPlugin(this.auditLogPath, "plugin_connect");
-                ws.on("message", (data) => {
-                    clientInfo.alive = true;
-                    try {
-                        const msg = JSON.parse(data.toString());
-                        if (msg.type === "ready") {
-                            const incomingFileKey = msg.fileKey || null;
-                            const incomingFileName = msg.fileName || null;
-                            if (incomingFileKey) {
-                                const existing = this.findClientByFileKey(incomingFileKey);
-                                if (existing && existing.clientId !== clientId) {
-                                    logger.info({ oldClientId: existing.clientId, newClientId: clientId, fileKey: incomingFileKey }, "Plugin bridge: replacing existing client for same fileKey");
-                                    this.removeClient(existing.clientId, "Replaced by new connection for same file");
-                                    try {
-                                        existing.ws.close();
-                                    }
-                                    catch { /* ignore */ }
-                                }
-                            }
-                            clientInfo.fileKey = incomingFileKey;
-                            clientInfo.fileName = incomingFileName;
-                            logger.info({ clientId, fileKey: incomingFileKey, fileName: incomingFileName }, "Plugin bridge: client registered (fileKey=%s, fileName=%s)", incomingFileKey, incomingFileName);
-                            ws.send(JSON.stringify({
-                                type: "welcome",
-                                bridgeVersion: FMCP_VERSION,
-                                port: this.port,
-                                clientId,
-                                multiClient: true,
-                                clientName: this.clientName,
-                            }));
-                            return;
-                        }
-                        if (msg.type === "pong" || msg.type === "keepalive") {
-                            return;
-                        }
-                        if (msg.type === "setToken" && typeof msg.token === "string") {
-                            const token = msg.token;
-                            if (token) {
-                                this.setFigmaRestToken(token);
-                                logger.info({ clientId }, "Plugin bridge: REST API token set via plugin UI");
-                            }
-                            return;
-                        }
-                        if (msg.type === "clearToken") {
-                            this.clearFigmaRestToken();
-                            logger.info({ clientId }, "Plugin bridge: REST API token cleared via plugin UI");
-                            return;
-                        }
-                        if (msg.id && this.pending.has(msg.id)) {
-                            const p = this.pending.get(msg.id);
-                            this.pending.delete(msg.id);
-                            clearTimeout(p.timeout);
-                            const durationMs = Date.now() - p.startTime;
-                            if (msg.error) {
-                                auditTool(this.auditLogPath, p.method, false, msg.error, durationMs);
-                                p.reject(new Error(msg.error));
-                            }
-                            else {
-                                if (msg.result === undefined) {
-                                    logger.warn({ method: p.method, msgId: msg.id }, "Plugin bridge: response has no result and no error");
-                                }
-                                auditTool(this.auditLogPath, p.method, true, undefined, durationMs);
-                                p.resolve(msg.result);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        logger.warn({ err }, "Plugin bridge: invalid message from plugin");
-                    }
-                });
-                ws.on("close", () => {
-                    this.removeClient(clientId, "WebSocket closed");
-                });
-                ws.on("error", (err) => {
-                    logger.warn({ err, clientId }, "Plugin bridge: client error");
-                });
-            });
-            logger.info({ port: this.port, host: bindHost }, "Plugin bridge server listening (ws://%s:%s) — multi-client enabled", bindHost, this.port);
-            // Notify async restart() that binding succeeded
-            this._listenResolve?.(true);
-            this._listenResolve = null;
-            const heartbeat = () => {
-                for (const [clientId, info] of this.clients) {
-                    if (info.ws.readyState !== 1) {
-                        this.removeClient(clientId, "WebSocket not open");
-                        continue;
-                    }
-                    if (!info.alive) {
-                        info.missedHeartbeats++;
-                        if (info.missedHeartbeats >= 3) {
-                            logger.warn({ clientId, fileKey: info.fileKey }, "Plugin bridge: client not responding to heartbeat, terminating");
-                            try {
-                                info.ws.terminate();
-                            }
-                            catch { /* ignore */ }
-                            this.removeClient(clientId, "Heartbeat timeout");
-                            continue;
-                        }
-                    }
-                    else {
-                        info.missedHeartbeats = 0;
-                        info.alive = false;
-                    }
-                    try {
-                        info.ws.send(JSON.stringify({ type: "ping" }));
-                    }
-                    catch { /* ignore */ }
-                }
-                this.heartbeatTimer = setTimeout(heartbeat, HEARTBEAT_INTERVAL_MS);
-            };
-            this.heartbeatTimer = setTimeout(heartbeat, HEARTBEAT_INTERVAL_MS);
+            this.setupBridgeOnServer(server, port, bindHost);
         });
     }
     /**
@@ -428,7 +670,11 @@ export class PluginBridgeServer {
      * Otherwise routes to the most recently connected client.
      */
     async request(method, params, fileKey) {
-        const client = this.resolveClient(fileKey);
+        let client = this.resolveClient(fileKey);
+        // If no client found, wait briefly for plugin "ready" (race condition: plugin connected but fileKey not yet set)
+        if (!client || client.ws.readyState !== 1) {
+            client = await this.waitForClient(fileKey, 2000);
+        }
         if (!client || client.ws.readyState !== 1) {
             if (fileKey) {
                 const available = this.listConnectedFiles();