@lensmcp/cluster 1.16.23 → 1.16.25

package/basic-ssl.d.ts

@@ -1,7 +1,12 @@
 export declare const CA_CERT_FILE = "lensmcp-local-ca.crt";
+/** The machine-level CA directory: `~/.lensmcp/ca` (override home via `LENSMCP_HOME` — tests). */
+export declare function caDir(): string;
+/** Absolute path of the trust-once, machine-level CA certificate. */
+export declare function caCertPath(): string;
 export declare function getCertificateSync(cacheDir: string, name?: string, domains?: string[]): string;
-/** Absolute path of the trust-once CA certificate inside `cacheDir`. */
-export declare function caCertPath(cacheDir: string): string;
-/** Mint the local CA if it doesn't exist yet; returns the CA cert path. */
-export declare function ensureCaSync(cacheDir: string): string;
+/**
+ * Ensure the machine-level CA exists (promoting `legacyCacheDir`'s per-workspace
+ * CA when the machine store is still empty); returns the machine CA cert path.
+ */
+export declare function ensureCaSync(legacyCacheDir?: string): string;
 //# sourceMappingURL=basic-ssl.d.ts.map

package/basic-ssl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"basic-ssl.d.ts","sourceRoot":"","sources":["../../../libs/cluster/src/basic-ssl.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,YAAY,yBAAyB,CAAC;AAKnD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAgB,EAAE,OAAO,GAAE,MAAM,EAAO,GAAG,MAAM,CA0CzG;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMrD"}
+{"version":3,"file":"basic-ssl.d.ts","sourceRoot":"","sources":["../../../libs/cluster/src/basic-ssl.ts"],"names":[],"mappings":"AA4CA,eAAO,MAAM,YAAY,yBAAyB,CAAC;AAKnD,kGAAkG;AAClG,wBAAgB,KAAK,IAAI,MAAM,CAG9B;AAED,qEAAqE;AACrE,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,SAAgB,EAAE,OAAO,GAAE,MAAM,EAAO,GAAG,MAAM,CA8CzG;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5D"}

package/basic-ssl.js

@@ -1,18 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CA_CERT_FILE = void 0;
-exports.getCertificateSync = getCertificateSync;
+exports.caDir = caDir;
 exports.caCertPath = caCertPath;
+exports.getCertificateSync = getCertificateSync;
 exports.ensureCaSync = ensureCaSync;
 const tslib_1 = require("tslib");
 /**
  * Dev HTTPS certificates, mkcert-style: a long-lived LOCAL CA (10 years,
- * minted once per project, trusted once in the OS keychain) signs short-lived
+ * minted once per MACHINE, trusted once in the OS keychain) signs short-lived
  * leaf certs (30 days, re-minted per SAN set). Because the browser chains the
  * leaf to the trusted CA, cert rotation and new gateway hostnames never show
  * an interstitial again — unlike a bare self-signed cert, which would need
  * re-trusting on every change.
  *
+ * The CA is MACHINE-LEVEL — `~/.lensmcp/ca/` (override the home via
+ * `LENSMCP_HOME`, same convention as the workspace registry) — so every
+ * workspace/daemon on the machine serves chains anchored to ONE CA:
+ *  - the OS keychain holds exactly one "lensmcp local dev CA" (no same-CN
+ *    collisions between per-workspace CAs shadowing each other in `trust`),
+ *  - a pod's `NODE_EXTRA_CA_CERTS` stays valid across daemon handovers
+ *    (guest workspace → own daemon), because every daemon signs with the
+ *    same anchor.
+ * The first machine-CA resolution PROMOTES a pre-existing per-workspace CA
+ * (the pre-machine-CA layout) when one exists, so keychain trust already
+ * granted to it carries over without another sudo prompt. LEAF certs stay
+ * per-workspace in `<root>/node_modules/.cache/davnx-webpack` and are reused
+ * only when they chain to the CURRENT machine CA (the issuer pin below).
+ *
  * `getCertificateSync` returns ONE concatenated PEM (leaf key + leaf cert +
  * CA cert). Node's `https.createServer({ key: pem, cert: pem })` accepts it:
  * `key` takes the first private-key block, `cert` takes every certificate
@@ -20,10 +35,11 @@ const tslib_1 = require("tslib");
  *
  * Trust once (macOS):
  *   sudo security add-trusted-cert -d -r trustRoot \
- *     -k /Library/Keychains/System.keychain <cacheDir>/lensmcp-local-ca.crt
+ *     -k /Library/Keychains/System.keychain ~/.lensmcp/ca/lensmcp-local-ca.crt
  */
 const crypto = tslib_1.__importStar(require("node:crypto"));
 const fs = tslib_1.__importStar(require("node:fs"));
+const os = tslib_1.__importStar(require("node:os"));
 const path = tslib_1.__importStar(require("node:path"));
 /** Re-mint the leaf when the cached one is older than this (TTL is 30 days). */
 const LEAF_MAX_AGE_MS = 25 * 24 * 60 * 60 * 1000;
@@ -34,16 +50,22 @@ exports.CA_CERT_FILE = 'lensmcp-local-ca.crt';
 /** The legacy (pre-rebrand) CA filename — swept on mint so a stale `davnx-local-ca.crt` never lingers. */
 const LEGACY_CA_CERT_FILE = 'davnx-local-ca.crt';
 const CA_KEY_FILE = '_ca-key.pem';
