pi-lens 3.8.26 → 3.8.28

package/CHANGELOG.md

@@ -2,7 +2,119 @@
 
 All notable changes to pi-lens will be documented in this file.
 
-## [Unreleased]
+## [3.8.28] - 2026-04-19
+
+### Fixed
+- **Session startup no longer blocks the Node event loop** — tool availability probes (biome, ast-grep, ruff, knip, jscpd, madge) now run via async `ensureAvailable()` in a fire-and-forget IIFE instead of `setImmediate` + `spawnSync`, eliminating ~8–10 s of main-thread freeze on startup.
+- **Biome binary lookup extended** — `getBiomeBinary()` now checks `~/.pi-lens/tools/node_modules/.bin/biome` so the async probe finds the pre-installed binary without falling back to `npx`.
+- **CSS roots and Windows LSP shims tightened** — improved root resolution for CSS language server on Windows.
+- **Zig compile coverage kept active** — LSP availability check no longer incorrectly disables Zig compile diagnostics.
+- **Ruby LSP startup budgets relaxed** — reduced false-negative LSP attach failures on slower machines.
+- **Kotlin and Zig LSP availability improved** — more reliable server detection across platforms.
+- **Standalone Python and Ruby LSP roots fixed** — correct workspace root used when opening files outside a project directory.
+
+## [3.8.27] - 2026-04-19
+
+### Added
+- **Review graph impact cascade** — turn-end cascade now renders a review-graph impact view showing which files were affected and how diagnostics propagated.
+- **Fact-rule pipeline in dispatch** — new `fact-rules` dispatch runner computes function-level facts (depth, cyclomatic complexity, call counts) and evaluates quality rules inline, replacing the bespoke tree-sitter booboo runner.
+- **Function facts: depth / CC / calls** — tree-sitter extracts per-function cyclomatic complexity, nesting depth, and outgoing call count for fact-rule evaluation.
+- **File role classification** — dispatch classifies files as `source`, `test`, `config`, or `vendor` and adjusts rule severity accordingly.
+- **Inline suppression directives** — sources can suppress diagnostics with `// pi-lens-ignore` or `# pi-lens-ignore` comments; suppressed items are omitted from inline output.
+- **High-complexity fact rule** — flags functions exceeding configurable cyclomatic complexity thresholds.
+- **Unsafe-boundary fact rule** — detects dangerous boundary crossings (unvalidated user input → trusted context).
+- **High-fan-out fact rule** — flags functions with excessive outgoing call count (default threshold 20).
+- **`async-unnecessary-wrapper` ast-grep rule** — detects trivial async wrappers that just await and return.
+- **`missing-error-propagation` ast-grep rule** — detects catch blocks that swallow errors without re-throwing or logging.
+- **36 new ast-grep rules** — expanded coverage for security, correctness, and style across TypeScript, JavaScript, and Python.
+- **5 quality fact rules** — structured quality checks driven by function-level metrics.
+- **8 SonarJS-aligned rules** — try-catch enrichment and 8 rules ported from SonarJS patterns.
+- **Slop-detection rules** — identifies low-signal / boilerplate-heavy code regions with observability log entries.
+- **Dart-analyze dispatch runner** — runs `dart analyze` on `.dart` files.
+- **Ktlint dispatch runner** — runs `ktlint` on `.kt` / `.kts` files.
+- **TFLint dispatch runner** — runs `tflint` on `.tf` / `.tfvars` files.
+- **Taplo dispatch runner + formatter** — runs `taplo` for TOML lint and format.
+- **Credo dispatch runner** — runs `mix credo` on Elixir files (falls back to LSP).
+- **Phpstan dispatch runner** — runs `phpstan` on PHP files (falls back to LSP).
+- **Prettier-check dispatch runner** — runs `prettier --check` as a lint runner (not auto-fix, purely diagnostic).
+- **PSScriptAnalyzer runner** — PowerShell linting via `Invoke-ScriptAnalyzer`, using temp `-File` instead of `-Command` to avoid cmd.exe mangling.
+- **Hadolint dispatch runner** — Dockerfile lint with always-run dispatch gating.
+- **Htmlhint dispatch runner** — HTML lint with tag-pair detection.
+- **Docker / PHP / PowerShell / Prisma FileKind** — new language kind mappings enable LSP and dispatch for Dockerfile, `.php`, `.ps1`/`.psm1`, and `.prisma` files.
+- **GitHub release downloader for installer** — `shellcheck`, `shfmt`, `rust-analyzer`, and `golangci-lint` are now auto-installed from GitHub releases with asset selection across platforms.
+- **Auto-install gopls and ruby-lsp** — `gopls` installed via `go install`; `ruby-lsp` installed via `gem install` when not found.
+- **Biome as default JS/TS linter** — when no ESLint or oxlint config exists, Biome runs as the default linter for write-path dispatch instead of silently skipping.
+- **Bundled ruff config fallback** — Python projects without a `ruff.toml` / `pyproject.toml` ruff section now use a bundled safe-default config so ruff still produces useful findings.
+- **Ruff autofix after diagnostics** — the ruff dispatch runner now applies safe autofixes after capturing diagnostics, mirroring Biome's write-path behavior.
+- **Diagnostic history logging** — tree-sitter warnings and debounced ast-grep findings are now logged to session history for observability and `/lens-booboo` review.
+- **Tree-sitter grammar downloads expanded** — additional grammars downloaded at install time for broader language coverage.
+- **Java and C# fallback analysis** — dispatch includes fallback analysis paths for Java (`.java`) and C# (`.cs`) when LSP is unavailable.
+- **CI: tsc type-check + vitest + install gate** — CI now runs `tsc --noEmit` and `vitest` as separate jobs; install-test is gated on both passing.
+- **CI: tsx extension load check** — CI verifies that required extensions load correctly to catch missing dependency errors early.
+
+### Changed
+- **Promote LSP-backed languages into dispatch** — languages with active LSP servers now route through dispatch's standard pipeline instead of ad-hoc paths.
+- **Dispatch language fallbacks aligned** — LSP-backed and fallback runner selection now uses consistent language-to-capability mapping.
+- **CSS / HTML / TOML / Elixir fallback wiring** — dispatch fallbacks now include CSS (stylelint), HTML (htmlhint), TOML (taplo), and Elixir (credo).
+- **Prettier-check and stylelint cwd handling** — both runners now resolve project root correctly instead of skipping when the working directory overshoots.
+- **OS portability: vendor/bin and sg resolution** — `vendor/bin` tools resolve with multi-extension support (`.bat`/`.cmd`/no-ext); `sg` candidate list works across platforms.
+- **LSP: live Windows registry PATH** — LSP spawn reads the live `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\Path` at launch time so newly installed tools are immediately discoverable.
+- **LSP: unified resolveAndLaunch** — four separate resolution mechanisms (local binary, global, npx, package manager) collapsed into a single `resolveAndLaunch` flow with clear fallback ordering.
+- **LSP: telemetry and logging tightened** — init failures logged to `sessionstart.log`; terminal noise reduced; basename matching improved.
+- **YAML LSP root fallback** — YAML language server uses `RootWithFallback` for seamless multi-root project support.
+- **Dart / Terraform / TOML LSP: RootWithFallback** — same root-fallback pattern applied across these servers for reliable workspace detection.
+- **Terraform-ls HashiCorp install fallback** — improved install path resolution for terraform-ls.
+- **`empty-catch` and `unchecked-sync-fs` downgraded to warning** — too many false positives as errors; now `warning` severity.
+- **High-fan-out threshold raised to 20** — reduced noise from earlier threshold of 10.
+- **High-complexity and unsafe-boundary thresholds tightened** — reduced false positives at the default severity boundaries.
+- **False-positive reduction: 8 rules + 3 error rules** — tuned OAuth/constants-related patterns, removed 3 error-level rules that flagged too broadly, and fixed `ts-ssrf` identifier argument matching.
+- **Removed unused/noisy ast-grep rules** — culled rules that overlapped with tree-sitter coverage or produced excessive noise.
+- **Moved duplicate TS tree-sitter rules** — overlapping rules relocated to `typescript-disabled/` to avoid double-reporting.
+- **LSP crash diagnostics** — startup stderr captured and logged for faster root-cause analysis.
+- **Tool PATH normalization** — cross-platform PATH resolution unified for LSP and dispatch tool spawning.
+- **Cleaned up runtime dependencies** — moved `@ast-grep/napi` and `js-yaml` to `dependencies` (were `devDependencies`); removed unused deps.
+- **Complexity reduction** — decomposed four highest-complexity functions (CC 75–153 → <20 each) for maintainability.
+
+### Fixed
+- **Windows LSP startup fallback** — hardened spawn logic for `.cmd` wrappers, PATH resolution, and process creation on Windows.
+- **C# launch and secondary language fallbacks** — C# LSP and secondary language servers start reliably in more project layouts.
+- **Prettier-check / stylelint cwd overshoot** — both runners now find the project root correctly instead of silently skipping.
+- **Hadolint asset name case** — GitHub release downloader resolves case-sensitive asset names.
+- **Htmlhint / hadolint always-run dispatch** — both runners fire correctly regardless of file presence heuristics.
+- **Bash LSP re-spawn** — bash-language-server restarts cleanly after unexpected exit.
+- **HTML dispatch + htmlhint tag-pair detection** — HTML file kind wired into dispatch; htmlhint catches missing closing tags.
+- **Intelephense needs `scripts`** — PHP LSP installed with `--scripts` flag so its postinstall binary is available.
+- **Rust-analyzer: RootWithFallback + Windows .zip asset** — both root detection and Windows asset extraction fixed.
+- **Managed Pyright launch path** — pyright LSP binary resolves correctly when installed as a managed tool.
+- **Terraform / Kotlin / coverage fallback handling** — all three dispatch paths handle missing tools or configs gracefully.
+- **Shellcheck auto-install** — auto-installer works across platforms with GitHub release asset selection.
+- **Ktlint asset names** — ktlint release assets resolved with correct URL patterns.
+- **Coverage notice for mode:all linters** — mode:all linters that can't generate coverage now emit a notice instead of crashing.
+- **npm install 120s timeout** — `ensureTool` npm installs have a hard 120s timeout to prevent indefinite hangs.
+- **npm install ERESOLVE retry** — installer retries npm installs on ERESOLVE dependency conflicts.
+- **Remove spawnSync from `unchecked-throwing-call` rule** — rule no longer flags `spawnSync` calls as unhandled throwing calls.
+- **`flush()` drain before write-complete** — diagnostic history flush now drains pending entries before awaiting write completion, preventing data loss on session end.
+- **Runner checks diagnostics-only** — dispatch runner checks are now diagnostics-only, avoiding stale LSP state mutations.
+- **Biome-lsp server removed** — duplicate `biome-lsp` server entry removed; Biome LSP is accessed through the standard biome binary.
+- **Size guards + path caching for ensureTool** — tool availability checks are cached and sized to avoid re-probing on every call.
+- **Test assertions after runner wiring** — test expectations updated for new runner ordering and diagnostics pipeline.
+- **OS path separator normalization** — path separators and map keys normalized for cross-platform compatibility in diagnostics and LSP.
+- **Drop unnecessary async from `ensureAvailable`** — removed spurious `async` that added nothing and complicated error handling.
+- **Tree-sitter rule false positives** — fixed query syntax, scan scripts, and architect glob patterns that produced incorrect findings.
+
+### Performance
+- **Startup: defer npm tool availability probes** — tool availability checks (Biome, ESLint, etc.) now run lazily out of the critical path, reducing session start latency.
+- **Defer TypeScript loading in similarity runner** — similarity detection lazily imports the TypeScript parser, eliminating cold-start cost on first call.
+
+### Refactored
+- **LSP: collapse resolution into `resolveAndLaunch`** — unified four spawn mechanisms into one function with clear platform-aware fallbacks.
+- **Booboo: replace bespoke tree-sitter runner** — `/lens-booboo` tree-sitter checks now use the same fact-rule pipeline as dispatch, eliminating code duplication.
+- **Drop redundant async from LSP spawn** — removed unnecessary `async`/`await` from functions that already return Promises.
+
+### Tests
+- **GitHub release asset selection and PATH tests** — installer asset URL construction and PATH resolution covered by unit tests.
+- **Rust-analyzer Windows .zip asset expectation** — test fixture updated for `.zip` extension on Windows.
+- **Async-noise test multi-statement function** — test rule updated to match multi-statement function bodies.
 
 ## [3.8.26] - 2026-04-15
 

