pi-lens 4.4.3 → 4.4.5

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 (185) hide show
  1. package/CHANGELOG.md +721 -0
  2. package/README.md +25 -3
  3. package/config/dependency-cruiser-eager-allowlist.json +1 -0
  4. package/dist/chunk-22Y2BM7H.js +23 -0
  5. package/dist/{chunk-WU567RSC.js → chunk-27VWVB23.js} +16 -14
  6. package/dist/{chunk-FLKWCIZH.js → chunk-2FYKETQJ.js} +10 -6
  7. package/dist/{chunk-MQLUAEOC.js → chunk-2LDMXL2M.js} +2 -2
  8. package/dist/{chunk-YSZNHOBY.js → chunk-2SDHYHHO.js} +17 -17
  9. package/dist/chunk-2Y6OJRSI.js +38 -0
  10. package/dist/chunk-3SNDVPOR.js +507 -0
  11. package/dist/{chunk-EJIUXPBX.js → chunk-3WCEHYOI.js} +1 -1
  12. package/dist/chunk-44X7VIKR.js +73 -0
  13. package/dist/{chunk-Q7DUK4LX.js → chunk-4FHUGDKU.js} +16 -14
  14. package/dist/{chunk-H6MF6EVN.js → chunk-4ODSZ35Z.js} +1498 -534
  15. package/dist/{chunk-ZGDGW2V3.js → chunk-4U7GDSZQ.js} +2 -2
  16. package/dist/chunk-54NIOJJZ.js +25 -0
  17. package/dist/{chunk-ZWFS3OEF.js → chunk-5DKE4HGX.js} +38 -37
  18. package/dist/{chunk-VRZP76YM.js → chunk-5LRUKYFA.js} +34 -4
  19. package/dist/{chunk-QOBUHWHX.js → chunk-63NMUNYP.js} +12 -16
  20. package/dist/{chunk-VWCXW2E7.js → chunk-6XSESGWD.js} +13 -6
  21. package/dist/{chunk-QGQ5CCCG.js → chunk-72J27ICO.js} +2 -3
  22. package/dist/{chunk-CSHFH5IN.js → chunk-7FLRUH6B.js} +1 -1
  23. package/dist/chunk-7IYC4ENJ.js +297 -0
  24. package/dist/chunk-7WWQAW5P.js +30 -0
  25. package/dist/{chunk-EU63SDCG.js → chunk-7ZS7MC24.js} +885 -451
  26. package/dist/{chunk-KBG47GHP.js → chunk-AHWA4AKM.js} +18 -12
  27. package/dist/{chunk-FMSO6RDZ.js → chunk-AI3GP74G.js} +17 -19
  28. package/dist/chunk-APFJKOP6.js +67 -0
  29. package/dist/{chunk-RXCOMYPY.js → chunk-ASRAO7KG.js} +31 -33
  30. package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
  31. package/dist/{chunk-QILIYSJF.js → chunk-CG5V25HX.js} +1 -1
  32. package/dist/chunk-CKEQFGLT.js +32 -0
  33. package/dist/{chunk-RPLINGVB.js → chunk-COOUUC5W.js} +6 -6
  34. package/dist/{chunk-GBPP5P7X.js → chunk-CPZ5JJW6.js} +4 -4
  35. package/dist/{chunk-OCAGUNBC.js → chunk-DS2USX5G.js} +13 -15
  36. package/dist/chunk-EA2ZRG44.js +27 -0
  37. package/dist/{chunk-ZHFZWTZV.js → chunk-EDMLIW6W.js} +13 -14
  38. package/dist/{chunk-2EECBNC5.js → chunk-EIKRZ32J.js} +75 -0
  39. package/dist/chunk-EKNWOL2I.js +27 -0
  40. package/dist/{chunk-CMMHNUZ2.js → chunk-ELZRSR5N.js} +65 -43
  41. package/dist/{chunk-BKE7E7TC.js → chunk-EN5AM7PX.js} +11 -12
  42. package/dist/{chunk-N2H3ZPZY.js → chunk-EWXXLS26.js} +227 -24
  43. package/dist/chunk-EX4EXBW7.js +37 -0
  44. package/dist/{chunk-YYOIQFRS.js → chunk-EXVXBSGN.js} +130 -52
  45. package/dist/{chunk-6GFRNVYR.js → chunk-F7BO6FWH.js} +12 -13
  46. package/dist/chunk-FEDWAYDS.js +2485 -0
  47. package/dist/{chunk-JAU72XNY.js → chunk-FWZRGGGY.js} +73 -9
  48. package/dist/{chunk-GXW6K4YJ.js → chunk-G224FADB.js} +1 -1
  49. package/dist/chunk-G5UCJFT7.js +26 -0
  50. package/dist/{chunk-67WMNWEE.js → chunk-GLW3YDZZ.js} +22 -13
  51. package/dist/{chunk-724UL2TJ.js → chunk-GTDSYEA2.js} +72 -39
  52. package/dist/{chunk-PHDMFAKM.js → chunk-GYRZ72R4.js} +10 -4
  53. package/dist/chunk-HYVXA3BB.js +49 -0
  54. package/dist/{chunk-SAEFPSB6.js → chunk-IEBJF3PN.js} +23 -15
  55. package/dist/chunk-IJYGIDF4.js +186 -0
  56. package/dist/{chunk-ACXEQZOU.js → chunk-IL7K66ZQ.js} +101 -109
  57. package/dist/{chunk-ZXYDQ3TZ.js → chunk-JWOVP5BL.js} +50 -19
  58. package/dist/{chunk-OXXKQCSV.js → chunk-K2GUZ4DN.js} +4 -4
  59. package/dist/{chunk-AW7R2GWG.js → chunk-K4SZB56V.js} +39 -39
  60. package/dist/{chunk-WOA4LN2R.js → chunk-KCBRHV5E.js} +3 -3
  61. package/dist/{chunk-3W7IEVVL.js → chunk-KFXCL4OV.js} +47 -45
  62. package/dist/{chunk-2BBLFX75.js → chunk-KJJAVH3X.js} +81 -15
  63. package/dist/{chunk-VCHXCQFG.js → chunk-KPVLQHCZ.js} +4 -6
  64. package/dist/{chunk-P7266HLM.js → chunk-KX56K73G.js} +10 -13
  65. package/dist/{chunk-VSSBEUFT.js → chunk-LMCTHJ2H.js} +19 -19
  66. package/dist/{chunk-IBGIOBEE.js → chunk-MEFLGBCS.js} +69 -8
  67. package/dist/{chunk-TYM6OUIT.js → chunk-MKPCELNI.js} +17 -17
  68. package/dist/{chunk-XTMJ7XDT.js → chunk-N3PLNNCW.js} +1 -1
  69. package/dist/chunk-N5FBM25N.js +22 -0
  70. package/dist/{chunk-CHOW74WE.js → chunk-NFNVDDGB.js} +7 -12
  71. package/dist/{chunk-52FUZI6K.js → chunk-NLIVE7L6.js} +2 -30
  72. package/dist/{chunk-SS36ZX4J.js → chunk-OMJ3OFBJ.js} +6 -6
  73. package/dist/{chunk-4W4VLAPJ.js → chunk-OZNCKLOX.js} +13 -14
  74. package/dist/chunk-P5XUGPIX.js +31 -0
  75. package/dist/{chunk-5UCAH366.js → chunk-PJXNTPB2.js} +253 -33
  76. package/dist/chunk-PKOXJIVT.js +88 -0
  77. package/dist/{chunk-6C7JWPCP.js → chunk-PP2A5V2T.js} +27 -26
  78. package/dist/{chunk-L3BLXZG7.js → chunk-Q42LJANT.js} +31 -70
  79. package/dist/{chunk-AB3YYG6N.js → chunk-Q4BKKOVC.js} +8 -8
  80. package/dist/{chunk-3EFKIGZN.js → chunk-QT66NEYN.js} +4 -4
  81. package/dist/{chunk-3VPVG5SU.js → chunk-RCHO5W7M.js} +19 -18
  82. package/dist/{chunk-77M37OKR.js → chunk-RG3MXTRI.js} +7 -7
  83. package/dist/chunk-RG7OODGM.js +57 -0
  84. package/dist/{chunk-T6CPIZNT.js → chunk-RU34BA4D.js} +44 -39
  85. package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
  86. package/dist/{chunk-5NGR67U5.js → chunk-S55TEC7I.js} +33 -5
  87. package/dist/{chunk-M6HSLBWY.js → chunk-SJHC3BCZ.js} +7956 -8047
  88. package/dist/{chunk-XCJN5IJU.js → chunk-SNEUMLM7.js} +4 -4
  89. package/dist/{chunk-UZ3TUTRV.js → chunk-T4NGVFYI.js} +2 -2
  90. package/dist/{chunk-2VUQMUMT.js → chunk-THEXI2QO.js} +49 -43
  91. package/dist/{chunk-R3PCY3YS.js → chunk-TL2TCJYL.js} +15 -16
  92. package/dist/{chunk-C34ZXZ7O.js → chunk-TPYYEDP5.js} +838 -352
  93. package/dist/{chunk-AOHZU2BM.js → chunk-TVZRLTG6.js} +8 -1
  94. package/dist/{chunk-XMSXXAHW.js → chunk-UCVMSOXF.js} +2 -2
  95. package/dist/chunk-UL5SXQVX.js +32 -0
  96. package/dist/{chunk-GAEGEPOC.js → chunk-UO66IMVP.js} +2 -2
  97. package/dist/{chunk-N3X6Q4YT.js → chunk-UVY4TOJH.js} +3 -3
  98. package/dist/{chunk-2CD5RS6M.js → chunk-VIDEKABZ.js} +23 -2
  99. package/dist/{chunk-JSQFTSC6.js → chunk-VITFDI3O.js} +13 -14
  100. package/dist/{chunk-YIUAVF7E.js → chunk-VUAVE3QC.js} +42 -42
  101. package/dist/{chunk-QOZXJ4NA.js → chunk-WUY4BZEP.js} +21 -20
  102. package/dist/{chunk-VCO24T4L.js → chunk-X3UTCXAA.js} +43 -53
  103. package/dist/chunk-XHDBJODR.js +45 -0
  104. package/dist/{chunk-MXGY6KPT.js → chunk-XHLK33VM.js} +28 -21
  105. package/dist/{chunk-RWWYJ623.js → chunk-XI34NWDI.js} +2 -2
  106. package/dist/{chunk-QQNQ7SJW.js → chunk-XWFIHYCH.js} +12 -4
  107. package/dist/{chunk-6SDEP3AJ.js → chunk-Y2TPADJR.js} +10 -11
  108. package/dist/{chunk-MRXKYPCS.js → chunk-Y5KTA2OB.js} +17 -17
  109. package/dist/{chunk-7DYBLXYA.js → chunk-YKVDBNPO.js} +11 -5
  110. package/dist/{chunk-2B73ZPOK.js → chunk-YSDPVDFC.js} +3 -3
  111. package/dist/chunk-YWNO5Q4R.js +44 -0
  112. package/dist/{chunk-QHJ6DQ2R.js → chunk-YWWG4AQA.js} +165 -32
  113. package/dist/{chunk-3JNKMP3B.js → chunk-YXDCRUKQ.js} +4 -4
  114. package/dist/{chunk-UXGETRP4.js → chunk-YXGRRORB.js} +16 -17
  115. package/dist/{chunk-SQ4TVJBR.js → chunk-ZAPSUBLU.js} +13 -7
  116. package/dist/{chunk-76MWC2K6.js → chunk-ZPJM7DID.js} +90 -97
  117. package/dist/{chunk-XVF2VVXP.js → chunk-ZSUX7KEM.js} +16 -15
  118. package/dist/index.js +31038 -20893
  119. package/dist/mcp/analyze-cli.js +11 -11
  120. package/dist/mcp/cli.js +47 -43
  121. package/dist/mcp/server.js +2188 -906
  122. package/dist/mcp/worker.js +66 -63
  123. package/dist/probes/installer.js +21 -23
  124. package/dist/workers/project-snapshot-persist-worker.js +28 -9
  125. package/dist/workers/review-graph-persist-worker.js +1 -1
  126. package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
  127. package/docs/adr/README.md +1 -0
  128. package/docs/ast-grep_rules_catalog.md +5 -3
  129. package/docs/configuration.md +20 -0
  130. package/docs/engineering-principles.md +44 -0
  131. package/docs/environment-variables.md +20 -0
  132. package/docs/features.md +16 -1
  133. package/docs/globalconfig.md +37 -8
  134. package/docs/lsp-capability-matrix.md +105 -12
  135. package/docs/lsp-idle-eviction.md +44 -36
  136. package/docs/pi-lens-fixer.md +139 -14
  137. package/docs/pi-lens-investigator.md +14 -0
  138. package/docs/pi-lens-merge-policy.md +120 -17
  139. package/docs/pi-lens-monitor.md +71 -9
  140. package/docs/pi-lens-retro.md +6 -3
  141. package/docs/pi-lens-reviewer.md +160 -5
  142. package/docs/pi-lens-subagent.md +29 -14
  143. package/docs/release-qa-baseline.md +21 -7
  144. package/docs/servercapabilities.md +53 -63
  145. package/docs/settings.md +9 -5
  146. package/docs/subagent-compat.md +1 -1
  147. package/docs/usage.md +1 -0
  148. package/package.json +9 -5
  149. package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
  150. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
  151. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
  152. package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
  153. package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
  154. package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
  155. package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
  156. package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
  157. package/rules/rule-catalog.json +25 -1
  158. package/scripts/analyze-pi-lens-logs.mjs +15 -5
  159. package/scripts/download-grammars.js +40 -7
  160. package/scripts/lib/is-main-module.mjs +27 -0
  161. package/scripts/lib/latency-log-phases.mjs +95 -0
  162. package/scripts/lib/scratch-home-env.mjs +21 -0
  163. package/scripts/rpc-load-check.mjs +568 -81
  164. package/scripts/warm-loader-cache.mjs +2 -5
  165. package/dist/chunk-23WOO7TX.js +0 -23
  166. package/dist/chunk-3YN6V5TV.js +0 -85
  167. package/dist/chunk-466Z26MG.js +0 -30
  168. package/dist/chunk-4UNXBNE2.js +0 -24
  169. package/dist/chunk-6STA6Z7I.js +0 -47
  170. package/dist/chunk-ABBOA7UD.js +0 -157
  171. package/dist/chunk-BRGDSBJE.js +0 -28
  172. package/dist/chunk-EC47DWFA.js +0 -56
  173. package/dist/chunk-FCSOVF55.js +0 -273
  174. package/dist/chunk-IZSHAIJ7.js +0 -26
  175. package/dist/chunk-KDERNTCQ.js +0 -28
  176. package/dist/chunk-KSX3TXSZ.js +0 -69
  177. package/dist/chunk-LOP6GRPH.js +0 -31
  178. package/dist/chunk-PNQDPDRC.js +0 -184
  179. package/dist/chunk-UOPVJQ4N.js +0 -103
  180. package/dist/chunk-XAGLWMJ4.js +0 -51
  181. package/dist/chunk-XIJZVPD5.js +0 -39
  182. package/dist/chunk-Z3CCVDUB.js +0 -76
  183. package/dist/chunk-Z527N6YQ.js +0 -28
  184. package/dist/chunk-ZANLILYD.js +0 -79
  185. /package/dist/{chunk-FC4RP4I2.js → chunk-6HWVI6MI.js} +0 -0
