pi-lens 3.8.67 → 3.8.68

package/CHANGELOG.md

@@ -10,6 +10,25 @@ All notable changes to pi-lens will be documented in this file.
 
 ### Fixed
 
+## [3.8.68] - 2026-07-10
+
+### Added
+
+- **Subagent light mode** (#449) — the nicobailon/pi-subagents extension spawns each subagent as a child `pi` CLI process and sets `PI_SUBAGENT_CHILD=1` unconditionally in every child's environment, so a fan-out of N subagents in the same cwd previously paid N full LSP pre-warms plus N sets of heavyweight startup scans — mostly wasted on short-lived task agents. `clients/subagent-mode.ts` adds `isSubagentSession()`, detected once at session start; when engaged, both the LSP pre-warm (explicit `warmFiles` and the dominant-language auto-warm) and the knip/jscpd/madge/dead-code/govulncheck/gitleaks/trivy startup scans are skipped, extending the same `skipHeavyweightScans` gate #462 introduced for slow filesystems. Per-edit LSP dispatch and the in-process scans (todo/call-graph/codebase-model/ast-grep-exports/word-index) are untouched, so a subagent that actually edits code still gets diagnostics and symbol search. Escape hatch: `PI_LENS_SUBAGENT_FULL=1` forces full behavior even inside a detected subagent session. Logged to the latency log as a `subagent_light_mode` phase with the subagent's `runId`/`agentName` (from `PI_SUBAGENT_RUN_ID`/`PI_SUBAGENT_CHILD_AGENT`) when present.
+- **Cross-process instance registry** (#449 slice 1) — a tiny machine-global registry (`~/.pi-lens/instances.json`, `clients/instance-registry.ts`) now records every live pi-lens process: pid, project root, live LSP child servers (pid/serverId/command/spawn marker), RSS, and a heartbeat. Registered at `session_start`, updated opportunistically at `turn_end` (piggybacked on the existing per-turn touchpoint, no new timer), and deregistered synchronously at `session_shutdown`. Pure observability substrate for now (zero dispatch/behavior change) — the groundwork later slices (cross-process LSP budget, same-root warm attach) will build on. Reads are corruption-safe (garbage/missing file ⇒ empty, never throws); writes are atomic tmp+rename. `PI_LENS_INSTANCE_REGISTRY=0` disables it entirely.
+- **Slow-filesystem mode** (#462) — WSL 9p mounts (`/mnt/c/...`) measure ~1.3ms/`stat` vs ~17µs native (75x), so an unbounded synchronous tree walk (e.g. a 5,000-file project) could cost ~6.5s of stat time alone and freeze the TUI. `clients/slow-fs.ts` adds a cheap session-start probe (median of up to 15 `fs.statSync` calls under the project root) that classifies the workspace by measurement, not path shape, so it also catches drvfs/NFS/SMB rather than 9p-only. In slow-FS mode the sync `collectSourceFiles` walker clamps to a reduced 500-file cap (the async twin is unaffected), and the knip/jscpd/madge/dead-code/govulncheck/gitleaks/trivy background scans are skipped at session start with a visible notice instead of silently returning stale/empty results. Escape hatches: `PI_LENS_ALLOW_SLOW_FS_SCAN=1` disables slow-FS mode entirely; `PI_LENS_FORCE_SLOW_FS=1` forces it on for testing or when the probe under-fires; `PI_LENS_SLOW_FS_THRESHOLD_US` overrides the 500µs default. The verdict is logged to the latency log as a `slow_fs_probe` phase for dogfooding.
+- **Subagent-extension compat smoke** (#476) — pi-lens's subagent-compatibility features (#473/#474/#475) were built on reverse-engineered facts about the nicobailon/pi-subagents and `@tintinweb/pi-subagents` extensions plus the pi SDK itself. A new nightly `.github/workflows/compat-smoke.yml` makes that compatibility empirical: Layer A (`scripts/compat-contracts.mjs`) npm-installs the real third-party packages and mechanically re-verifies six pinned contracts with resilient pattern matchers (`scripts/lib/compat-contracts.mjs`) against the installed source — no `pi` process, no LLM. Layer B (`scripts/compat-smoke-behavioral.mjs`) installs the packed pi-lens tarball into a real `pi` (the same mechanism `install-smoke.yml`'s `pi-load` job uses) and drives `pi --mode rpc` to assert, through pi-lens's own latency log, that subagent light mode engages under `PI_SUBAGENT_CHILD=1`, that `PI_LENS_SUBAGENT_FULL=1` overrides it off, and that zero LSP-server processes survive a graceful pi exit (the #472 orphan class). Both layers run `continue-on-error`; a failure opens/refreshes a single tracking issue rather than reddening the nightly. `docs/subagent-compat.md` records the exact pinned contracts (file + version last verified) and the three env levers (`PI_LENS_SUBAGENT_FULL`, `PI_LENS_CONCURRENT_SESSION_GUARD`, `PI_LENS_INSTANCE_REGISTRY`).
+
+### Changed
+
+### Fixed
+
+- **Orphaned LSP server processes no longer survive abnormal session exit** (#472) — the #234 teardown constraint (no child spawn during `session_shutdown`, else libuv aborts) only covers CLEAN shutdown; a crashed/hard-killed/OOM'd session never runs teardown, and Windows does not kill children when a parent dies, so the whole LSP fleet could leak (7 orphaned ast-grep pairs found in the wild, up to 13 days old, ~700MB). `killProcessTree`'s `processExiting` branch only ever killed the DIRECT child (for shell/`.cmd`-wrapped servers that's the wrapper, not the real server) — its comment claiming Windows grandchildren "are reaped by the OS as the host exits" was false and is now corrected in place (behavior unchanged: still direct-child-only, per #234). The real fix is the #449 instance registry's orphan reaper: every LSP child (core and auxiliary, uniformly, at the shared `clients/lsp/launch.ts`/`client.ts` spawn/kill seam — no per-server special casing) is now recorded with its pid, resolved command, and — when the launch args carry a temp-config-style value (e.g. ast-grep's `--config <tmp sgconfig path>`) — a per-spawn-unique marker for command-line re-identification when the pid chain is broken (the synthesized baseline sgconfig now embeds the owning pid in its filename — `baseline-<pid>.sgconfig.yml`, with age-based cleanup of stale siblings — so the marker really is unique per instance; the previous shared `baseline.sgconfig.yml` would have made the marker fallback match every live ast-grep on the machine). `clients/instance-reaper.ts` sweeps at every `session_start`: a pure `decideOrphanReaping` function (conservative liveness — ESRCH-only counts as dead, EPERM/ambiguous never does; markers claimed by any live instance are never search-killed; pid kills are identity-verified against a batched command-line lookup so a recycled pid is never killed blind) decides what to kill, and an impure `sweepOrphans` executes it (`taskkill /F /T` on Windows, process-group kill on POSIX) plus a marker-based `Get-CimInstance` command-line search fallback for the broken-pid-chain case. Also resolves ast-grep's platform-native exe directly (`resolveAstGrepNativeExe`, `@ast-grep/cli-<platform>-<arch>` packages) ahead of the node-bin-wrapper candidate — one less orphanable process layer.
+- **Concurrent in-process subagent binds no longer tear down the parent's LSP fleet/runtime state (#473)** — extensions that build a fresh `AgentSession` and call `session.bindExtensions()` *inside the same Node process* as the parent pi session (tintinweb/pi-subagents-style) reuse pi's process-global extension-loader cache, so the subagent's `session_start` re-invoked pi-lens's SAME module-scope singletons the parent was still using — `resetLSPService({fast:true})` killed every live LSP client and `runtime.resetForSession()` bumped the session generation, silently orphaning the parent's in-flight continuations (parked cascades, diagnostics waits) mid-turn, with no visible error. New `clients/session-lifecycle.ts` classifies each `session_start`/`session_shutdown` as `primary` / `sequential-replacement` / `concurrent-secondary` by probing whether the previously-registered ctx is still active (an SDK-wrapped accessor throws pi's own stale-ctx error only for real sequential replacement — `newSession`/`fork`/`switchSession`/`reload` — never for a concurrently-live sibling). A `concurrent-secondary` session_start now skips `handleSessionStart` and the runtime-identity update entirely and rides the already-initialized shared infra; its later shutdown skips the destructive teardown too. Classification is fail-safe: any inconclusive signal (probe failure, no prior session) falls back to today's full-reset behavior, and `PI_LENS_CONCURRENT_SESSION_GUARD=0` disables the guard outright. Zero behavior change for the common single-session process.
+- **Review-graph snapshot persist is now atomic (tmp + rename)** — the debounced cache write went straight to `review-graph.json` with a plain `fs.writeFile`, so a concurrent reader (another process's blind load, or the tier-2 disk load under CI's parallel test runners) could observe a created-but-partially-written file, fail the JSON parse, and silently fall open to a full whole-repo rebuild. The write now lands in a `.tmp-<pid>` sibling and is renamed into place (atomic on POSIX and Windows), so a snapshot either doesn't exist yet or is complete; the process-exit flush uses the same pattern. This was the flaky `expected 'cached' to be 'full'` CI failure in the #300 git-stamp tests.
+- **`servercapabilities.md` merge guard survives schema changes and merges bullet sections (#469)** — the #390 nightly merge guard for `scripts/server-capabilities.mjs` required the prior and freshly-generated table headers to be byte-identical before merging, so adding the `ws-pull` column silently disabled the guard and last night's ubuntu-only run dropped the rust and php rows (and their capability-key / executeCommand bullets) entirely. Fixed by reshaping prior rows onto the new header **by column name** (`reshapeRowsByName` in `scripts/lib/md-matrix.mjs` — columns the prior doc lacked are filled with the `·` placeholder, columns dropped from the new schema are simply not carried) and by merging the two bulleted sections ("Raw advertised capability keys", "Advertised executeCommand allowlists") for preserved servers, which the original guard never touched at all (`parseBulletSection`/`mergeBulletSection`). The whole merge is now a pure, unit-tested function (`mergeServerCapabilitiesDoc`) that never spawns an LSP server and fails open (writes the fresh doc, logs to stderr) if either doc's table is unparseable.
+- **pi-lens loads under pi's Bun-compiled binary again** (#335) — pi ships as a `bun build --compile` single-file executable and loads extensions inside that embedded runtime, whose module resolver does not traverse the extension's on-disk `node_modules` for a bare specifier. So a static `import { minimatch } from "minimatch"` in `file-utils.js` (and every other third-party bare import) failed with `Cannot find package`, dropping the jscpd/todo/complexity analyzers into degraded mode. `dist/index.js` is now bundled into one self-contained file (`scripts/bundle-dist.mjs`, wired into `build:dist`) that inlines the pure-JS deps (minimatch, js-yaml, vscode-jsonrpc and transitives), so nothing is imported by bare specifier at load time. Host-provided packages (typebox, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`) and the native/wasm packages (`@ast-grep/napi`, web-tree-sitter) stay external; the two lazy native/wasm accessors resolve to an absolute path via `createRequire` before dynamic-importing (a bare specifier fails under the compiled host, an absolute path does not), with the bare specifier kept as a fallback for other runtimes. esbuild is run through `node <npm-cli> exec` (shell-free, not the `npx.cmd` shim), installing into npm's cache rather than the project tree, so the build adds no dependency and works on a from-source `--omit=dev` install; a `createRequire` banner is prepended so the bundled CJS deps load under pure-ESM Node. The reporter's Windows junction workaround does not port to the Linux compiled host, so bundling is the cross-platform fix.
+
 ## [3.8.67] - 2026-07-09
 
 ### Added

package/README.md

@@ -149,6 +149,8 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/cmptr"><img src="https://avatars.githubusercontent.com/u/32746889?v=4" width="100px;" alt=""/><br /><sub><b>Aaron Bell</b></sub></a><br /><a href="#code-cmptr" title="Code">💻</a> <a href="#bug-cmptr" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="http://jasonrimmer.com/"><img src="https://avatars.githubusercontent.com/u/629?v=4" width="100px;" alt=""/><br /><sub><b>Jason Rimmer</b></sub></a><br /><a href="#bug-jrimmer" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/moj02090"><img src="https://avatars.githubusercontent.com/u/57255166?v=4" width="100px;" alt=""/><br /><sub><b>moj02090</b></sub></a><br /><a href="#code-moj02090" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/vkarasen"><img src="https://avatars.githubusercontent.com/u/7932536?v=4" width="100px;" alt=""/><br /><sub><b>Vitali Karasenko</b></sub></a><br /><a href="#code-vkarasen" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mehalter"><img src="https://avatars.githubusercontent.com/u/1591837?v=4" width="100px;" alt=""/><br /><sub><b>Micah Halter</b></sub></a><br /><a href="#code-mehalter" title="Code">💻</a></td>
     </tr>
 </tbody>
 </table>

package/dist/clients/deps/ast-grep-napi.js

@@ -1,3 +1,22 @@
+/**
+ * Centralized LAZY accessor for `@ast-grep/napi` (a native addon — loaded on
+ * demand, never at module-eval). See ./typescript.ts for the rationale.
+ * Types are re-exported; the module itself is fetched via `loadAstGrepNapi()`.
+ *
+ * Resolved to an absolute `file://` URL via `createRequire` before importing: an
+ * absolute-path dynamic import works under pi's bundled host, a bare specifier
+ * does not. The path is converted to a `file://` URL (a raw Windows path is not
+ * a valid import specifier); bare import kept as a fallback.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+const _require = createRequire(import.meta.url);
 export function loadAstGrepNapi() {
-    return import("@ast-grep/napi");
+    try {
+        const entry = _require.resolve("@ast-grep/napi");
+        return import(pathToFileURL(entry).href);
+    }
+    catch {
+        return import("@ast-grep/napi");
+    }
 }

package/dist/clients/deps/pi-tui.js

@@ -1,5 +1,8 @@
 /**
  * Centralized accessor for `@earendil-works/pi-tui`. See ./typescript.ts for the
  * rationale. (pi-tui is a pi-bundled core package, host-provided at runtime.)
+ *
+ * Re-export named bindings, not `export *`: with the package kept external, a
+ * wildcard re-export leaves the namespace undefined at runtime under the bundle.
  */
-export * from "@earendil-works/pi-tui";
+export { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";

package/dist/clients/deps/typebox.js

@@ -1,6 +1,9 @@
 /**
  * Centralized accessor for `typebox`. See ./typescript.ts for the rationale.
  * (typebox is a pi-bundled core package, so it resolves from the host at
- * runtime — but it's still routed through here for a uniform dep surface.)
+ * runtime -- but it's still routed through here for a uniform dep surface.)
+ *
+ * Re-export named bindings, not `export *`: with the package kept external, a
+ * wildcard re-export leaves the namespace undefined at runtime under the bundle.
  */
-export * from "typebox";
+export { Type } from "typebox";

package/dist/clients/deps/web-tree-sitter.js

@@ -1,3 +1,24 @@
+/**
+ * Centralized LAZY accessor for `web-tree-sitter` (wasm — loaded on demand). See
+ * ./typescript.ts for the rationale. Types are re-exported; the module itself is
+ * fetched via `loadWebTreeSitter()`.
+ *
+ * Resolved to an absolute `file://` URL via `createRequire` before importing: an
+ * absolute-path dynamic import works under pi's bundled host, a bare specifier
+ * does not. The package `exports` map exposes only the `.` entry (no custom
+ * subpath), so we resolve the bare package name and convert it to a `file://`
+ * URL (a raw Windows path is not a valid import specifier); bare import kept as
+ * a fallback.
+ */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+const _require = createRequire(import.meta.url);
 export function loadWebTreeSitter() {
-    return import("web-tree-sitter");
+    try {
+        const entry = _require.resolve("web-tree-sitter");
+        return import(pathToFileURL(entry).href);
+    }
+    catch {
+        return import("web-tree-sitter");
+    }
 }

package/dist/clients/instance-reaper.js

@@ -0,0 +1,418 @@
+/**
+ * Orphaned LSP process reaper (#472), built on the instance registry (#449
+ * slice 1).
+ *
+ * Split into a PURE decision function (`decideOrphanReaping`) and an IMPURE
+ * sweep (`sweepOrphans`) so the decision logic is unit-testable with fake
+ * pid tables — no real process spawns/kills in tests.
+ *
+ * Why the registry reaper, not EOF/processId alone (see issue #472): both are
+ * best-effort hints a well-behaved server may honor (typescript-language-server
+ * does; ast-grep's native exe does not — an upstream LSP-spec violation). The
+ * registry reaper works regardless of why a stdin pipe write-end stayed open
+ * after the parent died (Windows handle-inheritance capture) — it identifies
+ * dead-parent instances directly and kills the full recorded child tree, with
+ * a command-line marker fallback for the case where the pid itself was
+ * recycled or the mid-tree pid link is broken (e.g. a dead node-wrapper whose
+ * native-exe grandchild is still alive under a different, unrecorded pid).
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getGlobalPiLensDir } from "./file-utils.js";
+import { isInstanceRegistryEnabled, readInstanceRegistry, } from "./instance-registry.js";
+import { logLatency } from "./latency-logger.js";
+const isWindows = process.platform === "win32";
+/**
+ * Markers claimed by any LIVE instance's children. A marker search kills by
+ * command-line match, so a marker that a live session also uses must never
+ * be searched — killing it would take down the live session's server.
+ * Markers are per-process-unique by construction (sgconfig.ts embeds the
+ * pid), so this is defense in depth against non-unique markers ever
+ * reappearing (#472: the original shared baseline.sgconfig.yml would have
+ * made the fallback kill every live ast-grep on the machine).
+ */
+function collectLiveMarkers(registry, isPidAlive) {
+    const liveMarkers = new Set();
+    for (const instance of registry) {
+        if (!isPidAlive(instance.pid))
+            continue;
+        for (const child of instance.lspChildren) {
+            if (child.marker)
+                liveMarkers.add(child.marker);
+        }
+    }
+    return liveMarkers;
+}
+/**
+ * Classify one dead-parent instance's children into kills / marker-searches,
+ * appending onto the shared `out` accumulator. Extracted from
+ * `decideOrphanReaping` to keep cognitive complexity in check — no behavior
+ * change, just the per-instance inner loop pulled out.
+ */
+function classifyDeadInstanceChildren(instance, isPidAlive, matchProcess, liveMarkers, out) {
+    for (const child of instance.lspChildren) {
+        const childAlive = isPidAlive(child.pid);
+        if (childAlive) {
+            const identityOk = matchProcess
+                ? matchProcess(child.pid, {
+                    command: child.command,
+                    marker: child.marker,
+                })
+                : true;
+            if (identityOk) {
+                out.childrenToKill.push({
+                    pid: child.pid,
+                    serverId: child.serverId,
+                    command: child.command,
+                });
+                continue;
+            }
+        }
+        // Child pid is dead, or alive-but-identity-mismatched (recycled pid) —
+        // if we have a marker, surface it so the caller can find a live
+        // process (e.g. the native exe grandchild) by command-line match.
+        // Never surface a marker a live instance also claims (see above).
+        if (child.marker && !liveMarkers.has(child.marker)) {
+            out.markerSearches.push({ marker: child.marker, serverId: child.serverId });
+        }
+    }
+}
+/**
+ * Pure decision function: given the registry state and injectable liveness /
+ * identity predicates, decide what to kill. Performs zero I/O.
+ *
+ * @param isPidAlive - `process.kill(pid, 0)`-style liveness check. Must be
+ *   CONSERVATIVE: only pid-confirmed-dead (ESRCH) counts as dead. Any
+ *   ambiguous result (EPERM, or the caller's fake table saying "unknown")
+ *   must be treated as alive — never kill on an ambiguous signal-check.
+ * @param matchProcess - optional identity verification (e.g. confirm the
+ *   live pid's command line still matches what we recorded) to guard against
+ *   a recycled pid coincidentally matching. If omitted, liveness alone is used.
+ */
+export function decideOrphanReaping(registry, isPidAlive, matchProcess) {
+    const deadInstances = [];
+    const childrenToKill = [];
+    const markerSearches = [];
+    const liveMarkers = collectLiveMarkers(registry, isPidAlive);
+    for (const instance of registry) {
+        if (isPidAlive(instance.pid)) {
+            continue; // parent still alive — leave its children alone entirely
+        }
+        deadInstances.push(instance);
+        classifyDeadInstanceChildren(instance, isPidAlive, matchProcess, liveMarkers, {
+            childrenToKill,
+            markerSearches,
+        });
+    }
+    return { deadInstances, childrenToKill, markerSearches };
+}
+// --- 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) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true; // no throw — process exists and we can signal it
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ESRCH")
+            return false; // definitively dead
+        // EPERM (exists, no permission) or any other/unknown errno: ambiguous —
+        // never treat as dead.
+        return true;
+    }
+}
+function windowsExe(name) {
+    return path.join(process.env.SystemRoot ?? String.raw `C:\Windows`, "System32", name);
+}
+/** Resolve an absolute path to `ps` (S4036: never spawn via bare PATH lookup).
+ *  Prefers `/bin/ps` (present on virtually every POSIX system), falls back to
+ *  `/usr/bin/ps`, and defaults back to `/bin/ps` if neither probe succeeds
+ *  (spawn will then fail closed rather than silently resolving via PATH). */
+function posixPsPath() {
+    if (fs.existsSync("/bin/ps"))
+        return "/bin/ps";
+    if (fs.existsSync("/usr/bin/ps"))
+        return "/usr/bin/ps";
+    return "/bin/ps";
+}
+/** Escape a value for embedding in a WQL LIKE clause: WQL uses `'` as the
+ *  string delimiter (doubled to escape) and `%`/`_` as wildcards — the marker
+ *  is an opaque path string, so escape all three before interpolating. */
+function escapeWqlLikeValue(value) {
+    return value.replaceAll("'", "''").replaceAll(/[%_]/g, (ch) => `[${ch}]`);
+}
+/** Search running processes whose command line contains `marker` (Windows,
+ *  via CIM/WQL). Returns matching pids. Best-effort: any failure ⇒ []. */
+async function findPidsByMarkerWindows(marker) {
+    if (!isWindows || !marker)
+        return [];
+    const escaped = escapeWqlLikeValue(marker);
+    // $PID exclusion: the query's own powershell.exe command line embeds the
+    // marker string, so it would match itself.
+    const psScript = `Get-CimInstance Win32_Process -Filter "CommandLine LIKE '%${escaped}%'" ` +
+        `| Where-Object { $_.ProcessId -ne $PID } ` +
+        `| Select-Object -ExpandProperty ProcessId`;
+    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 pids = out
+                    .split(/\r?\n/)
+                    .map((line) => Number(line.trim()))
+                    .filter((n) => Number.isFinite(n) && n > 0);
+                resolve(pids);
+            });
+        }
+        catch {
+            resolve([]);
+        }
+    });
+}
+/** Fetch command lines for a set of pids in one query (Windows: CIM; POSIX:
+ *  `ps`). Returns a pid → command-line map; pids that can't be resolved are
+ *  simply absent (the caller treats absent as "identity unverifiable — do not
+ *  kill by pid"). Best-effort: any failure ⇒ empty map. */
+async function queryCommandLines(pids) {
+    const valid = [...new Set(pids.filter((p) => Number.isFinite(p) && p > 0))];
+    const map = new Map();
+    if (valid.length === 0)
+        return map;
+    if (isWindows) {
+        const filter = valid.map((p) => `ProcessId=${p}`).join(" OR ");
+        const psScript = `Get-CimInstance Win32_Process -Filter "${filter}" ` +
+            `| ForEach-Object { "$($_.ProcessId)\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(map));
+                child.once("close", () => {
+                    for (const line of out.split(/\r?\n/)) {
+                        const tab = line.indexOf("\t");
+                        if (tab <= 0)
+                            continue;
+                        const pid = Number(line.slice(0, tab).trim());
+                        if (Number.isFinite(pid) && pid > 0)
+                            map.set(pid, line.slice(tab + 1));
+                    }
+                    resolve(map);
+                });
+            }
+            catch {
+                resolve(map);
+            }
+        });
+    }
+    return new Promise((resolve) => {
+        try {
+            const child = nodeSpawn(posixPsPath(), ["-p", valid.join(","), "-o", "pid=,args="], { shell: false, stdio: ["ignore", "pipe", "ignore"] });
+            let out = "";
+            child.stdout?.on("data", (chunk) => {
+                out += chunk.toString();
+            });
+            child.once("error", () => resolve(map));
+            child.once("close", () => {
+                for (const line of out.split(/\r?\n/)) {
+                    // Linear parse (S8786/S6594: avoid regex backtracking on
+                    // attacker-lengthenable ps output) — trim leading whitespace,
+                    // then split on the first whitespace run: "  1234 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 pidStr = trimmed.slice(0, i);
+                    let j = i;
+                    while (j < trimmed.length && (trimmed[j] === " " || trimmed[j] === "\t"))
+                        j++;
+                    const pid = Number(pidStr);
+                    if (Number.isFinite(pid) && pid > 0)
+                        map.set(pid, trimmed.slice(j));
+                }
+                resolve(map);
+            });
+        }
+        catch {
+            resolve(map);
+        }
+    });
+}
+/**
+ * Build a `matchProcess` identity predicate from a pid → command-line map
+ * (as produced by `queryCommandLines`). PURE — exported for unit testing.
+ *
+ * Semantics (guarding pid kills against pid recycling):
+ * - pid absent from the map ⇒ false: identity is UNVERIFIABLE, so never kill
+ *   by pid (the marker-search fallback may still catch a real orphan).
+ * - marker recorded and present in the command line ⇒ match (strongest
+ *   signal — markers are per-spawn-unique).
+ * - else: the recorded command's basename appears (case-insensitive) in the
+ *   command line ⇒ match. Empty basename never matches (guard against a
+ *   recorded empty/odd command matching everything via `includes("")`).
+ */
+export function buildIdentityMatcher(cmdlines) {
+    return (pid, expected) => {
+        const cmdline = cmdlines.get(pid);
+        if (cmdline === undefined)
+            return false; // unverifiable ⇒ never kill by pid
+        if (expected.marker && cmdline.includes(expected.marker))
+            return true;
+        const basename = path.basename(expected.command ?? "").toLowerCase();
+        if (!basename)
+            return false;
+        return cmdline.toLowerCase().includes(basename);
+    };
+}
+/** Force-kill a pid's full process tree. Windows: `taskkill /F /T`. POSIX:
+ *  mirror killProcessTree's process-group kill, falling back to a direct
+ *  signal. Best-effort: swallow all errors. */
+async function killPidTree(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return;
+    if (isWindows) {
+        try {
+            const taskkill = windowsExe("taskkill.exe");
+            const killer = nodeSpawn(taskkill, ["/F", "/T", "/PID", String(pid)], {
+                shell: false,
+                windowsHide: true,
+                stdio: "ignore",
+            });
+            await new Promise((resolve) => {
+                killer.once("close", () => resolve());
+                killer.once("error", () => resolve());
+            });
+        }
+        catch {
+            // best-effort
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // best-effort — process may already be gone
+        }
+    }
+}
+/**
+ * Fire-and-forget orphan sweep: reads the registry, decides what's dead via
+ * `decideOrphanReaping`, kills orphaned LSP children (by pid, with a
+ * marker-based command-line search fallback), then drops fully-dead
+ * instances from the registry. Never throws — every step is wrapped so a
+ * reap failure cannot block or crash the caller (session_start).
+ */
+export async function sweepOrphans() {
+    if (!isInstanceRegistryEnabled())
+        return;
+    const startedAt = Date.now();
+    try {
+        const registry = await readInstanceRegistry();
+        if (registry.length === 0)
+            return;
+        // Identity verification before any pid kill (recycled-pid guard): fetch
+        // the command lines of every recorded child pid in ONE batched query,
+        // then let the pure decision function verify each live child's identity
+        // against what was recorded at spawn. A pid whose command line can't be
+        // fetched is treated as unverifiable and never killed by pid — the
+        // marker-search fallback may still catch it.
+        const candidatePids = registry.flatMap((instance) => instance.lspChildren.map((child) => child.pid));
+        const cmdlines = await queryCommandLines(candidatePids);
+        const matchProcess = buildIdentityMatcher(cmdlines);
+        const decision = decideOrphanReaping(registry, realIsPidAlive, matchProcess);
+        let killedCount = 0;
+        const killedServerIds = [];
+        for (const child of decision.childrenToKill) {
+            await killPidTree(child.pid);
+            killedCount++;
+            killedServerIds.push(child.serverId);
+        }
+        for (const search of decision.markerSearches) {
+            try {
+                const pids = await findPidsByMarkerWindows(search.marker);
+                for (const pid of pids) {
+                    await killPidTree(pid);
+                    killedCount++;
+                    killedServerIds.push(search.serverId);
+                }
+            }
+            catch {
+                // best-effort — a failed marker search just misses that orphan this sweep
+            }
+        }
+        if (decision.deadInstances.length > 0) {
+            try {
+                const deadPids = new Set(decision.deadInstances.map((i) => i.pid));
+                await pruneDeadInstances(deadPids);
+            }
+            catch {
+                // best-effort — a stale registry entry is re-evaluated next sweep
+            }
+        }
+        try {
+            logLatency({
+                type: "phase",
+                phase: "orphan_lsp_reaped",
+                filePath: "",
+                durationMs: Date.now() - startedAt,
+                metadata: {
+                    deadInstances: decision.deadInstances.length,
+                    killed: killedCount,
+                    serverIds: killedServerIds,
+                    markerSearches: decision.markerSearches.length,
+                },
+            });
+        }
+        catch {
+            // best-effort logging only
+        }
+    }
+    catch {
+        // The sweep must never throw out of session_start.
+    }
+}
+/** Drop dead-parent instances from the registry. Re-reads immediately before
+ *  writing (rather than reusing the earlier `readInstanceRegistry()` snapshot)
+ *  to narrow — not eliminate — the last-writer-wins race already accepted for
+ *  slice 1's read-modify-write model. */
+async function pruneDeadInstances(deadPids) {
+    const target = path.join(getGlobalPiLensDir(), "instances.json");
+    try {
+        const raw = await fs.promises.readFile(target, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.instances))
+            return;
+        const remaining = parsed.instances.filter((entry) => !deadPids.has(entry.pid));
+        if (remaining.length === parsed.instances.length)
+            return;
+        const tmpPath = `${target}.tmp-${process.pid}`;
+        await fs.promises.mkdir(getGlobalPiLensDir(), { recursive: true });
+        await fs.promises.writeFile(tmpPath, JSON.stringify({ instances: remaining }), "utf-8");
+        await fs.promises.rename(tmpPath, target);
+    }
+    catch {
+        // best-effort
+    }
+}