package/README.md

@@ -8,14 +8,18 @@ pi-lens focuses on real-time inline code feedback for AI agents.
 
 On every `write` and `edit`, pi-lens runs a fast, language-aware pipeline (checks depend on file language, project config, and installed tools):
 
-- **Formatting + autofix**: language/tool-specific formatters and safe autofixers (Biome, Ruff, ESLint, and other toolchain-native formatters when available)
-- **Type checking**: unified LSP (enabled by default) with language fallbacks (for example `ts-lsp`, `pyright`)
-- **Lint + static analysis**: active runners for the current language and config
-- **Test running**: related-file tests, with failed-first reruns for faster feedback
-- **Security checks**: secret scanning and structural security rules
-- **Structural analysis**: tree-sitter + ast-grep for bug patterns across supported languages
-- **Delta reporting**: prioritize new issues over legacy baseline noise
-- **Coverage transparency**: when primary analysis tools are unavailable for a file kind, pi-lens emits a non-blocking inline "analysis unavailable" warning (deduped per file per session)
+1. **Secrets scan** — blocking; aborts the write if credentials are detected
+2. **Auto-format** — language-specific formatters (Biome, Prettier, Ruff, gofmt, rustfmt, and 25+ others)
+3. **Auto-fix** — safe autofixes from 6 tools (Biome `--write`, Ruff `--fix`, ESLint `--fix`, stylelint `--fix`, sqlfluff `fix`, RuboCop `-a`) applied before analysis
+4. **LSP file sync** — opens/updates the file in active language servers
+5. **Dispatch lint** — parallel runner groups: LSP diagnostics, tree-sitter structural rules, ast-grep security/correctness rules, fact rules, language-specific linters, similarity detection, and architect checks
+6. **Test runner** — runs the corresponding test file; reruns known failures first
+7. **Cascade diagnostics** — review-graph impact cascade showing which other files were affected and how diagnostics propagated
+
+Results are inline and actionable:
+- **Blocking issues** — stop progress until fixed
+- **Warnings** — summarized inline, detail in `/lens-booboo`
+- **Health/telemetry** — available in `/lens-health`
 
 ### Session Start
 