@@ -2,7 +2,7 @@
2
2
 
3
3
  <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
4
4
 
5
- pi-lens bundles **483 enabled** ast-grep rules (299 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
5
+ pi-lens bundles **485 enabled** ast-grep rules (301 pi-lens-authored + 184 vendored from CodeRabbit) across **17 languages**, plus 16 disabled.
6
6
 
7
7
  See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `rules/ast-grep-rules/rules/` (pi-lens), `rules/ast-grep-rules/coderabbit/rules/` (vendored).
8
8
 
@@ -151,7 +151,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
151
151
  | `use-of-sha1-java` | warning | no | CodeRabbit | Detected SHA1 hash algorithm which is considered insecure. SHA1 is not collision resistant and is therefore not suitable as a cryptographic… |
152
152
  | `weak-ssl-context-java` | warning | no | CodeRabbit | 'An insecure SSL context was detected. TLS versions 1.0, 1.1, and all SSL versions are considered weak encryption and are deprecated. Use S… |
153
153
 
154
- ### JavaScript (79)
154
+ ### JavaScript (80)
155
155
 
156
156
  | Rule | Severity | Fixable | Source | Description |
157
157
  |---|---|---|---|---|
@@ -202,6 +202,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
202
202
  | `no-reflect-apply-js` | error | no | pi-lens | Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead |
203
203
  | `no-reflect-get-js` | error | yes | pi-lens | Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead |
204
204
  | `no-single-promise-in-promise-methods-js` | warning | no | pi-lens | Promise.all/race with a single promise is unnecessary — await it directly |
205
+ | `no-sql-in-code-execute-js` | warning | no | pi-lens | Raw SQL string in code — use query builder or ORM |
205
206
  | `no-sql-in-code-js` | error | no | pi-lens | Raw SQL string in code — use query builder or ORM |
206
207
  | `no-throw-string-js` | error | no | pi-lens | Throw Error objects, not strings |
207
208
  | `no-typeof-undefined-js` | hint | no | pi-lens | Use === undefined instead of typeof x === 'undefined' |
@@ -436,7 +437,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
436
437
  | `redundant-usestate-type` | info | yes | pi-lens | `useState<TYPE>(...)` where TYPE is a primitive redundant — TS can infer it from the initial value |
437
438
  | `unnecessary-react-hook` | warning | no | pi-lens | Function with a `use*` name does not call any other React hook — rename to a plain function |
438
439
 
439
- ### TypeScript (135)
440
+ ### TypeScript (136)
440
441
 
441
442
  | Rule | Severity | Fixable | Source | Description |
442
443
  |---|---|---|---|---|
@@ -507,6 +508,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
507
508
  | `no-single-promise-in-promise-methods` | warning | no | pi-lens | Promise.all/race with a single promise is unnecessary — await it directly |
508
509
  | `no-sort-without-comparator` | warning | no | pi-lens | .sort()/.toSorted() without a compare function sorts by string order — numbers sort wrong (e.g. [10,9,1] becomes [1,10,9]) |
509
510
  | `no-sql-in-code` | error | no | pi-lens | Raw SQL string in code — use query builder or ORM |
511
+ | `no-sql-in-code-execute` | warning | no | pi-lens | Raw SQL string in code — use query builder or ORM |
510
512
  | `no-throw-string` | error | no | pi-lens | Throw Error objects, not strings |
511
513
  | `no-typeof-undefined` | hint | no | pi-lens | Use === undefined instead of typeof x === 'undefined' |
512
514
  | `no-unimplemented-stub` | warning | no | pi-lens | Unimplemented stub — function was scaffolded but never completed |
@@ -51,6 +51,14 @@ schema slice does not change server launch behavior.
51
51
  }
