@muloka/figma-console-mcp 0.3.0 → 0.4.0

package/dist/cloudflare/core/figma-tools.js

@@ -951,21 +951,24 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
             .optional()
             .default(false)
             .describe("DEPRECATED — setting this to true now raises an explicit error. The Puppeteer-based console parser no longer exists. Open the Figma Console MCP Desktop Bridge plugin in Figma Desktop and call figma_get_variables() without parseFromConsole; the plugin returns full variable data through the WebSocket bridge."),
+        // NOTE: deliberately no .default() on either param. Every consumer below
+        // applies its own fallback (?? 1 / ?? 50), and leaving these undefined is
+        // what lets format='full' tell "caller asked for page 2" apart from
+        // "caller passed nothing" — without that distinction, honoring them would
+        // silently truncate every full response to 50 variables.
         page: z
             .number()
             .int()
             .min(1)
             .optional()
-            .default(1)
-            .describe("Page number for paginated results (1-based). Use when response is too large (>1MB). Each page returns up to 50 variables."),
+            .describe("Page number for paginated results (1-based). Use when the response is too large to handle in one call. Applies to format='filtered' and format='full'. Default: 1. IMPORTANT: a page number beyond the last page is CLAMPED to the last page, not rejected — it returns that page's data again with currentPage set to the real last page. Drive iteration off pagination.hasNextPage; a loop that just increments page will repeat the final page forever."),
         pageSize: z
             .number()
             .int()
             .min(1)
             .max(100)
             .optional()
-            .default(50)
-            .describe("Number of variables per page (1-100). Default: 50. Smaller values reduce response size."),
+            .describe("Number of variables per page. Hard limit 100 — higher values are rejected with a validation error, not clamped. Default: 50. Applies to format='filtered' and format='full'. For format='full', pagination is applied only when page or pageSize is explicitly passed; otherwise the complete dataset is returned. SOFT LIMIT: a page that exceeds ~25K estimated tokens is auto-summarized, so the page is discarded rather than returned — measured on a 689-variable file, pageSize=100 reached ~16K tokens at standard verbosity and ~20K with verbosity='full' plus resolveAliases. 100 is safe at roughly 200 tokens/variable; prefer 50 when resolving aliases on a mode-heavy file."),
         resolveAliases: z
             .boolean()
             .optional()
@@ -1199,6 +1202,22 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                 }
                 else {
                     // format === 'full'
+                    // Honor page/pageSize when the caller explicitly passed either one.
+                    // Previously they were accepted, silently ignored, and omitted from
+                    // the response, so a caller had no way to tell paging had not
+                    // happened (southleft/figma-console-mcp#98).
+                    //
+                    // This runs BEFORE the token estimate on purpose: slicing is exactly
+                    // how a caller retrieves a large dataset in pieces that fit under the
+                    // limit, so summarizing first would defeat the request.
+                    //
+                    // Both params are undefined unless passed (no zod .default()), so an
+                    // un-paginated full request still returns the complete dataset.
+                    if (page !== undefined || pageSize !== undefined) {
+                        const paginated = paginateVariables(responseData, page ?? 1, pageSize ?? 50);
+                        responseData = paginated.data;
+                        paginationInfo = paginated.pagination;
+                    }
                     // Check if we need to auto-summarize
                     const estimatedTokens = estimateTokens(responseData);
                     if (estimatedTokens > 25000) {
@@ -1435,19 +1454,30 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                             };
                         }
                     }
-                    // Apply pagination if requested
+                    // Apply pagination if requested.
+                    //
+                    // page/pageSize no longer carry zod .default() values (see the note on
+                    // the schema), so this branch restates the 1/50 it previously received
+                    // implicitly. That keeps the REST path's behavior byte-identical: it
+                    // has always paginated to 50 whether or not the caller asked. Reaching
+                    // this code requires a Figma Enterprise plan, so it cannot be exercised
+                    // from this fork — left deliberately unchanged rather than "fixed"
+                    // blind. The divergent field names here vs. paginateVariables() are
+                    // southleft/figma-console-mcp#99.
+                    const restPage = page ?? 1;
+                    const restPageSize = pageSize ?? 50;
                     let paginationInfo;
