@lensmcp/cluster 1.16.31 → 1.17.0

package/executors/gateway/runtime/lifecycle.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 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");
 /**
@@ -16,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");
 /**
@@ -90,14 +94,19 @@ async function gitIgnoredPaths(root) {
 /** Bounded, async, non-blocking walk of the workspace source tree → a signature of the file SET
  *  (`<count>:<xor-of-path-hashes>`). Skips node_modules/dist/build/dotdirs + `*-devserver` sock dirs + every
  *  GITIGNORED path (runtime output is not source — see `SRC_EXCLUDE`), and only counts source-extension
- *  files. Order-independent (readdir order irrelevant) and null-safe. */
-async function sourceSetSignature(root) {
+ *  files. Order-independent (readdir order irrelevant) and null-safe.
+ *
+ *  `scopeDirs` (absolute, from {@link sourceScopeDirs}) narrows the walk to the subtrees a given child could
+ *  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, extraExclude) {
     let count = 0;
     let xor = 0;
     const ignored = await gitIgnoredPaths(root);
     // git speaks posix-relative; `path.relative` yields `\` on win32 — normalize before every lookup.
     const rel = (abs) => path.relative(root, abs).split(path.sep).join('/');
-    const walk = async (dir) => {
+    const walk = async (dir, recurse = true) => {
         if (count > SCAN_FILE_CAP)
             return;
         let entries;
@@ -113,7 +122,9 @@ async function sourceSetSignature(root) {
             const name = e.name;
             const abs = path.join(dir, name);
             if (e.isDirectory()) {
-                if (name.startsWith('.') || SRC_EXCLUDE.has(name) || name.endsWith('-devserver'))
+                if (!recurse)
+                    continue; // scoped mode: root's own dirs are entered only via scopeDirs
+                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/`)
@@ -130,9 +141,56 @@ async function sourceSetSignature(root) {
             }
         }
     };
-    await walk(root);
+    if (scopeDirs && scopeDirs.length > 0) {
+        await walk(root, false); // root-level loose files only — its subdirs come from scopeDirs
+        // Sequential, not Promise.all: `count`/`xor` are shared accumulators, and the xor is
+        // order-independent anyway — so concurrency would buy nothing but interleaving risk.
+        for (const dir of scopeDirs)
+            await walk(dir);
+    }
+    else {
+        await walk(root);
+    }
     return `${count}:${(xor >>> 0).toString(36)}`;
 }
+/**
+ * PURE: which subtrees a child of `projectRoot` must watch for a "file set changed" verdict.
+ *
+ * The staleness signal exists to catch a vite/pod whose fs-watcher MISSED a file add. But the signature was
+ * workspace-WIDE while its consumers are PER-CHILD, so adding a backend-only `server/apps/auth/**\/*.ts`
+ * — a file in no vite module graph — recycled every frontend vite too. Worked failure (foodguard,
+ * 2026-07-28): one session writing `server/apps/auth/src/modules/totp/**` added a `.ts` every ~15-20s and
+ * held `app.foodguard.local` in near-continuous 502s, 951 recycles in a session, none of them relevant to
+ * the dashboard.
+ *
+ * The scope is the child's OWN top-level bucket plus every bucket that hosts no OTHER gateway-managed
+ * project (`managedBuckets`). In a scope-first monorepo (`web/ server/ shared/ ai/ tools/`) that yields
+ * `web + shared + ai + tools` for a frontend and `server + shared + ai + tools` for a service: a
+ * `server/**` add no longer touches a frontend, while a `shared/contracts` add still reaches both — which
+ * is correct, since both import it. It deliberately OVER-includes (a frontend watches `ai/` it may never
+ * import) because a false recycle costs a cold start whereas a MISSED one costs a wedged dev server.
+ *
+ * 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, extraExclude) {
+    const bucketOf = (abs) => {
+        const r = path.relative(workspaceRoot, abs).split(path.sep).filter(Boolean);
+        return r.length === 0 || r[0].startsWith('..') ? '' : r[0];
+    };
+    const own = bucketOf(projectRoot);
+    if (!own)
+        return []; // project root === workspace root (or outside it) → cannot narrow
+    const managed = new Set(managedBuckets.filter(Boolean));
+    const keep = new Set([own]);
+    for (const d of topLevelDirs) {
+        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
+    }
+    return [...keep].sort().map((d) => path.join(workspaceRoot, d));
+}
 /**
  * PURE decision: should this pod be recycled as a stale-view zombie, and why? A pod qualifies only when it
  * is a live, UP, gateway-spawned pod that is currently QUIET (0 in-flight AND idle for `settleMs`, so a busy
@@ -174,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 —
@@ -535,23 +643,100 @@ function createServiceLayer(rt, obs) {
         settleMs: types_1.POD_RECYCLE_SETTLE_MS, cooldownMs: types_1.POD_STALE_RECYCLE_COOLDOWN_MS,
     };
     let prevSig;
+    const prevScopedSig = new Map(); // bucket → its last signature
     let scanInFlight = false;
     let lastScanAt = 0;
-    // Kick a bounded, async source-set scan when due; on a SET change (file added/removed) stamp the shared
-    // clock so pods that predate it recycle. Non-blocking — the sweeper never awaits it.
+    /** The distinct top-level buckets owned by a gateway-managed project (services + `lens:true` apps) — every
+     *  OTHER bucket is shared/leaf and belongs in every scope. Recomputed per scan so a workspace registered
+     *  after boot is picked up. */
+    const managedBuckets = () => {
+        const roots = rt.projectRoots ?? {};
+        const names = new Set(rt.services.map((s) => s.project));
+        for (const r of rt.routes)
+            if (r.lens)
+                names.add(r.lens.project);
+        const buckets = new Set();
+        for (const n of names) {
+            const pr = roots[n];
+            if (!pr)
+                continue;
+            const seg = path.relative(rt.root, pr).split(path.sep).filter(Boolean)[0];
+            if (seg && !seg.startsWith('..'))
+                buckets.add(seg);
+        }
+        return [...buckets];
+    };
+    /** 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, extraExclude) => {
+        const pr = rt.projectRoots?.[project];
+        if (!pr)
+            return undefined;
+        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
+    // children that predate it recycle. Non-blocking — the sweeper never awaits it. Two tiers: the
+    // workspace-WIDE signature (the fallback + back-compat clock) and one SCOPED signature per managed
+    // project's bucket, so a `server/**` add no longer recycles a `web/**` vite (see `sourceScopeDirs`). One
+    // scan per bucket, not per project — sibling projects in a bucket share a scope, so `web/apps/dashboard`
+    // and `web/apps/authentication` cost a single walk between them.
     const maybeScanSourceSet = () => {
         if (scanInFlight || Date.now() - lastScanAt < types_1.POD_STALE_SCAN_MS)
             return;
         scanInFlight = true;
         lastScanAt = Date.now();
-        void sourceSetSignature(rt.root)
-            .then((sig) => {
-            if (prevSig !== undefined && sig !== prevSig) {
+        void (async () => {
+            // 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' });
             }
-            prevSig = sig;
-        })
+            prevSig = wide;
+            // Scoped tier. Skipped entirely without project roots (nothing to narrow by) — consumers then read
+            // the wide clock exactly as before.
+            if (!rt.projectRoots)
+                return;
+            let topLevel;
+            try {
+                topLevel = (await fs.promises.readdir(rt.root, { withFileTypes: true }))
+                    .filter((e) => e.isDirectory()).map((e) => e.name);
+            }
+            catch {
+                return;
+            }
+            const managed = managedBuckets();
+            const projects = new Set(rt.services.map((s) => s.project));
+            for (const r of rt.routes)
+                if (r.lens)
+                    projects.add(r.lens.project);
+            // 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, extraExclude);
+                if (!dirs)
+                    continue;
+                const key = dirs.join('|');
+                const entry = byBucket.get(key) ?? { dirs, projects: [] };
+                entry.projects.push(project);
+                byBucket.set(key, entry);
+            }
+            const now = Date.now();
+            for (const [key, { dirs, projects: sharing }] of byBucket) {
+                const sig = await sourceSetSignature(rt.root, dirs, extraExclude);
+                const prev = prevScopedSig.get(key);
+                prevScopedSig.set(key, sig);
+                if (prev === undefined || sig === prev)
+                    continue;
+                rt.sourceSetChangedFor ??= new Map();
+                for (const p of sharing)
+                    rt.sourceSetChangedFor.set(p, now);
+                emit('info', `source file set changed in ${sharing.join(', ')}'s scope`, 'cluster-gateway', { kind: 'source-set-changed', scoped: true, projects: sharing });
+            }
+        })()
             .catch(() => undefined)
             .finally(() => { scanInFlight = false; });
     };
@@ -595,7 +780,10 @@ function createServiceLayer(rt, obs) {
                     // stale — neither exit-respawn nor wedge-recycle sees it. Idle-gated in podRecycleReason so a busy
                     // pod is never interrupted.
                     if (live && !coldStarting && types_1.POD_RECYCLE_ENABLED) {
-                        const reason = podRecycleReason(svc, Date.now(), rt.sourceSetChangedAt ?? 0, recycleCfg);
+                        // Prefer this project's SCOPED clock (only the subtrees it can resolve); fall back to the
+                        // workspace-wide one when the scan hasn't produced a scoped verdict for it.
+                        const changedAt = rt.sourceSetChangedFor?.get(svc.project) ?? rt.sourceSetChangedAt ?? 0;
+                        const reason = podRecycleReason(svc, Date.now(), changedAt, recycleCfg);
                         if (reason)
                             recyclePod(svc, reason);
                     }

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,CA8RxB"}
+{"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"}