@lensmcp/cluster 1.16.33 → 1.17.0

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

@@ -2,12 +2,34 @@ 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>;
+/** True when something is LISTENING on `port` on loopback — the liveness signal the exit handler cannot
+ *  give us ({@link LENS_PROBE_ENABLED}: a vite alive with zero LISTEN sockets).
+ *
+ *  BOTH loopback families are tried before reporting a failure. Vite binds the NAME `localhost`, which can
+ *  resolve to `::1` on a v6-preferring host — probing only `127.0.0.1` there would report every healthy dev
+ *  server as wedged and SIGKILL the whole cluster in a loop. The v6 attempt only runs on the v4 failure
+ *  path, so the healthy case stays one connect. */
+export declare function probePortListening(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Poll until `port` is actually BINDABLE, up to `timeoutMs`. Resolves `true` when it frees, `false` on
+ * timeout (the caller then spawns anyway and lets the normal heal handle the fallout).
+ *
+ * WHY a respawn must await this: a dying vite can hold its listener for seconds (open HMR websockets keep
+ * the server closing), so the fixed 1.5s heal delay raced it and the fresh child died on
+ * `listen EADDRINUSE` — a self-inflicted crash that burned a heal attempt and lengthened the outage
+ * (see {@link PORT_FREE_WAIT_MS}). Probes at least ONCE even with `timeoutMs: 0`, so the common already-free
+ * case costs a single probe and no delay.
+ */
+export declare function waitForPortFree(port: number, timeoutMs: number, deps?: {
+    isPortFree?: (port: number) => Promise<boolean>;
+    intervalMs?: number;
+}): Promise<boolean>;
+/** The `--port <n>` / `--port=<n>` a vite child was launched with. `spawnLensFrontend` always PINS the port
+ *  for a gateway-routed app (`--port <n> --strictPort`), so argv is the authoritative record of which port
+ *  this child owns — the port the liveness probe checks and the port its respawn must wait to be free.
+ *  `undefined` for an unpinned child (nothing to probe, nothing to wait for). */
+export declare function viteArgPort(args: readonly string[]): number | undefined;
 export interface LensChildren {
     spawnManagedChild: SpawnChild;
     /** Boot the dashboard + MCP singletons and every `lens:true` app. Pushes the

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":"AASA,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,kCAAkC,CAAC;AAI1C,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,CAsWd"}
+{"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;AAI1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAuB,MAAM,SAAS,CAAC;AAgB1F,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA0B7E,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAalE;AAyBD;;;;;;mDAMmD;AACnD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAG1F;AAMD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAClF,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;iFAGiF;AACjF,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAQvE;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,CAmbd"}

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

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.probePortFree = probePortFree;
+exports.probePortListening = probePortListening;
+exports.waitForPortFree = waitForPortFree;
+exports.viteArgPort = viteArgPort;
 exports.createLensChildren = createLensChildren;
 const tslib_1 = require("tslib");
 /**
@@ -27,14 +30,110 @@ const HEAL_HEALTHY_MS = 20_000; // ran at least this long ⇒ a FRESH crash ⇒
  *  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) {
+/** One bind attempt. `in-use` only for the errnos that actually mean "someone has it"; any other failure
+ *  means that ADDRESS FAMILY is unavailable on this machine (no IPv6, for instance), which is not evidence
+ *  either way and must never be reported as "taken" — that would make `claimFreePort` step up forever. */
+function tryBind(port, host) {
     return new Promise((resolve) => {
         const probe = net.createServer();
         probe.unref();
-        probe.once('error', () => resolve(false));
-        probe.listen(port, () => probe.close(() => resolve(true)));
+        probe.once('error', (e) => {
+            const code = e.code ?? '';
+            resolve(code === 'EADDRINUSE' || code === 'EACCES' ? 'in-use' : 'unavailable');
+        });
+        probe.listen(host === undefined ? { port } : { port, host }, () => probe.close(() => resolve('free')));
+    });
+}
+async function probePortFree(port) {
+    // The WILDCARD bind alone is NOT enough, and that hole defeated the very purpose of this probe. MEASURED:
+    // with a holder on `127.0.0.1:P`, `listen({ port: P })` (the wildcard) reports **FREE** — a wildcard bind
+    // does not collide with a specific-address bind on macOS/BSD. Our children bind the NAME `localhost`
+    // (vite `--port N --strictPort`, the dashboard bundles), i.e. a LOOPBACK address — exactly the case the
+    // wildcard probe cannot see. So an orphaned vite holding `127.0.0.1:4200` looked free, `claimFreePort`
+    // handed 4200 straight back out, and the fresh child died on `listen EADDRINUSE` — the self-inflicted
+    // crash this probe exists to prevent (and what makes `waitForPortFree` meaningful rather than a no-op).
+    // Free means bindable on the wildcard AND on both loopback addresses; unavailable families are skipped.
+    for (const host of [undefined, '127.0.0.1', '::1']) {
+        if ((await tryBind(port, host)) === 'in-use')
+            return false;
+    }
+    return true;
+}
+/** A single-address TCP connect: does `host:port` ACCEPT right now? Connect-and-destroy, never an HTTP
+ *  request — a WEDGED vite may accept then hang forever, so a `GET` would time out even where the listener
+ *  is fine (and would pollute the dev server's log). Every timer/socket is unref'd: a probe must never hold
+ *  the gateway process open. */
+function probeConnect(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        let done = false;
+        const sock = net.createConnection({ host, port });
+        sock.unref();
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        timer.unref?.();
+        function finish(ok) {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            sock.destroy();
+            resolve(ok);
+        }
+        sock.once('connect', () => finish(true));
+        sock.once('error', () => finish(false));
     });
 }