52
52
  ```
53
53
 
54
+ `initializationOptions` take the shape the server itself reads. rust-analyzer
55
+ reads them flat (`check`, `cargo`), as above. pyright and basedpyright read
56
+ only their pulled settings, so nest the override under the section they ask
57
+ for: `{ "python": { "analysis": { "typeCheckingMode": "strict" } } }`. pi-lens
58
+ answers each
59
+ `workspace/configuration` request from that section of the merged options and
60
+ returns `{}` for a section the options do not carry.
61
+
54
62
  An override may also provide an experimental launcher `command` and `env`.
55
63
  The built-in server ID and strategy remain in force; only the launcher is
56
64
  replaced, and project-sourced launcher fields follow the same pi trust gate.
@@ -221,6 +229,17 @@ once no matter which spelling each file uses. Migrating does not change the
221
229
  answer, staying un-migrated is not a way around the denial, and a half-migrated
222
230
  pair of files merges rather than one clobbering the other.
223
231
 
232
+ Denying a file's **language server** (its primary, such as `json` or
233
+ `typescript`) leaves that file unchecked for the language itself. Every
234
+ diagnostics route then reports a file with no findings as **unconfirmed**, not
235
+ clean, with a "Primary LSP (…): not available" note that says it is disabled in
236
+ config. On write-time checks the note appears once per server per session, and
237
+ a later write of such a file shows a one-line "unconfirmed" status instead of
238
+ "clean". When the denied server has a fallback (`deno` for `typescript`) that
239
+ cannot start either, the note says so. Cross-file (cascade) checks name the
240
+ server once per session. Auxiliary scanners such as `typos` still run and
241
+ report their own findings.
242
+
224
243
  Two rules make the rest of the table unambiguous:
225
244
 
226
245
  - **The search stops at `$HOME`.** pi-lens never reads a config file in your
@@ -336,5 +355,6 @@ produced — so a session's config posture is visible without the detail.
336
355
  - `docs/globalconfig.md` — every key of `~/.pi-lens/config.json`, in detail.
337
356
  - `docs/settings.md` — the CLI flags and what they map to.
338
357
  - `docs/environment-variables.md` — the `PI_LENS_*` tier.
358
+ - `docs/features.md` — the Python interpreter and syntax-level declarations pi-lens reads from a project (`VIRTUAL_ENV`, `requires-python`, `target-version`, `.python-version`).
339
359
  - `docs/public-api-stability.md` — what `x-stability`, the `PILENS_CFG_*` codes,
340
360
  and the deprecation windows commit pi-lens to.
@@ -20,6 +20,18 @@ the deliverable is the recorded refutation (which invariant covers it, with the
20
20
  probe) and, where cheap, an assertion that pins it, not machinery for a
21
21
  collision that cannot occur.
22
22
 
23
+ **Speculative robustness needs buy-in.** Before adding mechanism for a race,
24
+ security edge case or failure nobody has reproduced, state the trigger path
25
+ (which inputs, in what order, through which production caller), the evidence
26
+ that it can happen, and the cost (new state, seams, tests to maintain). Without
27
+ a reproduction the default is no new mechanism: record the case as a hypothesis
28
+ or an accepted residual for the maintainer to decide. Workers flag it in the
29
+ hand-back and do not build it; reviewers file an unproven race as a hypothesis,
30
+ not a high-severity finding. This never waives validation, error handling or
31
+ security at a real trust boundary; it bounds new mechanism, not hygiene.
32
+ Screen: can the author name the production sequence that triggers it, with
33
+ evidence?
34
+
23
35
  **Climb the minimalism ladder before writing code.** Be lazy about the
24
36
  solution, never about reading. Trace the real flow, then ask in order: does this
25
37
  need to exist at all; does the codebase already do it (reuse the seam); does the
@@ -55,6 +67,14 @@ event per session, never one per occurrence in a loop; repeated degradations go
55
67
  through a once-only or counted record. A discriminator nothing can observe is a
56
68
  vacuous guard and does not ship.
57
69
 
70
+ **Gates fail closed on what they do not recognize.** When code decides a
71
+ verdict (a trust check, a lint, a census, a body check), it admits a short list
72
+ of known-good forms and refuses everything else. It never enumerates known-bad
73
+ spellings. Each review of an enumerated gate finds the next spelling it missed;
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?
77
+
58
78
  **Blast radius as a call-tree diff.** For any change to a shared seam, list the
59
79
  changed symbol, its callers above, its callees below, with plus and minus on the
60
80
  lines that moved. Prose keeps missing callers; a tree the reviewer can grep does
@@ -118,6 +138,12 @@ thing is required, a registry entry, a baseline row and lane membership. A
118
138
  mocked seam is not a real spawn and gets an exemption with its reason, never an
119
139
  admission.
120
140
 
141
+ **A new ratchet sweeps the open changes before it lands.** A governance test
142
+ that rejects a new pattern fails every open change that already adds one, and
143
+ none of them conflict textually, so nothing warns. Before merging a ratchet,
144
+ run it against each open change merged with the base, and fix or notify each
145
+ one it fails. Screen: which open change would fail this test after the merge?
146
+
121
147
  **Run targeted files while iterating; the full suite runs once.** Build before
122
148
  testing when tests execute compiled output, and rebuild between mutations. A red
123
149
  is environmental only when the same test is red on the base branch in the same
@@ -156,6 +182,13 @@ literal, a changelog line) are applied by the orchestrator as trailing commits
156
182
  and never re-verified; anything that changes what code means goes through a
157
183
  round, however small it looks.
158
184
 
185
+ **A round does what its brief prescribes, and flags anything more.** A worker
186
+ that changes something outside its brief lists that change as scope growth at
187
+ the top of its hand-off; one round widened a shared detector while asked to add
188
+ a single admission. Routing then re-classifies the round, because a silent extra
189
+ mechanism turns a merge-on-green round into one that needs a verify. Screen:
190
+ does the hand-off name every change the brief did not ask for?
191
+
159
192
  **Merge gate.** Merge only when the verdict is merge-ready, every gating check
160
193
  genuinely executed and passed on the exact head, and every failing check was
161
194
  read and judged. Absent is not green. Read exit codes directly, never after a
@@ -170,11 +203,22 @@ at the worktree root; the orchestrator commits. Implementation and review are
170
203
  never mixed in one delegation. Scope changes are mirrored on the tracking issue
171
204
  before they are sent, so the worker can verify them.
172
205
 
206
+ **Work in progress survives a cut.** A worker with Git authority commits at
207
+ each green step; one without it leaves its tree and names it in the hand-off.
208
+ A backend outage, a quota stop or a crash then costs one step, not the round,
209
+ and the next round ports the tree instead of redoing it. Screen: how much is
210
+ lost if this process dies now?
211
+
173
212
  **No manufactured work.** An idle worker is cheaper than fake work. Delegate
174
213
  when a real producer, consumer, probe or diagnosis is unresolved, never to keep
175
214
  a pool busy. The same applies to status artifacts: they exist for coordination
176
215
  someone consumes.
177
216
 
217
+ **A step done by hand twice becomes a script with a test.** That includes
218
+ cleanup, triage and status upkeep. The script surfaces unfinished work and
219
+ never hides it: stalled work is restarted, not unassigned, archived or deleted.
220
+ Screen: is this the second time this step was done by hand?
221
+
178
222
  ## 4. Honesty and records
179
223
 
180
224
  **Closes versus refs follows delivery, not optimism.** Close only when every
@@ -210,6 +210,26 @@ back to a local LSP fleet for that session.
210
210
 
211
211
  ## Language-specific
212
212
 
213
+ ### Ambient Python environments (`VIRTUAL_ENV`, `CONDA_PREFIX`, `UV_PROJECT_ENVIRONMENT`)
214
+
215
+ pi-lens reads three ambient channels when it resolves the interpreter that runs
216
+ pyright and jedi. `UV_PROJECT_ENVIRONMENT` names a uv project environment path
217
+ (relative paths resolve against the uv project root) and is consulted only when
218
+ the directory is a uv project root. The full chain, in the order the code walks
219
+ it, is: `UV_PROJECT_ENVIRONMENT`, a uv workspace's `.venv` for a declared
220
+ member, `VIRTUAL_ENV`, `CONDA_PREFIX`, the project's `.venv`, then its `venv`
221
+ (relative to the root being resolved). The first that holds
222
+ `bin/python` (`Scripts/python.exe` on Windows) wins, and the three variables are
223
+ read in that position, not ahead of the workspace environment. An ambient
224
+ environment is already active in the calling shell, so it needs no project
225
+ trust; a `.venv` or `venv` found inside the project does, because its binary is
226
+ project-sourced. Untrusted or absent, resolution falls through to the managed
227
+ install and then `PATH`.
228
+
229
+ These channels select an interpreter only. They never declare a syntax level;
230
+ that comes from `target-version`, `pythonVersion`, `requires-python`, or
231
+ `.python-version` (see [Features](features.md)).
232
+
213
233
  ### `PI_LENS_VULTURE_MIN_CONFIDENCE`
214
234
 
215
235
  Minimum confidence for the Python dead-code (Vulture) scanner. **Default:** `60`.
package/docs/features.md CHANGED
@@ -21,6 +21,21 @@ pi-lens includes **49 language server definitions** (including four cross-cuttin
21
21
 
22
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.
23
23
 
24
+
25
+ ### Python: interpreter and syntax level
26
+
27
+ Python carries two separate declarations, and pi-lens reads both from the project rather than from whichever interpreter happens to run a checker.
28
+
29
+ **Interpreter** — `detectPythonEnvironment` takes the first directory that holds a Python binary, in this order: `UV_PROJECT_ENVIRONMENT` (only at a uv project root), a uv workspace's `.venv` for a declared member, `VIRTUAL_ENV`, `CONDA_PREFIX`, the project's `.venv`, then its `venv`. pyright and jedi both launch from it. A binary that comes from a project's own environment needs project trust; without it pi-lens falls back to the managed install and then `PATH`, and records the refusal once per session. A project launch that fails for any other reason also falls through to that fallback.
30
+
31
+ **Syntax level** — `detectPythonTargetVersion` walks up from the file and, in each directory, takes the first readable declaration of ruff `target-version` (`.ruff.toml`, then `ruff.toml`, then `pyproject.toml` `[tool.ruff]`, the order ruff itself measures), pyright `pythonVersion` (`pyrightconfig.json`, which may use comments and trailing commas, then `pyproject.toml` `[tool.pyright]`), `requires-python` from `pyproject.toml` `[project]` reduced to its strongest lower bound (`>=3.12,>=3.14` is 3.14 in either order), then the first line of `.python-version`. The nearest directory holding a declaration wins. Each source ends its own walk where its tool stops: ruff at a ruff config (`.ruff.toml`, `ruff.toml`, or a `pyproject.toml` with `[tool.ruff]`, even one that sets no `target-version`), pyright at `pyrightconfig.json` or `[tool.pyright]`, `requires-python` at a `pyproject.toml` that carries the key, and `.python-version` at itself. A `pyproject.toml` that holds none of these is walked past, as ruff and pyright walk past it, so a nested config that owns a source blocks an ancestor's level for that source and nothing else does. Text that names no CPython major/minor — a `pypy-3.10` or branch name in `.python-version`, an empty file, a specifier with no lower bound — is no declaration at all; pi-lens never invents a default.
32
+
33
+ When the declared level is 3.14 or newer, jedi's `compile` findings are dropped. jedi compiles with the interpreter it launched, so a 3.14-only construct reports a spurious `SyntaxError` (PEP 758's unparenthesized `except` is the common case). The drop is recorded once per session and file, naming the declared level and the file that declared it, and it applies to the fresh probe, its cached replay, `lsp_navigation`, `mode=full`, and the post-write runner that delivers the same server's answer. Every one of those surfaces names the rows it withheld on the text the agent reads (the count and the declaring file), including when the file would otherwise read as clean. A call that spans projects with different declarations cites each declaration with its own count. The structured result carries the same `details.withheldCompile` object (`count`, `declared`, and `declarations` when there is more than one) on `lsp_diagnostics`, `lens_diagnostics` and `lsp_navigation`. Pyright is unaffected: it parses at the level it resolves and stays the authority on type errors.
34
+
35
+ ruff needs no override. Its pre-check, `--fix` pass, and lint run all read `target-version` from the project config, so pi-lens passes no level to any of them, and pre-check and fix cannot disagree about which syntax parses.
36
+
37
+ Non-goal: pi-lens never installs, selects, or pins a Python interpreter, and never rewrites a project's declaration.
38
+
24
39
  ### Formatters
25
40
 
26
41
  pi-lens auto-detects and runs **35 formatters** based on project config:
@@ -373,7 +388,7 @@ Pattern-based structural rules in `rules/ast-grep-rules/` across JS, TS, and Pyt
373
388
  [Opengrep](https://github.com/opengrep/opengrep) (an open, login-free fork of Semgrep) runs as a pi-lens **auxiliary diagnostic LSP** — a cross-cutting, diagnostic-only language server that attaches *alongside* the file's normal language server (TypeScript, Python, …) and contributes findings on the same on-write diagnostics path. Running it as a warm LSP server compiles its ruleset **once per session** rather than on every file, so per-file scans cost ~1–2s (vs ~8s for a cold CLI invocation per file). High-signal security findings become blocking; the rest are advisory.
374
389
 
375
390
  - **On by default** (it's a registered LSP server) when the `opengrep` binary is available; pi-lens **auto-installs it on demand** — a single GitHub-release binary, **no login, token, or telemetry**. Disable with `--no-opengrep`.
376
- - **Rules:** a repo `.opengrep.yml`/`.opengrep.yaml` (or a legacy `.semgrep.yml`/`.semgrep.yaml`, whose format Opengrep consumes natively) is used if present; otherwise it falls back to Opengrep's login-free `auto` Community ruleset.
391
+ - **Rules:** a repo `.opengrep.yml`/`.opengrep.yaml` (or a legacy `.semgrep.yml`/`.semgrep.yaml`, whose format Opengrep consumes natively) is used if present; otherwise it uses the registry rule pack pi-lens refreshed into its own cache (a bounded weekly background download, validated by `opengrep --validate` before it replaces the previous file; pi-lens ships no rules), and only while no pack has been fetched yet does it fall back to Opengrep's login-free `auto` Community ruleset. Offline with no pack, that fallback is reported as an unconfirmed scan, never a clean one (#4764).
377
392
 
378
393
  This is the first adopter of pi-lens's **auxiliary-LSP capability** (`role:"auxiliary"` servers + `clients/dispatch/auxiliary-lsp.ts`) — the same path future cross-cutting scanners (spelling, secrets, …) plug into by registration.
379
394
 
@@ -25,6 +25,7 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
25
25
  | `--lens-guard` | `guard.enabled` | `false` |
26
26
  | `--lens-checkout-guard` | `guard.sharedCheckout` | `false` |
27
27
  | `--immediate-format` | `format.mode` (`"immediate"`) | `"deferred"` |
28
+ | `--lens-retain-injections` | `contextInjection.retain` | `false` |
28
29
  | `--lens-turn-summary` | `turnSummary.enabled` | `false` |
29
30
  | `--lens-actionable-warnings` | `actionableWarnings.enabled` | `false` |
30
31
  | `--lens-actionable-warning-actions` | `actionableWarnings.includeLspCodeActions` | `false` |
@@ -51,15 +52,41 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
51
52
  | `startup.mode` | `full` | `quick`, `full`, or `minimal`; `PI_LENS_STARTUP_MODE` wins |
52
53
  | `startup.scans.enabled` | `true` | `true` or `false` |
53
54
 
54
- By default pi-lens registers five situational tools (the `ast_grep_*` family,
55
- `lsp_navigation`, `lens_diagnostic_mark`) inactive and exposes a small loader,
55
+ pi-lens registers five situational tools (the `ast_grep_*` family,
56
+ `lsp_navigation`, `lens_diagnostic_mark`) and a small loader,
56
57
  `pi_lens_activate_tools`, that the model calls to activate the ones it needs.
57
- `--no-lazy-tools` turns that off: every pi-lens tool is active from the first
58
- turn and pi-lens never changes the tool list. Use it if you would rather spend
59
- the tokens of a longer tool list than have the list change mid-session. The
60
- loader tool is still registered and still describes itself as activating
61
- inactive tools; under this flag those tools are already active, so calling it
62
- does nothing.
58
+ `tools.lazy` decides whether the situational tools start inactive:
59
+
60
+ | `tools.lazy` | Situational tools |
61
+ | --- | --- |
62
+ | `true` (default) | Start inactive on every model. |
63
+ | `"auto"` | Start inactive only when the session's model keeps mid-conversation system messages (`compat.supportsMidConvoSystemMessages` is `true`). On any other model, including one that does not state the fact, every tool is active from the first turn. Before a model is known, the tools start inactive. |
64
+ | `false`, or `--no-lazy-tools` | Every tool is active for the whole session and pi-lens never changes the tool list. |
65
+
66
+ Why `true` is the default: a model without that fact gets every system message
67
+ folded into one prompt head, so each tool-list change rewrites the whole cached
68
+ prompt. Activations are rare, though. Over the window measured for #4687 the
69
+ loader ran about once per 3,329 requests, while carrying every situational
70
+ schema on every request costs more than the rewrites once activations are
71
+ rarer than about one per 1,000 requests. `"auto"` is there for a workload that
72
+ activates often on a folding model.
73
+
74
+ Under `"auto"`, pi-lens decides at session start and again only when you
75
+ switch models, never between turns of one model. A switch to a folding model
76
+ activates every enabled situational tool. A switch back deactivates only the
77
+ ones the conversation never activated or called. Any other value is reported
78
+ once as an ignored setting, and the default applies.
79
+
80
+ Precedence: `tools.<name>.enabled` (in either config file, or `--no-tool`)
81
+ filters first. A disabled tool is never registered, so it is absent under every
82
+ `tools.lazy` value and the loader refuses to activate it. `tools.lazy` then
83
+ applies only to the enabled situational tools. It is user-level only: a project
84
+ `.pi-lens.json` that sets it, `"auto"` included, is reported and ignored. The
85
+ CLI flag outranks the key.
86
+
87
+ The loader tool stays registered under every value and keeps describing itself
88
+ as activating inactive tools; when the tools it names are already active,
89
+ calling it does nothing.
63
90
 
64
91
  Keys are positive (`"enabled": true` means the feature runs), so a `--no-*` flag corresponds to setting its key `false`. A `no-*` flag on the command line is a one-way switch: it can disable, never re-enable, so `--no-lsp` wins over `lsp.enabled: true` but nothing on the CLI overrides `lsp.enabled: false`. Set the key back to `true` to re-enable.
65
92
 
@@ -112,6 +139,8 @@ Hide the diagnostics widget by default, run formatting immediately after write/e
112
139
 
113
140
  `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.
