lensmcp 1.16.0 → 1.16.2

package/lib/cli.js

@@ -200,12 +200,24 @@ function runGateway(ctx, args, out, err) {
     const logFile = join(cwd, '.lensmcp', 'gateway.log');
     const dashUrl = `https://lensmcp.local${cfg.dashboardBasePath}/`;
     const start = () => {
-        const running = readPid(pidFile);
-        if (running && isAlive(running)) {
+        // Reconcile with reality FIRST: an alive pid-file wins; else adopt an orphaned gateway on :443 (the
+        // desync self-heal) — so a second `start` NEVER spawns a duplicate that EADDRINUSE-crashes + orphans.
+        const { pid: running, healed } = reconcileGateway(pidFile, cwd);
+        if (running !== undefined && isAlive(running)) {
+            if (healed)
+                out(`healed: adopted a running gateway (pid ${running}) the pid file had lost — no duplicate started.`);
             out(`gateway already running (pid ${running}).`);
             out(`  dashboard → ${dashUrl}`);
             return { exitCode: 0 };
         }
+        // :443 is free of any lens gateway — but if a FOREIGN process holds it, spawning would just
+        // EADDRINUSE-crash and re-create the orphan mess. Surface it instead of stacking a doomed child.
+        const foreign = pidsOnPort443()[0];
+        if (foreign !== undefined) {
+            err(`port :443 is held by pid ${foreign}, which is not this workspace's gateway.\n` +
+                `Free it first (stop that process), then \`lensmcp gateway start\`.`);
+            return { exitCode: 1 };
+        }
         const target = findGatewayTarget(cwd, stringFlag(opts.flags['--project']), stringFlag(opts.flags['--target']));
         if (!target) {
             err('Could not find a gateway target (an executor `@lensmcp/cluster:gateway`) in this workspace.\n' +
@@ -235,32 +247,31 @@ function runGateway(ctx, args, out, err) {
         return { exitCode: 0 };
     };
     const stop = () => {
-        const pid = readPid(pidFile);
-        if (!pid || !isAlive(pid)) {
+        // Reality-based: kill the tracked pid OR an orphaned gateway the pid file lost track of (so `stop`
+        // works even after the desync — the case where the old CLI reported "not running" but :443 was held).
+        const { pid, healed } = reconcileGateway(pidFile, cwd);
+        if (pid === undefined) {
             out('gateway not running.');
             rmFile(pidFile);
             return { exitCode: 0 };
         }
+        if (healed)
+            out(`healed: found an orphaned gateway (pid ${pid}) the pid file had lost — stopping it.`);
         // Detached child is its own process-group leader → negative pid kills the whole tree.
-        try {
-            process.kill(-pid, 'SIGTERM');
-        }
-        catch {
-            try {
-                process.kill(pid, 'SIGTERM');
-            }
-            catch {
-                /* already gone */
-            }
-        }
+        killGatewayTree(pid);
         rmFile(pidFile);
+        // Escalate: if a lens gateway STILL holds :443 (a differently-parented tree), kill that too, so
+        // `stop` genuinely frees the port instead of leaving a wedged listener behind.
+        const still = gatewayOnPort443(cwd);
+        if (still !== undefined && still !== pid)
+            killGatewayTree(still);
         out(`gateway stopped (pid ${pid}).`);
         return { exitCode: 0 };
     };
     const status = () => {
-        const pid = readPid(pidFile);
+        const { pid, healed } = reconcileGateway(pidFile, cwd);
         const alive = pid !== undefined && isAlive(pid);
-        out(`gateway: ${alive ? `running (pid ${pid})` : 'stopped'}`);
+        out(`gateway: ${alive ? `running (pid ${pid})${healed ? ' — recovered a stale pid file' : ''}` : 'stopped'}`);
         out(`  workspace → ${cfg.key}`);
         out(`  dashboard → ${dashUrl}`);
         if (alive)
@@ -376,6 +387,79 @@ function isAlive(pid) {
         return e.code === 'EPERM'; // exists but not ours
     }
 }
+/* ───────── reality-based gateway discovery (self-heal the pid-file desync) ─────────
+ * The gateway is tracked ONLY by `.lensmcp/gateway.pid`. If a start crashed AFTER binding failed
+ * (a duplicate `start`/`restart` while an untracked gateway already held :443 → EADDRINUSE), the pid
+ * file ends up pointing at the DEAD child while the ORIGINAL gateway keeps running orphaned — so
+ * `status` falsely reports "stopped" and `stop` can't kill it. These helpers cross-check the ACTUAL
+ * :443 owner so start/stop/status reconcile with reality instead of trusting a stale pid file.
+ * Unix-only (lsof/ps); on a platform without them they no-op → the pid-file path is unchanged. */
+/** All pids LISTENING on :443 (best-effort via lsof; [] when free / lsof unavailable). */
+function pidsOnPort443() {
+    try {
+        const r = spawnSync('lsof', ['-nP', '-iTCP:443', '-sTCP:LISTEN', '-t'], { encoding: 'utf8' });
+        if (r.status !== 0 || !r.stdout)
+            return [];
+        return [...new Set(r.stdout.split(/\s+/).map(Number).filter((n) => Number.isInteger(n) && n > 0))];
+    }
+    catch {
+        return [];
+    }
+}
+/** The full command line of a pid (best-effort via ps; '' on failure). */
+function processCmd(pid) {
+    try {
+        return (spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }).stdout ?? '').trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** The pid on :443 that belongs to THIS workspace's lensmcp gateway. Only the gateway binds :443 in a
+ *  lens workspace, so a run-executor / `@lensmcp/cluster` process of `cwd` holding :443 IS the gateway.
+ *  Returns undefined when :443 is free, held by a foreign process, or lsof/ps are unavailable. */
+function gatewayOnPort443(cwd) {
+    const sigExecutor = join(cwd, 'node_modules', 'nx', 'dist', 'bin', 'run-executor.js');
+    const sigCluster = join(cwd, 'node_modules', '@lensmcp', 'cluster');
+    for (const pid of pidsOnPort443()) {
+        const cmd = processCmd(pid);
+        if (cmd.includes(sigExecutor) || cmd.includes(sigCluster))
+            return pid;
+    }
+    return undefined;
+}
+/** Reconcile the tracked pid with reality: a LIVE pid-file wins; otherwise ADOPT an orphaned gateway
+ *  still holding :443 (rewriting the pid file) — the self-heal for the stale-pid desync. */
+function reconcileGateway(pidFile, cwd) {
+    const tracked = readPid(pidFile);
+    if (tracked !== undefined && isAlive(tracked))
+        return { pid: tracked, healed: false };
+    const orphan = gatewayOnPort443(cwd);
+    if (orphan !== undefined) {
+        try {
+            writeFileSync(pidFile, String(orphan));
+        }
+        catch {
+            /* pid-file unwritable — still return the orphan so stop/status act on reality */
+        }
+        return { pid: orphan, healed: true };
+    }
+    return { healed: false };
+}
+/** Best-effort kill of a detached gateway process GROUP (the leader is its own group via `detached`). */
+function killGatewayTree(pid) {
+    try {
+        process.kill(-pid, 'SIGTERM');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
 function rmFile(path) {
     try {
         if (existsSync(path))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lensmcp",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",

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.16.0",
+  "version": "1.16.2",
   "author": {
     "name": "David Antoon",
     "email": "davidmantoon@gmail.com"

package/plugin/skills/stop/SKILL.md

@@ -10,8 +10,14 @@ Run the stop script with the Bash tool:
 "${CLAUDE_PLUGIN_ROOT}/scripts/gateway-stop.sh"
 ```
 
-It calls `lensmcp gateway stop` for `${CLAUDE_PROJECT_DIR}`, which reads the pid recorded
-in `.lensmcp/gateway.pid` and terminates the gateway process group (the gateway plus the
-app/service pods + the lens dashboard it spawned).
+It calls `lensmcp gateway stop` for `${CLAUDE_PROJECT_DIR}`, which terminates the gateway process
+group (the gateway plus the app/service pods + the lens dashboard it spawned).
 
-Report whether it stopped, or that it was already not running.
+`stop`/`status`/`start` are **reality-based**: they trust `.lensmcp/gateway.pid` only when it is
+alive, and otherwise **reconcile against the actual :443 owner**. So `stop` still kills an *orphaned*
+gateway that a stale pid file had lost track of (the desync where a crashed duplicate-`start` left the
+pid file pointing at a dead process while the original gateway kept running) — and `start` **adopts**
+that orphan instead of spawning a duplicate that would `EADDRINUSE`-crash.
+
+Report whether it stopped, whether it **healed** a stale/orphaned gateway (the CLI prints a `healed:` line),
+or that it was already not running.