pi-lens 4.4.4 → 4.4.6

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 (191) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +45 -3
  3. package/config/biome/core.jsonc +3 -3
  4. package/config/dependency-cruiser-eager-allowlist.json +1 -0
  5. package/dist/{chunk-UBOQLVT2.js → chunk-2DDDCJDL.js} +4 -4
  6. package/dist/{chunk-RKKOYPRA.js → chunk-2DMLM3ZO.js} +13 -15
  7. package/dist/chunk-2F47TQOA.js +73 -0
  8. package/dist/{chunk-O4NWQT6I.js → chunk-2PHMIAKO.js} +4 -4
  9. package/dist/{chunk-DGUKIYSI.js → chunk-2RLWJO5K.js} +8 -10
  10. package/dist/{chunk-S67KYG37.js → chunk-2X4VLOCC.js} +2 -2
  11. package/dist/{chunk-TIQ2PKDW.js → chunk-3MYEA7QD.js} +4 -4
  12. package/dist/{chunk-3DA2JDOL.js → chunk-3WEPUD2V.js} +551 -203
  13. package/dist/{chunk-AMERCH6V.js → chunk-4AVZ3TG7.js} +15 -16
  14. package/dist/{chunk-IYNJ6YPZ.js → chunk-4PCQCU47.js} +4 -4
  15. package/dist/chunk-4WX4CTUE.js +57 -0
  16. package/dist/{chunk-P63GXC37.js → chunk-5APMQ2IJ.js} +31 -4
  17. package/dist/{chunk-ZIVJBOO3.js → chunk-5CV5ITZF.js} +2 -2
  18. package/dist/{chunk-6DLWKFEX.js → chunk-5ZR3APIM.js} +41 -42
  19. package/dist/{chunk-XTBDCR27.js → chunk-63RIVFQI.js} +4 -4
  20. package/dist/{chunk-GSLNCYGG.js → chunk-75SY4F24.js} +13 -14
  21. package/dist/{chunk-U44DJXQP.js → chunk-7RQXA5GG.js} +15 -18
  22. package/dist/chunk-A3YNG5KP.js +45 -0
  23. package/dist/{chunk-5OFV52AM.js → chunk-AE37FEGH.js} +1 -1
  24. package/dist/{chunk-BWD5EPKO.js → chunk-AMXIUN2R.js} +4 -6
  25. package/dist/{chunk-3KAZU3VR.js → chunk-ARD426WI.js} +2 -2
  26. package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
  27. package/dist/{chunk-YH5MVY2U.js → chunk-BHUWL2Y3.js} +7 -7
  28. package/dist/{chunk-CT4MN5IU.js → chunk-BI5LAQ3Y.js} +353 -359
  29. package/dist/{chunk-KAPJINKN.js → chunk-BM5GS6ZH.js} +2 -2
  30. package/dist/{chunk-TLX72JTG.js → chunk-BWYQUPOS.js} +1 -1
  31. package/dist/chunk-CFRQMBGP.js +49 -0
  32. package/dist/{chunk-RMLC67LF.js → chunk-CJYKEW2L.js} +2 -30
  33. package/dist/chunk-CKEQFGLT.js +32 -0
  34. package/dist/{chunk-IWDLU6K3.js → chunk-DC4CFXM5.js} +4 -6
  35. package/dist/{chunk-ZVUL7QYY.js → chunk-DMSLNKF7.js} +29 -32
  36. package/dist/{chunk-KN35K52N.js → chunk-DQXSPYRI.js} +3 -3
  37. package/dist/{chunk-HYGZEMX6.js → chunk-EVDGNG4F.js} +11 -5
  38. package/dist/{chunk-SRYEJNES.js → chunk-F5Z6URKM.js} +2 -2
  39. package/dist/{chunk-UMS2MFPZ.js → chunk-F6X3YJWD.js} +2 -3
  40. package/dist/{chunk-XYURS6EN.js → chunk-FA5LDARD.js} +15 -17
  41. package/dist/{chunk-24AKHFGP.js → chunk-FFL3A2VP.js} +6 -6
  42. package/dist/chunk-FJIVKLPH.js +31 -0
  43. package/dist/chunk-G2B7F6ZU.js +88 -0
  44. package/dist/{chunk-US7ECLD7.js → chunk-GAACZY6R.js} +131 -41
  45. package/dist/{chunk-MZGQNL3Y.js → chunk-GMTFDAOK.js} +12 -13
  46. package/dist/{chunk-VOOAPROD.js → chunk-GNSIWBAT.js} +3 -3
  47. package/dist/chunk-GTAI2J6U.js +27 -0
  48. package/dist/{chunk-RVK72CZX.js → chunk-GZE7WOI4.js} +1362 -459
  49. package/dist/{chunk-IUE7SSKV.js → chunk-H7HTEQUZ.js} +13 -7
  50. package/dist/{chunk-EUXZEFTV.js → chunk-HK6JVFZC.js} +3 -3
  51. package/dist/chunk-IPDG45G5.js +26 -0
  52. package/dist/{chunk-5HSRT26B.js → chunk-J6JP25XU.js} +16 -15
  53. package/dist/{chunk-HWCCCQNX.js → chunk-JL6CXUMW.js} +13 -6
  54. package/dist/{chunk-EBC36LNN.js → chunk-K2YGBXOA.js} +17 -17
  55. package/dist/{chunk-WMYE35PX.js → chunk-KLQVC3XC.js} +7 -5
  56. package/dist/{chunk-ATKJFDQN.js → chunk-KSR7RGQY.js} +12 -14
  57. package/dist/{chunk-POMLXPMY.js → chunk-KXF5R4UN.js} +1 -1
  58. package/dist/{chunk-LLJNQKQW.js → chunk-LEJOJDXL.js} +20 -13
  59. package/dist/{chunk-JUKMK5Y4.js → chunk-MA77RSFN.js} +10 -11
  60. package/dist/{chunk-GAQ7OQG6.js → chunk-MKVZQUEG.js} +85 -96
  61. package/dist/{chunk-2EECBNC5.js → chunk-MN7MHUXQ.js} +75 -0
  62. package/dist/{chunk-DEL2U6CM.js → chunk-MT6BVNFW.js} +16 -14
  63. package/dist/chunk-NDMCVUYK.js +507 -0
  64. package/dist/{chunk-HRNHZA3N.js → chunk-NIU2IPC5.js} +12 -16
  65. package/dist/{chunk-AGSS7277.js → chunk-NNKXDXXS.js} +7 -24
  66. package/dist/{chunk-V35JG4JB.js → chunk-OJLTLYHB.js} +152 -334
  67. package/dist/{chunk-J6MPGQTS.js → chunk-OLAWH5UQ.js} +81 -15
  68. package/dist/{chunk-T57LYLZT.js → chunk-OOU2WZZE.js} +1 -1
  69. package/dist/{chunk-CYRKQRPM.js → chunk-OSTKYB55.js} +2 -4
  70. package/dist/chunk-P4QNXS6I.js +27 -0
  71. package/dist/chunk-PKES3ISE.js +297 -0
  72. package/dist/{chunk-ROYSX2S5.js → chunk-PO45POGF.js} +2 -2
  73. package/dist/{chunk-T7FEBKXN.js → chunk-PPIBVH4R.js} +7 -9
  74. package/dist/{chunk-3RKP3FMS.js → chunk-PQJFG24Z.js} +295 -23
  75. package/dist/{chunk-KUA4OJ5Y.js → chunk-Q3UZHW6N.js} +846 -350
  76. package/dist/{chunk-N5FLEO7W.js → chunk-Q4EMRFNA.js} +37 -37
  77. package/dist/{chunk-5IUSNGOC.js → chunk-Q4FCYCRE.js} +28 -21
  78. package/dist/chunk-Q6D6VMI4.js +22 -0
  79. package/dist/{chunk-UZ2XCLYS.js → chunk-QGSTQH4D.js} +8 -8
  80. package/dist/{chunk-DUO2TU77.js → chunk-RZOXUSPC.js} +10 -4
  81. package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
  82. package/dist/{chunk-GMX5OS7B.js → chunk-S67UJDGQ.js} +11 -12
  83. package/dist/chunk-SCIUNBPF.js +44 -0
  84. package/dist/{chunk-RKBXZN3A.js → chunk-SJJYRZB4.js} +2 -2
  85. package/dist/chunk-SXGD4ANG.js +25 -0
  86. package/dist/{chunk-YCWYO6TQ.js → chunk-T7FTXGS3.js} +48 -45
  87. package/dist/{chunk-FM4RDMKT.js → chunk-TIQJPRDD.js} +115 -61
  88. package/dist/{chunk-XHJBS436.js → chunk-TIYGSODX.js} +25 -25
  89. package/dist/{chunk-S2HEXIWI.js → chunk-U2SDMG7C.js} +10 -6
  90. package/dist/{chunk-2KXTHF3M.js → chunk-U6OC3QEM.js} +253 -33
  91. package/dist/{chunk-AWSCPCN2.js → chunk-UCGQT677.js} +19 -19
  92. package/dist/chunk-UHGF5UT5.js +32 -0
  93. package/dist/{chunk-JW3YWBVB.js → chunk-UN4TEBWN.js} +17 -19
  94. package/dist/{chunk-ZHH37KZL.js → chunk-V3APN3DY.js} +17 -17
  95. package/dist/{chunk-ED36RF6Y.js → chunk-V63BC55Q.js} +1 -1
  96. package/dist/{chunk-XBJVAEEO.js → chunk-VG5JS5SW.js} +3 -2
  97. package/dist/{chunk-W66O5E25.js → chunk-VPBIMOAQ.js} +13 -15
  98. package/dist/chunk-VQH24FIP.js +37 -0
  99. package/dist/{chunk-YNE3RP52.js → chunk-VSFLRN5Y.js} +8 -1
  100. package/dist/{chunk-7D6L4MTX.js → chunk-W2V54OCL.js} +3 -3
  101. package/dist/{chunk-2FN63LPV.js → chunk-W5LGKNET.js} +13 -14
  102. package/dist/{chunk-IQWN5JCP.js → chunk-W5R5SABV.js} +13 -14
  103. package/dist/{chunk-R3T7CLQ2.js → chunk-WIZWZR4C.js} +41 -41
  104. package/dist/{chunk-TOY6QKOH.js → chunk-WQOIR3QY.js} +17 -17
  105. package/dist/{chunk-Y6GZHWSJ.js → chunk-XAIT2YGS.js} +6 -6
  106. package/dist/chunk-XCUHKYCQ.js +23 -0
  107. package/dist/{chunk-GSM5UU7A.js → chunk-XQCSWV2G.js} +44 -35
  108. package/dist/{chunk-OHKJ7PQF.js → chunk-YBSONGSZ.js} +43 -39
  109. package/dist/{chunk-GXFV6MYU.js → chunk-YISME6ON.js} +72 -39
  110. package/dist/chunk-YRD4ISED.js +30 -0
  111. package/dist/{chunk-SD4I7ZO4.js → chunk-YSBHPOY6.js} +43 -53
  112. package/dist/{chunk-QBFBRV2B.js → chunk-Z2XAOKHK.js} +4 -2
  113. package/dist/{chunk-5VSF4UUQ.js → chunk-Z7IGUAXL.js} +34 -39
  114. package/dist/{chunk-MPNJLASA.js → chunk-ZKXQKGWZ.js} +10 -13
  115. package/dist/{chunk-J64T55EI.js → chunk-ZQ6NZZTB.js} +75 -9
  116. package/dist/chunk-ZUUI3ZSA.js +38 -0
  117. package/dist/{chunk-7HXE67BN.js → chunk-ZYNI26MI.js} +2 -2
  118. package/dist/index.js +32674 -27567
  119. package/dist/mcp/analyze-cli.js +11 -12
  120. package/dist/mcp/cli.js +46 -45
  121. package/dist/mcp/server.js +1210 -574
  122. package/dist/mcp/worker.js +65 -65
  123. package/dist/probes/installer.js +21 -23
  124. package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
  125. package/docs/adr/README.md +1 -0
  126. package/docs/agent-tools.md +28 -7
  127. package/docs/ast-grep_rules_catalog.md +5 -3
  128. package/docs/configuration.md +12 -1
  129. package/docs/defect-shapes.md +738 -0
  130. package/docs/engineering-principles.md +12 -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/invariants/caches-stores.md +30 -0
  135. package/docs/invariants/dispatch-runners.md +164 -0
  136. package/docs/invariants/git-guard-host.md +53 -0
  137. package/docs/invariants/language-config.md +31 -0
  138. package/docs/invariants/lsp-trust-exec.md +286 -0
  139. package/docs/invariants/paths-os.md +59 -0
  140. package/docs/invariants/session-telemetry.md +74 -0
  141. package/docs/lsp-capability-matrix.md +105 -12
  142. package/docs/lsp-idle-eviction.md +37 -18
  143. package/docs/pi-lens-fixer.md +24 -2
  144. package/docs/pi-lens-investigator.md +14 -0
  145. package/docs/pi-lens-merge-policy.md +32 -17
  146. package/docs/pi-lens-monitor.md +66 -10
  147. package/docs/pi-lens-orchestration.md +41 -0
  148. package/docs/pi-lens-release.md +20 -0
  149. package/docs/pi-lens-retro.md +5 -4
  150. package/docs/pi-lens-reviewer.md +54 -7
  151. package/docs/pi-lens-subagent.md +10 -3
  152. package/docs/release-qa-baseline.md +19 -7
  153. package/docs/servercapabilities.md +47 -47
  154. package/docs/settings.md +9 -5
  155. package/docs/subagent-compat.md +1 -1
  156. package/docs/usage.md +1 -0
  157. package/package.json +8 -5
  158. package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
  159. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
  160. package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
  161. package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
  162. package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
  163. package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
  164. package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
  165. package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
  166. package/rules/rule-catalog.json +25 -1
  167. package/scripts/analyze-pi-lens-logs.mjs +15 -5
  168. package/scripts/lib/is-main-module.mjs +27 -0
  169. package/scripts/lib/scratch-home-env.mjs +21 -0
  170. package/scripts/rpc-load-check.mjs +4 -6
  171. package/scripts/warm-loader-cache.mjs +2 -5
  172. package/dist/chunk-3PTHXJXR.js +0 -28
  173. package/dist/chunk-3QED2P4V.js +0 -31
  174. package/dist/chunk-5WRPDP2A.js +0 -47
  175. package/dist/chunk-ABBOA7UD.js +0 -157
  176. package/dist/chunk-CUHSHSB6.js +0 -273
  177. package/dist/chunk-GL5LUMZE.js +0 -51
  178. package/dist/chunk-HAD7QRQI.js +0 -30
  179. package/dist/chunk-JORED7EX.js +0 -44
  180. package/dist/chunk-KYUB6QDC.js +0 -72
  181. package/dist/chunk-LZSEQW6A.js +0 -57
  182. package/dist/chunk-M2IFVFWU.js +0 -79
  183. package/dist/chunk-M2UD3LPU.js +0 -88
  184. package/dist/chunk-MBKQHGA7.js +0 -39
  185. package/dist/chunk-R7YOCSNV.js +0 -23
  186. package/dist/chunk-SKAMFC7A.js +0 -28
  187. package/dist/chunk-SYE6T2EB.js +0 -28
  188. package/dist/chunk-TRETHTQO.js +0 -26
  189. package/dist/chunk-UA7ZXYDR.js +0 -184
  190. package/dist/chunk-XTFDJI3T.js +0 -24
  191. package/dist/chunk-Z3CCVDUB.js +0 -76
