pi-lens 4.4.0 → 4.4.2

package/dist/mcp/worker.js

@@ -2,74 +2,79 @@
 import { createRequire as __pilensCreateRequire } from "node:module"; const require = __pilensCreateRequire(import.meta.url);
 import {
   analyzeFile
-} from "../chunk-TLGFBM3F.js";
-import "../chunk-C2AUYXQH.js";
-import "../chunk-I3R7GKDR.js";
+} from "../chunk-ODBNXWT4.js";
+import "../chunk-OXXKQCSV.js";
+import "../chunk-EJIUXPBX.js";
 import "../chunk-FC4RP4I2.js";
-import "../chunk-DFVMIKMQ.js";
-import "../chunk-TO6WL3GM.js";
-import "../chunk-7F72PXY2.js";
-import "../chunk-RPD5K5NC.js";
-import "../chunk-ZMOL6RQC.js";
-import "../chunk-I7SPGOWI.js";
-import "../chunk-AS44CFQ4.js";
-import "../chunk-7FBF7NPR.js";
-import "../chunk-HHYAELLJ.js";
-import "../chunk-V5PXFSZK.js";
-import "../chunk-YLF3PPT5.js";
-import "../chunk-JOLITGCC.js";
-import "../chunk-E2WFBRHM.js";
-import "../chunk-6VCD4VKZ.js";
-import "../chunk-F3P7VQ7H.js";
-import "../chunk-LSMJ6KBE.js";
+import "../chunk-66SXUJCA.js";
+import "../chunk-VCHXCQFG.js";
+import "../chunk-IXXDFY73.js";
+import "../chunk-MRXKYPCS.js";
+import "../chunk-2CD5RS6M.js";
+import "../chunk-UZ3TUTRV.js";
+import "../chunk-EETY4LF7.js";
+import "../chunk-GOYRYZ2R.js";
+import "../chunk-RPLINGVB.js";
+import "../chunk-XCJN5IJU.js";
+import "../chunk-76MWC2K6.js";
+import "../chunk-GXW6K4YJ.js";
+import "../chunk-2B73ZPOK.js";
+import "../chunk-XMSXXAHW.js";
+import "../chunk-7DYBLXYA.js";
+import "../chunk-PV6LR5P5.js";
 import "../chunk-3MED75HT.js";
-import "../chunk-3I5QFT3N.js";
-import "../chunk-TVN5N6GY.js";
-import "../chunk-ARFCXG7S.js";
-import "../chunk-OAXNDZJ7.js";
+import "../chunk-CO2G5PHH.js";
+import "../chunk-IBGIOBEE.js";
+import "../chunk-PNQDPDRC.js";
 import "../chunk-XIMYZ3JA.js";
-import "../chunk-B3I2UUT4.js";
-import "../chunk-DIULIWKU.js";
-import "../chunk-VDBPVIKD.js";
+import "../chunk-ESBQHFMJ.js";
+import "../chunk-34WSVGEM.js";
+import "../chunk-VWCXW2E7.js";
+import "../chunk-ZXYDQ3TZ.js";
 import "../chunk-5W3R6LFT.js";
-import "../chunk-LW6XKDZQ.js";
+import "../chunk-QHJ6DQ2R.js";
 import "../chunk-Z54ZSOBZ.js";
-import "../chunk-TGPXLY2J.js";
+import "../chunk-724UL2TJ.js";
 import "../chunk-QOZXJ4NA.js";
-import "../chunk-V7R425XG.js";
-import "../chunk-PAK6IDME.js";
-import "../chunk-GUOGVTCQ.js";
-import "../chunk-AJVLWNFN.js";
-import "../chunk-YGVYKNSN.js";
-import "../chunk-LNAKEO63.js";
+import "../chunk-GBPP5P7X.js";
+import "../chunk-P7266HLM.js";
+import "../chunk-MQLUAEOC.js";
+import "../chunk-52FUZI6K.js";
+import "../chunk-SAEFPSB6.js";
+import "../chunk-GAEGEPOC.js";
 import "../chunk-Z3CCVDUB.js";
-import "../chunk-PWFHBTSF.js";
+import "../chunk-L3BLXZG7.js";
 import "../chunk-2BEMIWEW.js";
-import "../chunk-OQGFCZJ4.js";
-import "../chunk-RUOG5D2C.js";
-import "../chunk-U3VGR4VU.js";
-import "../chunk-NTUJEGDZ.js";
-import "../chunk-EOKRQ3SA.js";
-import "../chunk-WONERJTP.js";
-import "../chunk-22AVIGXS.js";
-import "../chunk-GVXA6CCE.js";
-import "../chunk-6QIUX4EP.js";
-import "../chunk-VHQLPIRJ.js";
-import "../chunk-VN2AXLEX.js";
+import "../chunk-66VMUL7Q.js";
+import "../chunk-Q7DUK4LX.js";
+import "../chunk-AW7R2GWG.js";
+import "../chunk-RWWYJ623.js";
+import "../chunk-VRZP76YM.js";
+import "../chunk-QOBUHWHX.js";
+import "../chunk-QILIYSJF.js";
+import "../chunk-6C7JWPCP.js";
+import "../chunk-5NGR67U5.js";
+import "../chunk-C34ZXZ7O.js";
 import "../chunk-BW5KFIQC.js";
 import "../chunk-QYF5S6P6.js";
