@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/docs/ast-grep_rules_catalog.md

@@ -2,7 +2,7 @@
 
 <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
 
-pi-lens bundles **435 enabled** ast-grep rules (251 pi-lens-authored + 184 vendored from CodeRabbit) across **16 languages**, plus 16 disabled.
+pi-lens bundles **446 enabled** ast-grep rules (262 pi-lens-authored + 184 vendored from CodeRabbit) across **16 languages**, plus 16 disabled.
 
 See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `rules/ast-grep-rules/rules/` (pi-lens), `rules/ast-grep-rules/coderabbit/rules/` (vendored).
 
@@ -133,7 +133,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `use-of-sha1-java` | warning | CodeRabbit | Detected SHA1 hash algorithm which is considered insecure. SHA1 is not collision resistant and is therefore not suitable as a cryptographic… |
 | `weak-ssl-context-java` | warning | CodeRabbit | 'An insecure SSL context was detected. TLS versions 1.0, 1.1, and all SSL versions are considered weak encryption and are deprecated. Use S… |
 
-### JavaScript (76)
+### JavaScript (79)
 
 | Rule | Severity | Source | Description |
 |---|---|---|---|
@@ -161,6 +161,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-case-declarations-js` | error | pi-lens | Unexpected lexical declaration in case block — wrap in braces to restrict scope |
 | `no-compare-neg-zero-js` | error | pi-lens | Disallow comparing against -0 |
 | `no-cond-assign-js` | error | pi-lens | Expected a conditional expression and instead saw an assignment. |
+| `no-conditional-empty-object-spread-js` | hint | pi-lens | Conditional empty-object spread — use an explicit if/else to omit fields |
 | `no-console-except-error-js` | warning | pi-lens | Avoid console.log/debug/warn in production code — use a logger or console.error inside catch only |
 | `no-constant-condition-js` | error | pi-lens | Unexpected constant condition |
 | `no-discarded-error-js` | error | pi-lens | new Error() result discarded — add 'throw' or assign to a variable |
@@ -180,6 +181,8 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-new-wrappers-js` | error | pi-lens | Do not use 'new' with wrapper objects — use literal primitives instead |
 | `no-open-redirect-js` | error | pi-lens | Potential open redirect vulnerability — validate redirect URLs |
 | `no-prototype-builtins-js` | error | pi-lens | Use Object.hasOwn() or Object.prototype.hasOwnProperty.call() instead of calling methods directly on the object |
+| `no-reflect-apply-js` | warning | pi-lens | Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead |
+| `no-reflect-get-js` | warning | pi-lens | Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead |
 | `no-single-promise-in-promise-methods-js` | warning | pi-lens | Promise.all/race with a single promise is unnecessary — await it directly |
 | `no-sql-in-code-js` | error | pi-lens | Raw SQL string in code — use query builder or ORM |
 | `no-throw-string-js` | error | pi-lens | Throw Error objects, not strings |
@@ -401,7 +404,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `redundant-usestate-type` | info | pi-lens | `useState<TYPE>(...)` where TYPE is a primitive redundant — TS can infer it from the initial value |
 | `unnecessary-react-hook` | warning | pi-lens | Function with a `use*` name does not call any other React hook — rename to a plain function |
 
-### TypeScript (117)
+### TypeScript (125)
 
 | Rule | Severity | Source | Description |
 |---|---|---|---|
@@ -429,9 +432,12 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-await-expression-member` | hint | pi-lens | Unnecessary parentheses around await — write await expr.prop directly |
 | `no-await-in-promise-all` | error | pi-lens | Avoid await inside Promise.all — use Promise.all with an array of promises instead |
 | `no-await-in-promise-methods` | warning | pi-lens | Do not await inside Promise.all/allSettled — pass the promises directly |
+| `no-bare-host-path-in-win32-branch` | warning | pi-lens | Use win32 path operations inside a branch committed to Windows path semantics |
 | `no-case-declarations` | error | pi-lens | Unexpected lexical declaration in case block — wrap in braces to restrict scope |
+| `no-chained-type-assertions` | warning | pi-lens | Chained type assertion (x as A as B) — stacking assertions with no runtime check between them |
 | `no-compare-neg-zero` | error | pi-lens | Disallow comparing against -0 |
 | `no-cond-assign` | error | pi-lens | Expected a conditional expression and instead saw an assignment. |
+| `no-conditional-empty-object-spread` | hint | pi-lens | Conditional empty-object spread — use an explicit if/else to omit fields |
 | `no-console-except-error` | warning | pi-lens | Avoid console.log/debug/warn in production code — use a logger or console.error inside catch only |
 | `no-constant-condition` | error | pi-lens | Unexpected constant condition |
 | `no-demeter-message-chain` | warning | pi-lens | Message chain (Law of Demeter) — navigating 3+ deep through accessors couples the caller to the whole path. |
@@ -456,6 +462,9 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-open-redirect` | error | pi-lens | Potential open redirect vulnerability — validate redirect URLs |
 | `no-prototype-builtins` | error | pi-lens | Use Object.hasOwn() or Object.prototype.hasOwnProperty.call() instead of calling methods directly on the object |
 | `no-prototype-builtins-native` | hint | pi-lens | Use Object.hasOwn() instead of hasOwnProperty() — ES2022 standard |
+| `no-raw-json-store-write` | warning | pi-lens | Use the atomic write seam for JSON stores instead of writeFileSync |
+| `no-reflect-apply` | warning | pi-lens | Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead |
+| `no-reflect-get` | warning | pi-lens | Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead |
 | `no-relative-cross-package-import` | info | pi-lens | Avoid relative imports across package boundaries (../../). Use absolute imports (@app/..., @components/...) for better agent reasoning abou… |
 | `no-return-await` | warning | pi-lens | Unnecessary 'await' in return statement — use direct return instead |
 | `no-single-promise-in-promise-methods` | warning | pi-lens | Promise.all/race with a single promise is unnecessary — await it directly |