-                    if (pageSize) {
-                        const startIdx = (page - 1) * pageSize;
-                        const endIdx = startIdx + pageSize;
+                    if (restPageSize) {
+                        const startIdx = (restPage - 1) * restPageSize;
+                        const endIdx = startIdx + restPageSize;
                         const totalVars = localFormatted.variables.length;
                         paginationInfo = {
-                            page,
-                            pageSize,
+                            page: restPage,
+                            pageSize: restPageSize,
                             totalItems: totalVars,
-                            totalPages: Math.ceil(totalVars / pageSize),
+                            totalPages: Math.ceil(totalVars / restPageSize),
                             hasNextPage: endIdx < totalVars,
-                            hasPrevPage: page > 1,
+                            hasPrevPage: restPage > 1,
                         };
                         localFormatted.variables = localFormatted.variables.slice(startIdx, endIdx);
                         if (includePublished && publishedFormatted) {
@@ -1627,6 +1657,10 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                         }
                         // Apply format logic
                         let responseData = dataForCache;
+                        // Declared out here so the response builder below can see it —
+                        // it was previously scoped inside the 'filtered' branch, computed,
+                        // and then unreachable at return time.
+                        let paginationInfo = null;
                         if (format === 'summary') {
                             responseData = generateSummary(dataForCache);
                             logger.info({ fileKey, estimatedTokens: estimateTokens(responseData) }, 'Generated summary from fetched data');
@@ -1644,7 +1678,6 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                                 filteredCount: responseData.variables?.length,
                             }, 'Applied filters to fetched data');
                             // Apply pagination (CRITICAL - was missing!)
-                            let paginationInfo = null;
                             const paginated = paginateVariables(responseData, page || 1, pageSize || 50);
                             responseData = paginated.data;
                             paginationInfo = paginated.pagination;
@@ -1694,6 +1727,19 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                         }
                         else {
                             // format === 'full'
+                            // Same fix as the cached path above (southleft#98): honor
+                            // page/pageSize when explicitly passed, before the token
+                            // estimate, so slicing is what keeps a large dataset under the
+                            // limit rather than the summarizer discarding it.
+                            //
+                            // This branch serves cache-miss requests. It is a separate code
+                            // path from the cached one and needed the fix independently —
+                            // a live check against a warm cache exercises only the other.
+                            if (page !== undefined || pageSize !== undefined) {
+                                const paginated = paginateVariables(responseData, page ?? 1, pageSize ?? 50);
+                                responseData = paginated.data;
+                                paginationInfo = paginated.pagination;
+                            }
                             // Check if we need to auto-summarize
                             const estimatedTokens = estimateTokens(responseData);
                             if (estimatedTokens > 25000) {
@@ -1773,6 +1819,11 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                                         timestamp: dataForCache.timestamp,
                                         data: responseData,
                                         cached: false,
+                                        // paginationInfo was computed above and then dropped on the
+                                        // floor, so a cache-miss request through the Desktop Bridge
+                                        // received sliced data with no indication more pages existed
+                                        // — silent truncation. Same shape the cache path returns.
+                                        ...(paginationInfo && { pagination: paginationInfo }),
                                     }),
                                 },
                             ],

package/dist/cloudflare/core/tokens-tools.js

@@ -35,7 +35,7 @@ const logger = createChildLogger({ component: "tokens-tools" });
  * on every exported token document. Kept in sync with package.json by
  * scripts/release.sh — see step 3 of the release flow.
  */
