pi-lens 3.8.61 → 3.8.63

package/CHANGELOG.md

@@ -10,6 +10,43 @@ All notable changes to pi-lens will be documented in this file.
 
 ### Fixed
 
+## [3.8.63] - 2026-07-01
+
+### Added
+
+### Changed
+
+- **Consolidated the timeout-race helpers into one shared `clients/deadline-utils.ts` (#366)** — the "race a promise against a timer" pattern had drifted into three near-identical copies (`withTimeout` in the LSP client, `withBudget` in read-expansion, `withinRemaining` in module-report). They're now thin adapters over one `withDeadline` core, which also fixes two latent bugs the copies carried: `withBudget` didn't suppress the loser promise's late rejection (an unhandled rejection when the timer won first), and `withinRemaining` never cleared its timer. Behaviour at every call site is unchanged (covered by the consumer suites); the core's semantics are locked by dedicated tests including an explicit late-rejection-suppression probe.
+
+### Fixed
+
+- **Bounded the remaining unbounded LSP requests — `workspace/symbol`, `textDocument/codeAction`, `workspace/executeCommand` (#365)** — like the pull-diagnostics fix (#364), these were sent via `safeSendRequest` with no `withTimeout` ceiling, so a language server that accepts a request but never replies (alive but hung) would make the `await` never resolve — hanging symbol search (`pilens_symbol_search`), code-action lookups, and server-command execution. `workspace/symbol` and `textDocument/codeAction` now route through the shared `navRequest` helper (its `withTimeout` ceiling + single-file stale-drop), timing out to `[]`. `workspace/executeCommand` — which is mutating and legitimately long-running — gets a separate, generous 30s anti-deadlock backstop (`PI_LENS_LSP_EXECUTE_COMMAND_TIMEOUT_MS`) that returns an honest `executed:false, reason:"…may still be applying server-side"` rather than truncating valid work or pretending it ran; its allowlist-by-advertisement and server-edit-window hardening are preserved. Real (non-timeout) errors still propagate throughout.
+- **Autofix project-snapshot walk no longer freezes the TUI on large repos (#368)** — `snapshotProjectFiles` (the `tool_result` autofix side-effect detection that snapshots the project tree before/after a formatter or fixer runs, to catch files it changed as a side effect) was a fully synchronous `readdirSync`/`statSync` walk bounded only by a 5,000-file cap — a ~130ms event-loop block at the cap (2–4× that under load), stalling keystrokes on large projects while autofix ran. It now walks asynchronously and yields to the event loop every 500 files, so it holds the loop only for a short chunk. The scan cap and directory-exclusion/confinement behavior are unchanged; a cap-scale (~5k-file) event-loop occupancy guard asserts the walk keeps yielding.
+- **Bounded LSP pull-diagnostics request — a hung server can no longer hang `lens_diagnostics` (#349, #364)** — the pull path in `clientWaitForDiagnostics` awaited a `textDocument/diagnostic` request via `safeSendRequest`, which only settles on a reply or a *destroyed* stream. A pull-mode server that is alive but hung (accepts the request, never replies) made that `await` never resolve, hanging the diagnostics wait → the `dispatch_lint` pipeline phase → `flushDebouncedToolResults` → `lens_diagnostics`, forever (and `safeSpawnAsync`'s 30s cap doesn't apply — it's a pipe request, not a spawn). Unlike the navigation/init/shutdown callers, this request had no `withTimeout` ceiling; the `timeoutMs` passed into `clientWaitForDiagnostics` only bounded the push backstop and the pull *retry interval*, never the individual request. The request is now wrapped in the existing `withTimeout` helper, bounded by `min(PULL_REQUEST_TIMEOUT_MS, remaining caller budget)` (env `PI_LENS_LSP_PULL_REQUEST_TIMEOUT_MS`, default 10s, mirroring `NAV_REQUEST_TIMEOUT_MS`). On timeout the request is caught as `unavailable`, which per #240 is not read as clean and falls through to the already-bounded push backstop. Explains the intermittent repro — it only fires for pull-mode servers (rust-analyzer being the classic) stalling mid-analysis. Regression test: a pull server whose `sendRequest` never resolves now resolves within the caller's budget instead of hanging.
+- **POSIX LSP teardown now cleans up the whole process tree, not just the direct child (#362, #363)** — on POSIX, LSP servers launched through wrappers (npm shims, shell/node launchers) could leave descendants alive after pi-lens reset or shut down an LSP service; observed most visibly as `vscode-html-language-server` processes accumulating across long-lived zellij sessions and pressuring memory. LSP servers are now spawned detached into their own process group and teardown signals the group (`process.kill(-pid, ...)`) before falling back to the direct child, bringing POSIX cleanup in line with the existing Windows `taskkill /T` behavior. Windows teardown is unchanged (`taskkill /T` mid-session, handle-only kill for `processExiting`). Guarded by the `pid <= 0` check so a group signal can never degrade into `process.kill(-0)` against pi-lens's own process group.
+
+## [3.8.62] - 2026-06-28
+
+### Added
+
+- **Compact, blue-branded tool-result rendering (refs #345)** — the navigable/structural/diagnostic tools (`module_report`, `read_symbol`, `read_enclosing`, `ast_grep_search`, `ast_grep_replace`, `ast_grep_dump`/`ast_dump`, `ast_grep_outline`, `lsp_navigation`, `lsp_diagnostics`, `lens_diagnostics`) no longer flood the terminal with their full body. Each now defines a `renderResult` that shows a one-line summary by default — in pi-lens **blue characters** (bold blue text on the default tool-shell background) built from the tool's structured `details` (semantic counts/ranges, not blind truncation) — while the **model still receives the untouched full `content`**; the full output is one keystroke away via expand. Errors stay theme-red. The pi host only dumps a tool's `content` verbatim when it defines no `renderResult`, so supplying one decouples the model payload from the terminal view. Coexists with global renderer extensions (pi-tool-display / pi-claude-style-tools), which default to respecting a tool's own renderer. Shared helper `tools/render-compact.ts`, with unit tests; `pi-tui` `Text` routed through the `clients/deps/*` accessor (dep-centralization seam #285/#335).
+- **Cross-file dead-code detection for non-JS/TS languages — Phase 1: Python via vulture (#127)** — Knip gives JS/TS projects project-wide unused exports/files/deps at session-start, but per-file dispatch linters can't catch "this exported symbol is unused anywhere in the project" for other languages. New `DeadCodeClient` interface (`clients/dead-code-client.ts`) parallels Knip's lifecycle (detect → ensureAvailable → analyze, cached at session-start, surfaced as a turn-end advisory), with a Python implementation backed by [`vulture`](https://github.com/jendrikseipp/vulture). Detection gates on a Python marker (`pyproject.toml`/`setup.py`/`requirements.txt`/…) with the same home-dir + VCS-boundary containment as Knip, so a scan launched from a bare cwd can't recurse `$HOME`. **Presence-gated, never auto-installed** — vulture is a pure-Python package with no standalone binary, so auto-installing would mean mutating the user's active Python environment (wrong for uv/poetry/conda/pipx); pi-lens uses it only when already present, probing both the `vulture` script and `python -m vulture` (mirrors `govulncheck`'s no-install gating). Its text output (`path:line: unused <kind> '<name>' (NN% confidence)`) is parsed into the uniform `DeadCodeResult` buckets. The turn-end advisory reads the cached session-start scan (project-wide scans are slow — no per-turn re-scan) and merges across languages for polyglot repos; advisory-only, never a blocker. Telemetry: one NDJSON event per scan to `~/.pi-lens/dead-code.log`. Future phases add Go/Rust/etc. by implementing the interface. Guards: parser unit tests against captured real vulture output + a guarded real-binary integration test.
+
+### Changed
+
+- **Round-2 agent-tool ergonomics (#345): validation, summary tiers, and high-volume caps** — `ast_grep_search` gains `validateOnly` (compile a pattern/rule against a throwaway snippet to distinguish a bad pattern from a real no-match), `maxMatches` (per-call cap, default 50 / max 200; also the pagination step for `skip`), and `groupByFile` (compact one-line-per-file `L<line>:<col>` distribution instead of full match bodies — for high-volume searches; per-match read slices stay in `details.matchLocations`). The pattern/rule validator uses a per-language temp snippet so the throwaway file parses under the requested lang, rejects NUL/oversized inputs before spawning, and treats only line-anchored `error:` stderr as failure (not warnings like "contains ERROR node"). `module_report` gains a `summary` view tier (top-level read handles + `recommendedReads`; heavy callback/usedBy/blast-radius payloads omitted) and section-level `provenance` (`syntax` / `cached-review-graph` / `heuristic` / `none`); the unimplemented `deep` view tier was dropped. Unit tests cover each. (Block-unit selection from the same plan was deliberately deferred — per-language tree-sitter block queries across ~15 grammars are high-risk/low-marginal-value over the existing `read_enclosing onOversize=slice`.)
+- **Agent-tool ergonomics for ast-grep search/debug flows** — `ast_grep_search` results now include `details.matchLocations[]` with ready `readSlice` handles so agents can jump from a structural hit to bounded context without manually computing offsets. Zero-match results now point at `ast_grep_dump` and include a bounded `suggestedDump` hint instead of leaving agents to guess node kinds. Added `ast_grep_dump` as the preferred AST dump tool name while keeping `ast_dump` as a compatibility alias; the ast-grep skill now includes lifecycle/callback search recipes. New `ast_grep_outline` exposes `ast-grep outline` as a syntax-only structure tool (symbols/imports/exports/members for files or directories, with `items`/`view`/`type`/`match`/`pubMembers`/`globs` and ready `read` handles) — fast, local, no index/LSP; `module_report` stays the pi-lens-aware default.
+
+- **`module_report` now surfaces callback/closure handles, with per-language semantics** — reports include a `callbacks[]` section for high-signal inline executable nodes that normal symbol outlines miss: event handlers (`pi.on`/`*.on`), timers, promise callbacks, object/dict function properties, and assigned closures/lambdas/function literals. Each entry has stable synthetic `name`, flags such as `captures ctx.ui` / `detached timer`, and ready `read` args. `read_symbol` now accepts those handles, returns the exact body, and records read-guard coverage just like a named symbol. New `read_enclosing` bridges search/diagnostic line hits to the smallest enclosing symbol/callback body, also with read-guard coverage. `module_report.focus` can optionally rank existing symbols/callbacks in `recommendedReads` without expanding scope, building the graph, or calling LSP. The inline-executable *node kinds* are language-uniform over the tree-sitter WASMs, but the callback *semantics* are per-language via a `CALLBACK_RULES` table keyed like `SYMBOL_QUERIES`: JS/TS-tuned rules are the default, plus language slices for Go (goroutine/`defer` closures), Python (scheduler/future lambdas — `call_later`/`call_soon`/`Timer`/`add_done_callback`), Rust (`spawn` and `move` closures), Swift (strong-vs-`[weak self]` capture — the retain-cycle signal), C++ (`[&]` by-reference capture + `std::thread`/`std::async` launches), Kotlin (coroutine builders — `launch`/`async`/`withContext`/…), Java (`new Thread`, executor `submit`/`execute`/`schedule`, UI/event listeners), and C# (`Task.Run`/`StartNew` + `event += handler` subscriptions) that surface lifecycle callbacks the generic rules previously dropped. The report's `callbackSupport: "tuned" | "generic"` flag tells callers whether language-specific rules applied, so the list isn't over-trusted for untuned languages. (Named-symbol navigation — `module_report` outline, `read_symbol`, `read_enclosing` — already spans all ~19 tree-sitter `SYMBOL_QUERIES` languages.) Each symbol/member entry now also carries `decorators[]` — the declaration's decorators/attributes/annotations in source order (`@app.get("/x")`, `#[tokio::main]`, `@Override`), surfacing a symbol's role (route/test/fixture/entrypoint) without reading its body. Extracted structurally from the declaration node (preceding-sibling / own-child / `modifiers`-nested shapes), spanning Python/Rust/TS/Java/Kotlin/C# including nested method members. Async/suspend functions and methods now carry an `async` flag (structurally detected — `async` keyword node or `async`/`suspend` in a modifiers container), marking concurrency boundaries.
+
+- **Fuller, more correct utilization of knip + madge (tool-utilization audit)** — an audit of our whole-project analyzers (validated by running them on this repo) found gaps and silent-failure modes. (1) **knip** now requests `enumMembers` in `--include` — finer-grained dead code (unused enum members) than file-level exports, advisory-only. *(The audit also caught a bug: knip 6.x has **no `classMembers` issue type** — requesting it makes knip exit 2 with zero output, silently disabling the scan. Verified against knip 6.20.)* (2) **madge** now passes `--ts-config <tsconfig.json>` when one exists, so TypeScript `paths` aliases (`@/foo`) resolve — previously alias-routed imports were silently unresolved and **cycles through an alias were missed**. (3) **madge** `--extensions` gained `mjs,cjs`. (4) **madge** now runs with `--warning` and we parse its stderr for **skipped (unresolvable) files** — previously `--json` mode hid these, so a skipped *local* file could silently drop an internal edge and hide a cycle; local skips are now logged (external package skips are expected and ignored). jscpd was already broad (≈20 languages, unrestricted scan since #126) — no gap there. Guards: knip member-type parse test, `buildMadgeArgs` + `parseMadgeSkips` unit tests.
+- **Turn-end injects only this-turn, high-confidence findings — not the full project-wide warning set** — measured on this repo, the whole-project analyzers emit hundreds of findings (knip 390, jscpd 136 clones in `clients/` alone), most pre-existing and noisy. Injecting that wall every turn would drown the genuine blockers and burn context. So the turn-end knip advisory now surfaces only the **delta attributable to the agent's edits** (symbols in files it just touched that became unused) — low-volume and actionable — instead of the whole project. The full picture remains available on demand via `lens_diagnostics`, and the delta still feeds the session-slop record. (madge already operated in this blockers-only mode.)
+- **Read-guard: every blocking verdict ends with a concrete next-action line (#328)** — an LLM recovers best when each blocking/retryable verdict tells it exactly what to do next. An audit found the read-guard verdicts were *almost* uniform — `read-guard.ts` (zero-read / file-modified / out-of-range / range-stale) and the oldText-not-found path all already end with a recovery instruction — except the `unsupported_hashline_edit_target` block (malformed/unsupported hashline anchors), which listed the errors with no next step. It now ends with a single concrete next-action ("Re-read `<file>` to get current #line anchors, then retry with `set_line` / `replace_lines` — or use a native ranged edit"). Message-only; a guard test asserts the next-action line is present.
+
+### Fixed
+
+- **LSP idle reset no longer touches stale pi contexts after session replacement (#338)** — the detached 240s idle timer now captures any footer repaint callback while the `turn_end` event context is still active, skips resets from superseded session generations, and swallows timer-only cleanup errors so `ctx.newSession()` / `ctx.fork()` / `ctx.switchSession()` / `ctx.reload()` cannot crash later when the old `ctx.ui` getter becomes stale.
+
 ## [3.8.61] - 2026-06-25
 
 ### Added

package/README.md

@@ -4,10 +4,6 @@
 
 # pi-lens
 
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/github/all-contributors/apmantza/pi-lens?color=ee8449&style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
-
 pi-lens gives AI coding agents fast, language-aware feedback while they write/edit.
 
 ## What It Does
@@ -146,6 +142,11 @@ Thanks goes to these wonderful people:
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/JustlyAI"><img src="https://avatars.githubusercontent.com/u/12634140?v=4" width="100px;" alt=""/><br /><sub><b>Laurent Wiesel</b></sub></a><br /><a href="#bug-JustlyAI" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/stark-bit"><img src="https://avatars.githubusercontent.com/u/44064758?v=4" width="100px;" alt=""/><br /><sub><b>Rei Starks</b></sub></a><br /><a href="#bug-stark-bit" title="Bug reports">🐛</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/robertoecf"><img src="https://avatars.githubusercontent.com/u/54923863?v=4" width="100px;" alt=""/><br /><sub><b>Roberto Freitas</b></sub></a><br /><a href="#bug-robertoecf" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/tmttodd"><img src="https://avatars.githubusercontent.com/u/160077416?v=4" width="100px;" alt=""/><br /><sub><b>tmttodd</b></sub></a><br /><a href="#bug-tmttodd" title="Bug reports">🐛</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/smaharnav"><img src="https://avatars.githubusercontent.com/u/263328627?v=4" width="100px;" alt=""/><br /><sub><b>smaharnav</b></sub></a><br /><a href="#bug-smaharnav" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/MzaGuille"><img src="https://avatars.githubusercontent.com/u/151482698?v=4" width="100px;" alt=""/><br /><sub><b>Mza.Guille</b></sub></a><br /><a href="#bug-MzaGuille" title="Bug reports">🐛</a></td>
     </tr>
 </tbody>
 </table>

package/banner.svg

@@ -24,65 +24,73 @@
   <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="155" r="180" fill="none" stroke="#2f81f7" stroke-width="1.5"/>
-    <circle cx="920" cy="155" r="145" fill="none" stroke="#2f81f7" stroke-width="1"/>
-    <circle cx="920" cy="155" r="110" fill="none" stroke="#2f81f7" stroke-width="1"/>
-    <circle cx="920" cy="155" r="75"  fill="none" stroke="#2f81f7" stroke-width="1"/>
-    <line x1="740" y1="155" x2="1100" y2="155" stroke="#2f81f7" stroke-width="0.8"/>
-    <line x1="920" y1="-40"  x2="920"  y2="350"  stroke="#2f81f7" stroke-width="0.8"/>
-    <line x1="793" y1="28"   x2="1047" y2="282"  stroke="#2f81f7" stroke-width="0.6"/>
-    <line x1="1047" y1="28"  x2="793"  y2="282"  stroke="#2f81f7" stroke-width="0.6"/>
+  <g opacity="0.06" clip-path="url(#bounds)">
+    <circle cx="980" cy="100" r="170" fill="none" stroke="#2f81f7" stroke-width="1.5"/>
+    <circle cx="980" cy="100" r="132" fill="none" stroke="#2f81f7" stroke-width="1"/>
+    <circle cx="980" cy="100" r="94"  fill="none" stroke="#2f81f7" stroke-width="1"/>
+    <circle cx="980" cy="100" r="56"  fill="none" stroke="#2f81f7" stroke-width="1"/>
+    <line x1="810" y1="100" x2="1100" y2="100" stroke="#2f81f7" stroke-width="0.8"/>
+    <line x1="980" y1="-70" x2="980"  y2="270"  stroke="#2f81f7" stroke-width="0.8"/>
   </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>
+  <circle cx="118" cy="88" r="56" fill="#2f81f708"/>
+  <circle cx="118" cy="88" r="50" fill="#2f81f710" stroke="url(#accent)" stroke-width="4"/>
+  <circle cx="118" cy="88" r="37" fill="none" stroke="#2f81f740" stroke-width="1.4"/>
+  <line x1="156" y1="126" x2="182" y2="155" stroke="url(#accent)" stroke-width="7" stroke-linecap="round"/>
+  <text x="93" y="98" font-family="'Courier New', Courier, monospace" font-size="27" 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>
+  <text x="208" y="82" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif" font-size="58" 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 — row 1 -->
-  <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>
+  <!-- Languages badge (header) -->
+  <rect x="446" y="44" width="132" height="28" rx="14" fill="#2f81f718" stroke="#2f81f755" stroke-width="1"/>
+  <text x="512" y="63" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif" font-size="13" font-weight="600" fill="#58a6ff" text-anchor="middle">36+ languages</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>
+  <!-- Tagline -->
+  <text x="210" y="116" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif" font-size="19" font-weight="400" fill="#8b949e" letter-spacing="0.3">Real-time code intelligence for AI agents</text>
 
-    <rect x="505" y="196" width="84"  height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
-    <text x="547" y="213" fill="#58a6ff" text-anchor="middle">Auto-Fix</text>
+  <!-- Divider under header -->
+  <rect x="40" y="146" width="1020" height="1" fill="#2f81f730"/>
 
-    <rect x="599" y="196" width="100" height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
-    <text x="649" y="213" fill="#58a6ff" text-anchor="middle">Read-Guard</text>
+  <!-- Column dividers -->
+  <g fill="#2f81f722">
+    <rect x="294" y="170" width="1" height="108"/>
+    <rect x="550" y="170" width="1" height="108"/>
+    <rect x="806" y="170" width="1" height="108"/>
   </g>
 
-  <!-- Feature pills — row 2 -->
-  <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif" font-size="12" font-weight="500">
-    <rect x="261" y="228" width="152" height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
-    <text x="337" y="245" fill="#58a6ff" text-anchor="middle">Structural Analysis</text>
+  <g font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif">
+    <!-- ANALYZE -->
+    <rect x="56" y="176" width="7" height="7" rx="1.5" fill="url(#accent)"/>
+    <text x="72" y="183" font-size="13.5" font-weight="700" fill="#58a6ff" letter-spacing="2">ANALYZE</text>
+    <text x="56" y="200" font-size="11" font-weight="400" fill="#6e7681" letter-spacing="0.2">inline feedback, every write/edit</text>
+    <text x="56" y="225" font-size="14.5" font-weight="400" fill="#c9d1d9">LSP diagnostics</text>
+    <text x="56" y="248" font-size="14.5" font-weight="400" fill="#c9d1d9">Linters &amp; type-checks</text>
+    <text x="56" y="271" font-size="14.5" font-weight="400" fill="#c9d1d9">ast-grep &#183; tree-sitter</text>
 
-    <rect x="423" y="228" width="96"  height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
-    <text x="471" y="245" fill="#58a6ff" text-anchor="middle">Cascade</text>
+    <!-- FIX & GUARD -->
+    <rect x="312" y="176" width="7" height="7" rx="1.5" fill="url(#accent)"/>
+    <text x="328" y="183" font-size="13.5" font-weight="700" fill="#58a6ff" letter-spacing="2">FIX &amp; GUARD</text>
+    <text x="312" y="200" font-size="11" font-weight="400" fill="#6e7681" letter-spacing="0.2">automatic</text>
+    <text x="312" y="225" font-size="14.5" font-weight="400" fill="#c9d1d9">Formatters &amp; auto-fix</text>
+    <text x="312" y="248" font-size="14.5" font-weight="400" fill="#c9d1d9">Read-guard</text>
+    <text x="312" y="271" font-size="14.5" font-weight="400" fill="#c9d1d9">Edit autopatch</text>
 
-    <rect x="529" y="228" width="100" height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
-    <text x="579" y="245" fill="#58a6ff" text-anchor="middle">Tree-sitter</text>
+    <!-- UNDERSTAND -->
+    <rect x="568" y="176" width="7" height="7" rx="1.5" fill="url(#accent)"/>
+    <text x="584" y="183" font-size="13.5" font-weight="700" fill="#58a6ff" letter-spacing="2">UNDERSTAND</text>
+    <text x="568" y="200" font-size="11" font-weight="400" fill="#6e7681" letter-spacing="0.2">review-graph engine</text>
+    <text x="568" y="225" font-size="14.5" font-weight="400" fill="#c9d1d9">Review graph</text>
+    <text x="568" y="248" font-size="14.5" font-weight="400" fill="#c9d1d9">Impact cascade</text>
+    <text x="568" y="271" font-size="14.5" font-weight="400" fill="#c9d1d9">Centrality ranking</text>
 
-    <rect x="639" y="228" width="96"  height="24" rx="12" fill="#2f81f715" stroke="#2f81f740" stroke-width="1"/>
-    <text x="687" y="245" fill="#58a6ff" text-anchor="middle">ast-grep</text>
+    <!-- AGENT TOOLS -->
+    <rect x="824" y="176" width="7" height="7" rx="1.5" fill="url(#accent)"/>
+    <text x="840" y="183" font-size="13.5" font-weight="700" fill="#58a6ff" letter-spacing="2">AGENT TOOLS</text>
+    <text x="824" y="200" font-size="11" font-weight="400" fill="#6e7681" letter-spacing="0.2">on demand</text>
+    <text x="824" y="225" font-size="14.5" font-weight="400" fill="#c9d1d9">Symbol search</text>
+    <text x="824" y="248" font-size="14.5" font-weight="400" fill="#c9d1d9">Module reports</text>
+    <text x="824" y="271" font-size="14.5" font-weight="400" fill="#c9d1d9">AST search &amp; replace</text>
   </g>
 </svg>

package/dist/clients/ast-grep-client.js

@@ -41,6 +41,44 @@ function snippetForRange(source, offsets, startLine0, startCol0, endLine0, endCo
     const text = source.slice(start, end).replace(/\s+/g, " ").trim();
     return text.length > 80 ? `${text.slice(0, 77)}...` : text;
 }
+const MAX_VALIDATE_PATTERN_CHARS = 20_000;
+const MAX_VALIDATE_RULE_CHARS = 200_000;
+const VALIDATION_SNIPPETS = {
+    bash: { ext: "sh", source: "echo pi_lens_validate\n" },
+    c: { ext: "c", source: "int main(void) { return 0; }\n" },
+    cpp: { ext: "cpp", source: "int main() { return 0; }\n" },
+    csharp: { ext: "cs", source: "class C { static void Main() {} }\n" },
+    css: { ext: "css", source: ".pi-lens { color: black; }\n" },
+    go: { ext: "go", source: "package main\nfunc main() {}\n" },
+    html: { ext: "html", source: "<main>pi-lens</main>\n" },
+    java: { ext: "java", source: "class Main { void run() {} }\n" },
+    javascript: { ext: "js", source: "const piLensValidate = 1;\n" },
+    json: { ext: "json", source: "{\"piLensValidate\":true}\n" },
+    kotlin: { ext: "kt", source: "fun main() {}\n" },
+    lua: { ext: "lua", source: "local pi_lens_validate = 1\n" },
+    php: { ext: "php", source: "<?php $piLensValidate = 1;\n" },
+    python: { ext: "py", source: "pi_lens_validate = 1\n" },
+    ruby: { ext: "rb", source: "pi_lens_validate = 1\n" },
+    rust: { ext: "rs", source: "fn main() {}\n" },
+    tsx: { ext: "tsx", source: "export function App() { return <div />; }\n" },
+    typescript: { ext: "ts", source: "const piLensValidate = 1;\n" },
+    yaml: { ext: "yaml", source: "piLensValidate: true\n" },
+};
+function validationSnippetFor(language) {
+    const key = language.toLowerCase().replace(/^"|"$/g, "");
+    return VALIDATION_SNIPPETS[key] ?? { ext: key.replace(/[^a-z0-9_-]/gi, "") || "txt", source: "pi_lens_validate\n" };
+}
+function validateInputShape(value, maxChars, label) {
+    if (value.includes("\0"))
+        return `${label} contains NUL bytes`;
+    if (value.length > maxChars) {
+        return `${label} is too large (${value.length} chars, max ${maxChars})`;
+    }
+    return undefined;
+}
+function stderrHasError(stderr) {
+    return stderr.split(/\r?\n/).some((line) => /^\s*(error|Error):/.test(line));
+}
 function formatDebugAst(tree, source) {
     const offsets = lineStartOffsets(source);
     return tree
@@ -94,16 +132,30 @@ export class AstGrepClient {
                 // Stale-preview check: dry-run first
                 const preCheck = await this.runner.tempScanAsync(scanPath, "agent-rule", ruleYaml);
                 if (preCheck.length === 0) {
-                    return { matches: [], totalMatches: 0, applied: false, stalePreview: true };
+                    return {
+                        matches: [],
+                        totalMatches: 0,
+                        applied: false,
+                        stalePreview: true,
+                    };
                 }
             }
             const result = await this.runner.tempScanWithFixAsync(scanPath, "agent-rule", ruleYaml, apply);
             if (result.error) {
-                return { matches: allMatches, totalMatches: allMatches.length, applied: false, error: result.error };
+                return {
+                    matches: allMatches,
+                    totalMatches: allMatches.length,
+                    applied: false,
+                    error: result.error,
+                };
             }
             allMatches.push(...result.matches);
         }
-        return { matches: allMatches, totalMatches: allMatches.length, applied: apply };
+        return {
+            matches: allMatches,
+            totalMatches: allMatches.length,
+            applied: apply,
+        };
     }
     /**
      * Search using a raw YAML rule (Phase 4 of #125).
@@ -160,6 +212,111 @@ export class AstGrepClient {
             fs.rmSync(tmpDir, { recursive: true, force: true });
         }
     }
+    async validatePattern(pattern, lang, options) {
+        const shapeError = validateInputShape(pattern, MAX_VALIDATE_PATTERN_CHARS, "pattern");
+        if (shapeError)
+            return { valid: false, error: shapeError };
+        const snippet = validationSnippetFor(lang);
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-lens-sg-validate-"));
+        const tmpFile = path.join(tmpDir, `snippet.${snippet.ext}`);
+        try {
+            fs.writeFileSync(tmpFile, snippet.source, "utf-8");
+            const args = ["run", "-p", pattern, "--lang", lang, "--json=compact"];
+            if (options?.selector)
+                args.push("--selector", options.selector);
+            if (options?.strictness)
+                args.push("--strictness", options.strictness);
+            args.push(tmpFile);
+            const result = await this.runner.execRaw(args);
+            const stderr = result.stderr.trim();
+            const stdout = result.stdout.trim();
+            if (result.error)
+                return { valid: false, error: result.error };
+            if (stderrHasError(stderr))
+                return { valid: false, error: stderr };
+            const warning = stderr || stdout || undefined;
+            return {
+                valid: true,
+                ...(warning ? { warning } : {}),
+            };
+        }
+        finally {
+            try {
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort cleanup; never mask the validation result.
+            }
+        }
+    }
+    async validateRule(ruleYaml) {
+        const shapeError = validateInputShape(ruleYaml, MAX_VALIDATE_RULE_CHARS, "rule");
+        if (shapeError)
+            return { valid: false, error: shapeError };
+        const language = /^\s*language:\s*([^\s#]+)/im.exec(ruleYaml)?.[1] ?? "typescript";
+        const snippet = validationSnippetFor(language);
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-lens-sg-rule-"));
+        try {
+            fs.writeFileSync(path.join(tmpDir, `snippet.${snippet.ext}`), snippet.source, "utf-8");
+            await this.runner.tempScanAsync(tmpDir, "agent-rule", ruleYaml, 10000);
+            return { valid: true };
+        }
+        catch (err) {
+            return { valid: false, error: String(err) };
+        }
+        finally {
+            try {
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort cleanup; never mask the validation result.
+            }
+        }
+    }
+    /**
+     * Syntax-only code outline via `ast-grep outline` (#311) — symbols, imports,
+     * exports, and members for file or directory input. Raw, fast, no index/LSP;
+     * complements module_report (which adds the cached graph's who-uses-this,
+     * complexity, and blast radius). Returns parsed JSON; args go through
+     * `execRaw` (execFile-style, no shell), so no interpolation risk.
+     */
+    async outline(paths, options = {}) {
+        if (paths.length === 0)
+            return { error: "no paths provided" };
+        const args = ["outline", "--json=compact", "--color", "never"];
+        if (options.lang)
+            args.push("--lang", options.lang);
+        if (options.items)
+            args.push("--items", options.items);
+        if (options.view)
+            args.push("--view", options.view);
+        if (options.types?.length)
+            args.push("--type", options.types.join(","));
+        if (options.match)
+            args.push("--match", options.match);
+        if (options.pubMembers)
+            args.push("--pub-members");
+        for (const glob of options.globs ?? [])
+            args.push("--globs", glob);
+        args.push(...paths);
+        const result = await this.runner.execRaw(args);
+        const raw = (result.stdout ?? "").trim();
+        if (!raw) {
+            return {
+                error: result.error ||
+                    result.stderr?.trim() ||
+                    "ast-grep outline returned no output",
+            };
+        }
+        try {
+            return { output: JSON.parse(raw) };
+        }
+        catch (err) {
+            return {
+                error: `failed to parse ast-grep outline JSON: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
     /**
      * Search for AST patterns in files
      */

package/dist/clients/ast-grep-tool-logger.js

@@ -102,7 +102,7 @@ export function astGrepRemediationHint(kind) {
         case "json_parse_failed":
             return "Hint: ast-grep produced output that could not be parsed — retry with a simpler pattern; the installed CLI version may be incompatible.";
         default:
-            return "Hint: verify the pattern is a single valid AST node for this `lang` (use ast_dump to discover node kinds), or fall back to grep for plain-text search.";
+            return "Hint: verify the pattern is a single valid AST node for this `lang` (use ast_grep_dump to discover node kinds), or fall back to grep for plain-text search.";
     }
 }
 function rotateIfNeeded() {

package/dist/clients/ast-grep-yaml-synth.js

@@ -13,7 +13,10 @@
  * Multiple constraints are combined directly on the rule object — ast-grep
  * evaluates all of them as an implicit AND.
  */
-import { dump } from "js-yaml";
+import { dump } from "./deps/js-yaml.js";
+const MAX_SYNTHESIZED_PATTERN_CHARS = 4_000;
+const MAX_NODE_KIND_CHARS = 80;
+const NODE_KIND_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
  * Returns true when at least one structural-intent field is present.
  */
@@ -38,24 +41,24 @@ export function synthesizeReplaceRule(intent) {
  * @throws if pattern is empty
  */
 export function synthesizeRule(intent) {
-    if (!intent.pattern.trim()) {
-        throw new Error("pattern is required for YAML synthesis");
-    }
+    assertSafePattern(intent.pattern, "pattern");
     // Canonical language name for the YAML header (ast-grep is case-sensitive here).
     const language = canonicalLanguage(intent.lang);
     const rule = {
         pattern: intent.pattern,
     };
     if (intent.insideKind) {
-        rule.inside = { kind: intent.insideKind, stopBy: "end" };
+        rule.inside = { kind: assertSafeNodeKind(intent.insideKind, "insideKind"), stopBy: "end" };
     }
     if (intent.hasKind) {
-        rule.has = { kind: intent.hasKind };
+        rule.has = { kind: assertSafeNodeKind(intent.hasKind, "hasKind") };
     }
     if (intent.follows) {
+        assertSafePattern(intent.follows, "follows");
         rule.follows = { pattern: intent.follows };
     }
     if (intent.precedes) {
+        assertSafePattern(intent.precedes, "precedes");
         rule.precedes = { pattern: intent.precedes };
     }
     const doc = {
@@ -65,6 +68,27 @@ export function synthesizeRule(intent) {
     };
     return dump(doc, { lineWidth: -1 });
 }
+function assertSafePattern(value, field) {
+    if (!value.trim()) {
+        throw new Error(`${field} is required for YAML synthesis`);
+    }
+    if (value.length > MAX_SYNTHESIZED_PATTERN_CHARS) {
+        throw new Error(`${field} is too long for YAML synthesis`);
+    }
+    if (value.includes("\0")) {
+        throw new Error(`${field} contains a NUL byte`);
+    }
+}
+function assertSafeNodeKind(value, field) {
+    const kind = value.trim();
+    if (kind.length === 0) {
+        throw new Error(`${field} is required for YAML synthesis`);
+    }
+    if (kind.length > MAX_NODE_KIND_CHARS || !NODE_KIND_RE.test(kind)) {
+        throw new Error(`${field} must be a single AST node kind like function_declaration`);
+    }
+    return kind;
+}
 /**
  * Map a user-supplied lang value (e.g. "typescript", "TypeScript") to the
  * capitalisation ast-grep expects in the YAML `language:` field.