114
141
 
142
+ `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.
143
+
115
144
  `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.
116
145
 
117
146
  `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.
@@ -90,6 +90,14 @@ the docs refresh commits the confirmed class and the marker must move with it.
90
90
  A single-night flip remains in the refresh-state JSON below and does not change
91
91
  the census's confirmed population.
92
92
 
93
+ The class is defined on a DIRTY file — is the first publish for a file that HAS
94
+ findings the answer, or an empty placeholder while a one-time index builds? — so
95
+ the probe takes it from a dirty fixture and never from a `clean: true` one: a
96
+ clean file has no finding to publish, so its trace can only ever be `empty-only`.
97
+ Before #4615 the clean fixture supplied both axes, which is how a publish that
98
+ belonged to another live client of the same server id became `typescript`'s
99
+ `empty-first`.
100
+
93
101
  ## The strategies
94
102
 
95
103
  | Tier | Signal | Affirmative clean? | Example |
@@ -131,12 +139,16 @@ Two bounded guards keep that preservation from hiding a dead instrument
131
139
  re-observe is stamped once with the date of its first miss and degrades to
132
140
  `unknown` once five calendar days have elapsed since it (skipped nights do not
133
141
  stall it, and a re-observation clears the stamp). `empty-first` cells are never
134
- expired: they back the live `emptyFirstPublish` markers (php, terraform) and
135
- expiring one would erase the measurement behind a marker. A `clean-behavior`/
136
- `tier` change is written only after two consecutive nightly runs observe the
137
- same new value, so one flapping nightly (ast-grep went 2 → 2* → 3 → 2* across
138
- four runs) cannot rewrite a cell; a night that measured nothing for the lang
139
- resets the hold. A subset probe (`probe-clean-signal.mjs <langs>`) leaves the
142
+ expired: they back the live `emptyFirstPublish` markers (php) and
143
+ expiring one would erase the measurement behind a marker. That exception is
144
+ bounded too (#4615): the refresh stamps the FIRST night it does not re-observe an
145
+ `empty-first` cell, and the first-publish census reds once that stamp is five
146
+ days old, so the cell+marker pair cannot outlive the instrument that produced it
147
+ — a cell with no live measurement behind it is no longer indistinguishable from
148
+ a healthy one. A `clean-behavior`/`tier` change is written only after two
149
+ consecutive nightly runs observe the same new value, so one flapping nightly
150
+ (ast-grep went 2 → 2* → 3 → 2* across four runs) cannot rewrite a cell; a night
151
+ that measured nothing for the lang resets the hold. A subset probe (`probe-clean-signal.mjs <langs>`) leaves the
140
152
  bookkeeping of the langs it did not probe untouched.
141
153
 
142
154
  The bookkeeping lives in the generated `## Capability matrix refresh state`