@@ -28,7 +32,7 @@ At `session_start`, pi-lens:
 - emits missing-tool install hints for detected languages when relevant
 - injects session guidance through internal context (non-user channel) to reduce acknowledgement-only first responses
 
-For one-shot print sessions (for example `pi --print ...`), pi-lens auto-uses a quick startup path that skips heavy bootstrap work to reduce startup latency. You can override startup behavior with `PI_LENS_STARTUP_MODE=full|minimal|quick`.
+For one-shot print sessions (for example `pi --print ...`), pi-lens auto-uses a quick startup path that skips heavy bootstrap work to reduce startup latency. Override with `PI_LENS_STARTUP_MODE=full|minimal|quick`.
 
 ### Turn End
 
@@ -37,12 +41,7 @@ At `turn_end`, pi-lens:
 - summarizes deferred findings (for example duplicates/circulars)
 - persists turn findings for next context injection
 - updates debt/diagnostic tracking and cleans transient state
-
-Inline output is intentionally concise and actionable.
-
-- **Blocking issues**: shown inline and stop progress until fixed
-- **Warnings**: summarized, with deeper detail in `/lens-booboo`
-- **Health/telemetry**: available in `/lens-health`
+- renders a review-graph impact cascade showing affected files and diagnostic propagation
 
 ## Install
 
