pi-lens 4.4.7 → 4.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/CHANGELOG-USER.md +31 -0
  2. package/CHANGELOG.md +327 -0
  3. package/README.md +13 -2
  4. package/config/dependency-cruiser-eager-allowlist.json +1 -1
  5. package/config/markdownlint/run-no-fix.mjs +36 -0
  6. package/dist/{chunk-4LM3VAZH.js → chunk-2VZ3VN3N.js} +2 -2
  7. package/dist/{chunk-PUZ3E2J4.js → chunk-3HTZDY3C.js} +8 -6
  8. package/dist/{chunk-RORGS5II.js → chunk-3NPWO5UO.js} +7 -13
  9. package/dist/{chunk-MNJIXFX4.js → chunk-47UCC4MM.js} +1 -1
  10. package/dist/chunk-4ENEJHF4.js +198 -0
  11. package/dist/chunk-5GEYJJHG.js +22 -0
  12. package/dist/{chunk-U6VN4NVL.js → chunk-5YSEQHJN.js} +3 -3
  13. package/dist/{chunk-6IR3ZYIB.js → chunk-6GPB3JLL.js} +3 -3
  14. package/dist/{chunk-MB6PXBUA.js → chunk-7R5GZIA6.js} +7 -15
  15. package/dist/{chunk-DH5JPM3K.js → chunk-7UTSNTWM.js} +10 -9
  16. package/dist/{chunk-24BILSZW.js → chunk-7YTRG6YW.js} +2 -2
  17. package/dist/{chunk-KW5JQPO5.js → chunk-AACN5GNE.js} +2 -2
  18. package/dist/{chunk-PKES3ISE.js → chunk-ACRJ2GZ5.js} +2 -2
  19. package/dist/{chunk-4ZYJHQMB.js → chunk-C3YRO3EU.js} +10 -12
  20. package/dist/{chunk-PQJFG24Z.js → chunk-CB7PEVOJ.js} +1300 -946
  21. package/dist/{chunk-ABPKUVA4.js → chunk-CDFJF5YD.js} +1 -1
  22. package/dist/{chunk-T7A2HK2B.js → chunk-CJS6WE66.js} +17 -18
  23. package/dist/{chunk-3YY7IXIL.js → chunk-CM6BDY4E.js} +14 -60
  24. package/dist/{chunk-RZOXUSPC.js → chunk-CZCAZVTD.js} +16 -2
  25. package/dist/chunk-DGKFWQK4.js +23 -0
  26. package/dist/{chunk-NA7SEXHE.js → chunk-E65WJVI5.js} +7 -9
  27. package/dist/{chunk-2TF6RXWB.js → chunk-EKNYSXFB.js} +8 -10
  28. package/dist/{chunk-RRV3FNNM.js → chunk-EY6LY2HO.js} +27 -30
  29. package/dist/{chunk-LBLBAFG3.js → chunk-F6BEQWAK.js} +17 -5
  30. package/dist/{chunk-4L36HG27.js → chunk-FGNSESAC.js} +12 -14
  31. package/dist/{chunk-3FRLWYBG.js → chunk-FRUBVFXV.js} +39 -42
  32. package/dist/{chunk-FB5SCCPT.js → chunk-G22UNQID.js} +14 -15
  33. package/dist/{chunk-LV4UMYVH.js → chunk-GQTQUNCG.js} +26 -27
  34. package/dist/{chunk-E7HJ56Y7.js → chunk-H3BVMK47.js} +64 -73
  35. package/dist/chunk-H6FLQ5NW.js +28 -0
  36. package/dist/{chunk-QHSNL7B2.js → chunk-HEA3EM23.js} +15 -19
  37. package/dist/{chunk-AWDSEDER.js → chunk-HSOBIN22.js} +2 -2
  38. package/dist/{chunk-EAOK7MIZ.js → chunk-HYSKJMZK.js} +17 -4
  39. package/dist/{chunk-VUZWQ7UG.js → chunk-IICERRFF.js} +46 -72
  40. package/dist/{chunk-OXOI55RU.js → chunk-IILEH3ZC.js} +8 -10
  41. package/dist/{chunk-ZKXQKGWZ.js → chunk-J3Q2NYJR.js} +4 -3
  42. package/dist/{chunk-YHC2O2WO.js → chunk-JUZ67QZQ.js} +20 -9
  43. package/dist/chunk-KR5VGMVT.js +25 -0
  44. package/dist/{chunk-F7K5IBZG.js → chunk-KV6GQOGN.js} +41 -44
  45. package/dist/{chunk-SNDXCFRS.js → chunk-KXMJLOZF.js} +25 -23
  46. package/dist/{chunk-CB4WHS4H.js → chunk-L4Y3ROKQ.js} +3 -3
  47. package/dist/{chunk-3F6BMY53.js → chunk-L6WBJGQS.js} +1 -1
  48. package/dist/{chunk-MPKRJBPK.js → chunk-L7O774U7.js} +30 -32
  49. package/dist/{chunk-URCQWAQ4.js → chunk-LAHHGNAY.js} +21 -21
  50. package/dist/{chunk-V63BC55Q.js → chunk-LT62P654.js} +1 -1
  51. package/dist/{chunk-ZMAUPOMG.js → chunk-LWOM6LVS.js} +34 -34
  52. package/dist/{chunk-HO6LWE2E.js → chunk-MKPDIAZH.js} +21 -1
  53. package/dist/{chunk-2PHMIAKO.js → chunk-MN635QYA.js} +3 -4
  54. package/dist/{chunk-KDX35VXP.js → chunk-MQ4PPCJB.js} +166 -149
  55. package/dist/{chunk-QOE342SU.js → chunk-MRLH4MYU.js} +2 -2
  56. package/dist/{chunk-CE6VMBCB.js → chunk-N56BNAA6.js} +20 -21
  57. package/dist/{chunk-L3CMBQMH.js → chunk-N5CEGQPG.js} +14 -17
  58. package/dist/{chunk-7E2563GA.js → chunk-NCLO6E6N.js} +13 -33
  59. package/dist/{chunk-J6JP25XU.js → chunk-NL5LSKVD.js} +4 -3
  60. package/dist/{chunk-U7BD2QL7.js → chunk-NMUSOZ2D.js} +10 -12
  61. package/dist/{chunk-BZARLRJW.js → chunk-NOWH2VA2.js} +8 -33
  62. package/dist/{chunk-U2SDMG7C.js → chunk-NUSXS6YB.js} +6 -5
  63. package/dist/{chunk-ZJTT47IG.js → chunk-OSEKJEUU.js} +2 -2
  64. package/dist/{chunk-FZKFVUEC.js → chunk-OUYAUXAT.js} +647 -355
  65. package/dist/{chunk-ZE3KXHS7.js → chunk-PBZNYHMM.js} +84 -4
  66. package/dist/{chunk-U5HPROLA.js → chunk-PIIUNJIT.js} +2 -4
  67. package/dist/chunk-PKLB2XJL.js +8 -0
  68. package/dist/{chunk-RC2Z6K47.js → chunk-PRHYIA6X.js} +15 -6
  69. package/dist/{chunk-RQS4QQSD.js → chunk-PXQ45SGD.js} +2 -2
  70. package/dist/chunk-Q6JQKWPK.js +25 -0
  71. package/dist/{chunk-F6X3YJWD.js → chunk-QB7T2PHK.js} +2 -2
  72. package/dist/{chunk-TIQJPRDD.js → chunk-QGITU23N.js} +3 -2
  73. package/dist/chunk-QJJKOHLH.js +57 -0
  74. package/dist/{chunk-4LOE5R5P.js → chunk-QP33NKYC.js} +18 -15
  75. package/dist/{chunk-N5WSK2K7.js → chunk-QVBOXT3L.js} +12 -17
  76. package/dist/{chunk-DPGEAHZT.js → chunk-RNJFRXEN.js} +10 -18
  77. package/dist/{chunk-EKWX4WD3.js → chunk-RNXOWDM6.js} +10 -10
  78. package/dist/{chunk-O4BJFESU.js → chunk-RTFMDIKV.js} +1 -1
  79. package/dist/{chunk-LS3QJRUB.js → chunk-SIQHOB6P.js} +11 -13
  80. package/dist/{chunk-3K2F6UDZ.js → chunk-SLSMJPEF.js} +43 -42
  81. package/dist/chunk-T5QSLSMM.js +50 -0
  82. package/dist/chunk-TGQDAG4B.js +88 -0
  83. package/dist/{chunk-4YHYPW2G.js → chunk-THYHUIDR.js} +44 -13
  84. package/dist/{chunk-YVHBNSME.js → chunk-TMNUTMT5.js} +1099 -1100
  85. package/dist/{chunk-WDBICWH3.js → chunk-TOE2RRCS.js} +1 -1
  86. package/dist/chunk-TYHPVE5H.js +25 -0
  87. package/dist/chunk-UAKO2M6B.js +73 -0
  88. package/dist/chunk-UC5AXW5Z.js +20 -0
  89. package/dist/chunk-UTJP6WOS.js +28 -0
  90. package/dist/{chunk-DQZFQSR5.js → chunk-UXTQ3QPD.js} +4 -4
  91. package/dist/chunk-UYXV5NIS.js +20 -0
  92. package/dist/{chunk-KKCK636N.js → chunk-V2WDBOLZ.js} +10 -12
  93. package/dist/{chunk-PR6PO3ES.js → chunk-V67D6TMU.js} +22 -20
  94. package/dist/{chunk-VSFLRN5Y.js → chunk-VCRVNLE7.js} +135 -2
  95. package/dist/{chunk-CPSR3AVL.js → chunk-VO4JFPTV.js} +2 -2
  96. package/dist/{chunk-XT2HTCJ5.js → chunk-VWLSU3XV.js} +6 -5
  97. package/dist/{chunk-WME2OQST.js → chunk-W5E72HJA.js} +66 -24
  98. package/dist/{chunk-LLS45EWB.js → chunk-W7TY6HYX.js} +6 -8
  99. package/dist/{chunk-CCV2EU7T.js → chunk-WSSLVMDA.js} +12 -13
  100. package/dist/{chunk-YISME6ON.js → chunk-WTB4GKMH.js} +10 -1
  101. package/dist/{chunk-KPPJTH44.js → chunk-X5BJ3G2P.js} +64 -35
  102. package/dist/{chunk-JMEKXFOL.js → chunk-XKFO2SZV.js} +39 -34
  103. package/dist/{chunk-HR3OJ3TH.js → chunk-XLAI7UYY.js} +84 -31
  104. package/dist/{chunk-H7OR7DFZ.js → chunk-XO756WE5.js} +53 -37
  105. package/dist/{chunk-F5Z6URKM.js → chunk-XVB3Q2PG.js} +2 -4
  106. package/dist/{chunk-R5MOQM2H.js → chunk-YOXCCJDF.js} +607 -366
  107. package/dist/{chunk-ZGSJDWQU.js → chunk-ZCQBNPRH.js} +2 -2
  108. package/dist/chunk-ZD4KVFXI.js +234 -0
  109. package/dist/{chunk-WGRJOXED.js → chunk-ZDMFGACN.js} +1295 -966
  110. package/dist/{chunk-OSTKYB55.js → chunk-ZMMHHXSW.js} +1 -1
  111. package/dist/{chunk-75GAYVNO.js → chunk-ZPM7ZIFL.js} +6 -6
  112. package/dist/{chunk-LUBPZN36.js → chunk-ZVCDHYWZ.js} +9 -11
  113. package/dist/{chunk-Y7F7IEE3.js → chunk-ZZN74OGD.js} +102 -7
  114. package/dist/{chunk-L5JYIU47.js → chunk-ZZSJAR76.js} +39 -20
  115. package/dist/index.js +10933 -8644
  116. package/dist/mcp/analyze-cli.js +12 -17
  117. package/dist/mcp/cli.js +43 -42
  118. package/dist/mcp/server.js +3073 -1147
  119. package/dist/mcp/worker.js +61 -61
  120. package/dist/probes/installer.js +18 -19
  121. package/docs/adr/0003-git-guard-latch-writer.md +11 -6
  122. package/docs/agent-tools.md +58 -16
  123. package/docs/alignment-families.md +29 -0
  124. package/docs/analysisall.md +1 -1
  125. package/docs/ast-grep_rules_catalog.md +6 -4
  126. package/docs/ci-bot-pr-checks.md +128 -0
  127. package/docs/configuration.md +150 -12
  128. package/docs/defect-shapes.md +107 -15
  129. package/docs/engineering-principles.md +27 -2
  130. package/docs/environment-variables.md +18 -1
  131. package/docs/features.md +14 -7
  132. package/docs/globalconfig.md +11 -3
  133. package/docs/invariants/git-guard-host.md +7 -3
  134. package/docs/invariants/language-config.md +15 -4
  135. package/docs/invariants/lsp-trust-exec.md +25 -4
  136. package/docs/invariants/paths-os.md +4 -2
  137. package/docs/invariants/session-telemetry.md +2 -2
  138. package/docs/language-coverage.md +1 -0
  139. package/docs/lsp-capability-matrix.md +167 -65
  140. package/docs/lsp-idle-eviction.md +4 -1
  141. package/docs/merge-queue-rollout.md +10 -8
  142. package/docs/module-report-read-symbol.md +34 -23
  143. package/docs/pi-lens-fixer.md +34 -17
  144. package/docs/pi-lens-investigator.md +3 -0
  145. package/docs/pi-lens-merge-policy.md +34 -17
  146. package/docs/pi-lens-monitor.md +9 -0
  147. package/docs/pi-lens-orchestration.md +4 -1
  148. package/docs/pi-lens-reviewer.md +6 -6
  149. package/docs/pi-lens-subagent.md +19 -3
  150. package/docs/public-api-stability.md +57 -7
  151. package/docs/release-qa-baseline.md +7 -4
  152. package/docs/schema/pi-lens-config-v1.json +21 -2
  153. package/docs/servercapabilities.md +3 -1
  154. package/docs/settings.md +11 -7
  155. package/docs/word-index.md +20 -7
  156. package/package.json +11 -4
  157. package/rules/ast-grep-rules/rule-tests/no-accumulating-spread-js-test.yml +37 -0
  158. package/rules/ast-grep-rules/rule-tests/ts-redundant-filter-map-test.yml +12 -1
  159. package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-js-test.yml +12 -0
  160. package/rules/ast-grep-rules/rule-tests-disabled/filter-then-map-test.yml +25 -0
  161. package/rules/ast-grep-rules/rules/no-accumulating-spread-js.yml +49 -1
  162. package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +1 -2
  163. package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +1 -2
  164. package/rules/ast-grep-rules/rules/ts-redundant-filter-map.yml +9 -1
  165. package/rules/ast-grep-rules/rules-disabled/filter-then-map-js.yml +17 -0
  166. package/rules/ast-grep-rules/rules-disabled/filter-then-map.yml +36 -0
  167. package/rules/ast-grep-rules/self-scan-baseline.json +1 -1
  168. package/scripts/download-grammars.js +3 -2
  169. package/skills/pi-lens-lsp-navigation/SKILL.md +5 -1
  170. package/dist/chunk-46TNM7XZ.js +0 -88
  171. package/dist/chunk-72OKUXSD.js +0 -31
  172. package/dist/chunk-7GLOLOSH.js +0 -57
  173. package/dist/chunk-AKUUMGD5.js +0 -26
  174. package/dist/chunk-ASUXV767.js +0 -22
  175. package/dist/chunk-CTADOKYM.js +0 -25
  176. package/dist/chunk-GNSIWBAT.js +0 -106
  177. package/dist/chunk-HWDAVBFU.js +0 -49
  178. package/dist/chunk-JJ2RRESP.js +0 -58
  179. package/dist/chunk-KXF5R4UN.js +0 -48
  180. package/dist/chunk-LSC3VADM.js +0 -23
  181. package/dist/chunk-OE5ZBP7F.js +0 -443
  182. package/dist/chunk-SHLDT3OI.js +0 -27
  183. package/dist/chunk-UF7RTZSO.js +0 -27
  184. package/dist/chunk-W4WP2ERB.js +0 -30
  185. package/dist/chunk-YES5CACN.js +0 -73
  186. package/dist/chunk-Z2XAOKHK.js +0 -136