@@ -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
@@ -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.
@@ -0,0 +1,30 @@
1
+ <important if="touching caches, stores, and project intelligence rules">
2
+
3
+ ### Caches, stores, and project intelligence
4
+
5
+ - Behavior-gating durable stores use `clients/durable-store.ts`: lock, re-read,
6
+ merge the caller delta, atomically publish, refresh coupled mirrors before
7
+ releasing the lock. Best-effort derived caches declare their loss policy.
8
+ - Every cache states its freshness axes, bound, eviction axis, and invalidation
9
+ source. A bounded entry count does not excuse unbounded bytes, timers, WASM
10
+ objects, or persisted evidence.
11
+ - Workspace diagnostics cache mtime-drift hashing is limited by
12
+ `CONTENT_HASH_MAX_BYTES` in `clients/content-stamp.ts`; larger entries retain
13
+ strict mtime invalidation. Persistent reverify keeps zero mtime tolerance;
14
+ session-state restore keeps its 1 ms tolerance.
15
+ - Tree-sitter's `queryBatchCache` is invalidated by `clearWasmInput` when a
16
+ trapped query heals, because an in-flight batch may have cached a result that
17
+ omitted the healed rule (#3834).
18
+ - Async publication carries a generation or epoch and checks it before and
19
+ after awaited work. Graph snapshots are immutable by replacement.
20
+ - Review-graph, snapshot, reverse-dependency, word-index, and call-graph data
21
+ use path identities and explicit partial-coverage markers. A capped walk is
22
+ lower-bound evidence, never a clean zero.
23
+ - Tree-sitter uses the shared client and file-major project passes. Grammar
24
+ crashes are blocked before load; source overrides record package/version
25
+ provenance. Real grammar and rule tests use the warmed shared client.
26
+ - `module_report` and `symbol_search` are read-only orientation surfaces.
27
+ `read_symbol` and `read_enclosing` return bodies and record pi read coverage;
28
+ outlines do not claim body coverage. MCP adapters call `lens-engine.ts` only.
29
+
30
+ </important>
@@ -0,0 +1,164 @@
1
+ <important if="touching dispatch, runners, formatters, and installers rules">
2
+
3
+ ### Dispatch, runners, formatters, and installers
4
+
5
+ - The analysed-state latch records a pipeline-owned target hash captured after
6
+ pi-lens writes and before LSP or dispatch awaits. `fileModified` also covers
7
+ side-effect files, so `postWriteStateHash` is the ownership discriminator;
8
+ an absent hash must not stamp the target with later disk bytes (#2499).
9
+ - The opaque prescan resolves its root once, through `opaquePrescanRoot`
10
+ (`clients/opaque-mutation-scan.ts`), and every consumer of that session root
11
+ asks the same owner: the baseline record and take, the head-move record and
12
+ take, and the root each held-primary send is scoped by. A
13
+ session whose cwd is not the coordinator's `projectRoot` — a concurrent
14
+ secondary session, which the host's session-start guard declines before any
15
+ `session_start` body runs — otherwise records its baseline and its HEAD under
16
+ one root and takes them under another, reporting `no-pending-snapshot` for a
17
+ command that did write. Scan evidence is scoped to the checkout it ran in: a
18
+ recognized write outside that root is kept (never cleared by a scan that
19
+ could not see it) and earns no authorship the scan cannot confirm.
20
+ - A bash command's writes are recovered from that session root AND from every
21
+ checkout the command ITSELF names — its `cd`/`pushd` target or a recognised
22
+ write operand — when that checkout is a linked worktree of the session's own
23
+ repository (`resolveOpaqueRecoveryRoots`, `sameCheckoutOtherRoot`). Both hooks
24
+ derive bounded root lists (`OPAQUE_RECOVERY_ROOT_CAP`) from the command text,
25
+ the session root, and the checkout each hook sees at its own instant, so a
26
+ worktree the command itself creates is admitted only at `tool_result` and its
27
+ missing baseline is reported as `partial-recognition-no-baseline`, while a
28
+ root both hooks admit still names one key for its record and its take; a
29
+ checkout of another repository, a checkout named past the cap, and a
30
+ git target under a non-checkout session root each leave one bounded
31
+ `opaque-recovery-root-refused` record per session. This is why a `cd` into a
32
+ sibling worktree no longer reads a clean `git status` in the wrong checkout as
33
+ "nothing changed". Relative operands resolve against the directory in effect
34
+ for their own segment (`scanShellWriteScopes`). That directory moves only for
35
+ an admitted form: `cd DIR` or `pushd DIR` whose one operand is a plain
36
+ path: bash's own word after quote removal, made only of admitted characters
37
+ (any quoted one, an escape bash also removes, an unquoted letter, digit or
38
+ `_./@%:,=+-`, and a leading `~` only as `~` or `~/`), starting with a
39
+ letter, digit, `_`, `.`, `/` or `~`; or a bare `popd` of a push the scan
40
+ admitted, entered at list start or after `&&`, `;`, a newline
41
+ or a backgrounded list, ended by `&&`, `;`, a newline or the end, and in no
42
+ pipeline or backgrounded list. A move entered after `&&` holds only to the end
43
+ of that `&&` chain, because it happened only if the left side succeeded. A
44
+ directory builtin in a pipeline or a backgrounded list leaves the directory
45
+ unchanged. Any other directory change, construct or shell-text builtin
46
+ returns the scan to the session root for the rest of the command.
47
+ - A recovered write is judged by the checkout that OWNS it, in both directions:
48
+ the ignore gate a synthetic bash-write dispatch passes asks the `.gitignore`
49
+ of the root that admitted the write (`_ownerRoot`), not the session root's, so
50
+ a linked worktree nested under a directory the session checkout ignores is
51
+ analysed instead of dropped silently (`.claude/worktrees/` in this
52
+ repository); and admission asks `analysis-root.ts`
53
+ (`canWriteAnalysisRoot(resolveAnalysisRoot(...))`) rather than re-deriving the
54
+ rule. Ownership is compared by REAL path, so a `cd` into a symlinked spelling
55
+ of a worktree keeps its authorship and its observed identity.
56
+ - `RUNNERS` declarations include file kinds. Runner selection is gated by file
57
+ kind and anchored at the file's language root, not by dispatch-root config or
58
+ declaration order. Runner children use `resolveToolCwd` with launcher markers.
59
+ - Automatic tests do not cross a Git checkout boundary, including through
60
+ filesystem aliases: `foreignGitRoot` (`clients/test-runner-client.ts`) gates
61
+ failed-first cache admission, retirement, every discovery path, and the
62
+ turn-end gate. Indeterminate ownership is not a foreign verdict, a deleted
63
+ target retires as `retired-missing`, and final rejections emit
64
+ `test-target-foreign-checkout`. Proven by
65
+ `tests/clients/test-runner-worktree-isolation.test.ts`.
66
+ - By design, a session whose cwd is a plain folder with no `.git` that holds several repositories, a submodule, or a nested linked worktree gets no automatic tests for the files inside them: any nested `.git` is a foreign checkout, and there is no per-project opt-in (maintainer decision, #3649/#3691). Run them explicitly.
67
+ - The one exception to that boundary is a linked worktree of the session's own repository (same git commondir, different top level, `resolveLinkedWorktreeOwner` in `clients/review-graph/git-identity.ts`, #3871): turn_end selects and runs its tests with that worktree's root as the project root (`clients/test-target-roots.ts`), so config, `node_modules` and the failed-first state are the worktree's own. A worktree root without its own runner install (no `node_modules/.bin`, venv or `vendor/bin`) is skipped with a counted `turn-end-test-root-skipped` row rather than run through `npx` or a bare interpreter; a reported location is rebased through `displayRoot` using the runner cwd first, then the dispatch root, only when that file exists, and otherwise remains as printed. A sibling worktree's file is still foreign to every other root. Python's ambient `VIRTUAL_ENV`, `CONDA_PREFIX`, or absolute `UV_PROJECT_ENVIRONMENT` is accepted for the session checkout, and for a linked worktree only when the environment root is inside that checkout; a skipped pytest row says that ambient environments were not borrowed when one is set. The edit worklist is the session's project worklist (#2504), so a session whose cwd is itself a linked worktree never sees an edit in the main checkout or a sibling and runs only its own tests. Each turn that edited files writes one `turn_end_test_selection` record to `latency.log` (candidates, selected, why not, and selected/candidates per owning root; first 8 roots, the rest in `rootsOmitted`; `selected` includes carried deferred targets, which no candidate bucket counts, so per-root `selected` can sum below it; one row of about 570 B per edit turn with candidates, bounded by log rotation only), so a turn with 0 tests is explained without the dbg lines the MCP route drops.
68
+ - Managed tools resolve through the registry and sanctioned availability seams.
69
+ Do not hand-roll install, PATH, or package-manager discovery. Use typed
70
+ `SpawnFailure.kind`; repair only `tool-not-found`.
71
+ - Windows LSP startup exit-code-1 failures are repairable only when the shared
72
+ command resolver finds no command or an npm shim target is absent; present
73
+ binaries that exit 1 remain runtime failures (#4263, #1199). The launch and
74
+ repair gate are pinned by `tests/clients/lsp/windows-startup-repair.test.ts`.
75
+ - Expected skips remain distinct from clean success and failure. Extend the
76
+ closed `RUNNER_SKIP_REASONS` taxonomy when policy intentionally defers work.
77
+ Preserve the skip reason through runner latency and model-facing delivery.
78
+ - `scripts/ci-verdict.mjs` ends every CLI path with `ci-verdict: exit <N> (<kind>)`;
79
+ read that final stdout line instead of `$?` after a pipe. `guard-bash` denies
80
+ the piped-status recurrence while allowing output-only pipes.
81
+ - A formatter is handed the file's identity, never the link that named it:
82
+ `realpathOrResolve` (`clients/path-utils.ts`) is the real path
83
+ of the nearest existing ancestor plus the missing tail, with no lexical `..`
84
+ collapse first. `formatFile` and `FormatService.formatFile` use it, so
85
+ `AGENTS.md -> CLAUDE.md` formats `CLAUDE.md` and Prettier's "is a symbolic
86
+ link" rejection never occurs. `FormatService.formatFile` also requires
87
+ `sessionRoot` and classifies the identity through `resolveAnalysisRoot`: an
88
+ `adopted` or `none` identity is refused, writes nothing, and records one
89
+ `adopted-root-writer-skipped` row (`writer: "format"`). The refusal is on
90
+ identity, not spelling, so a plain file outside every writable root (a
91
+ sibling package of a monorepo session cwd, say) is refused as well; a caller
92
+ that must format it passes that root as `sessionRoot`. Proven by
93
+ `tests/clients/format-service-symlink-identity.test.ts`.
94
+ - Formatter and autofix policy is config-first where the registry says so.
95
+ Formatting is strict by default. Autofix must carry per-diagnostic fixability
96
+ or a conservative capability allowlist.
97
+ - Analyzer and runner fallback filters must match the substituted surface's
98
+ contract. Empty output distinguishes clean, skipped, unavailable, errored,
99
+ inconclusive, and partial states.
100
+ - Every autonomous writer (pipeline autofix, immediate/deferred formatter, and
101
+ actionable-warning quickfix) resolves through `clients/tool-agreement.ts`.
102
+ Its declarative population assigns one evidence bucket and declines absent,
103
+ unreadable, unparseable, unsupported, or unregistered evidence; callers emit
104
+ bounded degradation records. Ktlint's standalone-CLI exception still
105
+ declines Gradle-owned projects without guessing a CLI version.
106
+ - Node tool agreement in `nodeAgreement` is established from the project's lockfile evidence in the deterministic order npm (`package-lock.json`) → pnpm (`pnpm-lock.yaml`, v9 `importers` and v6 top-level maps) → yarn (`yarn.lock`, v1 blocks and Berry `npm:` descriptors); the decision names the supplying lockfile, and missing, unreadable, unparseable, or shape-unsupported evidence declines.
107
+ - A whole-package fixer (`cargo clippy --fix`, `dart fix --apply`) rewrites
108
+ files pi's mutation queue does not hold, so it runs through
109
+ `runWithFixRestore` (`clients/fix-run-restore.ts`, #3598): hash the tool's
110
+ source files, capture agent mutations pi-lens observes during the run (the
111
+ tool_result seam and the mutation bridge), write them back after, one
112
+ degradation per run, and name any edit that cannot be restored. The restore
113
+ takes pi's queue entry for each sibling, one at a time (#3830). It starts
114
+ after the caller's scan of the tool's changes and is awaited only after the
115
+ target's hold is released, never inside it. The tool_result pipeline does not
116
+ await it (F's result must not wait on a sibling's holder; the loss notice is
117
+ queued as an advisory), the `agent_end` drain does, after the release: a queue entry is requested by something that holds no other
118
+ entry, except the multi-path LSP edit, which requests in ascending key order,
119
+ and nothing that holds an entry awaits the restore. Do not add a second
120
+ whole-package fixer without it, and do not await a queue entry while holding
121
+ another.
122
+ - A file's first write in a session blocks on the linter delta, not on every
123
+ linter error. The `tool_call` of the first classified write or edit
124
+ runs the file's inline linters (`PRE_EDIT_SEED_RUNNER_IDS`, tied to the
125
+ edit-scope census's LINTER lanes) over the bytes still on disk, under
126
+ `bounded()` with `PRE_EDIT_CAPTURE_BUDGET_MS` (500 ms), and installs their blocking
127
+ findings as `session.preEdit.<file>` beside the delta baseline. The capture
128
+ admits at most four active captures, aborts their process groups on abandonment
129
+ or session reset, and retains slots until teardown settles. It
130
+ only creates that record, and only while no baseline, tombstone or seed
131
+ exists, the bytes are the ones it read, and its session is current; each
132
+ dispatch only shrinks it (`classifyPreExisting`, identity plus line text,
133
+ one current finding per entry). A matched finding is reported as
134
+ pre-existing, never as a blocker, unless the inline record already holds
135
+ it. Language servers, type checkers, gated runners and scanners are never
136
+ seeded (maintainer scope, 2026-10-15). Collect-later linters and the MCP
137
+ route have no seed. Proven by
138
+ `tests/index-4483-first-write-seed-witness.test.ts`.
139
+ - `clients/dispatch/runners/runner-spawn-cwd-sweep.test.ts` is the population
140
+ guard for child cwd derivation. Add a reasoned migration row instead of a
141
+ pin-only update.
142
+ - Each real-bytes fixture under `tests/fixtures/runner-output/` records the
143
+ availability probe its runner sends (`availability`: the argv, the binary
144
+ that answered from its own banner, and the real exit status) and a real clean
145
+ run (`clean`; there is no prose alternative). The clean record is the
146
+ fixture's own invocation run in `tests/fixtures/runner-output-clean/<runner>`,
147
+ whose inputs are un-ignored by `.gitignore` on purpose. One gate,
148
+ `recordProblems` in `scripts/capture-runner-output.mjs`, refuses a record whose
149
+ version its own answer never printed, and a clean run whose argv is not this
150
+ fixture's; the capture and the census both call it.
151
+ `captured-real-output.test.ts` runs the REAL checker against that record
152
+ instead of mocking it, so a tool that rejects its own probe — helm 4 rejects
153
+ `--version` — reaches the replay; the clean bytes are what the matrix's clean
154
+ cell replays, in the clean workspace. `scripts/capture-runner-fixtures.mjs
155
+ --records-only` retrofits those records onto an existing fixture without
156
+ touching its work bytes, keyed on the fixture's own case.
157
+ Enforced by `tests/clients/dispatch/smoke-fixture-coverage.test.ts` and
158
+ `tests/clients/dispatch/tool-state-matrix.test.ts`.
159
+ - Every `parseToolRun` runner documents its nonzero-exit table; the documented
160
+ `ran` codes are pinned exactly so adding or removing one does not pass
161
+ silently, and each documented code needs an executable status fixture in the
162
+ runner's own test matrix (#3292).
163
+
164
+ </important>
@@ -0,0 +1,53 @@
1
+ <important if="touching git guard and host adapters rules">
2
+
3
+ ### Git guard and host adapters
4
+
5
+ - Git command classification has one lexer and one guarded-verb matcher seam.
6
+ Unknown wrappers and indirect guarded verbs fail closed. Text-consumer
7
+ allowances recurse through command substitutions and execution contexts. A
8
+ substitution's output is read both empty and opaque (shape 61).
9
+ - The commit gate reads two states: the inline-blocker map's latch
10
+ (`RuntimeCoordinator`), then the persisted `turn-end-findings` record. A
11
+ collect-later runner's blocking findings join the map through
12
+ `clients/deferred-runner-blockers.ts`, never a second store: the turn-end
13
+ late-runner lane records them before the blocker replay (so the replay is
14
+ their one delivery and the composer persists them), and the gate judges
15
+ answers that settled but no turn end has drained, then refreshes the
16
+ persisted record (`syncGitGuardRecord`) as the inline path does at
17
+ `tool_result`. Both sites call one verdict, `judgeDeferredRunnerFindings`
18
+ (freshness, then policy), and the record's `sources` and `lines` come from
19
+ `clients/inline-blocker-fields.ts`, shared with the pipeline's writer. A run
20
+ still in flight does not gate, and an edit to the file while its re-check is in
21
+ flight clears the record until that answer settles (#3814). The gate and the
22
+ record's writers in `clients/git-guard.ts` and the turn-end composer read it
23
+ at any age. Each blocker section keeps the session that wrote it (top-level
24
+ `sessionId`, other owners in `carriedBlockers`; a record without that field
25
+ is one owner's), and a writer replaces only its own session's sections.
26
+ Another session's section leaves only for a file a dispatch checked
27
+ whole and found clean (`checkedWholeFile`), or whose file is gone. Its text
28
+ no file owns (a project lane's report: CVEs, secrets, cascade) leaves only
29
+ when its owner rewrites it, or at a turn end once `DEFAULT_MAX_AGE_MS` has
30
+ passed since its owner's own write (`blockerWrittenAt`, per partition; the
31
+ record's own timestamp moves with every writer). A record written before
32
+ this version has no stamp: the first turn end of another session that
33
+ carries it (a composer write or a settled turn end) writes one, and its
34
+ window starts there. Only a write logs what it drops. The gate judges a
35
+ record alone only when this session is its sole owner. A settled turn end
36
+ drops this session's sections and another session's expired text no file
37
+ owns, and retires a record that is this session's own, claims no blocker, or
38
+ holds no structured claim (the `--lens-guard`-off writer's), with one
39
+ `record_retired` row (#4725). A dispatch that never answered
40
+ (`pipeline_crash`, `pipeline_error`) is latched per file, apart from the
41
+ record's latch, and only that file's own returning dispatch clears it.
42
+ - The shared-checkout guard refuses unsafe worktree mutation when another live
43
+ session and uncommitted work are both proven. It never auto-stashes.
44
+ - `mcp/server.ts` talks to pi-lens through `clients/lens-engine.ts`. A mirrored
45
+ capability is one engine method plus one route. MCP transport remains
46
+ hand-rolled and dependency-free.
47
+ - Host SDK imports are type-only, except the one lazy, caught lookup of pi's
48
+ `withFileMutationQueue` in `index.ts` (#3506), admitted by count in
49
+ `tests/host-sdk-type-only.test.ts`; `clients/file-mutation-queue.ts` detects
50
+ and records a second SDK copy. Runtime dependencies belong in
51
+ `dependencies`.
52
+
53
+ </important>
@@ -0,0 +1,31 @@
1
+ <important if="touching language and configuration rules">
2
+
3
+ ### Language and configuration
4
+
5
+ - `clients/language-registry.ts` is the identity source for language ids,
6
+ extensions, filenames, file kinds, LSP ids, and grammars. Consumers project
7
+ from it; they do not maintain parallel language tables.
8
+ - Agent-facing advisory text resolves names through `resolveLensToolName` with
9
+ the delivery host: pi uses `piName`, and MCP uses `mcpName` from
10
+ `TOOL_REGISTRY`. Known tools without a host mapping resolve to `undefined`,
11
+ so callers omit or rephrase them; pi-only rows require
12
+ `PI_ONLY_TOOL_REASONS`. Do not add a second name map or hard-code a pi tool
13
+ name in advisory output (#2535).
14
+ - `clients/config-core/` owns schema validation, normalization, merging,
15
+ provenance, deny precedence, merge strategies, trust-gated process specs,
16
+ and bounded migration records. Existing LSP, global, and project loaders
17
+ adopt it without adding another merge implementation.
18
+ - Canonical config is `.pi-lens.json` plus `~/.pi-lens/config.json`; locations,
19
+ legacy migrations, and namespaces live in the config-location/schema modules.
20
+ A new config key or environment flag needs a forcing function, stability tier,
21
+ diagnostic code, tests, and docs.
22
+ - `rules.<id>.ignorePaths` is an experimental, project-relative path denial
23
+ resolved by config-core with array-union semantics: global entries cannot be
24
+ cleared by project config. Ast-grep and tree-sitter apply it before scanning;
25
+ other runner output uses the shared rule-policy filter.
26
+ - `lens_diagnostics` has one model-facing diagnostic surface. `source` is
27
+ `session` or `lsp`; `scope` is `paths` or `workspace`; explicit paths always
28
+ win. Severity is a threshold. Retired compatibility names must not widen a
29
+ request into a workspace sweep.
30
+
31
+ </important>