@@ -59,11 +58,15 @@ pi install git:github.com/apmantza/pi-lens
 ## Run
 
 ```bash
-# Standard mode
+# Standard mode (LSP enabled by default)
 pi
 
-# Optional safety: disable unified LSP and use fallbacks
-pi --no-lsp
+# Optional switches
+pi --no-lsp              # Disable unified LSP, use language-specific fallbacks
+pi --no-autoformat        # Skip auto-formatting
+pi --no-autofix           # Skip auto-fix (Biome, Ruff, ESLint, stylelint, sqlfluff, RuboCop)
+pi --no-tests             # Skip test runner
+pi --no-shellcheck        # Disable shellcheck runner
 ```
 
 ## Key Commands
@@ -71,50 +74,181 @@ pi --no-lsp
 - `/lens-booboo` — full quality report for current project state
 - `/lens-health` — runtime health, latency, and diagnostic telemetry
 
-## Runners
+## Language Coverage
 
-Registered dispatch runners:
+pi-lens supports **35+ languages** through dispatch runners and LSP integration:
 
-- `lsp`, `ts-lsp`, `pyright`
-- `biome-check-json`, `biome-lint`, `ruff-lint`, `eslint`, `oxlint`
-- `tree-sitter`, `ast-grep-napi`, `type-safety`, `similarity`
-- `architect`, `python-slop`, `shellcheck`, `spellcheck`
-- `yamllint`, `sqlfluff`
-- `go-vet`, `golangci-lint`, `rust-clippy`, `rubocop`
+| Language | LSP | Dispatch Runners | Formatter |
+|---|---|---|---|
+| JavaScript/TypeScript | ✓ | lsp, ts-lsp, biome-check-json, tree-sitter, ast-grep-napi, type-safety, similarity, fact-rules, eslint, architect | biome, prettier |
+| Python | ✓ | lsp, pyright, ruff-lint, tree-sitter, python-slop, architect | ruff, black |
+| Go | ✓ | lsp, go-vet, golangci-lint, tree-sitter | gofmt |
+| Rust | ✓ | lsp, rust-clippy, tree-sitter | rustfmt |
+| Ruby | ✓ | lsp, rubocop, tree-sitter | rubocop, standardrb |
+| C/C++ | ✓ | lsp, cpp-check | clang-format |
+| Shell | ✓ | lsp, shellcheck | shfmt |
+| CSS/SCSS/Less | ✓ | lsp, stylelint, prettier-check | biome, prettier |
+| HTML | ✓ | lsp, htmlhint, prettier-check | prettier |
+| YAML | ✓ | lsp, yamllint | prettier |
+| JSON | ✓ | lsp | biome, prettier |
+| SQL | — | sqlfluff | sqlfluff |
+| Markdown | — | spellcheck, markdownlint | prettier |
+| Docker | ✓ | lsp, hadolint | — |
+| PHP | ✓ | lsp, php-lint, phpstan | php-cs-fixer |
+| PowerShell | ✓ | lsp, psscriptanalyzer | — |
+| Prisma | ✓ | lsp, prisma-validate | — |
+| C# | ✓ | lsp, dotnet-build | csharpier |
+| F# | ✓ | lsp | fantomas |
+| Java | ✓ | lsp, javac | — |
+| Kotlin | ✓ | lsp, ktlint | ktlint |
+| Swift | ✓ | lsp | swiftformat |
+| Dart | ✓ | lsp, dart-analyze | dart format |
+| Lua | ✓ | lsp | stylua |
+| Zig | ✓ | lsp, zig-check | zig fmt |
+| Haskell | ✓ | lsp | ormolu |
+| Elixir | ✓ | lsp, elixir-check, credo | mix format |
+| Gleam | ✓ | lsp, gleam-check | gleam format |
+| OCaml | ✓ | lsp | ocamlformat |
+| Clojure | ✓ | lsp | — |
+| Terraform | ✓ | lsp, tflint | terraform fmt |
+| Nix | ✓ | lsp | nixfmt |
+| TOML | ✓ | lsp, taplo | taplo |
+| CMake | ✓ | lsp | — |
+
+## Fact Rules Pipeline
+
+Dispatch includes a fact-rule engine that extracts function-level metrics (cyclomatic complexity, nesting depth, outgoing calls) and evaluates quality rules inline:
+
+- **high-complexity** — flags functions exceeding configurable CC thresholds
+- **unsafe-boundary** — detects dangerous boundary crossings (unvalidated user input → trusted context)
+- **high-fan-out** — flags excessive outgoing call count (default threshold: 20)
+- **comment-facts** — classifies comment quality (TODO density, doc coverage)
+- **try-catch-facts** — flags empty/obscuring catch blocks
+- **import-facts** — detects circular/star/unused imports
+- **file-role** — classifies files as source/test/config/vendor and adjusts severity
+
+## Tree-sitter Rules
+
+Structural rules are organized by language in `rules/tree-sitter-queries/`:
+
+- **TypeScript** (18 rules): console-statement, debugger, deep-nesting, eval, sql-injection, ssrf, weak-hash, unsafe-regex, variable-shadowing, and more
+- **Python** (26 rules): debug statements, hardcoded secrets, mutable class attrs, unsafe regex, empty except, and more
+- **Go** (17 rules): defer-in-loop, hardcoded secrets, unchecked errors, and more
+- **Rust** (6 rules): unsafe blocks, unwrap outside tests, and more
+- **Ruby** (15 rules): empty rescue, rescue Exception, debugger, hardcoded secrets, and more
+
+Plus **180+ ast-grep rules** in `rules/ast-grep-rules/` covering security (no-eval, jwt-no-verify, no-hardcoded-secrets, no-insecure-randomness), correctness (strict-equality, empty-catch, no-cond-assign), and style patterns across JS/TS/Python.
+
+## Review Graph
+
+pi-lens builds a review graph (`file → symbol → dependency`) during session and uses it at turn end to render an impact cascade: which files were affected by a change and how diagnostics propagated through the dependency graph. Nodes track kind, language, and export status; edges track contains/imports/calls/references.
+
+## LSP Support
+
+pi-lens includes **37 language server definitions**. LSP is **enabled by default** (`--lsp` or no flag). Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server is not installed, pi-lens offers an interactive install prompt.
+
+LSP servers for: TypeScript, Deno, Python (pyright + pylsp), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, C# (omnisharp), F#, Java, Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, OCaml, Clojure, Terraform, Nix, Bash, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, ESLint, CSS.
 