@@ -464,10 +473,12 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-throw-string` | error | pi-lens | Throw Error objects, not strings |
 | `no-typeof-undefined` | hint | pi-lens | Use === undefined instead of typeof x === 'undefined' |
 | `no-unimplemented-stub` | warning | pi-lens | Unimplemented stub — function was scaffolded but never completed |
+| `no-unknown-laundering` | warning | pi-lens | type alias to bare 'unknown' — give the alias real shape or inline 'unknown' at the one call site that needs it |
 | `no-unnecessary-array-flat-depth` | hint | pi-lens | .flat(1) is the default depth — just use .flat() |
 | `no-useless-length-check` | warning | pi-lens | Use .some() instead of .filter().length check — short-circuits at first match |
 | `no-useless-promise-resolve-reject` | warning | pi-lens | Unnecessary Promise.resolve/reject wrapping — return the value directly |
 | `no-useless-rest-spread` | warning | pi-lens | Redundant spread into same container type — remove the extra spread |
+| `no-win32-isabsolute-for-qualification` | warning | pi-lens | Use isFullyQualified for path qualification instead of win32.isAbsolute |
 | `node-rsa-weak-key-typescript` | warning | CodeRabbit | Use of RSA-$BITS, which is considered weak. Based on NIST standards, RSA keys should be at least 2048 bits. |
 | `node-sequelize-empty-password-argument-typescript` | warning | CodeRabbit | The application creates a database connection with an empty password. This can lead to unauthorized access by either an internal or externa… |
 | `node-sequelize-hardcoded-secret-argument-typescript` | warning | CodeRabbit | A secret is hard-coded in the application. Secrets stored in source code, such as credentials, identifiers, and other types of sensitive da… |

package/node_modules/pi-lens/docs/durable-store-audit-1202.md

@@ -0,0 +1,32 @@
+# Durable-store cross-process audit (#1202)
+
+Atomic rename prevents torn files; it does not serialize read-modify-write. This
+audit classifies stores reachable by extension, MCP, CLI, and subagent processes.
+`<project>` means `getProjectDataDir(cwd)` and `<global>` means
+`getGlobalPiLensDir()`.
+
+| Store and path | Racing writers | Semantics | Risk | Existing mitigation / decision |
+|---|---|---|---|---|
+| Turn state — `<project>/turn-state.json` | extension, MCP, CLI; subagents use distinct owners | read-modify-write worklist | (a) impossible | **fixed here:** deferred-format writes now carry the pi session owner, and `clearTurnState` / `incrementTurnCycle` reject a foreign live owner just like `addModifiedRange`; MCP turn-end operations are FIFO-serialized. |
+| Scanner caches — `<project>/cache/{scanner}.json` + `{scanner}.meta.json` | extension, MCP, CLI, subagents | overwrite-only scan result + freshness metadata | (b) possible, benign | none; a losing cache publication is recoverable on the next scan. Data is written before metadata, so interruption cannot make old data newly fresh; concurrent last-finisher wins. |
+| Rule cache — `<project>/cache/{language}-rules-3.json` | all analysis processes | overwrite-only, content-hash validated | (a) impossible | rule hash rejects a cache for different inputs. |
+| Workspace diagnostics — `<project>/cache/lsp-workspace-diagnostics.json` | extension/MCP/CLI sweeps and subagents | read-merge-overwrite cache | (b) possible, benign | mtime/content/dependency freshness rejects stale entries; a lost entry causes a rescan. Accepted benign. |
+| Call graph — `<project>/cache/call-graph.json` + `.meta.json` | extension/MCP/CLI graph builds, subagents | overwrite-only derived graph | (b) possible, benign | source freshness validation; a loss rebuilds from source. Accepted benign. |
+| Codebase model — `<project>/cache/codebase-model.json` + `.meta.json` | extension/MCP/CLI builds, subagents | overwrite-only derived model | (b) possible, benign | source/file-set validation; a loss rebuilds. Accepted benign. |
+| Actionable-warning state — `<project>/cache/actionable-warning-state.json` | dispatches in every process | read-merge-overwrite behavior gate | (c) possible, harmful | **fixed here:** bounded exclusive pid lock, in-lock disk re-read, and per-warning merge preserve concurrent suppression fields before atomic replacement. |
+| Actionable-warning history — `<project>/actionable-warnings.jsonl` | every dispatcher | append-only telemetry | (b) possible, benign | one append call per batch; malformed/truncated telemetry lines are ignored. Accepted benign. |
+| Metrics history — `<project>/metrics-history.json` | session scans and `/lens-metrics` in every process | read-modify-overwrite trend cache | (c) possible, harmful | **accepted loss:** telemetry only; a race can leave a user-visible gap in trend history, but gaps are self-healing after the next scan restores the latest snapshot. Locking every passive capture or restructuring the established bounded JSON format is disproportionate to advisory history. |
+| Project diagnostics — `<project>/cache/project-diagnostics.json` and `project-diagnostics-delta.json` | extension/MCP/CLI scans, subagents | overwrite-only derived snapshots | (b) possible, benign | per-file mtime filtering; next scan replaces loss. Accepted benign. |
+| Worklog — `<project>/worklog.jsonl` | all dispatchers | append-only best-effort telemetry | (b) possible, benign | OS append operation per batch; readers skip malformed lines. Accepted benign. |
+| Widget/read-guard session state — `<project>/sessions/{sessionId}.json` | one extension host per stable session id | overwrite-only session snapshot | (a) impossible | session-id sharding; read guard and widget are co-snapshotted atomically. |
+| Diagnostic dispositions — `<project>/cache/diagnostic-dispositions.json` | extension, MCP, CLI tools, subagents | read-modify-write behavior gate | (c) possible, harmful | **fixed here:** exclusive pid lock, in-lock disk re-read, and per-anchor merge refuse stale whole-file promotion. |
+| Recent touches — `<project>/recent-touches.json` | every extension/subagent publisher | read-append-overwrite bounded attribution ring | (b) possible, benign | explicitly best-effort nudge attribution; lost entries do not gate edits/checks and later touches replenish it. Accepted benign. |
+| Instance registry — `<global>/instances.json` | every host/MCP/subagent process and reaper | read-modify-overwrite observability registry | (b) possible, benign | explicitly best-effort. Backstop orphan reaping intentionally kills untracked managed processes on dead-parent confirmation; missing registry entries allow this (intentional, #1267-adjacent; no fix needed). |
+| Project snapshot — `<project>/cache/project-snapshot.json.gz` + `.meta.json` | extension/MCP/CLI builders, subagents | monotonic derived snapshot | (a) impossible | durable project sequence/source identity and generation-gated staged promotion; body embeds its seq so mismatched metadata is rejected. |
+| Review graph + checkpoint — `<project>/cache/review-graph.json.gz`, `review-graph.checkpoint.json.gz` | extension/MCP/CLI builders, subagents | overwrite-only derived graph | (a) impossible | source signature/project-seq validation plus staged, generation-gated promotion; stale content is rejected on load. |
+| Probe cache — `<global>/probe-cache.json` | every installer/prober | read-modify-write tool availability | (a) impossible | existing bounded cross-process lock + in-lock re-read/change merge (#1263). |
+| Stop-hook status — OS temp `pi-lens-turn-end-*.json` | concurrent CLI Stop hooks | read-modify-overwrite counters | (b) possible, benign | atomic publication; explicitly bounded best-effort telemetry. Accepted benign. |
+
+The grammar/WASM destination files are immutable content assets, not shared
+mutable stores. Atomic staging artifacts are covered separately by the bounded
+session-start stage GC and are not authoritative stores.

package/node_modules/pi-lens/docs/environment-variables.md

@@ -195,6 +195,33 @@ honored.
 Node cap for `/lens-map` (default 500). Graphs with more files keep only the
 highest-degree ones and render a visible truncation note.
 
+## Memory / idle eviction
+
+Several in-memory caches release their contents after a period of inactivity so a
+long-running session does not retain hydrated state indefinitely. Each has an
+env-tunable window; all default to 20 minutes (`1200000` ms).
+
+### `PI_LENS_TS_IDLE_EVICT_MS`
+
+Idle window (ms) after which TypeScript language-service clients release their
+hydrated program and shut down, rebuilding transparently on the next request.
+**Default:** 20 minutes (`1200000`).
+
+### `PI_LENS_WORD_INDEX_IDLE_EVICT_MS`
+
+Idle window (ms) after which the persisted word index (`symbol_search`'s BM25
+index) is released from memory. **Default:** 20 minutes (`1200000`).
+
+### `PI_LENS_PROJECT_SNAPSHOT_IDLE_EVICT_MS`
+
+Idle window (ms) after which the cached project snapshot is released from
+memory. **Default:** 20 minutes (`1200000`).
+
+### `PI_LENS_REVIEW_GRAPH_IDLE_EVICT_MS`
+
+Idle window (ms) after which the in-memory review graph (`file → symbol →
+dependency`) is released. **Default:** 20 minutes (`1200000`).
+
 ## Bus events
 
 ### `PI_LENS_BUS_PUBLISH`
@@ -213,6 +240,23 @@ misbehaves.
 Set to `1` for verbose installer/debug logging (same as `--debug`). Off by
 default.
 
+### `PI_LENS_DEBUG_HANDLES`
+
+Set to `1` **before starting pi** to enable the handle-origin tracer
+(institutionalized from the #1097 hand-rolled `async_hooks` investigation
+that root-caused a leaked `setTimeout` keeping a `--print --no-session`
+process alive). Read once at extension load — toggling it mid-session has no
+effect. When set, pi-lens dumps `process.getActiveResourcesInfo()` counts by
+resource type (plus per-type creation-site stack attribution, since the
+`async_hooks` tracker only installs when the flag was already on at startup)
+to `~/.pi-lens/debug-handles.log` at two points: `agent_settled` (after
+quiet-window work is scheduled) and `session_shutdown` (after teardown —
+whatever is still alive at that point is the leak). Off by default, and a
+true no-op when unset — no writer, no `async_hooks` hook, zero overhead. Use
+it to diagnose a pi process that won't exit: run once with the flag set,
+reproduce the hang, then check `debug-handles.log`'s `session_shutdown`
+entry for what's still holding the loop open.
+
 ### `PI_LENS_LOG_RETENTION_DAYS`
 
 Days to keep rotated logs before cleanup. **Default:** `7`.

package/node_modules/pi-lens/docs/fable.md

@@ -138,3 +138,30 @@ inventory earning nothing. Feeding transitive impact into cascade neighbor
 selection is probably the highest-leverage *feature* work available — ideally
 paired with the #202 structural-hash short-circuit so the expansion prunes
 when a changed file's exported interface is unchanged.
+
+## OS-agnostic paths: classification is centralized, transformation isn't (#1193)
+
+The path-*shape* layer is genuinely unified — `isWindowsPath`, the
+`win32`-vs-`posix` shape-conditional idiom (confined to 4 files), `realpathSync`
+(confined to `path-utils.ts`), `PathKeyedMap`, the `walkUpDirs` family, and the
+`uriToPath`/`uriToDiskPath` LSP ingest boundary are all single-source and
+defensively documented. The path-*transformation* layer is not: slash-folding
+(`.replace(/\\/g, "/")`) is hand-rolled **138× across 83 files** with no shared
+helper, `\r\n`-folding re-implements `normalizeToLF` in five files, and ephemeral
+case/slash key-normalizers are copy-pasted in four (one of which case-folds but
+forgets to slash-fold). That gap is why the *same* shape-2 defect keeps re-filing
+under new numbers — #1150 → #1152 → #1161 → #1163 → #1194. Per-site
+`isWindowsPath ? win32 : posix` conditionals treat symptoms; every new interior
+`dirname`/`relative`/`isAbsolute` on a potentially-cross-shaped value is a fresh
+latent instance. The tell: LSP URIs are the one axis with a real *ingest*
+primitive, and the one axis not generating monthly bugs.
+
+Highest-leverage move (**P1**, tracked in #1193): ship a `toPosix()` slash-fold
+primitive and make it the only sanctioned form — it funnels the 138 sites *and*
+makes a shape-2 ast-grep rule **possible** for the first time (today the idiom and
+the bug are byte-identical, so #1158 can't distinguish them; an *un-migrated*
+`.replace` after the primitive exists is detectable). Then push normalization to
+the four ingest boundaries — **persisted-key rehydrate** (snapshot / word-index /
+call-graph / review-graph symbol keys written on Windows, read on Linux CI) is the
+hot one — so interior code can once again trust host-default `path` fns. Full P1–P5
+plan + enforcement in #1193; the latest missed member fixed in #1194.

package/node_modules/pi-lens/docs/features.md

@@ -40,6 +40,34 @@ Repositories can disable all immediate and deferred auto-format mutations with
 keeping formatter detection, lint dispatch, LSP synchronization, and
 diagnostics available.
 
+**Auto-fix timing depends on the tool.** A `write` (new file, full overwrite,
+or a bash-authored write like `sed -i`/a redirect) still gets pipeline autofix
+immediately, in the same tool result; when it changes the file, the result
+carries the full authoritative post-fix content (capped at 2 MiB per file, one
+shared budget across a multi-file bash write — past that it degrades to a
+re-read warning). An `edit` defers autofix to `agent_end`, where it joins the
+same per-file deferred-mutation queue as deferred formatting — one coalesced
+record per file (`kinds: {autofix, format}`), autofix draining before format
+so the final state is formatter-stable. A `write` immediately followed by an
+`edit` on the same file in the same turn demotes the write's autofix to
+deferred too. See `clients/pipeline.ts`, `clients/runtime-tool-result.ts`, and
+`clients/runtime-agent-end.ts`.
+
+Deferred formatting (the `agent_end` default) runs with **bounded
+concurrency**: at most three formatter subprocesses in flight at once, with
+results applied in admission order and cooperative yields between files, so a
+large batch of queued files can't stall the event loop or the turn-end pass.
+
+### Commit/Push Guard (Experimental)
+
+`--lens-guard` (also `guard.enabled: true` in `~/.pi-lens/config.json`) opts
+into blocking `git commit`/`git push` while unresolved pi-lens blockers exist.
+Detection covers normalized wrapper launchers, shell-escaped and
+keyword/combined-flag verb forms, and shell substitutions, while literal text
+in non-executing contexts remains allowed. Off by default; see
+[docs/agent-guide.md](agent-guide.md) and [docs/settings.md](settings.md) for
+the full behavior and honest limits.
+
 ### Review Graph - Cascade Diagnostics
 
 pi-lens builds a review graph (`file → symbol → dependency`) during session and uses it at turn end to render an impact cascade: which files were affected by a change and how diagnostics propagated through the dependency graph. Nodes track kind, language, and export status; edges track contains/imports/calls/references.
@@ -140,7 +168,7 @@ When `actionableWarnings.autoFix.enabled` is set in global or project config (or
 
 ### Bus Events — `pilens:files:touched` (#482)
 
-pi-lens writes files **outside the agent's own tool calls**: dispatch autofix (biome/ruff/eslint/stylelint/sqlfluff/rubocop/ktlint/rust-clippy/dart-fix/golangci-lint/detekt/ktfmt/markdownlint/oxlint --fix) and formatter runs (immediate or deferred-at-`agent_end`) both mutate files after the fact, and the conservative actionable-warnings autofix above applies LSP quickfixes the same way. Other extensions in the same session that track file mutations are otherwise blind to those writes.
+pi-lens writes files **outside the agent's own tool calls**: dispatch autofix (biome/ruff/eslint/stylelint/sqlfluff/rubocop/ktlint/ktfmt/rust-clippy/dart-fix/golangci-lint/detekt/markdownlint/oxlint --fix) mutates the file immediately for a `write` and at `agent_end` for a deferred `edit` (see "Formatters" above); formatter runs (immediate or deferred-at-`agent_end`) do the same; and the conservative actionable-warnings autofix above applies LSP quickfixes at `agent_end` the same way. Other extensions in the same session that track file mutations are otherwise blind to those writes — this event, published either way, is how they find out.
 
 pi-lens broadcasts them on pi's shared in-process event bus (`pi.events`, exposed to every extension via the `ExtensionAPI`) as a single named event:
 
@@ -317,9 +345,9 @@ pi-lens ships an MCP (Model Context Protocol) server so Claude Code — or any M
 | Layer | MCP tools | What they expose |
 |---|---|---|
 | **Per-edit** | `pilens_analyze`, `pilens_lsp_diagnostics`, `pilens_lsp_navigation`, `pilens_ast_grep_search`, `pilens_ast_grep_replace`, `pilens_module_report`, `pilens_read_symbol` | The fast pipeline (format → autofix → LSP diagnostics → parallel runners) plus the structured read-substitute pair. `analyze` accepts `mode: warm \| fresh` — `warm` reuses the server's in-process LSP, `fresh` forks a worker that loads freshly-built code from disk so the result reflects the latest commit. |
-| **Per-turn** | `pilens_turn_end` | Drives the **real** `handleTurnEnd` (knip incremental, jscpd delta, dep-circular, cascade, tests, actionable+code-quality warnings) — not a re-implementation. Caller-supplied edited files are auto-registered into turn-state via `addModifiedRange`. |
+| **Per-turn** | `pilens_turn_end` | Drives the **real** `handleTurnEnd` (knip incremental, dep-circular, cascade, tests, actionable+code-quality warnings) — not a re-implementation. Caller-supplied edited files are auto-registered into turn-state via `addModifiedRange`. |
 | **Per-session** | `pilens_session_start` | Drives the **real** `handleSessionStart` — full jscpd/knip/madge/govulncheck/gitleaks/trivy scans + complexity baselines + LSP warm. The error-debt baseline is not currently populated by the production session-start path. |
-| **Project / observability** | `pilens_project_scan`, `pilens_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search` | Cheap project-wide scans, cached diagnostic state, latency telemetry, ranked identifier search (BM25 over the persisted word index — see [docs/word-index.md](word-index.md)). Cross-file blast radius now lives in `pilens_module_report`'s `blastRadius` option. |
+| **Project / observability** | `pilens_project_scan`, `pilens_diagnostics`, `pilens_health`, `pilens_latency`, `pilens_symbol_search` | Cheap project-wide scans, cached diagnostic state, latency telemetry, ranked identifier search (BM25 over the persisted word index — see [docs/word-index.md](word-index.md)). Cross-file blast radius now lives in `pilens_module_report`'s `blastRadius` option. `pilens_health` (and its pi-side `/lens-health` counterpart) also reports a bounded, process-local **degradation ledger** — trust refusals, mode suppressions, LSP breaker trips, formatter skips/failures, TypeScript/word-index/review-graph/project-snapshot idle evictions, WASM aborts, and diagnostics-timeout tallies — so silently degraded behavior stays visible instead of vanishing into a log. |
 | **Lifecycle / loop** | `pilens_rebuild` | Runs `npm run build:dist` so `pilens_analyze mode=fresh` reflects the latest commit. Makes the review loop self-contained: commit → `pilens_rebuild` → `pilens_analyze mode=fresh` → `pilens_latency`. |
 
 **Honest limits** (live-tested, documented in `mcp.md`):
@@ -342,4 +370,18 @@ claude mcp add --scope user pi-lens \
   -- node <repo>/dist/mcp/server.js
 ```
 