+/** The machine-level CA directory: `~/.lensmcp/ca` (override home via `LENSMCP_HOME` — tests). */
+function caDir() {
+    const home = process.env['LENSMCP_HOME'] || os.homedir();
+    return path.join(home, '.lensmcp', 'ca');
+}
+/** Absolute path of the trust-once, machine-level CA certificate. */
+function caCertPath() {
+    return path.join(caDir(), exports.CA_CERT_FILE);
+}
 function getCertificateSync(cacheDir, name = 'lensmcp.dev', domains = []) {
-    // Resolve the CA FIRST: loadOrCreateCa mints a fresh CA (and sweeps every OLD-CA leaf) whenever the CA
-    // cert is missing/expired — e.g. after a rebrand renamed the CA file. Doing this BEFORE the leaf-cache read
-    // is what makes a CA change actually take effect: otherwise a stale, old-CA-signed leaf short-circuits the
-    // mint and the rebrand never applies (the bug that needed a manual cache clear). On a normal run the CA is
-    // unchanged, nothing is swept, and the SAN-keyed leaf cache below still fast-paths.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    // Resolve the CA FIRST (machine-level; promotes this workspace's legacy CA on first touch). The current
+    // CA pem then gates the leaf cache below — an issuer pin, see there.
     const forge = require('node-forge');
     fs.mkdirSync(cacheDir, { recursive: true });
-    const ca = loadOrCreateCa(cacheDir, forge);
+    const ca = loadOrCreateCa(forge, cacheDir);
+    const caPem = forge.pki.certificateToPem(ca.cert);
     // The SAN set is part of the cache key: adding a gateway hostname must
     // mint a fresh leaf, not serve a cached one that lacks the new SAN.
     const sanKey = crypto
@@ -55,7 +77,13 @@ function getCertificateSync(cacheDir, name = 'lensmcp.dev', domains = []) {
     try {
         const stat = fs.statSync(leafPath);
         if (Date.now() - stat.ctimeMs < LEAF_MAX_AGE_MS) {
-            return fs.readFileSync(leafPath, 'utf8'); // reached only when the CA was NOT just re-minted (a mint sweeps leaves)
+            const cached = fs.readFileSync(leafPath, 'utf8');
+            // ISSUER PIN: the cached pem embeds the CA it chained to — serve it only when that is the CURRENT
+            // machine CA. With the CA machine-level, a stale leaf in THIS workspace can't be swept by a CA mint
+            // that happened elsewhere (another workspace, or pre-machine-CA code), so the old "a mint sweeps
+            // this dir's leaves" guarantee no longer covers every path; the pin does.
+            if (cached.includes(caPem))
+                return cached;
         }
     }
     catch {
@@ -64,11 +92,13 @@ function getCertificateSync(cacheDir, name = 'lensmcp.dev', domains = []) {
     const pem = createLeafCertificate(forge, ca, name, domains);
     fs.writeFileSync(leafPath, pem);
     // Stale leaves and the pre-1.3.4 self-signed cache just rot here — sweep
-    // them so the dir holds only the active leaf + the CA pair.
+    // them so the dir holds only the active leaf (+ any legacy CA pair, kept
+    // readable for older-code daemons that still anchor to it).
     for (const f of fs.readdirSync(cacheDir)) {
         const stale = (/^_leaf-.*\.pem$/.test(f) && f !== `_leaf-${sanKey}.pem`) ||
             /^_cert.*\.pem$/.test(f) ||
-            /-dev\.crt$/.test(f);
+            /-dev\.crt$/.test(f) ||
+            f === LEGACY_CA_CERT_FILE;
         if (stale) {
             try {
                 fs.unlinkSync(path.join(cacheDir, f));
@@ -78,31 +108,79 @@ function getCertificateSync(cacheDir, name = 'lensmcp.dev', domains = []) {
     }
     return pem;
 }
-/** Absolute path of the trust-once CA certificate inside `cacheDir`. */
-function caCertPath(cacheDir) {
-    return path.join(cacheDir, exports.CA_CERT_FILE);
-}
-/** Mint the local CA if it doesn't exist yet; returns the CA cert path. */
-function ensureCaSync(cacheDir) {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
+/**
+ * Ensure the machine-level CA exists (promoting `legacyCacheDir`'s per-workspace
+ * CA when the machine store is still empty); returns the machine CA cert path.
+ */
+function ensureCaSync(legacyCacheDir) {
     const forge = require('node-forge');
-    fs.mkdirSync(cacheDir, { recursive: true });
-    loadOrCreateCa(cacheDir, forge);
-    return caCertPath(cacheDir);
+    loadOrCreateCa(forge, legacyCacheDir);
+    return caCertPath();
 }
-function loadOrCreateCa(cacheDir, forge) {
-    const certPath = path.join(cacheDir, exports.CA_CERT_FILE);
-    const keyPath = path.join(cacheDir, CA_KEY_FILE);
+/** Read a CA pair from `dir`; undefined when absent, unreadable, or too close to expiry to reuse. */
+function readCaPair(dir, forge) {
     try {
-        const cert = forge.pki.certificateFromPem(fs.readFileSync(certPath, 'utf8'));
-        const key = forge.pki.privateKeyFromPem(fs.readFileSync(keyPath, 'utf8'));
+        const cert = forge.pki.certificateFromPem(fs.readFileSync(path.join(dir, exports.CA_CERT_FILE), 'utf8'));
+        const key = forge.pki.privateKeyFromPem(fs.readFileSync(path.join(dir, CA_KEY_FILE), 'utf8'));
         if (cert.validity.notAfter.getTime() - Date.now() > CA_MIN_REMAINING_MS) {
             return { cert, key };
         }
     }
     catch {
-        /* no CA yet (or unreadable) — mint one */
+        /* absent or unreadable */
+    }
+    return undefined;
+}
+function loadOrCreateCa(forge, promoteFromDir) {
+    const dir = caDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const existing = readCaPair(dir, forge);
+    if (existing)
+        return existing;
+    // Files present but unusable (expired / half-written) — clear them so the `wx` claim below can win.
+    // Rotation this races is a once-per-decade event; last write wins is fine at dev grade.
+    for (const f of [CA_KEY_FILE, exports.CA_CERT_FILE]) {
+        try {
+            fs.unlinkSync(path.join(dir, f));
+        }
+        catch { /* absent */ }
+    }
+    // Candidate pair: PROMOTE the pre-machine-CA workspace pair when one exists — the exact cert the user
+    // already trusted in the keychain simply becomes the machine CA (no new sudo prompt). The workspace copy
+    // stays in place for any older-code daemon still anchoring to it. Otherwise mint fresh.
+    const promoted = promoteFromDir && promoteFromDir !== dir ? readCaPair(promoteFromDir, forge) : undefined;
+    const pair = promoted ?? mintCa(forge);
+    // Atomic claim on the KEY file (`wx`): concurrent daemons can race the first-ever machine resolution;
+    // exactly one pair may land on disk. The winner writes the cert right after; a loser adopts the winner's
+    // pair (bounded wait for that cert write).
+    try {
+        fs.writeFileSync(path.join(dir, CA_KEY_FILE), forge.pki.privateKeyToPem(pair.key), { mode: 0o600, flag: 'wx' });
+    }
+    catch (e) {
+        if (e.code !== 'EEXIST')
+            throw e;
+        const winner = spinReadCaPair(dir, forge);
+        if (winner)
+            return winner;
+        throw new Error(`machine dev CA at ${dir} is claimed but unreadable — remove the directory and retry`, { cause: e });
     }
+    fs.writeFileSync(path.join(dir, exports.CA_CERT_FILE), forge.pki.certificateToPem(pair.cert));
+    if (promoted) {
+        console.log(`[ssl] promoted the existing workspace dev CA to the machine store (${dir}) — keychain trust carries over.`);
+    }
+    return pair;
+}
+/** Bounded sync wait for a concurrent claimer's cert write to land (claim→cert is two writes apart). */
+function spinReadCaPair(dir, forge) {
+    const deadline = Date.now() + 2000;
+    for (;;) {
+        const pair = readCaPair(dir, forge);
+        if (pair || Date.now() >= deadline)
+            return pair;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25); // sync 25ms sleep
+    }
+}
+function mintCa(forge) {
     const keys = forge.pki.rsa.generateKeyPair(2048);
     const cert = forge.pki.createCertificate();
     cert.publicKey = keys.publicKey;
@@ -123,19 +201,6 @@ function loadOrCreateCa(cacheDir, forge) {
         { name: 'subjectKeyIdentifier' },
     ]);
     cert.sign(keys.privateKey, forge.md.sha256.create());
-    fs.writeFileSync(certPath, forge.pki.certificateToPem(cert));
-    fs.writeFileSync(keyPath, forge.pki.privateKeyToPem(keys.privateKey), { mode: 0o600 });
-    // A freshly-minted CA invalidates every cached LEAF (they were signed by the OLD CA) — sweep them so the
-    // next getCertificateSync re-mints against THIS CA (otherwise the SAN-keyed leaf cache serves a stale,
-    // old-CA-signed cert). Also drop the legacy `davnx-local-ca.crt` so the lensmcp rebrand leaves nothing behind.
-    for (const f of fs.readdirSync(cacheDir)) {
-        if (/^_leaf-.*\.pem$/.test(f) || f === LEGACY_CA_CERT_FILE) {
-            try {
-                fs.unlinkSync(path.join(cacheDir, f));
-            }
-            catch { /* best effort */ }
-        }
-    }
     return { cert, key: keys.privateKey };
 }
 function createLeafCertificate(forge, ca, name, domains, ttlDays = 30) {

package/executors/gateway/runtime/control.d.ts

@@ -6,8 +6,9 @@ export interface ControlServerDeps {
     rt: GatewayRuntime;
     /** Reap a fragment's spawned devservers when it unregisters (the svcLayer's `killSpawned`). */
     killService: (svc: WorkspaceFragment['services'][number], reason: string) => void;
-    /** Hooks so the daemon can host/tear-down a workspace's dashboard around the route merge (P3d). */
-    onRegister?: (fragment: WorkspaceFragment) => void;
+    /** Hooks so the daemon can host/tear-down a workspace's dashboard around the route merge (P3d).
+     *  `onRegister` may be async (port probing) — the register handler AWAITS it before the rebuild. */
+    onRegister?: (fragment: WorkspaceFragment) => void | Promise<void>;
     onUnregister?: (fragment: WorkspaceFragment) => void;
 }
 export interface ControlServer {

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

@@ -1 +1 @@
-{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/control.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,+GAA+G;AAC/G,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,cAAc,CAAC;IACnB,+FAA+F;IAC/F,WAAW,EAAE,CAAC,GAAG,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAClF,mGAAmG;IACnG,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnD,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAsBD;qFACqF;AACrF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAwEzE"}
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/control.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,+GAA+G;AAC/G,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,cAAc,CAAC;IACnB,+FAA+F;IAC/F,WAAW,EAAE,CAAC,GAAG,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAClF;wGACoG;IACpG,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAsBD;qFACqF;AACrF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAwEzE"}

package/executors/gateway/runtime/control.js

@@ -90,7 +90,7 @@ function startControlServer(deps) {
                     const { routes, services } = (0, discovery_1.discoverRoutes)(body.root, body.projects ?? {}, undefined, body.wsKey);
                     const fragment = { wsKey: body.wsKey, root: body.root, routes, services };
                     rt.registry.register(fragment);
-                    deps.onRegister?.(fragment); // hosts the dashboard + APPENDS its route to the fragment BEFORE the rebuild
+                    await deps.onRegister?.(fragment); // hosts the dashboard + APPENDS its route to the fragment BEFORE the rebuild
                     rt.rebuildRoutes();
                     return send(res, 200, { ok: true, wsKey: body.wsKey, routes: routes.length, services: services.length, workspaces: rt.registry.keys() });
                 }

package/executors/gateway/runtime/lens-children.d.ts

@@ -2,22 +2,31 @@ import { type SpawnChild } from '@lensmcp/nx-plugin/lens-frontend';
 import type { WorkspaceFragment } from './route-registry';
 import type { GatewayRuntime, GatewayRuntimeOptions } from './types';
 import { type Observability } from './observability';
+/** True when `port` can actually be BOUND on this machine right now. The in-process `used*Ports` sets only
+ *  know what THIS daemon claimed — an ORPHANED child of a CRASHED daemon (or any foreign process) still
+ *  holds its port at the OS level. Routing to such a port serves the WRONG workspace's content: the child
+ *  we spawn crash-loops on EADDRINUSE while the route proxies into the stale squatter (the "tetros
+ *  dashboard redirects to foodguard" bug). */
+export declare function probePortFree(port: number): Promise<boolean>;
 export interface LensChildren {
     spawnManagedChild: SpawnChild;
     /** Boot the dashboard + MCP singletons and every `lens:true` app. Pushes the
-     *  dashboard route onto `rt.routes` — MUST run before TLS SAN derivation. */
-    bootSingletonsAndApps(): void;
+     *  dashboard route onto `rt.routes` — MUST run before TLS SAN derivation.
+     *  Async: every claimed port is OS-probed first (an orphan may hold it). */
+    bootSingletonsAndApps(): Promise<void>;
     /** Host a REGISTERED workspace's dashboard (P3d): spawn its dashboard child on its OWN events file + a
      *  distinct port, append its `lensmcp.local/<key>` route to its fragment. Returns a reaper (kills the
      *  child WITHOUT auto-heal respawn) for the daemon to call on unregister — or undefined if no bundle. */
-    hostWorkspaceDashboard(fragment: WorkspaceFragment): (() => void) | undefined;
+    hostWorkspaceDashboard(fragment: WorkspaceFragment): Promise<(() => void) | undefined>;
     /** Host a REGISTERED workspace's `lens:true` FRONTEND apps (completes model-A "the daemon hosts
      *  everything"): spawn each app's vite (+ capture) in the workspace's OWN root + event bus, on a
      *  collision-safe port, and point its route target at that port. Returns a reaper for unregister. */
-    hostWorkspaceApps(fragment: WorkspaceFragment): () => void;
+    hostWorkspaceApps(fragment: WorkspaceFragment): Promise<() => void>;
     /** Reap all managed children (called from `stop()`): SIGTERM, a grace window, then SIGKILL any survivor
      *  (vite ignores SIGTERM → would orphan when the daemon exits). Async so `stop()` awaits the escalation. */
     reapAll(): Promise<void>;
 }
-export declare function createLensChildren(rt: GatewayRuntime, obs: Observability, options: GatewayRuntimeOptions): LensChildren;
+export declare function createLensChildren(rt: GatewayRuntime, obs: Observability, options: GatewayRuntimeOptions, deps?: {
+    isPortFree?: (port: number) => Promise<boolean>;
+}): LensChildren;
 //# sourceMappingURL=lens-children.d.ts.map

package/executors/gateway/runtime/lens-children.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lens-children.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/lens-children.ts"],"names":[],"mappings":"AAQA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAuB,MAAM,SAAS,CAAC;AAQ1F,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAM7E,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,UAAU,CAAC;IAC9B;iFAC6E;IAC7E,qBAAqB,IAAI,IAAI,CAAC;IAC9B;;6GAEyG;IACzG,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAC9E;;yGAEqG;IACrG,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAC;IAC3D;gHAC4G;IAC5G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,EAAE,OAAO,EAAE,qBAAqB,GAAG,YAAY,CAiUvH"}
+{"version":3,"file":"lens-children.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/lens-children.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAuB,MAAM,SAAS,CAAC;AAQ1F,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAM7E;;;;8CAI8C;AAC9C,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO5D;AAED,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,UAAU,CAAC;IAC9B;;gFAE4E;IAC5E,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;;6GAEyG;IACzG,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC,CAAC;IACvF;;yGAEqG;IACrG,iBAAiB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IACpE;gHAC4G;IAC5G,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,cAAc,EAClB,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,qBAAqB,EAE9B,IAAI,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GACzD,YAAY,CAgWd"}

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.probePortFree = probePortFree;
 exports.createLensChildren = createLensChildren;
 const tslib_1 = require("tslib");
 /**
@@ -8,6 +9,7 @@ const tslib_1 = require("tslib");
  * EVERY managed child AUTO-HEALS — restarted with exponential backoff when it
  * exits while the gateway is up — and a dead child NEVER kills the cluster.
  */
+const net = tslib_1.__importStar(require("node:net"));
 const path = tslib_1.__importStar(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const lens_frontend_1 = require("@lensmcp/nx-plugin/lens-frontend");
@@ -19,8 +21,24 @@ const observability_1 = require("./observability");
 const HEAL_BASE_MS = 1_500; // first restart delay
 const HEAL_MAX_MS = 30_000; // backoff cap — a true boot-loop settles here, never hot-loops
 const HEAL_HEALTHY_MS = 20_000; // ran at least this long ⇒ a FRESH crash ⇒ reset the backoff budget
-function createLensChildren(rt, obs, options) {
+/** True when `port` can actually be BOUND on this machine right now. The in-process `used*Ports` sets only
+ *  know what THIS daemon claimed — an ORPHANED child of a CRASHED daemon (or any foreign process) still
+ *  holds its port at the OS level. Routing to such a port serves the WRONG workspace's content: the child
+ *  we spawn crash-loops on EADDRINUSE while the route proxies into the stale squatter (the "tetros
+ *  dashboard redirects to foodguard" bug). */
+function probePortFree(port) {
+    return new Promise((resolve) => {
+        const probe = net.createServer();
+        probe.unref();
+        probe.once('error', () => resolve(false));
+        probe.listen(port, () => probe.close(() => resolve(true)));
+    });
+}
+function createLensChildren(rt, obs, options, 
+// Injectable OS-level port probe (unit tests stub it; real ports are machine-dependent).
+deps) {
     const { emit } = obs;
+    const isPortFree = deps?.isPortFree ?? probePortFree;
     const lensChildren = [];
     // Auto-heal bookkeeping per child label: consecutive restart attempts (drives the exponential
     // backoff) so a boot-loop settles instead of hammering, reset once a child has run healthily.
@@ -42,6 +60,18 @@ function createLensChildren(rt, obs, options) {
     // registered workspace whose app declares a port already in use gets offset (vite's --strictPort would
     // otherwise exit-loop). Keyed by the actual bound port.
     const usedAppPorts = new Set();
+    // The FIRST port at/above `desired` that is neither claimed in-process nor held at the OS level (an
+    // orphaned child of a crashed daemon squats its old port — see probePortFree). Claims it in `claimed`.
+    const claimFreePort = async (desired, claimed) => {
+        let port = desired;
+        while (claimed.has(port) || !(await isPortFree(port)))
+            port += 1;
+        claimed.add(port);
+        if (port !== desired) {
+            console.warn(`[gateway] port ${desired} is unavailable (another process holds it — an orphan from a crashed gateway?) — using ${port} instead.`);
+        }
+        return port;
+    };
     // A `SpawnChild` over the gateway's managed-children array — the SAME shape `agent-dev` passes to
     // `spawnLensFrontend`. EVERY gateway-managed child AUTO-HEALS: the dashboard + MCP singletons AND each
     // `lens:true` vite app are restarted when they exit while the gateway is up, with exponential backoff.
@@ -56,7 +86,14 @@ function createLensChildren(rt, obs, options) {
         void optional;
         void respawn; // legacy knobs — auto-heal is now universal (signature kept for compat)
         const spawnedAt = Date.now();
-        const child = (0, node_child_process_1.spawn)(bin, args, { cwd: cwd ?? rt.root, env: { ...process.env, ...(env ?? {}) }, stdio: 'inherit' });
+        // LENSMCP_PARENT_PID: our own bundles (dashboard/MCP) run a ppid watchdog against it and SELF-EXIT when
+        // this gateway dies ungracefully (crash/SIGKILL — reapAll never ran), so they don't orphan and squat
+        // their ports for the next gateway to route into.
+        const child = (0, node_child_process_1.spawn)(bin, args, {
+            cwd: cwd ?? rt.root,
+            env: { ...process.env, ...(env ?? {}), LENSMCP_PARENT_PID: String(process.pid) },
+            stdio: 'inherit',
+        });
         lensChildren.push(child);
         labeledChildren.set(label, child); // the CURRENT handle for this label (a per-workspace dashboard reap targets it)
         // Track a `lens:true` app's vite dev server (label 'vite', or `<ws>:<proj>:vite` for a registered
@@ -115,7 +152,7 @@ function createLensChildren(rt, obs, options) {
         }, Math.min(types_1.POD_STALE_SCAN_MS, 15_000));
         lensSweeper.unref?.();
     };
-    const bootSingletonsAndApps = () => {
+    const bootSingletonsAndApps = async () => {
         const lensApps = [...new Map(rt.routes.filter((r) => r.lens).map((r) => [r.project, r.lens])).values()];
         const wantDashboard = options.dashboard !== false;
         const wantMcp = options.mcp !== false && lensApps.length > 0;
@@ -130,8 +167,11 @@ function createLensChildren(rt, obs, options) {
                 // OWNS its base path (LENSMCP_DASHBOARD_BASE) and history-routes under it, so the
                 // gateway routes pass-through (matchRoute on the prefix; the proxy never strips).
                 const scope = (0, scope_1.readLensScope)(rt.root);
-                const dashboardPort = options.dashboardPort ?? scope.dashboardPort;
-                usedDashboardPorts.add(dashboardPort); // reserve the daemon's own dashboard port so a registered workspace's differs
+                // The per-workspace scoped port (`.lensmcp/config.json` ports.dashboard) unless explicitly
+                // overridden — then OS-probed: an orphaned dashboard from a crashed gateway may still hold it, and
+                // routing there serves ANOTHER workspace's dashboard. Claiming also reserves it in-process so a
+                // registered workspace's dashboard differs.
+                const dashboardPort = await claimFreePort(options.dashboardPort ?? scope.dashboardPort, usedDashboardPorts);
                 const lensHost = options.lensHost ?? 'lensmcp.local';
                 const lensBase = scope.basePath; // e.g. /tetros
                 // Pushed BEFORE the cert SANs are derived (routes.map(r=>r.host)), so lensmcp.local
@@ -172,7 +212,20 @@ function createLensChildren(rt, obs, options) {
             if (app.started)
                 continue;
             app.started = true;
-            usedAppPorts.add(app.port); // claim the daemon's own lens-app ports so a registered workspace offsets off them
+            // Claim the app's port OS-probed (an orphaned vite from a crashed daemon may hold it — vite's
+            // --strictPort would exit-loop while the route proxies into the stale one). On a step-up, point every
+            // route of this project at the ACTUAL port (route objects are shared with the registry fragment, so
+            // the rewrite survives rebuilds — mirrors hostWorkspaceApps).
+            const appPort = await claimFreePort(app.port, usedAppPorts);
+            if (appPort !== app.port) {
+                for (const r of rt.routes) {
+                    if (r.lens?.project === app.project) {
+                        r.lens.port = appPort;
+                        r.target = `http://localhost:${appPort}`;
+                    }
+                }
+                app.port = appPort;
+            }
             try {
                 (0, lens_frontend_1.spawnLensFrontend)({
                     projectRoot: app.projectRoot,
@@ -199,17 +252,15 @@ function createLensChildren(rt, obs, options) {
     // `lensmcp.local/<key>` route on its fragment. The dashboard BUNDLE is the daemon's (rt.root); only the
     // events file + base + port are the registered workspace's. Returns a reaper the control endpoint calls
     // on unregister (marks the label removed so auto-heal won't respawn it, then kills the child).
-    const hostWorkspaceDashboard = (fragment) => {
+    const hostWorkspaceDashboard = async (fragment) => {
         const bundle = (0, lens_frontend_1.findDashboardBundle)(rt.root);
         if (!bundle)
             return undefined;
         const scope = (0, scope_1.readLensScope)(fragment.root);
         const lensHost = options.lensHost ?? 'lensmcp.local';
         const lensBase = scope.basePath; // /<registered key>
-        let port = scope.dashboardPort;
-        while (usedDashboardPorts.has(port))
-            port += 1; // distinct from every other workspace's dashboard
-        usedDashboardPorts.add(port);
+        // Distinct from every other workspace's dashboard AND actually bindable (OS-probed for orphans).
+        const port = await claimFreePort(scope.dashboardPort, usedDashboardPorts);
         const label = `lens-dashboard:${fragment.wsKey}`;
         const eventFile = path.join(fragment.root, '.lensmcp', 'events.jsonl'); // the registered workspace's OWN bus
         removedLabels.delete(label); // a fresh registration after a prior unregister → allow auto-heal again
@@ -250,7 +301,7 @@ function createLensChildren(rt, obs, options) {
     // TARGET to that port so the merged table (rebuilt right after this in the control handler) upstreams
     // correctly. Unique labels (`<ws>:<proj>:vite`) keep auto-heal + the reaper from touching the daemon's own
     // identically-named vites. Returns a reaper the control endpoint calls on unregister.
-    const hostWorkspaceApps = (fragment) => {
+    const hostWorkspaceApps = async (fragment) => {
         // Group a project's (possibly several host) routes so one spawned vite serves them all.
         const byProject = new Map();
         for (const r of fragment.routes) {
@@ -269,11 +320,9 @@ function createLensChildren(rt, obs, options) {
             const lens0 = routes[0].lens;
             if (lens0.started)
                 continue;
-            // Collision-safe port: keep the declared port unless already claimed, else step up.
-            let port = lens0.port;
-            while (usedAppPorts.has(port))
-                port += 1;
-            usedAppPorts.add(port);
+            // Collision-safe port: keep the declared port unless already claimed in-process OR held at the OS
+            // level (an orphaned vite from a crashed daemon), else step up.
+            const port = await claimFreePort(lens0.port, usedAppPorts);
             ports.push(port);
             // Point every route of this project at the actual bound port (all share the one vite).
             for (const r of routes) {

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":"AAWA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAapE,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,iBAAiB,CAAC;AA4C/D;;sGAEsG;AACtG,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBtE;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,CAkRvF"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/lifecycle.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAapE,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,iBAAiB,CAAC;AA8C/D;;sGAEsG;AACtG,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBtE;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,CAkRvF"}

package/executors/gateway/runtime/lifecycle.js

@@ -15,13 +15,14 @@ const fs = tslib_1.__importStar(require("node:fs"));
 const http = tslib_1.__importStar(require("node:http"));
 const path = tslib_1.__importStar(require("node:path"));
 const discovery_1 = require("./discovery");
-const service_keys_1 = require("./service-keys");
 const types_1 = require("./types");
 /**
  * The east-west env a pod needs to call ANOTHER service's `internal.<host>` route (memberships, settings,
  * plan): (1) its OWN per-service key — presented as `x-api-key`; the gateway maps it back to the caller and
- * stamps `x-api-key-id` (a service can't forge another's identity). (2) `NODE_EXTRA_CA_CERTS` = the dev
- * gateway's self-signed CA, so the pod's OUTBOUND `fetch('https://internal.<host>')` clears TLS. Without
+ * stamps `x-api-key-id` (a service can't forge another's identity). (2) `NODE_EXTRA_CA_CERTS` = the
+ * MACHINE-LEVEL dev CA (`~/.lensmcp/ca`), so the pod's OUTBOUND `fetch('https://internal.<host>')` clears
+ * TLS — and keeps clearing it across daemon handovers, since every daemon on the machine signs with that
+ * same anchor (a per-workspace path here once broke pods that outlived a guest→own-daemon switch). Without
  * these the call fails (connect/TLS or a gateway 401) and tenant-token minting can't resolve the role.
  * NOT `INTERNAL_API_KEY`/`LENSMCP_INTERNAL_TOKEN` (those would flip ON the inbound gateway-trust guard) —
  * a DEDICATED name a service opts into for OUTBOUND only, leaving inbound dev-standalone behavior unchanged.
@@ -34,7 +35,7 @@ function eastWestEnv(rt, project) {
     if (rt.https) {
         // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy like server.ts (cert deps)
         const basicSsl = require('../../../basic-ssl');
-        const caPath = basicSsl.caCertPath((0, service_keys_1.gatewayCacheDir)(rt.root));
+        const caPath = basicSsl.caCertPath();
         if (fs.existsSync(caPath))
             env.NODE_EXTRA_CA_CERTS = caPath;
     }

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

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/proxy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,cAAc,EAAW,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8BhD,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACxH,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACnI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI,GAAG,IAAI,CAAC;IACrG,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC,KAAK,GAAG,OAAO,YAAY,EAAE,KAAK,CAAC;IACzE,aAAa,IAAI,IAAI,CAAC;IACtB,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,GAAG,UAAU,CAgTtG"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/proxy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,KAAK,MAAM,MAAM,aAAa,CAAC;AAG3C,OAAO,KAAK,EAAE,cAAc,EAAW,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8BhD,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACxH,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IACnI,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI,GAAG,IAAI,CAAC;IACrG,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC,KAAK,GAAG,OAAO,YAAY,EAAE,KAAK,CAAC;IACzE,aAAa,IAAI,IAAI,CAAC;IACtB,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,GAAG,UAAU,CAsTtG"}

package/executors/gateway/runtime/proxy.js

@@ -110,6 +110,11 @@ function createProxy(rt, obs, svcLayer) {
                 agent: agentForTarget(target),
             };
         }
+        // An h2 ServerResponse whose stream faults (a RST from the client, a
+        // `res.destroy(err)` below) emits 'error'; UNHANDLED, that throws and can
+        // escalate to tear the whole h2 session down — the very "burst" symptom.
+        // A no-op listener keeps the fault local to THIS stream. (Harmless on h1.)
+        res.on('error', () => { });
         const upstreamReq = mod.request(opts, (upstreamRes) => {
             cbs.onResponse();
             if (res.headersSent || res.writableEnded || res.destroyed) {

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/server.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAK/D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAkB,qBAAqB,EAAe,KAAK,EAAE,MAAM,SAAS,CAAC;AA0BxH;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,KAAK,EAAE,GAAG,gBAAgB,CA4ChF;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAkPxB"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/server.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAK/D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAkB,qBAAqB,EAAe,KAAK,EAAE,MAAM,SAAS,CAAC;AA0BxH;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,KAAK,EAAE,GAAG,gBAAgB,CA4ChF;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAmRxB"}

package/executors/gateway/runtime/server.js

@@ -189,13 +189,13 @@ async function startGateway(options, context) {
         controlServer = (0, control_1.startControlServer)({
             rt,
             killService: (svc, reason) => svcLayer.killSpawned(svc, reason),
-            onRegister: (fragment) => {
+            onRegister: async (fragment) => {
                 // Host the registered workspace's dashboard AND its lens FRONTEND apps (both spawned in ITS root/bus;
                 // the dashboard appends its lensmcp.local/<key> route + the apps rewrite their route targets to the
-                // actual bound port — all BEFORE the control handler's rebuild). The cert re-mint happens in
-                // rebuildRoutes (called by the control handler right after this), once the full table is live.
-                const reapDash = lens.hostWorkspaceDashboard(fragment);
-                const reapApps = lens.hostWorkspaceApps(fragment);
+                // actual bound port — all BEFORE the control handler's rebuild, which AWAITS this). The cert re-mint
+                // happens in rebuildRoutes (called by the control handler right after this), once the full table is live.
+                const reapDash = await lens.hostWorkspaceDashboard(fragment);
+                const reapApps = await lens.hostWorkspaceApps(fragment);
                 workspaceReapers.set(fragment.wsKey, () => { reapDash?.(); reapApps(); });
             },
             onUnregister: (fragment) => {
@@ -249,7 +249,7 @@ async function startGateway(options, context) {
     const sweeper = svcLayer.startSweeper();
     // --- lens-mode children: dashboard + MCP singletons + `lens:true` apps ------
     // MUST run before TLS — it pushes the dashboard route, which joins the cert SANs.
-    lens.bootSingletonsAndApps();
+    await lens.bootSingletonsAndApps();
     // Eager services boot with the gateway.
     for (const svc of services) {
         if (svc.decl.eager)
@@ -267,7 +267,7 @@ async function startGateway(options, context) {
         // below) automatically includes a newly-registered workspace's hostnames.
         mintCert = () => basicSsl.getCertificateSync(cacheDir, 'gateway', rt.routes.map((r) => r.host).filter((h) => !!h));
         pem = mintCert();
-        caPath = basicSsl.caCertPath(cacheDir);
+        caPath = basicSsl.caCertPath(); // machine-level (~/.lensmcp/ca) — one anchor for every daemon
     }
     const servers = [];
     const boundPorts = [];
@@ -286,10 +286,44 @@ async function startGateway(options, context) {
         // because node-http-proxy emits connection-specific headers that are illegal in h2.
         const server = pem
             ? // eslint-disable-next-line @typescript-eslint/no-require-imports
-                require('node:http2').createSecureServer({ key: pem, cert: pem, allowHTTP1: true }, (req, res) => handler(req, res))
+                require('node:http2').createSecureServer({
+                    key: pem,
+                    cert: pem,
+                    allowHTTP1: true,
+                    // A full Vite dev-app reload streams TENS of MB of transformed ESM
+                    // over ONE h2 session. Node's default `maxSessionMemory` is 10 MB —
+                    // cross it and the session RSTs its streams / sends GOAWAY, which the
+                    // browser reports as a BURST of ERR_HTTP2_PROTOCOL_ERROR (every
+                    // in-flight module fails at the same instant). Raise the ceiling and
+                    // the per-stream/peer limits to dev-front-door proportions.
+                    maxSessionMemory: 512,
+                    settings: { maxConcurrentStreams: 512 },
+                    peerMaxConcurrentStreams: 512,
+                }, (req, res) => handler(req, res))
             : http.createServer(handler);
         server.on('upgrade', upgrade);
         server.on('error', (err) => console.error(`[gateway] port ${port}: ${err.code}`));
+        // h2 SESSION resilience: without a `sessionError` handler ANY session-level
+        // fault (a client GOAWAY mid-burst, a flood-protection trip, a decode error)
+        // is unhandled → Node tears the session down, failing EVERY sibling stream at
+        // once. Handle it so ONE bad session logs + dies alone, never throwing and
+        // never taking the process (or other clients' sessions) with it. `session`
+        // errors are surfaced BOTH per-session and (unhandled) as `sessionError`.
+        const isH2 = pem != null;
+        if (isH2) {
+            const h2 = server;
+            h2.on('session', (session) => {
+                session.on('error', (err) => {
+                    const code = err.code ?? err.message;
+                    console.warn(`[gateway] h2 session error (${code}) — dropping this session only`);
+                    if (!session.destroyed)
+                        session.destroy();
+                });
+            });
+            h2.on('sessionError', (err) => {
+                console.warn(`[gateway] h2 sessionError: ${err.code ?? err.message}`);
+            });
+        }
         await new Promise((resolve) => {
             server.listen(port, () => {
                 const actual = server.address()?.port ?? port;

package/executors/gateway/schema.d.ts

@@ -11,7 +11,8 @@ export interface GatewayExecutorSchema {
   dashboard?: boolean;
   /** Spawn the single MCP server as a gateway-managed child when a `lens:true` app exists. Default true. */
   mcp?: boolean;
-  /** Port the managed dashboard listens on (proxied behind lens.<baseDomain>). Default 4321. */
+  /** Port the managed dashboard listens on (proxied behind lens.<baseDomain>).
+   *  Default: the workspace scope's dashboard port (`.lensmcp/config.json` `ports.dashboard`), else 4321. */
   dashboardPort?: number;
   /** Override the dashboard hostname. Default lens.<baseDomain>. */
   lensHost?: string;

package/executors/gateway/schema.json

@@ -37,8 +37,7 @@
     },
     "dashboardPort": {
       "type": "number",
-      "default": 4321,
-      "description": "Port the gateway-managed dashboard listens on (proxied behind lens.<baseDomain>). Default 4321."
+      "description": "Port the gateway-managed dashboard listens on (proxied behind lens.<baseDomain>). When omitted, the workspace's `.lensmcp/config.json` `ports.dashboard` wins (falling back to 4321) — a schema default here would OVERRIDE that per-workspace port for every workspace, colliding multi-workspace dashboards onto one port."
     },
     "lensHost": {
       "type": "string",

package/executors/serve/schema.d.ts

@@ -50,4 +50,8 @@ export interface ServeExecutorSchema {
   gateway?: GatewayConfig;
   /** Plain-http listener straight to the children - service-to-service calls, no gateway middleware. */
   internalPort?: number;
+  /** Inspector base port: pod slot N -> debugPort+N, workers -> debugPort+20+i. Env fallback: LENSMCP_DEBUG_PORT. */
+  debugPort?: number;
+  /** Tee pod/worker logs (ANSI-stripped) to this file for IDE tailing (WebStorm Logs tab). Env fallback: LENSMCP_LOG_FILE. */
+  logFile?: string;
 }

package/executors/serve/schema.json

@@ -186,6 +186,14 @@
     "internalPort": {
       "type": "number",
       "description": "Plain-http listener that proxies straight to this service children — no gateway routes, no gateway middleware (JWT). For service-to-service calls, mirroring cluster-internal networking."
+    },
+    "debugPort": {
+      "type": "number",
+      "description": "Open a Node inspector in every pod (127.0.0.1 only): pod at slot N listens on debugPort+N, workers on debugPort+20+i. The printed 'Debugger listening on ws://…' line is click-to-attach in WebStorm/VS Code run consoles; ports are stable across crash-respawns, and hot reloads swap in-process so an attached debug session survives rebuilds. Also settable via the LENSMCP_DEBUG_PORT env var (this option wins). Give each service a distinct base. Without it, POST /webpack/debug on the running devserver opens inspectors on demand — no restart."
+    },
+    "logFile": {
+      "type": "string",
+      "description": "Tee every pod/worker log line (ANSI-stripped) to this file, relative to workspace root (e.g. '.lensmcp/logs/my-service.log'). Point an IDE at it — WebStorm: Run/Debug configuration → Logs tab — to see live service logs next to the debugger. Truncated once per serve run. Also settable via the LENSMCP_LOG_FILE env var (this option wins)."
     }
   },
   "required": [

package/executors/serve/serve.impl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.impl.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/serve/serve.impl.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAKpD,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC5C,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,iBAAgB,aAAa,CAC3B,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgQxD;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"serve.impl.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/serve/serve.impl.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAKpD,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC5C,CAAC;CACH;AAED;;;;;;;;GAQG;AACH,iBAAgB,aAAa,CAC3B,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,eAAe,GACvB,cAAc,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6RxD;AAED,eAAe,aAAa,CAAC"}

package/executors/serve/serve.impl.js

@@ -51,6 +51,21 @@ async function* serveExecutor(options, context) {
         serviceName = options.serviceName;
     }
     const servePrefix = options.servePrefix ?? '';
+    // Debug base port: pod #slot opens its inspector on debugPort+slot (workers on
+    // debugPort+20+i). Option wins over the LENSMCP_DEBUG_PORT env var so per-project
+    // config can give each service a distinct base in cluster mode. Even without it,
+    // POST /webpack/debug on the running devserver opens inspectors on demand.
+    const debugPort = options.debugPort ?? (Number(process.env.LENSMCP_DEBUG_PORT) || undefined);
+    // Log tee: every pod/worker line is also appended (ANSI-stripped) to this file so
+    // an IDE can tail it — WebStorm: Run/Debug configuration → Logs tab. Truncated
+    // here once per `nx serve` run; devserver crash-respawns keep appending.
+    const logFile = options.logFile
+        ? path.resolve(workspaceRoot, options.logFile)
+        : process.env.LENSMCP_LOG_FILE || undefined;
+    if (logFile) {
+        fs.mkdirSync(path.dirname(logFile), { recursive: true });
+        fs.writeFileSync(logFile, '');
+    }
     // Resolve gateway middleware
     let gatewayMiddlewarePath;
     let gatewayConfigJson;
@@ -144,6 +159,8 @@ async function* serveExecutor(options, context) {
                 ...(options.gateway?.https && { GATEWAY_HTTPS: "1" }),
                 ...(options.gateway?.extraPorts?.length && { GATEWAY_EXTRA_PORTS: JSON.stringify(options.gateway.extraPorts) }),
                 ...(options.internalPort && { INTERNAL_PORT: String(options.internalPort) }),
+                ...(debugPort && { LENSMCP_DEBUG_PORT: String(debugPort) }),
+                ...(logFile && { LENSMCP_LOG_FILE: logFile }),
                 ...((options.workers?.length) && { WORKERS: JSON.stringify(options.workers.map(w => w.name)) }),
             },
             stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
@@ -162,6 +179,15 @@ async function* serveExecutor(options, context) {
             }, 1500).unref?.();
         });
         console.log(`[serve] Devserver started on port ${port} (service: ${serviceName}${servePrefix ? `, prefix: /${servePrefix}` : ''})`);
+        if (debugPort) {
+            console.log(`[serve] Debug: pod inspectors on 127.0.0.1:${debugPort}+ — click the "Debugger listening" link in the console, or attach WebStorm (Attach to Node.js/Chrome) to port ${debugPort}`);
+        }
+        else {
+            console.log(`[serve] Debug on demand: POST http://localhost:${port}/webpack/debug (optionally ?port=<base>) opens pod inspectors without a restart`);
+        }
+        if (logFile) {
+            console.log(`[serve] Logs teed to ${logFile} — tail it in WebStorm via Run/Debug configuration → Logs tab`);
+        }
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     function _notifyDevServerReload() {

package/executors/trust/trust.impl.d.ts

@@ -21,10 +21,12 @@ interface ExecutorContext {
  * `trust` executor — one idempotent command that makes the HTTPS dev gateway
  * green in real browsers:
  *
- *   1. mints the local dev CA if missing (same CA the gateway serves),
- *   2. adds it ONCE to the macOS System keychain (`sudo security
- *      add-trusted-cert`) — every leaf rotation / new hostname then chains
- *      to it with no interstitial,
+ *   1. resolves the MACHINE-LEVEL dev CA (`~/.lensmcp/ca`) — minting it if
+ *      missing, or promoting this workspace's legacy per-workspace CA so
+ *      existing keychain trust carries over,
+ *   2. adds it ONCE PER MACHINE to the macOS System keychain (`sudo security
+ *      add-trusted-cert`) — every leaf rotation / new hostname / new workspace
+ *      then chains to it with no interstitial,
  *   3. writes BOTH `/etc/hosts` families (`127.0.0.1` + `::1`) for every
  *      gateway route hostname — the missing `::1` line is what sends `.local`
  *      AAAA lookups to Bonjour/mDNS and costs ~5s per resolution,

package/executors/trust/trust.impl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust.impl.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/trust/trust.impl.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE;QACvB,QAAQ,EAAE,MAAM,CACd,MAAM,EACN;YACE,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;gBAAE,OAAO,CAAC,EAAE;oBAAE,OAAO,CAAC,EAAE;wBAAE,MAAM,CAAC,EAAE,KAAK,CAAC;4BAAE,IAAI,CAAC,EAAE,MAAM,CAAA;yBAAE,CAAC,CAAA;qBAAE,CAAA;iBAAE,CAAA;aAAE,CAAC,CAAC;SAC7F,CACF,CAAC;KACH,CAAC;CACH;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAA8B,aAAa,CACzC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAqF/B;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CAmC7F"}
+{"version":3,"file":"trust.impl.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/trust/trust.impl.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE;QACvB,QAAQ,EAAE,MAAM,CACd,MAAM,EACN;YACE,IAAI,EAAE,MAAM,CAAC;YACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;gBAAE,OAAO,CAAC,EAAE;oBAAE,OAAO,CAAC,EAAE;wBAAE,MAAM,CAAC,EAAE,KAAK,CAAC;4BAAE,IAAI,CAAC,EAAE,MAAM,CAAA;yBAAE,CAAC,CAAA;qBAAE,CAAA;iBAAE,CAAA;aAAE,CAAC,CAAC;SAC7F,CACF,CAAC;KACH,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAA8B,aAAa,CACzC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA+F/B;AAeD,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,EAAE,CAmC7F"}

package/executors/trust/trust.impl.js

@@ -11,10 +11,12 @@ const basic_ssl_1 = require("../../basic-ssl");
  * `trust` executor — one idempotent command that makes the HTTPS dev gateway
  * green in real browsers:
  *
- *   1. mints the local dev CA if missing (same CA the gateway serves),
- *   2. adds it ONCE to the macOS System keychain (`sudo security
- *      add-trusted-cert`) — every leaf rotation / new hostname then chains
- *      to it with no interstitial,
+ *   1. resolves the MACHINE-LEVEL dev CA (`~/.lensmcp/ca`) — minting it if
+ *      missing, or promoting this workspace's legacy per-workspace CA so
+ *      existing keychain trust carries over,
+ *   2. adds it ONCE PER MACHINE to the macOS System keychain (`sudo security
+ *      add-trusted-cert`) — every leaf rotation / new hostname / new workspace
+ *      then chains to it with no interstitial,
  *   3. writes BOTH `/etc/hosts` families (`127.0.0.1` + `::1`) for every
  *      gateway route hostname — the missing `::1` line is what sends `.local`
  *      AAAA lookups to Bonjour/mDNS and costs ~5s per resolution,
@@ -25,6 +27,8 @@ const basic_ssl_1 = require("../../basic-ssl");
  * Run it from a terminal: sudo prompts for your password inline.
  */
 async function trustExecutor(options, context) {
+    // The workspace cert-cache dir is only the PROMOTION SOURCE now: ensureCaSync resolves the machine-level
+    // CA (~/.lensmcp/ca), adopting a pre-existing per-workspace CA from here so its keychain trust survives.
     const cacheDir = path.join(context.root, 'node_modules', '.cache', 'davnx-webpack');
     const caPath = (0, basic_ssl_1.ensureCaSync)(cacheDir);
     // HOSTS-ONLY mode (set by the CLI when this workspace is a GUEST of a shared daemon): the daemon serves
@@ -44,10 +48,14 @@ async function trustExecutor(options, context) {
         return { success: true };
     }
     // --- 1) CA into the System keychain (skip when already there, or in hosts-only/guest mode) -----------
+    // "Already there" must match by FINGERPRINT, not CN: every workspace mints its own CA under the same
+    // "lensmcp local dev CA" name, so a same-named cert from another workspace (or a pre-rotation stale one)
+    // would otherwise satisfy a name lookup while the CA this gateway actually serves stays untrusted —
+    // the browser interstitial with a green-looking trust log.
+    const fingerprint = caSha256Fingerprint(caPath);
     const present = hostsOnly ||
-        (0, node_child_process_1.spawnSync)('security', ['find-certificate', '-c', 'lensmcp local dev CA', '/Library/Keychains/System.keychain'], {
-            stdio: 'ignore',
-        }).status === 0;
+        (fingerprint !== undefined &&
+            (0, node_child_process_1.spawnSync)('security', ['find-certificate', '-a', '-c', 'lensmcp local dev CA', '-Z', '/Library/Keychains/System.keychain'], { encoding: 'utf8' }).stdout?.includes(fingerprint) === true);
     if (hostsOnly) {
         console.log('[trust] hosts-only: a shared daemon serves TLS with its own CA — skipping the keychain step.');
     }
@@ -105,6 +113,19 @@ async function trustExecutor(options, context) {
     }
     return { success: true };
 }
+/**
+ * SHA-256 of the CA file as uppercase hex without separators — the exact format
+ * `security find-certificate -Z` prints ("SHA-256 hash: <hex>"), so the caller
+ * can substring-match the keychain listing. `undefined` when openssl can't read
+ * the file (caller then falls through to add-trusted-cert, which is idempotent).
+ */
+function caSha256Fingerprint(caPath) {
+    const r = (0, node_child_process_1.spawnSync)('openssl', ['x509', '-in', caPath, '-noout', '-fingerprint', '-sha256'], { encoding: 'utf8' });
+    if (r.status !== 0 || !r.stdout)
+        return undefined;
+    const hex = r.stdout.split('=')[1]?.replaceAll(':', '').trim().toUpperCase();
+    return hex && /^[0-9A-F]{64}$/.test(hex) ? hex : undefined;
+}
 function collectHosts(options, context) {
     const found = [];
     // 1) This project's embedded gateway routes (single-service setups).

package/main.devserver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.devserver.d.ts","sourceRoot":"","sources":["../../../libs/cluster/src/main.devserver.ts"],"names":[],"mappings":"AA8EA,MAAM,WAAW,YAAY;IAC3B,6FAA6F;IAC7F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"main.devserver.d.ts","sourceRoot":"","sources":["../../../libs/cluster/src/main.devserver.ts"],"names":[],"mappings":"AA+EA,MAAM,WAAW,YAAY;IAC3B,6FAA6F;IAC7F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/main.devserver.js

@@ -25,6 +25,7 @@ const node_child_process_1 = require("node:child_process");
 const http = tslib_1.__importStar(require("node:http"));
 const readline = tslib_1.__importStar(require("node:readline"));
 const inspector = tslib_1.__importStar(require("node:inspector"));
+const util = tslib_1.__importStar(require("node:util"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const httpProxy = require('http-proxy');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -150,6 +151,31 @@ function debounce(fn, ms) {
 // CHILD MODE (APP_RUNNER=1) — loads bundle, bootstraps NestJS app, listens on socket
 // ===================================================================================
 if (process.env.APP_RUNNER === '1') {
+    // Debug: open the inspector on the port the parent allocated (serve `debugPort`
+    // option / LENSMCP_DEBUG_PORT base + pod slot) and report the ws URL up via IPC.
+    // inspector.open() itself prints the native "Debugger listening on ws://…" line,
+    // which WebStorm/VS Code run consoles turn into a one-click attach link. The
+    // matching inspector.close() on shutdown already lives below.
+    const openInspector = (port) => {
+        if (!inspector.url()) {
+            try {
+                inspector.open(port, '127.0.0.1', false);
+            }
+            catch (err) {
+                console.warn(`[child] inspector.open(${port}) failed (port taken by another devserver?) — falling back to a random port:`, err.message);
+                try {
+                    inspector.open(0, '127.0.0.1', false);
+                }
+                catch { /* no inspector at all — pod still serves, just undebuggable */ }
+            }
+        }
+        const url = inspector.url();
+        if (url && process.send)
+            process.send({ type: 'inspector-url', url });
+    };
+    const CHILD_DEBUG_PORT = Number(process.env.CHILD_DEBUG_PORT || '');
+    if (Number.isInteger(CHILD_DEBUG_PORT) && CHILD_DEBUG_PORT > 1024)
+        openInspector(CHILD_DEBUG_PORT);
     // Zero-touch instrumentation: load BEFORE the app bundle so the require
     // hook sees pg/ioredis/bullmq/@nestjs/core on their first load, builtins
     // (fs/net/exec) are tapped, NestFactory.create grafts the lens module, and
@@ -273,6 +299,13 @@ if (process.env.APP_RUNNER === '1') {
         process.on('message', async (msg) => {
             if (!msg || typeof msg !== 'object')
                 return;
+            // On-demand debugging (POST /webpack/debug): open the inspector NOW, in the
+            // running pod — no restart, app state intact. Already open → just re-report.
+            if (msg.type === 'debug-open') {
+                const port = Number(msg.port);
+                openInspector(Number.isInteger(port) && port > 1024 ? port : 0);
+                return;
+            }
             if (msg.type === 'reload') {
                 try {
                     await swapNow();
@@ -323,6 +356,67 @@ else {
     ];
     const RESET = '\x1b[0m';
     const CHILD_COUNT = Math.max(1, Number(process.env.CHILD_COUNT || 1));
+    // Debug base port (serve `debugPort` option / LENSMCP_DEBUG_PORT env): pod at
+    // slot S opens its inspector on base+S, workers on base+WORKER_DEBUG_PORT_OFFSET+i.
+    // Unset/0 → no inspectors at boot; POST /webpack/debug can still turn debugging on
+    // at runtime (mutating this base — sticky, so respawned pods stay debuggable).
+    // Each service needs its OWN base — two services sharing one base would race for
+    // the same ports (loser warns and runs undebuggable).
+    let debugBasePort = (() => {
+        const n = Number(process.env.LENSMCP_DEBUG_PORT || '');
+        return Number.isInteger(n) && n > 1024 ? n : 0;
+    })();
+    const WORKER_DEBUG_PORT_OFFSET = 20;
+    // Log tee (serve `logFile` option / LENSMCP_LOG_FILE env): every pod/worker line
+    // is ALSO appended, ANSI-stripped, to this file — so an IDE can tail it (WebStorm:
+    // run config → Logs tab) while the service itself runs anywhere (terminal, gateway).
+    const LOG_FILE = process.env.LENSMCP_LOG_FILE || '';
+    const logFileStream = LOG_FILE
+        ? (() => {
+            try {
+                fs.mkdirSync(path.dirname(LOG_FILE), { recursive: true });
+                return fs.createWriteStream(LOG_FILE, { flags: 'a' });
+            }
+            catch (err) {
+                console.warn(`[parent] cannot open log file ${LOG_FILE}:`, err.message);
+                return null;
+            }
+        })()
+        : null;
+    // eslint-disable-next-line no-control-regex
+    const ANSI_RE = /\x1b\[[0-9;]*m/g;
+    // ---------- Log hub ----------
+    // Every pod/worker line (and the parent's own lifecycle lines) fans out to:
+    //  • the terminal (unchanged),
+    //  • a ring buffer + live HTTP subscribers — GET /webpack/logs, which is what
+    //    `lensmcp logs <service>` attaches to from any terminal (human or agent),
+    //  • the optional LENSMCP_LOG_FILE tee (ANSI-stripped) for IDE Logs tabs.
+    const LOG_BUFFER_MAX = 2000;
+    const logBuffer = [];
+    const logSubscribers = new Set();
+    function emitLogLine(text) {
+        logBuffer.push(text);
+        if (logBuffer.length > LOG_BUFFER_MAX)
+            logBuffer.splice(0, logBuffer.length - LOG_BUFFER_MAX);
+        logFileStream?.write(text.replace(ANSI_RE, ''));
+        for (const sub of logSubscribers) {
+            try {
+                sub.res.write(sub.plain ? text.replace(ANSI_RE, '') : text);
+            }
+            catch {
+                logSubscribers.delete(sub);
+            }
+        }
+    }
+    // The parent's own console lines (ready/respawn/Debugger listening/proxy errors)
+    // belong in the stream too — mirror console.* into the hub.
+    for (const level of ['log', 'info', 'warn', 'error']) {
+        const orig = console[level].bind(console);
+        console[level] = (...args) => {
+            orig(...args);
+            emitLogLine(args.map((a) => (typeof a === 'string' ? a : util.inspect(a))).join(' ') + '\n');
+        };
+    }
     const colorFor = (id) => {
         return COLORS[(id - 1) % COLORS.length];
     };
@@ -361,6 +455,7 @@ else {
             const dest = kind === 'stdout' ? process.stdout : process.stderr;
             const log = isJsonLog(line) ? prettyLog(line) : `${line}\n`;
             dest.write(`${tag}${log}`);
+            emitLogLine(`${tag}${log}`);
         };
         const attach = (stream, kind) => {
             if (!stream)
@@ -381,6 +476,14 @@ else {
         if (!publicPort)
             publicPort = 9090;
         const children = [];
+        const usedDebugSlots = new Set();
+        function allocDebugSlot() {
+            let slot = 0;
+            while (usedDebugSlots.has(slot))
+                slot++;
+            usedDebugSlots.add(slot);
+            return slot;
+        }
         let nextId = 1;
         let rrIndex = 0;
         let shuttingDown = false; // set by the parent's signal handler
@@ -406,17 +509,21 @@ else {
             if (__filename.endsWith('.ts')) {
                 childExecArgv.unshift('--require', '@swc-node/register');
             }
+            // Stable inspector port: lowest free slot → debugBasePort+slot. Slots are
+            // released when a pod exits, so a crash-respawned pod reclaims the SAME port —
+            // an IDE "attach to 127.0.0.1:<port>" config survives respawns unedited.
+            const debugSlot = debugBasePort ? allocDebugSlot() : -1;
             const proc = (0, node_child_process_1.fork)(__filename, {
                 env: {
                     ...process.env,
                     APP_RUNNER: '1',
                     CHILD_SOCK_PATH: sockPath,
-                    CHILD_DEBUG_PORT: CHILD_COUNT == 1 ? '1' : '0',
+                    ...(debugSlot >= 0 && { CHILD_DEBUG_PORT: String(debugBasePort + debugSlot) }),
                 },
                 stdio: ['inherit', 'pipe', 'pipe', 'ipc'],
                 execArgv: childExecArgv,
             });
-            const info = { id, proc, healthy: false, lastError: null };
+            const info = { id, proc, healthy: false, lastError: null, debugSlot };
             proc.on('message', (msg) => {
                 if (!msg || typeof msg !== 'object')
                     return;
@@ -427,7 +534,10 @@ else {
                     console.log(`[parent] Child#${info.id} ready on socket ${info.socketPath}`);
                 }
                 else if (m.type === 'inspector-url') {
-                    console.log(`[parent] Child#${info.id} inspector: ${m.url}`);
+                    info.inspectorUrl = String(m.url);
+                    // "Debugger listening on ws://…" is the exact phrase IDE run consoles
+                    // (WebStorm, VS Code) detect and render as a click-to-attach link.
+                    console.log(`[parent] Child#${info.id} Debugger listening on ${m.url}`);
                 }
                 else if (m.type === 'reloaded') {
                     info.socketPath = String(m.socketPath);
@@ -446,6 +556,10 @@ else {
                 }
             });
             proc.on('exit', (code, signal) => {
+                if (info.debugSlot >= 0) {
+                    usedDebugSlots.delete(info.debugSlot);
+                    info.debugSlot = -1;
+                }
                 const clean = signal === 'SIGINT' || signal === 'SIGTERM' || code === 0;
                 if (clean) {
                     console.log(`[parent] Child#${info.id} exited cleanly (code=${code}, signal=${signal ?? 'none'})`);
@@ -532,12 +646,21 @@ else {
                 workerExecArgv.push('--require', require.resolve('@lensmcp/node-instrumentation/register'));
             }
             catch { /* instrumentation package absent — workers run untapped */ }
+            // Workers get inspectors too, offset above the pod range: pods sit on
+            // base+slot, workers on base+20+i. The index comes from WORKER_NAMES order,
+            // so a worker keeps its port across restartWorkers(). With debugging off,
+            // --inspect-port only PRESETS the port (no listener) — SIGUSR1 from
+            // POST /webpack/debug activates it later without restarting the worker.
+            const workerDebugPort = (debugBasePort || 9229) + WORKER_DEBUG_PORT_OFFSET + Math.max(0, WORKER_NAMES.indexOf(name));
+            workerExecArgv.push(debugBasePort
+                ? `--inspect=127.0.0.1:${workerDebugPort}`
+                : `--inspect-port=127.0.0.1:${workerDebugPort}`);
             const proc = (0, node_child_process_1.fork)(workerBundle, {
                 env: process.env,
                 stdio: ['inherit', 'pipe', 'pipe', 'ipc'],
                 execArgv: workerExecArgv,
             });
-            const info = { name, proc };
+            const info = { name, proc, debugPort: workerDebugPort };
             workerProcesses.push(info);
             wireProcLogging(proc, `\x1b[35m[worker:${name}] \x1b[0m`);
             proc.on('exit', (code, signal) => {
@@ -602,6 +725,66 @@ else {
                 });
                 return;
             }
+            // Admin endpoint: the live log stream — history, then follow (chunked text).
+            // `lensmcp logs <service>` attaches a terminal here (human), or takes a
+            // one-shot snapshot with ?follow=0&tail=N (agent). ?plain=1 strips ANSI.
+            if (req.method === 'GET' && req.url?.startsWith('/webpack/logs')) {
+                const q = new URL(req.url, 'http://localhost').searchParams;
+                const tail = Math.min(Math.max(Number(q.get('tail') ?? '100') || 0, 0), LOG_BUFFER_MAX);
+                const follow = q.get('follow') !== '0';
+                const plain = q.get('plain') === '1';
+                res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-cache' });
+                const history = tail === 0 ? '' : logBuffer.slice(-tail).join('');
+                res.write(plain ? history.replace(ANSI_RE, '') : history);
+                if (!follow) {
+                    res.end();
+                    return;
+                }
+                const sub = { res, plain };
+                logSubscribers.add(sub);
+                req.on('close', () => logSubscribers.delete(sub));
+                return;
+            }
+            // Admin endpoint: attach a debugger to the RUNNING service — no restart, app
+            // state intact. POST /webpack/debug[?port=9339] opens (or re-reports) every
+            // pod's inspector and returns the ws URLs; the base becomes sticky so pods
+            // spawned later (respawn, scale) come up debuggable too. Workers are nudged
+            // via SIGUSR1 (their port was preset with --inspect-port at spawn).
+            if (req.method === 'POST' && req.url?.startsWith('/webpack/debug')) {
+                const requested = Number(new URL(req.url, 'http://localhost').searchParams.get('port') || '');
+                if (Number.isInteger(requested) && requested > 1024)
+                    debugBasePort = requested;
+                if (!debugBasePort)
+                    debugBasePort = 9229;
+                const targets = children.filter((c) => c.proc.exitCode === null && c.proc.signalCode === null);
+                for (const c of targets) {
+                    if (c.debugSlot < 0)
+                        c.debugSlot = allocDebugSlot();
+                    try {
+                        c.proc.send?.({ type: 'debug-open', port: debugBasePort + c.debugSlot });
+                    }
+                    catch { /* pod died mid-request */ }
+                }
+                for (const w of workerProcesses) {
+                    try {
+                        w.proc.kill('SIGUSR1');
+                    }
+                    catch { /* worker gone */ }
+                }
+                // inspector-url replies arrive async over IPC — wait briefly, then report
+                const deadline = Date.now() + 2000;
+                while (Date.now() < deadline && targets.some((c) => !c.inspectorUrl)) {
+                    await new Promise((r) => setTimeout(r, 50));
+                }
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({
+                    ok: true,
+                    basePort: debugBasePort,
+                    pods: targets.map((c) => ({ id: c.id, inspectorUrl: c.inspectorUrl ?? null })),
+                    workers: workerProcesses.map((w) => ({ name: w.name, port: w.debugPort })),
+                }, null, 2) + '\n');
+                return;
+            }
             // Front-gateway routes: host/prefix match → external target, or fall
             // through to this service's own children when the route has no target.
             const route = matchGatewayRoute(req);
@@ -675,7 +858,7 @@ else {
             const certDomains = GATEWAY_ROUTES.map((r) => r.host).filter((h) => !!h);
             const certCacheDir = path.join(process.cwd(), 'node_modules', '.cache', 'davnx-webpack');
             gatewayPem = basicSsl.getCertificateSync(certCacheDir, SERVICE_NAME || 'lensmcp.dev', certDomains);
-            gatewayCaPath = basicSsl.caCertPath(certCacheDir);
+            gatewayCaPath = basicSsl.caCertPath(); // machine-level (~/.lensmcp/ca)
             // eslint-disable-next-line @typescript-eslint/no-require-imports
             const httpsMod = require('node:https');
             server = httpsMod.createServer({ key: gatewayPem, cert: gatewayPem }, requestHandler);
@@ -819,10 +1002,24 @@ else {
             });
             extraServers.push(extra);
         }
+        // Control socket: the SAME admin surface (logs/debug/reload/scale), reachable
+        // WITHOUT knowing the public port or scheme. `lensmcp logs <service>` finds it
+        // by deriving $TMPDIR[/<wsKey>]/<service>-devserver/parent.sock — the exact
+        // derivation the gateway uses for the pod pool dir. Plain HTTP: it's a
+        // per-user unix socket, TLS adds nothing.
+        const controlSockPath = path.join(SOCK_DIR, 'parent.sock');
+        cleanupSock(controlSockPath); // stale socket from a crashed previous parent
+        const controlServer = http.createServer(requestHandler);
+        controlServer.on('error', (err) => {
+            console.warn(`[parent] control socket unavailable (${err.code}) — lensmcp logs/debug attach disabled.`);
+        });
+        controlServer.listen(controlSockPath);
+        extraServers.push(controlServer);
         // Graceful shutdown of parent (children get SIGTERM)
         const shutdown = async (sig) => {
             shuttingDown = true; // stop crash-respawn from fighting the teardown
             console.log(`[${sig}] [parent] shutting down…`);
+            cleanupSock(controlSockPath);
             for (const extra of extraServers) {
                 try {
                     extra.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/cluster",
-  "version": "1.16.23",
+  "version": "1.16.25",
   "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.23",
-    "@lensmcp/nx-plugin": "1.16.23",
+    "@lensmcp/node-instrumentation": "1.16.25",
+    "@lensmcp/nx-plugin": "1.16.25",
     "fork-ts-checker-webpack-plugin": "^9.0.0",
     "glob": "^11.0.0",
     "http-proxy": "^1.18.0",