@@ -167,7 +179,7 @@ carries the named admission until then.
167
179
  | deno | deno (alt of typescript) | pull | — | n/a (pull) | 1 | dev+ci |
168
180
  | ruby | ruby-lsp | pull | — | n/a (pull) | 1 | ci |
169
181
  | csharp | csharp-ls | pull | — | n/a (pull) | 1 | ci |
170
- | typescript | typescript-language-server | push-only | silent | empty-first | 3 | dev+ci |
182
+ | typescript | typescript-language-server | push-only | silent | direct | 3 | dev+ci |
171
183
  | markdown | marksman | push-only | silent | direct | 3 | ci |
172
184
  | lua | lua-language-server | push-only | silent | direct | 3 | dev+ci |
173
185
  | python | pyright | push-only | publishes-versioned | direct | 2 | dev+ci |
@@ -177,7 +189,7 @@ carries the named admission until then.
177
189
  | dockerfile | docker-langserver | push-only | publishes-unversioned | direct | 2* | dev+ci |
178
190
  | dockerfile-official | docker-language-server (official) | push-only | publishes-versioned | direct | 2 | dev+ci |
179
191
  | toml | taplo | push-only | publishes-unversioned | direct | 2* | dev+ci |
180
- | terraform | terraform-ls | push-only | publishes-unversioned | empty-first | 2* | dev+ci |
192
+ | terraform | terraform-ls | push-only | publishes-unversioned | direct | 2* | dev+ci |
181
193
  | prisma | @prisma/language-server | push-only | publishes-unversioned | direct | 2* | dev+ci |