-import "../chunk-5ZEJHV35.js";
-import "../chunk-DQ2NZ7C4.js";
-import "../chunk-VNMT7C64.js";
+import "../chunk-PHDMFAKM.js";
+import "../chunk-2BBLFX75.js";
+import "../chunk-XVF2VVXP.js";
+import {
+  setProjectTrustState
+} from "../chunk-ZANLILYD.js";
 import "../chunk-2EECBNC5.js";
-import "../chunk-N3YQJI6O.js";
-import "../chunk-O6TQT6RI.js";
-import "../chunk-5THXD6X5.js";
-import "../chunk-UK3CMEAL.js";
+import "../chunk-JAU72XNY.js";
+import {
+  logExtension
+} from "../chunk-XTMJ7XDT.js";
+import "../chunk-JMYYOTQG.js";
+import "../chunk-QQNQ7SJW.js";
+import "../chunk-AOHZU2BM.js";
 import "../chunk-LJDODBBZ.js";
-import "../chunk-NMABWBZN.js";
+import "../chunk-CHOW74WE.js";
 import "../chunk-ABBOA7UD.js";
-import "../chunk-Q5U6FMDI.js";
+import "../chunk-N2H3ZPZY.js";
 import "../chunk-NXL4FFQQ.js";
 
 // dist/mcp/worker.js