+**Hooks** (`settings.json`) close the loop: PostToolUse = per-edit, Stop = per-turn.
+
+```json
+{ "hooks": {
+  "PostToolUse": [
+    { "matcher": "Edit|Write",
+      "hooks": [ { "type": "command", "command": "pi-lens-analyze --hook" } ] } ],
+  "Stop": [
+    { "hooks": [ { "type": "command", "command": "pi-lens-analyze --turn-end", "timeout": 60 } ] } ]
+} }
+```
+
+The per-edit hook falls back to a cold local analysis when no server is up; the `Stop` hook is **warm-server-only** because only the server process owns the session state and pending turn work. It skips with a single stderr line when unavailable. Workspace IPC requests are ordered, so a timed-out PostToolUse client cannot let `Stop` overtake analysis still running in the server. `SubagentStop` is deliberately not registered because subagent edits already reach turn-state through PostToolUse.
+
 The full design + tier-by-tier progress (and known limits) lives in [`docs/mcp.md`](docs/mcp.md). Status: **experimental** — the foundation is solid (transport, warm LSP, lifecycle handlers wired), but the surface is still maturing. Use the pi extension for production agent work; reach for the MCP server for debugging, dogfooding, and direct Claude Code access.

package/node_modules/pi-lens/docs/globalconfig.md

