pi-lens 3.8.62 → 3.8.63

package/CHANGELOG.md

@@ -10,6 +10,21 @@ All notable changes to pi-lens will be documented in this file.
 
 ### Fixed
 
+## [3.8.63] - 2026-07-01
+
+### Added
+
+### Changed
+
+- **Consolidated the timeout-race helpers into one shared `clients/deadline-utils.ts` (#366)** — the "race a promise against a timer" pattern had drifted into three near-identical copies (`withTimeout` in the LSP client, `withBudget` in read-expansion, `withinRemaining` in module-report). They're now thin adapters over one `withDeadline` core, which also fixes two latent bugs the copies carried: `withBudget` didn't suppress the loser promise's late rejection (an unhandled rejection when the timer won first), and `withinRemaining` never cleared its timer. Behaviour at every call site is unchanged (covered by the consumer suites); the core's semantics are locked by dedicated tests including an explicit late-rejection-suppression probe.
+
+### Fixed
+
+- **Bounded the remaining unbounded LSP requests — `workspace/symbol`, `textDocument/codeAction`, `workspace/executeCommand` (#365)** — like the pull-diagnostics fix (#364), these were sent via `safeSendRequest` with no `withTimeout` ceiling, so a language server that accepts a request but never replies (alive but hung) would make the `await` never resolve — hanging symbol search (`pilens_symbol_search`), code-action lookups, and server-command execution. `workspace/symbol` and `textDocument/codeAction` now route through the shared `navRequest` helper (its `withTimeout` ceiling + single-file stale-drop), timing out to `[]`. `workspace/executeCommand` — which is mutating and legitimately long-running — gets a separate, generous 30s anti-deadlock backstop (`PI_LENS_LSP_EXECUTE_COMMAND_TIMEOUT_MS`) that returns an honest `executed:false, reason:"…may still be applying server-side"` rather than truncating valid work or pretending it ran; its allowlist-by-advertisement and server-edit-window hardening are preserved. Real (non-timeout) errors still propagate throughout.
+- **Autofix project-snapshot walk no longer freezes the TUI on large repos (#368)** — `snapshotProjectFiles` (the `tool_result` autofix side-effect detection that snapshots the project tree before/after a formatter or fixer runs, to catch files it changed as a side effect) was a fully synchronous `readdirSync`/`statSync` walk bounded only by a 5,000-file cap — a ~130ms event-loop block at the cap (2–4× that under load), stalling keystrokes on large projects while autofix ran. It now walks asynchronously and yields to the event loop every 500 files, so it holds the loop only for a short chunk. The scan cap and directory-exclusion/confinement behavior are unchanged; a cap-scale (~5k-file) event-loop occupancy guard asserts the walk keeps yielding.
+- **Bounded LSP pull-diagnostics request — a hung server can no longer hang `lens_diagnostics` (#349, #364)** — the pull path in `clientWaitForDiagnostics` awaited a `textDocument/diagnostic` request via `safeSendRequest`, which only settles on a reply or a *destroyed* stream. A pull-mode server that is alive but hung (accepts the request, never replies) made that `await` never resolve, hanging the diagnostics wait → the `dispatch_lint` pipeline phase → `flushDebouncedToolResults` → `lens_diagnostics`, forever (and `safeSpawnAsync`'s 30s cap doesn't apply — it's a pipe request, not a spawn). Unlike the navigation/init/shutdown callers, this request had no `withTimeout` ceiling; the `timeoutMs` passed into `clientWaitForDiagnostics` only bounded the push backstop and the pull *retry interval*, never the individual request. The request is now wrapped in the existing `withTimeout` helper, bounded by `min(PULL_REQUEST_TIMEOUT_MS, remaining caller budget)` (env `PI_LENS_LSP_PULL_REQUEST_TIMEOUT_MS`, default 10s, mirroring `NAV_REQUEST_TIMEOUT_MS`). On timeout the request is caught as `unavailable`, which per #240 is not read as clean and falls through to the already-bounded push backstop. Explains the intermittent repro — it only fires for pull-mode servers (rust-analyzer being the classic) stalling mid-analysis. Regression test: a pull server whose `sendRequest` never resolves now resolves within the caller's budget instead of hanging.
+- **POSIX LSP teardown now cleans up the whole process tree, not just the direct child (#362, #363)** — on POSIX, LSP servers launched through wrappers (npm shims, shell/node launchers) could leave descendants alive after pi-lens reset or shut down an LSP service; observed most visibly as `vscode-html-language-server` processes accumulating across long-lived zellij sessions and pressuring memory. LSP servers are now spawned detached into their own process group and teardown signals the group (`process.kill(-pid, ...)`) before falling back to the direct child, bringing POSIX cleanup in line with the existing Windows `taskkill /T` behavior. Windows teardown is unchanged (`taskkill /T` mid-session, handle-only kill for `processExiting`). Guarded by the `pid <= 0` check so a group signal can never degrade into `process.kill(-0)` against pi-lens's own process group.
+
 ## [3.8.62] - 2026-06-28
 
 ### Added

package/dist/clients/deadline-utils.js

@@ -0,0 +1,70 @@
+/**
+ * One implementation of the "race a promise against a timer" pattern that had
+ * drifted into three near-identical copies (#366): `withTimeout` (clients/lsp),
+ * `withBudget` (read-expansion), and `withinRemaining` (module-report-lsp).
+ *
+ * The differences between them were real — timeout can *reject* or *resolve
+ * undefined*, and the raced promise's own rejection can *propagate* or be
+ * *swallowed* — so they are kept as named adapters over one core. Consolidating
+ * fixes two latent bugs the copies had: `withBudget` did not suppress the loser
+ * promise's late rejection (an unhandled rejection if the timer won first), and
+ * `withinRemaining` never cleared its timer.
+ */
+export function withDeadline(promise, options) {
+    const onTimeout = options.onTimeout ?? "reject";
+    const onReject = options.onReject ?? "propagate";
+    const ms = options.ms ??
+        (options.deadlineAt !== undefined ? options.deadlineAt - Date.now() : 0);
+    // Past deadline / non-positive budget: settle immediately, no timer.
+    if (ms <= 0) {
+        return onTimeout === "undefined"
+            ? Promise.resolve(undefined)
+            : Promise.reject(new Error(`Timeout after ${Math.max(0, ms)}ms`));
+    }
+    // Base promise with rejection handled per `onReject`. In propagate mode we
+    // still attach a no-op catch so that if the timer wins the race, the loser
+    // promise's later rejection does not surface as an unhandled rejection.
+    const base = onReject === "undefined" ? promise.catch(() => undefined) : promise;
+    if (onReject === "propagate")
+        promise.catch(() => { });
+    let timer;
+    const timeoutPromise = new Promise((resolve, reject) => {
+        timer = setTimeout(() => {
+            if (onTimeout === "undefined")
+                resolve(undefined);
+            else
+                reject(new Error(`Timeout after ${ms}ms`));
+        }, ms);
+    });
+    return Promise.race([base, timeoutPromise]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+/**
+ * Resolve `promise`, or reject with `Error("Timeout after <ms>ms")` once
+ * `timeoutMs` elapses. The raced promise's own rejection propagates.
+ */
+export function withTimeout(promise, timeoutMs) {
+    return withDeadline(promise, { ms: timeoutMs });
+}
+/**
+ * Resolve `promise`, or `undefined` once `budgetMs` elapses (a non-positive
+ * budget resolves `undefined` immediately). The raced promise's own rejection
+ * propagates.
+ */
+export function withBudget(promise, budgetMs) {
+    return withDeadline(promise, { ms: budgetMs, onTimeout: "undefined" });
+}
+/**
+ * Resolve `promise`, or `undefined` once the shared `deadlineAt` passes (a past
+ * deadline resolves `undefined` immediately). The raced promise's own rejection
+ * is swallowed to `undefined`.
+ */
+export function withinRemaining(promise, deadlineAt) {
+    return withDeadline(promise, {
+        deadlineAt,
+        onTimeout: "undefined",
+        onReject: "undefined",
+    });
+}

package/dist/clients/installer/index.js

@@ -1150,6 +1150,8 @@ export async function updateProbeCache(toolId, resolvedPath) {
 export function resetProbeCacheStateForTesting() {
     _probeCache = null;
     _probeCacheDirty = false;
+    resolvedPathCache.clear();
+    ensureInFlight.clear();
     if (_probeCacheFlushTimer !== null) {
         clearTimeout(_probeCacheFlushTimer);
         _probeCacheFlushTimer = null;
@@ -2559,8 +2561,17 @@ export async function installTool(toolId) {
  * Ensure a tool is installed (check first, install if missing)
  */
 export async function ensureTool(toolId, opts) {
+    const cacheResolvedPath = (result) => {
+        if (result) {
+            resolvedPathCache.set(toolId, result);
+            void updateProbeCache(toolId, result);
+        }
+        return result;
+    };
     // forceReinstall: nuke caches, download from managed source, skip PATH entirely.
     // Used when a PATH-resolved tool proves broken at launch (e.g. broken symlink).
+    // allowInstall:false wins over forceReinstall: caches are still cleared, but
+    // the function falls back to discovery-only and never downloads.
     if (opts?.forceReinstall) {
         const ensureStartMs = Date.now();
         logSessionStart(`auto-install ensure ${toolId}: force reinstall — clearing caches`);
@@ -2576,6 +2587,10 @@ export async function ensureTool(toolId, opts) {
         catch {
             // best-effort
         }
+        if (opts.allowInstall === false) {
+            logSessionStart(`auto-install ensure ${toolId}: force reinstall blocked — install disabled, discovery only (${Date.now() - ensureStartMs}ms)`);
+            return cacheResolvedPath(await getToolPath(toolId));
+        }
         // Force download
         const installed = await installTool(toolId);
         if (!installed) {
@@ -2583,10 +2598,8 @@ export async function ensureTool(toolId, opts) {
             return undefined;
         }
         // Find the newly installed binary (github-local check now comes before PATH)
-        const result = await getToolPath(toolId);
+        const result = cacheResolvedPath(await getToolPath(toolId));
         if (result) {
-            resolvedPathCache.set(toolId, result);
-            void updateProbeCache(toolId, result);
             logSessionStart(`auto-install ensure ${toolId}: force reinstall success at ${result} (${Date.now() - ensureStartMs}ms)`);
         }
         return result;
@@ -2604,10 +2617,13 @@ export async function ensureTool(toolId, opts) {
     }
     // Coalesce the whole ensure operation, not just installation. Most startup
     // duplicates race while checking already-installed tools, before installTool()
-    // would ever run.
-    const inFlight = ensureInFlight.get(toolId);
+    // would ever run. The key includes the install policy so a discovery-only
+    // caller cannot accidentally inherit an install-allowed caller's download (or
+    // vice versa).
+    const inFlightKey = opts?.allowInstall === false ? `${toolId}:discovery-only` : toolId;
+    const inFlight = ensureInFlight.get(inFlightKey);
     if (inFlight) {
-        logSessionStart(`auto-install ensure ${toolId}: waiting for in-flight ensure`);
+        logSessionStart(`auto-install ensure ${toolId}: waiting for in-flight ensure (${inFlightKey})`);
         return inFlight;
     }
     const ensureStartMs = Date.now();
@@ -2621,6 +2637,14 @@ export async function ensureTool(toolId, opts) {
             logSessionStart(`auto-install ensure ${toolId}: already available at ${existingPath} (${Date.now() - ensureStartMs}ms)`);
             return existingPath;
         }
+        // Discovery and install are SEPARATE concerns. getToolPath() above already
+        // probed PATH / npm-global / managed bin — offline-safe, no download. When the
+        // caller forbids installs (allowInstall:false, e.g. PI_LENS_DISABLE_LSP_INSTALL=1)
+        // we must still return a discovered binary and only skip the actual install.
+        if (opts?.allowInstall === false) {
+            logSessionStart(`auto-install ensure ${toolId}: install disabled — discovery only, not found (${Date.now() - ensureStartMs}ms)`);
+            return undefined;
+        }
         const installed = await installTool(toolId);
         if (!installed) {
             logSessionStart(`auto-install ensure ${toolId}: unavailable (${Date.now() - ensureStartMs}ms)`);
@@ -2637,12 +2661,12 @@ export async function ensureTool(toolId, opts) {
         }
         return result;
     })();
-    ensureInFlight.set(toolId, ensurePromise);
+    ensureInFlight.set(inFlightKey, ensurePromise);
     try {
         return await ensurePromise;
     }
     finally {
-        ensureInFlight.delete(toolId);
+        ensureInFlight.delete(inFlightKey);
     }
 }
 // --- Integration Helpers ---

package/dist/clients/lsp/client.js

@@ -11,6 +11,7 @@ import { spawn as nodeSpawn } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { access, readFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
+import { withTimeout } from "../deadline-utils.js";
 import { logLatency } from "../latency-logger.js";
 // vscode-jsonrpc v9 ships an `exports` map exposing the Node entry as the
 // `./node` subpath (no `.js`); the old `/node.js` file path no longer resolves.
@@ -76,7 +77,20 @@ export const CLIENT_CAPABILITIES = {
 const NAV_REQUEST_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_NAV_REQUEST_TIMEOUT_MS", 10_000); // 10s — per-request ceiling; prevents heavy servers (vue, svelte) from hanging
 const DIAGNOSTICS_WAIT_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_DIAGNOSTICS_WAIT_MS", 10_000);
 const PULL_DIAGNOSTICS_RETRY_INTERVAL_MS = positiveIntFromEnv("PI_LENS_LSP_PULL_RETRY_INTERVAL_MS", 250);
+// Per-request ceiling for pull diagnostics (textDocument/diagnostic), mirroring
+// NAV_REQUEST_TIMEOUT_MS. safeSendRequest only settles on a reply or a *destroyed*
+// stream, so a pull-mode server that is alive but hung (accepts the request, never
+// replies) would await forever — hanging clientWaitForDiagnostics and, upstream,
+// the diagnostics flush. On timeout the request is treated as `unavailable`, which
+// (per #240) is NOT read as clean and falls through to the bounded push backstop.
+const PULL_REQUEST_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_PULL_REQUEST_TIMEOUT_MS", 10_000);
 const SHUTDOWN_REQUEST_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_SHUTDOWN_TIMEOUT_MS", 1000);
+// Anti-deadlock backstop for workspace/executeCommand. Deliberately generous
+// (30s): the command is mutating and legitimately long-running (a real server
+// refactor / organize-imports), so this must not truncate valid work — it only
+// stops a hung server from blocking the caller forever. On timeout the command
+// may still be applying server-side; we surface that rather than pretend it ran.
+const EXECUTE_COMMAND_TIMEOUT_MS = positiveIntFromEnv("PI_LENS_LSP_EXECUTE_COMMAND_TIMEOUT_MS", 30_000);
 const LSP_CRASH_CODES = new Set([
     "ERR_STREAM_DESTROYED",
     "ERR_STREAM_WRITE_AFTER_END",
@@ -179,18 +193,36 @@ export async function killProcessTree(proc, pid, options = {}) {
         }
         return;
     }
+    const killPosixProcessGroup = (signal) => {
+        if (pid <= 0)
+            return false;
+        try {
+            process.kill(-pid, signal);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const killDirectChild = (signal) => {
+        try {
+            proc.kill(signal);
+        }
+        catch {
+            // best-effort
+        }
+    };
     try {
-        proc.kill("SIGTERM");
+        if (!killPosixProcessGroup("SIGTERM")) {
+            killDirectChild("SIGTERM");
+        }
         if (options.fast) {
             const timer = setTimeout(() => {
-                try {
-                    if (!proc.killed) {
-                        proc.kill("SIGKILL");
+                if (!proc.killed) {
+                    if (!killPosixProcessGroup("SIGKILL")) {
+                        killDirectChild("SIGKILL");
                     }
                 }
-                catch {
-                    // best-effort
-                }
             }, 1500);
             timer.unref?.();
             proc.unref?.();
@@ -199,14 +231,11 @@ export async function killProcessTree(proc, pid, options = {}) {
         // SIGTERM → 1.5s → SIGKILL escalation.
         // SIGTERM alone can leave zombie processes if the server hangs.
         await new Promise((resolve) => setTimeout(resolve, 1500));
-        try {
-            if (!proc.killed) {
-                proc.kill("SIGKILL");
+        if (!proc.killed) {
+            if (!killPosixProcessGroup("SIGKILL")) {
+                killDirectChild("SIGKILL");
             }
         }
-        catch {
-            // best-effort
-        }
     }
     catch {
         // ignore
@@ -439,12 +468,17 @@ function setupConnectionLifecycle(state) {
         }
     });
 }
-async function clientRequestPullDiagnostics(state, filePath) {
+async function clientRequestPullDiagnostics(state, filePath, budgetMs = PULL_REQUEST_TIMEOUT_MS) {
     if (!isClientAlive(state))
         return { status: "unavailable" };
     const uri = pathToFileURL(filePath).href;
     try {
-        const report = await safeSendRequest(state.connection, "textDocument/diagnostic", { textDocument: { uri } });
+        // withTimeout is the backstop against a hung pull-mode server: without it
+        // this await never settles unless the stream is destroyed. Bounded by the
+        // smaller of the absolute ceiling and the caller's remaining wait budget.
+        // On timeout the caught error yields `unavailable` below (never a false
+        // `clean`), so it falls through to the push-wait/timeout backstop.
+        const report = await withTimeout(safeSendRequest(state.connection, "textDocument/diagnostic", { textDocument: { uri } }), Math.max(1, Math.min(PULL_REQUEST_TIMEOUT_MS, budgetMs)));
         if (!report)
             return { status: "unavailable" };
         const normalizedPath = normalizeMapKey(filePath);
@@ -499,7 +533,7 @@ export async function clientWaitForDiagnostics(state, filePath, timeoutMs, optio
         // `hasFreshDiagnostics()`, which is unconditionally true when there is no
         // version baseline (`minVersion === undefined`), so a failed pull returned
         // 0 and was read as a fresh clean.
-        let outcome = await clientRequestPullDiagnostics(state, filePath);
+        let outcome = await clientRequestPullDiagnostics(state, filePath, timeoutMs);
         if (outcome.status === "found")
             return;
         let sawClean = outcome.status === "clean";
@@ -513,7 +547,7 @@ export async function clientWaitForDiagnostics(state, filePath, timeoutMs, optio
         // any point is a valid affirmative answer for this touch.
         while (outcome.status !== "found" && Date.now() - startedAt < retryBudgetMs) {
             await new Promise((resolve) => setTimeout(resolve, PULL_DIAGNOSTICS_RETRY_INTERVAL_MS));
-            outcome = await clientRequestPullDiagnostics(state, filePath);
+            outcome = await clientRequestPullDiagnostics(state, filePath, Math.max(0, retryBudgetMs - (Date.now() - startedAt)));
             if (outcome.status === "clean")
                 sawClean = true;
         }
@@ -714,18 +748,20 @@ async function toWirePosition(state, filePath, line, character) {
 function navStaleDropEnabled() {
     return process.env.PI_LENS_LSP_NAV_STALE_DROP !== "0";
 }
-async function navRequest(state, method, params, 
+// Exported for the timeout regression tests (#365). `timeoutMs` overrides the
+// per-request ceiling so a test can bound a hung server quickly.
+export async function navRequest(state, method, params, 
 // When provided, the request is dropped if the document's version advances
 // (an edit landed) between send and response. Omit for non-single-file
 // requests (workspaceSymbol, call-hierarchy follow-ups) that have no version.
-staleCheckPath) {
+staleCheckPath, timeoutMs = NAV_REQUEST_TIMEOUT_MS) {
     if (!isClientAlive(state))
         return null;
     const normalizedPath = staleCheckPath !== undefined ? normalizeMapKey(staleCheckPath) : undefined;
     const requestVersion = normalizedPath !== undefined
         ? state.documentVersions.get(normalizedPath)
         : undefined;
-    const result = (await withTimeout(safeSendRequest(state.connection, method, params), NAV_REQUEST_TIMEOUT_MS).catch((err) => {
+    const result = (await withTimeout(safeSendRequest(state.connection, method, params), timeoutMs).catch((err) => {
         if (err instanceof Error && err.message.startsWith("Timeout after")) {
             return undefined;
         }
@@ -743,6 +779,50 @@ staleCheckPath) {
     }
     return result;
 }
+// Run an advertised server command via workspace/executeCommand, with the
+// generous EXECUTE_COMMAND_TIMEOUT_MS anti-deadlock backstop. Preserves the
+// hardening invariants: allowlist-by-advertisement (only commands the server
+// declared) and the serverEditsAllowed window that gates server-driven
+// applyEdit to the duration of an explicit call. Exported with an overridable
+// `timeoutMs` for the #365 regression tests.
+export async function runServerCommand(state, command, args, timeoutMs = EXECUTE_COMMAND_TIMEOUT_MS) {
+    if (!isClientAlive(state)) {
+        return { executed: false, reason: "lsp client not alive" };
+    }
+    if (!state.advertisedCommands.has(command)) {
+        return {
+            executed: false,
+            reason: `command "${command}" is not advertised by the ${state.serverId} server`,
+        };
+    }
+    state.serverEditsAllowed += 1;
+    try {
+        let result;
+        try {
+            result = await withTimeout(safeSendRequest(state.connection, "workspace/executeCommand", {
+                command,
+                arguments: args ?? [],
+            }), timeoutMs);
+        }
+        catch (err) {
+            // Generous backstop only: a timeout means the server is hung (or the
+            // command is running longer than the ceiling). Surface it honestly — the
+            // command may still be applying — instead of hanging the caller. Real
+            // (non-timeout) errors still propagate.
+            if (err instanceof Error && err.message.startsWith("Timeout after")) {
+                return {
+                    executed: false,
+                    reason: `workspace/executeCommand timed out after ${timeoutMs}ms — the command may still be applying server-side`,
+                };
+            }
+            throw err;
+        }
+        return { executed: true, result };
+    }
+    finally {
+        state.serverEditsAllowed -= 1;
+    }
+}
 async function resolveCodeActionBestEffort(state, action) {
     if (!isClientAlive(state) || action.edit)
         return action;
@@ -1009,25 +1089,7 @@ export async function createLSPClient(options) {
             return state.rawCapabilityKeys ?? [];
         },
         async executeCommand(command, args) {
-            if (!isClientAlive(state)) {
-                return { executed: false, reason: "lsp client not alive" };
-            }
-            // Hardening: allowlist-by-advertisement. Only commands the server
-            // itself declared (static or dynamic) may run — no arbitrary strings.
-            if (!state.advertisedCommands.has(command)) {
-                return {
-                    executed: false,
-                    reason: `command "${command}" is not advertised by the ${state.serverId} server`,
-                };
-            }
-            state.serverEditsAllowed += 1;
-            try {
-                const result = await safeSendRequest(state.connection, "workspace/executeCommand", { command, arguments: args ?? [] });
-                return { executed: true, result };
-            }
-            finally {
-                state.serverEditsAllowed -= 1;
-            }
+            return runServerCommand(state, command, args);
         },
         get diagnosticsVersion() {
             return state.diagnosticsVersion;
@@ -1091,14 +1153,22 @@ export async function createLSPClient(options) {
         async workspaceSymbol(query) {
             if (!isClientAlive(state))
                 return [];
-            const result = await safeSendRequest(connection, "workspace/symbol", { query });
+            // Route through navRequest for the shared withTimeout ceiling — a hung
+            // server would otherwise await forever (safeSendRequest only settles on
+            // a reply or a destroyed stream). No staleCheckPath: not single-file.
+            const result = await navRequest(state, "workspace/symbol", {
+                query,
+            });
             return result ?? [];
         },
         async codeAction(filePath, line, character, endLine, endCharacter) {
             if (!isClientAlive(state))
                 return [];
             const uri = pathToFileURL(filePath).href;
-            const result = await safeSendRequest(connection, "textDocument/codeAction", {
+            // navRequest adds the shared withTimeout ceiling + single-file
+            // stale-drop (matches documentSymbol); a hung server no longer awaits
+            // forever, and code actions computed against superseded content drop.
+            const result = await navRequest(state, "textDocument/codeAction", {
                 textDocument: { uri },
                 range: {
                     start: await toWirePosition(state, filePath, line, character),
@@ -1107,7 +1177,7 @@ export async function createLSPClient(options) {
                 context: {
                     diagnostics: getMergedDiagnosticsForPath(state, normalizeMapKey(filePath)),
                 },
-            });
+            }, filePath);
             if (!result || !Array.isArray(result))
                 return [];
             const actions = result.filter((item) => typeof item === "object" && item !== null && "title" in item);
@@ -1222,25 +1292,6 @@ function isStreamError(err) {
         err.code === "EPIPE");
 }
 // Using shared path utilities from path-utils.ts
-async function withTimeout(promise, timeoutMs) {
-    let timeout;
-    // Suppress unhandled rejection if `promise` rejects AFTER the timeout
-    // wins the race — Promise.race settles on the first result but the
-    // losing promises still run, and any later rejection would be uncaught.
-    promise.catch(() => { });
-    try {
-        return await Promise.race([
-            promise,
-            new Promise((_, reject) => {
-                timeout = setTimeout(() => reject(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs);
-            }),
-        ]);
-    }
-    finally {
-        if (timeout)
-            clearTimeout(timeout);
-    }
-}
 function positiveIntFromEnv(name, fallback) {
     const raw = process.env[name];
     if (!raw)

package/dist/clients/lsp/index.js

@@ -528,6 +528,16 @@ export class LSPService {
             if (!spawned) {
                 logSessionStart(`lsp spawn ${server.id}: unavailable (${Date.now() - startedAt}ms)`);
                 recordLsp(server.id, root, "spawn_failed", Date.now() - startedAt);
+                // When installs are disabled, an unavailable binary is an expected
+                // policy outcome, not proof the server/root is broken. Cool down briefly
+                // to avoid hot-looping PATH probes, but do not count toward permanent
+                // disablement: a user may install or expose the binary on PATH during the
+                // same session and should not need a full LSP reset.
+                if (!allowInstall) {
+                    logSessionStart(`lsp spawn ${server.id}: unavailable with install disabled; temporary cooldown only`);
+                    this.state.broken.set(key, Date.now() + BROKEN_BASE_COOLDOWN_MS);
+                    return undefined;
+                }
                 const uCount = (this.failureCounts.get(key) ?? 0) + 1;
                 this.failureCounts.set(key, uCount);
                 const uCooldown = Math.min(BROKEN_BASE_COOLDOWN_MS * 2 ** (uCount - 1), BROKEN_MAX_COOLDOWN_MS);

package/dist/clients/lsp/launch.js

@@ -294,7 +294,7 @@ function trySpawn(command, args, cwd, env, needsShell) {
             cwd,
             env,
             stdio: ["pipe", "pipe", "pipe"],
-            detached: false,
+            detached: !isWindows,
             windowsHide: true,
             shell: true,
         });
@@ -305,7 +305,7 @@ function trySpawn(command, args, cwd, env, needsShell) {
             cwd,
             env,
             stdio: ["pipe", "pipe", "pipe"],
-            detached: false,
+            detached: !isWindows,
             windowsHide: isWindows,
         });
     }

package/dist/clients/lsp/server.js

@@ -696,20 +696,22 @@ async function findTsserverPath(root, allowInstall) {
             /* not found */
         }
     }
-    if (canInstall(allowInstall)) {
-        const tscPath = await ensureTool("typescript");
-        if (tscPath) {
-            for (const p of [
-                path.join(path.dirname(tscPath), "..", "typescript", "lib", "tsserver.js"),
-                path.join(path.dirname(tscPath), "..", "..", "typescript", "lib", "tsserver.js"),
-            ]) {
-                try {
-                    await fs.access(p);
-                    return p;
-                }
-                catch {
-                    /* not found */
-                }
+    // Discover the typescript install (PATH / npm-global) even when install is
+    // disabled; only the download is gated by allowInstall.
+    const tscPath = await ensureTool("typescript", {
+        allowInstall: canInstall(allowInstall),
+    });
+    if (tscPath) {
+        for (const p of [
+            path.join(path.dirname(tscPath), "..", "typescript", "lib", "tsserver.js"),
+            path.join(path.dirname(tscPath), "..", "..", "typescript", "lib", "tsserver.js"),
+        ]) {
+            try {
+                await fs.access(p);
+                return p;
+            }
+            catch {
+                /* not found */
             }
         }
     }
@@ -933,12 +935,16 @@ export const TypeScriptServer = {
                 /* not found */
             }
         }
-        // Fall back to auto-installed version
+        // Fall back to a discovered or managed install. ensureTool() runs PATH /
+        // npm-global discovery even when install is disabled (only the download is
+        // gated by canInstall), so a globally-installed typescript-language-server
+        // resolves even without a per-project node_modules/.bin entry.
         if (!lspPath) {
-            if (canInstall(options?.allowInstall)) {
-                lspPath = await ensureTool("typescript-language-server");
+            lspPath = await ensureTool("typescript-language-server", {
+                allowInstall: canInstall(options?.allowInstall),
+            });
+            if (lspPath)
                 source = "managed";
-            }
             if (!lspPath) {
                 return undefined;
             }
@@ -1029,10 +1035,11 @@ export const PythonServer = {
                 initialization: pyrightInit(pythonPath),
             };
         }
-        if (!canInstall(options?.allowInstall)) {
-            return undefined;
-        }
-        const pyrightPath = await ensureTool("pyright");
+        // Discover a globally-installed pyright even when install is disabled;
+        // only the download is gated by canInstall.
+        const pyrightPath = await ensureTool("pyright", {
+            allowInstall: canInstall(options?.allowInstall),
+        });
         if (!pyrightPath)
             return undefined;
         source = "managed";

package/dist/clients/module-report-lsp.js

@@ -16,6 +16,7 @@
  *   - OPT-IN: disabled by default (budget 0) until validated in a real pi session;
  *     enable with PI_LENS_MODULE_REPORT_LSP_BUDGET_MS.
  */
+import { withinRemaining } from "./deadline-utils.js";
 import { uriToPath } from "./path-utils.js";
 let _lspBudgetMs;
 let lspEnrichmentTail = Promise.resolve();
@@ -82,12 +83,6 @@ function lspLocationsToUsedBy(locs, cap) {
     }
     return out;
 }
-function sleep(ms) {
-    return new Promise((resolve) => {
-        const timer = setTimeout(resolve, Math.max(0, ms));
-        timer.unref?.();
-    });
-}
 async function runWithExclusiveLspSweep(work) {
     const previous = lspEnrichmentTail.catch(() => undefined);
     let release;
@@ -102,16 +97,6 @@ async function runWithExclusiveLspSweep(work) {
         release();
     }
 }
-/** Resolve `promise`, or `undefined` once the shared deadline passes. */
-async function withinRemaining(promise, deadlineAt) {
-    const remaining = deadlineAt - Date.now();
-    if (remaining <= 0)
-        return undefined;
-    return Promise.race([
-        promise.catch(() => undefined),
-        sleep(remaining).then(() => undefined),
-    ]);
-}
 /**
  * Best-effort live-LSP enrichment for the requested file's exported symbols.
  * On-demand: the first `references` call spawns/reuses the language server for

package/dist/clients/pipeline.js

@@ -36,49 +36,70 @@ const LSP_MAX_FILE_BYTES = RUNTIME_CONFIG.pipeline.lspMaxFileBytes;
 const LSP_MAX_FILE_LINES = RUNTIME_CONFIG.pipeline.lspMaxFileLines;
 const LSP_SPAWN_BUDGET_MS = RUNTIME_CONFIG.pipeline.lspSpawnBudgetMs;
 const AUTOFIX_CHANGED_FILE_SCAN_LIMIT = 5000;
-function snapshotProjectFiles(root) {
-    const snapshot = new Map();
-    const projectRoot = path.resolve(root);
-    const ignoreMatcher = getProjectIgnoreMatcher(projectRoot);
-    const stack = [projectRoot];
-    while (stack.length > 0 && snapshot.size < AUTOFIX_CHANGED_FILE_SCAN_LIMIT) {
-        const dir = stack.pop();
-        let entries;
+// Scan one directory's entries into `snapshot`, pushing walkable subdirs onto
+// `stack`. Extracted from the walk loop to keep each function's cognitive
+// complexity low. Excluded/ignored dirs are not descended; ignored/vanished
+// files are skipped.
+// Files stat'd between event-loop yields. The walk stays on the tool_result
+// hot path; yielding every N keeps its longest synchronous stretch well under
+// the <50ms hook-burst budget even at the AUTOFIX_CHANGED_FILE_SCAN_LIMIT cap.
+const SNAPSHOT_YIELD_EVERY = 500;
+// Scan one directory's entries into `snapshot`, pushing walkable subdirs onto
+// `stack`. Yields to the event loop every SNAPSHOT_YIELD_EVERY files (shared
+// `counter`) so a single huge directory can't hold the loop. Excluded/ignored
+// dirs are not descended; ignored/vanished files are skipped.
+async function snapshotDirInto(dir, ignoreMatcher, stack, snapshot, counter) {
+    let entries;
+    try {
+        entries = nodeFs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!isExcludedDirName(entry.name) &&
+                !ignoreMatcher.isIgnored(fullPath, true)) {
+                stack.push(fullPath);
+            }
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (ignoreMatcher.isIgnored(fullPath, false))
+            continue;
         try {
-            entries = nodeFs.readdirSync(dir, { withFileTypes: true });
+            const stat = nodeFs.statSync(fullPath);
+            snapshot.set(path.resolve(fullPath), {
+                mtimeMs: stat.mtimeMs,
+                size: stat.size,
+            });
         }
         catch {
-            continue;
+            // ignore vanished files
         }
-        for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                if (!isExcludedDirName(entry.name) &&
-                    !ignoreMatcher.isIgnored(fullPath, true)) {
-                    stack.push(fullPath);
-                }
-                continue;
-            }
-            if (!entry.isFile())
-                continue;
-            if (ignoreMatcher.isIgnored(fullPath, false))
-                continue;
-            try {
-                const stat = nodeFs.statSync(fullPath);
-                snapshot.set(path.resolve(fullPath), {
-                    mtimeMs: stat.mtimeMs,
-                    size: stat.size,
-                });
-            }
-            catch {
-                // ignore vanished files
-            }
+        if (++counter.n % SNAPSHOT_YIELD_EVERY === 0) {
+            await new Promise((resolve) => setImmediate(resolve));
         }
     }
+}
+// Exported for the event-loop occupancy guard (#361/#368): an O(files) walk on
+// the tool_result autofix path, bounded by AUTOFIX_CHANGED_FILE_SCAN_LIMIT and
+// chunk-yielding every SNAPSHOT_YIELD_EVERY files so it never blocks the TUI.
+export async function snapshotProjectFiles(root) {
+    const snapshot = new Map();
+    const projectRoot = path.resolve(root);
+    const ignoreMatcher = getProjectIgnoreMatcher(projectRoot);
+    const stack = [projectRoot];
+    const counter = { n: 0 };
+    while (stack.length > 0 && snapshot.size < AUTOFIX_CHANGED_FILE_SCAN_LIMIT) {
+        await snapshotDirInto(stack.pop(), ignoreMatcher, stack, snapshot, counter);
+    }
     return snapshot;
 }
-function diffProjectSnapshot(root, before) {
-    const after = snapshotProjectFiles(root);
+async function diffProjectSnapshot(root, before) {
+    const after = await snapshotProjectFiles(root);
     const changed = new Set();
     for (const [filePath, next] of after) {
         const prev = before.get(filePath);
@@ -281,7 +302,7 @@ async function tryRustClippyFix(filePath) {
     ]);
     if (!cargoDir)
         return [];
-    const before = snapshotProjectFiles(cargoDir);
+    const before = await snapshotProjectFiles(cargoDir);
     const result = await safeSpawnAsync("cargo", ["clippy", "--fix", "--allow-dirty", "--allow-staged", "-q"], { timeout: 30000, cwd: cargoDir });
     if (result.error || result.status !== 0)
         return [];
@@ -294,7 +315,7 @@ async function tryDartFix(filePath) {
     const pubspecDir = findNearestContaining(path.dirname(path.resolve(filePath)), ["pubspec.yaml"]);
     if (!pubspecDir)
         return [];
-    const before = snapshotProjectFiles(pubspecDir);
+    const before = await snapshotProjectFiles(pubspecDir);
     const result = await safeSpawnAsync("dart", ["fix", "--apply"], {
         timeout: 30000,
         cwd: pubspecDir,

package/dist/clients/read-expansion.js

@@ -7,6 +7,7 @@
  * within the symbol pass without requiring the agent to have read every line.
  */
 import * as fs from "node:fs";
+import { withBudget } from "./deadline-utils.js";
 /** Only expand reads smaller than this (lines). Larger reads don't benefit. */
 export const EXPANSION_LIMIT_LINES = 100;
 /** Don't expand to a symbol larger than this. */
@@ -161,20 +162,6 @@ function buildAncestryChain(node, types) {
     }
     return chain.reverse(); // outermost first
 }
-function withBudget(promise, budgetMs) {
-    if (budgetMs <= 0)
-        return Promise.resolve(undefined);
-    let t;
-    return Promise.race([
-        promise,
-        new Promise((resolve) => {
-            t = setTimeout(() => resolve(undefined), budgetMs);
-        }),
-    ]).finally(() => {
-        if (t)
-            clearTimeout(t);
-    });
-}
 function tryExpandMarkdownSection(content, requestedStartRow, requestedLimit, totalLines) {
     const lines = content.split(/\r?\n/);
     const lastRow = totalLines - 1;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "3.8.62",
+	"version": "3.8.63",
 	"type": "module",
 	"description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
 	"repository": {

package/rules/ast-grep-rules/rule-tests/incomplete-string-escaping-js-test.yml

@@ -0,0 +1,21 @@
+id: incomplete-string-escaping-js
+valid:
+  - |
+    const escaped = s.replace(/\\/g, "\\\\");
+  - |
+    const escaped = s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+  - |
+    const html = s.replace(/&/g, "&");
+  - |
+    const literal = s.replace("|", "\\|");
+  - |
+    const printable = s.replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+  - |
+    const escaped = s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+invalid:
+  - |
+    const markdown = s.replace(/\|/g, "\\|");
+  - |
+    const quoted = s.replace(/"/g, '\\"');
+  - |
+    const templated = s.replace(/'/g, `\\'`);

package/rules/ast-grep-rules/rule-tests/incomplete-string-escaping-test.yml

@@ -0,0 +1,21 @@
+id: incomplete-string-escaping
+valid:
+  - |
+    const escaped = s.replace(/\\/g, "\\\\");
+  - |
+    const escaped = s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|");
+  - |
+    const html = s.replace(/&/g, "&");
+  - |
+    const literal = s.replace("|", "\\|");
+  - |
+    const printable = s.replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+  - |
+    const escaped = s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+invalid:
+  - |
+    const markdown = s.replace(/\|/g, "\\|");
+  - |
+    const quoted = s.replace(/"/g, '\\"');
+  - |
+    const templated = s.replace(/'/g, `\\'`);

package/rules/ast-grep-rules/rules/incomplete-string-escaping-js.yml

@@ -0,0 +1,19 @@
+id: incomplete-string-escaping-js
+language: JavaScript
+message: "Regex replace escapes with a backslash before escaping backslashes"
+severity: warning
+note: |
+  Escaping a delimiter with a backslash is incomplete if existing backslashes
+  are not escaped first. Escape `\\` before escaping the target character, e.g.
+  `s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|")`.
+rule:
+  pattern: $S.replace($RE, $REPL)
+constraints:
+  RE:
+    kind: regex
+  REPL:
+    regex: >-
+      ^["'`]\\\\[^\\A-Za-z0-9$]
+  S:
+    not:
+      kind: call_expression

package/rules/ast-grep-rules/rules/incomplete-string-escaping.yml

@@ -0,0 +1,19 @@
+id: incomplete-string-escaping
+language: TypeScript
+message: "Regex replace escapes with a backslash before escaping backslashes"
+severity: warning
+note: |
+  Escaping a delimiter with a backslash is incomplete if existing backslashes
+  are not escaped first. Escape `\\` before escaping the target character, e.g.
+  `s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|")`.
+rule:
+  pattern: $S.replace($RE, $REPL)
+constraints:
+  RE:
+    kind: regex
+  REPL:
+    regex: >-
+      ^["'`]\\\\[^\\A-Za-z0-9$]
+  S:
+    not:
+      kind: call_expression

package/skills/write-ast-grep-rule/SKILL.md

@@ -124,31 +124,33 @@ The parser is a real YAML parser, so unquoted special chars throw and the rule i
    (NAPI evaluates `regex` with JS RegExp on node.text() — keep it LINEAR so the
    detector can't itself ReDoS.)
 
-⚠ `-js` twins: ship ONE rule for a grammar-AGNOSTIC body, TWO for a grammar-DIVERGENT one.
-   The runner (`ast-grep-napi.ts`) runs EVERY ts/js rule on every jsts file — it only
-   language-gates NON-ts/js rules (`lang !== "typescript" && lang !== "javascript"`). So
-   whether a twin duplicates depends on whether its BODY matches the same nodes:
-   - **Grammar-agnostic body** (patterns / common kinds that parse identically in the
-     tree-sitter `typescript` and `javascript` grammars — `member_expression`,
-     `call_expression`, `lexical_declaration`, ternary, etc.): one `language: TypeScript`
-     rule already covers .js in the runner. A `-js` twin DUPLICATES (both fire on the same
-     node; dedup is by rule id, not finding). Shipped offenders: `prefer-at` + `prefer-at-js`,
-     `strict-equality` + `-js` — consolidate.
-   - **Grammar-divergent body** (node kinds that DIFFER between the two grammars): a single
-     rule MISSES the other grammar's form, so you NEED both twins — and they do NOT
-     duplicate, because each rule's kinds only exist in its own grammar. Example
-     (`no-flag-argument`, #305): a default parameter is `required_parameter` in the TS
-     grammar but `assignment_pattern` in the JS grammar; the TS rule gives 0 matches on
-     .js and the JS rule gives 0 on .ts. Other TS-only nodes: `optional_parameter`, type
-     annotations, `type_alias_declaration`, `enum_declaration`, `as`/satisfies expressions.
-   - **Decide:** does the rule name a node KIND that's specific to one grammar? Twin.
-     Pure pattern / shared kinds? Single rule.
-   - **Verify no dup before shipping a twin:** copy the twin, set its `language:` to the
-     base's, run `ast-grep scan` on a base-grammar file — `>0` matches = it duplicates
-     (drop the twin); `0` = grammar-divergent and safe (keep both).
-   - **CLI ≠ runner trap:** `ast-grep scan`/`test` GATE by the rule's `language:` (a TS rule
-     scans only .ts), so a TS rule shows 0 on a .js file in the CLI — but the RUNNER runs
-     it. Don't conclude "need a twin" from CLI gating; reason about the grammar instead.
+⚠ String-literal regexes match SOURCE text, not the runtime string value.
+   Inspect the exact node text before writing constraints:
+     ast-grep run --kind string --lang ts sample.ts --json=compact
+   Example: source `"\\|"` is node text `"\\\\|"` in JSON; to match a
+   source-level escaped backslash (`\\`) followed by a non-backslash, the rule
+   regex needs FOUR regex backslashes, preferably in a YAML block scalar:
+     regex: >-
+       ^["'`]\\\\[^\\A-Za-z0-9$]
+   This is how `incomplete-string-escaping` catches both `"\\|"` and
+   `'\\"'`. Avoid shell here-doc probes for this class — shell/JSON escaping
+   can silently eat a backslash and make the rule look broken.
+
+⚠ `-js` twins: remember there are TWO execution surfaces.
+   - ast-grep CLI/LSP language-gates by `language:`. A `language: TypeScript`
+     rule is not enough for standalone `.js` coverage, so shipped user-facing
+     TS/JS rules that should fire under the ast-grep LSP usually need a `-js`
+     twin with `language: JavaScript` plus its own fixture.
+   - the in-process NAPI fallback (`ast-grep-napi.ts`) parses the target file's
+     own grammar and currently runs both TS and JS rules on every jsts file. A
+     grammar-agnostic twin can therefore duplicate in fallback mode.
+   - **Decide explicitly:** if the rule must cover `.js` through the ast-grep
+     CLI/LSP baseline, ship the twin and test both. If a rule is NAPI-only or
+     fallback duplication is unacceptable, fix runner dedup/normalization before
+     relying on a single TypeScript rule for JS coverage.
+   - **Grammar-divergent bodies** still need separate variants regardless:
+     e.g. `no-flag-argument` uses `required_parameter` in TS and
+     `assignment_pattern` in JS.
 
 ✅ Node-kind facts (tree-sitter-typescript grammar — NOT the TS compiler / Roslyn):
    - let / const  → `lexical_declaration`     (var is NOT here)
@@ -216,13 +218,21 @@ The parser is a real YAML parser, so unquoted special chars throw and the rule i
 ## Validating a candidate rule against the REAL engine (not the warm MCP cache)
 
 ```
+
 # inspect how a PATTERN parses → find the node kind you actually need
+
 ast-grep run -p 'x = false' --lang ts --debug-query=cst file.ts
+
 # match by kind (──kind and ──pattern are mutually exclusive in `run`)
+
 ast-grep run --kind required_parameter --lang ts file.ts
+
 # run ONE rule from an sgconfig against a sample
+
 ast-grep scan -c <sgconfig.yml> --filter '^<id>$' sample.ts
+
 # run the fixture harness for one rule
+
 ast-grep test -c rules/ast-grep-rules/.sgconfig.yml --skip-snapshot-tests --filter '<id>'
-```
+
 ```