lensmcp 1.17.4 → 1.18.1

package/bundled/dashboard.js

@@ -17435,9 +17435,14 @@ var MAX_ERRORS = 50;
 var STATE_BY_KIND = {
   "service-starting": "starting",
   "service-respawn": "starting",
+  // A lens frontend's vite has been SPAWNED — started, not yet proven to serve.
+  // The gateway's liveness probe emits `service-up` once its port accepts, so
+  // this must claim `starting` and never `up`.
+  "lens-app-up": "starting",
   "service-up": "up",
   "cold-start": "up",
   "service-down": "down",
+  "idle-kill": "idle",
   "service-recycle": "wedged",
   "pod-recycle": "wedged",
   "service-crash-loop": "crash-looping"
@@ -17494,6 +17499,7 @@ var ClusterHealth = class {
       down: byState("down"),
       wedged: byState("wedged"),
       crashLooping: byState("crash-looping"),
+      idle: byState("idle"),
       buildFailed: services.filter((s) => s.buildFailed).map((s) => s.project),
       restarts: services.reduce((n, s) => n + s.restarts, 0),
       errors: this.errors.slice()

package/bundled/main.js

@@ -17437,9 +17437,14 @@ var MAX_ERRORS = 50;
 var STATE_BY_KIND = {
   "service-starting": "starting",
   "service-respawn": "starting",
+  // A lens frontend's vite has been SPAWNED — started, not yet proven to serve.
+  // The gateway's liveness probe emits `service-up` once its port accepts, so
+  // this must claim `starting` and never `up`.
+  "lens-app-up": "starting",
   "service-up": "up",
   "cold-start": "up",
   "service-down": "down",
+  "idle-kill": "idle",
   "service-recycle": "wedged",
   "pod-recycle": "wedged",
   "service-crash-loop": "crash-looping"
@@ -17496,6 +17501,7 @@ var ClusterHealth = class {
       down: byState("down"),
       wedged: byState("wedged"),
       crashLooping: byState("crash-looping"),
+      idle: byState("idle"),
       buildFailed: services.filter((s) => s.buildFailed).map((s) => s.project),
       restarts: services.reduce((n, s) => n + s.restarts, 0),
       errors: this.errors.slice()
@@ -21901,6 +21907,92 @@ function watchParentGateway(label) {
   timer.unref();
 }
 
+// servers/lensmcp-mcp/dist/shim/workspace.js
+import { existsSync as existsSync7, readFileSync as readFileSync5, realpathSync } from "node:fs";
+import { basename, dirname as dirname5, join as join5 } from "node:path";
+var BASE_PORTS = { dashboard: 4321, mcpHttp: 4500, bridge: 5747 };
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync5(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function hashToRange(s, range) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return Math.abs(h | 0) % range;
+}
+function slugify2(input) {
+  return input.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "workspace";
+}
+function resolveWorkspaceKey(root) {
+  const nx = readJson(join5(root, "nx.json"));
+  if (nx?.lensmcp?.key)
+    return slugify2(nx.lensmcp.key);
+  const pkg = readJson(join5(root, "package.json"));
+  if (pkg?.name)
+    return slugify2(pkg.name);
+  if (nx?.name)
+    return slugify2(nx.name);
+  return slugify2(basename(root));
+}
+function deriveMcpHttpPort(key) {
+  return BASE_PORTS.mcpHttp + hashToRange(key, 200);
+}
+function findWorkspaceRoot(start) {
+  let nxFallback;
+  let dir = start;
+  for (; ; ) {
+    if (existsSync7(join5(dir, ".lensmcp", "config.json")))
+      return dir;
+    if (nxFallback === void 0 && existsSync7(join5(dir, "nx.json")))
+      nxFallback = dir;
+    const parent = dirname5(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return nxFallback ?? start;
+}
+function resolveWorkspaceScope(start, env = process.env) {
+  const root = findWorkspaceRoot(start);
+  const file2 = readJson(join5(root, ".lensmcp", "config.json"));
+  const key = file2?.key ? slugify2(file2.key) : resolveWorkspaceKey(root);
+  const mcpHttpPort = typeof file2?.ports?.mcpHttp === "number" ? file2.ports.mcpHttp : deriveMcpHttpPort(key);
+  return {
+    root,
+    key,
+    mcpHttpPort,
+    eventFile: env["LENSMCP_EVENT_FILE"] ?? join5(root, ".lensmcp", "events.jsonl")
+  };
+}
+var IDENTITY_PATH = "/lensmcp/identity";
+var IDENTITY_KIND = "lensmcp-mcp-identity";
+function canonicalRoot(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+function resolveServerIdentity(env = process.env, cwd = process.cwd()) {
+  const scope = resolveWorkspaceScope(cwd, env);
+  const root = canonicalRoot(env["LENSMCP_WORKSPACE_ROOT"] ?? scope.root);
+  const key = env["LENSMCP_WORKSPACE_KEY"] ? slugify2(env["LENSMCP_WORKSPACE_KEY"]) : env["LENSMCP_WORKSPACE_ROOT"] ? resolveWorkspaceScope(root, env).key : scope.key;
+  return {
+    kind: IDENTITY_KIND,
+    key,
+    root,
+    eventFile: scope.eventFile,
+    pid: process.pid,
+    port: env["LENSMCP_PORT"] ? Number(env["LENSMCP_PORT"]) : void 0
+  };
+}
+
 // servers/lensmcp-mcp/dist/main.js
 watchParentGateway("mcp");
 var { session, providers } = createLensSession();
@@ -21950,7 +22042,25 @@ if (transport === "stdio") {
   });
 } else {
   const entryPath = process.env["LENSMCP_HTTP_PATH"] ?? "/mcp";
-  const http = transport === "socket" ? { socketPath: process.env["LENSMCP_SOCKET_PATH"] ?? "/tmp/lensmcp-mcp.sock", entryPath } : { port: Number(process.env["LENSMCP_PORT"] ?? 3e3), entryPath };
+  const identity = resolveServerIdentity();
+  const identityRoute = {
+    method: "GET",
+    path: IDENTITY_PATH,
+    handler: (_req, res) => {
+      res.setHeader("content-type", "application/json");
+      res.setHeader("cache-control", "no-store");
+      res.end(JSON.stringify(identity));
+    }
+  };
+  const http = transport === "socket" ? {
+    socketPath: process.env["LENSMCP_SOCKET_PATH"] ?? "/tmp/lensmcp-mcp.sock",
+    entryPath,
+    routes: [identityRoute]
+  } : {
+    port: Number(process.env["LENSMCP_PORT"] ?? 3e3),
+    entryPath,
+    routes: [identityRoute]
+  };
   void FrontMcpInstance.bootstrap({
     ...serverConfig,
     logging: { level: LogLevel.Info },

package/bundled/shim.js

@@ -8485,8 +8485,17 @@ async function ensureSharedServer(deps) {
   const poll = deps.pollMs ?? READY_POLL_MS;
   const ttl = deps.lockTtlMs ?? SPAWN_LOCK_TTL_MS;
   const elapsed = () => deps.now() - started;
+  const live = (outcome) => {
+    const foreign = deps.verifyIdentity?.();
+    if (foreign)
+      return { outcome: "unavailable", reason: foreign, waitedMs: elapsed() };
+    return { outcome, waitedMs: elapsed() };
+  };
   if (await deps.probe())
-    return { outcome: "already-running", waitedMs: elapsed() };
+    return live("already-running");
+  const taken = await deps.foreignPortOwner?.();
+  if (taken)
+    return { outcome: "unavailable", reason: taken, waitedMs: elapsed() };
   let holdsLock = deps.tryCreateLock(JSON.stringify({ pid: process.pid, at: deps.now() }));
   if (!holdsLock) {
     const existing = parseSpawnLock(deps.readLock());
@@ -8507,7 +8516,7 @@ async function ensureSharedServer(deps) {
       while (elapsed() < timeout) {
         await deps.sleep(poll);
         if (await deps.probe())
-          return { outcome: "started", waitedMs: elapsed() };
+          return live("started");
         if (deps.serverExited?.()) {
           return {
             outcome: "unavailable",
@@ -8528,7 +8537,7 @@ async function ensureSharedServer(deps) {
   while (elapsed() < timeout) {
     await deps.sleep(poll);
     if (await deps.probe())
-      return { outcome: "waited", waitedMs: elapsed() };
+      return live("waited");
     const lock = parseSpawnLock(deps.readLock());
     if (!isSpawnLockHeld(lock, deps.now(), deps.isAlive, ttl) && !await deps.probe()) {
       return {
@@ -8590,7 +8599,9 @@ function startSharedServerWatched(opts) {
       LENSMCP_TRANSPORT: "http",
       LENSMCP_PORT: String(opts.port),
       LENSMCP_EVENT_FILE: opts.eventFile,
-      LENSMCP_SHARED_OWNER: "shim"
+      LENSMCP_SHARED_OWNER: "shim",
+      ...opts.workspaceKey ? { LENSMCP_WORKSPACE_KEY: opts.workspaceKey } : {},
+      ...opts.workspaceRoot ? { LENSMCP_WORKSPACE_ROOT: opts.workspaceRoot } : {}
     };
     delete env["LENSMCP_PARENT_PID"];
     const child = spawn(process.execPath, [opts.serverEntry], {
@@ -8616,6 +8627,191 @@ function startSharedServerWatched(opts) {
   }
 }
 
+// servers/lensmcp-mcp/dist/shim/probe.js
+import { connect } from "node:net";
+
+// servers/lensmcp-mcp/dist/shim/workspace.js
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { basename, dirname, join as join2 } from "node:path";
+var BASE_PORTS = { dashboard: 4321, mcpHttp: 4500, bridge: 5747 };
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync2(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+function hashToRange(s, range) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return Math.abs(h | 0) % range;
+}
+function slugify2(input) {
+  return input.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "workspace";
+}
+function resolveWorkspaceKey(root) {
+  const nx = readJson(join2(root, "nx.json"));
+  if (nx?.lensmcp?.key)
+    return slugify2(nx.lensmcp.key);
+  const pkg = readJson(join2(root, "package.json"));
+  if (pkg?.name)
+    return slugify2(pkg.name);
+  if (nx?.name)
+    return slugify2(nx.name);
+  return slugify2(basename(root));
+}
+function deriveMcpHttpPort(key) {
+  return BASE_PORTS.mcpHttp + hashToRange(key, 200);
+}
+function findWorkspaceRoot(start) {
+  let nxFallback;
+  let dir = start;
+  for (; ; ) {
+    if (existsSync2(join2(dir, ".lensmcp", "config.json")))
+      return dir;
+    if (nxFallback === void 0 && existsSync2(join2(dir, "nx.json")))
+      nxFallback = dir;
+    const parent = dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return nxFallback ?? start;
+}
+function resolveWorkspaceScope(start, env = process.env) {
+  const root = findWorkspaceRoot(start);
+  const file = readJson(join2(root, ".lensmcp", "config.json"));
+  const key = file?.key ? slugify2(file.key) : resolveWorkspaceKey(root);
+  const mcpHttpPort = typeof file?.ports?.mcpHttp === "number" ? file.ports.mcpHttp : deriveMcpHttpPort(key);
+  return {
+    root,
+    key,
+    mcpHttpPort,
+    eventFile: env["LENSMCP_EVENT_FILE"] ?? join2(root, ".lensmcp", "events.jsonl")
+  };
+}
+function sharedMcpUrl(port) {
+  return `http://127.0.0.1:${port}/mcp`;
+}
+var IDENTITY_PATH = "/lensmcp/identity";
+var IDENTITY_KIND = "lensmcp-mcp-identity";
+function identityUrl(port) {
+  return `http://127.0.0.1:${port}${IDENTITY_PATH}`;
+}
+function canonicalRoot(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+function parseServerIdentity(value) {
+  if (!value || typeof value !== "object")
+    return void 0;
+  const o = value;
+  if (o["kind"] !== IDENTITY_KIND)
+    return void 0;
+  if (typeof o["key"] !== "string" || typeof o["root"] !== "string")
+    return void 0;
+  return {
+    kind: IDENTITY_KIND,
+    key: o["key"],
+    root: o["root"],
+    ...typeof o["eventFile"] === "string" ? { eventFile: o["eventFile"] } : {},
+    ...typeof o["pid"] === "number" ? { pid: o["pid"] } : {},
+    ...typeof o["port"] === "number" ? { port: o["port"] } : {}
+  };
+}
+function describeIdentityMismatch(expected, actual) {
+  if (!actual)
+    return void 0;
+  if (actual.key !== expected.key) {
+    return `it serves workspace "${actual.key}", not "${expected.key}"`;
+  }
+  const ours = canonicalRoot(expected.root);
+  const theirs = canonicalRoot(actual.root);
+  if (ours !== theirs) {
+    return `it serves another checkout of "${actual.key}" (${theirs}), not ${ours}`;
+  }
+  return void 0;
+}
+
+// servers/lensmcp-mcp/dist/shim/probe.js
+async function probeMcp(url2, timeoutMs) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url2, {
+      method: "POST",
+      signal: ctrl.signal,
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream"
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2025-06-18",
+          capabilities: {},
+          clientInfo: { name: "lensmcp-shim-probe", version: "1" }
+        }
+      })
+    });
+    if (!res.ok)
+      return false;
+    const text = await res.text();
+    return text.includes('"result"');
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function probeShared(port, timeoutMs = 2e3) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  let answered = false;
+  try {
+    const res = await fetch(identityUrl(port), {
+      signal: ctrl.signal,
+      headers: { accept: "application/json" }
+    });
+    answered = true;
+    if (res.ok) {
+      const identity = parseServerIdentity(await res.json().catch(() => void 0));
+      if (identity)
+        return { alive: true, identity, owner: "lensmcp" };
+    } else {
+      await res.text().catch(() => void 0);
+    }
+  } catch {
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!answered)
+    return { alive: false, owner: "none" };
+  const legacy = await probeMcp(sharedMcpUrl(port), timeoutMs);
+  return { alive: legacy, owner: legacy ? "lensmcp" : "foreign" };
+}
+function tcpAccepts(port, timeoutMs = 750) {
+  return new Promise((resolve2) => {
+    const socket = connect({ port, host: "127.0.0.1" });
+    const settle = (accepted) => {
+      socket.destroy();
+      resolve2(accepted);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => settle(true));
+    socket.once("timeout", () => settle(false));
+    socket.once("error", () => settle(false));
+  });
+}
+
 // servers/lensmcp-mcp/dist/shim/proxy.js
 function isRequest(m) {
   return typeof m.method === "string" && m.id !== void 0;
@@ -8769,73 +8965,6 @@ function startProxy(opts) {
   };
 }
 
-// servers/lensmcp-mcp/dist/shim/workspace.js
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { basename, dirname, join as join2 } from "node:path";
-var BASE_PORTS = { dashboard: 4321, mcpHttp: 4500, bridge: 5747 };
-function readJson(path) {
-  try {
-    return JSON.parse(readFileSync2(path, "utf8"));
-  } catch {
-    return void 0;
-  }
-}
-function hashToRange(s, range) {
-  let h = 2166136261;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 16777619);
-  }
-  return Math.abs(h | 0) % range;
-}
-function slugify2(input) {
-  return input.toLowerCase().replace(/^@[^/]+\//, "").replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "workspace";
-}
-function resolveWorkspaceKey(root) {
-  const nx = readJson(join2(root, "nx.json"));
-  if (nx?.lensmcp?.key)
-    return slugify2(nx.lensmcp.key);
-  const pkg = readJson(join2(root, "package.json"));
-  if (pkg?.name)
-    return slugify2(pkg.name);
-  if (nx?.name)
-    return slugify2(nx.name);
-  return slugify2(basename(root));
-}
-function deriveMcpHttpPort(key) {
-  return BASE_PORTS.mcpHttp + hashToRange(key, 200);
-}
-function findWorkspaceRoot(start) {
-  let nxFallback;
-  let dir = start;
-  for (; ; ) {
-    if (existsSync2(join2(dir, ".lensmcp", "config.json")))
-      return dir;
-    if (nxFallback === void 0 && existsSync2(join2(dir, "nx.json")))
-      nxFallback = dir;
-    const parent = dirname(dir);
-    if (parent === dir)
-      break;
-    dir = parent;
-  }
-  return nxFallback ?? start;
-}
-function resolveWorkspaceScope(start, env = process.env) {
-  const root = findWorkspaceRoot(start);
-  const file = readJson(join2(root, ".lensmcp", "config.json"));
-  const key = file?.key ? slugify2(file.key) : resolveWorkspaceKey(root);
-  const mcpHttpPort = typeof file?.ports?.mcpHttp === "number" ? file.ports.mcpHttp : deriveMcpHttpPort(key);
-  return {
-    root,
-    key,
-    mcpHttpPort,
-    eventFile: env["LENSMCP_EVENT_FILE"] ?? join2(root, ".lensmcp", "events.jsonl")
-  };
-}
-function sharedMcpUrl(port) {
-  return `http://127.0.0.1:${port}/mcp`;
-}
-
 // servers/lensmcp-mcp/dist/shim.js
 function log(line) {
   process.stderr.write(`${line}
@@ -8848,43 +8977,12 @@ function argValue(flag) {
 function serverEntry() {
   return join3(dirname2(fileURLToPath(import.meta.url)), "main.js");
 }
-async function probe(url2, timeoutMs = 2e3) {
-  const ctrl = new AbortController();
-  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-  try {
-    const res = await fetch(url2, {
-      method: "POST",
-      signal: ctrl.signal,
-      headers: {
-        "content-type": "application/json",
-        accept: "application/json, text/event-stream"
-      },
-      body: JSON.stringify({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "initialize",
-        params: {
-          protocolVersion: "2025-06-18",
-          capabilities: {},
-          clientInfo: { name: "lensmcp-shim-probe", version: "1" }
-        }
-      })
-    });
-    if (!res.ok)
-      return false;
-    const text = await res.text();
-    return text.includes('"result"');
-  } catch {
-    return false;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-function runEmbedded(cwd, why) {
+function runEmbedded(cwd, why, advise = true) {
   log(`[lensmcp] shared MCP server unavailable (${why}) \u2014 falling back to an embedded server.`);
   log("[lensmcp] the lens works for this session, but it is pinned to the bundle it");
   log("[lensmcp] starts with and will not pick up an upgrade until the session ends.");
-  log("[lensmcp] to get the shared server: `lensmcp gateway start`");
+  if (advise)
+    log("[lensmcp] to get the shared server: `lensmcp gateway start`");
   const env = { ...process.env };
   delete env["LENSMCP_MCP_MODE"];
   env["LENSMCP_TRANSPORT"] = "stdio";
@@ -8898,16 +8996,70 @@ async function main() {
   const scope = resolveWorkspaceScope(cwd);
   const url2 = sharedMcpUrl(scope.mcpHttpPort);
   log(`[lensmcp] shim \u2192 workspace "${scope.key}" (${scope.root}) \u2192 ${url2}`);
+  let seen = { alive: false, owner: "none" };
+  let warnedUnknown = false;
+  let explained = false;
+  const verifyIdentity = () => {
+    const mismatch = describeIdentityMismatch(scope, seen.identity);
+    if (!mismatch) {
+      if (seen.alive && !seen.identity && !warnedUnknown) {
+        warnedUnknown = true;
+        log(`[lensmcp] note: the server on :${scope.mcpHttpPort} does not report a workspace (it predates this check), so it cannot be verified as "${scope.key}". Restart it \u2014 \`lensmcp gateway restart\` \u2014 to get the check.`);
+      }
+      return void 0;
+    }
+    const theirs = seen.identity;
+    explained = true;
+    log("");
+    log(`[lensmcp] REFUSING the shared MCP server on 127.0.0.1:${scope.mcpHttpPort} \u2014 ${mismatch}.`);
+    log(`[lensmcp]   this session's workspace : "${scope.key}"  ${scope.root}`);
+    log(`[lensmcp]   the server's workspace    : "${theirs?.key}"  ${theirs?.root}` + (theirs?.pid ? `  (pid ${theirs.pid})` : ""));
+    log("[lensmcp]   Two workspaces derive the same MCP port. Attaching would show you the");
+    log("[lensmcp]   OTHER project's events, builds and flows, so this session will not.");
+    log("[lensmcp]   Fix: pin a distinct port in this workspace's .lensmcp/config.json \u2014");
+    log(`[lensmcp]     { "ports": { "mcpHttp": ${scope.mcpHttpPort + 1} } }`);
+    log("[lensmcp]   then restart this session. Any free 4500-4699 port works.");
+    log("");
+    return `the shared MCP port is served by workspace "${theirs?.key}", not "${scope.key}"`;
+  };
+  const foreignPortOwner = async () => {
+    const port = scope.mcpHttpPort;
+    const nonHttp = seen.owner === "foreign" ? false : await tcpAccepts(port);
+    if (seen.owner !== "foreign" && !nonHttp)
+      return void 0;
+    explained = true;
+    log("");
+    log(`[lensmcp] the shared MCP port 127.0.0.1:${port} is TAKEN by another process.`);
+    log(`[lensmcp]   It ${nonHttp ? "accepts connections but does not speak HTTP" : "answers HTTP but is not a lensmcp MCP server"}, so this session cannot attach to it.`);
+    log("[lensmcp]   Not starting a server on it: on macOS a second bind SUCCEEDS on the");
+    log("[lensmcp]   wildcard address while the kernel keeps routing 127.0.0.1 to the");
+    log("[lensmcp]   process already there \u2014 the new server would be unreachable, and");
+    log("[lensmcp]   would keep running after this session ends.");
+    log("[lensmcp]   Fix EITHER by freeing the port:");
+    log(`[lensmcp]     lsof -nP -iTCP:${port} -sTCP:LISTEN`);
+    log(`[lensmcp]   OR by pinning a different one in ${join3(scope.root, ".lensmcp", "config.json")}:`);
+    log(`[lensmcp]     { "ports": { "mcpHttp": ${port + 1} } }`);
+    log("[lensmcp]   then restart this session. Any free 4500-4699 port works.");
+    log("");
+    return `the shared MCP port ${port} is held by another process that is not a lensmcp server`;
+  };
   const ensure = () => {
     let watch;
     return ensureSharedServer({
-      probe: () => probe(url2),
+      probe: async () => {
+        seen = await probeShared(scope.mcpHttpPort);
+        return seen.alive;
+      },
+      verifyIdentity,
+      foreignPortOwner,
       startServer: () => {
         const started = startSharedServerWatched({
           serverEntry: serverEntry(),
           port: scope.mcpHttpPort,
           eventFile: scope.eventFile,
           cwd: scope.root,
+          workspaceKey: scope.key,
+          workspaceRoot: scope.root,
           onLog: log
         });
         watch = started.exited;
@@ -8922,7 +9074,7 @@ async function main() {
   };
   const ensured = await ensure();
   if (ensured.outcome === "unavailable") {
-    runEmbedded(cwd, ensured.reason ?? "unknown");
+    runEmbedded(cwd, ensured.reason ?? "unknown", !explained);
     return;
   }
   log(`[lensmcp] shim: shared server ${ensured.outcome} (${ensured.waitedMs}ms)`);
@@ -8936,8 +9088,17 @@ async function main() {
       }
       return new StreamableHTTPClientTransport(new URL(url2));
     },
-    // Consulted before acting on an error, so a blip does not cost a session.
-    isUpstreamHealthy: () => probe(url2, 1e3),
+    // Filters blips so a transient error does not cost a live session — but a
+    // server that has become a STRANGER is not a blip. Reporting it unhealthy
+    // sends the pump into `connect()`, which re-ensures, refuses, and ends the
+    // session cleanly; calling it healthy would instead leave the pump erroring
+    // forever against a server that has never heard of our session id.
+    isUpstreamHealthy: async () => {
+      const now = await probeShared(scope.mcpHttpPort, 1e3);
+      if (!now.alive)
+        return false;
+      return describeIdentityMismatch(scope, now.identity) === void 0;
+    },
     log,
     onFatal: (reason) => log(`[lensmcp] shim: ${reason}`)
   });

package/lib/mcp-mode.d.ts

@@ -36,14 +36,25 @@
  * spawns the server, waits, and if it still cannot get one it falls back to
  * today's embedded server so a session is NEVER left without the lens.
  *
- * The isolation boundary is the PORT
- * ----------------------------------
+ * The isolation boundary is the PORT — and the port is VERIFIED
+ * -------------------------------------------------------------
  * One daemon hosts many workspaces (foodguard + tetros), and their observability
  * data must never mix. Each workspace already reserves its own `ports.mcpHttp`
  * in `.lensmcp/config.json` (deterministic per workspace key). The shim resolves
  * that port from the workspace it was pointed at — NEVER a shared default. Two
  * workspaces landing on one port would cross-feed each other's events.
  *
+ * But the port is DERIVED (`4500 + fnv1a(key) % 200`), so two workspaces CAN
+ * hash onto one — and unlike the dashboard port it must not step up on
+ * collision, because the port IS the shim's contract. Two checkouts of one repo
+ * are worse: same key, same port, different event files. So the port alone is
+ * not proof of ownership. The shared server STATES which workspace it serves, on
+ * a `GET /lensmcp/identity` route mounted beside the MCP endpoint, and the shim
+ * REFUSES a server whose workspace is not its own — degrading to the embedded
+ * server rather than silently reading another project's events. It is checked
+ * before a single JSON-RPC frame is proxied, and costs nothing: that GET
+ * REPLACES the `initialize` probe the shim already had to make.
+ *
  * This module is pure (values in, values out) so every rule below is
  * unit-testable without a filesystem, a daemon, or an agent client.
  */

package/lib/mcp-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-mode.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,sDAAsD;AACtD,MAAM,MAAM,OAAO;AACjB,yFAAyF;AACvF,UAAU;AACZ,sFAAsF;GACpF,QAAQ,CAAC;AAEb,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,EAAE,OAAoB,CAAC;AAEpD,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAgC,GAAG,MAAM,CAEzF;AAED,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,aAAkB,GAAG,OAAO,CAKlE;AAED,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAcD,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,CASnF"}
+{"version":3,"file":"mcp-mode.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAEH,sDAAsD;AACtD,MAAM,MAAM,OAAO;AACjB,yFAAyF;AACvF,UAAU;AACZ,sFAAsF;GACpF,QAAQ,CAAC;AAEb,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,EAAE,OAAoB,CAAC;AAEpD,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAgC,GAAG,MAAM,CAEzF;AAED,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,aAAkB,GAAG,OAAO,CAKlE;AAED,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAcD,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,CASnF"}

package/lib/mcp-mode.js

@@ -36,14 +36,25 @@
  * spawns the server, waits, and if it still cannot get one it falls back to
  * today's embedded server so a session is NEVER left without the lens.
  *
- * The isolation boundary is the PORT
- * ----------------------------------
+ * The isolation boundary is the PORT — and the port is VERIFIED
+ * -------------------------------------------------------------
  * One daemon hosts many workspaces (foodguard + tetros), and their observability
  * data must never mix. Each workspace already reserves its own `ports.mcpHttp`
  * in `.lensmcp/config.json` (deterministic per workspace key). The shim resolves
  * that port from the workspace it was pointed at — NEVER a shared default. Two
  * workspaces landing on one port would cross-feed each other's events.
  *
+ * But the port is DERIVED (`4500 + fnv1a(key) % 200`), so two workspaces CAN
+ * hash onto one — and unlike the dashboard port it must not step up on
+ * collision, because the port IS the shim's contract. Two checkouts of one repo
+ * are worse: same key, same port, different event files. So the port alone is
+ * not proof of ownership. The shared server STATES which workspace it serves, on
+ * a `GET /lensmcp/identity` route mounted beside the MCP endpoint, and the shim
+ * REFUSES a server whose workspace is not its own — degrading to the embedded
+ * server rather than silently reading another project's events. It is checked
+ * before a single JSON-RPC frame is proxied, and costs nothing: that GET
+ * REPLACES the `initialize` probe the shim already had to make.
+ *
  * This module is pure (values in, values out) so every rule below is
  * unit-testable without a filesystem, a daemon, or an agent client.
  */

package/lib/workspace-scope.d.ts

@@ -44,6 +44,20 @@ export interface LensConfig {
      * just because this field was added.
      */
     mcp?: LensMcpConfig;
+    /**
+     * Optional. Dirs removed from the source-set staleness signature + pod scope
+     * (e.g. `["docs"]` so a docs write does not recycle every vite pod). READ by
+     * `@lensmcp/cluster` (`runtime/scope.ts` `readSourceSetExclude`); declared here
+     * so this writer round-trips it instead of dropping it.
+     */
+    sourceSet?: {
+        exclude?: string[];
+    };
+    /**
+     * Any key this version does not know about. Preserved verbatim on write —
+     * see the round-trip contract on `readLensConfig`.
+     */
+    [key: string]: unknown;
 }
 /** Lowercase kebab slug; empty input → `workspace`. */
 export declare function slugify(input: string): string;
@@ -62,6 +76,14 @@ export declare function deriveConfig(root: string): LensConfig;
  * Read `<root>/.lensmcp/config.json` if present, else the derived defaults. A present
  * file OVERRIDES derived values field-by-field (so a user can pin a key/port without
  * losing the rest), and is the seam the gateway + CLI both read so they agree.
+ *
+ * ROUND-TRIP CONTRACT: every key on disk survives, including ones this version does
+ * not model. `ensureLensConfig` writes whatever this returns, so anything dropped
+ * here is silently DELETED from the user's file. That was a real bug: the result was
+ * built field-by-field from the four known keys, so a hand-set `sourceSet.exclude`
+ * (honored by `@lensmcp/cluster`, but not declared here) was stripped on every
+ * `lensmcp setup` — the docs-exclusion never took effect, and `docs/**` writes kept
+ * recycling every vite pod. Spread the file FIRST, then normalize; never enumerate.
  */
 export declare function readLensConfig(root: string): LensConfig;
 /** Persist the (derived/merged) config so it is visible + overridable. Idempotent;

package/lib/workspace-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-scope.d.ts","sourceRoot":"","sources":["../../src/lib/workspace-scope.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,SAAS;IACxB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAaD,uDAAuD;AACvD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOxD;AAOD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAOlD;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAGrD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAevD;AAED;yDACyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAQzD"}
+{"version":3,"file":"workspace-scope.d.ts","sourceRoot":"","sources":["../../src/lib/workspace-scope.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,SAAS;IACxB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACnC;;;OAGG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAaD,uDAAuD;AACvD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOxD;AAOD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAOlD;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAGrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAiBvD;AAED;yDACyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAQzD"}

package/lib/workspace-scope.js

@@ -57,6 +57,14 @@ export function deriveConfig(root) {
  * Read `<root>/.lensmcp/config.json` if present, else the derived defaults. A present
  * file OVERRIDES derived values field-by-field (so a user can pin a key/port without
  * losing the rest), and is the seam the gateway + CLI both read so they agree.
+ *
+ * ROUND-TRIP CONTRACT: every key on disk survives, including ones this version does
+ * not model. `ensureLensConfig` writes whatever this returns, so anything dropped
+ * here is silently DELETED from the user's file. That was a real bug: the result was
+ * built field-by-field from the four known keys, so a hand-set `sourceSet.exclude`
+ * (honored by `@lensmcp/cluster`, but not declared here) was stripped on every
+ * `lensmcp setup` — the docs-exclusion never took effect, and `docs/**` writes kept
+ * recycling every vite pod. Spread the file FIRST, then normalize; never enumerate.
  */
 export function readLensConfig(root) {
     const derived = deriveConfig(root);
@@ -65,6 +73,8 @@ export function readLensConfig(root) {
         return derived;
     const key = file.key ? slugify(file.key) : derived.key;
     return {
+        // Unknown//future keys ride through untouched — the normalized fields below win.
+        ...file,
         schemaVersion: 1,
         key,
         ports: { ...derived.ports, ...(file.ports ?? {}) },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lensmcp",
-  "version": "1.17.4",
+  "version": "1.18.1",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",
@@ -17,7 +17,7 @@
     }
   },
   "dependencies": {
-    "@frontmcp/sdk": "^1.5.6",
+    "@frontmcp/sdk": "^1.5.7",
     "reflect-metadata": "^0.2.2",
     "tslib": "^2.3.0",
     "vectoriadb": "^2.2.0"

package/plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "lensmcp",
   "displayName": "LensMCP",
   "description": "The observability lens for coding agents. One command brings up the dev cluster gateway (every project.json `cluster` decl → its host on :443), the per-project lens dashboard at https://lensmcp.local/<project>/, and the MCP server your agent connects to — scoped automatically to whatever project you opened Claude Code in.",
-  "version": "1.17.4",
+  "version": "1.18.1",
   "author": {
     "name": "David Antoon",
     "email": "davidmantoon@gmail.com"