@@ -10,10 +10,26 @@ There are **two** pi-lens config files:
10
10
  Both files have the same shape, with one exception noted below the example:
11
11
  everything LSP-related lives under an `lsp` namespace inside them.
12
12
 
13
- Executable LSP fields from a project config are admitted only when pi has
14
- marked the project trusted. This includes custom `command` values, command
15
- overrides, `env`, and `initializationOptions`; an untrusted or older host is
16
- fail-closed and emits one bounded notice telling you to mark the project
13
+ LSP fields from a project config are admitted without trust only when they
14
+ are on a short list. On an `lsp.servers.<id>` entry an untrusted project may
15
+ set `name` and nothing else. It may not set `command`, `args`, `extensions`,
16
+ `rootMarkers`, `env`, `initializationOptions`, `covers`, `enabled`, `role`, or
17
+ any field pi-lens does not recognise; on `lsp.serverOverrides.<id>` it may set
18
+ none of `command`, `env`, `initializationOptions`, or any other field. Those
19
+ fields need pi to have marked the project trusted. An untrusted project that
20
+ sets one of them on an `lsp.servers.<id>` entry disables that server for the
21
+ project: pi-lens does not start it, rather than start it on a configuration
22
+ where the project's value replaced one you set in your global config. Under
23
+ `serverOverrides.<id>`, the project's fields are dropped and your global
24
+ override for that built-in applies field by field: a global wrapper `command`
25
+ stays, a global value the project replaced comes back, and a field you did not
26
+ set globally runs on the pi-lens default. The built-in server stays on. Look
27
+ for the `lsp-registry-decision` record: its reason reads "project LSP <field>
28
+ refused for <id>: pi project trust is <state>; the <id> entry is not applied
29
+ for this project" for a server, or "...; the project's <id> override is not
30
+ applied" for an override. An `lsp.servers.<id>` entry with no `extensions`
31
+ list is not registered, since no file can select it. An untrusted or older host
32
+ is fail-closed and emits one bounded notice telling you to mark the project
17
33
  trusted in pi or upgrade pi. Global config remains trusted, and a project can