-const MCP_VERSION = "1.35.0";
+const MCP_VERSION = "1.36.0";
 const EXPORT_TOOL_DESCRIPTION = `Export Figma variables to design token files in your codebase. Bidirectional with figma_import_tokens — together they replace Style Dictionary and Tokens Studio's export pipeline for the popular styling methods.
 
 FULLY-IMPLEMENTED OUTPUT FORMATS:

package/dist/cloudflare/core/websocket-server.js

@@ -75,6 +75,14 @@ export class FigmaWebSocketServer extends EventEmitter {
         this._pendingClients = new Map();
         /** The fileKey of the currently active (targeted) file */
         this._activeFileKey = null;
+        /**
+         * When true, the active file is pinned: new connections, reconnects, and
+         * user interaction (selection/page changes) will NOT move the active target.
+         * Lets the agent work in one file while the user works in another without
+         * commands silently routing to the wrong file. Cleared if the locked file
+         * disconnects.
+         */
+        this._targetLocked = false;
         this.pendingRequests = new Map();
         this.requestIdCounter = 0;
         this._isStarted = false;
@@ -376,7 +384,8 @@ export class FigmaWebSocketServer extends EventEmitter {
                 if (found) {
                     found.client.selection = message.data;
                     found.client.lastActivity = Date.now();
-                    this._activeFileKey = found.fileKey;
+                    if (!this._targetLocked)
+                        this._activeFileKey = found.fileKey;
                 }
                 this.emit('selectionChange', { fileKey: found?.fileKey ?? null, ...message.data });
             }
@@ -387,7 +396,8 @@ export class FigmaWebSocketServer extends EventEmitter {
                     found.client.fileInfo.currentPage = message.data.pageName;
                     found.client.fileInfo.currentPageId = message.data.pageId || null;
                     found.client.lastActivity = Date.now();
-                    this._activeFileKey = found.fileKey;
+                    if (!this._targetLocked)
+                        this._activeFileKey = found.fileKey;
                 }
                 this.emit('pageChange', { fileKey: found?.fileKey ?? null, ...message.data });
             }
@@ -440,6 +450,9 @@ export class FigmaWebSocketServer extends EventEmitter {
             this.clients.delete(previousEntry.fileKey);
             if (this._activeFileKey === previousEntry.fileKey) {
                 this._activeFileKey = null;
+                // The pinned plugin navigated to a different file — the old pin is
+                // meaningless, so release it rather than silently re-pinning the new file.
+                this._targetLocked = false;
             }
             // In-flight commands to the old file can never receive a response now —
             // reject them immediately instead of leaving them to hang until timeout
@@ -514,7 +527,14 @@ export class FigmaWebSocketServer extends EventEmitter {
         // Most recently connected file becomes active (user just opened the plugin there).
         // On bulk reconnect the order is non-deterministic, but the first user interaction
         // (SELECTION_CHANGE or PAGE_CHANGE) will correct the active file immediately.
-        this._activeFileKey = fileKey;
+        // Skip when the target is pinned so a new or reconnecting plugin can't steal it.
+        // Invariant: a locked target always has an active file — every path that nulls
+        // _activeFileKey also releases the lock — so there is no "locked but nothing
+        // active" case to re-adopt here, and a crash-reconnect within the grace window
+        // keeps its active key (the grace timer is cleared before it can fire).
+        if (!this._targetLocked) {
+            this._activeFileKey = fileKey;
+        }
         logger.info({
             fileName: data.fileName,
             fileKey,
@@ -556,9 +576,15 @@ export class FigmaWebSocketServer extends EventEmitter {
             if (current && current.ws === ws) {
                 this.clients.delete(fileKey);
                 this.rejectPendingRequestsForFile(fileKey, 'WebSocket client disconnected');
-                // If active file disconnected, switch to another connected file
+                // If active file disconnected, switch to another connected file.
+                // Release any lock — the pinned file is gone, so honoring the lock
+                // would strand every command against a dead connection.
                 if (this._activeFileKey === fileKey) {
                     this._activeFileKey = null;
+                    if (this._targetLocked) {
+                        this._targetLocked = false;
+                        logger.info({ fileKey }, 'Target lock released — locked file disconnected');
+                    }
                     for (const [fk, c] of this.clients) {
                         if (c.ws.readyState === WebSocket.OPEN) {
                             this._activeFileKey = fk;
@@ -855,13 +881,19 @@ export class FigmaWebSocketServer extends EventEmitter {
     }
     /**
      * Set the active file by fileKey. Returns true if the file is connected.
+     *
+     * Pass `lock: true` to pin the target so subsequent connections, reconnects,
+     * and user interaction won't move it. Any explicit switch resets the lock to
+     * the value passed here (default: unlocked), so switching without `lock`
+     * releases a prior lock.
      */
-    setActiveFile(fileKey) {
+    setActiveFile(fileKey, lock = false) {
         const client = this.clients.get(fileKey);
         if (client && client.ws.readyState === WebSocket.OPEN) {
             this._activeFileKey = fileKey;
-            logger.info({ fileKey, fileName: client.fileInfo.fileName }, 'Active file switched');
-            this.emit('activeFileChanged', { fileKey, fileName: client.fileInfo.fileName });
+            this._targetLocked = lock;
+            logger.info({ fileKey, fileName: client.fileInfo.fileName, locked: lock }, 'Active file switched');
+            this.emit('activeFileChanged', { fileKey, fileName: client.fileInfo.fileName, locked: lock });
             return true;
         }
         return false;
@@ -872,6 +904,26 @@ export class FigmaWebSocketServer extends EventEmitter {
     getActiveFileKey() {
         return this._activeFileKey;
     }
+    /**
+     * Pin the current active file so connections, reconnects, and user
+     * interaction won't move the target. Returns false if no file is active.
+     */
+    lockTarget() {
+        if (!this._activeFileKey)
+            return false;
+        this._targetLocked = true;
+        logger.info({ fileKey: this._activeFileKey }, 'Target locked');
+        return true;
+    }
+    /** Release the target lock; the active file resumes following user activity. */
+    unlockTarget() {
+        this._targetLocked = false;
+        logger.info({ fileKey: this._activeFileKey }, 'Target unlocked');
+    }
+    /** Whether the active file is currently pinned. */
+    isTargetLocked() {
+        return this._targetLocked;
+    }
     /**
      * Get the editor type of the currently active file.
      * Returns 'figma' if no file is connected or editorType wasn't reported.
@@ -937,6 +989,7 @@ export class FigmaWebSocketServer extends EventEmitter {
         }
         this.clients.clear();
         this._activeFileKey = null;
+        this._targetLocked = false;
         // Close WS server first (handles WebSocket connections)
         if (this.wss) {
             await new Promise((resolve) => {

package/dist/cloudflare/index.js

@@ -75,7 +75,7 @@ export class FigmaConsoleMCPv3 extends McpAgent {
         this.server = (() => {
             const s = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.35.0",
+                version: "1.36.0",
             });
             // Identity wrap — every tool's response and thrown error gets stamped
             // with our MCP name so cross-MCP attribution is unambiguous.
@@ -1085,7 +1085,7 @@ export default {
             });
             const statelessServer = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.35.0",
+                version: "1.36.0",
             });
             wrapServerForIdentity(statelessServer);
             // ================================================================
@@ -1723,7 +1723,7 @@ export default {
             return new Response(JSON.stringify({
                 status: "healthy",
                 service: "Figma Console MCP",
-                version: "1.35.0",
+                version: "1.36.0",
                 endpoints: {
                     mcp: ["/sse", "/mcp"],
                     oauth_mcp_spec: ["/.well-known/oauth-authorization-server", "/authorize", "/token", "/oauth/register"],

package/dist/core/port-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port-discovery.d.ts","sourceRoot":"","sources":["../../src/core/port-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAaH,uCAAuC;AACvC,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,mEAAmE;AACnE,eAAO,MAAM,eAAe,KAAK,CAAC;AAQlC,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,QAAqB,CAAC;AAEvD,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAE3C,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,QAAgB,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,QAAgB,CAAC;AAEjD,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,QAAY,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,aAAa,GAAE,MAAwB,GAAG,MAAM,EAAE,CAM9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAoB,GAAG,IAAI,CAiB5E;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAa3D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAUlD;AAcD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAY3D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,QAA4B,CAAC;AA6NtE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAoB9D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,GAAE,MAAwB,GAAG,YAAY,EAAE,CAW/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAyD9C;AAED;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CAyDlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,GAAE,MAAwB,EACvC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,MAAM,CAiFR;AAiDD;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,aAAa,GAAE,MAAwB,EACvC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,CAAC,CA4DjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,GAAE,MAAwB,GAAG,OAAO,CA0EpF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAStD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,GAAE,MAAwB,GAAG,MAAM,IAAI,CAgCvF"}
+{"version":3,"file":"port-discovery.d.ts","sourceRoot":"","sources":["../../src/core/port-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAaH,uCAAuC;AACvC,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,mEAAmE;AACnE,eAAO,MAAM,eAAe,KAAK,CAAC;AAQlC,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,QAAqB,CAAC;AAEvD,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAE3C,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,QAAgB,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,QAAgB,CAAC;AAEjD,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,QAAY,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,aAAa,GAAE,MAAwB,GAAG,MAAM,EAAE,CAM9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAoB,GAAG,IAAI,CAkB5E;AA0BD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAsB3D;AAaD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAalD;AAcD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAY3D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,QAA4B,CAAC;AAwOtE;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAoB9D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,GAAE,MAAwB,GAAG,YAAY,EAAE,CAW/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CA+D9C;AAED;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CA+DlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,GAAE,MAAwB,EACvC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,MAAM,CA4FR;AAiDD;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,aAAa,GAAE,MAAwB,EACvC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,CAAC,CA0EjB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,GAAE,MAAwB,GAAG,OAAO,CA0EpF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAStD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,GAAE,MAAwB,GAAG,MAAM,IAAI,CAgCvF"}

package/dist/core/port-discovery.js

@@ -29,7 +29,7 @@
  *   Plugin scans ports 9223-9232 → connects to first responding server
  *   External tools read port files for discovery
  */
-import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync } from 'fs';
+import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync, renameSync } from 'fs';
 import { join } from 'path';
 import { tmpdir, devNull } from 'os';
 import { execFile, execFileSync } from 'child_process';
@@ -101,13 +101,41 @@ export function advertisePort(port, host = 'localhost') {
     };
     const filePath = getPortFilePath(port);
     try {
-        writeFileSync(filePath, JSON.stringify(data, null, 2));
+        writePortFileAtomic(filePath, data);
+        advertisedPorts.add(port);
         logger.info({ port, filePath }, 'Port advertised');
     }
     catch (error) {
         logger.warn({ port, filePath, error }, 'Failed to write port advertisement file');
     }
 }
+/**
+ * Write a port file atomically: full write to a PID-unique temp file, then
+ * `renameSync` onto the target. `rename(2)` is atomic on POSIX, so a reader
+ * only ever sees the complete old file or the complete new one.
+ *
+ * A plain `writeFileSync` truncates first, leaving a window where readers see
+ * an empty or partial file. That window is re-opened every 30s per instance
+ * by the heartbeat, while every sibling scans all ten files — and a reader
+ * that hits it gets a JSON parse error, which the cleanup paths used to treat
+ * as "corrupt, delete it" and the orphan reaper treats as "no port file =
+ * orphan, kill it". A transient read blip must never be able to strand or
+ * kill a healthy server.
+ */
+function writePortFileAtomic(filePath, data) {
+    const tmpPath = `${filePath}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+        renameSync(tmpPath, filePath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch { /* best-effort */ }
+        throw error;
+    }
+}
 /**
  * Refresh the lastSeen timestamp in a port advertisement file.
  * Called periodically as a heartbeat to prove this server is still active.
@@ -116,26 +144,47 @@ export function advertisePort(port, host = 'localhost') {
 export function refreshPortAdvertisement(port) {
     const filePath = getPortFilePath(port);
     try {
-        if (!existsSync(filePath))
+        if (!existsSync(filePath)) {
+            // Our file is gone but we are still running and still hold the port.
+            // Returning here (the old behaviour) left the process permanently
+            // unadvertised — and an unadvertised process holding a port is exactly
+            // what the orphan reaper terminates. Re-advertise instead so the state
+            // is self-healing rather than terminal. Guarded by ownsPort so we never
+            // resurrect a file for a port that has since been taken by someone else.
+            if (ownsPort(port))
+                advertisePort(port);
             return;
+        }
         const raw = readFileSync(filePath, 'utf-8');
         const data = JSON.parse(raw);
         // Only refresh our own port file
         if (data.pid !== process.pid)
             return;
         data.lastSeen = new Date().toISOString();
-        writeFileSync(filePath, JSON.stringify(data, null, 2));
+        writePortFileAtomic(filePath, data);
     }
     catch {
         // Best-effort — heartbeat failures are non-fatal
     }
 }
+/**
+ * Whether THIS process is the one that advertised `port` in this run.
+ * Tracked in-process rather than re-derived from the filesystem, because the
+ * filesystem is precisely the state we may be repairing.
+ */
+const advertisedPorts = new Set();
+function ownsPort(port) {
+    return advertisedPorts.has(port);
+}
 /**
  * Remove the port advertisement file for this instance.
  * Call on clean shutdown.
  */
 export function unadvertisePort(port) {
     const filePath = getPortFilePath(port);
+    // Drop ownership first so a heartbeat racing this shutdown can't re-advertise
+    // the file we are deliberately removing.
+    advertisedPorts.delete(port);
     try {
         if (existsSync(filePath)) {
             unlinkSync(filePath);
@@ -208,9 +257,20 @@ function isValidProbePort(port) {
 /** curl arguments for the /health liveness probe against a sibling's port.
  * `devNull` (not a literal /dev/null) — Windows ships curl.exe, and a bad
  * output path there makes curl exit non-zero, which reads as "nothing
- * responding" and would let the reaper kill a healthy sibling. */
+ * responding" and would let the reaper kill a healthy sibling.
+ *
+ * The host MUST be `localhost`, not `127.0.0.1`. The WebSocket server binds
+ * `options.host || 'localhost'`, and on a dual-stack macOS box Node resolves
+ * that to the IPv6 loopback — `lsof` shows `[::1]:9223`, with nothing
+ * listening on IPv4. Probing `127.0.0.1` therefore returned connection-refused
+ * for every *healthy* server, which `probeServerHealth` maps to `false` =
+ * "confirmed dead". That inverted every kill-safety gate below: the probe that
+ * exists to spare live-but-stale siblings was instead rubber-stamping their
+ * termination. Verified live: on a working server, `127.0.0.1` gave curl exit
+ * 7 while `localhost` gave exit 0. `localhost` lets curl try every resolved
+ * address (both families), so it works regardless of which stack Node picked. */
 function healthProbeArgs(port) {
-    return ['-s', '-o', devNull, '-m', '1', `http://127.0.0.1:${port}/health`];
+    return ['-s', '-o', devNull, '-m', '1', `http://localhost:${port}/health`];
 }
 /**
  * Liveness probe against a sibling server's HTTP `/health` endpoint (the
@@ -507,12 +567,14 @@ export function cleanupStalePortFiles() {
                     }
                 }
                 catch {
-                    // Corrupt file — remove it
-                    try {
-                        unlinkSync(filePath);
-                        cleaned++;
-                    }
-                    catch { /* ignore */ }
+                    // Unreadable/unparseable — do NOT delete. A partial read of a file
+                    // mid-rewrite is indistinguishable from genuine corruption, and
+                    // deleting it strands a healthy server: it becomes a port-holder
+                    // with no port file, which the orphan reaper terminates on sight.
+                    // Writes are atomic now (writePortFileAtomic), so this should be
+                    // unreachable in practice; leaving the file alone means the worst
+                    // case is a stale file that the dead-PID branch reclaims later.
+                    logger.debug({ filePath }, 'Unreadable port file — leaving in place');
                 }
             }
         }