-Some runners are language/config-gated and may skip when not applicable.
-`ast-grep-napi` runs in post-write dispatch for JS/TS with blocker-focused filtering; `/lens-booboo` additionally runs full CLI ast-grep scans.
+## Runners
+
+44 registered dispatch runners:
+
+| Category | Runners |
+|---|---|
+| LSP | `lsp`, `ts-lsp`, `pyright` |
+| JS/TS | `biome-check-json`, `eslint`, `ast-grep-napi`, `type-safety`, `similarity`, `tree-sitter`, `fact-rules` |
+| Python | `ruff-lint`, `tree-sitter`, `python-slop`, `mypy` |
+| Go | `go-vet`, `golangci-lint` |
+| Rust | `rust-clippy` |
+| Ruby | `rubocop` |
+| PHP | `php-lint`, `phpstan` |
+| C# | `dotnet-build` |
+| Java | `javac` |
+| Kotlin | `ktlint` |
+| Dart | `dart-analyze` |
+| Elixir | `elixir-check`, `credo` |
+| Gleam | `gleam-check` |
+| Zig | `zig-check` |
+| C/C++ | `cpp-check` |
+| Docker | `hadolint` |
+| HTML | `htmlhint` |
+| CSS | `stylelint`, `prettier-check` |
+| Markdown | `markdownlint`, `spellcheck` |
+| Shell | `shellcheck`, `shfmt` |
+| YAML | `yamllint` |
+| SQL | `sqlfluff` |
+| TOML | `taplo` |
+| Terraform | `tflint` |
+| PowerShell | `psscriptanalyzer` |
+| Prisma | `prisma-validate` |
+| Architecture | `architect`, `fact-rules` |
+
+Runners are language/config-gated and skip when not applicable. `ast-grep-napi` runs in post-write dispatch for JS/TS with blocker-focused filtering; `/lens-booboo` additionally runs full CLI ast-grep scans.
+
+## Formatters
+
+pi-lens auto-detects and runs **26 formatters** based on project config:
+
+biome, prettier, ruff, black, sqlfluff, gofmt, rustfmt, zig fmt, dart format, shfmt, nixfmt, mix format, ocamlformat, clang-format, ktlint, rubocop, standardrb, gleam format, terraform fmt, php-cs-fixer, csharpier, fantomas, swiftformat, stylua, ormolu, taplo
+
+Detection rules:
+- **Config-gated**: only runs when project config indicates usage (e.g. `biome.json`, `.prettierrc`, `ruff.toml`)
+- **Nearest-wins**: when multiple formatter configs exist at different directory levels, the one closest to the edited file wins
+- **Biome-default**: for JS/TS files without Prettier or Biome config, Biome is used as the default formatter
+- **Ruff-default**: for Python files without Black config, Ruff format is used when available
 
 ## Dependencies
 
 Auto-install behavior depends on gate type:
 
