pi-lens 3.8.46 → 3.8.47

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to pi-lens will be documented in this file.
 
 ## [Unreleased]
 
+## [3.8.47] - 2026-06-01
+
+### Added
+
+- **Actionable-warnings ecosystem expansion (closes #112)** — six dispatch runners now propagate `fixable` + a `fixSuggestion` so the actionable-warnings advisory can surface them instead of dropping them into code-quality. rust-clippy and golangci-lint read the structured replacement metadata each tool already publishes (`suggested_replacement` / `Replacement`); sqlfluff, detekt, swiftlint, and dart-analyze use curated allowlists of rules their respective `--fix` / `--auto-correct` / `dart fix --apply` commands rewrite deterministically. oxlint, stylelint, and markdownlint received the same treatment earlier in the cycle. Each slice ships parser-level unit tests against the runner's real output shape.
+- **Framework / convention detector foundation (#118 Phases 1 + 2)** — new `clients/project-conventions.ts` exports `detectProjectConventions(cwd)` returning detected `frameworks` (react / next / vite / vitest in the first cut, each with confidence + signals), `testRunners`, `buildTools`, and `agentDocs`. Detection is purely deterministic — no LLM, no spawn — from `package.json` deps, canonical config files, and directory shape. `ProjectSnapshot` gained an optional `conventions` field with explicit-arg → previously-saved → fresh-detect precedence so a snapshot rewrite without conventions inherits rather than blanks.
+- **Per-runner timeoutMs overrides the global 30 s default (#107)** — each `RunnerDefinition` may now declare its own `timeoutMs`; the dispatch harness honours it instead of the shared `RUNNER_TIMEOUT_FLOOR_MS`. The floor is also configurable via `pi-lens.runnerTimeoutFloorMs` config and `PI_LENS_RUNNER_TIMEOUT_FLOOR_MS` env, guarded against NaN, and lazy-resolved so tests can reset it.
+- **LSP diagnostics-wait cap with env override (#117)** — dispatch LSP wait is now capped at 2.5 s by default to prevent slow language servers from holding edit feedback; tunable via `PI_LENS_LSP_DIAGNOSTICS_MAX_WAIT_MS`. A new `lsp_diagnostics_timeout` phase event and a `diagnosticsTimedOut` flag in the success log surface when the cap fires.
+- **Tool-result debounce window (#115)** — `PI_LENS_TOOL_RESULT_DEBOUNCE_MS` (default 0, max 1 s) coalesces sequential tool_results for the same file so burst edits no longer rerun the full pipeline on every keystroke. Off by default; opt-in via env.
+- **Custom rules guide + JSON schemas** — new docs and JSON schemas for tree-sitter and ast-grep custom rule authoring, plus tightened agent skill docs for write-ast-grep-rule, write-tree-sitter-rule, ast-grep, and lsp-navigation.
+- **Read-guard `oldtext_duplicate` disambiguation** — the first `oldtext_not_found` and every `oldtext_duplicate` now include surrounding line context so the agent can pick the right occurrence without rereading the whole file.
+
+### Performance
+
+- **In-flight dedupe on RuffClient and BiomeClient (#120)** — concurrent first-time callers to `ensureAvailable()` now share a single probe + auto-install promise via `ensureInFlight`, mirroring the pattern that closed #113 for SgRunner. Previously two parallel session-start tasks (one Python, one JS/TS) could each race the `ensureTool()` auto-install branch and produce partial state in `~/.pi-lens/tools`.
+- **SgRunner in-flight dedupe (#113)** — concurrent ast-grep `ensureAvailable()` callers now share one probe; the auto-install branch runs at most once across a session.
+- **Centralized `~/.pi-lens` and `walkUpDirs` helpers** — every `~/.pi-lens` computation now routes through `getGlobalPiLensDir()` (#122), and the parent-dir walk is consolidated as a `walkUpDirs` generator + `findNearestContaining` helper in `path-utils.ts`. Same behaviour, fewer ad-hoc walks.
+
+### Fixed
+
+- **Cascade reverse-dependency neighbors now use the in-memory index** — the cascade builder was building a reverse-dep index from the review graph, saving it to the project snapshot, then immediately reloading it from disk to compute affected-file neighbors. The reload almost always returned `null` during active editing because the project sequence had advanced past the snapshot sequence, silently discarding the freshly computed data every time. Affected-file queries now run directly against the in-memory index built from the just-completed graph.
+- **Tree-sitter rule cache preserves `has_fix` across the roundtrip** — `has_fix` was set on first load but dropped on the cache rehydration path, so cached runs never marked tree-sitter findings as fixable. Restored — the cache now roundtrips the flag end to end.
+- **TypeScript LSP starts for pi-extension files when only `~/.pi/agent/package.json` exists (#123)** — root detection now performs a bounded walk to the extension boundary; if no marker is found inside that scope, it falls back to `FileDirRoot` provided the agent-level `package.json` exists, instead of silently giving up.
+- **BiomeClient resolves binaries per project cwd, not `process.cwd()` (#121)** — `getBiomeBinary` now accepts a per-call cwd and caches resolved binaries keyed by cwd, so monorepos with sub-package biome installs reach the right binary even when pi-lens was invoked from a different directory.
+- **Skip redundant `notify.open` on `touchFile` when content was already pushed within the debounce window (#116)** — split `shouldSkipTouch` from `shouldSkipNotify`; the latter avoids re-opening but still waits for diagnostics so cache invalidation isn't lost. A `notifySkipped` flag in the latency log records when the optimization fires.
+- **dispatch runner `--version` probes flow through `createAvailabilityChecker`** — cpp-check is now cwd-keyed and dedupes concurrent first-time callers, eliminating one of the hottest uncached spawn paths in the audit.
+- **PILENS_DATA_DIR compliance in actionable-warnings, review-graph, semgrep-config** — these paths now route through `getProjectDataDir(cwd)` instead of hardcoding `.pi-lens/` under cwd, so the data dir override is respected end to end.
+- **Read-guard tracks session writes in an explicit Set** — unreliable mtime checks could let a Write→Edit sequence be blocked by a zero-read violation; an explicit per-session write set is the new authoritative signal.
+- **Read-guard partial apply routes through post-edit analysis** — when only some `oldText` edits resolve, partial application performs exact replacements and then invokes the normal `handleToolResult` pipeline so staleness stamps, modified ranges, deferred formatting, dispatch diagnostics, cascade, and warning collection stay in sync with disk.
+- **Read-guard staleness escalation fires across inter-turn gaps** — `REPEAT_FAILURE_TTL_MS` raised from 30 s to 300 s so repeated stale `oldText` attempts 2–3 minutes apart are still counted as the same streak; at ≥ 2 failures the preflight error is upgraded from `🔄 RETRYABLE` to `🛑 RE-READ REQUIRED`.
+- **dart-analyze / detekt drop the dead sync `isAvailable` fallback** — both runners now use only the async availability check, eliminating a dead code path that masked test-mock mismatches.
+- **ReDoS hotspots in oxlint rule extraction and cors-wildcard patterns** — bounded the affected regexes; the oxlint fix also backfills `defectClass` on five runners that had been missing it.
+- **5 runners that were missing `defectClass`** — backfilled correctness/style/etc. classifications so downstream taxonomy + advisory routing work consistently.
+
+### Widget
+
+- **Quieter widget glyphs and tighter horizontal layout** — warning glyph swapped from triangle to exclamation mark, dispatch findings pack into a single horizontal row at normal widths, the red dot now reflects blocking semantics (not just severity), and the divider/filename header / non-blocking fillers in horizontal mode were dropped.
+
 ## [3.8.46] - 2026-05-27
 
 ### Added

package/README.md

@@ -8,6 +8,22 @@ pi-lens focuses on real-time inline code feedback for AI agents.
 
 ## What It Does
 
+### At Session Start
+
+At `session_start`, pi-lens:
+
+- resets runtime state and diagnostic telemetry
+- detects project root, language profile, and active tools
+- applies language-aware startup defaults for tool preinstall
+- warms caches and optional indexes (with overlap/session guardrails)
+- emits missing-tool install hints for detected languages when relevant
+- prepends session guidance before the user's prompt so provider bridges keep the real prompt active
+- opens `warmFiles` (if configured in `.pi-lens/lsp.json`) to seed lazy-indexing language servers like clangd before the first symbol query
+
+Startup scan context and language profile are cached in the project snapshot and reused on subsequent `/new` invocations when the project has not changed, avoiding repeated full filesystem walks (~2.5 s saved on medium-to-large projects). Background startup scans are deferred past the interactive session-start path so they do not inflate visible `/new` latency.
+
+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`.
+
 ### On Write/Edit
 
 On every `write` and `edit`, pi-lens runs a fast, language-aware pipeline (checks depend on file language, project config, and installed tools):
@@ -34,22 +50,6 @@ At `agent_end` (once per user prompt, after all agent tool calls complete):
 - **Conservative LSP warning autofix** — when `actionableWarnings.autoFix.enabled` is set, applies up to 5 preferred LSP quickfixes for warnings flagged in the turn's actionable warnings report. Each fix is re-validated against the live LSP server at apply time, checked for ambiguity (skipped if multiple eligible actions exist), and gated by a safety check before any write occurs. Changed files are registered with the read-guard and cache manager
 - **Summary notification** — concise status: how many files were formatted, which changed, and whether any formatter failed
 
-### Session Start
-
-At `session_start`, pi-lens:
-
-- resets runtime state and diagnostic telemetry
-- detects project root, language profile, and active tools
-- applies language-aware startup defaults for tool preinstall
-- warms caches and optional indexes (with overlap/session guardrails)
-- emits missing-tool install hints for detected languages when relevant
-- prepends session guidance before the user's prompt so provider bridges keep the real prompt active
-- opens `warmFiles` (if configured in `.pi-lens/lsp.json`) to seed lazy-indexing language servers like clangd before the first symbol query
-
-Startup scan context and language profile are cached in the project snapshot and reused on subsequent `/new` invocations when the project has not changed, avoiding repeated full filesystem walks (~2.5 s saved on medium-to-large projects). Background startup scans are deferred past the interactive session-start path so they do not inflate visible `/new` latency.
-
-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
 
 At `turn_end`, pi-lens:
@@ -159,54 +159,19 @@ Supported: TypeScript, TSX, JavaScript, JSX, Python, Go, Rust, Ruby.
 
 Covers JavaScript/TypeScript, Python, Go, Rust, Ruby, Shell, and CMake. A TypeScript AST-based fact-rule engine extracts function-level metrics and evaluates quality and security rules inline. Blocking rules surface immediately at write time; advisory rules are available via `/lens-booboo`.
 
-**Blocking (surface inline at write time):**
-
-- **cors-wildcard** — `Access-Control-Allow-Origin: *` in server-side code
-- **error-swallowing** — empty catch block (skips documented local fallbacks and fs-boundary catches)
-- **no-commented-credentials** — password/token/secret in commented-out code
-- **high-entropy-string** — string literals with suspiciously high Shannon entropy (possible hardcoded secret)
-
-**Advisory (accessible via `/lens-booboo`):**
-
-- **high-complexity** / **no-complex-conditionals** — cyclomatic complexity and deeply nested conditions
-- **high-fan-out** — function calls too many distinct functions (coordination smell)
-- **unsafe-boundary** — dangerous `any` casts at API boundaries
-- **async-noise** / **async-unnecessary-wrapper** — async functions with no await; wrappers that add no value
-- **pass-through-wrappers** — trivial wrapper functions
-- **dynamic-regexp** — `new RegExp(variable)` (potential ReDoS; complements tree-sitter `unsafe-regex`)
-- **jwt-without-verify** — `jwt.sign()` without `jwt.verify()` in the same file
-- **missing-error-propagation** — catch blocks that log but don't rethrow
-- **error-obscuring** — catch blocks that wrap errors in a different type
-- **duplicate-string-literal** / **no-boolean-params** / **high-import-coupling** — code-quality signals
-
 ### Tree-sitter Rules
 
-Structural rules organized by language in `rules/tree-sitter-queries/`. Rules marked **🔴** block the agent inline at write time (only for lines in the current edit); others are advisory.
-
-**TypeScript (23 rules):**
-🔴 `eval`, `sql-injection`, `ts-command-injection`, `ts-ssrf`, `ts-xss-dom-sink`, `ts-dynamic-require`, `ts-open-redirect`, `ts-nosql-injection`, `ts-weak-hash`, `ts-hallucinated-react-import`, `unsafe-regex`, `debugger`, `default-not-last`, `duplicate-function-arg`, `empty-switch-case`, `infinite-loop`, `self-assignment`, `switch-case-termination`  
-⚠️ `console-statement`, `deep-promise-chain`, `mixed-async-styles`, `ts-insecure-random`, `ts-detached-async-call`, `ts-react-antipatterns`, `ts-weak-hash`, `variable-shadowing`
-
-**Python:** 🔴 `python-command-injection`, `python-sql-injection`, `python-insecure-deserialization`, `python-weak-hash`, `python-hallucinated-import` + 20 advisory rules
-
-**Go:** 🔴 `go-command-injection`, `go-sql-injection`, `go-shared-map-write-goroutine`, `go-weak-hash` + 13 advisory rules
-
-**Rust:** 🔴 `rust-lock-held-across-await` + 3 advisory rules (`rust-unsafe-block`, `rust-expect`, `rust-clone-in-loop`)
-
-**Ruby:** 🔴 `ruby-weak-hash` + 14 advisory rules
+Structural rules organized by language in `rules/tree-sitter-queries/<language>/`. Rules marked **🔴** block the agent inline at write time (only for lines in the current edit); others are advisory.
 
 **Suppressing a finding:** add `// pi-lens-ignore: rule-id` on the flagged line or the line above (JS/TS), or `# pi-lens-ignore: rule-id` for Python/Ruby/Shell. This suppresses that specific rule at that location only.
 
-**Project-wide disabling** is not currently supported through config — there is no `.pi-lens/disabled-rules` file. Use inline suppression for per-occurrence overrides. When editing pi-lens itself, move a rule file to the `<language>-disabled/` directory to prevent it from running.
+**Bring your own rules:** drop YAML query files into `rules/tree-sitter-queries/<language>/` in your project — pi-lens merges them with the built-ins on session start. The schema, predicates (`eq`, `match`, `any-of`), and `inline_tier` (`blocking` | `warning` | `review`) are documented in [`docs/custom-rules.md`](docs/custom-rules.md). A `rules/tree-sitter-queries/rule-schema.json` JSON Schema is bundled for editor autocomplete via `.vscode/settings.json`.
 
 ### Ast-Grep Rules
 
-**180+ rules** in `rules/ast-grep-rules/` across JS, TS, and Python:
+Pattern-based structural rules in `rules/ast-grep-rules/` across JS, TS, and Python — covers security (eval, hardcoded secrets, insecure randomness, dangerous DOM sinks), correctness (strict equality, constant conditions, duplicate keys), code smells (nested ternaries, long parameter lists, redundant state), and agent stubs (unimplemented bodies, raise NotImplementedError).
 
-- **Security** — no-eval, jwt-no-verify, no-hardcoded-secrets, no-insecure-randomness, no-inner-html, no-javascript-url, weak-rsa-key
-- **Correctness** — strict-equality, no-cond-assign, no-constant-condition, no-dupe-keys, no-nan-comparison, array-callback-return, constructor-super
-- **Style/smells** — nested-ternary, long-parameter-list, large-class, prefer-optional-chain, redundant-state, require-await
-- **Agent stubs** — no-unimplemented-stub, no-raise-not-implemented, no-ellipsis-body
+**Bring your own rules:** drop YAML rule files into `rules/ast-grep-rules/rules/<id>.yml` in your project — pi-lens merges them with the built-ins; same `id` as a built-in overrides it. The supported subset of ast-grep's rule schema (the NAPI runner does not support `inside` / `follows` / `precedes` / `stopBy` / `field` / `nthChild` / `constraints` — use a tree-sitter rule when you need relational context) is documented in [`docs/custom-rules.md`](docs/custom-rules.md), with a `rules/ast-grep-rules/rule-schema.json` JSON Schema for editor autocomplete.
 
 ### Semgrep CLI Integration (Experimental)
 
@@ -238,58 +203,6 @@ metadata:
     confidence: high
 ```
 
-## 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
-- **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                       |
-| `prettier`                          | Formatting fallback              | Yes            | Config-gated                       |
-| `yamllint`                          | YAML linting                     | Yes            | Config-gated                       |
-| `actionlint`                        | GitHub Actions workflow linting  | Yes            | GitHub release                     |
-| `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             |
-| `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                         |
-| `semgrep`                           | Experimental security dispatch   | Manual         | Local config / explicit opt-in     |
-| `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.
-
 ## Run
 
 ```bash
@@ -410,3 +323,55 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | Nix                   | ✓   | lsp                                                                                                            | nixfmt                  |
 | TOML                  | ✓   | lsp, taplo                                                                                                     | taplo                   |
 | CMake                 | ✓   | lsp                                                                                                            | cmake-format            |
+
+## 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
+- **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                       |
+| `prettier`                          | Formatting fallback              | Yes            | Config-gated                       |
+| `yamllint`                          | YAML linting                     | Yes            | Config-gated                       |
+| `actionlint`                        | GitHub Actions workflow linting  | Yes            | GitHub release                     |
+| `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             |
+| `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                         |
+| `semgrep`                           | Experimental security dispatch   | Manual         | Local config / explicit opt-in     |
+| `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.

package/clients/actionable-warnings-logger.ts

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
+import { isTestMode } from "./env-utils.js";
+import { getGlobalPiLensDir } from "./file-utils.js";
 
-const AW_LOG_DIR = path.join(os.homedir(), ".pi-lens");
+const AW_LOG_DIR = getGlobalPiLensDir();
 const AW_LOG_FILE = path.join(AW_LOG_DIR, "actionable-warnings.log");
 const AW_LOG_BACKUP_FILE = path.join(AW_LOG_DIR, "actionable-warnings.log.1");
 const MAX_LOG_BYTES = Math.max(
@@ -47,10 +48,7 @@ function rotateIfNeeded(): void {
 export function logActionableWarningsEvent(
 	entry: ActionableWarningsLogEntry,
 ): void {
-	if (
-		process.env.PI_LENS_TEST_MODE === "1" ||
-		(process.env.VITEST && process.env.PI_LENS_TEST_MODE !== "0")
-	) {
+	if (isTestMode()) {
 		return;
 	}
 	const line = `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`;

package/clients/actionable-warnings.ts

@@ -9,6 +9,7 @@ import { getLSPService } from "./lsp/index.js";
 import { normalizeMapKey } from "./path-utils.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 import { logActionableWarningsEvent } from "./actionable-warnings-logger.js";
+import { getProjectDataDir } from "./file-utils.js";
 
 export interface ActionableWarningAction {
 	title: string;
@@ -142,8 +143,7 @@ function serializeAction(action: LSPCodeAction): ActionableWarningAction {
 
 function readSuppressionState(cwd: string): WarningStateFile {
 	const statePath = path.join(
-		cwd,
-		".pi-lens",
+		getProjectDataDir(cwd),
 		"cache",
 		"actionable-warning-state.json",
 	);
@@ -162,8 +162,7 @@ function updateWarningState(
 	warnings: ActionableWarningRecord[],
 ): void {
 	const statePath = path.join(
-		cwd,
-		".pi-lens",
+		getProjectDataDir(cwd),
 		"cache",
 		"actionable-warning-state.json",
 	);

package/clients/biome-client.ts

@@ -32,7 +32,16 @@ export interface BiomeDiagnostic {
 
 export class BiomeClient {
 	private biomeAvailable: boolean | null = null;
-	private localBinaryPath: string | null = null;
+	// Per-cwd cache of the resolved biome binary. Keying by cwd matters in
+	// monorepos where different sub-packages each ship their own biome
+	// installation; sharing one slot across the whole client would cause
+	// the first resolution to win and stale across other packages.
+	private localBinaryByCwd = new Map<string, string>();
+	// The binary path written by `ensureTool("biome")` — genuinely global
+	// (lives under ~/.pi-lens/tools), so it's stored separately from the
+	// per-cwd cache and used as a final fallback before npx.
+	private autoInstalledBinaryPath: string | null = null;
+	private ensureInFlight: Promise<boolean> | null = null;
 	private log: (msg: string) => void;
 
 	constructor(verbose = false) {
@@ -42,12 +51,22 @@ export class BiomeClient {
 	}
 
 	/**
-	 * Resolve the fastest available biome binary.
+	 * Resolve the fastest available biome binary for `cwd`.
 	 * Prefers local node_modules/.bin/biome (skip npx overhead ~1s).
-	 * Falls back to global biome, then npx.
+	 * Falls back to ~/.pi-lens/tools, then npx.
+	 *
+	 * In monorepos, callers should pass the project / sub-package root for the
+	 * edited file (typically `path.dirname(absolutePath)`). Omitting `cwd`
+	 * falls back to `process.cwd()`, which is wrong when pi is invoked from
+	 * a different directory than the file being edited.
 	 */
-	private getBiomeBinary(): { cmd: string; args: string[] } {
-		if (this.localBinaryPath) return { cmd: this.localBinaryPath, args: [] };
+	private getBiomeBinary(cwd?: string): { cmd: string; args: string[] } {
+		const resolveCwd = cwd ?? process.cwd();
+		const cached = this.localBinaryByCwd.get(resolveCwd);
+		if (cached) return { cmd: cached, args: [] };
+		if (this.autoInstalledBinaryPath) {
+			return { cmd: this.autoInstalledBinaryPath, args: [] };
+		}
 
 		// Walk up from cwd looking for node_modules/.bin/biome.
 		// Also check ~/.pi-lens/tools (where ensureTool("biome") auto-installs),
@@ -64,19 +83,19 @@ export class BiomeClient {
 		);
 		const candidates = isWin
 			? [
-					path.join(process.cwd(), "node_modules", ".bin", "biome.cmd"),
-					path.join(process.cwd(), "node_modules", ".bin", "biome"),
+					path.join(resolveCwd, "node_modules", ".bin", "biome.cmd"),
+					path.join(resolveCwd, "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(resolveCwd, "node_modules", ".bin", "biome"),
+					path.join(resolveCwd, "node_modules", ".bin", "biome.cmd"),
 					path.join(piLensBin, "biome"),
 				];
 		for (const p of candidates) {
 			if (fs.existsSync(p)) {
-				this.localBinaryPath = p;
+				this.localBinaryByCwd.set(resolveCwd, p);
 				return { cmd: p, args: [] };
 			}
 		}
@@ -85,15 +104,20 @@ export class BiomeClient {
 	}
 
 	/**
-	 * Spawn biome with the fastest available binary.
+	 * Spawn biome with the fastest available binary for `cwd`.
+	 * Pass the file's project root in monorepos so the per-package binary wins.
 	 */
-	private spawnBiome(args: string[], timeout = 15000) {
-		const { cmd, args: prefix } = this.getBiomeBinary();
+	private spawnBiome(args: string[], timeout = 15000, cwd?: string) {
+		const { cmd, args: prefix } = this.getBiomeBinary(cwd);
 		return safeSpawn(cmd, [...prefix, ...args], { timeout });
 	}
 
-	private async spawnBiomeAsync(args: string[], timeout = 15000) {
-		const { cmd, args: prefix } = this.getBiomeBinary();
+	private async spawnBiomeAsync(
+		args: string[],
+		timeout = 15000,
+		cwd?: string,
+	) {
+		const { cmd, args: prefix } = this.getBiomeBinary(cwd);
 		return safeSpawnAsync(cmd, [...prefix, ...args], { timeout });
 	}
 
@@ -121,10 +145,25 @@ export class BiomeClient {
 	/**
 	 * Ensure Biome is available, auto-installing if necessary.
 	 * Prefer this over isAvailable() for auto-install behavior.
+	 *
+	 * Re-entrancy safe: concurrent first-time callers share a single
+	 * `ensureInFlight` promise so probing/auto-install isn't duplicated.
+	 * Mirrors the dedupe pattern in `SgRunner` / `KnipClient` /
+	 * `DependencyChecker`.
 	 */
 	async ensureAvailable(): Promise<boolean> {
 		if (this.biomeAvailable !== null) return this.biomeAvailable;
+		if (this.ensureInFlight) return this.ensureInFlight;
+
+		this.ensureInFlight = this.doEnsureAvailable();
+		try {
+			return await this.ensureInFlight;
+		} finally {
+			this.ensureInFlight = null;
+		}
+	}
 
+	private async doEnsureAvailable(): Promise<boolean> {
 		// Check if already available
 		const result = await this.spawnBiomeAsync(["--version"], 10000);
 		if (!result.error && result.status === 0) {
@@ -139,8 +178,9 @@ export class BiomeClient {
 
 		if (installedPath) {
 			this.log(`Biome auto-installed: ${installedPath}`);
-			// Set the installed path as local binary to avoid npx overhead
-			this.localBinaryPath = installedPath;
+			// Set the installed path as the global fallback so every cwd
+			// reaches it after its own per-package lookup misses.
+			this.autoInstalledBinaryPath = installedPath;
 			this.biomeAvailable = true;
 			return true;
 		}
@@ -179,12 +219,16 @@ export class BiomeClient {
 		if (!absolutePath) return [];
 
 		try {
-			const result = this.spawnBiome([
-				"check",
-				"--reporter=json",
-				"--max-diagnostics=50",
-				absolutePath,
-			]);
+			const result = this.spawnBiome(
+				[
+					"check",
+					"--reporter=json",
+					"--max-diagnostics=50",
+					absolutePath,
+				],
+				15000,
+				path.dirname(absolutePath),
+			);
 
 			// Biome exits 0 on success, 1 on issues found
 			const output = result.stdout || "";
@@ -218,7 +262,11 @@ export class BiomeClient {
 		const content = fs.readFileSync(absolutePath, "utf-8");
 
 		try {
-			const result = this.spawnBiome(["format", "--write", absolutePath]);
+			const result = this.spawnBiome(
+				["format", "--write", absolutePath],
+				15000,
+				path.dirname(absolutePath),
+			);
 
 			if (result.error) {
 				return { success: false, changed: false, error: result.error.message };
@@ -266,7 +314,11 @@ export class BiomeClient {
 			// lint --write applies safe lint fixes only — no formatting.
 			// Formatting is deferred to agent_end to avoid mid-turn file modifications
 			// that trigger read-guard "file modified since read" blocks.
-			const result = this.spawnBiome(["lint", "--write", absolutePath]);
+			const result = this.spawnBiome(
+				["lint", "--write", absolutePath],
+				15000,
+				path.dirname(absolutePath),
+			);
 
 			if (result.error) {
 				return {
@@ -325,11 +377,11 @@ export class BiomeClient {
 
 		try {
 			const before = await fs.promises.readFile(absolutePath, "utf-8");
-			const result = await this.spawnBiomeAsync([
-				"lint",
-				"--write",
-				absolutePath,
-			]);
+			const result = await this.spawnBiomeAsync(
+				["lint", "--write", absolutePath],
+				15000,
+				path.dirname(absolutePath),
+			);
 
 			if (result.error) {
 				return {

package/clients/cache/rule-cache.ts

@@ -10,7 +10,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getProjectDataDir } from "../file-utils.js";
 
-const CACHE_VERSION = "v2";
+const CACHE_VERSION = "v3";
 
 export interface QueryCacheEntry {
 	version: string;
@@ -27,6 +27,9 @@ export interface QueryCacheEntry {
 		post_filter?: string;
 		// biome-ignore lint/suspicious/noExplicitAny: Flexible filter params
 		post_filter_params?: Record<string, any>;
+		defect_class?: string;
+		inline_tier?: "blocking" | "warning" | "review";
+		has_fix?: boolean;
 		filePath?: string;
 	}>;
 }

package/clients/cascade-logger.ts

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
+import { isTestMode } from "./env-utils.js";
+import { getGlobalPiLensDir } from "./file-utils.js";
 
-const CASCADE_LOG_DIR = path.join(os.homedir(), ".pi-lens");
+const CASCADE_LOG_DIR = getGlobalPiLensDir();
 const CASCADE_LOG_FILE = path.join(CASCADE_LOG_DIR, "cascade.log");
 
 try {
@@ -63,10 +64,7 @@ export interface CascadeLogEntry {
 }
 
 export function logCascade(entry: CascadeLogEntry): void {
-	if (
-		process.env.PI_LENS_TEST_MODE === "1" ||
-		(process.env.VITEST && process.env.PI_LENS_TEST_MODE !== "0")
-	) {
+	if (isTestMode()) {
 		return;
 	}
 	const line = `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`;

package/clients/cascade-types.ts

@@ -15,3 +15,22 @@ export interface CascadeResult {
 	neighbors: CascadeNeighborResult[];
 	formatted: string;
 }
+
+/** Why a cascade run produced no formatted output. */
+export type CascadeSkipReason =
+	| "blockers"    // primary file had blocking diagnostics
+	| "non_code"    // file kind not eligible for cascade
+	| "no_neighbors" // reverse-dep lookup found no importing files
+	| "clean";      // neighbors found but none had new diagnostics
+
+/**
+ * Always-present result of one computeCascadeForFile invocation.
+ * result is defined only when formatted output was produced.
+ */
+export interface CascadeRun {
+	filePath: string;
+	result: CascadeResult | undefined;
+	neighborCount: number;
+	diagnosticCount: number;
+	skipReason?: CascadeSkipReason;
+}

package/clients/diagnostic-logger.ts

@@ -7,6 +7,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { isTestMode } from "./env-utils.js";
 
 export interface DiagnosticEntry {
 	// When
@@ -108,10 +109,7 @@ export function createDiagnosticLogger(): DiagnosticLogger {
 
 	return {
 		log(entry: DiagnosticEntry) {
-			if (
-				process.env.PI_LENS_TEST_MODE === "1" ||
-				(process.env.VITEST && process.env.PI_LENS_TEST_MODE !== "0")
-			) {
+			if (isTestMode()) {
 				return;
 			}
 			pending.push(entry);