@@ -574,12 +636,14 @@ export async function cleanupStalePortFilesAsync() {
                     }
                 }
                 catch {
-                    // Corrupt file — remove it
-                    try {
-                        unlinkSync(filePath);
-                        cleaned++;
-                    }
-                    catch { /* ignore */ }
+                    // Unreadable/unparseable — do NOT delete. A partial read of a file
+                    // mid-rewrite is indistinguishable from genuine corruption, and
+                    // deleting it strands a healthy server: it becomes a port-holder
+                    // with no port file, which the orphan reaper terminates on sight.
+                    // Writes are atomic now (writePortFileAtomic), so this should be
+                    // unreachable in practice; leaving the file alone means the worst
+                    // case is a stale file that the dead-PID branch reclaims later.
+                    logger.debug({ filePath }, 'Unreadable port file — leaving in place');
                 }
             }
         }
@@ -642,7 +706,14 @@ export function cleanupOrphanedProcesses(preferredPort = DEFAULT_WS_PORT, option
                         if (minAgeMs > 0 && ageMs !== null && ageMs < minAgeMs) {
                             continue;
                         }
-                        logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port)');
+                        // See the async path: a missing port file is not proof of death.
+                        // Only a definitive probe failure authorises termination.
+                        const health = probeServerHealth(port);
+                        if (health !== false) {
+                            logger.debug({ port, pid, probe: health === true ? 'responding' : 'inconclusive' }, 'Port-holder without a port file is still serving /health — skipping kill');
+                            continue;
+                        }
+                        logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port, health probe failed)');
                         // terminateProcess escalates SIGTERM -> SIGKILL. Only count it as
                         // cleaned when the process is confirmed gone, so the log reflects
                         // reality (the old code counted attempts and reported success even
@@ -758,7 +829,17 @@ export async function cleanupOrphanedProcessesAsync(preferredPort = DEFAULT_WS_P
                 if (minAgeMs > 0 && ageMs !== null && ageMs < minAgeMs) {
                     continue;
                 }
-                logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port)');
+                // A missing port file is not proof of death — it can also mean a
+                // transient read failure, or a file removed out from under a healthy
+                // server. Ask the server itself before killing it. Same verdict
+                // semantics as the stale-file path: only a definitive `false`
+                // (probe ran, nothing answered) authorises termination.
+                const health = await probeServerHealthAsync(port);
+                if (health !== false) {
+                    logger.debug({ port, pid, probe: health === true ? 'responding' : 'inconclusive' }, 'Port-holder without a port file is still serving /health — re-advertising is its job, not ours; skipping kill');
+                    continue;
+                }
+                logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port, health probe failed)');
                 // Only count confirmed kills, matching the sync path.
                 if (await terminateProcessAsync(pid)) {
                     cleaned++;