182
194
  | php | intelephense | push-only | publishes-unversioned | empty-first | 2* | dev+ci |
183
195
  | zig | zls | push-only | publishes-unversioned | direct | 2* | dev+ci |
@@ -201,8 +213,9 @@ and were characterized `push-only` in the run above).
201
213
  - **Mode ≠ tier, and the split needs BOTH axes.** Push-only further splits along
202
214
  latency (does anything publish on a clean transition? — silence is the only
203
215
  budget-wait case, because pi-lens's publish handler emits and early-returns the
204
- wait on every publish, versioned or not, with the single #3310 exception of a
205
- held empty FIRST publish from an `empty-first` server) and currency-proof (is the publish
216
+ wait on every publish, versioned or not, with two exceptions: #3310's held
217
+ empty FIRST publish from an `empty-first` server, and #4763's held empty
218
+ publish from opengrep before `semgrep/rulesRefreshed`) and currency-proof (is the publish
206
219
  versioned, i.e. provably about the live edit?). The 4-way
207
220
  `probe-clean-signal.mjs` measurement drives this: ast-grep → 2, yaml/opengrep →
208
221
  2\*, typescript (clean file) → 3.
@@ -211,6 +224,32 @@ and were characterized `push-only` in the run above).
211
224
  `pubVersion=undefined`, so currency is only temporally correlated, not proven —
212
225
  a staleness-risk note, not a latency cost. An earlier hand-note called it Tier 2
213
226
  on the "re-publishes" observation alone; the phase-aware probe refines it to 2\*.
227
+ - **opengrep's first publish depends on its config (#4763).** With a local rule
228
+ file the rules load before the first scan and `semgrep/rulesRefreshed` precedes
229
+ the first publish (`direct`, the column above). With `--config auto` (the
230
+ default pi-lens launch) opengrep scans the opened document before its rules
231
+ load, logs "Rules not loaded yet, not scanning anything" and publishes `[]`;
232
+ it then sends `semgrep/rulesRefreshed` and republishes every open document
233
+ (opengrep@60ed3b3 `Scan_helpers.run_semgrep` / `refresh_rules`, unchanged since
234
+ v1.0.0). Cold, online, 1.30.0 x3 and 1.32.0 x2: `[]` at +11..18 ms, the
235
+ notification at +0.7..1.0 s, the findings 0.25..0.5 s later. Warm: `didChange`
236
+ publishes nothing; the reopen pi-lens sends instead (`reopenOnResync`)
237
+ publishes the fresh scan once, +0.25..0.4 s on both versions; a reopen with
238
+ `didSave` publishes twice (+0.3..0.9 s), a lone `didSave` once (+0.25..0.5 s).
239
+ Rules that never load (offline) leave the `[]` as the only publish and
240
+ `window/showMessage` carries the error after it (#4764). Measured offline on
241
+ the built tree, nine touches: the edit path (`with-auxiliary`) waits the
242
+ aux grace ceiling (about 2 s) for six touches, then the existing demotion
243
+ (`aux_wait_demoted`) skips the wait (0 ms); the explicit all-scope
244
+ `lsp_diagnostics` call waits the full wait budget (3 s) every time and
245
+ reports the coverage notice. The strategy marker
246
+ `emptyUntilRulesRefreshed` holds that `[]`, released by the notification, not
247
+ by a timer. The other three auxiliaries do not need it, measured in
248
+ `tests/fixtures/opengrep-lsp-trace/auxiliary-first-publish.json`: ast-grep
249
+ compiles its rules before the first parse (3/3, first publish carries the
250
+ findings at +30..35 ms), zizmor audits inline and publishes once (3/3, +3 ms;
251
+ its source runs every audit, online ones included, before the one publish),
252
+ typos has the dictionary compiled in (3/3, +0..1 ms).
214
253
  - **typescript's clean behavior is diagnostic-set-dependent (major probe finding).**
215
254
  On a DIRTY file it re-publishes (version-lessly) after every change — the dirty
216
255
  fixture measures 2\*. On a genuinely CLEAN file (the `typescript-clean` fixture)
@@ -242,6 +281,60 @@ and were characterized `push-only` in the run above).
242
281
  is not the bottleneck. The cost on a clean with-auxiliary touch is the *silent
243
282
  primary* (typescript), a pre-existing Tier-3 cost independent of ast-grep.
244
283
 