+/** True when something is LISTENING on `port` on loopback — the liveness signal the exit handler cannot
+ *  give us ({@link LENS_PROBE_ENABLED}: a vite alive with zero LISTEN sockets).
+ *
+ *  BOTH loopback families are tried before reporting a failure. Vite binds the NAME `localhost`, which can
+ *  resolve to `::1` on a v6-preferring host — probing only `127.0.0.1` there would report every healthy dev
+ *  server as wedged and SIGKILL the whole cluster in a loop. The v6 attempt only runs on the v4 failure
+ *  path, so the healthy case stays one connect. */
+async function probePortListening(port, timeoutMs = 1_000) {
+    if (await probeConnect('127.0.0.1', port, timeoutMs))
+        return true;
+    return probeConnect('::1', port, timeoutMs);
+}
+/** Unref'd sleep — a heal/backoff wait must never keep the gateway alive past `stop()`. */
+const sleepUnref = (ms) => new Promise((r) => { const t = setTimeout(r, ms); t.unref?.(); });
+/**
+ * Poll until `port` is actually BINDABLE, up to `timeoutMs`. Resolves `true` when it frees, `false` on
+ * timeout (the caller then spawns anyway and lets the normal heal handle the fallout).
+ *
+ * WHY a respawn must await this: a dying vite can hold its listener for seconds (open HMR websockets keep
+ * the server closing), so the fixed 1.5s heal delay raced it and the fresh child died on
+ * `listen EADDRINUSE` — a self-inflicted crash that burned a heal attempt and lengthened the outage
+ * (see {@link PORT_FREE_WAIT_MS}). Probes at least ONCE even with `timeoutMs: 0`, so the common already-free
+ * case costs a single probe and no delay.
+ */
+async function waitForPortFree(port, timeoutMs, deps = {}) {
+    const isFree = deps.isPortFree ?? probePortFree;
+    const intervalMs = Math.max(1, deps.intervalMs ?? types_1.PORT_FREE_POLL_MS);
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+        if (await isFree(port))
+            return true;
+        const left = deadline - Date.now();
+        if (left <= 0)
+            return false;
+        await sleepUnref(Math.min(intervalMs, left));
+    }
+}
+/** The `--port <n>` / `--port=<n>` a vite child was launched with. `spawnLensFrontend` always PINS the port
+ *  for a gateway-routed app (`--port <n> --strictPort`), so argv is the authoritative record of which port
+ *  this child owns — the port the liveness probe checks and the port its respawn must wait to be free.
+ *  `undefined` for an unpinned child (nothing to probe, nothing to wait for). */
+function viteArgPort(args) {
+    const valid = (n) => (Number.isInteger(n) && n > 0 && n < 65_536 ? n : undefined);
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === '--port')
+            return valid(Number(args[i + 1]));
+        if (a.startsWith('--port='))
+            return valid(Number(a.slice('--port='.length)));
+    }
+    return undefined;
+}
 function createLensChildren(rt, obs, options, 
 // Injectable OS-level port probe (unit tests stub it; real ports are machine-dependent).
 deps) {
@@ -43,10 +142,14 @@ deps) {
     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.
+    // `portConflicts` counts CONSECUTIVE lost bind races (EADDRINUSE) — forgiven rather than charged to
+    // `attempts`, but capped so a permanently-squatted port still falls back to backoff.
     const lensHeal = new Map();
-    // Zombie recycle: the live `lens:true` app VITE children (label 'vite') + when each spawned, so the lens
-    // sweeper can restart one whose fs-watcher missed a post-spawn file add (the reported dashboard zombie).
-    // The capture sidecar + the dashboard/MCP singletons are NOT tracked (they don't serve app source).
+    // Zombie recycle + LIVENESS probe: the live `lens:true` app VITE children (label 'vite') + when each
+    // spawned, its pinned `port`, and its run of consecutive probe failures. `port`/`probeFails` drive the
+    // wedge probe (alive but NOT listening); `spawnedAt` also drives the stale-source-set recycle. Both reset
+    // naturally on a respawn, which registers a FRESH handle. The capture sidecar + the dashboard/MCP
+    // singletons are NOT tracked (they don't serve app source).
     const viteChildren = new Map();
     // Per-project last-recycle time — the cooldown survives the kill→auto-heal→respawn (a new child handle).
     const viteRecycleAt = new Map();
@@ -101,9 +204,14 @@ deps) {
         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
-        // workspace) for the zombie recycle. Its `LENSMCP_PROJECT` names the app; a fresh respawn re-adds here.
-        if (label === 'vite' || label.endsWith(':vite'))
-            viteChildren.set(child, { project: env?.['LENSMCP_PROJECT'] ?? 'app', spawnedAt });
+        // workspace) for the zombie recycle + the liveness probe. Its `LENSMCP_PROJECT` names the app and its
+        // argv pins the port; a fresh respawn re-adds here with a clean probe run.
+        const isVite = label === 'vite' || label.endsWith(':vite');
+        // The port THIS child owns (pinned `--port <n> --strictPort`): what the liveness probe checks and what
+        // the respawn must wait to be free. `undefined` for the dashboard/MCP singletons + an unpinned vite.
+        const ownPort = isVite ? viteArgPort(args) : undefined;
+        if (isVite)
+            viteChildren.set(child, { project: env?.['LENSMCP_PROJECT'] ?? 'app', spawnedAt, port: ownPort, probeFails: 0 });
         child.on('exit', (code, sig) => {
             const idx = lensChildren.indexOf(child);
             if (idx >= 0)
@@ -111,34 +219,120 @@ deps) {
             viteChildren.delete(child); // the auto-heal respawn re-registers a fresh handle with a new spawnedAt
             if (rt.stopped() || removedLabels.has(label))
                 return; // shutting down, or this workspace unregistered — do NOT resurrect
-            const heal = lensHeal.get(label) ?? { attempts: 0 };
-            if (Date.now() - spawnedAt >= HEAL_HEALTHY_MS)
-                heal.attempts = 0; // it was healthy → fresh budget
-            const delay = Math.min(HEAL_MAX_MS, HEAL_BASE_MS * 2 ** heal.attempts);
-            heal.attempts += 1;
-            lensHeal.set(label, heal);
-            console.warn(`[gateway] lens child ${label} exited (code=${code} sig=${sig}); auto-healing in ${Math.round(delay / 1000)}s (attempt ${heal.attempts}).`);
-            const t = setTimeout(() => { if (!rt.stopped())
-                spawnManagedChild(label, bin, args, env, optional, respawn, cwd); }, delay);
-            t.unref?.();
+            const ranMs = Date.now() - spawnedAt;
+            const heal = lensHeal.get(label) ?? { attempts: 0, portConflicts: 0 };
+            // The heal is ASYNC from here: classifying a bind race and waiting for the port both need a probe.
+            // Every wait is unref'd and every resume re-checks stopped()/removedLabels, so shutdown still wins.
+            void (async () => {
+                // BIND RACE vs CRASH. A fast non-zero exit while ANOTHER process still holds our pinned port is
+                // vite's `--strictPort` losing an EADDRINUSE race with the child it replaced — an environment
+                // condition, not a code fault. Charging it to `attempts` is what pushed the observed heal to
+                // "attempt 2" and doubled the outage; forgive it (bounded) and wait the port out instead.
+                const portHeld = ownPort !== undefined && !(await isPortFree(ownPort));
+                const raceLost = (0, lifecycle_1.isPortConflictExit)({ code, signal: sig, ranMs, portHeld }, { fastFailMs: types_1.CHILD_START_FAIL_MS });
+                if (raceLost && heal.portConflicts < types_1.MAX_PORT_CONFLICT_RETRIES) {
+                    heal.portConflicts += 1; // `attempts` UNTOUCHED — the crash-loop budget is for real crashes
+                    lensHeal.set(label, heal);
+                    console.warn(`[gateway] lens child ${label} lost the :${ownPort} bind race (EADDRINUSE, code=${code}); waiting for the port, then retrying (port-retry ${heal.portConflicts}/${types_1.MAX_PORT_CONFLICT_RETRIES}; crash budget untouched).`);
+                }
+                else {
+                    heal.portConflicts = 0; // a real exit ends the bind-race run
+                    if (ranMs >= HEAL_HEALTHY_MS)
+                        heal.attempts = 0; // it was healthy → fresh budget
+                    const delay = Math.min(HEAL_MAX_MS, HEAL_BASE_MS * 2 ** heal.attempts);
+                    heal.attempts += 1;
+                    lensHeal.set(label, heal);
+                    console.warn(`[gateway] lens child ${label} exited (code=${code} sig=${sig}); auto-healing in ${Math.round(delay / 1000)}s (attempt ${heal.attempts}).`);
+                    await sleepUnref(delay);
+                }
+                if (rt.stopped() || removedLabels.has(label))
+                    return;
+                // NEVER respawn into the dying child's port. A closing vite can hold its listener for seconds (open
+                // HMR websockets), so the old fixed delay raced it → `listen EADDRINUSE` → a self-inflicted crash
+                // that burned a heal attempt and LENGTHENED the 502. Bounded: past the budget we spawn anyway and
+                // let the (now correctly-classified) heal take it from there.
+                if (ownPort !== undefined && !(await waitForPortFree(ownPort, types_1.PORT_FREE_WAIT_MS, { isPortFree, intervalMs: types_1.PORT_FREE_POLL_MS }))) {
+                    console.warn(`[gateway] lens child ${label}: :${ownPort} still held after ${Math.round(types_1.PORT_FREE_WAIT_MS / 1000)}s — spawning anyway.`);
+                }
+                if (rt.stopped() || removedLabels.has(label))
+                    return;
+                spawnManagedChild(label, bin, args, env, optional, respawn, cwd);
+            })().catch(() => undefined); // a heal must never surface as an unhandled rejection
         });
         return child;
     };
