pi-lens 3.8.39 → 3.8.41

package/CHANGELOG.md

@@ -4,6 +4,89 @@ All notable changes to pi-lens will be documented in this file.
 
 ## [Unreleased]
 
+## [3.8.41] - 2026-05-05
+
+### Fixed
+
+- **tree-sitter wasm abort loop and memory leak (fixes #56)** — when the emscripten wasm runtime aborts (OOM or assertion failure on large workspaces), the module-level heap is permanently corrupted. pi-lens was re-invoking the dead runtime on every subsequent file write, printing `Aborted()` to stderr on each query and leaking memory on each retry. Added a module-level `_wasmAborted` flag: the first abort detected in the query catch loop poisons the singleton and prevents any further tree-sitter calls for the session. The runner skips cleanly with `reason: wasm_aborted_fatal` logged to `tree-sitter.log`.
+- **`turn_end` phases now instrumented in latency log** — `handleTurnEnd` previously had no `logLatency` calls; all timing data was buried in plain-text `dbg()` lines in `sessionstart.log`. Added per-phase latency entries for `cascade_merge`, `jscpd`, `knip`, and `madge`, plus a `tool_result` total with `fileCount` and `blockerSections`. This gives a baseline for measuring the cost of future turn_end additions (e.g. LSP re-query).
+- **Cascade ran graph build on non-code files** — markdown, YAML, JSON, and other files without a dispatchable kind were reaching `buildOrUpdateGraph`, causing cold graph builds that took up to 3–4 seconds per write with zero useful output. `computeCascadeForFile` now exits immediately with `cascade_skip / non_code_file` when `detectFileKind` returns `undefined`, consistent with the existing `shouldDispatch` gate used by the lint pipeline.
+
+### Added
+
+- **Per-server LSP diagnostic strategies** — new `clients/lsp/server-strategies.ts` codifies known server behavior (TypeScript, rust-analyzer, pyright, ESLint) so timing decisions are automatic rather than one-size-fits-all. Strategies control first-push seeding, debounce window, pull retry budget, aggregate wait timeout, and whether a server benefits from a semantic second pull pass. Env var overrides (`PI_LENS_LSP_*`) take precedence. Unknown servers get a conservative default.
+- **Result-aware diagnostic racing (`raceToCompletion`)** — new `clients/lsp/aggregation.ts` replaces the simple `Promise.race` + grace window pattern with a result-quality-aware aggregator. The grace window only triggers when at least one client has returned non-empty diagnostics, preventing premature resolution when the fastest client returns empty (e.g., TypeScript's syntactic pass). Document mode uses 0ms grace; full mode keeps the 400ms default.
+- **`seedFirstPush` early-exit for clean files** — `raceToCompletion`'s completion predicate now also fires when a `seedFirstPush` server (TypeScript, ESLint) returns any result, even an empty one. These servers' first push is authoritative — waiting further yields nothing. Cuts clean-file diagnostic latency from ~1000ms to ~450ms in full mode and to near-zero in document mode (cascade neighbor touches).
+
+- **`/lens-toggle` session switch** — added a single command to toggle pi-lens on/off at runtime without restarting pi. When off, write/edit analysis, read-guard, formatting, cascade, turn-end checks, and context injection are paused; running `/lens-toggle` again resumes them. `--no-lens` starts a session in the disabled state. Closes #49.
+- **Experimental Semgrep CLI dispatch integration** — added a config-gated `semgrep` dispatch runner that normalizes Semgrep JSON findings into pi-lens diagnostics. The runner never auto-installs Semgrep and only runs when a local `.semgrep.yml`/`.semgrep.yaml`/`semgrep.yml`/`semgrep.yaml` is discovered or when explicitly configured with `--lens-semgrep --lens-semgrep-config <auto|p/pack|path>` / `/lens-semgrep enable --config <...>`. Dispatch scans pass `--metrics=off`; local rule scans do not require a Semgrep token, while Semgrep AppSec/Pro/managed configs may require `semgrep login` or `SEMGREP_APP_TOKEN`.
+- **`/lens-semgrep` command** — new project command for managing Semgrep dispatch: `status` shows CLI/config/effective state, `init` writes a starter `.semgrep.yml` and enables dispatch, `enable [--config <auto|p/pack|path>]` persists activation in `.pi-lens/semgrep.json`, `disable` persists opt-out, and `clear` removes the pi-lens Semgrep config to return to local-config auto-discovery.
+- **Semgrep severity policy metadata** — Semgrep rules can opt into pi-lens blocking semantics with metadata such as `metadata.pi-lens.semantic: blocking` and `metadata.pi-lens.defect_class: injection`. Otherwise, pi-lens promotes only high-signal Semgrep `ERROR` findings in security defect classes (`injection`, `secrets`, `safety`) to blockers and leaves other findings as warnings.
+- **Experimental terminal dashboard** — `--lens-dashboard` / `PI_LENS_DASHBOARD=1` streams redacted session telemetry to a per-session JSONL file (`~/.pi-lens/dashboard-events/{sessionId}.jsonl`) and opens a live terminal dashboard. The dashboard shows the working folder, detected languages, formatter/linter activity, LSP servers spawned, diagnostics grouped by file with OSC-8 clickable links, and a session-start summary of languages, tools, configs, and autoinstalls. Each session gets its own event file; old files are pruned after 7 days (configurable via `PI_LENS_DASHBOARD_RETENTION_DAYS`). Use `PI_LENS_DASHBOARD_LOG_ONLY=1` to emit JSONL without opening a terminal. The viewer auto-scrolls to the latest content on each render.
+
+### Changed
+
+- **LSP diagnostic pipeline latency optimization** — six targeted refactors reduce per-file diagnostic wait times by 50–900ms depending on the language server: first-push seeding skips the debounce timer for TypeScript and ESLint (~150–200ms saved); adaptive debounce computes remaining wait from `pushDiagnosticTimestamps` (50–140ms saved); per-server aggregate wait times (1000ms for TypeScript, 3000ms for rust-analyzer, 1500ms default); semantic settle pass gated to rust-analyzer only; pull retry budget zeroed for TypeScript/ESLint. Global constants `DIAGNOSTICS_DEBOUNCE_MS`, `PULL_DIAGNOSTICS_RETRY_BUDGET_MS`, and `DIAGNOSTICS_AGGREGATE_WAIT_MS` replaced by per-server strategy values from the new `server-strategies.ts`.
+
+### Fixed
+
+- **Cascade neighbor touch cache ignores `writeSeq` on hit** — the A5 neighbor touch cache checked only `turnSeq` on cache hits, so a neighbor diagnosed at writeSeq=1 was served stale results when a second file write (writeSeq=2) cascaded to the same neighbor in the same turn. Fixed by requiring both `turnSeq` and `writeSeq` to match before using the cached entry.
+- **Cascade fallback neighbors include other primary files** — `appendFallbackNeighbors` (the degraded-LSP path) excluded only the current primary file from the passive diagnostic snapshot sweep, but not other files edited as primary this turn. Those files could appear as cascade neighbors even though their own pipeline run is the authoritative diagnostic source. Fixed by adding a `primaryFilesThisTurn` check consistent with the B10 filter in the main neighbor path.
+
+- **Semgrep dispatch plan regression** — kept the experimental Semgrep runner out of static `TOOL_PLANS` exposure and appends it only at runtime when Semgrep is actually configured. Fixes CI regressions in plan-shape tests while preserving config-gated Semgrep dispatch.
+- **Widget theme method binding crash** — `renderWidget` now calls `theme.fg(...)` directly instead of destructuring `fg`, preserving the `this` binding required by pi's `Theme` class. Fixes the `Cannot read properties of undefined (reading 'fgColors')` widget render crash. Closes #53.
+- **Read-guard follow-up edits after own writes** — tuned `file_modified` handling so a file changed by the agent's own prior allowed edit, immediate format, autofix, or deferred `agent_end` formatting does not force a redundant re-read when the next edit is still within already-read ranges. The guard still blocks zero-read and out-of-range edits, and external/stale changes outside the own-edit grace window remain protected. `PI_LENS_READ_GUARD_OWN_EDIT_GRACE_MS` controls the default 120s grace window.
+- **Read-guard log noise and growth** — `~/.pi-lens/read-guard.log` now defaults to block/warn/anomaly events instead of logging every read and allowed edit. Verbose logging is available with `PI_LENS_READ_GUARD_VERBOSE=1` or `PI_LENS_READ_GUARD_LOG=verbose`; allowed-edit logging can be restored with `PI_LENS_READ_GUARD_LOG_ALLOWS=1`. The log now rotates at 1MB by default (`PI_LENS_READ_GUARD_MAX_BYTES`).
+- **Pipelines skipped for external and vendor files** — agents reading dependency source (global npm packages, project-local `node_modules`) previously triggered LSP server spawns, tree-sitter read-range expansion, read-guard recording, and complexity baseline capture on those files — all noise with no diagnostic value. Added `isExternalOrVendorFile()` (built on the existing `isUnderDir` helper for correct Windows case handling) and gated all five pipeline paths: LSP auto-touch, tree-sitter expansion, read-guard recording, complexity baseline, and the full dispatch pipeline on write/edit.
+- **Security: absolute paths for `cmd.exe` and `osascript` spawn calls** — dashboard terminal launch now resolves both executables via `process.env.SystemRoot` / absolute macOS path instead of relying on `PATH`, eliminating the SonarCloud S4036 PATH-injection finding.
+- **Security: installed binary permissions tightened** — `chmod` calls on downloaded tool binaries changed from `0o755` to `0o750`, removing world-execute permission (SonarCloud S2612). GitHub Actions `contents: write` permission moved from workflow level to the `release` job only (S8233).
+- **Agent messages: full-file-read options removed** — read-guard block messages no longer offer "read the full file" as an alternative. The out-of-range block now presents only the pre-computed targeted `offset`/`limit`; the zero-read block gives a single imperative directive. "Re-read the file" fallback text in ambiguous-edit messages replaced with "Re-read the relevant section" throughout.
+- **Agent messages: indentation-mismatch RETRYABLE made explicitly directive** — the block now opens with "Retry the same edit call immediately with the corrected oldText shown below — copy it exactly as-is" and labels each corrected entry with "do not shorten, do not change newText", preventing agents from improvising instead of copying the corrected text verbatim.
+- **SonarCloud reliability fixes** — five `.sort()` calls on string arrays given explicit `localeCompare` comparators (S2871); three identical-branch conditionals collapsed (S3923 in `knip-client.ts`, `shellcheck.ts`, `production-readiness.ts`); emoji character class converted to alternation to handle multi-codepoint variation-selector emojis (S5868); regex alternation precedence made explicit with non-capturing groups (S5850); `| 0` in hash function annotated as intentional 32-bit truncation (S7767).
+- **CI: build step added before tests** — Vitest's native ESM resolver requires compiled `.js` output when `vi.resetModules()` is used; without a prior `tsc` build, imports of newly-added exports resolved as `undefined` in CI.
+- **Widget: diagnostic rows exceeded terminal width** — the custom `truncate()` helper stripped ANSI sequences to measure length but sliced the raw string, losing OSC-8 hyperlinks and SGR sequences from the count. Replaced with pi-tui's `truncateToWidth()` / `visibleWidth()` which correctly account for all escape sequences. All widget lines (header, file rows, separators, diagnostic detail, LSP status) are now clamped. Closes #54.
+- **Widget: file list capped at 5 entries, basename deduplication** — reduced max file rows from 6 to 5 to keep the widget compact. Added basename deduplication (last write wins) so that different files with the same name (e.g. `pi-lens/index.ts` and `pi-webaio/index.ts`) show as a single merged entry instead of flooding the widget with near-identical labels.
+
+## [3.8.40] - 2026-05-04
+
+### Added
+
+- **60+ SonarCloud BLOCKER tree-sitter rules** — comprehensive BLOCKER severity rules across 13 languages:
+  - **Java (11 rules)**: no-exit-methods, no-threads-in-constructors, switch-fall-through, no-wait-notify-on-thread, no-double-checked-locking, no-future-keywords, no-field-shadowing, junit-call-super, no-octal-values, short-circuit-logic, infinite-loop, infinite-recursion, name-capitalization-conflict, mockito-initialized, resources-closed, unnecessary-bit-ops-java
+  - **TypeScript (5 rules)**: infinite-loop, self-assignment, duplicate-function-arg, empty-switch-case, default-not-last, switch-case-termination
+  - **JavaScript (1 rule)**: switch-case-termination-js (replaces switch-fall-through-js)
+  - **PL/SQL (7 rules)**: forallsave-exceptions, not-null-initialization, end-loop-semicolon, raise-application-error-codes, no-synchronize, lock-table, nchar-nvarchar2-bytes, delete-update-where, fetch-bulk-collect-limit
+  - **Python (8 rules)**: send-file-mimetype, no-super-torchscript, return-in-init, yield-return-outside-function, notimplemented-boolean-context, exit-signature-check, return-in-generator, iter-return-iterator, in-operator-unsupported
+  - **C++ (5 rules)**: unnecessary-bit-ops, noexcept-functions, no-auto-ptr, no-memset-sensitive-data, no-scoped-lock-without-args, no-confused-move-forward
+  - **PHP (2 rules)**: this-in-static-context, no-exit-die
+  - **C (3 rules)**: case-range-multiple-values, goto-label-order, goto-into-block
+  - **C# (5 rules)**: is-with-this, no-operator-eq-reference, no-dangerous-get-handle, no-thread-resume-suspend, async-await-identifiers
+  - **Kotlin (1 rule)**: prepared-statement-indices
+  - **ABAP (1 rule)**: delete-where
+  - **COBOL (2 rules)**: alter-statement, lock-table-cobol
+  - **CSS (1 rule)**: calc-spacing
+- **rule-catalog.json** updated with all 60+ new rule registrations
+
+### Fixed
+
+- **Read-guard: false `file_modified` blocks after own edits** — `ReadGuard` was blocking the second edit to a file because the model's first write changed the file's mtime, making `FileTime.hasChanged()` return `true` on the next `checkEdit`. Added `recordWritten(filePath)` to `ReadGuard` and wired it into the `tool_result` handler (post-write, file already on disk), so the FileTime stamp stays in sync with the model's own writes. Eliminates the spurious `file_modified` blocks that appeared on every multi-edit file in a session.
+
+- **LSP: parallel-turn root-resolution timeouts** — `NearestRoot` performed a fresh `fs.stat` directory walk on every call with no caching. When Claude Code edited multiple files simultaneously (e.g. a 4-file turn), all pipelines raced `NearestRoot` concurrently, saturating Windows filesystem I/O and triggering the 750ms `lsp_client_wait_timeout` on all but the first. `NearestRoot` now maintains per-instance result and in-flight caches keyed by resolved directory: successful roots are cached for the session lifetime; concurrent calls for the same directory share one walk promise. Only successful roots are cached so a `package.json` created mid-session is still detected on the next call.
+
+- **Memory: `lastAnalyzedStateByFile` cleared each turn** — module-level Map in `runtime-tool-result.ts` accumulated dead entries across turns (entries from previous turns can never match the new `turnIndex`). Now cleared at `turn_start` alongside `runtime.beginTurn()`, keeping the map bounded to files touched in the current turn only. (refs #50)
+- **Memory: `recentTouches` stale entry eviction** — `LSPService.recentTouches` grew unboundedly across a session with one entry per unique file path. Entries older than `TOUCH_DEBOUNCE_MS` are already ignored by `shouldSkipTouch`; a threshold-based sweep (triggered when size > 200) now removes them. (refs #50)
+- **Memory: orphaned LSP child processes on Windows** — `clientShutdown` only called `process.kill()` which on Windows terminates the direct child but leaves grandchildren (e.g. `tsserver.js`) as orphaned OS processes each holding 300–600MB. Both the normal shutdown and crash paths now go through a shared `killProcessTree` helper: on Windows it runs `taskkill /F /T` via absolute `SystemRoot` path and awaits completion before returning; on other platforms it sends `SIGTERM`. The SIGKILL fallback timer is also skipped on Windows since `taskkill /F` already force-terminates. (refs #50)
+- **Memory: file-time session state not cleared on session reset** — `clearAllSessions()` from `file-time.ts` is now called during `handleSessionStart`, clearing stale file timestamp state that previously accumulated across session switches. (refs #50)
+- **Memory: pending ast-grep warn timers not cancelled on session reset** — `resetDispatchBaselines()` left active `astGrepWarnDebounceTimers` running into a cleared session context. Now explicitly cancelled and cleared on reset. (refs #50)
+- **Security: `taskkill` spawned via absolute path** — both the normal shutdown and crash paths now resolve `taskkill.exe` through `process.env.SystemRoot` instead of relying on PATH, eliminating the SonarCloud PATH-injection hotspot.
+- **LSP: shutdown cannot hang indefinitely** — `client.shutdown()` now bounds the graceful `shutdown` request and proceeds to `exit`/process-tree kill if a server stops responding.
+- **LSP: test cleanup stop helper hardened on Windows** — `stopLSP()` now uses the absolute `taskkill.exe` path, handles already-exited processes, and avoids orphaning grandchildren by killing the process tree before the direct child on Windows.
+
+- **booboo project root detection** — `resolveProjectRoot` now walks up to the nearest ancestor with a root marker (`package.json`, `tsconfig.json`, `.git`, etc.), then falls back to walking down one level if exactly one immediate subdirectory has a root marker. Fixes scans running against the wrong directory in nested-project layouts (e.g. `pi-models/pi-models/`).
+
+- **Switch-case false positives eliminated** — replaced naive `switch-fall-through` rules with `switch-case-termination` rules that properly recognize `return`, `throw`, and `continue` as valid case terminators. Reduced false positive hits from 174 to 0.
+- **Self-assignment false positives fixed** — changed from `post_filter: same_identifier` to inline `#eq?` predicate so `wave = nextWave` is no longer flagged as self-assignment
+
 ## [3.8.39] - 2026-05-02
 
 ### Fixed
@@ -12,6 +95,7 @@ All notable changes to pi-lens will be documented in this file.
 - **jscpd no longer runs on YAML/JSON/Markdown files** — `getFilesForJscpd` now filters to source code extensions only, preventing multi-second delays at `turn_end` when editing rule YAMLs or config files.
 - **ReDoS S5852 final (gleam/zig parsers)** — rewrote `gleamRe` and `zigRe` as line-by-line parsers, eliminating the multiline flag that SonarCloud continued to flag despite `[ \t]*` substitution.
 - **SonarCloud MAJOR code smells (batch 1 & 2)** — `readonly` members, `void` operator removals, nested ternaries, nested template literals, optional chains, duplicate branches, and redundant type alias across 15+ files.
+- **Type-narrow `severityMap` for `Diagnostic.severity` union** — properly satisfies the union type for diagnostic severity mapping.
 - **9 tree-sitter query bugs in new rule files** — predicate outside outermost parens (`cpp/no-auto-ptr`); false-positive `post_filter` gate added (`cpp/no-confused-move-forward`); leaf-node child match removed (`php/this-in-static-context`); invalid node name `class_hereditary` replaced (`java/no-field-shadowing`); field order corrected (`java/no-wait-notify-on-thread`); duplicate `modifiers` blocks merged (`java/spring-session-attributes-setcomplete`); invalid anonymous-node field label removed (`csharp/is-with-this`); inline alternation replaced with two patterns (`python/in-operator-unsupported`); adjacent sibling requirement removed, delegated to `post_filter` (`python/return-in-generator`).
 
 ## [3.8.38] - 2026-05-02
@@ -1133,7 +1217,6 @@ All runtime-applicable TypeScript ast-grep rules now have JavaScript equivalents
 - **Rust performance core (`pi-lens-core`)** — Optional Rust binary for CPU-intensive operations.
   All features fall back to TypeScript automatically if the binary is not available (it is **not**
   built automatically on `npm install` — run `npm run rust:build` once if you have Rust installed).
-
   - **File scanning** — ripgrep’s `ignore` crate for `.gitignore`-aware project scanning
   - **Similarity detection** — parallel 57×72 state-matrix index, persisted to
     `.pi-lens/rust-index.json` between invocations (fixes in-memory cache that reset on every
@@ -1187,7 +1270,6 @@ All runtime-applicable TypeScript ast-grep rules now have JavaScript equivalents
   - Removed `clients/interviewer-templates.ts` (240 lines)
   - Removed initialization from `index.ts`
 - **Deleted deprecated commands** — All were superseded by `/lens-booboo`:
-
   - `/lens-booboo-fix` command (fix-from-booboo.ts, 430 lines) — showed warning to use `/lens-booboo`
   - `/lens-fix-simplified` command (fix-simplified.ts, 770 lines) — never registered, unused
   - `/lens-rate` command (rate.ts, 340 lines) — showed warning to use `/lens-booboo`
@@ -1206,7 +1288,6 @@ All runtime-applicable TypeScript ast-grep rules now have JavaScript equivalents
   - Broken runner tests (7 files) — thin CLI wrappers with wrong imports
   - Trivial utility tests (5 files) — file extension parsing, string sanitization
 - **Added meaningful integration tests**:
-
   - `tests/clients/dispatch/dispatcher-flow.test.ts` — Runner registration, execution, delta mode, conditional runners
   - `tests/extension-hooks.test.ts` — pi API: tool/command/flag registration, event handlers
   - `tests/mocks/runner-factory.ts` — Mock runners for testing without real CLI tools
@@ -1542,7 +1623,6 @@ Migrated 20 critical security rules to NAPI (fast native execution):
 Three new lint runners with full test coverage:
 
 - **Spellcheck runner** (`clients/dispatch/runners/spellcheck.ts`): Markdown spellchecking
-
   - Uses `typos-cli` (Rust-based, fast, low false positives)
   - Checks `.md` and `.mdx` files
   - Priority 30, runs after code quality checks
@@ -1550,7 +1630,6 @@ Three new lint runners with full test coverage:
   - Install: `cargo install typos-cli`
 
 - **Oxlint runner** (`clients/dispatch/runners/oxlint.ts`): Fast JS/TS linting
-
   - Uses `oxlint` from Oxc project (Rust-based, ~100x faster than ESLint)
   - Zero-config by default
   - JSON output with fix suggestions

package/README.md

@@ -16,7 +16,7 @@ On every `write` and `edit`, pi-lens runs a fast, language-aware pipeline (check
 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
+5. **Dispatch lint** — parallel runner groups: LSP diagnostics, tree-sitter structural rules, ast-grep security/correctness rules, fact rules, language-specific linters, experimental Semgrep security scans, similarity detection
 6. **Cascade diagnostics** — review-graph impact cascade showing which other files were affected and how diagnostics propagated
 
 Results are inline and actionable:
@@ -153,6 +153,36 @@ Structural rules are organized by language in `rules/tree-sitter-queries/`:
 - **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
 
+### Semgrep CLI Integration (Experimental)
+
+pi-lens can run the locally installed `semgrep` CLI as an optional dispatch runner for security-focused findings. Semgrep diagnostics are normalized into the same pi-lens `Diagnostic` model as LSP, tree-sitter, ast-grep, and linters: high-signal security findings can become blocking, while other findings remain warnings for `/lens-booboo`/history.
+
+Activation is intentionally gated:
+
+- pi-lens **does not auto-install Semgrep**.
+- A local `.semgrep.yml`, `.semgrep.yaml`, `semgrep.yml`, or `semgrep.yaml` enables the runner when the `semgrep` CLI is available.
+- Without a local config, Semgrep stays skipped unless explicitly configured with `--lens-semgrep --lens-semgrep-config <auto|p/pack|path>` or `/lens-semgrep enable --config <auto|p/pack|path>`.
+- Local `.semgrep.yml` scans do not require a Semgrep token. Semgrep AppSec/Pro/managed configurations may require `semgrep login` or `SEMGREP_APP_TOKEN`.
+- pi-lens passes `--metrics=off` for dispatch scans.
+
+Commands:
+
+- `/lens-semgrep status` — show CLI availability, discovered local config, persisted pi-lens config, and effective dispatch state
+- `/lens-semgrep init` — create a starter `.semgrep.yml` with a blocking `eval(...)` rule and enable Semgrep dispatch
+- `/lens-semgrep enable [--config <auto|p/pack|path>]` — persist Semgrep dispatch activation in `.pi-lens/semgrep.json`
+- `/lens-semgrep disable` — persistently disable Semgrep dispatch for this project
+- `/lens-semgrep clear` — remove `.pi-lens/semgrep.json` and return to local-config auto-discovery
+
+Local rules can opt into pi-lens blocking semantics with metadata:
+
+```yaml
+metadata:
+  pi-lens:
+    semantic: blocking
+    defect_class: injection
+    confidence: high
+```
+
 ## Dependencies
 
 Auto-install behavior depends on gate type:
@@ -199,6 +229,7 @@ Auto-install behavior depends on gate type:
 | `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.
@@ -210,6 +241,7 @@ Additional language servers (gopls, ruby-lsp, solargraph, etc.) are auto-detecte
 pi
 
 # Optional switches
+pi --no-lens             # Start pi-lens disabled for this session; /lens-toggle can re-enable
 pi --no-lsp              # Disable unified LSP diagnostics
 pi --no-autoformat        # Skip auto-formatting entirely
 pi --immediate-format      # Format immediately after each edit instead of deferring to agent_end
@@ -217,6 +249,8 @@ pi --no-autofix           # Skip auto-fix (Biome, Ruff, ESLint, stylelint, sqlfl
 pi --no-tests             # Skip test runner
 pi --no-delta             # Disable delta mode (show all diagnostics, not just new ones)
 pi --lens-guard           # Block git commit/push when unresolved blockers exist (experimental)
+pi --lens-semgrep         # Enable Semgrep dispatch when a local/configured Semgrep config exists
+pi --lens-semgrep-config p/ci  # Explicit Semgrep config for dispatch (requires --lens-semgrep)
 ```
 
 ## Environment Variables
@@ -233,10 +267,12 @@ pi --lens-guard           # Block git commit/push when unresolved blockers exist
 
 ## Key Commands
 
+- `/lens-toggle` — toggle pi-lens on/off for the current session without restarting
 - `/lens-booboo` — full quality report for current project state
 - `/lens-health` — runtime health, latency, and diagnostic telemetry
 - `/lens-tools` — tool installation status: globally installed, auto-installed, or npx fallback
 - `/lens-tdi` — Technical Debt Index (TDI) and project health trend
+- `/lens-semgrep` — manage experimental Semgrep dispatch (`status`, `init`, `enable`, `disable`, `clear`)
 
 ## Language Coverage
 

package/clients/biome-client.ts

@@ -263,9 +263,10 @@ export class BiomeClient {
 		const content = fs.readFileSync(absolutePath, "utf-8");
 
 		try {
-			// Single invocation: check --write applies safe formatting + lint fixes.
-			// No pre-flight checkFile() needed — content diff tells us if anything changed.
-			const result = this.spawnBiome(["check", "--write", absolutePath]);
+			// 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]);
 
 			if (result.error) {
 				return {
@@ -325,7 +326,7 @@ export class BiomeClient {
 		try {
 			const before = await fs.promises.readFile(absolutePath, "utf-8");
 			const result = await this.spawnBiomeAsync([
-				"check",
+				"lint",
 				"--write",
 				absolutePath,
 			]);

package/clients/cache/rule-cache.ts

@@ -50,7 +50,7 @@ export class RuleCache {
 
 	private computeRuleHash(ruleFiles: string[]): string {
 		const hash = crypto.createHash("sha256");
-		for (const file of ruleFiles.sort()) {
+		for (const file of ruleFiles.sort((a, b) => a.localeCompare(b))) {
 			if (fs.existsSync(file)) {
 				const stat = fs.statSync(file);
 				hash.update(`${file}:${stat.mtimeMs}:${stat.size}`);

package/clients/complexity-client.ts

@@ -386,7 +386,7 @@ export class ComplexityClient {
 		let count = 0;
 
 		const aiPatterns = [
-			/[🔍✅📝🔧🐛⚠️🚀💡🎯📌🏷️🔑🏗️🧪🗑️🔄♻️📋🔖📊💬🔥💎⭐🌟🎯🎨🔧🛠️]/u,
+			/(?:🔍|✅|📝|🔧|🐛|⚠️|🚀|💡|🎯|📌|🏷️|🔑|🏗️|🧪|🗑️|🔄|♻️|📋|🔖|📊|💬|🔥|💎|⭐|🌟|🎨|🛠️)/u,
 			/\/\/\s*(Initialize|Setup|Clean up|Create|Define|Check if|Handle|Process|Validate|Return|Get|Set|Add|Remove|Update|Fetch)\b/i,
 			/\/\/\s*(This function|This method|This code|Here we|Now we)\b/i,
 			/\/\*\*?\s*(Overview|Summary|Description|Example|Usage)\s*\*?\//i,

package/clients/dependency-checker.ts

@@ -408,7 +408,7 @@ export class DependencyChecker {
 		let output = `[Circular Deps] ${circular.length} cycle(s) found:\n`;
 
 		for (const dep of circular) {
-			const cycleKey = dep.path.sort().join("→");
+			const cycleKey = dep.path.sort((a, b) => a.localeCompare(b)).join("→");
 			if (seen.has(cycleKey)) continue;
 			seen.add(cycleKey);
 

package/clients/dispatch/diagnostic-taxonomy.ts

@@ -12,6 +12,9 @@ const SILENT_ERROR_HINTS = [
 
 const INJECTION_HINTS = [
 	"sql-injection",
+	"command-injection",
+	"template-injection",
+	"xss",
 	"eval",
 	"exec",
 	"inner-html",
@@ -56,7 +59,16 @@ export function classifyDefect(
 		return "correctness";
 	}
 
-	if (text.includes("unsafe") || text.includes("security")) return "safety";
+	if (
+		text.includes("unsafe") ||
+		text.includes("security") ||
+		text.includes("ssrf") ||
+		text.includes("path-traversal") ||
+		text.includes("deserial") ||
+		text.includes("auth-bypass") ||
+		text.includes("crypto")
+	)
+		return "safety";
 	if (text.includes("style") || text.includes("format")) return "style";
 
 	return "unknown";

package/clients/dispatch/dispatcher.ts

@@ -16,6 +16,7 @@
 
 import * as path from "node:path";
 import type { FileKind } from "../file-kinds.js";
+import { recordRunner } from "../widget-state.js";
 import { detectFileKind } from "../file-kinds.js";
 import { isTestFile } from "../file-utils.js";
 import { getPrimaryDispatchGroup } from "../language-policy.js";
@@ -389,6 +390,7 @@ function buildCoverageNotice(
 		"similarity",
 		"spellcheck",
 		"fact-rules",
+		"semgrep",
 	]);
 	const anyLinterHasCoverage = runnerLatencies.some(
 		(r) =>
@@ -597,6 +599,13 @@ async function runGroup(
 			diagnosticCount: result.diagnostics.length,
 			semantic: result.semantic ?? semantic,
 		});
+		recordRunner(
+			ctx.filePath,
+			runnerId,
+			result.status,
+			result.diagnostics.length,
+			duration,
+		);
 
 		diagnostics.push(...result.diagnostics);
 

package/clients/dispatch/fact-scheduler.ts

@@ -69,7 +69,7 @@ export function scheduleProviders(providers: FactProvider[]): FactProvider[] {
     const cycleParticipants = providers
       .filter((p) => !result.includes(p))
       .map((p) => p.id)
-      .sort();
+      .sort((a, b) => a.localeCompare(b));
     throw new Error(
       `Cycle detected among FactProviders: ${cycleParticipants.join(", ")}`,
     );

package/clients/dispatch/integration.ts

@@ -16,6 +16,7 @@ import {
 	formatSlopScoreSummary,
 	type SlopScoreSummary,
 } from "../session-summary.js";
+import { resolveSemgrepConfig } from "../semgrep-config.js";
 import {
 	clearCoverageNoticeState,
 	clearLatencyReports,
@@ -290,6 +291,52 @@ export function getDispatchSlopScoreLine(): string {
 	return formatSlopScoreSummary(summary);
 }
 
+const SEMGREP_SUPPORTED_KINDS = new Set<FileKind>([
+	"csharp",
+	"css",
+	"cxx",
+	"dart",
+	"docker",
+	"go",
+	"html",
+	"java",
+	"json",
+	"jsts",
+	"kotlin",
+	"lua",
+	"php",
+	"python",
+	"ruby",
+	"rust",
+	"shell",
+	"swift",
+	"terraform",
+	"yaml",
+]);
+
+function withSemgrepGroup(
+	kind: FileKind,
+	groups: RunnerGroup[],
+	ctx: ReturnType<typeof createDispatchContext>,
+): RunnerGroup[] {
+	if (!SEMGREP_SUPPORTED_KINDS.has(kind)) return groups;
+	const config = resolveSemgrepConfig(ctx.cwd, {
+		enabled: Boolean(ctx.pi.getFlag("lens-semgrep")),
+		config: ctx.pi.getFlag("lens-semgrep-config"),
+	});
+	if (!config.enabled) return groups;
+	if (groups.some((group) => group.runnerIds.includes("semgrep"))) return groups;
+	return [
+		...groups,
+		{
+			mode: "all",
+			runnerIds: ["semgrep"],
+			filterKinds: [kind],
+			semantic: "warning",
+		},
+	];
+}
+
 function withPrimaryPolicyGroup(
 	kind: keyof typeof TOOL_PLANS,
 	groups: RunnerGroup[],
@@ -358,6 +405,8 @@ export function resetDispatchBaselines(): void {
 	primaryFilesThisTurn.clear();
 	cascadeDiagnosticBaselines.clear();
 	cascadeSessionStats = { runs: 0, diagnosticsSurfaced: 0, coldSnapshotTouches: 0 };
+	for (const timer of astGrepWarnDebounceTimers.values()) clearTimeout(timer);
+	astGrepWarnDebounceTimers.clear();
 }
 
 let cascadeSessionStats = { runs: 0, diagnosticsSurfaced: 0, coldSnapshotTouches: 0 };
@@ -428,6 +477,11 @@ export async function computeCascadeForFile(
 		return undefined;
 	}
 
+	if (!detectFileKind(filePath)) {
+		logCascade({ phase: "cascade_skip", filePath, reason: "non_code_file" });
+		return undefined;
+	}
+
 	const normalizedFile = resolveRunnerPath(cwd, filePath);
 	const normalizedFileKey = normalizeMapKey(normalizedFile);
 
@@ -584,7 +638,7 @@ export async function computeCascadeForFile(
 				// write sequence. A new write (higher writeSeq) invalidates the cache entry.
 				const cached =
 					writeSeq != null ? neighborTouchCache.get(cacheKey) : undefined;
-				if (cached?.turnSeq === turnSeq) {
+				if (cached?.turnSeq === turnSeq && cached?.writeSeq === writeSeq) {
 					producedLspData = true;
 					const durationMs = Date.now() - neighborStart;
 					logCascade({
@@ -819,6 +873,7 @@ function appendFallbackNeighbors(
 	for (const [diagPath, { diags, ts }] of allDiags) {
 		const diagKey = normalizeMapKey(diagPath);
 		if (diagKey === normalizedFileKey || seen.has(diagKey)) continue;
+		if (primaryFilesThisTurn.has(diagKey)) continue;
 		if (!nodeFs.existsSync(diagPath)) continue;
 		if (now - ts > CASCADE_TTL_MS) continue;
 		const errors = convertLspDiagnostics(
@@ -917,7 +972,7 @@ export async function dispatchLint(
 	const kind = ctx.kind;
 	if (!kind) return "";
 
-	const groups = getDispatchGroupsForKind(kind, pi);
+	const groups = withSemgrepGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
 	if (groups.length === 0) return "";
 
 	await runProviders(ctx);
@@ -960,7 +1015,7 @@ export async function dispatchLintWithResult(
 		};
 	}
 
-	const groups = getDispatchGroupsForKind(kind, pi);
+	const groups = withSemgrepGroup(kind, getDispatchGroupsForKind(kind, pi), ctx);
 	if (groups.length === 0) {
 		return {
 			diagnostics: [],

package/clients/dispatch/runners/index.ts

@@ -34,6 +34,7 @@ import pythonSlopRunner from "./python-slop.js";
 import rubocopRunner from "./rubocop.js";
 import ruffRunner from "./ruff.js";
 import rustClippyRunner from "./rust-clippy.js";
+import semgrepRunner from "./semgrep.js";
 import shellcheckRunner from "./shellcheck.js";
 import shfmtRunner from "./shfmt.js";
 // Import similarity runner
@@ -65,6 +66,7 @@ export function registerDefaultRunners(registry: RunnerRegistry): void {
 	registry.register(pythonSlopRunner); // Python slop via CLI (priority 25)
 	registry.register(typeSafetyRunner); // Type safety checks (priority 20)
 	registry.register(shellcheckRunner); // Shell script linting (priority 20)
+	registry.register(semgrepRunner); // Semgrep security/deep static analysis (config/flag-gated, priority 50)
 	// DISABLED: registerRunner(astGrepRunner); // Replaced by ast-grep-napi for dispatch
 	// CLI ast-grep kept for ast_grep_search/ast_grep_replace tools only
 	registry.register(similarityRunner); // Semantic reuse detection (priority 35)