@@ -24,6 +24,18 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
 | `--lens-actionable-warning-actions` | `actionableWarnings.includeLspCodeActions` | `false` |
 | `--lens-actionable-warning-autofix` | `actionableWarnings.autoFix.enabled` | `false` |
 | `--lens-actionable-warning-all` | `actionableWarnings.deltaOnly` (`false`) | `true` |
+| `--lens-compact-tool-line` | `ui.compactToolLine` | `false` |
+| `--no-lazy-tools` | `tools.lazy` | `true` |
+
+By default pi-lens registers six situational tools (the `ast_grep_*` family,
+`lsp_navigation`, `lens_diagnostic_mark`) inactive and exposes a small loader,
+`pi_lens_activate_tools`, that the model calls to activate the ones it needs.
+`--no-lazy-tools` turns that off: every pi-lens tool is active from the first
+turn and pi-lens never changes the tool list. Use it if you would rather spend
+the tokens of a longer tool list than have the list change mid-session. The
+loader tool is still registered and still describes itself as activating
+inactive tools; under this flag those tools are already active, so calling it
+does nothing.
 
 Keys are positive (`"enabled": true` means the feature runs), so a `--no-*` flag corresponds to setting its key `false`. A `no-*` flag on the command line is a one-way switch: it can disable, never re-enable, so `--no-lsp` wins over `lsp.enabled: true` but nothing on the CLI overrides `lsp.enabled: false`. Set the key back to `true` to re-enable.
 