18
34
  always disable a server. pi-lens does not maintain a second trust setting.
19
35
 
@@ -21,9 +37,14 @@ The editor-facing JSON Schema is published at
21
37
  [`docs/schema/pi-lens-config-v1.json`](schema/pi-lens-config-v1.json). LSP
22
38
  server entries also accept canonical argv arrays, optional `name` (defaulting
23
39
  to the map id), `enabled`, `role` (`language` or `auxiliary`), `args`, and
24
- `rootMarkers`. These new fields are experimental; reserved role, root-policy,
25
- and timing semantics are inert until their planned catalog slices land, so this
26
- schema slice does not change server launch behavior.
40
+ `rootMarkers`. A `command` is either a bare string (launched with `args`,
41
+ default `["--stdio"]`) or an argv array whose first element is the program;
42
+ the array's remaining elements come before `args`, and no `--stdio` is added to
43
+ it. A `command` that is neither, or an empty or non-string array, fails at
44
+ launch with a message naming the field. These new fields are experimental;
45
+ reserved role, root-policy, and timing semantics are inert until their planned
46
+ catalog slices land, so this schema slice does not change server launch
47
+ behavior.
27
48
 
28
49
  ```jsonc
29
50
  {
@@ -231,6 +252,14 @@ once no matter which spelling each file uses. Migrating does not change the
231
252
  answer, staying un-migrated is not a way around the denial, and a half-migrated
232
253
  pair of files merges rather than one clobbering the other.
233
254
 
255
+ An entry must name a server pi-lens knows: a built-in server id or a server
256
+ declared under `lsp.servers`. An entry that names neither is dropped and
257
+ reported with one `PILENS_CFG_0005` notice per distinct id, which quotes the
258
+ entry and says it is not a recognized LSP server id. Without that notice a
259
+ misspelled id would match no server, so the server you meant to turn off would
260
+ keep running. Entries that are not strings are kept as written and match no
261
+ server.
262
+
234
263
  Denying a file's **language server** (its primary, such as `json` or
235
264
  `typescript`) leaves that file unchecked for the language itself. Every
236
265
  diagnostics route then reports a file with no findings as **unconfirmed**, not
@@ -252,6 +281,115 @@ Two rules make the rest of the table unambiguous:
252
281
  same thing as the canonical one, the canonical one is used — otherwise the
253
282
  migration below could never be completed.
254
283
 
284
+ ### `dispatch.disabledRunners` — turning a dispatch runner off
285
+
286
+ `lsp.disabledServers` switches off a language server. A dispatch **runner**
287
+ (a linter, type-checker, or build such as `dotnet-build`, `javac`, or
288
+ `rust-clippy`) has its own denial list, with the same semantics:
289
+
290
+ ```jsonc
291
+ // ~/.pi-lens/config.json (or a project .pi-lens.json)
292
+ { "dispatch": { "disabledRunners": ["dotnet-build"] } }
293
+ ```
294
+
295
+ - **Union across tiers.** Like `lsp.disabledServers`, the list is the union of
296
+ `~/.pi-lens/config.json`, the project `.pi-lens.json`, and any nested
297
+ `.pi-lens.json`. A project can add a runner and can never re-enable one a
298
+ farther tier denied.
299
+ - **The tool never spawns.** The dispatcher skips a disabled runner before its
300
+ precondition and before it runs, so no availability probe, no `dotnet build`,
301
+ nothing. The skip is recorded with the reason `disabled-by-config`
302
+ (`latency.log`, `skipReason`). It is an operator decision, not a failure: it
303
+ raises no blocker and no "tool failed" notice, and a `fallback` group (such as
304
+ C#'s `lsp`, then `dotnet-build`) simply moves on to its next member. The other
305
+ runners of the group, the language server included, run as before.
306
+ - **Unknown ids are dropped, not ignored silently.** An entry that names no
307
+ registered runner is dropped with a `PILENS_CFG_0005` warning that quotes the
308
+ entry, so a typo does not read as a runner that was turned off.
309
+ - **Edits apply on the next dispatch.** The list is resolved for each dispatch,
310
+ so a change to the file needs no restart.
311
+ - **The nearest config owns the file.** A nested `.pi-lens.json` governs the
312
+ files under it, so a denial there applies to those files only. `rules` reads
313
+ the same per-file resolution (see below).
314
+ - **Disabling the only checker leaves the file unconfirmed.** Turning off a
315
+ runner that was the sole check for a file kind produces a notice that names
316
+ `dispatch.disabledRunners` (once per session, then the status line alone)
317
+ rather than a clean result. When another runner of the file is missing,
318
+ timed out, or failed as well, the notice says so and names the denial beside
319
+ it.
320
+
321
+ `pilens_effective_config file=Program.cs` reports the runner as denied, with the
322
+ tier and file that denied it, while the language server stays selected:
323
+
324
+ ```console
325
+ $ pilens_effective_config file=src/Program.cs
326
+ tools:
327
+ lsp selected
328
+ dotnet-build ✗ disabled-by-config (global ~/.pi-lens/config.json → /dispatch/disabledRunners/0)
329
+ ```
330
+
331
+ `dispatch.runnerTimeoutFloorMs`, the other `dispatch` key, stays global-only.
332
+ Putting it in a project `.pi-lens.json` logs the usual one-time "global-only"
333
+ notice.
334
+
335
+ ### `rules.<id>` — read from each file's own config
336
+
337
+ `rules.<id>.disable`, `select`, and `ignorePaths` are resolved for each file
338
+ from the nearest directory at or above it that holds a `.pi-lens.json`, up to
339
+ the workspace root. That resolution layers the global file, the workspace
340
+ root's file, and every nested file between, by the field-wise order above. So a
341
+ nested `.pi-lens.json` governs the files under it and no others, and the
342
+ workspace root's policy still reaches them. Every surface that filters by rule
343
+ policy reads it this way: the per-edit dispatch, `lens_diagnostics`,
344
+ `lsp_diagnostics`, and the turn-end advisories.
345
+
346
+ `rules.<id>.disable` is a denial, like `lsp.disabledServers`: it resolves as the
347
+ union of every tier's list. A project or nested file can add rules to what the
348
+ global or root file disabled and can never re-enable one. `select` is an
349
+ allowlist, not a denial: per grouping key, the nearest file that sets it supplies
350
+ the whole list. Lists under different keys are unioned, so a global `k.select:
351
+ [x]` and a nearer file's `k2.select: [y]` keep both `x` and `y`.
352
+
353
+ In both lists a member that is not a string, or a value that is not an array,
354
+ is dropped and the valid members keep their effect. A string member is trimmed
355
+ before it is matched, so `" ra "` names `ra`, and a blank member is dropped. The
356
+ global file reports
357
+ each one with a `PILENS_CFG_0005` notice. A project or nested file reports a
358
+ value that is not an array, or a list whose members are all dropped, with the
359
+ same notice; a non-string member beside a valid string is dropped without one.
360
+ A `select` array whose members are all dropped still sets that key's list: it
361
+ is empty, so it lifts a farther file's allowlist for the key, as `select: []`
362
+ does. A `select` that is not an array is ignored, and the farther list stands.
363
+
364
+ `ignorePaths` entries follow the same gitignore rules as the `ignore` field. Each entry is
365
+ relative to the directory of the file that declares it: a global entry, and an entry in the
366
+ workspace root's own file, match against the workspace root, and an entry in `pkg/.pi-lens.json`
367
+ matches under `pkg/`:
368
+
369
+ ```jsonc
370
+ // pkg/.pi-lens.json — carves out pkg/legacy/** except pkg/legacy/keep.ts; nothing at the root
371
+ { "rules": { "no-eval": { "ignorePaths": ["legacy/**", "!legacy/keep.ts"] } } }
372
+ ```
373
+
374
+ - The last matching entry wins, so `!` re-includes a file an earlier entry carved out, and an
375
+ entry placed after a `!` ignores it again.
376
+ - A leading `/` roots the entry at the declaring file's directory: `/legacy/**` is `legacy/**`
377
+ there and nowhere deeper.
378
+ - A trailing `/` names a directory: `legacy/` carves out every directory named `legacy` at any
379
+ depth below the file, and everything in it.
380
+ - An entry with no slash matches at any depth below the file: `*.gen.ts` carves out
381
+ `pkg/a.gen.ts` and `pkg/src/b.gen.ts`. To carve out a whole directory, end the entry with `/` or
382
+ `/**`: a bare `legacy` names a file called `legacy`, not the files inside a directory of that name.
383
+ - An entry that climbs out of the declaring directory, such as `../other/**`, matches nothing.
384
+ A file outside the workspace root is never carved out.
385
+ - A line starting with `#` is a comment, as in `.gitignore`, and is dropped.
386
+
387
+ The files are a union: a path is carved out when any file's entries carve it out. A nearer file
388
+ adds carve-outs and never lifts one, so a `!` entry re-includes only against the entries of its
389
+ own file, and a project `!` cannot clear a carve-out the global config declared. Unlike the
390
+ `ignore` field, `ignorePaths` has no cross-file lift: a nearer file's `!` can lift a path that a
391
+ parent file's `ignore` line hid, but never a path that a parent file's `ignorePaths` entry carves out.
392
+
255
393
  ## Legacy locations (still read; being removed)
256
394
 
257
395
  These are read for their deprecation window and then **removed**. Each one you
@@ -283,14 +421,14 @@ canonical key wins, and the keys you have not moved yet keep working.
283
421
  Only keys pi-lens actually recognizes get "move it to …" advice. A key in a
284
422
  legacy file that is not a pi-lens setting at all — a typo, or a leftover from
285
423
  another tool — cannot be migrated anywhere, so it gets the ordinary
286
- unrecognized-key notice (`PILENS_CFG_0001`) and is counted in ONE whole-file
424
+ unrecognized-key notice (`PILENS_CFG_0004`) and is counted in ONE whole-file
287
425
  `PILENS_CFG_0003` notice for the file rather than being told to move.
288
426
 
289
427
  ## When a config is ignored
290
428
 
291
- A file that cannot be read or parsed is **ignored, never partially applied** —
292
- pi-lens runs on defaults for it and says so once, with the code
293
- `PILENS_CFG_0001`. A field whose value does not match its declared type is
429
+ A file that is unreadable, unparsable, or not a JSON object is **ignored, never
430
+ partially applied** — pi-lens runs on defaults for it and says so once, with the
431
+ code `PILENS_CFG_0001`. A field whose value does not match its declared type is
294
432
  dropped on its own (`PILENS_CFG_0005`), and an unrecognized field is dropped
295
433
  with a message naming the key (`PILENS_CFG_0004`). If resolving a file fails
296
434
  internally the whole file is ignored and said so under its own code
@@ -307,7 +445,7 @@ them rather than by what they say — both are about values that were rejected:
307
445
  deprecation notices (`PILENS_CFG_0002`, `PILENS_CFG_0003`), which share this
308
446
  list;
309
447
  - what the **loader** reading the file produced on its own — unknown top-level
310
- keys and settings it refused (`PILENS_CFG_0001`).
448
+ keys (`PILENS_CFG_0004`) and values it refused (`PILENS_CFG_0005`).
311
449
 
312
450
  Each list is bounded at 20 records: up to 19 notices plus, when the bound bit,
313
451
  a single `PILENS_CFG_0007` summary giving the count that was suppressed, so a
@@ -170,6 +170,9 @@ file-scoped worklist and receives no project-wide scanner output.
170
170
  path discloses its truncation on the rendered surface; a count recorded
171
171
  only in `latency.log` is not disclosure (#3166 r2: an 80-finding input
172
172
  bound zeroed a neighbour's genuine errors, counted only in the log).
173
+ Removing a false "unavailable" notice never turns the file clean: a file
174
+ no analyzer applies to reads "not analyzed" (#5238 r2 read
175
+ `build.gradle` as "Groovy clean" after its notice was dropped).
173
176
  An out-of-session-root project edit records one bounded degradation and
174
177
  uses the existing advisory notice seam; intended vendor skips and pi-owned
175
178
  OS-temp artifacts stay silent (`clients/runtime-tool-result.ts`,
@@ -179,9 +182,12 @@ file-scoped worklist and receives no project-wide scanner output.
179
182
  decides only delivery, and a run with no verdict (failed, unanswered, in
180
183
  flight) observes nothing, so neither retires a recorded blocker. A skip
181
184
  has a verdict only with a stated not-applicable reason
182
- (`RUNNER_SKIP_REASONS`). A recorded blocker is still observed only at its
183
- own line, aligned to the current bytes: another occurrence of the same
184
- rule is not it. A fallback for missing evidence narrows what retires:
185
+ (`RUNNER_SKIP_REASONS`). `not-enabled` (an opt-in runner left off, #5042)
186
+ is the one stated reason that stays a no-verdict: admitting it would retire
187
+ recorded helm-render blockers and stop their owed ranges. A recorded blocker
188
+ is still observed only at its own line, aligned to the current bytes:
189
+ another occurrence of the same rule is not it. A fallback for missing
190
+ evidence narrows what retires:
185
191
  with no alignment, its identity anywhere keeps it. It stays a per-write
186
192
  hold and never widens what counts as the same finding: the match still
187
193
  needs the entry's own line text, and owed lines are matched by content,
@@ -195,6 +201,18 @@ file-scoped worklist and receives no project-wide scanner output.
195
201
  kept entry with no place in a write's bytes is recorded as such
196
202
  (`positionStale`), never inferred later from one line's hash, and a line
197
203
  with no word character owes nothing by its text.
204
+ A non-authoritative answer never stands in for a primary that never
205
+ answered: a `fallbackFor` alternate (python-jedi beside a pyright that was
206
+ trust-refused, failed to start, sat in a breaker cool-down or was not
207
+ installed) is not its owner, so the file reads unavailable with the owner
208
+ named, never "confirmed clean" (#5014). The rule admits the known-good
209
+ forms (a non-alternate primary acquired, an alternate standing in for an
210
+ owner the operator disabled, an alternate whose owner resolved no root) in
211
+ `unansweredPrimaries` (`clients/lsp/index.ts`); every other cause, listed or
212
+ not, lands unconfirmed. Screen: can a file read clean when its primary
213
+ never answered? Population enforcer:
214
+ `tests/clients/lsp/unanswered-primaries-fallback-5014.test.ts` (every
215
+ registered `fallbackFor` alternate).
198
216
  Enforced by `tests/clients/dispatch/runners/run-outcome-ratchet.test.ts`,
199
217
  `tests/clients/dispatch/runners/parsed-nothing-sweep.test.ts` and
200
218
  `tests/clients/delivery-surface-ratchet.test.ts` (partial: no detector
@@ -273,7 +291,17 @@ file-scoped worklist and receives no project-wide scanner output.
273
291
  for). Derive the named set from the registry, never a hand list. Screen:
274
292
  render the prose under each posture combination and each host, and assert
275
293
  every clause is true (#4293, #4294 enabled axis; #4682 lazy axis and the
276
- hand list that dropped two tools).
294
+ hand list that dropped two tools). User docs that say which tools a
295
+ script or user can call are in scope too (#5242: "every pi-lens tool"
296
+ under `--no-lazy-tools` missed the enabled axis).
297
+
298
+ 90. **Generated proof line for a step that did not run:** a composer that
299
+ writes a PR, issue or report body states what ran. A branch where the step
300
+ failed, was skipped or timed out renders that outcome, never the success
301
+ sentence (#5243 r1: the nightly refresh body said the flips were
302
+ classified against master when the flip check had failed). Screen: for
303
+ each proof sentence a composer emits, which input proves the step ran,
304
+ and does the failed branch render something else?
277
305
 
278
306
  </important>
279
307
 
@@ -328,6 +356,24 @@ file-scoped worklist and receives no project-wide scanner output.
328
356
  try) by `tests/clients/worker-message-boundary-ratchet.test.ts`; screen
329
357
  `close` and timer callbacks by hand.
330
358
 
359
+ 89. **Serial await of independent work on a hot path:** a `for` loop or a run
360
+ of `await`s on the edit, write or turn-end path waits for each call before
361
+ starting the next, though no call needs another's result. The cost is the
362
+ sum of the calls instead of the slowest one: LSP servers spawned one after
363
+ another made a cold first edit block ~7 s (#2540), and a serial stat walk
364
+ took 8 s on a slow filesystem (#1409). Overlapping is not always a win:
365
+ some servers answer one request at a time (typescript-language-server
366
+ forwards to one tsserver; #387, #631), and a write-ordered loop
367
+ (`runtime.nextWriteIndex()`, a pipeline claim) must stay serial. Screen: do
368
+ the calls this loop or sequence awaits one at a time need each other's
369
+ results, share a write order, or go to one server that answers one request
370
+ at a time? If none, overlap them through `clients/map-with-concurrency.ts`;
371
+ if one does, a comment at the loop names it. Measure before overlapping
372
+ calls to one server. #5174 is the open instance. Census: not
373
+ countable. Enforcer: none: judgment-only; a scan cannot tell an
374
+ independent await from an ordered one without reading what each call
375
+ feeds. Instances and dates: `HISTORY.md`.
376
+
331
377
  60. **Wasm failure outside the #3605 containment:** every failure thrown out
332
378
  of web-tree-sitter classifies through `classifyTreeSitterWasmError`, and a
333
379
  `catch` inside a `withParsedTree` consumer calls `reportWasmAbort` before it
@@ -411,6 +457,20 @@ file-scoped worklist and receives no project-wide scanner output.
411
457
  tell a copied rule from a coincidental literal without reading what the
412
458
  value feeds. Instances and dates: `HISTORY.md`.
413
459
 
460
+ 88. **Learned attribution keyed on a name alone:** tier 4 of
461
+ `classifyMutatingTool` admits any tool name that was once seen with a disk
462
+ change in its call window and a `path` field, then classifies every later
463
+ call of that name as an edit. A tool that never wrote (one operation of a
464
+ mixed tool, #4139) and a call whose work already ran (a provider's
465
+ display-only replay, #5160) both reach it on name plus path alone. Tier 4 is
466
+ admit-by-default with enumerated exemptions (the registry names, the
467
+ `cursor-replay-` id prefix); a third carve-out is the trigger to redesign it
468
+ fail-closed, learning only when the call, not the window, owns the change.
469
+ Screen: can a call whose work already ran, or a tool that never wrote, reach
470
+ the learned lookup or the arm gate on name plus path alone? Census: not
471
+ countable. Enforcer: none: judgment-only, the exempt population is whatever
472
+ other providers replay or mix. Instances and dates: `HISTORY.md`.
473
+
414
474
  </important>
415
475
 
416
476
  <important if="a test double, ratchet or sweep">
@@ -455,8 +515,9 @@ file-scoped worklist and receives no project-wide scanner output.
455
515
  38. **Data-only admission:** a new exemption or baseline row requires a reason
456
516
  in a separate checked file and a fixture that crosses the boundary.
457
517
 
458
- 44. **Portable entry-module check:** compare `import.meta.url` with
459
- `pathToFileURL(process.argv[1]).href`.
518
+ 44. **Portable entry-module check:** decide the entry module only with
519
+ `isMainModule(import.meta.url)` from `scripts/lib/is-main-module.mjs`;
520
+ `scripts/hooks/guard-bash.mjs` is the one standalone gate.
460
521
 
461
522
  45. **Root wrapper drops metadata:** wrappers preserve the complete marker table
462
523
  and are checked against direct root resolution.
@@ -583,6 +644,9 @@ file-scoped worklist and receives no project-wide scanner output.
583
644
  (`~/.config/.opengrep`, `~/.config/.semgrep`), and a symlinked managed `bin`
584
645
  lets an installer write through to the real `~/.pi-lens/bin`. The pin is
585
646
  the whole set, assigned once in the worker so every child inherits it.
647
+ npm's cache and log directory (`npm_config_cache`, default `~/.npm`) is
648
+ in the set: two probes on 2026-11-04 (the #5239 fixer, the #5244
649
+ reviewer) wrote `~/.npm/_logs` through `npx`.
586
650
  Screen: which directory does the process I run resolve from, and is every
587
651
  variable that names it pinned? Enforcer:
588
652
  `tests/clients/worker-home-pin-hermeticity.test.ts` (a real child reports
@@ -605,11 +669,13 @@ file-scoped worklist and receives no project-wide scanner output.
605
669
  the lane's timeout scale and is refused; a same-named local constant is
606
670
  admitted and an import alias of the shared one is refused (no live member
607
671
  either way). Screen: does this case call a walker or read a binding one
608
- produced, and is its third argument one of those two forms? Census: 151 in
609
- `tests/config`, all budgeted; 79 outside it still keep the default (a probe,
610
- not a command). Enforcer: `tests/config/tree-census-timeout.test.ts` (it
611
- derives the declaration callee from the file's vitest imports, resolves
612
- walker aliases, and counts a test-shaped call it cannot trace as a census).
672
+ produced, and is its third argument one of those two forms? Census: 244
673
+ under `tests/` (154 in `tests/config`, all budgeted; 90 outside it, of which
674
+ 87 are refused and admitted by name in
675
+ `tests/config/tree-census-timeout.baseline.json`, and 3 budgeted). Enforcer:
676
+ `tests/config/tree-census-timeout.test.ts` (it derives the declaration
677
+ callee from the file's vitest imports, resolves walker aliases, and counts a
678
+ test-shaped call it cannot trace as a census).
613
679
  It does not read a walker reached through a helper in another module, a
614
680
  variable-bound arrow-function walker, a local spawn wrapper, or a walk named
615
681
  only by an enclosing `describe.each` or loop; `Unit tests Windows` is the
@@ -622,8 +688,15 @@ file-scoped worklist and receives no project-wide scanner output.
622
688
  (`tests/clients/interleaving-kit.ts`), which reads a real-clock deadline
623
689
  scaled by `PI_LENS_TEST_TIMEOUT_SCALE`, and give the test a timeout above
624
690
  that deadline. Screen: does the wait end on the event it waits for or on a
625
- real-clock deadline, never on a count? Enforcer: none yet; the detector is
626
- tracked in #4865. Instances and dates: `HISTORY.md`.
691
+ real-clock deadline, never on a count? Enforcer: the governance ast-grep
692
+ rules `turn-count-wait` and `turn-count-wait-test-hook`
693
+ (`scripts/governance-rules/`, run by `npm run astgrep:self-scan`), with a
694
+ reasoned baseline. It does not see a count loop with no exit besides the
695
+ count (a pure `for (N) await yield` flush), a wait spelled as recursion, a
696
+ count written as iteration over a generated range
697
+ (`for (const _ of Array.from({ length: N }))`), or a loop that compares a
698
+ clock value for some other purpose.
699
+ Instances and dates: `HISTORY.md`.
627
700
 
628
701
  </important>
629
702
 
@@ -718,8 +791,27 @@ file-scoped worklist and receives no project-wide scanner output.
718
791
  <reason>`, and a `session` owner states `sessionSeamException`, why a scope
719
792
  cell cannot hold it yet. A moved store has no process container and no
720
793
  entry; `scanScopeCellKeys` pins every cell by file and key
721
- (`SESSION_CELL_KEYS`). Partial: it reads the registered stores only, so an
722
- unregistered module-level field is still not scanned.
794
+ (`SESSION_CELL_KEYS`). The same `auditOwnerKeys` reads all three lists:
795
+ `SESSION_STATE_REGISTRY`, the file-level `EXEMPT_SESSION_STATE_FILES` rows
796
+ and the declared `SESSION_STORE_REGISTRY` rows (#5027); a file with several
797
+ owners states the narrowest. The scan behind them
798
+ (`scanSessionStateCandidates`) flags a file for a module-level container
799
+ with or without a reset, except one admitted constant: an UPPER_SNAKE
800
+ built-in `Map`/`Set`/`WeakMap`/`WeakSet` declared `const` whose every use
801
+ in `clients/`, `tools/`, `mcp/` and `index.ts` is a read; and for a class
802
+ field or `this.x` assignment bound to `new <container or clients/ class>`
803
+ or `[]`, or a depth-1 `key: new <container>` member of a module-level
804
+ object literal (`globalState = { reads: new Map() }`). An admitted
805
+ constant removes the symbol, not the file: a file that also exports a
806
+ reset stays a candidate with a 0 pin. One symbol-count pin counts the
807
+ containers, fields and members. Partial: it walks `clients/`;
808
+ `tools/` holds no candidate today, `index.ts` is censused by
809
+ `tests/config/session-scope-sweep.test.ts` (#3611), and `mcp/server.ts`
810
+ (`lspReadyCwds`) is outside the scan root. A field built by a factory call,
811
+ through another binding or an aliased constructor is not read, and an
812
+ admitted constant's `forEach` callback or stored value can be mutated
813
+ unseen (`SWEEP_HEURISTIC_LIMITS`; live population 0), and the owner value
814
+ itself is a judgment the audit only forces to be stated.
723
815
 
724
816
  87. **Factory-time read of a host value set later:** pi applies an extension flag's command-line value after every factory has run, so a flag read while the factory runs answers the registered default. Screen: does any flag read run while the factory runs, and does the host test apply the value after the factory, as pi does? Read it in a handler, a command or a tool, or once in `session_start`. Enforcer: `tests/config/factory-flag-read-sweep.test.ts` (partial: a reader handed to a callee that invokes it synchronously is not seen). Instances and dates: `HISTORY.md`.
725
817
 
@@ -72,8 +72,10 @@ verdict (a trust check, a lint, a census, a body check), it admits a short list
72
72
  of known-good forms and refuses everything else. It never enumerates known-bad
73
73
  spellings. Each review of an enumerated gate finds the next spelling it missed;
74
74
  one gate took sixteen rounds that way. Once a second round finds a new
75
- spelling, stop patching and redesign. Screen: can an input nobody planned for
76
- pass the gate?
75
+ spelling, stop patching and redesign. A value the gate cannot resolve to a
76
+ known-good literal (computed, concatenated, aliased, templated, reached through
77
+ an indirection) is unrecognized: it counts as a hit, never a pass. Screen: can
78
+ an input nobody planned for pass the gate?
77
79
 
78
80
  **Blast radius as a call-tree diff.** For any change to a shared seam, list the
79
81
  changed symbol, its callers above, its callees below, with plus and minus on the
@@ -115,6 +117,13 @@ it, and paste the red. A checked box with no transcript is treated as false. A
115
117
  mutation that fails to compile proves nothing about the test; redo it as a
116
118
  compile-valid change. A guard that cannot be made to red does not need to exist.
117
119
 
120
+ **A precision figure names its judgement and an outside sample.** A claim that
121
+ a rule, check or heuristic is N% precise states what counts as a true positive,
122
+ and someone other than its author judges a random sample. "The pattern matched"
123
+ is not "the finding is worth acting on": one rule reported 611 of 611 hits real
124
+ on a type check, and an independent sample of 58 found none worth the rewrite.
125
+ Below the stated bar, the rule ships disabled with the count recorded.
126
+
118
127
  **Tautological tests are harmful.** A test observes behaviour through the real
119
128
  seam and asserts an independent effect. It never restates the implementation,
120
129
  never asserts a value its own setup supplied, and never swaps a real in-process
@@ -138,6 +147,13 @@ thing is required, a registry entry, a baseline row and lane membership. A
138
147
  mocked seam is not a real spawn and gets an exemption with its reason, never an
139
148
  admission.
140
149
 
150
+ **A gate judges the actor's delta, not inherited state.** A check run on an
151
+ artifact someone edits (a tracker body, a shared file, a long-lived record)
152
+ judges only what that edit adds or changes. Inherited violations belong in a
153
+ baseline that shrinks on purpose. Refusing an honest edit for debt it did not
154
+ create blocks the work or invites routing around the gate. If the gate cannot
155
+ compute the delta, it checks the whole artifact, failing closed.
156
+
141
157
  **A new ratchet sweeps the open changes before it lands.** A governance test
142
158
  that rejects a new pattern fails every open change that already adds one, and
143
159
  none of them conflict textually, so nothing warns. Before merging a ratchet,
@@ -219,6 +235,15 @@ cleanup, triage and status upkeep. The script surfaces unfinished work and
219
235
  never hides it: stalled work is restarted, not unassigned, archived or deleted.
220
236
  Screen: is this the second time this step was done by hand?
221
237
 
238
+ **Process carries the net-count rule too.** A new guard, hook, script, lint
239
+ rule, ratchet or scheduled routine retires one of the same kind in the same
240
+ change, or it cites fire data showing what the existing ones miss. Each rule
241
+ must also earn its keep: count how often it fired, and what each fire led to
242
+ (a real fix, a wording edit, or a route-around). One that never fired in its
243
+ window and names no recurrence is demoted or deleted. Process cost is paid on
244
+ every change, while the bug a rule prevents may never arrive. Screen: what
245
+ does this rule retire, and when did the last one like it fire?
246
+
222
247
  ## 4. Honesty and records
223
248
 
224
249
  **Closes versus refs follows delivery, not optimism.** Close only when every
@@ -173,7 +173,14 @@ Set to `1` to skip auto-installing language servers. Off by default.
173
173
  ### `PI_LENS_DISABLE_TOOL_INSTALL`
174
174
 
175
175
  Set to `1` to skip auto-installing managed tools (formatters, linters,
176
- scanners). Off by default.
176
+ scanners). Off by default. It stops four things: the managed installer, the
177
+ lazy installer (`gem install rubocop`, `rustup component add clippy|rustfmt`),
178
+ govulncheck's `go install`, and any `npx` package-runner spawn, which runs
179
+ offline (`npm_config_offline=true`): it uses npm's cache or fails, and never
180
+ downloads. A refused lazy or govulncheck install records one `install-disabled`
181
+ degradation row per tool per session. It does not cover `bunx` (which ignores
182
+ that variable; pi-lens never spawns it) or language-server installs (see
183
+ `PI_LENS_DISABLE_LSP_INSTALL`).
177
184
 
178
185
  ## Context injection
179
186
 
@@ -260,6 +267,16 @@ Explicit path to a Lombok jar for the Java language server, used when
260
267
  auto-resolution does not find one. The legacy `LOMBOK_JAR` variable is also
261
268
  honored.
262
269
 
270
+ ### `GROOVY_LANGUAGE_SERVER_JAR`
271
+
272
+ Path to the `groovy-language-server-all.jar` the built-in Groovy row runs as
273
+ `java -jar <jar>`, when no `groovy-language-server` launcher is on `PATH`.
274
+ groovy-language-server publishes no release: build it with `./gradlew build` in
275
+ a checkout of GroovyLanguageServer/groovy-language-server and point this at
276
+ `build/libs/groovy-language-server-all.jar`. Java 17 or newer is found the same
277
+ way the Java language server finds it. A path that is not a file reads as not
278
+ installed, and the session start log says so.
279
+
263
280
  ## Project map
264
281
 
265
282
  ### `PI_LENS_MAP_MAX_NODES`
package/docs/features.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ### LSP Support
4
4
 
5
- pi-lens includes **50 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — and one opt-in, JS/TS-only auxiliary, fallow, off unless `fallow.enabled` is set; 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.
5
+ pi-lens includes **51 language server definitions** (including four cross-cutting *auxiliary* scanners that attach alongside the file's language server — Opengrep, ast-grep, zizmor, and typos — and one opt-in, JS/TS-only auxiliary, fallow, off unless `fallow.enabled` is set; 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.
6
6
 
7
7
  **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.
8
8
 
@@ -19,7 +19,9 @@ pi-lens includes **50 language server definitions** (including four cross-cuttin
19
19
  - **`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).
20
20
  - **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.
21
21
 
22
- 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.
22
+ `lsp_navigation` answers with Neovim-style text by default: a `path:line:col` location list, `hover` markdown, an indented `start-end kind name` symbol tree, and `path:line:col: severity: message` diagnostic rows. Pass `view: "json"` for the structured envelope the pre-text default returned (refs #1449).
23
+
24
+ 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, Groovy (groovy-language-server, from PATH or `GROOVY_LANGUAGE_SERVER_JAR`), 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.
23
25
 
24
26
 
25
27
  ### TypeScript and JavaScript server
@@ -149,6 +151,8 @@ pi-lens enforces a **read-before-edit** policy on all file writes and edits. Bef
149
151
 
150
152
  Coverage is tracked across multiple reads: two reads of lines 1–100 and 101–200 together satisfy a full-file write. Symbol-expanded reads (small reads widened to the enclosing symbol via tree-sitter, labelled with a leading note) count toward coverage at the symbol level. Markdown files generate a warning instead of blocking (edits outside the section-expanded read range are warned, not silently passed). Plain-text (`.txt`) and log (`.log`) files remain fully exempt.
151
153
 
154
+ A provider extension's display-only replay of work that already ran is not guarded. pi-cursor-sdk replays Cursor's native edits as tool calls whose ids start with `cursor-replay-`; the files were written before the replay arrived, so an "Edit without read" refusal would protect nothing and only turn the replayed card into an error. Such a call is never checked by the read guard and never taught to pi-lens as a mutating tool name. A real `edit` or `write` call and Cursor's real bridged executions (`cursor-pi-bridge-*`) are checked as usual.
155
+
152
156
  Override for a single edit: `/lens-allow-edit <path>`
153
157
 
154
158
  Configure behavior with `--no-read-guard` to disable it entirely, or use the
@@ -164,7 +168,7 @@ instead of a flat blob of source. See
164
168
  [`module-report-read-symbol.md`](module-report-read-symbol.md)
165
169
  for the full design and token-efficiency numbers.
166
170
 
167
- **`module_report(filePath, maxRefsPerSymbol?, focus?, view?, blastRadius?, blastRadiusDepth?)`** —
171
+ **`module_report(path, maxRefsPerSymbol?, focus?, view?, blastRadius?, blastRadiusDepth?)`** —
168
172
  returns a structured outline: every symbol's name/kind/startLine/endLine/signature
169
173
  (plus a first-line `doc` summary when a doc comment is attached — #512),
170
174
  exported vs internal split (with class/interface members nested under their
@@ -178,13 +182,16 @@ path since they point at a different file. Pass `blastRadius: true` to also get
178
182
  the cross-file **blast radius** — transitive dependents aggregated to ranked
179
183
  file `read` args ("if you change this, verify these files"); read-only over
180
184
  the cached graph, omitted when cold (this replaced the standalone
181
- `pilens_impact` tool). `view: "compact"` returns a line-oriented text
182
- rendering (one line per symbol/callback, roughly a quarter of the JSON cost)
183
- instead of JSON — same data, opt-in. Tree-sitter extract + cached review-graph
185
+ `pilens_impact` tool). `view` selects an output preset, projection × format
186
+ (`"summary-text"` default = metrics off, text; `"summary-json"`; `"full-text"`;
187
+ `"full-json"` = every field, JSON) — the text cell is lossless against the
188
+ JSON payload; the default leaves out `usedBy`, `fanout` and `complexity`, at
189
+ roughly half the byte
190
+ size. Tree-sitter extract + cached review-graph
184
191
  lookup; never builds the graph, never calls LSP on this path.
185
192
  `semantic.source` reports what backed the data (`review-graph` | `none`).
186
193
 
187
- **`read_symbol(filePath, symbol)`** — returns the verbatim body of one
194
+ **`read_symbol(path, symbol)`** — returns the verbatim body of one
188
195
  named symbol plus a one-line header (`<kind> <name> <basename>:<startLine>-<endLine>`).
189
196
  Records the read against the read-guard so a follow-up edit anywhere in
190
197
  that symbol's range passes the read-before-edit check (an outline from
@@ -144,7 +144,9 @@ Hide the diagnostics widget by default, run formatting immediately after write/e
144
144
 
145
145
  `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.
146
146
 
147
- `contextInjection.retain` (default `false`, or `--lens-retain-injections`) keeps injection on and makes it cache-stable instead. An injection normally rides one provider request: pi rebuilds the next request from its own transcript, so that request no longer carries it, and an engine that caches by exact prefix (a local llama.cpp or Qwen server) re-processes everything after the point where it sat. With `retain` on, pi-lens re-sends each injection's bytes unchanged, at the same place, in every later request of the session, so each request is the previous one plus new content. Findings are still delivered once; each retained block ends with a snapshot label naming `lens_diagnostics` for the current state. A compaction, a `/tree` move, or a new, resumed, forked or reloaded session drops what was retained. A session holds at most 64 retained injections and 256 KiB; past either, a new injection reaches its one request only and one `context-injection-retain-declined` degradation row is recorded.
147
+ While a 🔴 blocker the model was told about stays unresolved, the first request of each later prompt repeats it once, headed "Still unresolved (already reported on an earlier turn, not new)" and ending with a `lens_diagnostics` call that lists every blocker, because pi rebuilds that request from its transcript and a blocker from a nested write (a codemode script that drops the STOP note) is not in it. Requests inside one prompt, blockers the session has fixed or marked (whatever another session still holds), and the MCP host repeat nothing; `contextInjection.enabled: false` repeats nothing either.
148
+
149
+ `contextInjection.retain` (default `false`, or `--lens-retain-injections`) keeps injection on and makes it cache-stable instead. An injection normally rides one provider request: pi rebuilds the next request from its own transcript, so that request no longer carries it, and an engine that caches by exact prefix (a local llama.cpp or Qwen server) re-processes everything after the point where it sat. With `retain` on, pi-lens re-sends each injection's bytes unchanged, at the same place, in every later request of the session, so each request is the previous one plus new content. Findings are still delivered once, and a repeat of a blocker a retained block already carries is skipped, so it spends none of the cap; each retained block ends with a snapshot label naming `lens_diagnostics` for the current state. A compaction, a `/tree` move, or a new, resumed, forked or reloaded session drops what was retained. A session holds at most 64 retained injections and 256 KiB; past either, a new injection reaches its one request only and one `context-injection-retain-declined` degradation row is recorded.
148
150
 
149
151
  `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.
150
152
 
@@ -265,10 +267,16 @@ Per-rule threshold overrides and policy filters. Currently honored:
265
267
  `no-eval` once and the filter covers `no-eval`, `ast-grep:no-eval`, and
266
268
  `no-eval-js`. Side effect: a rule whose real name genuinely ends in `-js`
267
269
  (e.g. `prefer-js`) is conflated with its stem (`prefer`) — disabling or
268
- selecting one also disables or selects the other.
270
+ selecting one also disables or selects the other. The list is a denial: the
271
+ union of the global, project and nested files' lists, so a nearer file adds
272
+ rules and never re-enables one.
269
273
  - `<id>.select` — allowlist of rule ids; only the listed rule ids survive
270
274
  filtering. Disable wins over select project-wide, even when the two lists
271
- are configured under different keys.
275
+ are configured under different keys. Unlike `disable`, the nearest file that
276
+ sets `select` supplies the whole list per grouping key; a global `select`
277
+ applies to a key no nearer file sets. Lists under different keys are unioned,
278
+ so a global `k.select: [x]` and a nearer `k2.select: [y]` keep both `x` and
279
+ `y`.
272
280
 
273
281
  The `<id>` key is a grouping label only — it does not scope which rules the
274
282
  `disable`/`select` list underneath it can match. Matching is **project-wide**:
@@ -44,9 +44,13 @@
44
44
  The commit gate reads every record, whoever owns it, because the tree is
45
45
  shared. A turn end reads only its own session's records: it delivers,
46
46
  sweeps, re-judges and consumes those, and files its guard section under its
47
- own id. Only a write by the coordinator's session latches
48
- `session_mismatch`; a concurrent session's write leaves another
49
- session's record and the latch alone.
47
+ own id. The gate reads every record but retires only its own session's: its
48
+ missing-file sweep (#5020) persists into the cache of the acting session's
49
+ own records, whose cache is the coordinator root's cache or the session
50
+ cwd's, whichever wrote them, so another session's dead-cite row waits for
51
+ that session's own gate or turn end. Only a write by the coordinator's
52
+ session latches `session_mismatch`; a concurrent session's write leaves
53
+ another session's record and the latch alone.
50
54
  - The commit gate is keyed by the repository being committed (#4941), not by
51
55
  session. A commit/push is judged by the unresolved blockers whose files lie
52
56
  in the git checkout it targets (`resolveGitCheckout`, the seam the review