-- **Config-gated**: installs only when project config/deps indicate usage.
-- **Flow/language-gated**: installs when the runtime path needs it for the current file/session flow.
-- **Operational prewarm**: installs during session warm scans / turn-end analysis paths.
+- **Config-gated**: installs only when project config/deps indicate usage
+- **Flow/language-gated**: installs when the runtime path needs it for the current file/session flow
+- **Operational prewarm**: installs during session warm scans / turn-end analysis paths
+- **GitHub release**: platform-specific binary downloaded from GitHub releases to `~/.pi-lens/bin/`
 
 | Tool | Purpose | Auto-installed | Gate |
 |---|---|---|---|
-| `@biomejs/biome` | JS/TS lint/format/autofix | Yes | Config-gated (`biome.json`/`biome.jsonc` or `@biomejs/biome` dep) |
-| `prettier` | Formatting fallback | Yes | Config-gated (Prettier dep or `package.json#prettier`) |
-| `yamllint` | YAML linting | Yes | Config-gated (`.yamllint*` / tool section / dep hint) |
-| `sqlfluff` | SQL linting/formatting | Yes | Config-gated (`.sqlfluff` / tool section / dep hint) |
-| `ruff` | Python lint/format/autofix | Yes | Language-default + flow-gated (Python detected; respects `--no-autofix-ruff`) |
-| `typescript-language-server` | Unified LSP diagnostics | Yes | Language-default + flow-gated (JS/TS detected and LSP enabled) |
-| `pyright` | Python type diagnostics fallback | Yes | Flow/language-gated (Python fallback paths) |
-| `@ast-grep/cli` (`sg`) | AST scans/search/replace | Yes | Operational prewarm + analysis flows |
-| `knip` | Dead code analysis | Yes | Operational prewarm + turn-end flows (JS/TS language + config gated at startup) |
-| `jscpd` | Duplicate code detection | Yes | Operational prewarm + turn-end flows (JS/TS language + config gated at startup) |
+| `@biomejs/biome` | JS/TS lint/format/autofix | Yes | Config-gated |
+| `prettier` | Formatting fallback | Yes | Config-gated |
+| `yamllint` | YAML linting | Yes | Config-gated |
+| `sqlfluff` | SQL linting/formatting | Yes | Config-gated |
+| `ruff` | Python lint/format/autofix | Yes | Language-default + flow-gated |
+| `typescript-language-server` | Unified LSP diagnostics | Yes | Language-default |
+| `typescript` | TypeScript compiler | Yes | Language-default |
+| `pyright` | Python type diagnostics fallback | Yes | Flow/language-gated |
+| `@ast-grep/cli` (sg) | AST scans/search/replace | Yes | Operational prewarm |
+| `knip` | Dead code analysis | Yes | Operational prewarm + config-gated |
+| `jscpd` | Duplicate code detection | Yes | Operational prewarm + config-gated |
 | `madge` | Circular dependency analysis | Yes | Turn-end analysis flow |