@@ -167,10 +179,52 @@ Note: `maxProjectFiles` (below) is discovered differently — via an upward walk
 
 ### `rules`
 
-Per-rule threshold overrides. Currently honored:
+Per-rule threshold overrides and policy filters. Currently honored:
 
 - `high-complexity.threshold` — cyclomatic complexity (default `15`)
 - `high-fan-out.threshold` — distinct function calls (default `20`)
+- `<id>.disable` — disable diagnostics for the listed rule ids (output-only
+  filter). Same rule-id normalization as `pi-lens-ignore`: a user lists
+  `no-eval` once and the filter covers `no-eval`, `ast-grep:no-eval`, and
+  `no-eval-js`. Side effect: a rule whose real name genuinely ends in `-js`
+  (e.g. `prefer-js`) is conflated with its stem (`prefer`) — disabling or
+  selecting one also disables or selects the other.
+- `<id>.select` — allowlist of rule ids; only the listed rule ids survive
+  filtering. Disable wins over select project-wide, even when the two lists
+  are configured under different keys.
+
+The `<id>` key is a grouping label only — it does not scope which rules the
+`disable`/`select` list underneath it can match. Matching is **project-wide**:
+every `disable` list across every key is unioned into one drop list, and
+every `select` list across every key is unioned into one allowlist. So
+`"security": { "disable": ["no-eval"] }` disables `no-eval` regardless of
+`security` being the rule's own id, and two keys can each contribute to the
+same select union.
+
+```json
+{
+  "rules": {
+    "high-complexity": { "threshold": 25 },
+    "high-fan-out": { "threshold": 30 },
+    "no-eval": { "disable": ["no-eval", "no-eval-js", "ast-grep:no-eval"] },
+    "my-rule-set": { "select": ["rule-a", "rule-b"] }
+  }
+}
+```
+
+**Warning:** because select is project-wide, a non-empty `select` list
+*anywhere* in `rules` silences every rule not in that list, across the whole
+project — including tsc/eslint findings, not just the rule types you're
+thinking about when you write it. It's a big hammer; reach for `disable`
+instead unless you actually want an allowlist over everything. Findings that
+carry no rule id at all (an eslint parse error, for example) are exempt from
+select, so an allowlist can never hide them.
+
+Disable and select are output-only filters applied AFTER inline suppression,
+disposition, and dedup — the project-level policy never widens the trusted
+surface area (widget state, baseline, dedup cache stay authoritative). The
+baseline still records the full unfiltered set so a project-config edit does
+not corrupt delta baselines.
 
 ### `maxProjectFiles`
 