284
+ ## Save-triggered servers: per-server verdict (#3405)
285
+
286
+ Population: every server that declares `textDocumentSync.save` in
287
+ `docs/servercapabilities.md` (15 `save`, 5 `save+text`), plus zizmor, which
288
+ registers `textDocument/didSave` dynamically. Verdicts are moved from the #4768
289
+ PR body (merged as 11cf30f8d) and re-read on origin/master d21f7d267: each
290
+ server's registry entry is in `clients/lsp/server.ts`, and each save declaration
291
+ matches `docs/servercapabilities.md`. `publishes after save only` is `no` when
292
+ the server publishes without a save, `yes` when only a save publishes, and
293
+ `unknown` when nothing was measured. A `source` row cites an external
294
+ repository at the pinned commit; those commits were not re-fetched here.
295
+
296
+ | server | save as declared | publishes after save only | verdict | evidence |
297
+ |---|---|---|---|---|
298
+ | expert | `save` | no | Measured: answers with no `didSave` once the seed is under `lib/`. Gated (`lspGate: true`). | #4768 arms A, B, C; nightly run 39852672584 (answered on call 6, 10955 ms); `tests/fixtures/nightly-floors/expert-readiness.json` |
299
+ | cpp (clangd 22.1.0) | `save` | no | Measured: publishes on `didOpen` alone (97 ms, 3 diagnostics). Gated. Open conflict with #4527, see note 2. | #4768 local probe; #4527 wire scenario (issue comment) |
300
+ | lua | `save` | no | Measured: the first publish carries 6 diagnostics at 135 ms; a save adds a late republish at 3.7 s. Gated. | #4768 local probe |
301
+ | python-jedi | `save` | no | Measured: publishes on `didOpen` alone (about 1 s). Gated. | #4768 local probe; `clients/python-environment.ts:421` (id) |
302
+ | opengrep (aux) | `save` | no | Measured: a save rescans and republishes (#3482); it also publishes on open once its rules load. Auxiliary, not gated. | `clients/lsp/wait-policy/strategies.ts:100`; Key findings above (#4763) |
303
+ | gleam | `save` | no | Source: a save only marks the project changed and drops the in-memory cache; the publish comes from `CompilePlease`. Gated. | gleam-lang/gleam `0d9fa18ddb69`, `language-server/src/server.rs` (`SourceFileSaved`, `discard_in_memory_cache`, `compile_please`) |
304
+ | go (gopls) | `save` | no | Source: `DidSave` calls `didModifyFiles`, the path a change takes. Gated. | golang/tools `02c9e4cb4c2f`, `gopls/internal/server/text_synchronization.go` |
305
+ | zig (zls) | `save` | no | Source: a save runs the build-on-save watch update and autofix; ast-check diagnostics come from changes. Gated. | zigtools/zls `82ba5351ca8a`, `src/Server.zig` (`saveDocumentHandler`) |
306
+ | rust (rust-analyzer) | `save` | no | Source: a save starts flycheck (`cargo check`); native diagnostics come from pull mode and do not wait for it. Exempt: runner availability. | rust-lang/rust-analyzer `0c4d74686b21`, `crates/rust-analyzer/src/handlers/notification.rs` (`handle_did_save_text_document`); matrix tier 1 |
307
+ | terraform | `save` | no | Source: `terraform validate` runs on save only with the experimental `ValidateOnSave`, off by default. Gated. | hashicorp/terraform-ls `3dbe85a2b4e1`, `internal/langserver/handlers/did_save.go` |
308
+ | fsharp | `save+text` | no | Source: a save holds the source and refreshes code lenses; diagnostics come from open and change checks. Exempt: 0 findings in every run. | ionide/FsAutoComplete `8f011f1395a4`, `src/FsAutoComplete/LspServers/AdaptiveFSharpLspServer.fs` (`TextDocumentDidSave`); nightly run 39845687189 |
309
+ | zizmor (dynamic) | not declared (`textDocumentSync` only) | no | Source: `didSave` is registered dynamically and pi-lens does not map that registration, so no save is sent. Auxiliary. | zizmor `crates/zizmor/src/lsp.rs` (`initialized`); `clients/lsp/wait-policy/strategies.ts:400-410` (#3548) |
310
+ | clojure | `save+text` | unknown | Unverified: not measured. Gated; one save per write. | none |
311
+ | fish | `save+text` | unknown | Unverified: not measured. Gated; one save per write. | none |
312
+ | tinymist | `save` | unknown | Unverified: not measured. Gated (typst fixture); one save per write. | none |
313
+ | cue | `save` | unknown | Unverified: not measured. Gated; one save per write. | none |
314
+ | csharp | `save+text` | unknown | Unverified: not measured. Pull mode, so diagnostics are requested and a save is unlikely to be the only trigger. Gated. | matrix row (csharp-ls, tier 1) |
315
+ | deno | `save` | unknown | Unverified: not measured. Pull mode. Gated. | matrix row (deno, tier 1) |
316
+ | svelte | `save` | unknown | Unverified: not measured. Pull mode. Gated. | matrix row (svelte-language-server, tier 1) |
317
+ | powershell | `save+text` | unknown | Unverified: not measured. Exempt: intermittent. | none |
318
+ | cmake | `save` | unknown | Unverified: the local probe published nothing in either arm (12 s each) with an `if(` seed, so inconclusive. Exempt: upstream documents no diagnostics. | #4768 local probe (no named command) |
319
+
320
+ Notes.
321
+
322
+ 1. Probe. The only command #4768 names is `node scripts/smoke-tools.mjs --lsp-gate`
323
+ (the nightly `tool-smoke.yml` step "LSP diagnostics clean-gate"). It runs
324
+ the gated fixture rows and does not write per-server save verdicts. The local
325
+ probes behind the cpp, lua, python-jedi and cmake rows, and the Expert arms
326
+ run outside CI, are not named in #4768's body, so no command regenerates this
327
+ table. Each row cites its own evidence instead.
328
+ 2. Open conflict, cpp. #4527 records a clangd 22.1.0 wire scenario in which the
329
+ save sender changes the outcome (base 1 of 5, head 5 of 5). #4768 records clangd
330
+ publishing on `didOpen` alone. The two records are not reconciled here; the row
331
+ keeps #4768's verdict.
332
+ 3. Citations corrected against master. #4768 cites `clients/lsp/client.ts:4410`
333
+ for `sendDidSave`; it is at `clients/lsp/client.ts:4909`, with the save-capability
334
+ gate at line 4917. The opengrep rescan claim is at
335
+ `clients/lsp/wait-policy/strategies.ts:100`; line 345 is the
336
+ `emptyUntilRulesRefreshed` hold.
337
+
245
338
  ## Completing the matrix
246
339
  The fixtures (`tests/fixtures/tool-smoke/<lang>/`) are durable and cover every
247
340
  registered server. `mode` is read from the server's advertised capabilities at
@@ -274,7 +367,7 @@ Telemetry only — never a CI gate. Compares each probed server's observed
274
367
  marker; a mismatch means the marker may need a human update (#529). `unknown`
275
368
  observations are never compared (a slow/absent server is not evidence either way).
276
369
 
277
- _None observed as of the last probe run._
370
+ - **[silent-not-marked]** observed silent on clean transitions but wait-policy/strategies.ts has no silentOnClean marker for "typescript7" — cascade is burning the full in-lane wait it could skip (the pre-#458 situation)
278
371
 
279
372
  ## Capability matrix refresh state (nightly-generated)
280
373
 
@@ -283,5 +376,5 @@ date-based `direct` expiry (#3401) and consecutive-night `idle-eviction`
283
376
  counts (#3989). Regenerated every run; never a measurement.
284
377
 
285
378
  ```json
286
- {"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"}}}
379
+ {"idle-eviction":{"docker-official":{"nights":[{"day":"2026-10-23","rssMb":62,"coldMs":883},{"day":"2026-10-24","rssMb":62,"coldMs":957}]},"kotlin":{"nights":[{"day":"2026-10-25","rssMb":270,"coldMs":2522}]},"powershell":{"nights":[{"day":"2026-10-25","rssMb":167,"coldMs":2967}]},"rust":{"nights":[{"day":"2026-10-25","rssMb":596,"coldMs":2927}]},"svelte":{"nights":[{"day":"2026-10-25","rssMb":232,"coldMs":2674}]},"zizmor":{"nights":[{"day":"2026-10-23","rssMb":55,"coldMs":1661},{"day":"2026-10-24","rssMb":57,"coldMs":1683}]}}}
287
380
  ```
@@ -15,7 +15,7 @@ respawned server reports every finding it reported before eviction; the
15
15
  content-bound coverage check the auxiliary freeze depends on. A server that
16
16
  cannot demonstrate it is never proposed for eviction on perf grounds alone.
17
17
 
18
- _Last generated: 2026-10-10 on linux; 48 registry servers: 8 eligible, 0 vetoed, 16 inconclusive, 24 unavailable (0 not reached: budget)._
18
+ _Last generated: 2026-10-25 on linux; 49 registry servers: 33 eligible, 0 vetoed, 2 inconclusive, 14 unavailable (0 not reached: budget)._
19
19
 
20
20
  ## Per-server rows
21
21
 
@@ -35,54 +35,55 @@ step log only, because it flaps.
35
35
 
36
36
  | server | role | declared | result | reason | respawn | coverage |
37
37
  |---|---|---|---|---|---|---|
38
- | ast-grep | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
39
- | bash | primary | transparent | unavailable | server-not-started | n/a | n/a |
38
+ | ast-grep | auxiliary | unmeasured | eligible | · | ok | preserved |
39
+ | bash | primary | transparent | eligible | · | ok | preserved |
40
40
  | clojure | primary | transparent | eligible | · | ok | preserved |
41
41
  | cmake | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
42
42
  | cpp | primary | transparent | eligible | · | ok | preserved |
43
43
  | csharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
44
- | css | primary | transparent | unavailable | server-not-started | n/a | n/a |
45
- | cue | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
44
+ | css | primary | transparent | eligible | · | ok | preserved |
45
+ | cue | primary | unmeasured | eligible | · | ok | preserved |
46
46
  | dart | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
47
47
  | deno | primary | transparent | eligible | · | ok | preserved |
48
- | docker | primary | transparent | unavailable | server-not-started | n/a | n/a |
49
- | docker-official | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
48
+ | docker | primary | transparent | eligible | · | ok | preserved |
49
+ | docker-official | primary | unmeasured | eligible | · | ok | preserved |
50
50
  | elixir | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
51
- | expert | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
52
- | fish | primary | transparent | unavailable | server-not-started | n/a | n/a |
51
+ | expert | primary | unmeasured | eligible | · | ok | preserved |
52
+ | fish | primary | transparent | eligible | · | ok | preserved |
53
53
  | fsharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
54
- | gleam | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
54
+ | gleam | primary | unmeasured | eligible | · | ok | preserved |
55
55
  | go | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
56
56
  | haskell | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
57
- | html | primary | transparent | unavailable | server-not-started | n/a | n/a |
57
+ | html | primary | transparent | eligible | · | ok | preserved |
58
58
  | java | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
59
59
  | json | primary | transparent | eligible | · | ok | preserved |
60
- | kotlin | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
61
- | lua | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
60
+ | kotlin | primary | unmeasured | eligible | · | ok | preserved |
61
+ | lean | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
62
+ | lua | primary | unmeasured | eligible | · | ok | preserved |
62
63
  | marksman | primary | transparent | eligible | · | ok | preserved |
63
64
  | nix | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
64
65
  | ocaml | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
65
66
  | omnisharp | primary | unmeasured | unavailable | no-fixture | n/a | n/a |
66
67
  | opengrep | auxiliary | transparent | eligible | · | ok | preserved |
67
- | php | primary | transparent | unavailable | server-not-started | n/a | n/a |
68
- | powershell | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
69
- | prisma | primary | transparent | unavailable | server-not-started | n/a | n/a |
70
- | python | primary | transparent | unavailable | server-not-started | n/a | n/a |
68
+ | php | primary | transparent | eligible | · | ok | preserved |
69
+ | powershell | primary | unmeasured | eligible | · | ok | preserved |
70
+ | prisma | primary | transparent | eligible | · | ok | preserved |
71
+ | python | primary | transparent | eligible | · | ok | preserved |
71
72
  | python-jedi | primary | transparent | eligible | · | ok | preserved |
72
73
  | ruby | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
73
- | rust | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
74
+ | rust | primary | unmeasured | eligible | · | ok | preserved |
74
75
  | shuck | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
75
- | svelte | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
76
+ | svelte | primary | unmeasured | eligible | · | ok | preserved |
76
77
  | swift | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
77
- | terraform | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
78
- | tinymist | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
79
- | toml | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
78
+ | terraform | primary | unmeasured | eligible | · | ok | preserved |
79
+ | tinymist | primary | unmeasured | eligible | · | ok | preserved |
80
+ | toml | primary | unmeasured | eligible | · | ok | preserved |
80
81
  | typescript | primary | transparent | eligible | · | ok | preserved |
81
- | typos | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
82
- | vue | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
83
- | yaml | primary | transparent | unavailable | server-not-started | n/a | n/a |
84
- | zig | primary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
85
- | zizmor | auxiliary | unmeasured | inconclusive | not-evicted | not-evicted | n/a |
82
+ | typos | auxiliary | unmeasured | eligible | · | ok | preserved |
83
+ | vue | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
84
+ | yaml | primary | transparent | eligible | · | ok | preserved |
85
+ | zig | primary | unmeasured | eligible | · | ok | preserved |
86
+ | zizmor | auxiliary | unmeasured | eligible | · | ok | preserved |
86
87
 
87
88
  ## Declared versus measured
88
89
 
@@ -90,15 +91,22 @@ step log only, because it flaps.
90
91
  or `info` line is for a maintainer to act on in a follow-up; this run changed
91
92
  nothing.
92
93
 
93
- - **bash** [info] declared transparent with no evidence this run: unavailable (server-not-started)
94
- - **css** [info] declared transparent with no evidence this run: unavailable (server-not-started)
95
- - **docker** [info] declared transparent with no evidence this run: unavailable (server-not-started)
96
- - **fish** [info] declared transparent with no evidence this run: unavailable (server-not-started)
97
- - **html** [info] declared transparent with no evidence this run: unavailable (server-not-started)
98
- - **php** [info] declared transparent with no evidence this run: unavailable (server-not-started)
99
- - **prisma** [info] declared transparent with no evidence this run: unavailable (server-not-started)
100
- - **python** [info] declared transparent with no evidence this run: unavailable (server-not-started)
101
- - **yaml** [info] declared transparent with no evidence this run: unavailable (server-not-started)
94
+ - **ast-grep** [proposal] declared unmeasured but eviction and respawn preserved its findings
95
+ - **cue** [proposal] declared unmeasured but eviction and respawn preserved its findings
96
+ - **docker-official** [proposal] declared unmeasured but eviction and respawn preserved its findings
97
+ - **expert** [proposal] declared unmeasured but eviction and respawn preserved its findings
98
+ - **gleam** [proposal] declared unmeasured but eviction and respawn preserved its findings
99
+ - **kotlin** [proposal] declared unmeasured but eviction and respawn preserved its findings
100
+ - **lua** [proposal] declared unmeasured but eviction and respawn preserved its findings
101
+ - **powershell** [proposal] declared unmeasured but eviction and respawn preserved its findings
102
+ - **rust** [proposal] declared unmeasured but eviction and respawn preserved its findings
103
+ - **svelte** [proposal] declared unmeasured but eviction and respawn preserved its findings
104
+ - **terraform** [proposal] declared unmeasured but eviction and respawn preserved its findings
105
+ - **tinymist** [proposal] declared unmeasured but eviction and respawn preserved its findings
106
+ - **toml** [proposal] declared unmeasured but eviction and respawn preserved its findings
107
+ - **typos** [proposal] declared unmeasured but eviction and respawn preserved its findings
108
+ - **zig** [proposal] declared unmeasured but eviction and respawn preserved its findings
109
+ - **zizmor** [proposal] declared unmeasured but eviction and respawn preserved its findings
102
110
 
103
111
  ## Reasons
104
112