@lensmcp/cluster 1.16.30 → 1.16.31

package/executors/gateway/runtime/lens-children.js

@@ -186,7 +186,7 @@ deps) {
                 rt.rebuildRoutes();
                 // Publish this workspace to the GLOBAL registry so the root chooser at `${lensHost}/` lists it
                 // (and marks it live while this gateway runs). Best-effort — a registry write never blocks serving.
-                (0, workspace_registry_1.registerWorkspace)({ key: scope.key, root: rt.root, base: lensBase, pid: process.pid, updatedAt: new Date().toISOString() });
+                (0, workspace_registry_1.registerWorkspace)({ key: scope.key, root: rt.root, base: lensBase, pid: process.pid, procStamp: (0, workspace_registry_1.processStamp)(process.pid), updatedAt: new Date().toISOString() });
                 console.log(`[gateway] starting lens dashboard → http://localhost:${dashboardPort} (routed at https://${lensHost}${lensBase}/)`);
                 emit('info', `lens dashboard up: ${lensHost}${lensBase} → :${dashboardPort}`, 'cluster-lens-dashboard', { kind: 'lens-dashboard-up', host: lensHost, port: dashboardPort, base: lensBase });
                 spawnManagedChild('lens-dashboard', process.execPath, [dashboardBundle], {
@@ -271,7 +271,7 @@ deps) {
         rt.registry.appendRoutes(fragment.wsKey, [{ host: lensHost, prefix: lensBase, project: observability_1.LENS_DASHBOARD_PROJECT, target: `http://localhost:${port}` }]);
         // Publish the hosted workspace to the GLOBAL chooser registry (keyed on the DAEMON's pid — the daemon is
         // what keeps it live), so `lensmcp.local/` lists it. Reaped on unregister below.
-        (0, workspace_registry_1.registerWorkspace)({ key: fragment.wsKey, root: fragment.root, base: lensBase, pid: process.pid, updatedAt: new Date().toISOString() });
+        (0, workspace_registry_1.registerWorkspace)({ key: fragment.wsKey, root: fragment.root, base: lensBase, pid: process.pid, procStamp: (0, workspace_registry_1.processStamp)(process.pid), updatedAt: new Date().toISOString() });
         console.log(`[gateway] hosting dashboard for workspace '${fragment.wsKey}' → http://localhost:${port} (routed at https://${lensHost}${lensBase}/)`);
         emit('info', `lens dashboard up: ${lensHost}${lensBase} → :${port}`, 'cluster-lens-dashboard', { kind: 'lens-dashboard-up', host: lensHost, port, base: lensBase });
         spawnManagedChild(label, process.execPath, [bundle], {

package/executors/gateway/runtime/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/lifecycle.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAapE,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,iBAAiB,CAAC;AAyE/D;;;yEAGyE;AACzE,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BtE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,oBAAoB,CAAC,EACpG,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,gBAAgB,GACpB,kBAAkB,GAAG,SAAS,GAAG,IAAI,CAQvC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAMT;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAChC,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,2EAA2E;IAC3E,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC;CAChC;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CA4XvF"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/lifecycle.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAapE,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,iBAAiB,CAAC;AAyE/D;;;yEAGyE;AACzE,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BtE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,oBAAoB,CAAC,EACpG,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,gBAAgB,GACpB,kBAAkB,GAAG,SAAS,GAAG,IAAI,CAQvC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAMT;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IAChC,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,2EAA2E;IAC3E,YAAY,IAAI,MAAM,CAAC,OAAO,CAAC;CAChC;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,GAAG,YAAY,CAiYvF"}

package/executors/gateway/runtime/lifecycle.js

@@ -196,7 +196,7 @@ function createServiceLayer(rt, obs) {
      * its whole devserver tree with it. One `ps` exec; a clean cold start is a no-op.
      */
     const reapForeignRunners = (svc, target) => {
-        let out = '';
+        let out;
         try {
             out = (0, node_child_process_1.execFileSync)('ps', ['ax', '-ww', '-o', 'pid=,pgid=,command='], { encoding: 'utf8', timeout: 5_000 });
         }
@@ -300,6 +300,11 @@ function createServiceLayer(rt, obs) {
                 NX_ISOLATE_PLUGINS: 'false',
                 ...(svc.wsKey ? { LENSMCP_WS_KEY: svc.wsKey } : {}),
                 LENSMCP_EVENT_FILE: svc.wsKey === rt.wsKey ? rt.eventFile : path.join(svc.root, '.lensmcp', 'events.jsonl'),
+                // Rides the env inherit down the whole nx chain (nx run → run-executor → serve fork) into
+                // main.devserver, whose gateway watchdog self-exits the pod tree when this pid dies. Without
+                // it an UNGRACEFUL gateway death (crash/SIGKILL — no process-group kill runs) orphans the
+                // entire chain under launchd forever (2026-07-28: a day-old tetros pod tree at PPID 1).
+                LENSMCP_GATEWAY_PID: String(process.pid),
                 ...eastWestEnv(rt, svc.project),
             },
             stdio: ['ignore', 'pipe', 'pipe'],

package/executors/gateway/runtime/observability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/observability.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B;;4GAEwG;IACxG,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvJ,GAAG,IAAI,MAAM,CAAC;IACd,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3D,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1F,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5G,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5E,0FAA0F;IAC1F,gBAAgB,IAAI,MAAM,CAAC,OAAO,CAAC;CACpC;AAKD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAoGtG"}
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/observability.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAoB9C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B;;4GAEwG;IACxG,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvJ,GAAG,IAAI,MAAM,CAAC;IACd,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,GAAG,OAAO,GAAG,SAAS,CAAC;IAC3D,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1F,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5G,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5E,0FAA0F;IAC1F,gBAAgB,IAAI,MAAM,CAAC,OAAO,CAAC;CACpC;AAKD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAiHtG"}

package/executors/gateway/runtime/observability.js

@@ -17,6 +17,15 @@ const tslib_1 = require("tslib");
  */
 const fs = tslib_1.__importStar(require("node:fs"));
 const path = tslib_1.__importStar(require("node:path"));
+const busHygiene = (() => {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('@lensmcp/node-instrumentation');
+    }
+    catch {
+        return undefined;
+    }
+})();
 /**
  * The lens's OWN dashboard route project (the value `lens-children.ts` gives the `lensmcp.local/<key>/`
  * route). Traffic to it is the lens UI polling its own control-plane API (`/<key>/api/cluster|logs|snapshot`)
@@ -29,15 +38,28 @@ exports.LENS_DASHBOARD_PROJECT = '(lens-dashboard)';
 const hdr = (v) => typeof v === 'string' && v !== '' ? v : Array.isArray(v) ? v[0] : undefined;
 function createObservability(eventFile, opts) {
     const eid = () => Date.now().toString(36) + Math.random().toString(36).slice(2, 12);
+    // The gateway narrates OTHER apps' traffic — an app stuck in a retry loop must not turn that
+    // narration into a bus flood (2026-07-28: `gateway-request:<project>` alone wrote thousands of
+    // lines/min). Per-fingerprint token bucket: first burst passes, then a trickle carrying
+    // `floodSuppressed` counts. Errors stay loud — the burst re-arms once the storm subsides.
+    const floodGuard = busHygiene?.createEventFloodGuard({ burst: 30, perSec: 5 });
     const emit = (severity, title, fingerprint, raw, flowCtx, busFile) => {
         const target = busFile ?? eventFile; // a registered workspace's service events go to ITS bus, not the daemon's
         try {
+            const admit = floodGuard ? floodGuard.admit(fingerprint) : { ok: true, suppressed: 0 };
+            if (!admit.ok)
+                return;
             fs.mkdirSync(path.dirname(target), { recursive: true });
-            fs.appendFileSync(target, JSON.stringify({
+            const line = JSON.stringify({
                 id: eid(), sessionId: 'pending', timestamp: Date.now(),
                 source: 'gateway', category: 'cluster', severity,
-                context: { sessionId: 'pending', ...flowCtx }, fingerprint, title, raw,
-            }) + '\n');
+                context: { sessionId: 'pending', ...flowCtx }, fingerprint, title,
+                raw: admit.suppressed > 0 ? { ...raw, floodSuppressed: admit.suppressed } : raw,
+            }) + '\n';
+            // The gateway was the one bus writer with NO size cap — enforce the same rotation contract
+            // as every other producer (emit.ts / capture-runner), per target file.
+            busHygiene?.maybeRotateEventFile(target, line.length);
+            fs.appendFileSync(target, line);
         }
         catch { /* lens offline — never block traffic */ }
     };

package/executors/gateway/runtime/workspace-registry.d.ts

@@ -7,9 +7,23 @@ export interface WorkspaceEntry {
     base: string;
     /** The gateway process that registered this workspace (owns :443 for it). Liveness is checked via this. */
     pid: number;
+    /**
+     * The registering process's start-time stamp (`ps -o lstart=`), captured at register. A pid alone
+     * can LIE: after an ungraceful gateway death the OS recycles the number, and `kill(pid, 0)` then
+     * vouches for a stranger (2026-07-28: tetros's dead-gateway pid came back as an nx run-executor and
+     * the chooser kept listing the workspace as live). Same pid + same start time = same process.
+     * Absent on legacy entries and on platforms without `ps` — liveness then falls back to kill(0).
+     */
+    procStamp?: string;
     /** ISO timestamp of the last register. */
     updatedAt: string;
 }
+/**
+ * The start-time identity stamp for a pid (`''` when `ps` is unavailable — Windows, restricted
+ * environments — or the process is gone). Start time is immutable for the life of a process and
+ * survives in no recycled successor, which makes it the cheapest cross-platform-ish identity proof.
+ */
+export declare function processStamp(pid: number): string;
 /** `~/.lensmcp/workspaces.json` — override the home dir via `LENSMCP_HOME` (tests). */
 export declare function registryPath(): string;
 export declare function readWorkspaces(file?: string): WorkspaceEntry[];
@@ -17,6 +31,10 @@ export declare function readWorkspaces(file?: string): WorkspaceEntry[];
 export declare function registerWorkspace(entry: WorkspaceEntry, file?: string): void;
 /** Drop this workspace — called on a graceful gateway stop. */
 export declare function unregisterWorkspace(key: string, file?: string): void;
-/** Is the gateway that registered this workspace still alive? `process.kill(pid, 0)` throws ESRCH if not. */
-export declare function isWorkspaceLive(entry: Pick<WorkspaceEntry, 'pid'>): boolean;
+/**
+ * Is the gateway that registered this workspace still alive? `process.kill(pid, 0)` throws ESRCH if
+ * not — and when the entry carries a `procStamp`, the pid must ALSO still be the SAME process
+ * (recycled pids fail the start-time comparison instead of impersonating a live gateway).
+ */
+export declare function isWorkspaceLive(entry: Pick<WorkspaceEntry, 'pid' | 'procStamp'>): boolean;
 //# sourceMappingURL=workspace-registry.d.ts.map

package/executors/gateway/runtime/workspace-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-registry.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/workspace-registry.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2GAA2G;IAC3G,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uFAAuF;AACvF,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,wBAAgB,cAAc,CAAC,IAAI,SAAiB,GAAG,cAAc,EAAE,CAYtE;AAWD,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,SAAiB,GAAG,IAAI,CAKpF;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAiB,GAAG,IAAI,CAK5E;AAED,6GAA6G;AAC7G,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC,GAAG,OAAO,CAQ3E"}
+{"version":3,"file":"workspace-registry.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/workspace-registry.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC7B,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,2GAA2G;IAC3G,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWhD;AAED,uFAAuF;AACvF,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,wBAAgB,cAAc,CAAC,IAAI,SAAiB,GAAG,cAAc,EAAE,CAYtE;AAWD,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,SAAiB,GAAG,IAAI,CAKpF;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAiB,GAAG,IAAI,CAK5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,WAAW,CAAC,GAAG,OAAO,CAUzF"}

package/executors/gateway/runtime/workspace-registry.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.processStamp = processStamp;
 exports.registryPath = registryPath;
 exports.readWorkspaces = readWorkspaces;
 exports.registerWorkspace = registerWorkspace;
@@ -16,9 +17,29 @@ const tslib_1 = require("tslib");
  * Concurrency: read-modify-write, best-effort. Writes are rare (start/stop only) and the file is tiny, so
  * a lost update at most drops one entry from the listing until the next start — never a correctness issue.
  */
+const node_child_process_1 = require("node:child_process");
 const fs = tslib_1.__importStar(require("node:fs"));
 const os = tslib_1.__importStar(require("node:os"));
 const path = tslib_1.__importStar(require("node:path"));
+/**
+ * The start-time identity stamp for a pid (`''` when `ps` is unavailable — Windows, restricted
+ * environments — or the process is gone). Start time is immutable for the life of a process and
+ * survives in no recycled successor, which makes it the cheapest cross-platform-ish identity proof.
+ */
+function processStamp(pid) {
+    if (!pid || pid <= 0 || process.platform === 'win32')
+        return '';
+    try {
+        return (0, node_child_process_1.execFileSync)('ps', ['-p', String(pid), '-o', 'lstart='], {
+            encoding: 'utf8',
+            timeout: 2_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
 /** `~/.lensmcp/workspaces.json` — override the home dir via `LENSMCP_HOME` (tests). */
 function registryPath() {
     const home = process.env['LENSMCP_HOME'] || os.homedir();
@@ -56,15 +77,23 @@ function registerWorkspace(entry, file = registryPath()) {
 function unregisterWorkspace(key, file = registryPath()) {
     writeWorkspaces(readWorkspaces(file).filter((e) => e.key !== key), file);
 }
-/** Is the gateway that registered this workspace still alive? `process.kill(pid, 0)` throws ESRCH if not. */
+/**
+ * Is the gateway that registered this workspace still alive? `process.kill(pid, 0)` throws ESRCH if
+ * not — and when the entry carries a `procStamp`, the pid must ALSO still be the SAME process
+ * (recycled pids fail the start-time comparison instead of impersonating a live gateway).
+ */
 function isWorkspaceLive(entry) {
     if (!entry.pid || entry.pid <= 0)
         return false;
     try {
         process.kill(entry.pid, 0);
-        return true; // alive (or EPERM below — exists but not ours)
     }
     catch (e) {
-        return e.code === 'EPERM'; // EPERM = exists but not signalable; ESRCH = gone
+        if (e.code !== 'EPERM')
+            return false; // EPERM = exists but not signalable; ESRCH = gone
     }
+    if (!entry.procStamp)
+        return true; // legacy entry / no-ps platform — pid liveness is all we have
+    const now = processStamp(entry.pid);
+    return now === '' ? true : now === entry.procStamp; // '' = ps unavailable here — don't false-negative
 }

package/main.devserver.js

@@ -1090,5 +1090,28 @@ else {
             setTimeout(() => process.exit(0), 700).unref();
         };
         ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT', 'SIGUSR2'].forEach(sig => process.on(sig, () => void shutdown(sig)));
+        // Gateway watchdog: the gateway kills pods via its spawned process group, but an UNGRACEFUL
+        // gateway death (crash/SIGKILL) never runs that kill — the whole nx run → run-executor →
+        // devserver chain reparents to launchd and squats its ports/sockets forever (the 2026-07-28
+        // day-old orphan tree). We are layers below the gateway, so a ppid check can't see it — poll
+        // the stamped pid instead and tear down through the SAME graceful path when it's gone. The
+        // chain above us unwinds as our exit propagates. A pod run OUTSIDE a gateway (`nx serve`
+        // directly) has no LENSMCP_GATEWAY_PID and is untouched.
+        const gatewayPid = Number(process.env.LENSMCP_GATEWAY_PID ?? 0);
+        if (Number.isInteger(gatewayPid) && gatewayPid > 0) {
+            const watchdog = setInterval(() => {
+                try {
+                    process.kill(gatewayPid, 0);
+                }
+                catch (e) {
+                    if (e.code === 'EPERM')
+                        return; // exists, just not signalable
+                    clearInterval(watchdog);
+                    console.error(`[parent] gateway (pid ${gatewayPid}) is gone — shutting the pod down to avoid an orphan tree.`);
+                    void shutdown('gateway-gone');
+                }
+            }, 5_000);
+            watchdog.unref(); // never keeps an otherwise-done parent alive
+        }
     })();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/cluster",
-  "version": "1.16.30",
+  "version": "1.16.31",
   "description": "Run your Nx workspace as a local production cluster: pods on unix sockets with true HMR, one https gateway with per-project domains, scale-from-zero, autoscale, idle-kill, local-CA TLS — observed by the LensMCP lens.",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -65,8 +65,8 @@
     }
   },
   "dependencies": {
-    "@lensmcp/node-instrumentation": "1.16.30",
-    "@lensmcp/nx-plugin": "1.16.30",
+    "@lensmcp/node-instrumentation": "1.16.31",
+    "@lensmcp/nx-plugin": "1.16.31",
     "fork-ts-checker-webpack-plugin": "^9.0.0",
     "glob": "^11.0.0",
     "http-proxy": "^1.18.0",