@@ -197,5 +251,6 @@ Explicit override for the review graph's own file budget (#775), for monorepos t
 - A malformed JSON file is logged once and treated as "no config" — your diagnostics never get blocked by a syntax error in your own config.
 - Rule thresholds must be positive finite numbers; invalid, zero, or negative values are logged once and ignored.
 - Mutation-control `enabled` values must be booleans; invalid values are logged once and ignored.
+- `rules.<id>.disable` and `rules.<id>.select` must each be a non-empty array of non-empty strings; a non-array value, an empty array, or an all-whitespace array is logged once and the entry is dropped. A policy-only entry (no `threshold`) is honored. A policy entry with an invalid value still keeps any valid `threshold` alongside it.
 - The depth sub-threshold of `high-complexity` (default `6`) is intentionally not exposed; only the cyclomatic-complexity knob ships today to keep the schema tight.
 - The file is mtime-cached, so editing it takes effect on the next scan without restarting the agent.

package/node_modules/pi-lens/docs/language-coverage.md

@@ -20,8 +20,8 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | HTML                  | ✓   | lsp, htmlhint                                                                                                  | prettier                |
 | YAML                  | ✓   | lsp, yamllint, actionlint (GitHub workflows)                                                                   | prettier                |
 | JSON                  | ✓   | lsp                                                                                                            | biome, prettier         |
-| Svelte                | ✓   | lsp                                                                                                            | —                       |
-| Vue                   | ✓   | lsp                                                                                                            | —                       |
+| Svelte                | ✓   | lsp                                                                                                            | oxfmt (needs `svelte` pkg installed + config `svelte: true`) |
+| Vue                   | ✓   | lsp                                                                                                            | prettier, oxfmt         |
 | SQL                   | —   | sqlfluff                                                                                                       | sqlfluff                |
 | Markdown              | —   | spellcheck, markdownlint, vale                                                                                 | prettier                |
 | Docker                | ✓   | lsp, hadolint                                                                                                  | —                       |
@@ -42,7 +42,8 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | Gleam                 | ✓   | lsp, gleam-check                                                                                               | gleam format            |
 | OCaml                 | ✓   | lsp                                                                                                            | ocamlformat             |
 | Clojure               | ✓   | lsp                                                                                                            | cljfmt                  |
-| Terraform             | ✓   | lsp, tflint                                                                                                    | terraform fmt           |
+| Terraform             | ✓   | lsp, tflint, trivy-config (opt-in)                                                                             | terraform fmt           |
+| Terragrunt            | —   | terragrunt                                                                                                     | terragrunt hcl fmt      |
 | Nix                   | ✓   | lsp                                                                                                            | nixfmt                  |
 | TOML                  | ✓   | lsp, taplo                                                                                                     | taplo                   |
 | CMake                 | ✓ (cmake-language-server) | lsp                                                                                           | cmake-format            |

package/node_modules/pi-lens/docs/lsp-capability-matrix.md

