@lensmcp/cluster 1.18.4 → 1.18.7

package/executors/gateway/runtime/lifecycle.js

@@ -1,842 +1,3 @@
-"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");
-/**
- * Service lifecycle: scale-from-zero, autoscale, idle kill. The gateway is the
- * load balancer in front of each pod service's unix-socket pool and owns the
- * pods' serverless lifecycle (eager/minPods/maxPods/idleKillSec).
- */
-const node_child_process_1 = require("node:child_process");
-const fs = tslib_1.__importStar(require("node:fs"));
-const http = tslib_1.__importStar(require("node:http"));
-const path = tslib_1.__importStar(require("node:path"));
-const 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");
-/**
- * The east-west env a pod needs to call ANOTHER service's `internal.<host>` route (memberships, settings,
- * plan): (1) its OWN per-service key — presented as `x-api-key`; the gateway maps it back to the caller and
- * stamps `x-api-key-id` (a service can't forge another's identity). (2) `NODE_EXTRA_CA_CERTS` = the
- * MACHINE-LEVEL dev CA (`~/.lensmcp/ca`), so the pod's OUTBOUND `fetch('https://internal.<host>')` clears
- * TLS — and keeps clearing it across daemon handovers, since every daemon on the machine signs with that
- * same anchor (a per-workspace path here once broke pods that outlived a guest→own-daemon switch). Without
- * these the call fails (connect/TLS or a gateway 401) and tenant-token minting can't resolve the role.
- * NOT `INTERNAL_API_KEY`/`LENSMCP_INTERNAL_TOKEN` (those would flip ON the inbound gateway-trust guard) —
- * a DEDICATED name a service opts into for OUTBOUND only, leaving inbound dev-standalone behavior unchanged.
- */
-function eastWestEnv(rt, project) {
-    const env = {};
-    const key = rt.serviceKeys[project];
-    if (key)
-        env.LENSMCP_SERVICE_KEY = key;
-    if (rt.https) {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy like server.ts (cert deps)
-        const basicSsl = require('../../../basic-ssl');
-        const caPath = basicSsl.caCertPath();
-        if (fs.existsSync(caPath))
-            env.NODE_EXTRA_CA_CERTS = caPath;
-    }
-    return env;
-}
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-// --- zombie-pod recycle: source-file-SET signature -------------------------------------------------------
-// A pod goes "stale" when the set of source files CHANGES (a file added/removed) after it spawned and its
-// degraded watcher missed it. We detect a set change — NOT a content change — by a cheap order-independent
-// signature over source file PATHS (count + xor of per-path hashes): adding/removing a path flips the
-// signature; editing a file's CONTENTS does not, so ordinary saves never trigger a recycle.
-// RUNTIME OUTPUT IS NOT SOURCE. The hardcoded list below can only ever name the conventional output dirs;
-// a workspace whose app WRITES into some other gitignored dir under the root would otherwise read every
-// write as "a dev added a source file" and recycle every pod. Worked failure (foodguard, 2026-07-28): the
-// engine's local artifact store defaults to `./artifacts` at the workspace root, so each run's
-// `publish_pack` added pack-manifest + source-snapshot `.json` → the set flipped → the sweeper SIGTERMed all
-// four vite pods → a ~12-18s `gateway.unavailable` 502 window per run (201 dashboard recycles in one
-// session, and it crossed workspaces: the sweeper's viteChildren span every REGISTERED workspace while the
-// scan only walks the daemon host's root). So the set is filtered by git's OWN ignore verdict too.
-const SRC_EXCLUDE = new Set(['node_modules', 'dist', 'tmp', 'coverage', 'build', 'out', 'target']);
-const SRC_EXT = new Set([
-    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.css', '.scss', '.sass', '.less',
-    '.json', '.html', '.htm', '.vue', '.svelte', '.mdx',
-]);
-const SCAN_FILE_CAP = 100_000;
-function fnv1a(s) {
-    let h = 2166136261;
-    for (let i = 0; i < s.length; i += 1) {
-        h ^= s.charCodeAt(i);
-        h = Math.imul(h, 16777619);
-    }
-    return h >>> 0;
-}
-const execFileP = (0, node_util_1.promisify)(node_child_process_1.execFile);
-/** The repo-relative paths git IGNORES — directories carry a trailing `/` (git's `--directory` collapses a
- *  wholly-ignored dir), files do not. ONE `git ls-files` per scan (~80ms on a 2.6k-file workspace, off the
- *  event loop) buys exact gitignore semantics — nested `.gitignore`, `.git/info/exclude`, global excludes —
- *  with no new dependency and no hand-rolled glob matcher. A partially-ignored dir isn't collapsed, so its
- *  individual ignored files are listed and filtered per-file instead. Fails OPEN to an empty set (git absent,
- *  not a repo, timeout) → the hardcoded `SRC_EXCLUDE` list alone still applies, exactly as before. */
-async function gitIgnoredPaths(root) {
-    try {
-        const { stdout } = await execFileP('git', ['ls-files', '--others', '--directory', '--ignored', '--exclude-standard', '-z'], { cwd: root, maxBuffer: 32 * 1024 * 1024, timeout: 10_000, windowsHide: true });
-        return new Set(stdout.split('\0').filter(Boolean)); // -z → NUL-separated, never git's quoted-path form
-    }
-    catch {
-        return new Set();
-    }
-}
-/** 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.
- *
- *  `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, recurse = true) => {
-        if (count > SCAN_FILE_CAP)
-            return;
-        let entries;
-        try {
-            entries = await fs.promises.readdir(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const e of entries) {
-            if (count > SCAN_FILE_CAP)
-                return;
-            const name = e.name;
-            const abs = path.join(dir, name);
-            if (e.isDirectory()) {
-                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/`)
-                await walk(abs);
-            }
-            else if (e.isFile()) {
-                const dot = name.lastIndexOf('.');
-                if (dot <= 0 || !SRC_EXT.has(name.slice(dot)))
-                    continue;
-                if (ignored.has(rel(abs)))
-                    continue; // a gitignored file in a tracked dir (generated reports)
-                count += 1;
-                xor ^= fnv1a(abs);
-            }
-        }
-    };
-    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
- * pod is never interrupted) and past its per-service cooldown. Then it recycles if the source file SET
- * changed after it spawned (`stale-source-set`) or as a plain age backstop (`max-age`). Returns `null` when
- * it must be left alone. Kept pure (no `ServiceCtl` mutation, no fs) so the sweeper's logic is unit-tested
- * without spawning a process. `sourceSetChangedAt` is 0 until the gateway first observes a set change.
- */
-function podRecycleReason(svc, now, sourceSetChangedAt, cfg) {
-    if (!svc.proc || svc.state !== 'up' || svc.spawnAt == null)
-        return null; // only a live, up, spawned pod
-    if (svc.inflight > 0)
-        return null; // never mid-request
-    if (now - svc.lastUsed < cfg.settleMs)
-        return null; // wait for an inter-request lull
-    if (svc.lastStaleRecycleAt != null && now - svc.lastStaleRecycleAt < cfg.cooldownMs)
-        return null; // anti-thrash
-    if (sourceSetChangedAt > 0 && sourceSetChangedAt - svc.spawnAt > cfg.graceMs)
-        return 'stale-source-set';
-    if (cfg.maxAgeMs > 0 && now - svc.spawnAt > cfg.maxAgeMs)
-        return 'max-age';
-    return null;
-}
-/**
- * PURE decision for a LENS-FRONTEND vite child (a `lens:true` app's dev server — the reported zombie). It
- * has no in-flight/idle signal like a pod, so it recycles ONLY on a settled source-file-SET change that
- * POST-dates its spawn (the precise "watcher missed a new file" trigger) — never a blind max-age (which
- * could interrupt active work). `killing` it lets the manager's `on('exit')` auto-heal respawn a fresh vite
- * that re-scans the FS. Kept pure + exported so the recycle logic is unit-tested without a process.
- */
-function lensFrontendStale(spawnedAt, lastRecycleAt, sourceSetChangedAt, now, cfg) {
-    if (now - lastRecycleAt < cfg.cooldownMs)
-        return false; // anti-thrash on a source-churn burst
-    if (sourceSetChangedAt <= 0)
-        return false; // no set change observed yet
-    if (sourceSetChangedAt - spawnedAt <= cfg.graceMs)
-        return false; // this vite already postdates the change
-    if (now - sourceSetChangedAt < cfg.settleMs)
-        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 —
-    // mirrors the pod runtime-event routing below (svc.wsKey === rt.wsKey ? rt.eventFile : <root>/.lensmcp).
-    // The daemon's own services stay on rt.eventFile; a REGISTERED workspace's go to its own bus, so each
-    // hosted dashboard's cluster view (/<key>/api/cluster) is scoped to ITS workspace, not the daemon's
-    // (foodguard/cluster was empty because every service event went to the daemon's tetros bus). Two
-    // workspaces can share a service NAME (both have `auth`), so this MUST key off svc.wsKey, not the project.
-    const serviceBus = (svc) => svc.wsKey === rt.wsKey ? undefined : path.join(svc.root, '.lensmcp', 'events.jsonl');
-    const emitSvc = (svc, severity, title, fingerprint, raw) => emit(severity, title, fingerprint, { wsKey: svc.wsKey, ...raw }, undefined, serviceBus(svc));
-    const scanNow = (pool) => { pool.scannedAt = 0; return (0, discovery_1.pickSock)(pool, rt.scanTtlMs) ? pool.socks.length : 0; };
-    /**
-     * FOREIGN-GENERATION REAPER (the respawn deadlock, foodguard 2026-07-26): nx records a
-     * running continuous task in its workspace-data DB, and a NEW `nx run <svc>:serve-hmr`
-     * invocation WAITS on that record ("Waiting for <task> in another nx process") — even with
-     * NX_DAEMON=false. When the record's holder is an ORPHANED runner (a replaced daemon's
-     * tree, a half-killed generation), every respawn parks forever and `ensureUp` hangs each
-     * request with no log. Before spawning, kill any nx runner for THIS target that this
-     * gateway does not own — the runner is the detached group leader, so `kill(-pgid)` reaps
-     * its whole devserver tree with it. One `ps` exec; a clean cold start is a no-op.
-     */
-    const reapForeignRunners = (svc, target) => {
-        let out;
-        try {
-            out = (0, node_child_process_1.execFileSync)('ps', ['ax', '-ww', '-o', 'pid=,pgid=,command='], { encoding: 'utf8', timeout: 5_000 });
-        }
-        catch {
-            return 0;
-        }
-        const ownPid = svc.proc?.pid;
-        let reaped = 0;
-        for (const line of out.split('\n')) {
-            const m = line.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/);
-            if (!m)
-                continue;
-            const pid = Number(m[1]);
-            const pgid = Number(m[2]);
-            const cmd = m[3];
-            if (!cmd.includes(`run ${target}`))
-                continue; // only THIS service's runners
-            // Only nx runners (direct nx.js entry or the yarn/npx shim) — never a stray grep/editor.
-            if (!/\bnx(\.js)?\b/.test(cmd))
-                continue;
-            // A direct-entry runner carries its workspace's nx path — scope to OUR workspace root so a
-            // same-named project in another workspace is never touched. (The yarn-shim fallback has no
-            // path in argv; the target match alone bounds it.)
-            if (cmd.includes('/node_modules/nx/') && !cmd.includes(svc.root))
-                continue;
-            if (pid === process.pid || pid === ownPid)
-                continue;
-            if (ownPid !== undefined && pgid === ownPid)
-                continue; // our own detached tree
-            try {
-                process.kill(-pgid, 'SIGKILL');
-            }
-            catch {
-                try {
-                    process.kill(pid, 'SIGKILL');
-                }
-                catch { /* already gone */ }
-            }
-            reaped += 1;
-        }
-        if (reaped > 0) {
-            console.log(`[gateway] ${target}: reaped ${reaped} stale runner tree(s) — a foreign generation held the nx task lock`);
-            emitSvc(svc, 'warning', `stale-runner reap: ${svc.project} (${reaped} foreign tree(s))`, `cluster-service:${svc.project}`, { kind: 'stale-runner-reap', project: svc.project, reaped });
-        }
-        return reaped;
-    };
-    const spawnService = (svc) => {
-        if (rt.stopped())
-            return; // never spawn a process after the gateway is told to stop
-        const target = `${svc.project}:${svc.decl.serveTarget ?? 'serve-hmr'}`;
-        const min = Math.max(1, svc.decl.minPods ?? 1);
-        reapForeignRunners(svc, target); // clear nx's running-tasks lock BEFORE the spawn can park on it
-        svc.lockBlockedAt = undefined;
-        console.log(`[gateway] starting ${target} (pods=${min})…`);
-        emitSvc(svc, 'info', `service starting: ${svc.project} (${min} pod${min > 1 ? 's' : ''})`, `cluster-service:${svc.project}`, { kind: 'service-starting', project: svc.project, pods: min });
-        svc.state = 'starting';
-        svc.spawnAt = Date.now();
-        // childCount goes as a CLI option, NOT env: nx executes tasks via its
-        // daemon, whose environment is not the gateway's — env vars get lost.
-        // Invoke the workspace's nx entry DIRECTLY (node + nx/dist/bin/nx.js) instead of through the
-        // `yarn nx` shim: the shim is a ~40MB node process that does nothing after the handoff yet
-        // lives for the service's whole life — ~600MB across a 15-service cluster. Resolved per
-        // svc.root so each hosted workspace runs its own nx; falls back to `yarn nx` when the entry
-        // isn't where node_modules linkers put it (pnp/odd layouts).
-        const nxEntry = path.join(svc.root, 'node_modules', 'nx', 'dist', 'bin', 'nx.js');
-        const [spawnCmd, spawnArgs] = fs.existsSync(nxEntry)
-            ? [process.execPath, [nxEntry, 'run', target, `--childCount=${min}`]]
-            : ['yarn', ['nx', 'run', target, `--childCount=${min}`]];
-        const proc = (0, node_child_process_1.spawn)(spawnCmd, spawnArgs, {
-            // The service's OWN workspace root — `rt.root` for the daemon's own workspace, the registered
-            // workspace's root for a second one (so ONE daemon hosts several workspaces' devservers — model (A)).
-            cwd: svc.root,
-            detached: true,
-            // NX_DAEMON=false keeps the serve task IN this spawned process group.
-            // With the daemon on, Nx hands the long-running task to the persistent
-            // daemon (a DIFFERENT group), so the later process-group kill reaps only
-            // the `yarn nx` shim and orphans the devserver + pod tree — the classic
-            // "idle-kill leaves live pods" leak. (--childCount as a CLI arg already
-            // avoids the env-loss the daemon was relied on for.) NX_DAEMON=false also
-            // means env vars DO reach the pod, so the east-west key + CA propagate.
-            // LENSMCP_WS_KEY (the SERVICE's owning workspace) namespaces its pod sock dir
-            // ($TMPDIR/<wsKey>/<service>-devserver) — the namespaced pool the daemon scans for this fragment.
-            // LENSMCP_EVENT_FILE points a REGISTERED workspace's pods at ITS OWN bus (<root>/.lensmcp/events.jsonl),
-            // so its dashboard shows its live traces, not the daemon's. The daemon's own services keep rt.eventFile
-            // exactly (svc.root === rt.root), so single-workspace behavior is unchanged.
-            env: {
-                // FOREIGN-POD ENV SCRUB (pod-env.ts): a registered workspace's pod must NOT inherit the daemon
-                // host's dotenv-loaded env (nx never overrides an already-set var, so foodguard's PG_URL/REDIS_URL
-                // riding the daemon once pointed tetros's auth+iam at foodguard's stores). The daemon's own
-                // workspace keeps the full inherit — its pods reload the same files anyway.
-                ...(0, pod_env_1.podBaseEnv)(process.env, rt.root, svc.root),
-                NX_DAEMON: 'false',
-                // NX_ISOLATE_PLUGINS=false: with the daemon off (above), EVERY serve client builds the
-                // project graph itself — and with plugin isolation on (nx's default) each client spawns
-                // 8 plugin-worker processes (~50MB each) that stay ALIVE for the life of the service:
-                // ~400MB of nx machinery per ~50MB service pod, ~4-5GB across a 13-service cluster
-                // (measured tetros 2026-07-25). Isolation-off loads plugins in-process: the graph is
-                // identical and zero workers spawn (nx itself runs isolation-off in sandboxes/WASM —
-                // a supported mode). NOTE this is authoritative for spawned clients: nx's dotenv load
-                // never overrides an already-set env var, so a workspace .env cannot flip it back on.
-                NX_ISOLATE_PLUGINS: 'false',
-                ...(svc.wsKey ? { LENSMCP_WS_KEY: svc.wsKey } : {}),
-                LENSMCP_EVENT_FILE: svc.wsKey === rt.wsKey ? rt.eventFile : path.join(svc.root, '.lensmcp', 'events.jsonl'),
-                // Rides the env inherit down the whole nx chain (nx run → run-executor → serve fork) into
-                // main.devserver, whose gateway watchdog self-exits the pod tree when this pid dies. Without
-                // it an UNGRACEFUL gateway death (crash/SIGKILL — no process-group kill runs) orphans the
-                // entire chain under launchd forever (2026-07-28: a day-old tetros pod tree at PPID 1).
-                LENSMCP_GATEWAY_PID: String(process.pid),
-                ...eastWestEnv(rt, svc.project),
-            },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        svc.lastErrors = [];
-        svc.buildFailed = false;
-        const sniff = (d) => {
-            const text = d.toString();
-            for (const line of text.split('\n')) {
-                if (/ERROR in |error TS\d+|Found \d+ error|Unhandled 'error' event|EADDRINUSE/.test(line)) {
-                    // eslint-disable-next-line no-control-regex -- strip ANSI color codes from child output
-                    const clean = line.replace(/\x1b\[[0-9;]*m/g, '').trim();
-                    svc.lastErrors.push(clean);
-                    if (svc.lastErrors.length > 12)
-                        svc.lastErrors.shift();
-                    svc.buildFailed = true;
-                    // THROTTLE: a crash-looping pod re-prints the same error line on every restart. Emit the
-                    // 'service error' event only when the error line CHANGES or after the throttle window —
-                    // otherwise the bus (and the lens log) floods with identical errors many times a second.
-                    const now = Date.now();
-                    if (clean !== svc.lastErrorEmitSig || now - (svc.lastErrorEmitAt ?? 0) >= types_1.SERVICE_ERROR_THROTTLE_MS) {
-                        svc.lastErrorEmitSig = clean;
-                        svc.lastErrorEmitAt = now;
-                        emitSvc(svc, 'error', `service error: ${svc.project}`, `cluster-service:${svc.project}`, { kind: 'service-error', project: svc.project, line: clean });
-                    }
-                }
-                if (/No typescript errors found|webpack compiled successfully|Child#\d+ ready/.test(line))
-                    svc.buildFailed = false;
-                // LOCK-BREAK: nx prints exactly this when a FOREIGN runner holds the running-tasks
-                // record for our target — this spawn will park forever and every request would hang
-                // through ensureUp with no further log. Cure it once per spawn: kill our parked
-                // waiter, reap the foreign tree, and respawn clean.
-                if (!svc.lockBlockedAt && /Waiting for .+ in another nx process/.test(line)) {
-                    svc.lockBlockedAt = Date.now();
-                    console.log(`[gateway] ${target}: spawn blocked by a stale nx runner — breaking the lock + respawning`);
-                    emitSvc(svc, 'warning', `nx task lock: ${svc.project} blocked by a stale runner — auto-breaking`, `cluster-service:${svc.project}`, { kind: 'nx-lock-break', project: svc.project });
-                    setTimeout(() => {
-                        if (rt.stopped() || !svc.lockBlockedAt)
-                            return;
-                        killSpawned(svc, 'parked on a foreign nx task lock — recycling', { announce: false }); // a recycle: `nx-lock-break` above is the report
-                        reapForeignRunners(svc, target);
-                        setTimeout(() => {
-                            if (!rt.stopped() && !svc.proc && svc.state === 'down')
-                                spawnService(svc);
-                        }, 1_500).unref?.();
-                    }, 250).unref?.();
-                }
-            }
-        };
-        proc.stdout?.on('data', (d) => { if (rt.stopped())
-            return; sniff(d); process.stdout.write(`[${svc.project}] ${d}`); });
-        proc.stderr?.on('data', (d) => { if (rt.stopped())
-            return; sniff(d); process.stderr.write(`[${svc.project}] ${d}`); });
-        proc.on('exit', (code) => {
-            svc.proc = undefined;
-            svc.state = 'down';
-            if (rt.stopped())
-                return; // gateway is tearing down — its dying services' exit chatter is noise
-            console.log(`[gateway] ${target} exited (${code})`);
-            emitSvc(svc, code === 0 ? 'info' : 'warning', `service down: ${svc.project} (exit ${code})`, `cluster-service:${svc.project}`, { kind: 'service-down', project: svc.project, code });
-            // SELF-HEAL: respawn an UNEXPECTEDLY-crashed pod so a transient failure recovers with no manual
-            // restart. A clean exit (code 0) or a sniffed BUILD failure (a code error → a fix, not a transient
-            // crash) is left down — scale-from-zero (ensureUp) still spawns it on the next request. A crash-loop
-            // guard (≤ SERVICE_MAX_RESTARTS within the window, exponential backoff) stops a broken service
-            // hot-looping the CPU.
-            if (code === 0 || svc.buildFailed)
-                return;
-            const now = Date.now();
-            svc.restarts = (svc.restarts ?? []).filter((t) => now - t < types_1.SERVICE_RESTART_WINDOW_MS);
-            if (svc.restarts.length >= types_1.SERVICE_MAX_RESTARTS) {
-                emitSvc(svc, 'error', `service crash-looping: ${svc.project} — ${types_1.SERVICE_MAX_RESTARTS}+ restarts/min, not auto-respawning (the next request retries)`, `cluster-service:${svc.project}`, { kind: 'service-crash-loop', project: svc.project });
-                return;
-            }
-            svc.restarts.push(now);
-            const backoffMs = Math.min(8000, 500 * 2 ** (svc.restarts.length - 1)); // 0.5 → 1 → 2 → 4 → 8s
-            setTimeout(() => {
-                if (rt.stopped() || svc.proc || svc.state !== 'down')
-                    return; // a request already respawned it, or teardown
-                console.log(`[gateway] self-heal: respawning ${svc.project} (restart ${svc.restarts.length}/${types_1.SERVICE_MAX_RESTARTS})`);
-                emitSvc(svc, 'info', `self-heal: respawning ${svc.project}`, `cluster-service:${svc.project}`, { kind: 'service-respawn', project: svc.project, attempt: svc.restarts.length });
-                spawnService(svc);
-            }, backoffMs);
-        });
-        svc.proc = proc;
-    };
-    /**
-     * The RECOVERY edge — the counterpart to `service-down`/`service-recycle`/`pod-recycle`.
-     *
-     * The gateway used to announce a service going UP from exactly two places, both inside
-     * `ensureUp`: the adopt fast-path and the cold-start wait loop. But the proxy only calls
-     * `ensureUp` when `pickSock` came back EMPTY — so a service that self-healed on its own (the
-     * exit auto-heal respawn, a recycled pod re-binding, an externally-started devserver) was never
-     * announced. Its `svc.state` stayed `'starting'` and the lens fold behind `process://cluster`
-     * latched on the last DEGRADATION forever: `agent://current-status` reported `failing` while the
-     * app served every request (foodguard 2026-07-31 — four services `starting`, `up: []`, 20×200,
-     * 0×502).
-     *
-     * So the transition lives here, callable from every place that observes a live pod, and the
-     * evidence is the SAME socket scan the wedge detector uses (`live = scanNow(pool) > 0`) — the
-     * detector that clears `wedgedSince` must also be the one that records `up`, or the two disagree.
-     * Idempotent, so the per-request call costs one property compare.
-     */
-    const markUp = (svc, how) => {
-        if (svc.state === 'up')
-            return false;
-        svc.state = 'up';
-        const pods = svc.pool.socks.length;
-        emitSvc(svc, 'info', `service up: ${svc.project} (${pods} pods, ${how})`, `cluster-service:${svc.project}`, { kind: 'service-up', project: svc.project, pods, adopted: how === 'adopted' });
-        return true;
-    };
-    const ensureUp = async (svc) => {
-        if (scanNow(svc.pool) > 0) {
-            markUp(svc, 'adopted');
-            return true;
-        }
-        if (rt.stopped())
-            return false;
-        if (svc.state !== 'starting' && !svc.proc)
-            spawnService(svc); // a live spawn supervises itself — don't stack a second one (EADDRINUSE)
-        const deadline = Date.now() + rt.startupTimeoutMs;
-        const failFastAt = Date.now() + 12_000; // a build error within 12s → stop waiting, report the cause
-        while (!rt.stopped() && Date.now() < deadline) {
-            await sleep(Math.min(700, rt.startupTimeoutMs / 4));
-            if (svc.buildFailed && Date.now() > failFastAt)
-                return false;
-            if (scanNow(svc.pool) > 0) {
-                svc.state = 'up';
-                svc.buildFailed = false;
-                const durationMs = svc.spawnAt ? Date.now() - svc.spawnAt : undefined;
-                console.log(`[gateway] ${svc.project} up (${svc.pool.socks.length} pods${durationMs ? `, cold start ${durationMs}ms` : ''})`);
-                emitSvc(svc, 'info', `cold start: ${svc.project} (${svc.pool.socks.length} pods, ${durationMs ?? '?'}ms)`, `cluster-service:${svc.project}`, { kind: 'cold-start', project: svc.project, pods: svc.pool.socks.length, durationMs });
-                return true;
-            }
-            if (svc.state === 'down')
-                return false; // spawn died
-        }
-        return false;
-    };
-    const scaleUp = (svc) => {
-        const max = svc.decl.maxPods ?? svc.decl.minPods ?? 1;
-        const cur = svc.pool.socks.length;
-        const admin = svc.decl.adminUrl ?? (svc.decl.port ? `http://localhost:${svc.decl.port}` : undefined);
-        if (!admin || cur === 0 || cur >= max || svc.inflight <= cur)
-            return;
-        if (Date.now() - svc.lastScaleAt < 5000)
-            return;
-        svc.lastScaleAt = Date.now();
-        const mod = admin.startsWith('https')
-            ? // eslint-disable-next-line @typescript-eslint/no-require-imports
-                require('node:https')
-            : http;
-        const r = mod.request(`${admin}/webpack/scale`, { method: 'POST', rejectUnauthorized: false }, (rs) => rs.resume());
-        r.on('error', () => undefined);
-        r.end(JSON.stringify({ pods: cur + 1 }));
-        console.log(`[gateway] autoscale ${svc.project}: ${cur} → ${cur + 1} pods (inflight ${svc.inflight})`);
-        emitSvc(svc, 'info', `autoscale: ${svc.project} ${cur} → ${cur + 1} pods`, `cluster-service:${svc.project}`, { kind: 'autoscale', project: svc.project, from: cur, to: cur + 1, inflight: svc.inflight });
-    };
-    // Idle sweeper: kill gateway-spawned lazy services after idleKillSec.
-    //
-    // `announce: false` for a caller that is TEARING THE TREE DOWN AS PART OF A RECYCLE. This function
-    // is the shared teardown for two different intents — "park this service, it's idle" and "kill this
-    // service, it's broken" — and the `idle-kill` event only describes the first. A recycle caller has
-    // ALREADY announced the real reason (`service-recycle` / `pod-recycle` / `service-crash-loop`), and
-    // an `idle-kill` on top would OVERWRITE that fault in the lens fold with a benign `idle` — the
-    // crash-loop and wedge reports would vanish milliseconds after they were raised. It also read wrong
-    // in the log ("idle kill: auth (wedged: 0 live pods — recycling)").
-    const killSpawned = (svc, why, opts) => {
-        if (!svc.proc)
-            return;
-        console.log(`[gateway] ${svc.project} ${why} — scaling to zero.`);
-        if (opts?.announce !== false) {
-            emitSvc(svc, 'info', `idle kill: ${svc.project} (${why})`, `cluster-service:${svc.project}`, { kind: 'idle-kill', project: svc.project, why });
-        }
-        const dying = svc.proc;
-        // Detach the corpse's handlers BEFORE killing: a dying webpack/nx flushes
-        // buffered stdout/stderr as it exits, and those `sniff` callbacks would
-        // keep mutating svc.lastErrors/buildFailed (phantom build failures) — fatal
-        // if a fresh request re-spawns this same svc while the corpse still flushes.
-        try {
-            dying.stdout?.removeAllListeners('data');
-            dying.stderr?.removeAllListeners('data');
-            dying.removeAllListeners('exit');
-        }
-        catch { /* ignore */ }
-        try {
-            process.kill(-dying.pid, 'SIGTERM');
-        }
-        catch {
-            try {
-                dying.kill('SIGTERM');
-            }
-            catch { /* gone */ }
-        }
-        svc.proc = undefined;
-        svc.state = 'down';
-        // children die with the tree but their sock FILES survive — remove them so the canvas
-        // and the proxy never see ghost pods. OWNER-AWARE: a sock whose `.owner` pidfile names a
-        // LIVE process belongs to a NEWER generation binding concurrently — leave it (the
-        // devserver's bind-steal owns the path now; unlinking it here recreates the vanished-sock
-        // wedge this sweep exists to prevent).
-        setTimeout(() => {
-            try {
-                for (const f of fs.readdirSync(svc.pool.dir)) {
-                    if (!f.endsWith('.sock'))
-                        continue;
-                    const sockPath = path.join(svc.pool.dir, f);
-                    try {
-                        const owner = Number(fs.readFileSync(`${sockPath}.owner`, 'utf8').trim());
-                        if (Number.isFinite(owner) && owner > 0) {
-                            try {
-                                process.kill(owner, 0); // throws when the owner is dead
-                                continue; // a LIVE foreign owner — a newer generation's pod; keep it
-                            }
-                            catch { /* dead owner → sweep */ }
-                        }
-                    }
-                    catch { /* no owner file (legacy) → sweep */ }
-                    try {
-                        fs.unlinkSync(sockPath);
-                    }
-                    catch { /* gone */ }
-                    try {
-                        fs.unlinkSync(`${sockPath}.owner`);
-                    }
-                    catch { /* gone */ }
-                }
-            }
-            catch { /* dir gone */ }
-            svc.pool.socks = [];
-            svc.pool.scannedAt = 0;
-        }, 1200).unref?.();
-    };
-    // SELF-HEAL a WEDGED service: its gateway-spawned parent is ALIVE but 0 pods are live — an HMR hot-swap
-    // (or the proxy wedge/connection evict) unlinked the child socket, and `ensureUp` won't respawn because
-    // its `!svc.proc` guard sees the alive parent (the "ghost-socket zombie" — the evict→respawn gap). Kill
-    // the wedged tree (killSpawned clears svc.proc + unlinks stale socks) then respawn a fresh pod. A
-    // crash-loop cap (shared with the exit-self-heal) stops a genuinely-broken service hot-looping.
-    const recycleWedged = (svc) => {
-        const now = Date.now();
-        svc.restarts = (svc.restarts ?? []).filter((t) => now - t < types_1.SERVICE_RESTART_WINDOW_MS);
-        if (svc.restarts.length >= types_1.SERVICE_MAX_RESTARTS) {
-            emitSvc(svc, 'error', `service crash-looping: ${svc.project} — wedged ${types_1.SERVICE_MAX_RESTARTS}+×/min, not auto-recycling (the next request retries)`, `cluster-service:${svc.project}`, { kind: 'service-crash-loop', project: svc.project });
-            killSpawned(svc, 'wedged (crash-loop cap) — leaving down for the next request', { announce: false }); // svc.proc cleared → scale-from-zero can retry
-            return;
-        }
-        svc.restarts.push(now);
-        console.log(`[gateway] self-heal: recycling WEDGED ${svc.project} (live parent, 0 live pods; ${svc.restarts.length}/${types_1.SERVICE_MAX_RESTARTS})`);
-        emitSvc(svc, 'warning', `self-heal: recycling wedged ${svc.project} (0 live pods)`, `cluster-service:${svc.project}`, { kind: 'service-recycle', project: svc.project, attempt: svc.restarts.length });
-        killSpawned(svc, 'wedged: 0 live pods — recycling', { announce: false }); // kills the tree + unlinks stale socks (+1200ms) + svc.proc=undefined + state='down'
-        // A wedge is unexpected — bring it straight back (don't wait for a request). Respawn AFTER killSpawned's
-        // deferred sock cleanup (1200ms) so the fresh child binds a clean socket path.
-        setTimeout(() => {
-            if (!rt.stopped() && !svc.proc && svc.state === 'down')
-                spawnService(svc);
-        }, 1500).unref?.();
-    };
-    // --- zombie-pod recycle: source-set-change tracking + a fresh-pod recycle for a live-but-stale pod ------
-    const recycleCfg = {
-        maxAgeMs: types_1.POD_MAX_AGE_MS, graceMs: types_1.POD_STALE_GRACE_MS,
-        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;
-    /** 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 (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 = 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; });
-    };
-    // Recycle a live-but-STALE-VIEW pod (alive + reachable, yet its watcher missed post-spawn file adds).
-    // Kill it → scale-from-zero (or eager respawn) → a fresh pod re-scans the FS. NOT counted against the
-    // crash-loop cap (staleness ≠ crash); the per-service cooldown ({@link podRecycleReason}) stops thrash.
-    const recyclePod = (svc, reason) => {
-        svc.lastStaleRecycleAt = Date.now();
-        console.log(`[gateway] zombie recycle: ${svc.project} (${reason}) — stale fs view; fresh pod incoming`);
-        emitSvc(svc, 'warning', `zombie recycle: ${svc.project} (${reason})`, `cluster-service:${svc.project}`, { kind: 'pod-recycle', project: svc.project, reason });
-        const eager = !!svc.decl.eager;
-        killSpawned(svc, `${reason} — recycling stale pod`, { announce: false }); // clears proc, state='down', unlinks socks (+1200ms)
-        if (eager)
-            setTimeout(() => { if (!rt.stopped() && !svc.proc && svc.state === 'down')
-                spawnService(svc); }, 1500).unref?.();
-    };
-    const startSweeper = () => {
-        const sweeper = setInterval(() => {
-            if (rt.stopped())
-                return;
-            if (types_1.POD_RECYCLE_ENABLED)
-                maybeScanSourceSet();
-            for (const svc of rt.services) {
-                if (rt.stopped() || !svc.proc) {
-                    svc.wedgedSince = undefined;
-                    continue;
-                }
-                const idle = svc.decl.idleKillSec;
-                // Idle kill (unchanged): scale a lazy service to zero after its idle window.
-                if (idle && svc.inflight === 0 && Date.now() - svc.lastUsed > idle * 1000) {
-                    killSpawned(svc, `idle ${idle}s`);
-                    svc.wedgedSince = undefined;
-                    continue;
-                }
-                // WEDGE detection: a live parent with 0 live pods that is NOT legitimately cold-starting is wedged.
-                const coldStarting = svc.state === 'starting' && svc.spawnAt !== undefined && Date.now() - svc.spawnAt < rt.startupTimeoutMs;
-                const live = scanNow(svc.pool) > 0;
-                if (live || coldStarting) {
-                    svc.wedgedSince = undefined;
-                    // RECOVERY EDGE. `live` is the exact evidence that just cleared `wedgedSince`, so it must
-                    // also record the service as UP — otherwise the gateway silently forgives a wedge while
-                    // the lens fold stays latched on it. This is the path that heals a service which came
-                    // back WITHOUT a request (the exit auto-heal respawn), since nothing else calls `ensureUp`
-                    // once a pod socket exists. Idempotent: after the first tick it is a property compare.
-                    if (live)
-                        markUp(svc, 'observed');
-                    // ZOMBIE recycle: a live pod (live parent + live socket, answers requests) whose fs view went
-                    // 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) {
-                        // 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);
-                    }
-                    continue;
-                }
-                svc.wedgedSince ??= Date.now();
-                if (Date.now() - svc.wedgedSince > types_1.WEDGE_RECYCLE_GRACE_MS) {
-                    svc.wedgedSince = undefined;
-                    recycleWedged(svc);
-                }
-            }
-        }, rt.sweepMs);
-        sweeper.unref();
-        return sweeper;
-    };
-    return { scanNow, spawnService, ensureUp, scaleUp, killSpawned, markUp, startSweeper };
-}
+"use strict";var N=Object.defineProperty;var j=(t,c)=>N(t,"name",{value:c,configurable:!0});var I=Object.defineProperty,s=j((t,c)=>I(t,"name",{value:c,configurable:!0}),"s");Object.defineProperty(exports,"__esModule",{value:!0}),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"),node_child_process_1=require("node:child_process"),fs=tslib_1.__importStar(require("node:fs")),http=tslib_1.__importStar(require("node:http")),path=tslib_1.__importStar(require("node:path")),node_util_1=require("node:util"),discovery_1=require("./discovery"),scope_1=require("./scope"),pod_env_1=require("./pod-env"),types_1=require("./types");function eastWestEnv(t,c){const l={},p=t.serviceKeys[c];if(p&&(l.LENSMCP_SERVICE_KEY=p),t.https){const a=require("../../../basic-ssl").caCertPath();fs.existsSync(a)&&(l.NODE_EXTRA_CA_CERTS=a)}return l}j(eastWestEnv,"eastWestEnv"),s(eastWestEnv,"eastWestEnv");const sleep=s(t=>new Promise(c=>setTimeout(c,t)),"sleep"),SRC_EXCLUDE=new Set(["node_modules","dist","tmp","coverage","build","out","target"]),SRC_EXT=new Set([".ts",".tsx",".js",".jsx",".mjs",".cjs",".css",".scss",".sass",".less",".json",".html",".htm",".vue",".svelte",".mdx"]),SCAN_FILE_CAP=1e5;function fnv1a(t){let c=2166136261;for(let l=0;l<t.length;l+=1)c^=t.charCodeAt(l),c=Math.imul(c,16777619);return c>>>0}j(fnv1a,"fnv1a"),s(fnv1a,"fnv1a");const execFileP=(0,node_util_1.promisify)(node_child_process_1.execFile);async function gitIgnoredPaths(t){try{const{stdout:c}=await execFileP("git",["ls-files","--others","--directory","--ignored","--exclude-standard","-z"],{cwd:t,maxBuffer:33554432,timeout:1e4,windowsHide:!0});return new Set(c.split("\0").filter(Boolean))}catch{return new Set}}j(gitIgnoredPaths,"gitIgnoredPaths"),s(gitIgnoredPaths,"gitIgnoredPaths");async function sourceSetSignature(t,c,l){let p=0,a=0;const v=await gitIgnoredPaths(t),_=s(f=>path.relative(t,f).split(path.sep).join("/"),"rel"),S=s(async(f,k=!0)=>{if(p>SCAN_FILE_CAP)return;let M;try{M=await fs.promises.readdir(f,{withFileTypes:!0})}catch{return}for(const y of M){if(p>SCAN_FILE_CAP)return;const m=y.name,A=path.join(f,m);if(y.isDirectory()){if(!k||m.startsWith(".")||SRC_EXCLUDE.has(m)||l?.has(m)||m.endsWith("-devserver")||v.has(`${_(A)}/`))continue;await S(A)}else if(y.isFile()){const R=m.lastIndexOf(".");if(R<=0||!SRC_EXT.has(m.slice(R))||v.has(_(A)))continue;p+=1,a^=fnv1a(A)}}},"walk");if(c&&c.length>0){await S(t,!1);for(const f of c)await S(f)}else await S(t);return`${p}:${(a>>>0).toString(36)}`}j(sourceSetSignature,"sourceSetSignature"),s(sourceSetSignature,"sourceSetSignature");function sourceScopeDirs(t,c,l,p,a){const v=s(f=>{const k=path.relative(t,f).split(path.sep).filter(Boolean);return k.length===0||k[0].startsWith("..")?"":k[0]},"bucketOf")(c);if(!v)return[];const _=new Set(l.filter(Boolean)),S=new Set([v]);for(const f of p)f.startsWith(".")||SRC_EXCLUDE.has(f)||a?.has(f)||f.endsWith("-devserver")||_.has(f)||S.add(f);return[...S].sort().map(f=>path.join(t,f))}j(sourceScopeDirs,"sourceScopeDirs"),s(sourceScopeDirs,"sourceScopeDirs");function podRecycleReason(t,c,l,p){return!t.proc||t.state!=="up"||t.spawnAt==null||t.inflight>0||c-t.lastUsed<p.settleMs||t.lastStaleRecycleAt!=null&&c-t.lastStaleRecycleAt<p.cooldownMs?null:l>0&&l-t.spawnAt>p.graceMs?"stale-source-set":p.maxAgeMs>0&&c-t.spawnAt>p.maxAgeMs?"max-age":null}j(podRecycleReason,"podRecycleReason"),s(podRecycleReason,"podRecycleReason");function lensFrontendStale(t,c,l,p,a){return!(p-c<a.cooldownMs||l<=0||l-t<=a.graceMs||p-l<a.settleMs)}j(lensFrontendStale,"lensFrontendStale"),s(lensFrontendStale,"lensFrontendStale");function lensChildWedged(t,c,l,p){return l-t.spawnedAt<p.graceMs||l-c<p.cooldownMs||t.probeFails<Math.max(2,p.failureThreshold)?null:"wedged-no-listener"}j(lensChildWedged,"lensChildWedged"),s(lensChildWedged,"lensChildWedged");function isPortConflictExit(t,c){return t.signal||t.code===null||t.code===0||t.ranMs>c.fastFailMs?!1:t.portHeld}j(isPortConflictExit,"isPortConflictExit"),s(isPortConflictExit,"isPortConflictExit");function createServiceLayer(t,c){const{emit:l}=c,p=s(e=>e.wsKey===t.wsKey?void 0:path.join(e.root,".lensmcp","events.jsonl"),"serviceBus"),a=s((e,o,r,n,i)=>l(o,r,n,{wsKey:e.wsKey,...i},void 0,p(e)),"emitSvc"),v=s(e=>(e.scannedAt=0,(0,discovery_1.pickSock)(e,t.scanTtlMs)?e.socks.length:0),"scanNow"),_=s((e,o)=>{let r;try{r=(0,node_child_process_1.execFileSync)("ps",["ax","-ww","-o","pid=,pgid=,command="],{encoding:"utf8",timeout:5e3})}catch{return 0}const n=e.proc?.pid;let i=0;for(const d of r.split(`
+`)){const w=d.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/);if(!w)continue;const g=Number(w[1]),u=Number(w[2]),h=w[3];if(h.includes(`run ${o}`)&&/\bnx(\.js)?\b/.test(h)&&!(h.includes("/node_modules/nx/")&&!h.includes(e.root))&&!(g===process.pid||g===n)&&!(n!==void 0&&u===n)){try{process.kill(-u,"SIGKILL")}catch{try{process.kill(g,"SIGKILL")}catch{}}i+=1}}return i>0&&(console.log(`[gateway] ${o}: reaped ${i} stale runner tree(s) \u2014 a foreign generation held the nx task lock`),a(e,"warning",`stale-runner reap: ${e.project} (${i} foreign tree(s))`,`cluster-service:${e.project}`,{kind:"stale-runner-reap",project:e.project,reaped:i})),i},"reapForeignRunners"),S=s(e=>{if(t.stopped())return;const o=`${e.project}:${e.decl.serveTarget??"serve-hmr"}`,r=Math.max(1,e.decl.minPods??1);_(e,o),e.lockBlockedAt=void 0,console.log(`[gateway] starting ${o} (pods=${r})\u2026`),a(e,"info",`service starting: ${e.project} (${r} pod${r>1?"s":""})`,`cluster-service:${e.project}`,{kind:"service-starting",project:e.project,pods:r}),e.state="starting",e.spawnAt=Date.now();const n=path.join(e.root,"node_modules","nx","dist","bin","nx.js"),[i,d]=fs.existsSync(n)?[process.execPath,[n,"run",o,`--childCount=${r}`]]:["yarn",["nx","run",o,`--childCount=${r}`]],w=(0,node_child_process_1.spawn)(i,d,{cwd:e.root,detached:!0,env:{...(0,pod_env_1.podBaseEnv)(process.env,t.root,e.root),NX_DAEMON:"false",NX_ISOLATE_PLUGINS:"false",...e.wsKey?{LENSMCP_WS_KEY:e.wsKey}:{},LENSMCP_EVENT_FILE:e.wsKey===t.wsKey?t.eventFile:path.join(e.root,".lensmcp","events.jsonl"),LENSMCP_GATEWAY_PID:String(process.pid),...eastWestEnv(t,e.project)},stdio:["ignore","pipe","pipe"]});e.lastErrors=[],e.buildFailed=!1;const g=s(u=>{const h=u.toString();for(const E of h.split(`
+`)){if(/ERROR in |error TS\d+|Found \d+ error|Unhandled 'error' event|EADDRINUSE/.test(E)){const $=E.replace(/\x1b\[[0-9;]*m/g,"").trim();e.lastErrors.push($),e.lastErrors.length>12&&e.lastErrors.shift(),e.buildFailed=!0;const x=Date.now();($!==e.lastErrorEmitSig||x-(e.lastErrorEmitAt??0)>=types_1.SERVICE_ERROR_THROTTLE_MS)&&(e.lastErrorEmitSig=$,e.lastErrorEmitAt=x,a(e,"error",`service error: ${e.project}`,`cluster-service:${e.project}`,{kind:"service-error",project:e.project,line:$}))}/No typescript errors found|webpack compiled successfully|Child#\d+ ready/.test(E)&&(e.buildFailed=!1),!e.lockBlockedAt&&/Waiting for .+ in another nx process/.test(E)&&(e.lockBlockedAt=Date.now(),console.log(`[gateway] ${o}: spawn blocked by a stale nx runner \u2014 breaking the lock + respawning`),a(e,"warning",`nx task lock: ${e.project} blocked by a stale runner \u2014 auto-breaking`,`cluster-service:${e.project}`,{kind:"nx-lock-break",project:e.project}),setTimeout(()=>{t.stopped()||!e.lockBlockedAt||(y(e,"parked on a foreign nx task lock \u2014 recycling",{announce:!1}),_(e,o),setTimeout(()=>{!t.stopped()&&!e.proc&&e.state==="down"&&S(e)},1500).unref?.())},250).unref?.())}},"sniff");w.stdout?.on("data",u=>{t.stopped()||(g(u),process.stdout.write(`[${e.project}] ${u}`))}),w.stderr?.on("data",u=>{t.stopped()||(g(u),process.stderr.write(`[${e.project}] ${u}`))}),w.on("exit",u=>{if(e.proc=void 0,e.state="down",t.stopped()||(console.log(`[gateway] ${o} exited (${u})`),a(e,u===0?"info":"warning",`service down: ${e.project} (exit ${u})`,`cluster-service:${e.project}`,{kind:"service-down",project:e.project,code:u}),u===0||e.buildFailed))return;const h=Date.now();if(e.restarts=(e.restarts??[]).filter($=>h-$<types_1.SERVICE_RESTART_WINDOW_MS),e.restarts.length>=types_1.SERVICE_MAX_RESTARTS){a(e,"error",`service crash-looping: ${e.project} \u2014 ${types_1.SERVICE_MAX_RESTARTS}+ restarts/min, not auto-respawning (the next request retries)`,`cluster-service:${e.project}`,{kind:"service-crash-loop",project:e.project});return}e.restarts.push(h);const E=Math.min(8e3,500*2**(e.restarts.length-1));setTimeout(()=>{t.stopped()||e.proc||e.state!=="down"||(console.log(`[gateway] self-heal: respawning ${e.project} (restart ${e.restarts.length}/${types_1.SERVICE_MAX_RESTARTS})`),a(e,"info",`self-heal: respawning ${e.project}`,`cluster-service:${e.project}`,{kind:"service-respawn",project:e.project,attempt:e.restarts.length}),S(e))},E)}),e.proc=w},"spawnService"),f=s((e,o)=>{if(e.state==="up")return!1;e.state="up";const r=e.pool.socks.length;return a(e,"info",`service up: ${e.project} (${r} pods, ${o})`,`cluster-service:${e.project}`,{kind:"service-up",project:e.project,pods:r,adopted:o==="adopted"}),!0},"markUp"),k=s(async e=>{if(v(e.pool)>0)return f(e,"adopted"),!0;if(t.stopped())return!1;e.state!=="starting"&&!e.proc&&S(e);const o=Date.now()+t.startupTimeoutMs,r=Date.now()+12e3;for(;!t.stopped()&&Date.now()<o;){if(await sleep(Math.min(700,t.startupTimeoutMs/4)),e.buildFailed&&Date.now()>r)return!1;if(v(e.pool)>0){e.state="up",e.buildFailed=!1;const n=e.spawnAt?Date.now()-e.spawnAt:void 0;return console.log(`[gateway] ${e.project} up (${e.pool.socks.length} pods${n?`, cold start ${n}ms`:""})`),a(e,"info",`cold start: ${e.project} (${e.pool.socks.length} pods, ${n??"?"}ms)`,`cluster-service:${e.project}`,{kind:"cold-start",project:e.project,pods:e.pool.socks.length,durationMs:n}),!0}if(e.state==="down")return!1}return!1},"ensureUp"),M=s(e=>{const o=e.decl.maxPods??e.decl.minPods??1,r=e.pool.socks.length,n=e.decl.adminUrl??(e.decl.port?`http://localhost:${e.decl.port}`:void 0);if(!n||r===0||r>=o||e.inflight<=r||Date.now()-e.lastScaleAt<5e3)return;e.lastScaleAt=Date.now();const i=(n.startsWith("https")?require("node:https"):http).request(`${n}/webpack/scale`,{method:"POST",rejectUnauthorized:!1},d=>d.resume());i.on("error",()=>{}),i.end(JSON.stringify({pods:r+1})),console.log(`[gateway] autoscale ${e.project}: ${r} \u2192 ${r+1} pods (inflight ${e.inflight})`),a(e,"info",`autoscale: ${e.project} ${r} \u2192 ${r+1} pods`,`cluster-service:${e.project}`,{kind:"autoscale",project:e.project,from:r,to:r+1,inflight:e.inflight})},"scaleUp"),y=s((e,o,r)=>{if(!e.proc)return;console.log(`[gateway] ${e.project} ${o} \u2014 scaling to zero.`),r?.announce!==!1&&a(e,"info",`idle kill: ${e.project} (${o})`,`cluster-service:${e.project}`,{kind:"idle-kill",project:e.project,why:o});const n=e.proc;try{n.stdout?.removeAllListeners("data"),n.stderr?.removeAllListeners("data"),n.removeAllListeners("exit")}catch{}try{process.kill(-n.pid,"SIGTERM")}catch{try{n.kill("SIGTERM")}catch{}}e.proc=void 0,e.state="down",setTimeout(()=>{try{for(const i of fs.readdirSync(e.pool.dir)){if(!i.endsWith(".sock"))continue;const d=path.join(e.pool.dir,i);try{const w=Number(fs.readFileSync(`${d}.owner`,"utf8").trim());if(Number.isFinite(w)&&w>0)try{process.kill(w,0);continue}catch{}}catch{}try{fs.unlinkSync(d)}catch{}try{fs.unlinkSync(`${d}.owner`)}catch{}}}catch{}e.pool.socks=[],e.pool.scannedAt=0},1200).unref?.()},"killSpawned"),m=s(e=>{const o=Date.now();if(e.restarts=(e.restarts??[]).filter(r=>o-r<types_1.SERVICE_RESTART_WINDOW_MS),e.restarts.length>=types_1.SERVICE_MAX_RESTARTS){a(e,"error",`service crash-looping: ${e.project} \u2014 wedged ${types_1.SERVICE_MAX_RESTARTS}+\xD7/min, not auto-recycling (the next request retries)`,`cluster-service:${e.project}`,{kind:"service-crash-loop",project:e.project}),y(e,"wedged (crash-loop cap) \u2014 leaving down for the next request",{announce:!1});return}e.restarts.push(o),console.log(`[gateway] self-heal: recycling WEDGED ${e.project} (live parent, 0 live pods; ${e.restarts.length}/${types_1.SERVICE_MAX_RESTARTS})`),a(e,"warning",`self-heal: recycling wedged ${e.project} (0 live pods)`,`cluster-service:${e.project}`,{kind:"service-recycle",project:e.project,attempt:e.restarts.length}),y(e,"wedged: 0 live pods \u2014 recycling",{announce:!1}),setTimeout(()=>{!t.stopped()&&!e.proc&&e.state==="down"&&S(e)},1500).unref?.()},"recycleWedged"),A={maxAgeMs:types_1.POD_MAX_AGE_MS,graceMs:types_1.POD_STALE_GRACE_MS,settleMs:types_1.POD_RECYCLE_SETTLE_MS,cooldownMs:types_1.POD_STALE_RECYCLE_COOLDOWN_MS};let R;const D=new Map;let C=!1,T=0;const b=s(()=>{const e=t.projectRoots??{},o=new Set(t.services.map(n=>n.project));for(const n of t.routes)n.lens&&o.add(n.lens.project);const r=new Set;for(const n of o){const i=e[n];if(!i)continue;const d=path.relative(t.root,i).split(path.sep).filter(Boolean)[0];d&&!d.startsWith("..")&&r.add(d)}return[...r]},"managedBuckets"),L=s((e,o,r,n)=>{const i=t.projectRoots?.[e];if(!i)return;const d=sourceScopeDirs(t.root,i,r,o,n);return d.length>0?d:void 0},"scopeFor"),P=s(()=>{C||Date.now()-T<types_1.POD_STALE_SCAN_MS||(C=!0,T=Date.now(),(async()=>{const e=(0,scope_1.readSourceSetExclude)(t.root),o=await sourceSetSignature(t.root,void 0,e);if(R!==void 0&&o!==R&&(t.sourceSetChangedAt=Date.now(),l("info","source file set changed \u2014 stale pods recycle when idle","cluster-gateway",{kind:"source-set-changed"})),R=o,!t.projectRoots)return;let r;try{r=(await fs.promises.readdir(t.root,{withFileTypes:!0})).filter(g=>g.isDirectory()).map(g=>g.name)}catch{return}const n=b(),i=new Set(t.services.map(g=>g.project));for(const g of t.routes)g.lens&&i.add(g.lens.project);const d=new Map;for(const g of i){const u=L(g,r,n,e);if(!u)continue;const h=u.join("|"),E=d.get(h)??{dirs:u,projects:[]};E.projects.push(g),d.set(h,E)}const w=Date.now();for(const[g,{dirs:u,projects:h}]of d){const E=await sourceSetSignature(t.root,u,e),$=D.get(g);if(D.set(g,E),!($===void 0||E===$)){t.sourceSetChangedFor??=new Map;for(const x of h)t.sourceSetChangedFor.set(x,w);l("info",`source file set changed in ${h.join(", ")}'s scope`,"cluster-gateway",{kind:"source-set-changed",scoped:!0,projects:h})}}})().catch(()=>{}).finally(()=>{C=!1}))},"maybeScanSourceSet"),F=s((e,o)=>{e.lastStaleRecycleAt=Date.now(),console.log(`[gateway] zombie recycle: ${e.project} (${o}) \u2014 stale fs view; fresh pod incoming`),a(e,"warning",`zombie recycle: ${e.project} (${o})`,`cluster-service:${e.project}`,{kind:"pod-recycle",project:e.project,reason:o});const r=!!e.decl.eager;y(e,`${o} \u2014 recycling stale pod`,{announce:!1}),r&&setTimeout(()=>{!t.stopped()&&!e.proc&&e.state==="down"&&S(e)},1500).unref?.()},"recyclePod");return{scanNow:v,spawnService:S,ensureUp:k,scaleUp:M,killSpawned:y,markUp:f,startSweeper:s(()=>{const e=setInterval(()=>{if(!t.stopped()){types_1.POD_RECYCLE_ENABLED&&P();for(const o of t.services){if(t.stopped()||!o.proc){o.wedgedSince=void 0;continue}const r=o.decl.idleKillSec;if(r&&o.inflight===0&&Date.now()-o.lastUsed>r*1e3){y(o,`idle ${r}s`),o.wedgedSince=void 0;continue}const n=o.state==="starting"&&o.spawnAt!==void 0&&Date.now()-o.spawnAt<t.startupTimeoutMs,i=v(o.pool)>0;if(i||n){if(o.wedgedSince=void 0,i&&f(o,"observed"),i&&!n&&types_1.POD_RECYCLE_ENABLED){const d=t.sourceSetChangedFor?.get(o.project)??t.sourceSetChangedAt??0,w=podRecycleReason(o,Date.now(),d,A);w&&F(o,w)}continue}o.wedgedSince??=Date.now(),Date.now()-o.wedgedSince>types_1.WEDGE_RECYCLE_GRACE_MS&&(o.wedgedSince=void 0,m(o))}}},t.sweepMs);return e.unref(),e},"startSweeper")}}j(createServiceLayer,"createServiceLayer"),s(createServiceLayer,"createServiceLayer");