pi-lens 3.8.69 → 3.8.71

package/dist/clients/installer/index.js

@@ -196,7 +196,7 @@ export const TOOLS = [
         checkCommand: "jscpd",
         checkArgs: ["--version"],
         installStrategy: "npm",
-        packageName: "jscpd@3.5.10", // jscpd v4 introduced reprism dep whose lib/languages/ dir is missing from the published package — v3.5.x is the last stable release
+        packageName: "jscpd@5.0.12", // v4's packaging bug (reprism dep missing lib/languages/) is gone in v5's ground-up Rust rewrite — verified: real per-platform native binary (jscpd-windows-x64-msvc etc. via optionalDependencies, no missing-dir regression), --min-lines/--min-tokens/--reporters/--output/--ignore all unchanged, JSON schema fields read by clients/jscpd-client.ts's parseReport() (statistics.total.*, duplicates[].firstFile/secondFile.name+start, .lines, .tokens) are identical, and it's ~50x faster on this repo (4.1s -> 76ms detection time) — closes #582
         binaryName: "jscpd",
     },
     // Structural search and dead code detection
@@ -675,6 +675,48 @@ export const TOOLS = [
             treeMarker: "bin",
         },
     },
+    {
+        // lua-language-server (#564, split from #241) — same self-contained native
+        // TREE BUNDLE shape as clangd: bin/lua-language-server[.exe] + bundled
+        // locale/meta files, no external runtime. UNLIKE clangd, the release
+        // archive has NO wrapping version dir (verified by inspecting the actual
+        // 3.18.2 linux-x64 .tar.gz and win32-x64 .zip contents: `bin/`, `LICENSE`,
+        // `locale/`, … sit at archive root) — so stripComponents:0, not 1.
+        // LuaServer launches `<bundle>/bin/lua-language-server` directly.
+        // checkCommand documents the binary but is unused for resolution (tree
+        // bundles resolve only via the extract dir + treeMarker). Platform-matched
+        // url: LuaLS publishes darwin/linux x64+arm64 and win32 x64 (no win32/arm64
+        // build as of 3.18.2 → undefined, graceful unavailable); asset naming
+        // verified against the live GitHub release listing, not guessed.
+        id: "lua-language-server",
+        name: "lua-language-server",
+        checkCommand: "lua-language-server",
+        checkArgs: ["--version"],
+        installStrategy: "archive",
+        binaryName: "lua-language-server",
+        archive: {
+            url: (platform, arch) => {
+                const version = "3.18.2";
+                const base = `https://github.com/LuaLS/lua-language-server/releases/download/${version}`;
+                if (platform === "linux")
+                    return arch === "arm64"
+                        ? `${base}/lua-language-server-${version}-linux-arm64.tar.gz`
+                        : `${base}/lua-language-server-${version}-linux-x64.tar.gz`;
+                if (platform === "darwin")
+                    return arch === "arm64"
+                        ? `${base}/lua-language-server-${version}-darwin-arm64.tar.gz`
+                        : `${base}/lua-language-server-${version}-darwin-x64.tar.gz`;
+                if (platform === "win32")
+                    return arch === "arm64"
+                        ? undefined
+                        : `${base}/lua-language-server-${version}-win32-x64.zip`;
+                return undefined;
+            },
+            kind: "zip",
+            stripComponents: 0,
+            treeMarker: "bin",
+        },
+    },
     {
         id: "actionlint",
         name: "actionlint",
@@ -1183,6 +1225,7 @@ export function resetProbeCacheStateForTesting() {
     _probeCacheDirty = false;
     resolvedPathCache.clear();
     ensureInFlight.clear();
+    lastManagedInstallVersion.clear();
     if (_probeCacheFlushTimer !== null) {
         clearTimeout(_probeCacheFlushTimer);
         _probeCacheFlushTimer = null;
@@ -1238,11 +1281,44 @@ async function isCommandAvailable(command, _args) {
 export function isLspTransportRequiredError(output) {
     return /Connection (?:input|output) stream is not set|Use arguments of createConnection/i.test(output);
 }
+/**
+ * Parse the exact version pinned in a TOOLS `packageName` spec, e.g.
+ * `"jscpd@3.5.10"` -> `"3.5.10"`. Scoped packages (`"@ast-grep/cli"`) have no
+ * pin unless a version is appended after the package name
+ * (`"@scope/pkg@1.2.3"`) — `lastIndexOf("@")` on a bare scope marker (index 0)
+ * correctly reports "no pin" rather than mistaking the scope for a version.
+ * Returns undefined when packageName has no explicit `@version` suffix.
+ */
+function parsePinnedVersion(packageName) {
+    const at = packageName.lastIndexOf("@");
+    if (at <= 0)
+        return undefined;
+    return packageName.slice(at + 1) || undefined;
+}
+/** Extract the first semver-ish token (e.g. "3.5.10") from `--version` output. */
+function extractVersionToken(output) {
+    return output.match(/\d+\.\d+\.\d+(?:[-+][\w.]+)?/)?.[0];
+}
+/**
+ * Version reported by the last successful `--version` probe of a pi-lens
+ * managed local npm install, keyed by toolId. Populated only inside
+ * getToolPath()'s managed-local-install checks below — i.e. only when that
+ * code path already spawns verifyToolBinary anyway (cache hits in
+ * ensureTool()'s fast paths never reach getToolPath, so this never adds a new
+ * spawn). Consumed by ensureTool() to detect drift against the tool's current
+ * `packageName` pin (#589) — deliberately scoped to installStrategy "npm"
+ * with an explicit version pin; unpinned tools and non-npm strategies (github/
+ * maven/archive) never populate or read this map.
+ */
+const lastManagedInstallVersion = new Map();
 /**
  * Verify a tool binary actually works by running --version
- * This catches broken symlinks, partial installs, and corrupted binaries
+ * This catches broken symlinks, partial installs, and corrupted binaries.
+ * `onVersionOutput`, when provided, receives the raw stdout on a successful
+ * (exit 0) probe — used to piggyback version-pin drift detection onto this
+ * already-happening spawn instead of adding a new one (#589).
  */
-async function verifyToolBinary(binPath) {
+async function verifyToolBinary(binPath, onVersionOutput) {
     return new Promise((resolve) => {
         const isWindows = process.platform === "win32";
         const hasKnownWindowsExt = /\.(cmd|exe|ps1)$/i.test(binPath);
@@ -1277,6 +1353,7 @@ async function verifyToolBinary(binPath) {
         proc.on("exit", (code) => {
             if (code === 0) {
                 debugLog(`Verified: ${binPath} (version: ${stdout.trim()})`);
+                onVersionOutput?.(stdout);
                 resolve(true);
             }
             else if (isLspTransportRequiredError(`${stdout}\n${stderr}`)) {
@@ -1491,6 +1568,23 @@ export async function getToolPath(toolId) {
     if (tool.installStrategy === "archive" && !tool.archive?.launcher) {
         return getArchiveTreeBundlePath(tool);
     }
+    // Version-pin drift detection (#589) is scoped to npm-strategy tools with an
+    // explicit `@version` pin — everything else (unpinned npm entries, pip/gem,
+    // github/maven/archive) has no drift signal to piggyback on here. Clear any
+    // stale entry up front so a miss on the checks below never leaves a prior
+    // call's version lingering for ensureTool() to misread.
+    const pinnedVersion = tool.installStrategy === "npm" && tool.packageName
+        ? parsePinnedVersion(tool.packageName)
+        : undefined;
+    if (pinnedVersion)
+        lastManagedInstallVersion.delete(toolId);
+    const recordVersion = pinnedVersion
+        ? (output) => {
+            const seen = extractVersionToken(output);
+            if (seen)
+                lastManagedInstallVersion.set(toolId, seen);
+        }
+        : undefined;
     // Fast path: check local npm install first (where auto-install places tools).
     // This avoids the ~2-5s overhead of spawning npm global probes and PATH
     // searches for tools we already manage locally.
@@ -1500,7 +1594,7 @@ export async function getToolPath(toolId) {
         const cmdPath = `${localBase}.cmd`;
         try {
             await fs.access(cmdPath);
-            if (await verifyToolBinary(cmdPath)) {
+            if (await verifyToolBinary(cmdPath, recordVersion)) {
                 return cmdPath;
             }
             logSessionStart(`auto-install verify: ${cmdPath} exists but is broken, will reinstall`);
@@ -1513,7 +1607,7 @@ export async function getToolPath(toolId) {
         const exePath = `${localBase}.exe`;
         try {
             await fs.access(exePath);
-            if (await verifyToolBinary(exePath)) {
+            if (await verifyToolBinary(exePath, recordVersion)) {
                 return exePath;
             }
             logSessionStart(`auto-install verify: ${exePath} exists but is broken, will reinstall`);
@@ -1524,7 +1618,7 @@ export async function getToolPath(toolId) {
     }
     try {
         await fs.access(localBase);
-        if (await verifyToolBinary(localBase)) {
+        if (await verifyToolBinary(localBase, recordVersion)) {
             return localBase;
         }
         logSessionStart(`auto-install verify: ${localBase} exists but is broken, will reinstall`);
@@ -2653,6 +2747,29 @@ export async function ensureTool(toolId, opts) {
         // Check if already installed.
         const existingPath = await getToolPath(toolId);
         if (existingPath) {
+            // Version-pin drift (#589): getToolPath() above just spawned
+            // verifyToolBinary on the managed local install anyway (this is the
+            // slow path — fast paths 1/2 above already returned before reaching
+            // here), so lastManagedInstallVersion was populated for free if this
+            // is a pinned npm tool. Compare it to the current pin and, on
+            // mismatch, route through the EXISTING forceReinstall codepath rather
+            // than resolving to a known-stale binary. Piggybacks entirely on the
+            // probe-cache's ~once-per-24h/once-per-session cadence — no new spawn.
+            const tool = TOOLS.find((t) => t.id === toolId);
+            const pinnedVersion = tool?.installStrategy === "npm" && tool.packageName
+                ? parsePinnedVersion(tool.packageName)
+                : undefined;
+            if (pinnedVersion) {
+                const seenVersion = lastManagedInstallVersion.get(toolId);
+                if (seenVersion && seenVersion !== pinnedVersion) {
+                    lastManagedInstallVersion.delete(toolId);
+                    logSessionStart(`auto-install ensure ${toolId}: version drift (installed ${seenVersion} != pinned ${pinnedVersion}) — forcing reinstall (${Date.now() - ensureStartMs}ms)`);
+                    return ensureTool(toolId, {
+                        forceReinstall: true,
+                        allowInstall: opts?.allowInstall,
+                    });
+                }
+            }
             resolvedPathCache.set(toolId, existingPath);
             void updateProbeCache(toolId, existingPath);
             logSessionStart(`auto-install ensure ${toolId}: already available at ${existingPath} (${Date.now() - ensureStartMs}ms)`);

package/dist/clients/instance-reaper.js

@@ -199,8 +199,10 @@ export function decideOrphanReaping(registry, isPidAlive, matchProcess, now = Da
 }
 // --- Impure liveness / identity / kill helpers ---
 /** `process.kill(pid, 0)` liveness check: ESRCH ⇒ dead, anything else
- *  (EPERM, or no error thrown at all) ⇒ conservatively alive. */
-function realIsPidAlive(pid) {
+ *  (EPERM, or no error thrown at all) ⇒ conservatively alive. Exported so
+ *  other registry consumers (clients/lsp-budget.ts, #449 slice 2) reuse this
+ *  exact liveness check rather than inventing a second one. */
+export function realIsPidAlive(pid) {
     if (!Number.isFinite(pid) || pid <= 0)
         return false;
     try {
@@ -407,6 +409,231 @@ async function killPidTree(pid) {
         }
     }
 }
+/**
+ * #658: known pi-lens-managed LSP/scanner binary names (clients/lsp/server.ts
+ * spawn candidates), used by the registry-INDEPENDENT backstop sweep below.
+ * `opengrep-core` is opengrep's own native subprocess (not spawned directly by
+ * pi-lens, but still part of the tree we manage). `yaml-language-server` and
+ * `typescript-language-server` are node-launched — their OS image name is
+ * `node`/`node.exe`, so matching is done against the full command line
+ * (script path), not the process image name, exactly like the existing
+ * marker-search's WQL LIKE query below.
+ */
+export const MANAGED_BINARY_NAMES = [
+    "ast-grep",
+    "opengrep-core",
+    "opengrep",
+    "marksman",
+    "zizmor",
+    "typos-lsp",
+    "yaml-language-server",
+    "typescript-language-server",
+];
+/**
+ * PURE decision function for the #658 registry-independent backstop: given a
+ * live OS-process snapshot (already filtered to known managed binary names)
+ * and the current registry snapshot, decide which processes are backstop-
+ * kill-eligible. Zero I/O — unit-testable with fake data, mirroring
+ * `decideOrphanReaping`.
+ *
+ * A process is eligible ONLY when ALL of:
+ * - its pid is NOT already tracked in any instance's `lspChildren[]` (tracked
+ *   pids stay owned by the registry-driven `decideOrphanReaping` path above —
+ *   this backstop must never race or duplicate that logic);
+ * - its reported parent pid is a verifiable, well-formed pid (finite,
+ *   positive, and not equal to its own pid) — an unresolvable/malformed
+ *   parent pid is UNVERIFIABLE, never treated as "confirmed dead" (this is a
+ *   stricter contract than `realIsPidAlive`'s own conservatism, because here
+ *   an invalid value means "the OS couldn't tell us", not "confirmed gone");
+ * - `isPidAlive(parentPid)` reports the parent as dead.
+ *
+ * Note the direction of the ambiguity guard: if `parentPid` itself was
+ * recycled onto an unrelated live process, `isPidAlive` conservatively
+ * reports "alive" and the process is (safely) left alone — a false negative,
+ * never a false positive kill. Binary name alone is never sufficient (name
+ * matching only decides which processes are candidates for this check at
+ * all); a live parent is never overridden "however unfamiliar" the process.
+ */
+export function decideBackstopOrphanReaping(processes, registry, isPidAlive) {
+    const trackedPids = new Set();
+    for (const instance of registry) {
+        for (const child of instance.lspChildren)
+            trackedPids.add(child.pid);
+    }
+    const out = [];
+    for (const proc of processes) {
+        if (trackedPids.has(proc.pid))
+            continue; // owned by the registry-driven reaper
+        if (!Number.isFinite(proc.parentPid) || proc.parentPid <= 0)
+            continue; // unverifiable
+        if (proc.parentPid === proc.pid)
+            continue; // malformed data guard
+        if (isPidAlive(proc.parentPid))
+            continue; // live parent — never kill
+        out.push(proc);
+    }
+    return out;
+}
+/** Enumerate live OS processes whose command line contains one of
+ *  `MANAGED_BINARY_NAMES` (#658), independent of the instance registry.
+ *  Windows: one batched CIM/WQL query (mirrors `findPidsByMarkerWindows`'s
+ *  query pattern). POSIX: `ps -eo pid=,ppid=,args=`, filtered in JS. Returns
+ *  `{pid, parentPid, command}` rows. Best-effort: any failure ⇒ []. */
+async function enumerateManagedProcesses() {
+    if (isWindows) {
+        const clauses = MANAGED_BINARY_NAMES.map((name) => `CommandLine LIKE '%${escapeWqlLikeValue(name)}%'`).join(" OR ");
+        const psScript = `Get-CimInstance Win32_Process -Filter "${clauses}" ` +
+            `| ForEach-Object { "$($_.ProcessId)\t$($_.ParentProcessId)\t$($_.CommandLine)" }`;
+        return new Promise((resolve) => {
+            try {
+                const powershell = windowsExe("WindowsPowerShell\\v1.0\\powershell.exe");
+                const child = nodeSpawn(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+                let out = "";
+                child.stdout?.on("data", (chunk) => {
+                    out += chunk.toString();
+                });
+                child.once("error", () => resolve([]));
+                child.once("close", () => {
+                    const results = [];
+                    for (const line of out.split(/\r?\n/)) {
+                        const firstTab = line.indexOf("\t");
+                        if (firstTab <= 0)
+                            continue;
+                        const secondTab = line.indexOf("\t", firstTab + 1);
+                        if (secondTab <= 0)
+                            continue;
+                        const pid = Number(line.slice(0, firstTab).trim());
+                        const parentPid = Number(line.slice(firstTab + 1, secondTab).trim());
+                        const command = line.slice(secondTab + 1);
+                        if (Number.isFinite(pid) && pid > 0) {
+                            results.push({ pid, parentPid, command });
+                        }
+                    }
+                    resolve(results);
+                });
+            }
+            catch {
+                resolve([]);
+            }
+        });
+    }
+    // POSIX: enumerate everything, filter in JS by managed-name substring —
+    // there is no single-query WQL-style server-side filter available.
+    return new Promise((resolve) => {
+        try {
+            const child = nodeSpawn(posixPsPath(), ["-eo", "pid=,ppid=,args="], {
+                shell: false,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            let out = "";
+            child.stdout?.on("data", (chunk) => {
+                out += chunk.toString();
+            });
+            child.once("error", () => resolve([]));
+            child.once("close", () => {
+                const results = [];
+                for (const line of out.split(/\r?\n/)) {
+                    // Linear parse (S8786/S6594): "  pid ppid args here".
+                    const trimmed = line.trimStart();
+                    if (!trimmed)
+                        continue;
+                    let i = 0;
+                    while (i < trimmed.length && trimmed[i] >= "0" && trimmed[i] <= "9")
+                        i++;
+                    if (i === 0)
+                        continue;
+                    const pid = Number(trimmed.slice(0, i));
+                    let rest = trimmed.slice(i);
+                    let k = 0;
+                    while (k < rest.length && (rest[k] === " " || rest[k] === "\t"))
+                        k++;
+                    rest = rest.slice(k);
+                    let j = 0;
+                    while (j < rest.length && rest[j] >= "0" && rest[j] <= "9")
+                        j++;
+                    if (j === 0)
+                        continue;
+                    const parentPid = Number(rest.slice(0, j));
+                    let m = j;
+                    while (m < rest.length && (rest[m] === " " || rest[m] === "\t"))
+                        m++;
+                    const args = rest.slice(m);
+                    if (!Number.isFinite(pid) || pid <= 0)
+                        continue;
+                    const lowerArgs = args.toLowerCase();
+                    if (MANAGED_BINARY_NAMES.some((name) => lowerArgs.includes(name.toLowerCase()))) {
+                        results.push({ pid, parentPid, command: args });
+                    }
+                }
+                resolve(results);
+            });
+        }
+        catch {
+            resolve([]);
+        }
+    });
+}
+/**
+ * Fire-and-forget REGISTRY-INDEPENDENT backstop sweep (#658): finds
+ * pi-lens-managed LSP/scanner processes the registry-driven `sweepOrphans`
+ * can never see again once their registry trace is lost (a stale-heartbeat
+ * entry removal, or a `killPidTree` call that failed silently) — enumerates
+ * live OS processes by known binary name, and kills any that are both
+ * untracked and have a confirmed-dead parent. A strictly ADDITIVE second
+ * layer: `sweepOrphans`'s registry-driven path is untouched and remains the
+ * cheap, correct common case.
+ *
+ * Kill-attempt retry: deliberately NO separate retry-tracking state. If
+ * `killPidTree` fails silently, the process stays alive, untracked, and its
+ * parent stays dead — so it stays classified as backstop-kill-eligible and
+ * this exact sweep simply tries again at the next `session_start`, with zero
+ * extra bookkeeping. This only breaks if the orphan's *parent* pid gets
+ * reused by a live process in the interim (closes the window), which is the
+ * same residual risk `decideOrphanReaping`'s registry path already accepts.
+ * A future hardening (making `killPidTree` return a success signal so a
+ * failed kill can be logged distinctly from "already gone") is a reasonable
+ * follow-up, not required for correctness here.
+ *
+ * Never throws — every step is wrapped so a reap failure cannot block or
+ * crash the caller (session_start).
+ */
+export async function sweepUntrackedOrphans() {
+    if (!isInstanceRegistryEnabled())
+        return;
+    const startedAt = Date.now();
+    try {
+        const [registry, processes] = await Promise.all([
+            readInstanceRegistry(),
+            enumerateManagedProcesses(),
+        ]);
+        if (processes.length === 0)
+            return;
+        const candidates = decideBackstopOrphanReaping(processes, registry, realIsPidAlive);
+        let killedCount = 0;
+        for (const proc of candidates) {
+            await killPidTree(proc.pid);
+            killedCount++;
+        }
+        try {
+            logLatency({
+                type: "phase",
+                phase: "orphan_backstop_reaped",
+                filePath: "",
+                durationMs: Date.now() - startedAt,
+                metadata: {
+                    scanned: processes.length,
+                    killed: killedCount,
+                },
+            });
+        }
+        catch {
+            // best-effort logging only
+        }
+    }
+    catch {
+        // The sweep must never throw out of session_start.
+    }
+}
 /**
  * Fire-and-forget orphan sweep: reads the registry, decides what's dead via
  * `decideOrphanReaping`, kills orphaned LSP children (by pid, with a

package/dist/clients/instance-registry.js

@@ -23,6 +23,16 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getGlobalPiLensDir } from "./file-utils.js";
+// #735: reuse the #449/#525 reaper's exact conservative liveness check
+// (`process.kill(pid, 0)`, ESRCH-only-means-dead) rather than inventing a
+// second one — see realIsPidAlive's own docstring, which already calls out
+// clients/lsp-budget.ts as a precedent consumer. This creates a live-binding
+// import cycle with instance-reaper.ts (which imports readInstanceRegistry/
+// isInstanceRegistryEnabled from here); safe under Node ESM because every
+// use on both sides happens inside function bodies, never at module-
+// evaluation time, so both modules are fully initialized before either
+// import is actually invoked.
+import { realIsPidAlive } from "./instance-reaper.js";
 import { normalizeFilePath } from "./path-utils.js";
 function registryPath() {
     return path.join(getGlobalPiLensDir(), "instances.json");
@@ -138,7 +148,8 @@ export async function registerInstance(projectRoot) {
     });
     await writeRegistryAsync({ instances: others });
 }
-/** Update this process's heartbeat/rss. Cheap — safe to call every turn end. */
+/** Update this process's heartbeat/rss (and, since #620, host CPU% + live
+ *  LSP children's rss/CPU%). Cheap — safe to call every turn end. */
 export async function updateHeartbeat(patch = {}) {
     if (!isInstanceRegistryEnabled())
         return;
@@ -153,10 +164,24 @@ export async function updateHeartbeat(patch = {}) {
     }
     const now = new Date().toISOString();
     const current = file.instances[idx];
+    const lspChildren = patch.childUsage
+        ? current.lspChildren.map((child) => {
+            const usage = patch.childUsage?.[child.pid];
+            if (!usage)
+                return child;
+            return {
+                ...child,
+                rssBytes: usage.rssBytes ?? child.rssBytes,
+                cpuPercent: usage.cpuPercent ?? child.cpuPercent,
+            };
+        })
+        : current.lspChildren;
     file.instances[idx] = {
         ...current,
         rssBytes: patch.rssBytes ?? process.memoryUsage().rss,
-        lspChildCount: current.lspChildren.length,
+        cpuPercent: patch.cpuPercent ?? current.cpuPercent,
+        lspChildren,
+        lspChildCount: lspChildren.length,
         heartbeatAt: now,
     };
     await writeRegistryAsync(file);
@@ -236,3 +261,117 @@ export function deregisterInstance() {
         return; // nothing to remove
     writeRegistrySync({ instances: remaining });
 }
+/**
+ * PURE aggregation over a registry snapshot: "how much CPU/RAM is pi-lens
+ * attributable to, right now, across every process it owns" (#620) — the
+ * host of every registered instance plus every one of its live LSP children.
+ * Missing/unsampled `rssBytes`/`cpuPercent` (best-effort sampling can fail)
+ * are treated as 0 for summation purposes — never as a full instance to
+ * exclude, since a partially-sampled instance's other numbers are still real
+ * data worth surfacing.
+ *
+ * Does NOT include transient analyzer children (jscpd/knip/etc.) — those are
+ * short-lived and sampled separately per-invocation via
+ * clients/resource-sampler.ts into clients/latency-logger.ts, not carried in
+ * the registry (see the module docstring's scope note).
+ *
+ * #735: `isPidAlive`, when supplied, drops any instance whose owning pid is
+ * confirmed dead BEFORE aggregation — a hard-killed pi process otherwise
+ * leaves a registry entry with heartbeat-cached RSS that reads as a live,
+ * resource-consuming instance until it eventually ages out (up to
+ * `STALE_HEARTBEAT_MS`, see clients/instance-reaper.ts). Dropped rather than
+ * flagged `stale: true`: a dead pid is unambiguous (unlike heartbeat
+ * staleness, which the reaper deliberately treats as "maybe idle-but-alive"
+ * and never uses to justify removing/hiding anything) — the wire shape and
+ * every existing caller (chiefly `pilens_health`'s headline instance
+ * count/RSS/CPU numbers) simply expects a footprint of currently-live
+ * instances. Left `undefined` for pure/synchronous callers (incl. every
+ * pre-#735 unit test) that pass a plain snapshot with no intent to check OS
+ * process state — no filtering happens, preserving prior behavior exactly.
+ * No pid-reuse identity check is applied here (unlike the reaper's child-pid
+ * `matchProcess`): `InstanceEntry` never recorded the host's own command
+ * line to verify against (same gap #525 called out for the reaper's PARENT
+ * pid, deliberately left unfixed there too), and a health-report false
+ * positive is a much smaller blast radius than the reaper's mistaken kill —
+ * so plain liveness is judged sufficient here.
+ */
+export function computeResourceFootprint(instances, isPidAlive) {
+    const liveInstances = isPidAlive
+        ? instances.filter((instance) => isPidAlive(instance.pid))
+        : instances;
+    const perInstance = liveInstances.map((instance) => {
+        const lspChildRssBytes = instance.lspChildren.reduce((sum, child) => sum + (child.rssBytes ?? 0), 0);
+        const lspChildCpuPercent = instance.lspChildren.reduce((sum, child) => sum + (child.cpuPercent ?? 0), 0);
+        return {
+            pid: instance.pid,
+            projectRoot: instance.projectRoot,
+            rssBytes: instance.rssBytes ?? 0,
+            cpuPercent: instance.cpuPercent ?? 0,
+            lspChildCount: instance.lspChildren.length,
+            lspChildRssBytes,
+            lspChildCpuPercent,
+        };
+    });
+    let totalRssBytes = 0;
+    let totalCpuPercent = 0;
+    let totalLspChildCount = 0;
+    for (const inst of perInstance) {
+        totalRssBytes += inst.rssBytes + inst.lspChildRssBytes;
+        totalCpuPercent += inst.cpuPercent + inst.lspChildCpuPercent;
+        totalLspChildCount += inst.lspChildCount;
+    }
+    return {
+        instanceCount: perInstance.length,
+        totalRssBytes,
+        totalCpuPercent,
+        totalLspChildCount,
+        perInstance,
+    };
+}
+/**
+ * Read the live registry and compute the aggregate footprint — the query
+ * side of "how much CPU/RAM is pi-lens using right now" (#620). Best-effort
+ * (readInstanceRegistry never throws); the answer only reflects whatever
+ * heartbeats have landed so far.
+ *
+ * #735: defaults to the reaper's `realIsPidAlive` so dead-pid registry
+ * entries (a hard-killed pi process) are excluded from both the returned
+ * footprint AND — opportunistically, fire-and-forget, best-effort — pruned
+ * from the on-disk registry, the same "entry removal only, never blocks the
+ * caller" convention `sweepOrphans`/`pruneDeadInstances` already use.
+ * Pruning here is a bonus cleanup, not a substitute for the reaper sweep:
+ * this path only prunes pids this particular read happened to find dead,
+ * while the reaper sweep is the authoritative, scheduled cleanup. Injectable
+ * so tests can pass a fake predicate (or omit filtering entirely by passing
+ * a function that always returns true) without touching real OS process
+ * state.
+ */
+export async function getResourceFootprint(isPidAlive = realIsPidAlive) {
+    const instances = await readInstanceRegistry();
+    const deadPids = new Set(instances.filter((instance) => !isPidAlive(instance.pid)).map((instance) => instance.pid));
+    if (deadPids.size > 0) {
+        // Fire-and-forget: a health-report read must never block on, or fail
+        // because of, a registry write.
+        prunePids(deadPids).catch(() => {
+            // best-effort — a dead-pid entry that fails to prune here is simply
+            // re-evaluated (and re-dropped from the report) on the next read, and
+            // remains catchable by the scheduled reaper sweep regardless.
+        });
+    }
+    return computeResourceFootprint(instances, isPidAlive);
+}
+/** Best-effort removal of specific dead pids' entries from the on-disk
+ *  registry (#735). Re-reads immediately before writing (rather than reusing
+ *  an earlier snapshot) to narrow — not eliminate — the last-writer-wins race
+ *  already accepted for this module's read-modify-write model (see the
+ *  module docstring). Mirrors clients/instance-reaper.ts's
+ *  `pruneDeadInstances`, kept local here rather than imported to avoid
+ *  reaching back across the same import edge `realIsPidAlive` already
+ *  crosses in the other direction. */
+async function prunePids(deadPids) {
+    const file = await readRegistryAsync();
+    const remaining = file.instances.filter((entry) => !deadPids.has(entry.pid));
+    if (remaining.length === file.instances.length)
+        return;
+    await writeRegistryAsync({ instances: remaining });
+}