pi-lens 3.8.62 → 3.8.64

package/CHANGELOG.md

@@ -10,6 +10,43 @@ All notable changes to pi-lens will be documented in this file.
 
 ### Fixed
 
+## [3.8.64] - 2026-07-04
+
+### Added
+
+- **Opt-in `workspace/diagnostic` pull for the full scan — one request per server instead of N file opens (#387 Item 2)** — where a language server advertises `workspace/diagnostic` (e.g. TypeScript), `lens_diagnostics mode=full` can now issue a single project-wide pull per server instead of opening every file, detected via a new `workspaceDiagnostics` capability flag (distinct from per-document pull) and a `requestWorkspaceDiagnostics` client method. Gated behind `PI_LENS_LSP_WORKSPACE_PULL=1` (default off) and used per server-group only when the server advertises it and no file in the group has an auxiliary scanner; **any** miss (unsupported / dead / timeout / auxiliary present) falls back to the per-server-serial per-file path from #387 Item 1. Off by default because a **cold** server can answer a workspace pull with an empty/partial report that would read as a false "all clean", and the pull covers only the primary server — so it stays opt-in pending real-server validation before becoming the default. Completes the capability side of #387 (Item 1 shipped in #388).
+- **Progress bar for the long full-mode diagnostic scans (`lens_diagnostics mode=full`, `lsp_diagnostics` batch/directory)** — these scans can run for seconds to minutes and were previously opaque until they returned. They now stream a throttled progress bar (`Scanning… [████░░░░░░] 45/123 (37%)`) to the tool's `onUpdate` callback — at most ~4×/s plus a guaranteed final tick — so the agent/user sees movement. The data already existed (the sweep's per-file completion count); this just surfaces it. Shared `tools/scan-progress.ts` (`renderScanProgress` + `makeProgressReporter`); `runWorkspaceDiagnostics` and `mapWithConcurrency` gained an optional `onProgress(completed, total)`.
+
+- **Tree-sitter grammar provenance — sha256 sidecars + a committed manifest + a CI guard (#177)** — the grammar downloader now verifies every fetched `.wasm` against a committed provenance manifest (`scripts/grammars.lock.json`: package, version, per-grammar sha256) and writes a `<grammar>.wasm.json` sidecar recording what was installed. Two integrity gaps close: (1) fetched bytes are checked against the pinned hash — a grammar whose bytes don't match is never written (guards CDN corruption/tampering); (2) the old **skip-if-exists** behavior is replaced by **skip-if-verified** — on a version bump or hash mismatch the stale grammar is re-downloaded instead of silently persisting, so an ABI-mismatched `.wasm` can't survive against the deliberately pinned `web-tree-sitter`. A new `npm run check:grammars` (`scripts/check-grammar-provenance.mjs`, wired into CI like `check:lockfile`) re-hashes the installed grammars' bytes and fails on any drift from the manifest. Regenerate on a deliberate tree-sitter-wasms bump with `node scripts/download-grammars.js --write-manifest`.
+- **Package-manager detection — pi-lens no longer hardcodes npm/npx (#374)** — new `clients/package-manager.ts` is the single source of truth for *which* Node package manager to use (npm/pnpm/yarn/bun) and *how* to spell each command (run-script / install / global-install / exec / global-bin). Resolution: the project's lockfile or corepack `packageManager` field when that manager is installed, else the first installed by preference (npm → pnpm → yarn → bun), else npm. Routed through it: tool auto-install and global-bin discovery (`clients/installer`), LSP global binary lookup (`clients/lsp/launch.ts`), the interactive LSP-server global install (`clients/lsp/interactive-install.ts`), the MCP `pilens_rebuild` (`runRebuild` reports which manager it used), and project run-command hints. This makes pi-lens work on hosts that ship bun/pnpm/yarn instead of npm.
+
+### Changed
+
+- **Tree-sitter grammars: bundle a core set + fix cross-manager install** — grammars were fetched only by the `postinstall` script, which **npm** runs but **pnpm/bun block by default** (and **yarn** couldn't install at all — see below), so non-npm users depended entirely on a runtime CDN fetch and got *no* tree-sitter offline. Now the 12 core grammars (ts, tsx, js, python, go, rust, json, yaml, bash, html, css, java) are **downloaded at `prepare` time and shipped in the tarball** (`grammars/`, in `files[]`; ~+1 MB to the `.tgz` since wasm gzips well, +9 MB unpacked), so the common languages parse **offline on every package manager**. The long-tail grammars still lazy-fetch on first use, and a failed fetch now emits a **visible, actionable warning** instead of a silent debug line. Also removed the `tree-sitter-wasms: "npm:null@^0.11.0"` optional-dependency sentinel — npm/pnpm/bun skipped it as a failing optional but **yarn classic hard-errored** on it, so `yarn add pi-lens` failed outright; it's now installable under yarn.
+
+### Fixed
+
+- **The LSP notify write is now bounded at the source, so a wedged server can't ride an edit to the 30 s dispatcher timeout** — the pre-dispatch sync fix bounded one call site, but *every* `touchFile` caller (the dispatch LSP runner and the workspace sweep too) `await`ed `notify.open`'s `didChange`/`didOpen` write, which backpressures indefinitely on a server whose stdin isn't drained. So edits on a wedged server still took ~31 s — the dispatch LSP runner hung on that write until the coarse 30 s per-runner ceiling killed it (`Runner lsp timed out after 30000ms`). The write is now bounded inside `touchFile` itself (`PI_LENS_LSP_NOTIFY_BUDGET_MS`, default 2 s): on a wedged server it degrades to "no fresh diagnostics" (logged as `lsp_notify_timeout` / `notifyWriteTimedOut`) instead of hanging, for **all** callers.
+- **`lens_diagnostics`/`lsp_diagnostics` full sweep no longer floods a single-threaded server (#387)** — the sweep ran a flat 8-wide worker pool that was server-agnostic, so on a single-language repo all 8 concurrent touches hit one `tsserver`. It's single-threaded per project: they don't parallelize, they queue — inflating the working set (each `didOpen` can force a project recheck) and **cascading per-file-budget timeouts by queue position** (observed: 51 of 123 files "timed out" purely from being behind others, the count climbing 0→51 as the queue deepened). The sweep now **groups files by their primary server, serializes touches within a server (one in flight), and parallelizes across distinct servers** — real parallelism in a mixed TS+Python repo, no flooding in a single-language one. This uses the universal per-file `didOpen` path, so it works for every server regardless of `workspace/diagnostic` support (a single-request workspace pull for servers that advertise it remains the #387 follow-up).
+- **An edit could hang indefinitely (and ignore Escape) on a wedged language server — the pre-dispatch LSP sync was unbounded** — after an edit, pi-lens syncs the new content to the language server (a `didChange`/`didOpen`) before dispatching lint. Client *acquisition* was capped, but the notify *write* was not: when the server's stdin isn't being drained (a CPU-bound/wedged server — e.g. TypeScript mid-recheck), that write backpressures forever, hanging the whole edit with **no per-call bound and no log at all** (the first instrumented phase, `read_file`, sits *after* the sync, so the stall left zero trace). Observed live: an edit wedged 8+ minutes with the server timing out on every request. Now the sync is raced against a hard budget (`PI_LENS_LSP_SYNC_BUDGET_MS`, default 3 s) **and** the turn's abort signal, so Escape cancels it and a slow server can't park the pipeline — the edit proceeds (the dispatch LSP runner, with its own 30 s cap, still tries). Escape now reaches this path because the turn signal is exposed for in-process LSP awaits (`getAmbientAbortSignal`), not just child-process spawns. Two observability gaps closed too: an abandoned sync logs an `lsp_sync_abandoned` phase (timeout vs aborted), and a new `tool_result_received` marker fires the instant pi-lens receives an edit — so a future stall is localizable (present-then-silent = in-pipeline; absent = upstream) instead of invisible.
+- **Log retention was silently broken — rotated backups never got deleted, and three logs never rotated** — the 10 MB rotation worked, but the 7-day retention sweep that's supposed to reap the backups used a pattern (`/\.log\./`) that only matched the *legacy* `name.log.<ts>` shape, never the *current* `name.<ts>.log` that rotation actually produces — so every backup ever rotated accumulated forever (observed: ~200 MB of `~/.pi-lens` backups dating back 2.5 months against a 7-day policy). Separately, three of the eight global logs — `actionable-warnings.log`, `ast-grep-tools.log`, `dead-code.log` — were absent from the rotation list and grew unbounded. Both are fixed: the deletion pattern now matches both backup shapes (and never an active log), and all eight logs are managed from one shared `MANAGED_LOG_FILES` list so rotation and the storage summary can't drift apart again. Because `runLogCleanup` already runs unconditionally on every session start, the corrected sweep **self-heals existing backlogs** — the next launch after upgrade reaps each user's accumulated `>7 day` backups with no migration step.
+- **`lens_diagnostics mode=full` could hang indefinitely and didn't cancel on Escape** — an unattended session was observed wedged for ~8 hours on a small repo. Two root causes, both fixed: **(1) Escape didn't cancel** — the tool honored only the tool-call `signal` positional, not `ctx.signal` (the turn-wired abort Escape fires for a registered extension tool), so the sweep ran on. It now combines both (`combineAbortSignals`, shared in `deadline-utils`) and threads the result through the LSP sweep and project-runner scan. **(2) It could hang forever** — per-file diagnostic waits were bounded, but *client acquisition* in the sweep was not, so a language server hanging on spawn/`initialize` parked a worker permanently. Now (a) each file gets a per-file wall-clock budget (`PI_LENS_LSP_WORKSPACE_PER_FILE_MS`, default 15 s) so a worker always returns to its abort check, and (b) the whole scan has a hard wall-clock ceiling (`PI_LENS_LENS_DIAGNOSTICS_FULL_TIMEOUT_MS`, default 3 min) that aborts it to partial results rather than never returning. The sweep also now emits **start + periodic heartbeat** latency logs (with `completed/total`, `timedOutFiles`) so a future stall is debuggable instead of silent, and the `scripts/analyze-pi-lens-logs.mjs` smell report now consumes them — surfacing sweeps that started but never completed (the hang/kill signature, with the last heartbeat's `completed X/Y`), sweeps whose files hit the per-file budget, and any `*_timeout` phases. The same pass repairs the analyzer's `slow-background-tasks` detector, whose regex had drifted from the runtime's `session_start task … success runMs=<n>` format and was silently matching **zero** of ~2k rows — it now flags the real multi-second startup tasks (`call-graph`, `knip`, `project-index`) again, and accepts both the current `runMs=` and the older `(<n>ms)` shapes. The same `ctx.signal` cancellation gap is fixed in the sibling tools `lsp_diagnostics` (batch/directory scans) and `ast_grep_search` (which was already abort-aware but checked the wrong signal).
+
+## [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/README.md

@@ -71,7 +71,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/anh-chu"><img src="https://avatars.githubusercontent.com/u/34973633?v=4" width="100px;" alt=""/><br /><sub><b>Anh Chu</b></sub></a><br /><a href="#code-anh-chu" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Istar-Eldritch"><img src="https://avatars.githubusercontent.com/u/3746468?v=4" width="100px;" alt=""/><br /><sub><b>Ruben Paz</b></sub></a><br /><a href="#code-Istar-Eldritch" title="Code">💻</a> <a href="#bug-Istar-Eldritch" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tifandotme"><img src="https://avatars.githubusercontent.com/u/33323177?v=4" width="100px;" alt=""/><br /><sub><b>Tifan Dwi Avianto</b></sub></a><br /><a href="#code-tifandotme" title="Code">💻</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ricardoraposo"><img src="https://avatars.githubusercontent.com/u/50217712?v=4" width="100px;" alt=""/><br /><sub><b>Ricardo Raposo</b></sub></a><br /><a href="#code-ricardoraposo" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/cjunxiang"><img src="https://avatars.githubusercontent.com/u/26619858?v=4" width="100px;" alt=""/><br /><sub><b>C.Junxiang</b></sub></a><br /><a href="#code-cjunxiang" title="Code">💻</a> <a href="#bug-cjunxiang" title="Bug reports">🐛</a></td>
@@ -80,7 +80,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/fractiunate"><img src="https://avatars.githubusercontent.com/u/78024279?v=4" width="100px;" alt=""/><br /><sub><b>Fractiunate // David Rahäuser</b></sub></a><br /><a href="#code-fractiunate" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/bloodf"><img src="https://avatars.githubusercontent.com/u/1626923?v=4" width="100px;" alt=""/><br /><sub><b>Heitor Ramon Ribeiro</b></sub></a><br /><a href="#code-bloodf" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/JayceFreeman"><img src="https://avatars.githubusercontent.com/u/92962110?v=4" width="100px;" alt=""/><br /><sub><b>JayceFreeman</b></sub></a><br /><a href="#code-JayceFreeman" title="Code">💻</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/shaDmx"><img src="https://avatars.githubusercontent.com/u/91132641?v=4" width="100px;" alt=""/><br /><sub><b>Max L.</b></sub></a><br /><a href="#code-shaDmx" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Roman-Galeev"><img src="https://avatars.githubusercontent.com/u/40388226?v=4" width="100px;" alt=""/><br /><sub><b>Roman Galeev</b></sub></a><br /><a href="#code-Roman-Galeev" title="Code">💻</a></td>
@@ -89,7 +89,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/flowing-abyss"><img src="https://avatars.githubusercontent.com/u/98622217?v=4" width="100px;" alt=""/><br /><sub><b>flowing-abyss</b></sub></a><br /><a href="#code-flowing-abyss" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jerryfan"><img src="https://avatars.githubusercontent.com/u/2540814?v=4" width="100px;" alt=""/><br /><sub><b>jerryfan</b></sub></a><br /><a href="#code-jerryfan" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/loss-and-quick"><img src="https://avatars.githubusercontent.com/u/39405619?v=4" width="100px;" alt=""/><br /><sub><b>minicx</b></sub></a><br /><a href="#code-loss-and-quick" title="Code">💻</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/spyrosbazios"><img src="https://avatars.githubusercontent.com/u/37960233?v=4" width="100px;" alt=""/><br /><sub><b>spyrosbazios</b></sub></a><br /><a href="#code-spyrosbazios" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/trvon"><img src="https://avatars.githubusercontent.com/u/6031322?v=4" width="100px;" alt=""/><br /><sub><b>Trevon</b></sub></a><br /><a href="#code-trvon" title="Code">💻</a></td>
@@ -98,7 +98,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/mdbooth"><img src="https://avatars.githubusercontent.com/u/1318691?v=4" width="100px;" alt=""/><br /><sub><b>Matthew Booth</b></sub></a><br /><a href="#bug-mdbooth" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Wiedzmin89"><img src="https://avatars.githubusercontent.com/u/61706855?v=4" width="100px;" alt=""/><br /><sub><b>Wiedzmin89</b></sub></a><br /><a href="#ideas-Wiedzmin89" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/grodingo"><img src="https://avatars.githubusercontent.com/u/244184972?v=4" width="100px;" alt=""/><br /><sub><b>Virgile</b></sub></a><br /><a href="#bug-grodingo" title="Bug reports">🐛</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/finnvyrn"><img src="https://avatars.githubusercontent.com/u/90801772?v=4" width="100px;" alt=""/><br /><sub><b>Finn</b></sub></a><br /><a href="#ideas-finnvyrn" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ywh555hhh"><img src="https://avatars.githubusercontent.com/u/121592812?v=4" width="100px;" alt=""/><br /><sub><b>Wayne E</b></sub></a><br /><a href="#bug-ywh555hhh" title="Bug reports">🐛</a></td>
@@ -107,7 +107,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/pvtri96"><img src="https://avatars.githubusercontent.com/u/28696888?v=4" width="100px;" alt=""/><br /><sub><b>Tri Van Pham</b></sub></a><br /><a href="#bug-pvtri96" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/BingWuJ"><img src="https://avatars.githubusercontent.com/u/117666511?v=4" width="100px;" alt=""/><br /><sub><b>BingWuJ</b></sub></a><br /><a href="#bug-BingWuJ" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tackleberrybey"><img src="https://avatars.githubusercontent.com/u/156954032?v=4" width="100px;" alt=""/><br /><sub><b>tackleberrybey</b></sub></a><br /><a href="#bug-tackleberrybey" title="Bug reports">🐛</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/TaterDoge"><img src="https://avatars.githubusercontent.com/u/121467933?v=4" width="100px;" alt=""/><br /><sub><b>Mariann Abshire</b></sub></a><br /><a href="#bug-TaterDoge" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ProbabilityEngineer"><img src="https://avatars.githubusercontent.com/u/38498804?v=4" width="100px;" alt=""/><br /><sub><b>ProbabilityEngineer</b></sub></a><br /><a href="#ideas-ProbabilityEngineer" title="Ideas & Planning">🤔</a></td>
@@ -116,7 +116,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/rstacruz"><img src="https://avatars.githubusercontent.com/u/74385?v=4" width="100px;" alt=""/><br /><sub><b>Rico Sta. Cruz</b></sub></a><br /><a href="#ideas-rstacruz" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/acidnik"><img src="https://avatars.githubusercontent.com/u/1227955?v=4" width="100px;" alt=""/><br /><sub><b>Nikita Bilous</b></sub></a><br /><a href="#bug-acidnik" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/av1155"><img src="https://avatars.githubusercontent.com/u/117413846?v=4" width="100px;" alt=""/><br /><sub><b>Andrea Arturo Venti Fuentes</b></sub></a><br /><a href="#bug-av1155" title="Bug reports">🐛</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/dacec354"><img src="https://avatars.githubusercontent.com/u/90093629?v=4" width="100px;" alt=""/><br /><sub><b>dacec354</b></sub></a><br /><a href="#bug-dacec354" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/xuli500177"><img src="https://avatars.githubusercontent.com/u/62830942?v=4" width="100px;" alt=""/><br /><sub><b>Xu Yili</b></sub></a><br /><a href="#bug-xuli500177" title="Bug reports">🐛</a></td>
@@ -125,7 +125,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/asolopovas"><img src="https://avatars.githubusercontent.com/u/6893216?v=4" width="100px;" alt=""/><br /><sub><b>Andrius Solopovas</b></sub></a><br /><a href="#bug-asolopovas" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/GrahamJenkins"><img src="https://avatars.githubusercontent.com/u/6607975?v=4" width="100px;" alt=""/><br /><sub><b>Graham Jenkins</b></sub></a><br /><a href="#bug-GrahamJenkins" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/wings1848"><img src="https://avatars.githubusercontent.com/u/120104016?v=4" width="100px;" alt=""/><br /><sub><b>Wings Butterfly</b></sub></a><br /><a href="#bug-wings1848" title="Bug reports">🐛</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/JohannesKlauss"><img src="https://avatars.githubusercontent.com/u/6214415?v=4" width="100px;" alt=""/><br /><sub><b>Johannes Klauss</b></sub></a><br /><a href="#ideas-JohannesKlauss" title="Ideas & Planning">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tan-yong-sheng"><img src="https://avatars.githubusercontent.com/u/64836390?v=4" width="100px;" alt=""/><br /><sub><b>Tan Yong Sheng</b></sub></a><br /><a href="#ideas-tan-yong-sheng" title="Ideas & Planning">🤔</a></td>
@@ -134,7 +134,7 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Viterkim"><img src="https://avatars.githubusercontent.com/u/17838985?v=4" width="100px;" alt=""/><br /><sub><b>Viktor</b></sub></a><br /><a href="#bug-Viterkim" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/ortonomy"><img src="https://avatars.githubusercontent.com/u/6688676?v=4" width="100px;" alt=""/><br /><sub><b>Gregory Orton</b></sub></a><br /><a href="#bug-ortonomy" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jimallen"><img src="https://avatars.githubusercontent.com/u/868773?v=4" width="100px;" alt=""/><br /><sub><b>Jim Allen</b></sub></a><br /><a href="#bug-jimallen" title="Bug reports">🐛</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/quantfiction"><img src="https://avatars.githubusercontent.com/u/49965454?v=4" width="100px;" alt=""/><br /><sub><b>quantfiction</b></sub></a><br /><a href="#bug-quantfiction" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Artawower"><img src="https://avatars.githubusercontent.com/u/16963833?v=4" width="100px;" alt=""/><br /><sub><b>Art</b></sub></a><br /><a href="#bug-Artawower" title="Bug reports">🐛</a></td>
@@ -143,10 +143,13 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/stark-bit"><img src="https://avatars.githubusercontent.com/u/44064758?v=4" width="100px;" alt=""/><br /><sub><b>Rei Starks</b></sub></a><br /><a href="#bug-stark-bit" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/robertoecf"><img src="https://avatars.githubusercontent.com/u/54923863?v=4" width="100px;" alt=""/><br /><sub><b>Roberto Freitas</b></sub></a><br /><a href="#bug-robertoecf" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tmttodd"><img src="https://avatars.githubusercontent.com/u/160077416?v=4" width="100px;" alt=""/><br /><sub><b>tmttodd</b></sub></a><br /><a href="#bug-tmttodd" title="Bug reports">🐛</a></td>
-    </tr>
+    </tr><br />
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/smaharnav"><img src="https://avatars.githubusercontent.com/u/263328627?v=4" width="100px;" alt=""/><br /><sub><b>smaharnav</b></sub></a><br /><a href="#bug-smaharnav" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/MzaGuille"><img src="https://avatars.githubusercontent.com/u/151482698?v=4" width="100px;" alt=""/><br /><sub><b>Mza.Guille</b></sub></a><br /><a href="#bug-MzaGuille" title="Bug reports">🐛</a></td>
+      <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>
     </tr>
 </tbody>
 </table>

package/dist/clients/deadline-utils.js

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+/**
+ * Combine multiple abort signals into one that aborts when ANY of them does.
+ * Returns the single signal unchanged when only one is live, and `undefined`
+ * when none are — so callers can pass it straight through. Used so a tool honors
+ * both its tool-call `signal` positional and the turn-wired `ctx.signal` (Escape),
+ * and to fold in a wall-clock ceiling via `AbortSignal.timeout`.
+ */
+export function combineAbortSignals(...signals) {
+    const live = signals.filter((s) => s !== undefined);
+    if (live.length <= 1)
+        return live[0];
+    if (typeof AbortSignal.any === "function")
+        return AbortSignal.any(live);
+    const controller = new AbortController();
+    for (const s of live) {
+        if (s.aborted) {
+            controller.abort(s.reason);
+            break;
+        }
+        s.addEventListener("abort", () => controller.abort(s.reason), { once: true });
+    }
+    return controller.signal;
+}
+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

@@ -56,6 +56,7 @@ const _installerRequire = createRequire(import.meta.url);
 import { createGunzip } from "node:zlib";
 import { isTestMode } from "../env-utils.js";
 import { getGlobalPiLensDir } from "../file-utils.js";
+import { allAvailableGlobalBinDirs, installArgs, pmBinary, resolveNodePackageManager, } from "../package-manager.js";
 // Global installation directory for pi-lens tools
 const TOOLS_DIR = path.join(getGlobalPiLensDir(), "tools");
 // Directory for GitHub-downloaded binaries
@@ -1150,6 +1151,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;
@@ -1637,19 +1640,10 @@ async function getNpmGlobalBinCandidates() {
     else {
         add(path.join(os.homedir(), ".npm-global", "bin"));
     }
-    const pm = process.platform === "win32" ? "npm.cmd" : "npm";
-    const prefix = await new Promise((resolve) => {
-        const proc = spawn(pm, ["config", "get", "prefix"], {
-            stdio: ["ignore", "pipe", "pipe"],
-            shell: process.platform === "win32",
-        });
-        let stdout = "";
-        proc.stdout?.on("data", (data) => (stdout += data));
-        proc.on("exit", (code) => resolve(code === 0 ? stdout.trim() : ""));
-        proc.on("error", () => resolve(""));
-    });
-    if (prefix) {
-        add(process.platform === "win32" ? prefix : path.join(prefix, "bin"));
+    // Global bin dirs for every installed manager (npm/pnpm/yarn/bun) — a tool
+    // may have been installed globally via any of them.
+    for (const dir of await allAvailableGlobalBinDirs()) {
+        add(dir);
     }
     return dirs;
 }
@@ -2225,21 +2219,19 @@ async function installNpmTool(packageName, binaryName) {
         catch {
             await fs.writeFile(packageJsonPath, JSON.stringify({ name: "pi-lens-tools", version: "1.0.0" }, null, 2));
         }
-        // Install via npm or bun (use .cmd on Windows)
+        // Resolve the package manager for the tools dir and build install args.
         const isWindows = process.platform === "win32";
-        let pm = isWindows ? "npm.cmd" : "npm";
-        if (process.env.BUN_INSTALL) {
-            pm = isWindows ? "bun.exe" : "bun";
-        }
+        const pm = await resolveNodePackageManager(TOOLS_DIR);
+        const pmCommand = pmBinary(pm);
         // Use --ignore-scripts unless the package explicitly needs postinstall
         // (e.g. biome downloads a platform-specific native binary via postinstall).
         const needsScripts = NEEDS_POSTINSTALL.has(packageName);
-        const baseInstallArgs = needsScripts
-            ? ["install", packageName]
-            : ["install", "--ignore-scripts", packageName];
+        const baseInstallArgs = installArgs(pm, packageName, {
+            ignoreScripts: !needsScripts,
+        });
         const INSTALL_TIMEOUT_MS = 120_000;
         const runInstallAttempt = async (args) => new Promise((resolve) => {
-            const proc = spawn(pm, args, {
+            const proc = spawn(pmCommand, args, {
                 cwd: TOOLS_DIR,
                 stdio: ["ignore", "pipe", "pipe"],
                 shell: isWindows, // Required for .cmd files on Windows
@@ -2263,13 +2255,14 @@ async function installNpmTool(packageName, binaryName) {
             });
         });
         let outcome = await runInstallAttempt(baseInstallArgs);
-        const isNpm = pm === "npm" || pm === "npm.cmd";
+        // --legacy-peer-deps is npm-only; retry just npm's ERESOLVE failures.
         const erResolve = outcome.ok === false &&
             /npm\s+error\s+ERESOLVE|\bERESOLVE\b|could not resolve/i.test(outcome.stderr);
-        if (isNpm && erResolve) {
-            const retryArgs = needsScripts
-                ? ["install", "--legacy-peer-deps", packageName]
-                : ["install", "--ignore-scripts", "--legacy-peer-deps", packageName];
+        if (pm === "npm" && erResolve) {
+            const retryArgs = installArgs(pm, packageName, {
+                ignoreScripts: !needsScripts,
+                legacyPeerDeps: true,
+            });
             logSessionStart(`auto-install npm ${packageName}: retry with --legacy-peer-deps after ERESOLVE`);
             outcome = await runInstallAttempt(retryArgs);
         }
@@ -2559,8 +2552,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 +2578,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 +2589,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 +2608,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 +2628,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 +2652,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/log-cleanup.js

@@ -6,9 +6,11 @@
  *   PI_LENS_MAX_LOG_SIZE_MB    - Max size before rotation (default: 10)
  *
  * Scope:
- *   - ~/.pi-lens/*.log (latency.log, sessionstart.log, tree-sitter.log)
+ *   - ~/.pi-lens/*.log (all 8 global logs — see MANAGED_LOG_FILES: latency,
+ *     sessionstart, tree-sitter, cascade, read-guard, actionable-warnings,
+ *     ast-grep-tools, dead-code)
  *   - ~/.pi-lens/logs/*.jsonl (daily diagnostic logs)
- *   - ~/.pi-lens/*.log.* (rotated backups)
+ *   - ~/.pi-lens/<name>.<timestamp>.log (rotated backups, and legacy .log.<ts>)
  *
  * Excluded (intentionally NOT cleaned - project-scoped or persistent):
  *   - <project-data>/worklog.jsonl                - Agent fixable diagnostics
@@ -25,6 +27,30 @@ import * as path from "node:path";
 import { getGlobalPiLensDir } from "./file-utils.js";
 const LOG_DIR = getGlobalPiLensDir();
 const LOGS_SUBDIR = path.join(LOG_DIR, "logs");
+/**
+ * Every global `.log` pi-lens writes under ~/.pi-lens. Kept as one list so
+ * rotation and the storage summary can't drift out of sync — that drift is
+ * exactly what left actionable-warnings/ast-grep-tools/dead-code unrotated and
+ * growing unbounded. New global log file? Add it here.
+ */
+export const MANAGED_LOG_FILES = [
+    "latency.log",
+    "sessionstart.log",
+    "tree-sitter.log",
+    "cascade.log",
+    "read-guard.log",
+    "actionable-warnings.log",
+    "ast-grep-tools.log",
+    "dead-code.log",
+];
+/**
+ * Matches a rotated backup, never an active log. Rotation writes
+ * `name.<ISO-timestamp>.log` (timestamp before the extension); an older shape
+ * was `name.log.<timestamp>`. Match both so every backup — whichever version
+ * produced it — is reaped by the retention sweep. The active `name.log` has no
+ * timestamp segment and no trailing suffix after `.log`, so it never matches.
+ */
+export const ROTATED_BACKUP_RE = /(\.\d{4}-\d{2}-\d{2}T.*\.log|\.log\..+)$/;
 function getConfig() {
     return {
         retentionDays: Math.max(1, Number.parseInt(process.env.PI_LENS_LOG_RETENTION_DAYS ?? "7", 10) || 7),
@@ -123,17 +149,15 @@ export function runLogCleanup(dbg) {
     // Cleanup old daily diagnostic logs (*.jsonl)
     const dailyLogs = cleanupOldLogs(LOGS_SUBDIR, /\.jsonl$/, config.retentionDays);
     results.cleaned += dailyLogs.deleted.length;
-    // Cleanup old rotated log backups (*.log.*)
-    const rotatedLogs = cleanupOldLogs(LOG_DIR, /\.log\./, config.retentionDays);
+    // Cleanup old rotated log backups. This sweep runs unconditionally on every
+    // session start, so correcting the pattern self-heals any pre-existing
+    // backlog on the next launch — no separate migration needed. (The prior
+    // `/\.log\./` only matched the legacy `name.log.<ts>` shape, never the
+    // current `name.<ts>.log`, so backups accumulated indefinitely.)
+    const rotatedLogs = cleanupOldLogs(LOG_DIR, ROTATED_BACKUP_RE, config.retentionDays);
     results.cleaned += rotatedLogs.deleted.length;
     // Check main logs for rotation
-    const mainLogs = [
-        path.join(LOG_DIR, "latency.log"),
-        path.join(LOG_DIR, "sessionstart.log"),
-        path.join(LOG_DIR, "tree-sitter.log"),
-        path.join(LOG_DIR, "cascade.log"),
-        path.join(LOG_DIR, "read-guard.log"),
-    ];
+    const mainLogs = MANAGED_LOG_FILES.map((name) => path.join(LOG_DIR, name));
     for (const logFile of mainLogs) {
         const rotation = rotateLogIfNeeded(logFile, config.maxSizeMB);
         if (rotation.rotated) {
@@ -171,8 +195,7 @@ export function getLogStorageSummary() {
     const files = [];
     let totalMB = 0;
     // Main logs
-    const mainLogs = ["latency.log", "sessionstart.log", "tree-sitter.log"];
-    for (const name of mainLogs) {
+    for (const name of MANAGED_LOG_FILES) {
         const filePath = path.join(LOG_DIR, name);
         if (fs.existsSync(filePath)) {
             const sizeMB = getFileSizeMB(filePath);