-    // ZOMBIE recycle for lens frontends: restart a `lens:true` app's vite whose fs-watcher went stale — it is
-    // ALIVE + reachable yet MISSED files created after it spawned (500 `Failed to resolve import` for a file
-    // that exists; the reported 17.7h dashboard pod). The shared `rt.sourceSetChangedAt` (stamped by the
-    // lifecycle sweeper's source-set scan) drives it: a vite that spawned before a settled set change is
-    // killed → this manager's own `on('exit')` auto-heal respawns a fresh vite that re-scans the FS. Only on a
-    // set CHANGE (add/remove), never a content save, and never a blind max-age (no idle signal for a frontend).
+    // LIVENESS probe for lens frontends: kill a vite that is ALIVE but NOT LISTENING (the permanent-502 wedge
+    // — see LENS_PROBE_ENABLED). One cheap TCP connect per tracked child per tick; the pure `lensChildWedged`
+    // owns the verdict (grace + N consecutive failures + the shared per-project cooldown), this owns the I/O.
+    // A confirmed wedge gets SIGKILL — deliberately NOT SIGTERM: graceful shutdown is exactly what wedged (the
+    // event loop is pinned by the lens WS server / bridge sockets), so a SIGTERM can hang and leave the app
+    // 502ing forever. The kill lands on the proven exit→auto-heal path, which respawns after waiting the port
+    // out. `probeInFlight` keeps a slow round from overlapping the next tick.
+    let probeInFlight = false;
+    const probeLensChildren = async (cfg) => {
+        if (probeInFlight)
+            return;
+        probeInFlight = true;
+        try {
+            for (const [child, meta] of [...viteChildren]) {
+                if (rt.stopped())
+                    return;
+                if (meta.port === undefined)
+                    continue; // unpinned port ⇒ nothing to probe
+                if (child.exitCode !== null || child.signalCode !== null)
+                    continue; // already dying — the exit heal owns it
+                if (Date.now() - meta.spawnedAt < cfg.graceMs) {
+                    meta.probeFails = 0;
+                    continue;
+                } // still booting
+                if (await probePortListening(meta.port, types_1.LENS_PROBE_TIMEOUT_MS)) {
+                    meta.probeFails = 0;
+                    continue;
+                }
+                meta.probeFails += 1;
+                const reason = (0, lifecycle_1.lensChildWedged)(meta, viteRecycleAt.get(meta.project) ?? 0, Date.now(), cfg);
+                if (!reason)
+                    continue; // failing, but not yet N-in-a-row / still in cooldown
+                viteRecycleAt.set(meta.project, Date.now());
+                meta.probeFails = 0;
+                console.error(`[gateway] wedge recycle: lens app ${meta.project} is ALIVE but NOT LISTENING on :${meta.port} after ${Math.max(2, cfg.failureThreshold)} probes — SIGKILL; a fresh vite is coming.`);
+                emit('warning', `wedge recycle: ${meta.project} (${reason})`, `cluster-lens-app:${meta.project}`, { kind: 'pod-recycle', project: meta.project, reason, port: meta.port });
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* already gone — the exit auto-heal will respawn */ }
+            }
+        }
+        finally {
+            probeInFlight = false;
+        }
+    };
+    // The lens-frontend sweeper drives BOTH self-heals over the tracked vite children:
+    //  1. the LIVENESS probe above — alive but not listening (a permanent 502, invisible to the exit handler);
+    //  2. ZOMBIE recycle — a vite whose fs-watcher went stale: ALIVE + reachable yet MISSING files created
+    //     after it spawned (500 `Failed to resolve import` for a file that exists; the reported 17.7h
+    //     dashboard pod). The shared `rt.sourceSetChangedAt` (stamped by the lifecycle sweeper's source-set
+    //     scan) drives it: a vite that spawned before a settled set change is killed → this manager's own
+    //     `on('exit')` auto-heal respawns a fresh vite that re-scans the FS. Only on a set CHANGE
+    //     (add/remove), never a content save, and never a blind max-age (no idle signal for a frontend).
     const startLensSweeper = () => {
-        if (!types_1.POD_RECYCLE_ENABLED || lensSweeper)
+        // Either heal alone justifies the sweeper: a user who disabled the staleness recycle (its churn was a
+        // known problem) must still get a wedged 502 healed, so each branch is gated on its OWN switch.
+        if (lensSweeper || (!types_1.POD_RECYCLE_ENABLED && !types_1.LENS_PROBE_ENABLED))
             return;
         const cfg = { graceMs: types_1.POD_STALE_GRACE_MS, settleMs: types_1.POD_RECYCLE_SETTLE_MS, cooldownMs: types_1.POD_STALE_RECYCLE_COOLDOWN_MS };
+        const probeCfg = { graceMs: types_1.LENS_PROBE_GRACE_MS, failureThreshold: types_1.LENS_PROBE_FAILS, cooldownMs: types_1.POD_STALE_RECYCLE_COOLDOWN_MS };
         lensSweeper = setInterval(() => {
-            if (rt.stopped())
+            if (rt.stopped() || viteChildren.size === 0)
+                return;
+            // The liveness probe is INDEPENDENT of the source-set clock — a wedge has nothing to do with the file
+            // set, so it must run before (and regardless of) the staleness early-return below.
+            if (types_1.LENS_PROBE_ENABLED)
+                void probeLensChildren(probeCfg);
+            if (!types_1.POD_RECYCLE_ENABLED)
                 return;
             const wideChangedAt = rt.sourceSetChangedAt ?? 0;
-            if (wideChangedAt <= 0 || viteChildren.size === 0)
+            if (wideChangedAt <= 0)
                 return;
             const now = Date.now();
             for (const [child, meta] of viteChildren) {

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

@@ -9,7 +9,7 @@ import type { Observability } from './observability';
  *  actually resolve, instead of the whole monorepo — see that function for WHY. Omitted ⇒ the whole root
  *  (the original workspace-wide behavior, still used when a child's project root is unknown). Root-level
  *  loose files are always counted, so a `package.json`/`tsconfig.base.json` add reaches every scope. */
-export declare function sourceSetSignature(root: string, scopeDirs?: readonly string[]): Promise<string>;
+export declare function sourceSetSignature(root: string, scopeDirs?: readonly string[], extraExclude?: ReadonlySet<string>): Promise<string>;
 /**
  * PURE: which subtrees a child of `projectRoot` must watch for a "file set changed" verdict.
  *
@@ -30,7 +30,7 @@ export declare function sourceSetSignature(root: string, scopeDirs?: readonly st
  * Both args are absolute; the result is absolute and deduped. An empty result (the project root IS the
  * workspace root, or it sits outside it) means "no narrowing" → the caller falls back to the whole root.
  */
-export declare function sourceScopeDirs(workspaceRoot: string, projectRoot: string, managedBuckets: readonly string[], topLevelDirs: readonly string[]): string[];
+export declare function sourceScopeDirs(workspaceRoot: string, projectRoot: string, managedBuckets: readonly string[], topLevelDirs: readonly string[], extraExclude?: ReadonlySet<string>): string[];
 export interface PodRecycleConfig {
     maxAgeMs: number;
     graceMs: number;
@@ -58,6 +58,59 @@ export declare function lensFrontendStale(spawnedAt: number, lastRecycleAt: numb
     settleMs: number;
     cooldownMs: number;
 }): boolean;
+/** Config for the lens-child LIVENESS decision ({@link lensChildWedged}). */
+export interface LensChildProbeConfig {
+    /** Spawn grace: no verdict until the child has had this long to BIND its port (a cold vite boot). */
+    graceMs: number;
+    /** CONSECUTIVE probe failures required. Floored at 2 — one blip must never recycle. */
+    failureThreshold: number;
+    /** Per-project anti-thrash window after any recycle (shared with {@link lensFrontendStale}). */
+    cooldownMs: number;
+}
+/**
+ * PURE decision: is this ALIVE lens-frontend child WEDGED — process running, port NOT listening?
+ *
+ * The third self-heal blind spot. `lensFrontendStale` catches a vite serving a stale FS view; the exit
+ * handler catches a vite that DIED. Neither sees a vite that is alive, has printed `VITE ready`, and has
+ * NO LISTEN socket — its event loop held open by the lens WS server / bridge sockets while its HTTP
+ * listener is gone. Nothing exits, so nothing auto-heals, and the app 502s until a human kills the pid
+ * (foodguard 2026-07-29 — see {@link LENS_PROBE_ENABLED}).
+ *
+ * The caller owns the socket I/O (a cheap TCP connect per tick) and accumulates `probeFails`; this owns
+ * WHEN that evidence justifies a kill. Three guards, each earning its place:
+ *   - **grace** — a still-booting vite has no listener YET; killing it would be the outage, not the fix.
+ *   - **N consecutive failures** (≥2, enforced here so even a misconfigured `failureThreshold: 1` can't
+ *     single-blip recycle) — a momentary refusal is not a wedge.
+ *   - **cooldown** — the same per-project window the two recycle paths share, so probe + staleness can
+ *     never thrash one project between them.
+ * Returns the recycle reason or `null`. Kept pure (no process, no socket) so all four are unit-tested.
+ */
+export declare function lensChildWedged(child: {
+    spawnedAt: number;
+    probeFails: number;
+}, lastRecycleAt: number, now: number, cfg: LensChildProbeConfig): 'wedged-no-listener' | null;
+/**
+ * PURE decision: was this child's exit a lost BIND RACE (EADDRINUSE) rather than a crash?
+ *
+ * The auto-heal respawned on a fixed backoff while the child it replaced still held the pinned port, so
+ * vite's `--strictPort` exited code=1 on bind — and that self-inflicted exit consumed a heal attempt,
+ * pushing the backoff up and lengthening the very 502 it was healing (observed: `listen EADDRINUSE
+ * 127.0.0.1:50059` → `exited (code=1 sig=null); auto-healing in 3s (attempt 2)`). A bind race is an
+ * ENVIRONMENT condition, not a code fault, so it must not spend the crash-loop budget.
+ *
+ * The signature, from evidence we already have (stdio is `inherit`, so the child's stderr is unreadable):
+ * a non-zero exit, NOT from a signal (we killed it), FAST enough that it cannot have served traffic, while
+ * some OTHER process still holds the port. If the port is free by now the next spawn will simply succeed,
+ * so it is treated as a normal heal — the conservative direction.
+ */
+export declare function isPortConflictExit(exit: {
+    code: number | null;
+    signal: NodeJS.Signals | string | null;
+    ranMs: number;
+    portHeld: boolean;
+}, cfg: {
+    fastFailMs: number;
+}): boolean;
 export interface ServiceLayer {
     scanNow(pool: SockPool): number;
     spawnService(svc: ServiceCtl): void;

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;;;;;;;;wGAQwG;AACxG,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqCrG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,MAAM,EAAE,CAcV;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,CAgcvF"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/lifecycle.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAapE,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,iBAAiB,CAAC;AAyE/D;;;;;;;;wGAQwG;AACxG,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAqCzI;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACjC,MAAM,EAAE,CAcV;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,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,qGAAqG;IACrG,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,gBAAgB,EAAE,MAAM,CAAC;IACzB,gGAAgG;IAChG,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAChD,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,oBAAoB,GACxB,oBAAoB,GAAG,IAAI,CAK7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EACvG,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAC1B,OAAO,CAKT;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,CAmcvF"}

package/executors/gateway/runtime/lifecycle.js

@@ -4,6 +4,8 @@ exports.sourceSetSignature = sourceSetSignature;
 exports.sourceScopeDirs = sourceScopeDirs;
 exports.podRecycleReason = podRecycleReason;
 exports.lensFrontendStale = lensFrontendStale;
+exports.lensChildWedged = lensChildWedged;
+exports.isPortConflictExit = isPortConflictExit;
 exports.createServiceLayer = createServiceLayer;
 const tslib_1 = require("tslib");
 /**
@@ -17,6 +19,7 @@ const http = tslib_1.__importStar(require("node:http"));
 const path = tslib_1.__importStar(require("node:path"));
 const node_util_1 = require("node:util");
 const discovery_1 = require("./discovery");
+const scope_1 = require("./scope");
 const pod_env_1 = require("./pod-env");
 const types_1 = require("./types");
 /**
@@ -97,7 +100,7 @@ async function gitIgnoredPaths(root) {
  *  actually resolve, instead of the whole monorepo — see that function for WHY. Omitted ⇒ the whole root
  *  (the original workspace-wide behavior, still used when a child's project root is unknown). Root-level
  *  loose files are always counted, so a `package.json`/`tsconfig.base.json` add reaches every scope. */
-async function sourceSetSignature(root, scopeDirs) {
+async function sourceSetSignature(root, scopeDirs, extraExclude) {
     let count = 0;
     let xor = 0;
     const ignored = await gitIgnoredPaths(root);
@@ -121,7 +124,7 @@ async function sourceSetSignature(root, scopeDirs) {
             if (e.isDirectory()) {
                 if (!recurse)
                     continue; // scoped mode: root's own dirs are entered only via scopeDirs
-                if (name.startsWith('.') || SRC_EXCLUDE.has(name) || name.endsWith('-devserver'))
+                if (name.startsWith('.') || SRC_EXCLUDE.has(name) || extraExclude?.has(name) || name.endsWith('-devserver'))
                     continue;
                 if (ignored.has(`${rel(abs)}/`))
                     continue; // a gitignored output dir (foodguard's `artifacts/`)
@@ -170,7 +173,7 @@ async function sourceSetSignature(root, scopeDirs) {
  * Both args are absolute; the result is absolute and deduped. An empty result (the project root IS the
  * workspace root, or it sits outside it) means "no narrowing" → the caller falls back to the whole root.
  */
-function sourceScopeDirs(workspaceRoot, projectRoot, managedBuckets, topLevelDirs) {
+function sourceScopeDirs(workspaceRoot, projectRoot, managedBuckets, topLevelDirs, extraExclude) {
     const bucketOf = (abs) => {
         const r = path.relative(workspaceRoot, abs).split(path.sep).filter(Boolean);
         return r.length === 0 || r[0].startsWith('..') ? '' : r[0];
@@ -181,7 +184,7 @@ function sourceScopeDirs(workspaceRoot, projectRoot, managedBuckets, topLevelDir
     const managed = new Set(managedBuckets.filter(Boolean));
     const keep = new Set([own]);
     for (const d of topLevelDirs) {
-        if (d.startsWith('.') || SRC_EXCLUDE.has(d) || d.endsWith('-devserver'))
+        if (d.startsWith('.') || SRC_EXCLUDE.has(d) || extraExclude?.has(d) || d.endsWith('-devserver'))
             continue;
         if (!managed.has(d))
             keep.add(d); // a bucket owned by no managed project = shared/leaf → always watch
@@ -229,6 +232,56 @@ function lensFrontendStale(spawnedAt, lastRecycleAt, sourceSetChangedAt, now, cf
         return false; // let an add/remove burst settle → one recycle
     return true;
 }
+/**
+ * PURE decision: is this ALIVE lens-frontend child WEDGED — process running, port NOT listening?
+ *
+ * The third self-heal blind spot. `lensFrontendStale` catches a vite serving a stale FS view; the exit
+ * handler catches a vite that DIED. Neither sees a vite that is alive, has printed `VITE ready`, and has
+ * NO LISTEN socket — its event loop held open by the lens WS server / bridge sockets while its HTTP
+ * listener is gone. Nothing exits, so nothing auto-heals, and the app 502s until a human kills the pid
+ * (foodguard 2026-07-29 — see {@link LENS_PROBE_ENABLED}).
+ *
+ * The caller owns the socket I/O (a cheap TCP connect per tick) and accumulates `probeFails`; this owns
+ * WHEN that evidence justifies a kill. Three guards, each earning its place:
+ *   - **grace** — a still-booting vite has no listener YET; killing it would be the outage, not the fix.
+ *   - **N consecutive failures** (≥2, enforced here so even a misconfigured `failureThreshold: 1` can't
+ *     single-blip recycle) — a momentary refusal is not a wedge.
+ *   - **cooldown** — the same per-project window the two recycle paths share, so probe + staleness can
+ *     never thrash one project between them.
+ * Returns the recycle reason or `null`. Kept pure (no process, no socket) so all four are unit-tested.
+ */
+function lensChildWedged(child, lastRecycleAt, now, cfg) {
+    if (now - child.spawnedAt < cfg.graceMs)
+        return null; // still booting — it has no listener YET
+    if (now - lastRecycleAt < cfg.cooldownMs)
+        return null; // anti-thrash (shared with the staleness recycle)
+    if (child.probeFails < Math.max(2, cfg.failureThreshold))
+        return null; // one blip is never a wedge
+    return 'wedged-no-listener';
+}
+/**
+ * PURE decision: was this child's exit a lost BIND RACE (EADDRINUSE) rather than a crash?
+ *
+ * The auto-heal respawned on a fixed backoff while the child it replaced still held the pinned port, so
+ * vite's `--strictPort` exited code=1 on bind — and that self-inflicted exit consumed a heal attempt,
+ * pushing the backoff up and lengthening the very 502 it was healing (observed: `listen EADDRINUSE
+ * 127.0.0.1:50059` → `exited (code=1 sig=null); auto-healing in 3s (attempt 2)`). A bind race is an
+ * ENVIRONMENT condition, not a code fault, so it must not spend the crash-loop budget.
+ *
+ * The signature, from evidence we already have (stdio is `inherit`, so the child's stderr is unreadable):
+ * a non-zero exit, NOT from a signal (we killed it), FAST enough that it cannot have served traffic, while
+ * some OTHER process still holds the port. If the port is free by now the next spawn will simply succeed,
+ * so it is treated as a normal heal — the conservative direction.
+ */
+function isPortConflictExit(exit, cfg) {
+    if (exit.signal)
+        return false; // we (or the OS) killed it — a recycle/reap, never a bind failure
+    if (exit.code === null || exit.code === 0)
+        return false; // a clean exit is not a start failure
+    if (exit.ranMs > cfg.fastFailMs)
+        return false; // it RAN ⇒ it held the port ⇒ cannot be a bind race
+    return exit.portHeld; // someone else still holds it ⇒ this exit lost the bind race
+}
 function createServiceLayer(rt, obs) {
     const { emit } = obs;
     // Route a service's lifecycle events (starting/up/down/cold-start/…) to ITS OWNING workspace's bus —
@@ -615,11 +668,11 @@ function createServiceLayer(rt, obs) {
     };
     /** project → the absolute dirs its child must watch, or `undefined` when it cannot be narrowed (unknown
      *  project root / no `projectsConfigurations`) → that child keeps the workspace-wide clock. */
-    const scopeFor = (project, topLevel, managed) => {
+    const scopeFor = (project, topLevel, managed, extraExclude) => {
         const pr = rt.projectRoots?.[project];
         if (!pr)
             return undefined;
-        const dirs = sourceScopeDirs(rt.root, pr, managed, topLevel);
+        const dirs = sourceScopeDirs(rt.root, pr, managed, topLevel, extraExclude);
         return dirs.length > 0 ? dirs : undefined;
     };
     // Kick a bounded, async source-set scan when due; on a SET change (file added/removed) stamp the clocks so
@@ -634,7 +687,10 @@ function createServiceLayer(rt, obs) {
         scanInFlight = true;
         lastScanAt = Date.now();
         void (async () => {
-            const wide = await sourceSetSignature(rt.root);
+            // Per-workspace `.lensmcp/config.json` sourceSet.exclude — re-read per scan so an
+            // edit takes effect without a gateway restart (one tiny fs read per scan tick).
+            const extraExclude = (0, scope_1.readSourceSetExclude)(rt.root);
+            const wide = await sourceSetSignature(rt.root, undefined, extraExclude);
             if (prevSig !== undefined && wide !== prevSig) {
                 rt.sourceSetChangedAt = Date.now();
                 emit('info', 'source file set changed — stale pods recycle when idle', 'cluster-gateway', { kind: 'source-set-changed' });
@@ -660,7 +716,7 @@ function createServiceLayer(rt, obs) {
             // bucket → the scope dirs + the projects sharing it (one walk per bucket).
             const byBucket = new Map();
             for (const project of projects) {
-                const dirs = scopeFor(project, topLevel, managed);
+                const dirs = scopeFor(project, topLevel, managed, extraExclude);
                 if (!dirs)
                     continue;
                 const key = dirs.join('|');
@@ -670,7 +726,7 @@ function createServiceLayer(rt, obs) {
             }
             const now = Date.now();
             for (const [key, { dirs, projects: sharing }] of byBucket) {
-                const sig = await sourceSetSignature(rt.root, dirs);
+                const sig = await sourceSetSignature(rt.root, dirs, extraExclude);
                 const prev = prevScopedSig.get(key);
                 prevScopedSig.set(key, sig);
                 if (prev === undefined || sig === prev)

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

@@ -6,7 +6,10 @@ import type { ServiceLayer } from './lifecycle';
 export interface ProxyServer {
     web(req: http.IncomingMessage, res: http.ServerResponse, opts: Record<string, unknown>, cb: (err: Error) => void): void;
     ws(req: http.IncomingMessage, socket: stream.Duplex, head: Buffer, opts: Record<string, unknown>, cb: (err?: Error) => void): void;
-    on(event: 'proxyRes', cb: (proxyRes: http.IncomingMessage, req: http.IncomingMessage) => void): void;
+    on(event: 'proxyRes', cb: (proxyRes: http.IncomingMessage, req: http.IncomingMessage, res: http.ServerResponse) => void): void;
+    /** Emitted once the upstream ClientRequest has its socket — the only handle http-proxy gives us on the
+     *  OUTBOUND request, and so the only place the edge-cancel propagation below can be wired. */
+    on(event: 'proxyReq', cb: (proxyReq: http.ClientRequest, req: http.IncomingMessage, res: http.ServerResponse) => void): void;
     close?(): void;
 }
 export interface ProxyLayer {

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,CAsTtG"}
+{"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,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/H;kGAC8F;IAC9F,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7H,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,CAuYtG"}

package/executors/gateway/runtime/proxy.js

@@ -56,8 +56,46 @@ function createProxy(rt, obs, svcLayer) {
     // and leave the gateway-request trace open; the timeout fires the proxy
     // error path → 502 → res 'close' → inflight decrements + trace finishes.
     const proxy = httpProxy.createProxyServer({ xfwd: true, secure: false, proxyTimeout: 120_000, agent: httpAgent });
+    /**
+     * EDGE-CANCEL PROPAGATION for the H1 (node-http-proxy) path — the H1 twin of `pipeUpstream`'s
+     * `onEdgeClose`, and a real leak fix.
+     *
+     * node-http-proxy 1.18.1 propagates a client cancel through exactly ONE hook:
+     * `req.on('aborted', () => proxyReq.abort())` (web-incoming.js). `'aborted'` is the event Node
+     * DEPRECATED in v16 in favour of `'close'`, and it does not fire here — MEASURED on Node 24 with the
+     * real pooled-agent setup below: on an edge cancel mid-response the upstream request was never aborted
+     * (`aborted` 0 times), the upstream response never closed, the upstream kept STREAMING forever into a
+     * socket nobody reads, and the pooled socket stayed permanently CHECKED OUT of the agent
+     * (`in-use=1, free=0`) — leaked, never reused, never released. Every cancelled request (an unmounted
+     * SSE stream, an HMR reload, a navigated-away fetch) leaked one upstream socket AND pinned the pod
+     * generating events for a client that is gone; enough of them walk the agent to `maxSockets`, after
+     * which new requests queue behind sockets that can never come free.
+     *
+     * So the cancel is wired here instead, on both halves of the upstream exchange:
+     *  - `proxyReq` — cancel BEFORE the response arrives ⇒ destroy the outbound request.
+     *  - `proxyRes` — cancel MID-response ⇒ destroy the upstream response.
+     * DESTROY, never release: a destroyed socket is dropped from the agent instead of returned to
+     * `freeSockets`, so a half-drained socket can never be picked up by a later request. Measured after the
+     * fix: upstream closed, `in-use=0, free=0`, and http-proxy's error callback NOT invoked (so this raises
+     * no spurious 502 and triggers no heal retry). Each listener is removed when its upstream half closes,
+     * so nothing accumulates on a retried request (see the leak note in `pipeUpstream`).
+     */
+    const propagateEdgeCancel = (upstream, res, completed) => {
+        const onEdgeClose = () => {
+            if (completed())
+                return; // the response finished normally — nothing to cancel
+            if (!upstream.destroyed)
+                upstream.destroy();
+        };
+        res.once('close', onEdgeClose);
+        upstream.once('close', () => res.removeListener('close', onEdgeClose));
+    };
+    proxy.on('proxyReq', (proxyReq, _req, res) => {
+        // `writableEnded` ⇒ we already flushed the whole edge response, so this 'close' is normal completion.
+        propagateEdgeCancel(proxyReq, res, () => res.writableEnded);
+    });
     // Surface WHICH pod served the request (round-robin made visible).
-    proxy.on('proxyRes', (proxyRes, req) => {
+    proxy.on('proxyRes', (proxyRes, req, res) => {
         const pod = req.__lensmcpPod;
         if (pod)
             proxyRes.headers['x-lensmcp-pod'] = pod;
@@ -65,6 +103,10 @@ function createProxy(rt, obs, svcLayer) {
         // (e.g. NestJS/Express `x-powered-by`) and brand the hop as the LensMCP gateway.
         delete proxyRes.headers['x-powered-by'];
         proxyRes.headers['server'] = 'LensMCP';
+        // A mid-response cancel must stop the upstream too: `proxyRes.pipe(res)` only UNPIPES when the edge
+        // dies (Node's `pipe` never destroys the source), which is what stranded the socket.
+        if (res)
+            propagateEdgeCancel(proxyRes, res, () => res.writableEnded);
     });
     // --- native HTTP/2 forwarder ------------------------------------------------
     // node-http-proxy is HTTP/1.1-only: it copies connection-specific headers onto the
@@ -114,8 +156,34 @@ function createProxy(rt, obs, svcLayer) {
         // `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', () => { });
+        //
+        // ONCE PER REQUEST, not per attempt. `pipeUpstream` is re-entered for every TCP heal RETRY (see
+        // `tryTcp`), and containment is a property of the STREAM, not of one upstream attempt — so a plain
+        // `res.on('error')` here accumulated one listener per retry. With an 8s heal window at 300ms steps
+        // that is ~26 listeners on a single response, which Node reported as
+        // `MaxListenersExceededWarning: 11 error listeners added to [Http2ServerResponse]` (and the twin for
+        // [Http2ServerRequest] via the `req.on('error')` below). Each leaked closure also RETAINS the
+        // request/response objects — a memory bug, not just log noise. The marker makes re-entry idempotent.
+        const guard = res;
+        if (!guard.__lensmcpErrContained) {
+            guard.__lensmcpErrContained = true;
+            res.on('error', () => { });
+        }
+        // Per-ATTEMPT listeners live on the SHARED per-request `req`/`res`, so each attempt must REMOVE its own
+        // on the way out — otherwise a heal retry (`tryTcp`) stacks one more of each per pass (the leak above).
+        // `upstream` is captured so the edge-close handler can be built (and detached) outside the response cb.
+        let upstream;
+        const onReqError = () => { upstreamReq.destroy(); };
+        // The client canceled: stop reading the upstream so its pooled keep-alive socket isn't left flowing
+        // (a half-drained socket is corrupt on the next reuse → would break a later request).
+        const onEdgeClose = () => { if (upstream && !upstream.destroyed)
+            upstream.destroy(); };
+        const detach = () => {
+            req.removeListener('error', onReqError);
+            res.removeListener('close', onEdgeClose);
+        };
         const upstreamReq = mod.request(opts, (upstreamRes) => {
+            upstream = upstreamRes;
             cbs.onResponse();
             if (res.headersSent || res.writableEnded || res.destroyed) {
                 upstreamRes.destroy();
@@ -154,15 +222,17 @@ function createProxy(rt, obs, svcLayer) {
             // normal-completion 'close' a no-op. (An unhandled 'error' on upstreamRes would also throw.)
             const abortEdge = () => { if (!res.writableEnded && !res.destroyed)
                 res.destroy(); };
-            upstreamRes.on('error', abortEdge);
-            upstreamRes.on('close', abortEdge);
-            // The client canceled: stop reading the upstream so its pooled keep-alive socket isn't left flowing
-            // (a half-drained socket is corrupt on the next reuse → would break a later request).
-            res.on('close', () => { if (!upstreamRes.destroyed)
-                upstreamRes.destroy(); });
+            upstreamRes.once('error', abortEdge);
+            upstreamRes.once('close', abortEdge);
+            res.on('close', onEdgeClose);
         });
-        upstreamReq.on('error', (err) => cbs.onError(err));
-        req.on('error', () => upstreamReq.destroy());
+        upstreamReq.once('error', (err) => cbs.onError(err));
+        // ClientRequest 'close' fires exactly once however the attempt ended (completed, errored, destroyed), so
+        // it is the one place that can un-register this attempt's listeners — and drop the closures retaining
+        // `req`/`res`/`upstream`. For a long-lived stream it fires only when the stream ends, so `onEdgeClose`
+        // stays armed for the whole stream (a mid-stream client cancel MUST still destroy the upstream).
+        upstreamReq.once('close', detach);
+        req.on('error', onReqError);
         // GET/HEAD/OPTIONS carry no body — end immediately; else stream the request body upstream.
         if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS')
             upstreamReq.end();
@@ -234,8 +304,11 @@ function createProxy(rt, obs, svcLayer) {
             pipeUpstream(tcpTarget, req, res, {
                 onResponse: () => { },
                 onError: (err) => {
-                    if (isConnError(err) && Date.now() < tcpDeadline && !res.headersSent && !res.writableEnded) {
-                        setTimeout(tryTcp, types_1.UPSTREAM_HEAL_STEP_MS);
+                    // `!res.destroyed`: once the CLIENT is gone there is nobody to heal for — retrying would hammer a
+                    // recovering upstream for the rest of the window and then write an error into a dead stream.
+                    if (isConnError(err) && Date.now() < tcpDeadline && !res.headersSent && !res.writableEnded && !res.destroyed) {
+                        const t = setTimeout(tryTcp, types_1.UPSTREAM_HEAL_STEP_MS);
+                        t.unref?.(); // a pending heal retry must never keep the gateway process alive
                         return;
                     }
                     // Past the response headers there's nothing to send an error body into — reset the stream.
@@ -352,10 +425,14 @@ function createProxy(rt, obs, svcLayer) {
         const tcpDeadline = Date.now() + types_1.UPSTREAM_HEAL_WINDOW_MS;
         const tryTcp = () => {
             proxy.web(req, res, tcpOpts, (err) => {
-                if (isConnError(err) && Date.now() < tcpDeadline && !res.headersSent && !res.writableEnded) {
-                    setTimeout(tryTcp, types_1.UPSTREAM_HEAL_STEP_MS);
+                // `!res.destroyed` — see the h2 twin above: with the client gone there is nothing to heal for.
+                if (isConnError(err) && Date.now() < tcpDeadline && !res.headersSent && !res.writableEnded && !res.destroyed) {
+                    const t = setTimeout(tryTcp, types_1.UPSTREAM_HEAL_STEP_MS);
+                    t.unref?.();
                     return;
                 }
+                if (res.destroyed)
+                    return; // the client left — no stream to write an error into
                 console.error(`[gateway] upstream ${route.project} (${String(tcpTarget)}):`, err.message);
                 (0, edge_1.sendError)(res, req, 502, 'unavailable', `Upstream ${route.project} unavailable.`);
             });

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

@@ -11,6 +11,18 @@ export declare function readLensScope(root: string): {
     dashboardPort: number;
     basePath: string;
 };
+/**
+ * Per-workspace extra SOURCE-SET excludes (`.lensmcp/config.json` →
+ * `sourceSet.exclude: string[]`) — top-level dir names the staleness scanner
+ * must NOT treat as source. The scanner deliberately over-includes every
+ * unmanaged bucket (`shared/`, `docs/`, …) in every pod's scope, but a bucket
+ * like `docs/` can host source-extension files (`.json`, `.mdx`) that no pod
+ * can ever import — each add there flips the signature and recycles pods for
+ * nothing (foodguard 2026-07-29: a `docs/**\/*-intake.json` add recycled the
+ * dashboard; 475 recycles in one day were scope-C adds). Names only (no
+ * globs), matched exactly like the built-in excludes. Empty when unset.
+ */
+export declare function readSourceSetExclude(root: string): Set<string>;
 export declare function lensKeyFrom(root: string): string;
 export declare function lensSlug(input: string): string;
 //# sourceMappingURL=scope.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/scope.ts"],"names":[],"mappings":"AAOA;;;8CAG8C;AAC9C,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAUpD;AAED;;yEAEyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAmBpG;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ9C"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/scope.ts"],"names":[],"mappings":"AAOA;;;8CAG8C;AAC9C,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAUpD;AAED;;yEAEyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAmBpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAa9D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ9C"}

package/executors/gateway/runtime/scope.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.baseDomainOf = baseDomainOf;
 exports.readLensScope = readLensScope;
+exports.readSourceSetExclude = readSourceSetExclude;
 exports.lensKeyFrom = lensKeyFrom;
 exports.lensSlug = lensSlug;
 const tslib_1 = require("tslib");
@@ -48,6 +49,30 @@ function readLensScope(root) {
     const key = lensKeyFrom(root);
     return { key, dashboardPort: 4321, basePath: '/' + key };
 }
+/**
+ * Per-workspace extra SOURCE-SET excludes (`.lensmcp/config.json` →
+ * `sourceSet.exclude: string[]`) — top-level dir names the staleness scanner
+ * must NOT treat as source. The scanner deliberately over-includes every
+ * unmanaged bucket (`shared/`, `docs/`, …) in every pod's scope, but a bucket
+ * like `docs/` can host source-extension files (`.json`, `.mdx`) that no pod
+ * can ever import — each add there flips the signature and recycles pods for
+ * nothing (foodguard 2026-07-29: a `docs/**\/*-intake.json` add recycled the
+ * dashboard; 475 recycles in one day were scope-C adds). Names only (no
+ * globs), matched exactly like the built-in excludes. Empty when unset.
+ */
+function readSourceSetExclude(root) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(root, '.lensmcp', 'config.json'), 'utf8'));
+        const raw = cfg?.sourceSet?.exclude;
+        if (Array.isArray(raw)) {
+            return new Set(raw.filter((d) => typeof d === 'string' && d.length > 0 && !d.includes('/')));
+        }
+    }
+    catch {
+        /* no config — nothing extra to exclude */
+    }
+    return new Set();
+}
 function lensKeyFrom(root) {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));

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

@@ -15,5 +15,38 @@ export declare function buildEdgeVerifierPool(getRoutes: () => Route[]): EdgeVer
 /** Client-abort errnos that are NORMAL front-door traffic (a closed tab, a sleeping laptop, a canceled
  *  HMR socket) — dropped quietly. Anything else on an inbound socket is logged before the drop. */
 export declare const BENIGN_SOCKET_ERRNOS: ReadonlySet<string>;
+/**
+ * PURE classification of Node's H1 `clientError` — what to answer, and whether it is worth reporting.
+ *
+ * The old handler answered a BARE, UNLOGGED `400 Bad Request` to every cause and threw `err` away. That is
+ * how a gateway-generated 400 became indistinguishable from an application 400: a dev sees `GET
+ * /api/…/artifacts → 400` in the browser while the service logged `200`, with nothing anywhere to say the
+ * front door invented it. (Worked failure, foodguard: spurious empty-bodied 400s on real API calls, which
+ * a dev-proxy hop forwards verbatim to the browser, so they look exactly like app bugs.) MEASURED causes on
+ * Node 24: `HPE_INVALID_METHOD`, `HPE_INVALID_HEADER_TOKEN`, `HPE_HEADER_OVERFLOW`, `HPE_INVALID_EOF_STATE`.
+ *
+ * Three corrections fall out of that list:
+ *  - `HPE_HEADER_OVERFLOW` is **431**, not 400 — the request was well-formed, just too big.
+ *  - `ERR_HTTP_REQUEST_TIMEOUT` is **408** (what Node's own default handler answers) — a slow client is not
+ *    a malformed one, and calling it 400 sends a dev hunting a nonexistent parse bug.
+ *  - `HPE_INVALID_EOF_STATE` means the peer half-closed MID-MESSAGE — the signature of a client that went
+ *    away, and of the classic keep-alive REUSE RACE (a pooled client socket written to just as the server
+ *    closes it, see `GATEWAY_KEEPALIVE_TIMEOUT_MS`). Writing a 400 into that socket is precisely what turns
+ *    a harmless race into a client-visible 400, so it is treated like `ECONNRESET`: destroy, say nothing.
+ * Everything unrecognized keeps the previous behavior (400 + destroy), now logged.
+ */
+export interface ClientErrorVerdict {
+    /** Status line to best-effort write, or `null` for "write nothing, just destroy". */
+    status: 400 | 408 | 431 | null;
+    /** Log + emit? A routine client abort is not worth a line (and a scanner must not be able to flood). */
+    report: boolean;
+    /** Short cause label for the log/event. */
+    cause: string;
+}
+export declare function classifyClientError(code: string | undefined, message: string): ClientErrorVerdict;
+/** Per-cause log throttle for `clientError`: a desynced client or a port scanner can produce these in a
+ *  tight loop, and the point is a dev NOTICING one — not drowning in thousands. One line per cause per
+ *  window; the suppressed count rides the next admitted line. Exported for the unit test. */
+export declare function createClientErrorLogGate(windowMs?: number): (cause: string) => boolean;
 export declare function startGateway(options: GatewayRuntimeOptions, context: GatewayContext): Promise<GatewayHandle>;
 //# sourceMappingURL=server.d.ts.map

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;mGACmG;AACnG,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAA8E,CAAC;AAkBpI,wBAAsB,YAAY,CAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAqSxB"}
+{"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;AA2BxH;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,KAAK,EAAE,GAAG,gBAAgB,CA4ChF;AAED;mGACmG;AACnG,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAA8E,CAAC;AAEpI;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,kBAAkB;IACjC,qFAAqF;IACrF,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC;IAC/B,wGAAwG;IACxG,MAAM,EAAE,OAAO,CAAC;IAChB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAQjG;AAQD;;6FAE6F;AAC7F,wBAAgB,wBAAwB,CAAC,QAAQ,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAStF;AAkBD,wBAAsB,YAAY,CAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAsUxB"}

package/executors/gateway/runtime/server.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BENIGN_SOCKET_ERRNOS = void 0;
 exports.buildEdgeVerifierPool = buildEdgeVerifierPool;
+exports.classifyClientError = classifyClientError;
+exports.createClientErrorLogGate = createClientErrorLogGate;
 exports.startGateway = startGateway;
 const tslib_1 = require("tslib");
 /**
@@ -31,6 +33,7 @@ const hooks_1 = require("./hooks");
 const handler_1 = require("./handler");
 const upgrade_1 = require("./upgrade");
 const jwks_verify_1 = require("../jwks-verify");
+const types_1 = require("./types");
 /**
  * A `fetch`-shaped shim for the JWKS pull that accepts the dev gateway's OWN self-signed cert. The dev
  * IdP's JWKS is served behind the same local HTTPS front door (e.g. `https://auth.tetros.ai.local`), whose
@@ -116,6 +119,39 @@ function buildEdgeVerifierPool(getRoutes) {
 /** Client-abort errnos that are NORMAL front-door traffic (a closed tab, a sleeping laptop, a canceled
  *  HMR socket) — dropped quietly. Anything else on an inbound socket is logged before the drop. */
 exports.BENIGN_SOCKET_ERRNOS = new Set(['ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'ECONNABORTED', 'ECANCELED']);
+function classifyClientError(code, message) {
+    if (code && exports.BENIGN_SOCKET_ERRNOS.has(code))
+        return { status: null, report: false, cause: 'client-abort' };
+    // Peer half-closed mid-message: nobody is waiting for a 400, and writing one is the spurious-400 vector.
+    if (code === 'HPE_INVALID_EOF_STATE')
+        return { status: null, report: false, cause: 'truncated-at-eof' };
+    if (code === 'ERR_HTTP_REQUEST_TIMEOUT')
+        return { status: 408, report: true, cause: 'request-timeout' };
+    if (code === 'HPE_HEADER_OVERFLOW')
+        return { status: 431, report: true, cause: 'header-overflow' };
+    if (code?.startsWith('HPE_'))
+        return { status: 400, report: true, cause: 'parse-error' };
+    return { status: 400, report: true, cause: code ?? message ?? 'unknown' };
+}
+const CLIENT_ERROR_REASON = {
+    400: 'Bad Request',
+    408: 'Request Timeout',
+    431: 'Request Header Fields Too Large',
+};
+/** Per-cause log throttle for `clientError`: a desynced client or a port scanner can produce these in a
+ *  tight loop, and the point is a dev NOTICING one — not drowning in thousands. One line per cause per
+ *  window; the suppressed count rides the next admitted line. Exported for the unit test. */
+function createClientErrorLogGate(windowMs = 10_000) {
+    const lastAt = new Map();
+    return (cause) => {
+        const now = Date.now();
+        const prev = lastAt.get(cause) ?? 0;
+        if (now - prev < windowMs)
+            return false;
+        lastAt.set(cause, now);
+        return true;
+    };
+}
 /** Attach the inbound-socket error guard. EVERY socket the front door accepts gets an 'error' listener
  *  the moment it exists — both the raw TCP socket ('connection') and the post-handshake TLSSocket
  *  ('secureConnection', a DIFFERENT emitter). A client abort is routine, but with NO listener Node turns
@@ -202,6 +238,8 @@ async function startGateway(options, context) {
     };
     // --- layers -----------------------------------------------------------------
     const obs = (0, observability_1.createObservability)(eventFile, { trafficFlushMs });
+    // One gate for every front-door port — a desynced client must not get N log lines because we bound N ports.
+    const admitClientErrorLog = createClientErrorLogGate();
     const svcLayer = (0, lifecycle_1.createServiceLayer)(rt, obs);
     const lens = (0, lens_children_1.createLensChildren)(rt, obs, options);
     // The daemon CONTROL PLANE (loopback ~/.lensmcp/control.sock): a second workspace's `gateway start`
@@ -334,11 +372,42 @@ async function startGateway(options, context) {
         server.on('connection', guardInboundSocket);
         server.on('secureConnection', guardInboundSocket); // never fires on a plain-http server — harmless
         server.on('tlsClientError', (_err, tlsSocket) => tlsSocket.destroy());
-        server.on('clientError', (err, socket) => {
-            if (err.code !== 'ECONNRESET' && socket.writable)
-                socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+        server.on('clientError', (rawErr, socket) => {
+            // Node adds `bytesParsed`/`rawPacket` on an HTTP parse error (not on the base ErrnoException type):
+            // `bytesParsed` is the single most useful field for telling a truncated reuse race (0 / very low) from
+            // a genuinely malformed request, which is exactly what the old handler discarded.
+            const err = rawErr;
+            const v = classifyClientError(err.code, err.message);
+            // OBSERVABILITY (this used to be silent — the whole reason a gateway-invented 400 looked like an app
+            // bug). Rate-limited per cause so a port scanner or a desynced client cannot flood the log; the bus
+            // `emit` is separately flood-guarded by its fingerprint.
+            if (v.report && admitClientErrorLog(v.cause)) {
+                const peer = socket.remoteAddress ?? 'unknown';
+                const answer = v.status === null ? 'dropped' : String(v.status);
+                console.warn(`[gateway] inbound H1 clientError from ${peer}: ${v.cause} (${err.code ?? err.message}${err.bytesParsed !== undefined ? `, bytesParsed=${err.bytesParsed}` : ''}) → ${answer}. This status is the GATEWAY's, not the upstream service's.`);
+                obs.emit('warning', `inbound clientError: ${v.cause} → ${answer}`, `gateway-client-error:${v.cause}`, {
+                    kind: 'gateway-client-error', cause: v.cause, code: err.code ?? null, status: v.status, peer,
+                    bytesParsed: err.bytesParsed ?? null,
+                });
+            }
+            // Preserved intent: a best-effort status on a still-writable socket, then destroy.
+            if (v.status !== null && socket.writable)
+                socket.end(`HTTP/1.1 ${v.status} ${CLIENT_ERROR_REASON[v.status]}\r\n\r\n`);
             socket.destroy();
         });
+        // KEEP-ALIVE REUSE RACE. Node's server default `keepAliveTimeout` is 5s — and a Node HTTP client's
+        // pooled agent (Node 19+ `globalAgent` is keepAlive:true; vite's dev proxy uses it) idles on ~the same
+        // 5s. Both sides then race the SAME deadline: the client writes a request onto a socket the server is
+        // simultaneously closing, the server reads a truncated message, and the front door answers a bare
+        // `400` that the dev proxy forwards to the browser verbatim — a 400 on a request the service would
+        // have served 200. The documented fix is for the server's idle window to EXCEED every client's, so the
+        // server never closes first and the client always controls socket reuse. `headersTimeout` must stay
+        // above `keepAliveTimeout` (it bounds a request that has started arriving), and `requestTimeout` keeps
+        // its Node default. Dev-only front door, a handful of clients → holding idle sockets longer is free.
+        server.keepAliveTimeout = types_1.GATEWAY_KEEPALIVE_TIMEOUT_MS;
+        if (server.headersTimeout < types_1.GATEWAY_KEEPALIVE_TIMEOUT_MS + 5_000) {
+            server.headersTimeout = types_1.GATEWAY_KEEPALIVE_TIMEOUT_MS + 5_000;
+        }
         // 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

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

@@ -213,6 +213,61 @@ export declare const POD_STALE_SCAN_MS: number;
 /** Per-service cooldown between staleness recycles — stops a source-churn burst (codegen) thrash-recycling
  *  the same pod. Override `LENSMCP_POD_STALE_RECYCLE_COOLDOWN_MS`. Default 60s. */
 export declare const POD_STALE_RECYCLE_COOLDOWN_MS: number;
+/**
+ * LENS-CHILD LIVENESS PROBE (dev only). The FOURTH failure mode, and the one that wedges an app in a
+ * PERMANENT 502 with nothing in the log: a gateway-spawned vite that is ALIVE but NOT LISTENING. Child
+ * health was modelled ONLY as "has the process exited", so a vite whose HTTP listener closes/faults while
+ * its event loop stays held open (by the lensmcp plugin's WS server + the bridge connections) is INVISIBLE:
+ * `viteChildren` still holds it as live, no `lens child vite exited` line is ever logged, and the
+ * exit-driven auto-heal never fires. Worked failure (foodguard, 2026-07-29): two 43-minute-old vite children
+ * (pids 89518/89519) that had both printed `VITE ready in 1005 ms` + `Local: http://localhost:4200/`, yet
+ * `lsof -nP -p 89519` showed ZERO LISTEN sockets and `lsof -iTCP:4200 -sTCP:LISTEN` was empty —
+ * `https://app.foodguard.local` 502'd indefinitely until the pids were hand-killed (the exit handler then
+ * respawned them and the app returned 200 within 8s). So the sweeper now TCP-probes each live child's pinned
+ * port and SIGKILLs a confirmed wedge, letting the proven exit→auto-heal path do the rest.
+ */
+/** Master switch for the liveness probe. Deliberately INDEPENDENT of {@link POD_RECYCLE_ENABLED}: a user who
+ *  sets `LENSMCP_POD_RECYCLE=0` to stop staleness churn still wants a wedged 502 healed. Set
+ *  `LENSMCP_LENS_PROBE=0` to disable. Default ON (dev). */
+export declare const LENS_PROBE_ENABLED: boolean;
+/** Spawn grace: a child is never probed (and so never recycled) until it has had this long to BIND its port
+ *  — a cold vite/nx boot in a big monorepo takes many seconds, and killing a still-booting dev server would
+ *  be a self-inflicted outage. Override `LENSMCP_LENS_PROBE_GRACE_MS`. Default 45s. */
+export declare const LENS_PROBE_GRACE_MS: number;
+/** CONSECUTIVE probe failures required before a recycle — one blip (a momentary accept backlog, a laptop
+ *  sleep-wake, a GC pause) must never recycle a healthy dev server. Floored at 2 by
+ *  {@link lensChildWedged}. Override `LENSMCP_LENS_PROBE_FAILS`. Default 2. */
+export declare const LENS_PROBE_FAILS: number;
+/** Per-probe TCP connect timeout. Short: a listening socket accepts a loopback connect in microseconds, so
+ *  anything slower is indistinguishable from absent. Override `LENSMCP_LENS_PROBE_TIMEOUT_MS`. Default 1s. */
+export declare const LENS_PROBE_TIMEOUT_MS: number;
+/**
+ * RESPAWN-INTO-A-HELD-PORT (the EADDRINUSE self-inflicted crash). The auto-heal respawned after a FIXED
+ * backoff while the previous child still held the pinned port — vite's `--strictPort` then exits code=1 on
+ * bind, burning a heal attempt and EXTENDING the 502 window. Observed in the gateway log:
+ * `Error: listen EADDRINUSE: address already in use 127.0.0.1:50059` immediately followed by
+ * `lens child vite exited (code=1 sig=null); auto-healing in 3s (attempt 2).` (3 such events in one log).
+ * Two fixes: WAIT for the port to become bindable before spawning, and classify a bind-race exit as
+ * RETRYABLE so it does not consume the crash-loop budget a real code fault does.
+ */
+/** How long a respawn polls for its pinned port to become bindable before spawning anyway (past the budget
+ *  the normal heal backoff takes over). Override `LENSMCP_PORT_FREE_WAIT_MS`. Default 10s. */
+export declare const PORT_FREE_WAIT_MS: number;
+/** Poll interval while waiting for a port to free. Override `LENSMCP_PORT_FREE_POLL_MS`. Default 250ms. */
+export declare const PORT_FREE_POLL_MS: number;
+/** A non-zero exit sooner than this is a START failure (it never bound); later means the child RAN and so
+ *  had the port, which cannot be a bind race. Override `LENSMCP_CHILD_START_FAIL_MS`. Default 10s. */
+export declare const CHILD_START_FAIL_MS: number;
+/** Ultimate backstop: after this many CONSECUTIVE bind-race exits for one label, stop forgiving them and
+ *  fall back to the normal exponential backoff (so a permanently-squatted port can't 10s-loop forever).
+ *  Override `LENSMCP_MAX_PORT_CONFLICT_RETRIES`. Default 5. */
+export declare const MAX_PORT_CONFLICT_RETRIES: number;
+/** Inbound keep-alive idle window for the front door. MUST exceed every client's pooled-socket idle timeout
+ *  so the SERVER never closes a keep-alive socket a client is about to reuse — otherwise both sides race the
+ *  same deadline and the truncated request surfaces as a spurious front-door `400` (see
+ *  `classifyClientError`). Node's server default is 5s and a Node client agent's is ~5s, i.e. exactly tied.
+ *  Override `LENSMCP_KEEPALIVE_TIMEOUT_MS`. Default 76s. */
+export declare const GATEWAY_KEEPALIVE_TIMEOUT_MS: number;
 /** Test-tunable knobs on top of the user-facing schema. */
 export interface GatewayRuntimeOptions extends GatewayExecutorSchema {
     /** Traffic-edge flush period (ms). Default 5000. */

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../libs/cluster/src/executors/gateway/runtime/types.ts"],"names":[],"mappings":"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"}

package/executors/gateway/runtime/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.POD_STALE_RECYCLE_COOLDOWN_MS = exports.POD_STALE_SCAN_MS = exports.POD_RECYCLE_SETTLE_MS = exports.POD_STALE_GRACE_MS = exports.POD_MAX_AGE_MS = exports.POD_RECYCLE_ENABLED = exports.WEDGE_RECYCLE_GRACE_MS = exports.POD_RESPONSE_TIMEOUT_MS = exports.UPSTREAM_HEAL_STEP_MS = exports.UPSTREAM_HEAL_WINDOW_MS = exports.SERVICE_RESTART_WINDOW_MS = exports.SERVICE_MAX_RESTARTS = exports.SERVICE_ERROR_THROTTLE_MS = void 0;
+exports.GATEWAY_KEEPALIVE_TIMEOUT_MS = exports.MAX_PORT_CONFLICT_RETRIES = exports.CHILD_START_FAIL_MS = exports.PORT_FREE_POLL_MS = exports.PORT_FREE_WAIT_MS = exports.LENS_PROBE_TIMEOUT_MS = exports.LENS_PROBE_FAILS = exports.LENS_PROBE_GRACE_MS = exports.LENS_PROBE_ENABLED = exports.POD_STALE_RECYCLE_COOLDOWN_MS = exports.POD_STALE_SCAN_MS = exports.POD_RECYCLE_SETTLE_MS = exports.POD_STALE_GRACE_MS = exports.POD_MAX_AGE_MS = exports.POD_RECYCLE_ENABLED = exports.WEDGE_RECYCLE_GRACE_MS = exports.POD_RESPONSE_TIMEOUT_MS = exports.UPSTREAM_HEAL_STEP_MS = exports.UPSTREAM_HEAL_WINDOW_MS = exports.SERVICE_RESTART_WINDOW_MS = exports.SERVICE_MAX_RESTARTS = exports.SERVICE_ERROR_THROTTLE_MS = void 0;
 /** Parse a positive-integer env override; fall back to `def` on missing/NaN/negative. `allowZero` lets a
  *  `0` through (used as a "disable" sentinel, e.g. {@link POD_MAX_AGE_MS}); otherwise `0` also falls back. */
 function envInt(name, def, allowZero = false) {
@@ -77,3 +77,58 @@ exports.POD_STALE_SCAN_MS = envInt('LENSMCP_POD_STALE_SCAN_MS', 30_000);
 /** Per-service cooldown between staleness recycles — stops a source-churn burst (codegen) thrash-recycling
  *  the same pod. Override `LENSMCP_POD_STALE_RECYCLE_COOLDOWN_MS`. Default 60s. */
 exports.POD_STALE_RECYCLE_COOLDOWN_MS = envInt('LENSMCP_POD_STALE_RECYCLE_COOLDOWN_MS', 60_000);
+/**
+ * LENS-CHILD LIVENESS PROBE (dev only). The FOURTH failure mode, and the one that wedges an app in a
+ * PERMANENT 502 with nothing in the log: a gateway-spawned vite that is ALIVE but NOT LISTENING. Child
+ * health was modelled ONLY as "has the process exited", so a vite whose HTTP listener closes/faults while
+ * its event loop stays held open (by the lensmcp plugin's WS server + the bridge connections) is INVISIBLE:
+ * `viteChildren` still holds it as live, no `lens child vite exited` line is ever logged, and the
+ * exit-driven auto-heal never fires. Worked failure (foodguard, 2026-07-29): two 43-minute-old vite children
+ * (pids 89518/89519) that had both printed `VITE ready in 1005 ms` + `Local: http://localhost:4200/`, yet
+ * `lsof -nP -p 89519` showed ZERO LISTEN sockets and `lsof -iTCP:4200 -sTCP:LISTEN` was empty —
+ * `https://app.foodguard.local` 502'd indefinitely until the pids were hand-killed (the exit handler then
+ * respawned them and the app returned 200 within 8s). So the sweeper now TCP-probes each live child's pinned
+ * port and SIGKILLs a confirmed wedge, letting the proven exit→auto-heal path do the rest.
+ */
+/** Master switch for the liveness probe. Deliberately INDEPENDENT of {@link POD_RECYCLE_ENABLED}: a user who
+ *  sets `LENSMCP_POD_RECYCLE=0` to stop staleness churn still wants a wedged 502 healed. Set
+ *  `LENSMCP_LENS_PROBE=0` to disable. Default ON (dev). */
+exports.LENS_PROBE_ENABLED = process.env['LENSMCP_LENS_PROBE'] !== '0';
+/** Spawn grace: a child is never probed (and so never recycled) until it has had this long to BIND its port
+ *  — a cold vite/nx boot in a big monorepo takes many seconds, and killing a still-booting dev server would
+ *  be a self-inflicted outage. Override `LENSMCP_LENS_PROBE_GRACE_MS`. Default 45s. */
+exports.LENS_PROBE_GRACE_MS = envInt('LENSMCP_LENS_PROBE_GRACE_MS', 45_000);
+/** CONSECUTIVE probe failures required before a recycle — one blip (a momentary accept backlog, a laptop
+ *  sleep-wake, a GC pause) must never recycle a healthy dev server. Floored at 2 by
+ *  {@link lensChildWedged}. Override `LENSMCP_LENS_PROBE_FAILS`. Default 2. */
+exports.LENS_PROBE_FAILS = envInt('LENSMCP_LENS_PROBE_FAILS', 2);
+/** Per-probe TCP connect timeout. Short: a listening socket accepts a loopback connect in microseconds, so
+ *  anything slower is indistinguishable from absent. Override `LENSMCP_LENS_PROBE_TIMEOUT_MS`. Default 1s. */
+exports.LENS_PROBE_TIMEOUT_MS = envInt('LENSMCP_LENS_PROBE_TIMEOUT_MS', 1_000);
+/**
+ * RESPAWN-INTO-A-HELD-PORT (the EADDRINUSE self-inflicted crash). The auto-heal respawned after a FIXED
+ * backoff while the previous child still held the pinned port — vite's `--strictPort` then exits code=1 on
+ * bind, burning a heal attempt and EXTENDING the 502 window. Observed in the gateway log:
+ * `Error: listen EADDRINUSE: address already in use 127.0.0.1:50059` immediately followed by
+ * `lens child vite exited (code=1 sig=null); auto-healing in 3s (attempt 2).` (3 such events in one log).
+ * Two fixes: WAIT for the port to become bindable before spawning, and classify a bind-race exit as
+ * RETRYABLE so it does not consume the crash-loop budget a real code fault does.
+ */
+/** How long a respawn polls for its pinned port to become bindable before spawning anyway (past the budget
+ *  the normal heal backoff takes over). Override `LENSMCP_PORT_FREE_WAIT_MS`. Default 10s. */
+exports.PORT_FREE_WAIT_MS = envInt('LENSMCP_PORT_FREE_WAIT_MS', 10_000);
+/** Poll interval while waiting for a port to free. Override `LENSMCP_PORT_FREE_POLL_MS`. Default 250ms. */
+exports.PORT_FREE_POLL_MS = envInt('LENSMCP_PORT_FREE_POLL_MS', 250);
+/** A non-zero exit sooner than this is a START failure (it never bound); later means the child RAN and so
+ *  had the port, which cannot be a bind race. Override `LENSMCP_CHILD_START_FAIL_MS`. Default 10s. */
+exports.CHILD_START_FAIL_MS = envInt('LENSMCP_CHILD_START_FAIL_MS', 10_000);
+/** Ultimate backstop: after this many CONSECUTIVE bind-race exits for one label, stop forgiving them and
+ *  fall back to the normal exponential backoff (so a permanently-squatted port can't 10s-loop forever).
+ *  Override `LENSMCP_MAX_PORT_CONFLICT_RETRIES`. Default 5. */
+exports.MAX_PORT_CONFLICT_RETRIES = envInt('LENSMCP_MAX_PORT_CONFLICT_RETRIES', 5);
+/** Inbound keep-alive idle window for the front door. MUST exceed every client's pooled-socket idle timeout
+ *  so the SERVER never closes a keep-alive socket a client is about to reuse — otherwise both sides race the
+ *  same deadline and the truncated request surfaces as a spurious front-door `400` (see
+ *  `classifyClientError`). Node's server default is 5s and a Node client agent's is ~5s, i.e. exactly tied.
+ *  Override `LENSMCP_KEEPALIVE_TIMEOUT_MS`. Default 76s. */
+exports.GATEWAY_KEEPALIVE_TIMEOUT_MS = envInt('LENSMCP_KEEPALIVE_TIMEOUT_MS', 76_000);

package/package.json

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