-
-LSP is enabled by default. pi-lens includes many language-server definitions (including up to 31+ servers), and activates them when the server is installed and the project/root detection matches the file.
-
-Optional safety switch:
-
-- `--no-lsp` disables unified LSP dispatch and falls back to language-specific checks where available (for example `ts-lsp`, `pyright`).
-- `--lens-guard` (experimental) blocks `git commit`/`git push` attempts when unresolved pi-lens blockers are pending.
+| `mypy` | Python type checking | Yes | Flow-gated |
+| `stylelint` | CSS/SCSS/Less linting | Yes | Config-gated |
+| `markdownlint-cli2` | Markdown linting | Yes | Config-gated |
+| `shellcheck` | Shell script linting | Yes | GitHub release |
+| `shfmt` | Shell script formatting | Yes | GitHub release |
+| `rust-analyzer` | Rust LSP | Yes | GitHub release |
+| `golangci-lint` | Go linting | Yes | GitHub release |
+| `hadolint` | Dockerfile linting | Yes | GitHub release |
+| `ktlint` | Kotlin linting | Yes | GitHub release |
+| `tflint` | Terraform linting | Yes | GitHub release |
+| `taplo` | TOML linting/formatting | Yes | GitHub release |
+| `terraform-ls` | Terraform LSP | Yes | GitHub release |
+| `htmlhint` | HTML linting | Yes | Config-gated |
+| `@prisma/language-server` | Prisma LSP | Yes | Flow-gated |
+| `dockerfile-language-server-nodejs` | Dockerfile LSP | Yes | Flow-gated |
+| `intelephense` | PHP LSP | Yes | Flow-gated |
+| `bash-language-server` | Bash LSP | Yes | Language-default |
+| `yaml-language-server` | YAML LSP | Yes | Language-default |
+| `vscode-langservers-extracted` | JSON/ESLint/CSS/HTML LSP | Yes | Language-default |
+| `vscode-css-languageserver` | CSS LSP | Yes | Language-default |
+| `vscode-html-languageserver-bin` | HTML LSP | Yes | Language-default |
+| `svelte-language-server` | Svelte LSP | Yes | Flow-gated |
+| `@vue/language-server` | Vue LSP | Yes | Flow-gated |
+| `psscriptanalyzer` | PowerShell linting | Manual | — |
+
+Additional language servers (gopls, ruby-lsp, solargraph, etc.) are auto-detected from PATH or installed via native package managers (`go install`, `gem install`) when their language is detected.
 
 ## Notes
 
 - Not every auto-install runs in every project: gate type decides when install is attempted.
 - Rule packs are customizable via project-level rule directories.