@@ -18,7 +18,7 @@ regenerated docs — so this file self-populates from CI without manual copy-pas
 
 `probe-clean-signal.mjs` also runs a **drift check** (#529): it compares each
 probed server's observed `clean-behavior` against the hand-set `silentOnClean`
-marker in `clients/lsp/server-strategies.ts` and writes any mismatch to the
+marker in `clients/lsp/wait-policy/strategies.ts` and writes any mismatch to the
 `## silentOnClean drift` section below. This is telemetry only — never a CI
 gate — because the probe is a timing-based negative observation; a mismatch
 just tells a human the marker may need updating. `unknown` observations are
@@ -150,7 +150,7 @@ the rest fill in as the nightly reaches them.
 ## silentOnClean drift (nightly-generated)
 
 Telemetry only — never a CI gate. Compares each probed server's observed
-`clean-behavior` against `clients/lsp/server-strategies.ts`'s `silentOnClean`
+`clean-behavior` against `clients/lsp/wait-policy/strategies.ts`'s `silentOnClean`
 marker; a mismatch means the marker may need a human update (#529). `unknown`
 observations are never compared (a slow/absent server is not evidence either way).
 

package/node_modules/pi-lens/docs/mcp.md

@@ -378,13 +378,18 @@ be exercised + debugged directly through Claude Code without running pi.
   Wire it in Claude Code `settings.json`:
 
   ```json
-  { "hooks": { "PostToolUse": [
-    { "matcher": "Edit|Write",
-      "hooks": [ { "type": "command", "command": "pi-lens-analyze --hook" } ] } ] } }
+  { "hooks": {
+    "PostToolUse": [
+      { "matcher": "Edit|Write",
+        "hooks": [ { "type": "command", "command": "pi-lens-analyze --hook" } ] } ],
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "pi-lens-analyze --turn-end", "timeout": 60 } ] } ]
+  } }
   ```
 
   (the cold-LSP fix means the type-check is honestly reported as skipped, not a
-  false clean; the agent pulls `pilens_analyze` warm when it wants types.)
+  false clean; the agent pulls `pilens_analyze` warm when it wants types. The
+  `Stop` half is the per-turn pass — see the bullet below.)
 
 - [ ] **booboo** full-codebase review tool (`/lens-booboo` → handleBooboo:
   complexity, AI-slop, TODOs, dead-code, dupes, type-coverage).
@@ -410,6 +415,34 @@ be exercised + debugged directly through Claude Code without running pi.
   project. 5 IPC unit tests (path stability, named-pipe round-trip, no-server +
   error → undefined fallback); live-proven (server "warm analyze" log fired,
   bin returned the diagnostic). Removes the one real weakness of the push half.
+- [x] **Stop hook → per-turn pass** (#538) — the `pi-lens-analyze` bin gains a
+  turn-end mode (`--turn-end`, or a Claude Code `Stop` payload on stdin), the
+  analogue of pi's `agent_end`: incremental knip/madge, dep-circular,
+  cascade-to-dependents, tests, actionable-warnings aggregation. PostToolUse has
+  already accumulated the edited files into turn-state by the time `Stop` fires,
+  so the hook passes no files and clears any inherited pi `sessionId` — turn-
+  end's stale-session eviction leaves the registered worklist alone. The request is a
+  tagged route (`{route:"turn-end"}`, own schema version) on the **workspace**
+  socket, not the PID-scoped one: a Stop hook knows its cwd, never the server's
+  pid. It rides in ahead of the parse, so it inherits the #535 build-staleness
+  gate for free, and an untagged analyze request on the same socket is byte-for-
+  byte unchanged. All workspace IPC requests share one server-side queue, so a
+  timed-out PostToolUse client cannot let `Stop` overtake analysis still running
+  in the server, and concurrent turn-ends cannot race the turn-state clear.
+  **Warm-only, no cold fallback**: only the server process owns the session state
+  and pending turn work, so a local pass would report a false clean — no warm
+  server means one stderr line, silent stdout, exit 0.
+  The client waits 55s so it gives up inside Claude Code's 60s hook timeout.
+  `SubagentStop` is deliberately NOT registered: subagent edits already fire
+  PostToolUse into the shared turn-state, the consume bridges are one-shot (a
+  subagent pass would eat the main agent's findings into a transcript nobody
+  reads), and the fan-out would multiply the heavy pass. Visibility, honestly:
+  Stop-hook stdout is user-visible in transcript mode (Ctrl-R), NOT model
+  context — blockers still gate commits through the retained lens-guard record,
+  and a `decision:"block"` render is a follow-up. Tests run fire-and-forget
+  inside turn-end, so the `Tests:` section you see is the *previous* turn's
+  failures. Unit, bin, and live-route smoke tests cover transport, ordering,
+  rendering, and spawned-server behavior.
 
 ## Transport decision — RESOLVED: hand-roll (zero new deps)
 

package/node_modules/pi-lens/docs/servercapabilities.md

@@ -6,7 +6,7 @@ server's `initialize` handshake. Generated by `node scripts/server-capabilities.
 absent on the generating host are listed under *Unavailable* — run in a
 provisioned environment (the nightly) to capture those rows.
 
-_Last generated: 2026-08-01 on linux; 29 servers captured, 14 unavailable._
+_Last generated: 2026-08-15 on linux; 29 servers captured, 14 unavailable._
 
 ## Diagnostic mode + navigation/edit operations
 
@@ -19,7 +19,7 @@ Legend: ✓ advertised, · not. **mode** = document diagnostics (`pull` = `textD
 | clojure | push-only | · | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 62 |
 | csharp | pull | ✓ | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
 | css | pull | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
-| dart | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 16 |
+| dart | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 18 |
 | deno | pull | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 2 |
 | docker | push-only | · | ✓ | · | · | · | ✓ | ✓ | ✓ | · | · | ✓ | · | · | 0 |
 | expert | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | · | · | 2 |
@@ -89,7 +89,7 @@ surface, including providers pi-lens does not yet consume.
 
 - **ast-grep** (1): ast-grep.applyAllFixes
 - **clojure** (62): add-import-to-namespace, add-missing-import, add-missing-libspec, add-require-suggestion, as-to-refer, backward, backward-barf, backward-select, backward-slurp, change-coll, clean-ns, cond->if-refactor, create-function, create-test, cursor-info, cycle-coll, cycle-keyword-auto-resolve, cycle-privacy, demote-fn, destructure-keys, drag-backward, drag-forward, drag-param-backward, drag-param-forward, expand-let, extract-function, extract-to-def, forward, forward-barf, forward-select, forward-slurp, get-in-all, get-in-less, get-in-more, get-in-none, if->cond-refactor, inline-function, inline-symbol, introduce-let, kill-sexp, …
-- **dart** (16): dart.edit.codeAction.apply, dart.edit.sortMembers, dart.edit.organizeImports, dart.edit.fixAll, dart.edit.fixAllInWorkspace.preview, dart.edit.fixAllInWorkspace, dart.edit.sendWorkspaceEdit, refactor.perform, refactor.validate, dart.logAction, dart.refactor.add_constructor_name, dart.refactor.convert_all_formal_parameters_to_named, dart.refactor.convert_selected_formal_parameters_to_named, dart.refactor.move_selected_formal_parameters_left, dart.refactor.move_top_level_to_file, dart.refactor.remove_constructor_name
+- **dart** (18): dart.edit.codeAction.apply, dart.edit.sortMembers, dart.edit.organizeImports, dart.edit.fixAll, dart.edit.fixAllInWorkspace.preview, dart.edit.fixAllInWorkspace, dart.edit.sendWorkspaceEdit, refactor.perform, refactor.validate, dart.logAction, dart.refactor.add_constructor_name, dart.refactor_add.import_prefix, dart.refactor.convert_all_formal_parameters_to_named, dart.refactor.convert_selected_formal_parameters_to_named, dart.refactor.move_selected_formal_parameters_left, dart.refactor.move_top_level_to_file, dart.refactor.remove_constructor_name, dart.refactor.remove_import_prefix
 - **deno** (2): deno.cache, deno.reloadImportRegistries
 - **expert** (2): Reindex, connectionDetails
 - **go** (47): gopls.add_dependency, gopls.add_import, gopls.add_telemetry_counters, gopls.add_test, gopls.apply_fix, gopls.assembly, gopls.change_signature, gopls.check_upgrades, gopls.client_open_url, gopls.diagnose_files, gopls.doc, gopls.edit_go_directive, gopls.extract_to_new_file, gopls.fetch_vulncheck_result, gopls.free_symbols, gopls.gc_details, gopls.generate, gopls.go_get_package, gopls.implement_interface, gopls.list_imports, gopls.list_known_packages, gopls.lsp, gopls.maybe_prompt_for_telemetry, gopls.mem_stats, gopls.modify_tags, gopls.modules, gopls.move_type, gopls.package_symbols, gopls.packages, gopls.regenerate_cgo, gopls.remove_dependency, gopls.reset_go_mod_diagnostics, gopls.run_go_work_command, gopls.run_govulncheck, gopls.run_tests, gopls.scan_imports, gopls.split_package, gopls.start_debugging, gopls.start_profile, gopls.stop_profile, …

package/node_modules/pi-lens/docs/settings.md

@@ -60,6 +60,7 @@ column is the effective behavior when nothing is set.
 | `--no-tests` | `tests.enabled` | global | test runner **on** |
 | `--no-delta` | `delta.enabled` | global | delta mode **on** (new diagnostics only) |
 | `--lens-guard` | `guard.enabled` | global | **off** |
+
 | `--no-opengrep` | `opengrep.enabled` | global | Opengrep scanner **on** |
 | `--no-read-guard` | `readGuard.enabled` | global | read-before-edit monitor **on** |
 | `--no-lens-context` | `contextInjection.enabled` | global | context injection **on** |
@@ -68,6 +69,19 @@ column is the effective behavior when nothing is set.
 | `--lens-actionable-warning-actions` | `actionableWarnings.includeLspCodeActions` | global | **off** |
 | `--lens-actionable-warning-autofix` | `actionableWarnings.autoFix.enabled` | project | **off** |
 | `--lens-actionable-warning-all` | `actionableWarnings.deltaOnly` (`false`) | global | `deltaOnly` **on** (report this turn only) |
+| `--lens-compact-tool-line` | `ui.compactToolLine` | global | **off** (two-row tool rendering) |
+| `--no-lazy-tools` | `tools.lazy` | global | lazy tools **on** (six situational tools start inactive) |
+
+`--no-lazy-tools` keeps every pi-lens tool active for the whole session, so the
+advertised tool list never changes. The `pi_lens_activate_tools` loader stays
+registered and keeps its usual description; under this flag the tools it names
+are already active, so calling it is a no-op.
+
+`--lens-guard` is **EXPERIMENTAL and strictly opt-in**. When enabled, actual
+`git commit`/`git push` commands are blocked only for current, structured
+blocking findings (including blocking test failures); advisory/no-action-required
+findings do not block. Stale, malformed, or ambiguous persisted state blocks
+conservatively until checks run again.
 
 `--immediate-format` and `--lens-actionable-warning-all` are not `--no-*` flags,
 so they set a value rather than flipping a boolean off.
@@ -87,6 +101,8 @@ field docs.
 | `actionableWarnings.autoFix.maxFixes` | global | `5` | Cap on quickfixes applied per turn (`0` = report only) |
 | `rules.high-complexity.threshold` | project | `15` | Cyclomatic-complexity threshold |
 | `rules.high-fan-out.threshold` | project | `20` | Distinct-function-call threshold |
+| `rules.<id>.disable` | project | absent | Disable diagnostics for a rule (output-only filter, project-wide; same normalization as `pi-lens-ignore`) |
+| `rules.<id>.select` | project | absent | Allowlist of rule ids (output-only filter, project-wide across every key; disable wins over select) |
 | `maxProjectFiles` | project | `2000` | Base scale knob; derives five subsystem size budgets |
 | `reviewGraph.maxFiles` | project | derived (clamped `100`–`20000`) | Explicit review-graph file budget |
 | `trivy.enabled` / `trivy.minSeverity` | project | off | Opt-in Trivy vulnerability scanning |
@@ -140,7 +156,8 @@ tolerated without warning; anything else is logged once as a likely typo.
   "ignore": ["**/*.test.ts", "vendor/**"],
   "rules": {
     "high-complexity": { "threshold": 25 },
-    "high-fan-out": { "threshold": 30 }
+    "high-fan-out": { "threshold": 30 },
+    "no-eval": { "disable": ["no-eval", "ast-grep:no-eval", "no-eval-js"] }
   },
   "maxProjectFiles": 5000,
   "format": { "enabled": false }

package/node_modules/pi-lens/docs/tools.md

@@ -5,7 +5,10 @@ pi-lens registers the following slash commands with the pi host:
 - `/lens-toggle` — toggle pi-lens on/off for the current session without restarting
 - `/lens-context-toggle` — toggle automatic context injection on/off for the session (tools/LSP/read-guard/formatting stay active)
 - `/lens-widget-toggle` — show/hide the pi-lens diagnostics widget below the editor
-- `/lens-health` — runtime health, latency, and diagnostic telemetry
+- `/lens-health` — runtime health, latency, and diagnostic telemetry, including
+  bounded per-session degradation counts (trust refusals, LSP breakers,
+  formatter skips/failures, idle evictions, WASM aborts, timeout tallies, and
+  more)
 - `/lens-perf` — independent top-five p50 and p99 rankings for the current process session and machine-wide active latency-log window
 - `/lens-allow-edit <path>` — override the read-before-edit guard for a single edit
 - `/lens-tools` — tool installation status: globally installed, auto-installed, or npx fallback