@@ -79,6 +84,12 @@ function arg(name) {
   return found ? found.slice(prefix.length) : void 0;
 }
 async function main() {
+  setProjectTrustState("trusted");
+  logExtension({
+    subsystem: "project-trust",
+    level: "debug",
+    message: "mcp-worker: workspace trust belongs to the MCP client; pi trust not consulted"
+  });
   const file = arg("file");
   const cwd = arg("cwd") ?? process.cwd();
   if (!file) {

package/dist/probes/installer.js

@@ -53,30 +53,31 @@ import {
   verifyNpmPackageEntry,
   verifyToolBinary,
   wasLastResolveTransient
-} from "../chunk-OQGFCZJ4.js";
-import "../chunk-RUOG5D2C.js";
-import "../chunk-U3VGR4VU.js";
-import "../chunk-NTUJEGDZ.js";
-import "../chunk-EOKRQ3SA.js";
-import "../chunk-WONERJTP.js";
-import "../chunk-22AVIGXS.js";
-import "../chunk-GVXA6CCE.js";
-import "../chunk-6QIUX4EP.js";
-import "../chunk-VHQLPIRJ.js";
-import "../chunk-VN2AXLEX.js";
+} from "../chunk-66VMUL7Q.js";
+import "../chunk-Q7DUK4LX.js";
+import "../chunk-AW7R2GWG.js";
+import "../chunk-RWWYJ623.js";
+import "../chunk-VRZP76YM.js";
+import "../chunk-QOBUHWHX.js";
+import "../chunk-QILIYSJF.js";
+import "../chunk-6C7JWPCP.js";
+import "../chunk-5NGR67U5.js";
+import "../chunk-C34ZXZ7O.js";
 import "../chunk-BW5KFIQC.js";
 import "../chunk-QYF5S6P6.js";
-import "../chunk-5ZEJHV35.js";
-import "../chunk-DQ2NZ7C4.js";
-import "../chunk-VNMT7C64.js";
+import "../chunk-PHDMFAKM.js";
+import "../chunk-2BBLFX75.js";
+import "../chunk-XVF2VVXP.js";
+import "../chunk-ZANLILYD.js";
 import "../chunk-2EECBNC5.js";
-import "../chunk-N3YQJI6O.js";
-import "../chunk-O6TQT6RI.js";
-import "../chunk-5THXD6X5.js";
-import "../chunk-UK3CMEAL.js";
+import "../chunk-JAU72XNY.js";
+import "../chunk-XTMJ7XDT.js";
+import "../chunk-JMYYOTQG.js";
+import "../chunk-QQNQ7SJW.js";
+import "../chunk-AOHZU2BM.js";
 import "../chunk-LJDODBBZ.js";
 import "../chunk-ABBOA7UD.js";
-import "../chunk-Q5U6FMDI.js";
+import "../chunk-N2H3ZPZY.js";
 import "../chunk-NXL4FFQQ.js";
 export {
   GITHUB_TOOLS,

package/docs/ast-grep_rules_catalog.md

@@ -231,7 +231,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `prefer-structured-clone-js` | warning | no | pi-lens | Use structuredClone() instead of JSON.parse(JSON.stringify()) for deep cloning |
 | `strict-equality-js` | warning | yes | pi-lens | Use === instead of == |
 | `strict-inequality-js` | warning | yes | pi-lens | Use !== instead of != |
-| `throw-new-error-js` | error | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
+| `throw-new-error-js` | warning | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
 | `unchecked-throwing-call-js` | error | no | pi-lens | $CALL without try/catch — throws on invalid input |
 | `weak-rsa-key-js` | error | no | pi-lens | Weak RSA key size — use at least 2048 bits |
 
@@ -547,7 +547,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `strict-equality` | warning | yes | pi-lens | Use === instead of == |
 | `strict-inequality` | warning | yes | pi-lens | Use !== instead of != |
 | `switch-without-default` | warning | no | pi-lens | switch has no default clause — values matching no case are silently ignored; add a default (even one that throws) |
-| `throw-new-error` | error | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
+| `throw-new-error` | warning | no | pi-lens | Use new Error() not Error() — explicit construction is clearer |
 | `ts-array-concat-spread` | warning | no | pi-lens | arr.concat([...items]) - use arr.push(...items) or [...arr, ...items] |
 | `ts-array-every-some` | warning | no | pi-lens | arr.map(x => x.prop).every(Boolean) - use arr.every(x => !!x.prop) |
 | `ts-boolean-return-if-else` | warning | no | pi-lens | if/else returning true/false - simplify to return the condition directly |

package/docs/astplayground.md

@@ -17,7 +17,7 @@ The shipped rule set runs in two engines:
 
 | Path | Engine | Source |
 |------|--------|--------|
-| ast-grep LSP (the live path) | upstream binary, auto-installed by `ensureTool` | the binary's `ast-grep` version may be ahead of `npx ast-grep@x` |
+| ast-grep LSP (the live path) | upstream binary, auto-installed by `ensureTool` | the binary's `ast-grep` version may be ahead of the npm `@ast-grep/cli` version |
 | ast-grep napi runner (fallback) | `@ast-grep/napi` npm package, version-pinned in `package.json` | can lag the binary by a release |
 
 The CLI test in `tests/clients/dispatch/runners/ast-grep-catalog-rules.test.ts`

package/docs/configuration.md

@@ -10,6 +10,21 @@ There are **two** pi-lens config files:
 Both files have the same shape, with one exception noted below the example:
 everything LSP-related lives under an `lsp` namespace inside them.
 
+Executable LSP fields from a project config are admitted only when pi has
+marked the project trusted. This includes custom `command` values, command
+overrides, `env`, and `initializationOptions`; an untrusted or older host is
+fail-closed and emits one bounded notice telling you to mark the project
+trusted in pi or upgrade pi. Global config remains trusted, and a project can
+always disable a server. pi-lens does not maintain a second trust setting.
+
+The editor-facing JSON Schema is published at
+[`docs/schema/pi-lens-config-v1.json`](schema/pi-lens-config-v1.json). LSP
+server entries also accept canonical argv arrays, optional `name` (defaulting
+to the map id), `enabled`, `role` (`language` or `auxiliary`), `args`, and
+`rootMarkers`. These new fields are experimental; reserved role, root-policy,
+and timing semantics are inert until their planned catalog slices land, so this
+schema slice does not change server launch behavior.
+
 ```jsonc
 {
   "$schema": "https://raw.githubusercontent.com/apmantza/pi-lens/master/docs/schema/pi-lens-config-v1.json",
@@ -23,8 +38,7 @@ everything LSP-related lives under an `lsp` namespace inside them.
       "my-server": {
         "name": "My Custom LSP",
         "extensions": [".myext"],
-        "command": "my-lsp-server",
-        "args": ["--stdio"],
+        "command": ["my-lsp-server", "--stdio"],
         "covers": ["shellcheck"]
       }
     },
@@ -37,6 +51,10 @@ everything LSP-related lives under an `lsp` namespace inside them.
 }
 ```
 
+An override may also provide an experimental launcher `command` and `env`.
+The built-in server ID and strategy remain in force; only the launcher is
+replaced, and project-sourced launcher fields follow the same pi trust gate.
+
 Each model-facing tool accepts `tools.<name>.enabled` in the config file. Valid
 names include `ast_grep_search`, `ast_grep_replace`, `ast_grep_outline`,
 `lsp_navigation`, `lens_diagnostics`,
@@ -46,6 +64,24 @@ names include `ast_grep_search`, `ast_grep_replace`, `ast_grep_outline`,
 lifecycle tools `session_start`, `turn_end`, and `session_end` remain enabled
 because their host protocols require them.
 
+To see the resolved tool surface, use `/lens-health`; the `effective_config`
+tool provides the full configuration provenance. Bundled skills are managed by
+pi's package-manifest filters.
+
+### Session-start orientation
+
+The session-start orientation names only the tools pi-lens actually registered.
+A tool disabled with `tools.<name>.enabled: false` is never advertised, so the
+orientation cannot direct the agent to a tool it cannot call. The tool roster is
+the same registry that drives registration; there is no second list.
+
+`contextInjection.requirePreExistingFixes` (default `true`) controls one
+sentence in that orientation: whether pre-existing blocking errors must be
+fixed. Set it to `false` when the task's scope excludes pre-existing debt. The
+orientation then requires fixes only for blocking errors the agent's own edits
+introduce; pre-existing ones are reported, not demanded. It is a global setting,
+like every `contextInjection` key.
+
 ### `lsp.servers.<id>.covers` — declaring which runners a custom server subsumes
 
 A custom server entry accepts an optional `covers` array naming dispatch

package/docs/custom-rules.md

@@ -1,6 +1,6 @@
 # Custom Rules
 
-pi-lens picks up project-local rules automatically alongside its built-ins.
+pi-lens picks up project-local and user-level rules automatically alongside its built-ins.
 Drop YAML files in the right directory and they are active on the next file dispatch — no config required.
 
 > For the full list of bundled rules per language, see the generated catalogs:
@@ -20,7 +20,30 @@ your-project/
         my-rule.yml        ← ast-grep rule, overrides built-in with same id
 ```
 
-Project ast-grep rules are fingerprinted by relative path and contents, so in-place edits, renames, additions, and removals take effect within one tool call even when mtimes are preserved. Tree-sitter rules retain their directory-mtime cache.
+Both rule families are fingerprinted by relative path and contents, so in-place edits, renames, additions, and removals are picked up without a restart, even when mtimes are preserved.
+
+### When an edit takes effect
+
+A per-file dispatch reads the rule corpus fresh every time: its cache key is a
+content fingerprint of every rule file the language's rule set is built from,
+so an edit, addition, or removal is live on the next dispatched file.
+
+Whole-project surfaces — a project scan and a structural search — reuse a
+corpus fingerprint computed once per turn, so a rule edit lands on the next
+turn, or immediately if any file is dispatched in between (a dispatch
+republishes the fresh fingerprint for the rest of that turn). This is what
+keeps a warm scan at the cost of a string comparison instead of re-reading
+every rule file on every call.
+
+### User-level rules
+
+Rules shared across projects live under the relocatable machine-data directory:
+`<PI_LENS_HOME>/rules/` (or the platform default pi-lens directory when
+`PI_LENS_HOME` is unset). Use the same `tree-sitter-queries/` and
+`ast-grep-rules/` layout shown above. Precedence is project > user > bundled;
+when rule IDs collide, the higher tier wins and the lower definition is
+shadowed from execution. User rules are part of the same fingerprints as
+project rules, so they follow the same timing above.
 
 ---
 

package/docs/dependencies.md

@@ -28,6 +28,7 @@ Auto-install behavior depends on gate type:
 | `shellcheck`                        | Shell script linting             | Yes            | GitHub release                     |
 | `shfmt`                             | Shell script formatting          | Yes            | GitHub release                     |
 | `rust-analyzer`                     | Rust LSP                         | Yes            | GitHub release                     |
+| `lake serve`                        | Lean 4 LSP                       | No             | `lake` must be on PATH; uses the project's Lean toolchain |
 | `golangci-lint`                     | Go linting                       | Yes            | GitHub release                     |
 | `hadolint`                          | Dockerfile linting               | Yes            | GitHub release                     |
 | `ktlint`                            | Kotlin linting                   | Yes            | GitHub release                     |
@@ -51,6 +52,8 @@ Auto-install behavior depends on gate type:
 | `trivy`                             | Dependency-CVE session scan      | Auto-install   | Explicit opt-in (`trivy.enabled`)  |
 | `psscriptanalyzer`                  | PowerShell linting               | Manual         | —                                  |
 
+Lean LSP is launched as `lake serve` from the detected Lake project root, so elan selects the toolchain from that project's `lean-toolchain` file and Lake supplies its project environment. pi-lens does not install or manage Lean/elan; install Lean and Lake separately and ensure `lake` is on `PATH`.
+
 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.
 
 ## Pip tool installation order

package/docs/environment-variables.md

@@ -104,12 +104,14 @@ without changing the steady-state behaviour of an interactive session.
 
 ### `PI_LENS_STARTUP_SCAN_VERDICT_TTL_MS`
 
-How long (ms) a persisted `too-many-source-files` startup-scan verdict is
-trusted before the source-file count is re-walked (default 24h). The verdict
-is cached in the project snapshot so repeated `pi -p` runs in a very large
-repo skip the counting walk entirely; a repo that shrinks below the threshold
-recovers when the TTL expires. Other verdicts use content-based freshness and
-ignore this setting.
+How long (ms) a persisted size-skip startup-scan verdict (`too-many-source-files`
+or `too-many-entries`) is trusted before the project is re-walked (default
+24h). The verdict is cached in the project snapshot so repeated `pi -p` runs in
+a very large repo skip the counting walk entirely; a repo that shrinks below
+the threshold recovers when the TTL expires. The verdict also records the
+bounds that produced it (`maxProjectFiles`, `PI_LENS_STARTUP_SCAN_MAX_ENTRIES`),
+so raising either one invalidates it at once and the next session re-walks.
+Other verdicts use content-based freshness and ignore this setting.
 
 ## Scale and limits
 
@@ -144,6 +146,24 @@ Minimum wall-clock budget (ms) for every dispatch runner; the effective timeout
 is `max(runner budget, floor)`. **Default:** `0` (no floor). Also settable via
 the `dispatch.runnerTimeoutFloorMs` config key, which wins when both are set.
 
+### `PI_LENS_WORD_INDEX_MEMO_BACKSTOP_MS`
+
+Backstop (ms) for the word index's serialized memo, which is also its
+incremental-serialize cache: it is kept while a run edits (so each per-edit
+persist stays O(dirty tokens)) and released once per run at `agent_settled`.
+The backstop releases it when no persist has refreshed it for this long, for a
+host that never emits `agent_settled` and for a stalled run. It is re-armed by
+every serialize and never keeps the process alive. **Default:** `600000` (10
+minutes). `0`, a negative or a non-numeric value means the default (a backstop
+that fired at once would switch the memo off), and a value above `2147483647`
+(about 24.8 days, Node's largest timer delay) is clamped to it. The default is
+deliberately conservative: the maintainer's
+`latency.log` held only two intra-run gaps between `project_snapshot_persist`
+records (5.8 s), too few to derive a percentile. A release leaves one
+`word_index_memo_released` row in `latency.log` (`trigger`: `settle`,
+`post_settle_persist` or `backstop`). Releasing costs the next persist a full
+re-serialize.
+
 ## Install control
 
 ### `PI_LENS_DISABLE_LSP_INSTALL`
@@ -268,6 +288,14 @@ nightly measurement behind each declaration, is in
 When unset or invalid, `PI_LENS_TS_IDLE_EVICT_MS` (below) is read.
 **Default:** 20 minutes (`1200000`).
 
+### `PI_LENS_EPHEMERAL_LSP_IDLE_EVICT_MS`
+
+Idle window (ms) for language-service clients whose workspace is inside a
+temporary or ephemeral Git checkout. This overrides the shared window above
+for those roots; when unset or invalid, the default is 60 seconds (`60000`).
+The nightly idle-eviction measurement temporarily sets this variable alongside
+`PI_LENS_LSP_IDLE_EVICT_MS` so both root policies are measured.
+
 ### `PI_LENS_TS_IDLE_EVICT_MS`
 
 The original, TypeScript-named spelling of the same window, retained for

package/docs/features.md

@@ -2,7 +2,7 @@
 
 ### LSP Support
 
-pi-lens includes **48 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server is not installed, pi-lens offers an interactive install prompt.
+pi-lens includes **49 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — see below). LSP is **enabled by default**; use `--no-lsp` to disable it for a session. Servers are auto-discovered from PATH, project `node_modules`, and managed installs. When a server with a managed installer is not installed, pi-lens offers an interactive install prompt; toolchain-bundled servers, such as Lean's `lake`, are PATH-only, and pi-lens never installs or manages them.
 
 **LSP Idle Management:** LSP servers shut down after 240 seconds of inactivity (no files modified) to free resources. The timer resets when you resume editing, preventing cold-start penalties during active development.
 
@@ -19,7 +19,7 @@ pi-lens includes **48 language server definitions** (including four cross-cuttin
 - **`capabilities`** — shows which operations are supported by the active LSP server(s) for a file, read directly from the cached `initialize` response (no round-trip).
 - **Symbol column resolution** — passing `symbol: "myFunc"` instead of an exact `character` position resolves the correct column automatically. Use `symbol: "foo#2"` for the second occurrence of `foo` on the line.
 
-LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Typst (tinymist), Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Shuck (zsh-aware shell language server), Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
+LSP servers for: TypeScript, Deno, Python (pyright/basedpyright + jedi), Go, Rust, Ruby (ruby-lsp + solargraph), PHP, PowerShell, C# (omnisharp), F#, Java (JDT LS, with Lombok javaagent support when a Lombok jar is available), Kotlin, Lean, Swift, Dart, Lua, C/C++, Zig, Haskell, Elixir, Gleam, Typst (tinymist), Markdown (marksman), OCaml, Clojure, CUE (syntax and parse diagnostics; evaluation errors via the cue-vet auxiliary runner), Terraform, Nix, Bash, Shuck (zsh-aware shell language server), Fish, CMake, Docker, YAML, JSON, HTML, TOML, Prisma, Vue, Svelte, CSS.
 
 ### Formatters
 
@@ -183,7 +183,7 @@ pi-lens MCP server expose the same shape to Claude Code / any MCP client.
 
 At `turn_end`, pi-lens writes `<project-data-dir>/cache/actionable-warnings.json` summarizing fixable warnings introduced by the current turn. This powers the optional conservative autofix at `agent_end`.
 
-`<project-data-dir>` is whatever `getProjectDataDir(cwd)` resolves to: `<project>/.pi-lens` only when that legacy directory already exists, otherwise `~/.pi-lens/projects/<project-slug>` (or a `PILENS_DATA_DIR` location). The turn-end advisory points at `lens_diagnostics mode=delta` first and names the resolved file second, so you never have to work the layout out by hand (#2521).
+`<project-data-dir>` is whatever `getProjectDataDir(cwd)` resolves to: `<project>/.pi-lens` only when that legacy directory already exists when the process first resolves the root (a `.pi-lens` created mid-process takes effect at the next process start), otherwise `~/.pi-lens/projects/<project-slug>` (or a `PILENS_DATA_DIR` location). The turn-end advisory points at `lens_diagnostics mode=delta` first and names the resolved file second, so you never have to work the layout out by hand (#2521).
 
 **Report contents:**
 
@@ -234,6 +234,42 @@ One event per logical write batch (not per file) — e.g. a single eslint `--fix
 
 **Kill switch:** `PI_LENS_BUS_PUBLISH=0` disables publishing entirely (see `docs/environment-variables.md`). Publishing is fire-and-forget — a disabled/unavailable/throwing bus never affects the write path's own success or latency.
 
+### Bus Events — `pilens:format:*` (#673)
+
+Deferred formatting has a separate lifecycle on the same `pi.events` bus:
+
+```
+pilens:format:queued  { v: 1, source: "pi-lens", filePath, cwd, tool, kinds,
+                        ownerSessionId?, turnIndex?, batchId? }
+pilens:format:start   { v: 1, source: "pi-lens", cwd, paths, fileCount, kinds,
+                        ownerSessionId?, turnIndex?, batchId? }
+pilens:format:done    { v: 1, source: "pi-lens", cwd, paths, fileCount, kinds,
+                        ownerSessionId?, turnIndex?, batchId?, settled? }
+```
+
+Paths and `cwd` are absolute, normalized strings. `queued` is emitted when a
+file first enters the deferred queue; `start` is emitted when a non-empty
+claimed format batch begins; and `done` is emitted after all formatters in that
+batch and any late-write resyncs have settled. `paths: []` on `done` means the
+batch changed no bytes. `batchId` is process-unique and monotonic across
+coordinator generations, so
+two same-millisecond reloads cannot share a lifecycle identity. A normal
+`pilens:format:done` has `settled: true` (or omits the additive field for old
+producers). If the formatter remains unsettled after the bounded hook/format
+drain, pi-lens emits one terminal `pilens:format:done` with `settled: false`
+and the still-pending paths, and records one `deferred-format-unsettled`
+degradation for that batch. A later formatter write is resynced by the late
+continuation and does not emit a second done event.
+The session and turn fields let a listener match the lifecycle to its own
+session and turn; consumers must not infer ownership from paths or timing.
+
+These are visibility events, not a flush API. They are fire-and-forget and can
+be absent when the bus is disabled, unwired, stale, or throws. Replaced-session
+and aborted drains publish only for work they actually claim and finish; work
+requeued for its owner is not
+announced as done by the replacing session. The events are additive v1 schemas
+and may gain optional fields without a version bump.
+
 **Fix provenance (#502):** `FilesTouchedPayload` gained an additive, optional `fixes` field so a diff/review consumer can distinguish a pi-lens-mechanical hunk from an agent edit:
 
 ```

package/docs/globalconfig.md

@@ -112,6 +112,8 @@ Hide the diagnostics widget by default, run formatting immediately after write/e
 
 `contextInjection.enabled` (default `true`) controls whether pi-lens prepends automatic findings — session-start guidance, turn-end findings, and test findings — into the next model turn. Set it to `false` (or use `--no-lens-context` / `PI_LENS_NO_CONTEXT_INJECTION=1` / `/lens-context-toggle`) to keep tools, LSP, read-guard, and formatting running while avoiding the prompt-cache invalidation that injected messages cause in long, cache-sensitive sessions. Findings are still cached, so `lens_diagnostics` and `/lens-health` keep working.
 
+`contextInjection.requirePreExistingFixes` (default `true`) controls whether the session-start orientation tells the agent to fix pre-existing blocking errors; set `false` to scope that demand to errors its own edits introduce.
+
 `actionableWarnings.enabled` gates the turn_end report. `includeLspCodeActions` fetches LSP code actions for each warning (requires an active language server). `deltaOnly` (default `true`) limits the report to lines touched in the current turn. `autoFix.enabled` applies conservative LSP quickfixes at `agent_end`; `autoFix.maxFixes` caps the number applied per turn (default `5`, must be a non-negative whole number). `maxFixes: 0` keeps the report and applies nothing, which is a useful halfway step before enabling `autoFix` for real. Unlike the toggles in the table above there is no CLI counterpart, since it takes a number rather than being on or off.
 
 `turnEnd.madge.enabled` (default `false`) runs the per-turn-end madge circular-dependency check on import-changed files. It is off by default because that pass only writes debug output — user-facing madge diagnostics come from the session-start scan cache and the `lens_diagnostics` extractor — and its subprocess spawns dominated the turn-end latency tail (#766). Enable it with `--lens-turn-end-madge` or `turnEnd.madge.enabled: true` if you want the per-edit circular-dependency note.
@@ -263,7 +265,7 @@ not corrupt delta baselines.
 
 ### `maxProjectFiles`
 
-Single scale knob (default `2000`) that a large-but-healthy repo can raise to scale five independent size budgets together instead of tripping each one separately: the project-diagnostics scanner (0.25×, default 500 files), the review graph (0.5× up to a point, default 1,000 files — see below), the startup scan (1×, default 2,000 source files), jscpd (3×, default 6,000 directory entries), and the word index (3×, default 6,000 files). Raising it (e.g. to `5000`) scales all five proportionally. Each subsystem's own environment-variable override (e.g. `PI_LENS_REVIEW_GRAPH_MAX_FILES`, `PI_LENS_STARTUP_SCAN_MAX_ENTRIES`) still takes precedence over this knob when set, and a separate `PI_LENS_MAX_PROJECT_FILES` environment variable sits below `maxProjectFiles` but above the built-in default. See `clients/project-scale.ts` for the full ratio table and precedence order.
+Single scale knob (default `2000`) that a large-but-healthy repo can raise to scale five independent size budgets together instead of tripping each one separately: the project-diagnostics scanner (0.25×, default 500 files), the review graph (0.5× up to a point, default 1,000 files — see below), the startup scan (1.25×, default 2,500 source files), jscpd (3×, default 6,000 directory entries), and the word index (3×, default 6,000 files). Raising it (e.g. to `5000`) scales all five proportionally. Each subsystem's own environment-variable override (e.g. `PI_LENS_REVIEW_GRAPH_MAX_FILES`, `PI_LENS_STARTUP_SCAN_MAX_ENTRIES`) still takes precedence over this knob when set, and a separate `PI_LENS_MAX_PROJECT_FILES` environment variable sits below `maxProjectFiles` but above the built-in default. See `clients/project-scale.ts` for the full ratio table and precedence order.
 
 Unlike the other four, the review graph's budget stops scaling flatly at 0.5× once `maxProjectFiles` climbs past 4,000 — it tapers toward a 5,000-file ceiling instead of growing unbounded (#775). Its higher per-file cold-build cost bounds this default file budget independently of the graph's disk-persist circuit-breaker, whose measured default is now 500,000 elements (#936; override with `PI_LENS_GRAPH_PERSIST_MAX_ELEMENTS`). An over-cap graph persists a centrality-ranked partial snapshot with explicit total-versus-persisted coverage; read-only orientation may use it, but incremental builds never reuse it as a complete base. Below the 4,000 threshold (which covers every typical/default-sized project) it's the same flat 0.5× ratio as before. See `reviewGraph.maxFiles` below for an explicit opt-in past the taper.
 

package/docs/language-coverage.md

@@ -1,6 +1,6 @@
 # Language Coverage
 
-pi-lens supports **36+ languages** through dispatch runners and LSP integration.
+pi-lens supports **37+ languages** through dispatch runners and LSP integration.
 
 Formatting uses a single selected formatter per file: explicit project config wins, otherwise pi-lens uses a smart default where supported, and config-first ecosystems do not autoformat without config.
 
@@ -33,6 +33,7 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | Java                  | ✓   | lsp, javac                                                                                                     | google-java-format      |
 | Java + Lombok         | ✓   | JDT LS launched with `-javaagent:<lombok.jar>` when Lombok is detected and a jar is found (`PI_LENS_LOMBOK_JAR` / `LOMBOK_JAR`, project `.lombok/lombok.jar`, or Maven/Gradle cache) | google-java-format      |
 | Kotlin                | ✓   | lsp, ktlint, detekt                                                                                            | ktlint                  |
+| Lean 4                | ✓ (Lake `serve`) | lsp; uses each project's Lake toolchain and environment                                               | —                       |
 | Swift                 | ✓   | lsp, swiftlint                                                                                                 | swiftformat             |
 | Dart                  | ✓   | lsp, dart-analyze                                                                                              | dart format             |
 | Lua                   | ✓   | lsp                                                                                                            | stylua                  |

package/docs/lsp-capability-matrix.md

@@ -1,5 +1,22 @@
 # LSP capability matrix — affirmative-clean-signal strategy
 
+## Project-code trust class (#4269)
+
+Some global language-server binaries execute repository-owned build, plugin, or
+macro code while starting or indexing. The built-in registry marks these with
+`executesProjectCode`; the launch gate refuses them unless pi reports the
+project as trusted. Unknown trust is a `spawn-failed` refusal, not
+`tool-not-found`, and does not install or retry the server. The class currently
+includes rust-analyzer (Cargo `build.rs` and proc macros), Ruby LSP
+(Bundler/Gemfile composed-bundle setup), PowerShell Editor Services (workspace
+modules), C# / F# servers (MSBuild targets), JDT LS and Kotlin (Gradle/Maven),
+SourceKit-LSP (SwiftPM plugins), Haskell Language Server (Cabal/Stack and
+Template Haskell), ElixirLS / Expert (`mix compile`), and the project-configured
+analysis servers whose startup evaluates workspace configuration: Dart, ZLS,
+OCaml, Clojure, Terraform, Nix, CMake, Vue, and Svelte. Lean is tracked by
+#4122 and will declare itself when that change lands. gopls is excluded: its
+startup/index discovery uses `go list`; cgo is not compiled by gopls startup.
+
 How pi-lens knows a just-edited file is **clean** (no diagnostics) vs the server
 simply **hasn't answered yet** (cold/crashed/silent). pi-lens waits *synchronously*
 for a verdict, so — unlike an editor, which renders asynchronously and never needs
@@ -68,8 +85,10 @@ discriminator either.
 
 `tests/config/lsp-first-publish-census.test.ts` compares this column against the
 `emptyFirstPublish` markers and reds in BOTH directions, which is the expiry
-check: when the nightly re-measures a server into a different class, the docs
-refresh cannot merge until the marker is updated with it.
+check: when two consecutive nights re-measure a server into a different class,
+the docs refresh commits the confirmed class and the marker must move with it.
+A single-night flip remains in the refresh-state JSON below and does not change
+the census's confirmed population.
 
 ## The strategies
 
@@ -148,7 +167,7 @@ carries the named admission until then.
 | deno | deno (alt of typescript) | pull | — | n/a (pull) | 1 | dev+ci |
 | ruby | ruby-lsp | pull | — | n/a (pull) | 1 | ci |
 | csharp | csharp-ls | pull | — | n/a (pull) | 1 | ci |
-| typescript | typescript-language-server | push-only | silent | direct | 3 | dev+ci |
+| typescript | typescript-language-server | push-only | silent | empty-first | 3 | dev+ci |
 | markdown | marksman | push-only | silent | direct | 3 | ci |
 | lua | lua-language-server | push-only | silent | direct | 3 | dev+ci |
 | python | pyright | push-only | publishes-versioned | direct | 2 | dev+ci |
@@ -156,6 +175,7 @@ carries the named admission until then.
 | yaml | yaml-language-server | push-only | publishes-unversioned | direct | 2* | dev+ci |
 | shell | bash-language-server | push-only | publishes-versioned | direct | 2 | dev+ci |
 | dockerfile | docker-langserver | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| dockerfile-official | docker-language-server (official) | push-only | publishes-versioned | direct | 2 | dev+ci |
 | toml | taplo | push-only | publishes-unversioned | direct | 2* | dev+ci |
 | terraform | terraform-ls | push-only | publishes-unversioned | empty-first | 2* | dev+ci |
 | prisma | @prisma/language-server | push-only | publishes-unversioned | direct | 2* | dev+ci |
@@ -210,6 +230,9 @@ and were characterized `push-only` in the run above).
   `first-publish` measurements on the dev box, 2026-09-23: php `empty-first`,
   typescript / opengrep / ast-grep / marksman `direct` (so the class does not
   extend to them on the measurement, whatever their comments suggest).
+- The official Docker row's clean-gate witness requires the BuildKit-backed
+  `JSONArgsRecommended` rule and skips when `docker buildx` is unavailable;
+  its first-publish class is the nightly's measured `direct`.
 - **#458's learned-deadline target set = the tier-3 rows only.** 2\* rows resolve
   the wait at runtime and must NOT be given learned deadlines.
 - **Tier 3 is budget-bound by necessity**, not laziness: a silent server's silence is
@@ -255,10 +278,10 @@ _None observed as of the last probe run._
 
 ## Capability matrix refresh state (nightly-generated)
 
-Bookkeeping for the date-based `direct` `first-publish` expiry (#3401), the
-two-run `clean-behavior` hysteresis and the consecutive-night `idle-eviction`
+Bookkeeping for the two-run `first-publish`/`clean-behavior` hysteresis, the
+date-based `direct` expiry (#3401) and consecutive-night `idle-eviction`
 counts (#3989). Regenerated every run; never a measurement.
 
 ```json
-{"idle-eviction":{"docker":{"nights":[{"day":"2026-10-07","rssMb":64,"coldMs":566}]},"json":{"nights":[{"day":"2026-10-07","rssMb":67,"coldMs":1116}]},"powershell":{"nights":[{"day":"2026-10-07","rssMb":155,"coldMs":2601}]},"python-jedi":{"nights":[{"day":"2026-10-07","rssMb":51,"coldMs":1796}]},"zizmor":{"nights":[{"day":"2026-10-07","rssMb":58,"coldMs":608}]}}}
+{"first-publish":{"dockerfile":{"firstMissed":"2026-10-10"},"prisma":{"firstMissed":"2026-10-10"},"python":{"firstMissed":"2026-10-10"},"shell":{"firstMissed":"2026-10-10"},"terraform":{"pendingFirstPublish":"direct","runs":1},"yaml":{"firstMissed":"2026-10-10"}}}
 ```