pi-lens 3.8.34 → 3.8.36

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [Unreleased]
+
+## [3.8.36] - 2026-05-02
+
+### Changed
+
+- **`agent_end` deferred format notification now lists filenames** — the notification now reads `pi-lens deferred format applied to N file(s): foo.ts, bar.ts` instead of just the count, making it immediately clear which files were reformatted without needing to check logs.
+
+### Added
+
+- **Deferred formatting by default** — files touched by `write` and `edit` are now queued and formatted once at `agent_end` instead of immediately after each edit. This prevents mid-task formatting mutations from invalidating read-guard context and interrupting multi-edit flows. Formatting still runs in real time when `--immediate-format` is passed.
+- **`agent_end` lifecycle handler** — new `clients/runtime-agent-end.ts` drains the deferred format queue at the end of each agent turn, runs the formatter once per file, syncs formatted content to LSP, and emits a concise notification.
+- **`--immediate-format` flag** — opt-in flag to restore the legacy per-edit formatting behavior.
+- **`/lens-health` session timestamp** — output now opens with `Session started: HH:MM (Xh Ym ago)` so all session-scoped counters have clear time context.
+- **`/lens-health` LSP status section** — shows each currently running language server with a `✓`/`✗` connected indicator and workspace root. Makes dead servers immediately visible to the agent without needing to check logs. Also fixes `LSPService.getStatus()` which previously hardcoded `connected: true` instead of calling `isAlive()`.
+- **`/lens-health` cascade summary** — shows session-total cascade runs, diagnostics surfaced, and cold-snapshot touches (the new active-touch fallback for TypeScript neighbors with no snapshot).
+- **`/lens-health` i18n** — localizes status labels with English fallback; es, fr, and pt-BR strings included (PR #45 by @jerryfan).
+- **`/lens-booboo` language gates** — Knip (dead code), Madge (circular deps), and type coverage now skip on non-JS/TS projects. Compiler checks extended with Java (mvn/gradle), C# (dotnet build), Dart, Gleam, Zig, and Elixir alongside the existing TypeScript, Go, Rust, Ruby, and Python checks.
+- **`project-metadata` detects 8 new languages** — Java, Kotlin, C#, Dart, Gleam, Zig, Elixir, and C++ are now detected from their project markers (pom.xml, build.gradle.kts, \*.sln, pubspec.yaml, gleam.toml, build.zig, mix.exs, CMakeLists.txt). All runners and booboo language gates now work correctly for these languages.
+- **4 new formatters** — `google-java-format` (config-gated via `.editorconfig` or `.google-java-format`), `cljfmt` (config-gated via `.cljfmt.edn`), `cmake-format` (config-gated via `.cmake-format`), and `PSScriptAnalyzer` formatter for PowerShell (smart-default when PSScriptAnalyzer module is available).
+- **Startup pre-install defaults for shell, Ruby, Kotlin, TOML** — `shellcheck`, `rubocop`, `ktlint`, and `taplo` are now pre-installed fire-and-forget at session start for matching projects, consistent with the existing pattern for `typescript-language-server`, `biome`, `pyright`, `ruff`, `yamllint`, and `sqlfluff`. No latency impact — all installs are fire-and-forget and no-ops when already cached.
+
+### Fixed
+
+- **Installer race condition** — coalesced the entire `ensureTool()` operation (not just the install phase) to prevent duplicate concurrent "auto-install ensure X: start" probes when multiple tools race to resolve the same binary.
+- **Read-expansion union bug** — tree-sitter read expansion now returns the union of the requested range and the enclosing symbol range, instead of silently dropping originally requested prefix/suffix lines. Fixes false "Edit outside read range" blocks when an agent reads a partial range inside a large symbol.
+- **Startup probe deduplication** — removed broad eager probes for biome, ast-grep, ruff, knip, jscpd, and madge at session start. Replaced with `scheduleDeferredToolProbes()` which only probes tools not already covered by preinstall or startup scans, scoped to the project's actual language profile.
+- **ReDoS-safe compiler output parsers in `/lens-booboo`** — five regex patterns in the compiler checks (Maven, Gradle, .NET, Gleam, Elixir) flagged by SonarCloud as vulnerable to super-linear backtracking (S5852). Fixed: `mvnRe` and `gradleRe` replaced greedy `(.+)$` with `([^\n]+)` and dropped the end anchor; `csRe` replaced lazy `([^[]+?)` with greedy `([^[]+)`; `gleamRe` replaced `(.+?)` with `([^:]+)`; `elixirRe` replaced the multiline regex entirely with a line-by-line parser to eliminate the flagged pattern.
+- **Cascade diagnostics now surface for TypeScript neighbors on cold sessions** — previously cascade silently returned zero diagnostics for TypeScript/Deno neighbors when no passive snapshot existed (i.e. the agent had not yet opened the file). Cold-snapshot neighbors now fall through into the parallel `touchFile` pool with a 1000ms budget (tighter than the 2000ms used for non-jsts neighbors, since the TypeScript server is expected to be warm). Valid snapshots still use the fast read path with no touch. New `coldSnapshot: true` field on `neighbor_touch` log entries tracks these in `cascade.log`.
+
+### Improved
+
+- **`ast-grep` skill clarifies string literal behaviour** — exact string literals in patterns (e.g. `from "./utils"`) work correctly; only metavariables inside string literals (e.g. `from "$PATH"`) are not supported and should use grep instead. Previously the skill incorrectly implied import path matching was unsupported entirely, causing unnecessary grep fallbacks.
+
+## [3.8.35] - 2026-05-02
+
+### Fixed
+
+- **Startup hang for all users fixed (issue #46)** — `igniteWarmFiles` was previously `await`ed unconditionally on the session-start path, causing every session to pay the cost of a full directory walk looking for `lsp.json` (checking 3 config paths at every ancestor up to the filesystem root) before returning. This caused the 20–30s startup delay reported in 3.8.34 regardless of whether `warmFiles` was configured. The `loadLSPConfig` call now runs with `await` at the call site; if `warmFiles` is absent or empty, `igniteWarmFiles` is skipped entirely. When warm files are configured, the per-file LSP `touchFile` loop runs fire-and-forget so it never blocks session completion.
+
 ## [3.8.34] - 2026-05-01
 
 ### Added

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/apmantza/pi-lens/master/banner.svg" alt="pi-lens" width="1100">
+</p>
+
 # pi-lens
 
 pi-lens focuses on real-time inline code feedback for AI agents.
@@ -9,17 +13,25 @@ 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):
 
 1. **Secrets scan** — blocking; aborts the write if credentials are detected
-2. **Auto-format** — 26 language-specific formatters (Biome, Prettier, Ruff, gofmt, rustfmt, and 21 others)
+2. **Auto-format** — deferred to `agent_end` by default; queued files are formatted once after all agent tool calls complete. Use `--immediate-format` for per-edit formatting
 3. **Auto-fix** — safe autofixes from 6 tools (Biome `check --write`, Ruff `check --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
 6. **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`
 
+### Agent End
+
+At `agent_end` (once per user prompt, after all agent tool calls complete):
+
+- **Deferred formatting** — any files queued during the turn are formatted once, synced to LSP, and tracked for read-guard coverage
+- **Summary notification** — concise status: how many files were formatted, which changed, and whether any formatter failed
+
 ### Session Start
 
 At `session_start`, pi-lens:
@@ -80,6 +92,7 @@ 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
@@ -149,44 +162,44 @@ Auto-install behavior depends on gate type:
 - **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 |
-| `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 |
-| `psscriptanalyzer` | PowerShell linting | Manual | — |
+| 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                       |
+| `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                         |
+| `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.
 
@@ -198,7 +211,8 @@ pi
 
 # Optional switches
 pi --no-lsp              # Disable unified LSP diagnostics
-pi --no-autoformat        # Skip auto-formatting
+pi --no-autoformat        # Skip auto-formatting entirely
+pi --immediate-format      # Format immediately after each edit instead of deferring to agent_end
 pi --no-autofix           # Skip auto-fix (Biome, Ruff, ESLint, stylelint, sqlfluff, RuboCop)
 pi --no-tests             # Skip test runner
 pi --no-delta             # Disable delta mode (show all diagnostics, not just new ones)
@@ -232,39 +246,39 @@ Formatting uses a single selected formatter per file: explicit project config wi
 
 Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen in the post-write pipeline rather than through dispatch format-check runners.
 
-| Language | LSP | Dispatch Runners | Formatter |
-|---|---|---|---|
-| JavaScript/TypeScript | ✓ | lsp, ts-lsp, biome-check-json, tree-sitter, ast-grep-napi, type-safety, similarity, fact-rules, eslint, oxlint | biome, prettier |
-| Python | ✓ | lsp, pyright, ruff-lint, tree-sitter, python-slop | 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 | biome, prettier |
-| HTML | ✓ | lsp, htmlhint | 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 | — |
+| Language              | LSP | Dispatch Runners                                                                                               | Formatter           |
+| --------------------- | --- | -------------------------------------------------------------------------------------------------------------- | ------------------- |
+| JavaScript/TypeScript | ✓   | lsp, ts-lsp, biome-check-json, tree-sitter, ast-grep-napi, type-safety, similarity, fact-rules, eslint, oxlint | biome, prettier     |
+| Python                | ✓   | lsp, pyright, ruff-lint, tree-sitter, python-slop                                                              | 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                                                                                                 | biome, prettier     |
+| HTML                  | ✓   | lsp, htmlhint                                                                                                  | 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                                                                                                            | —                   |

package/banner.svg

@@ -0,0 +1,73 @@
+<svg width="1100" height="280" viewBox="0 0 1100 280" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#0d1117"/>
+      <stop offset="100%" stop-color="#161b22"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#2f81f7"/>
+      <stop offset="100%" stop-color="#58a6ff"/>
+    </linearGradient>
+    <linearGradient id="accentFade" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#2f81f7"/>
+      <stop offset="100%" stop-color="#2f81f700"/>
+    </linearGradient>
+    <clipPath id="bounds">
+      <rect width="1100" height="280" rx="12"/>
+    </clipPath>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1100" height="280" fill="url(#bg)" rx="12"/>
+
+  <!-- Top accent line -->
+  <rect x="0" y="0" width="1100" height="3" fill="url(#accent)" rx="1.5" clip-path="url(#bounds)"/>
+
+  <!-- Decorative aperture rings (right side) -->
+  <g opacity="0.07" clip-path="url(#bounds)">
+    <circle cx="920" cy="140" r="180" fill="none" stroke="#2f81f7" stroke-width="1.5"/>
+    <circle cx="920" cy="140" r="145" fill="none" stroke="#2f81f7" stroke-width="1"/>
+    <circle cx="920" cy="140" r="110" fill="none" stroke="#2f81f7" stroke-width="1"/>
+    <circle cx="920" cy="140" r="75"  fill="none" stroke="#2f81f7" stroke-width="1"/>
+    <line x1="740" y1="140" x2="1100" y2="140" stroke="#2f81f7" stroke-width="0.8"/>
+    <line x1="920" y1="-40"  x2="920"  y2="320"  stroke="#2f81f7" stroke-width="0.8"/>
+    <line x1="793" y1="13"   x2="1047" y2="267"  stroke="#2f81f7" stroke-width="0.6"/>
+    <line x1="1047" y1="13"  x2="793"  y2="267"  stroke="#2f81f7" stroke-width="0.6"/>
+  </g>
+
+  <!-- Lens icon -->
+  <!-- Outer ring glow -->
+  <circle cx="142" cy="130" r="70" fill="#2f81f708"/>
+  <!-- Lens circle -->
+  <circle cx="142" cy="130" r="63" fill="#2f81f710" stroke="url(#accent)" stroke-width="4.5"/>
+  <!-- Inner ring -->
+  <circle cx="142" cy="130" r="48" fill="none" stroke="#2f81f740" stroke-width="1.5"/>
+  <!-- Handle -->
+  <line x1="191" y1="179" x2="222" y2="214" stroke="url(#accent)" stroke-width="8" stroke-linecap="round"/>
+  <!-- Code brackets inside lens -->
+  <text x="110" y="145" font-family="'Courier New', Courier, monospace" font-size="34" font-weight="700" fill="#58a6ff">&lt;/&gt;</text>
+
+  <!-- pi-lens wordmark -->
+  <text x="258" y="122" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif" font-size="74" font-weight="700" fill="#e6edf3" letter-spacing="-2">pi-lens</text>
+
+  <!-- Tagline -->
+  <text x="261" y="164" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif" font-size="21" font-weight="400" fill="#8b949e" letter-spacing="0.3">Real-time code intelligence for AI agents</text>
+
+  <!-- Feature pills -->
+  <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif" font-size="12" font-weight="500">
+    <rect x="261" y="196" width="56"  height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
+    <text x="289" y="213" fill="#58a6ff" text-anchor="middle">LSP</text>
+
+    <rect x="327" y="196" width="68"  height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
+    <text x="361" y="213" fill="#58a6ff" text-anchor="middle">Linters</text>
+
+    <rect x="405" y="196" width="90"  height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
+    <text x="450" y="213" fill="#58a6ff" text-anchor="middle">Formatters</text>
+
+    <rect x="505" y="196" width="152" height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
+    <text x="581" y="213" fill="#58a6ff" text-anchor="middle">Structural Analysis</text>
+
+    <rect x="667" y="196" width="96"  height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
+    <text x="715" y="213" fill="#58a6ff" text-anchor="middle">Read-Guard</text>
+  </g>
+</svg>

package/clients/cascade-logger.ts

@@ -49,6 +49,7 @@ export interface CascadeLogEntry {
 	lspServerCount?: number; // number of LSP servers configured for this file type
 	touchedCount?: number;
 	snapshotCount?: number;
+	coldSnapshot?: boolean; // true when touch was triggered because autoPropagate snapshot was missing
 
 	// shared
 	fallbackUsed?: boolean;

package/clients/dispatch/integration.ts

@@ -357,6 +357,13 @@ export function resetDispatchBaselines(): void {
 	neighborTouchCache.clear();
 	primaryFilesThisTurn.clear();
 	cascadeDiagnosticBaselines.clear();
+	cascadeSessionStats = { runs: 0, diagnosticsSurfaced: 0, coldSnapshotTouches: 0 };
+}
+
+let cascadeSessionStats = { runs: 0, diagnosticsSurfaced: 0, coldSnapshotTouches: 0 };
+
+export function getCascadeSessionStats(): { runs: number; diagnosticsSurfaced: number; coldSnapshotTouches: number } {
+	return { ...cascadeSessionStats };
 }
 
 // A5: per-turn neighbor-touch cache keyed by normalized path.
@@ -496,6 +503,7 @@ export async function computeCascadeForFile(
 
 	const neighbors: CascadeResult["neighbors"] = [];
 	let producedLspData = false;
+	let coldSnapshotPaths: string[] = [];
 
 	if (sortedNeighbors.length > 0) {
 		const snapshotPaths = sortedNeighbors.filter(shouldReadCascadeFromSnapshot);
@@ -504,6 +512,10 @@ export async function computeCascadeForFile(
 		);
 
 		// Auto-propagating LSPs (TypeScript/Deno) — read passive snapshot with normalized key.
+		// When the snapshot is valid, use it immediately (no touch needed — server already has
+		// fresh data from auto-propagation). When missing or stale, fall through to the active
+		// touch pool below so we get real diagnostics instead of silently returning zero.
+		coldSnapshotPaths = [];
 		for (const neighborPath of snapshotPaths) {
 			const neighborStart = Date.now();
 			const entry = allDiags.get(normalizeMapKey(neighborPath));
@@ -512,14 +524,30 @@ export async function computeCascadeForFile(
 				: undefined;
 			const snapshotValid =
 				entry != null && Date.now() - entry.ts < CASCADE_TTL_MS;
-			const diags = snapshotValid
-				? convertLspDiagnostics(
-						entry.diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE),
-						neighborPath,
-						{ source: "cascade" },
-					)
-				: [];
-			if (snapshotValid) producedLspData = true;
+
+			if (!snapshotValid) {
+				// No usable snapshot — queue for active touch alongside non-jsts neighbors.
+				logCascade({
+					phase: "neighbor_snapshot",
+					filePath,
+					neighborFile: neighborPath,
+					diagnosticCount: 0,
+					durationMs: Date.now() - neighborStart,
+					autoPropagate: true,
+					snapshotMissing: entry == null,
+					snapshotAgeSec,
+					coldSnapshot: true,
+				});
+				coldSnapshotPaths.push(neighborPath);
+				continue;
+			}
+
+			const diags = convertLspDiagnostics(
+				entry.diags.filter((d) => d.severity === 1).slice(0, MAX_PER_FILE),
+				neighborPath,
+				{ source: "cascade" },
+			);
+			producedLspData = true;
 			const durationMs = Date.now() - neighborStart;
 
 			logCascade({
@@ -529,7 +557,7 @@ export async function computeCascadeForFile(
 				diagnosticCount: diags.length,
 				durationMs,
 				autoPropagate: true,
-				snapshotMissing: entry == null,
+				snapshotMissing: false,
 				snapshotAgeSec,
 			});
 
@@ -542,10 +570,13 @@ export async function computeCascadeForFile(
 			});
 		}
 
-		// non-jsts: fan-out active touches in parallel (A3), single wait per neighbor.
-		// touchFile("none") opens the doc; getDiagnostics waits once for fresh results.
+		// fan-out active touches in parallel (A3):
+		// - non-jsts neighbors (always touched)
+		// - autoPropagate neighbors whose snapshot was missing/stale (coldSnapshotPaths)
+		//   use a tighter 1000ms budget since the server is expected to be warm already.
 		const touchResults = await Promise.allSettled(
-			activePaths.map(async (neighborPath) => {
+			[...activePaths, ...coldSnapshotPaths].map(async (neighborPath) => {
+				const isColdSnapshot = coldSnapshotPaths.includes(neighborPath);
 				const neighborStart = Date.now();
 				const cacheKey = normalizeMapKey(neighborPath);
 
@@ -595,10 +626,13 @@ export async function computeCascadeForFile(
 				const content = await nodeFs.promises.readFile(neighborPath, "utf8");
 				// Open with silent=true (suppresses didChangeWatchedFiles rechecks, C2)
 				// and collect diagnostics from the same touched clients.
+				// Cold-snapshot neighbors (autoPropagate LSP, server warm) use a tighter
+				// 1000ms budget — they should respond quickly; we'd rather return zero
+				// than block cascade for 2s on a slow open.
 				const rawDiags = await lspService.touchFile(neighborPath, content, {
 					diagnostics: "document",
 					collectDiagnostics: true,
-					maxClientWaitMs: 2000,
+					maxClientWaitMs: isColdSnapshot ? 1000 : 2000,
 					silent: true,
 					source: "cascade",
 					clientScope: "all",
@@ -629,6 +663,7 @@ export async function computeCascadeForFile(
 					durationMs,
 					lspTouched: true,
 					lspServerCount: configuredServerCount,
+					coldSnapshot: isColdSnapshot,
 				});
 
 				return {
@@ -641,9 +676,10 @@ export async function computeCascadeForFile(
 			}),
 		);
 
+		const allTouchPaths = [...activePaths, ...coldSnapshotPaths];
 		for (let i = 0; i < touchResults.length; i++) {
 			const result = touchResults[i];
-			const neighborPath = activePaths[i];
+			const neighborPath = allTouchPaths[i];
 			if (result.status === "fulfilled") {
 				if (result.value) neighbors.push(result.value);
 			} else {
@@ -722,6 +758,13 @@ export async function computeCascadeForFile(
 		},
 	});
 
+	cascadeSessionStats.runs += 1;
+	cascadeSessionStats.diagnosticsSurfaced += visibleNeighbors.reduce(
+		(sum, n) => sum + n.diagnostics.length,
+		0,
+	);
+	cascadeSessionStats.coldSnapshotTouches += coldSnapshotPaths.length;
+
 	if (!formatted) return undefined;
 
 	getDiagnosticTracker().trackShown(

package/clients/formatters.ts

@@ -20,6 +20,9 @@ import {
 	hasBiomeConfig,
 	hasBlackConfig,
 	hasClangFormatConfig,
+	hasCljfmtConfig,
+	hasCmakeFormatConfig,
+	hasGoogleJavaFormatConfig,
 	hasNearestPackageJsonDependency,
 	hasNearestPackageJsonField,
 	hasOcamlformatConfig,
@@ -296,6 +299,12 @@ function hasExplicitFormatterConfig(
 			return hasStyluaConfig(cwd);
 		case "ocamlformat":
 			return hasOcamlformatConfig(cwd);
+		case "google-java-format":
+			return hasGoogleJavaFormatConfig(cwd);
+		case "cljfmt":
+			return hasCljfmtConfig(cwd);
+		case "cmake-format":
+			return hasCmakeFormatConfig(cwd);
 		default:
 			return false;
 	}
@@ -737,6 +746,63 @@ export const taploFormatter: FormatterInfo = {
 	},
 };
 
+export const googleJavaFormatFormatter: FormatterInfo = {
+	name: "google-java-format",
+	command: ["google-java-format", "--replace", "$FILE"],
+	extensions: [".java"],
+	async detect(cwd: string) {
+		if ((await which("google-java-format")) === null) return false;
+		return hasGoogleJavaFormatConfig(cwd);
+	},
+};
+
+export const cljfmtFormatter: FormatterInfo = {
+	name: "cljfmt",
+	command: ["cljfmt", "fix", "$FILE"],
+	extensions: [".clj", ".cljc", ".cljs"],
+	async detect(cwd: string) {
+		if ((await which("cljfmt")) === null) return false;
+		return hasCljfmtConfig(cwd);
+	},
+};
+
+export const cmakeFormatFormatter: FormatterInfo = {
+	name: "cmake-format",
+	command: ["cmake-format", "-i", "$FILE"],
+	extensions: [".cmake"],
+	async detect(cwd: string) {
+		if ((await which("cmake-format")) === null) return false;
+		return hasCmakeFormatConfig(cwd);
+	},
+};
+
+export const psscriptanalyzerFormatFormatter: FormatterInfo = {
+	name: "psscriptanalyzer-format",
+	command: ["pwsh", "-Command", "Invoke-Formatter -ScriptDefinition (Get-Content -Raw '$FILE') | Set-Content '$FILE'"],
+	extensions: [".ps1", ".psm1", ".psd1"],
+	async resolveCommand(filePath, _cwd) {
+		const pwsh = (await which("pwsh")) ?? (await which("powershell"));
+		if (!pwsh) return null;
+		return [
+			pwsh,
+			"-NoProfile",
+			"-Command",
+			`$content = Get-Content -Raw '${filePath}'; $formatted = Invoke-Formatter -ScriptDefinition $content; Set-Content -Path '${filePath}' -Value $formatted`,
+		];
+	},
+	async detect(_cwd: string) {
+		const pwsh = (await which("pwsh")) ?? (await which("powershell"));
+		if (!pwsh) return false;
+		// Check PSScriptAnalyzer module is available
+		const result = safeSpawn(pwsh, [
+			"-NoProfile",
+			"-Command",
+			"Get-Module -ListAvailable PSScriptAnalyzer | Select-Object -First 1 -ExpandProperty Name",
+		], { timeout: 5_000 });
+		return (result.stdout ?? "").includes("PSScriptAnalyzer");
+	},
+};
+
 // --- Registry ---
 
 const ALL_FORMATTERS: FormatterInfo[] = [
@@ -767,6 +833,10 @@ const ALL_FORMATTERS: FormatterInfo[] = [
 	standardrbFormatter,
 	gleamFormatter,
 	taploFormatter,
+	googleJavaFormatFormatter,
+	cljfmtFormatter,
+	cmakeFormatFormatter,
+	psscriptanalyzerFormatFormatter,
 ];
 
 // Cache for detection results - stores array of enabled formatter names per cwd+ext