+- Inline suppression: `// pi-lens-ignore` or `# pi-lens-ignore` comments suppress diagnostic output for that line.

package/clients/agent-behavior-client.ts

@@ -8,6 +8,8 @@
  * No external dependencies — purely tracks tool call history.
  */
 
+import { normalizeMapKey } from "./path-utils.js";
+
 // --- Types ---
 
 export type BehaviorWarning = {
@@ -107,9 +109,10 @@ export class AgentBehaviorClient {
 
 			// Track edits per file
 			if (filePath) {
+				const key = normalizeMapKey(filePath);
 				this.fileEditCount.set(
-					filePath,
-					(this.fileEditCount.get(filePath) ?? 0) + 1,
+					key,
+					(this.fileEditCount.get(key) ?? 0) + 1,
 				);
 			}
 		}

package/clients/ast-grep-client.ts

@@ -55,7 +55,7 @@ export class AstGrepClient {
 	/**
 	 * Check if ast-grep CLI is available, auto-install if not
 	 */
-	async ensureAvailable(): Promise<boolean> {
+	ensureAvailable(): Promise<boolean> {
 		return this.runner.ensureAvailable();
 	}
 

package/clients/biome-client.ts

@@ -9,6 +9,7 @@
  */
 
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { isFileKind } from "./file-kinds.js";
 import { safeSpawn, safeSpawnAsync } from "./safe-spawn.js";
@@ -60,16 +61,29 @@ export class BiomeClient {
 		if (this.localBinaryPath) return { cmd: this.localBinaryPath, args: [] };
 
 		// Walk up from cwd looking for node_modules/.bin/biome.
+		// Also check ~/.pi-lens/tools (where ensureTool("biome") auto-installs),
+		// so we avoid the ~1.5s `npx @biomejs/biome --version` fallback when
+		// the tool is already installed but not in the project's node_modules.
 		// On Windows prefer .cmd (native batch) over the sh wrapper — 2x faster.
 		const isWin = process.platform === "win32";
+		const piLensBin = path.join(
+			os.homedir(),
+			".pi-lens",
+			"tools",
+			"node_modules",
+			".bin",
+		);
 		const candidates = isWin
 			? [
 					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
 					path.join(process.cwd(), "node_modules", ".bin", "biome"),
+					path.join(piLensBin, "biome.cmd"),
+					path.join(piLensBin, "biome"),
 				]
 			: [
 					path.join(process.cwd(), "node_modules", ".bin", "biome"),
 					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
+					path.join(piLensBin, "biome"),
 				];
 		for (const p of candidates) {
 			if (fs.existsSync(p)) {

package/clients/diagnostic-logger.ts

@@ -57,7 +57,7 @@ export interface Diagnostic {
 	message?: string;
 }
 
-interface LogContext {
+export interface LogContext {
 	model: string;
 	sessionId: string;
 	turnIndex: number;
@@ -100,7 +100,7 @@ export function createDiagnosticLogger(): DiagnosticLogger {
 		try {
 			await fs.promises.appendFile(getLogFile(), lines);
 		} catch (err) {
-			// Log write failure but don't block
+			// pi-lens-ignore: missing-error-propagation — fire-and-forget log write, must not throw
 			console.error("Failed to write diagnostic log:", err);
 		}
 		writing = false;
@@ -137,7 +137,8 @@ export function createDiagnosticLogger(): DiagnosticLogger {
 		},
 
 		async flush() {
-			// Wait for any pending writes to complete
+			// Drain any buffered entries, then wait for the write to finish.
+			await writePending();
 			while (writing) {
 				await new Promise((resolve) => setTimeout(resolve, 10));
 			}