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
@@ -0,0 +1,286 @@
1
+ <important if="touching lsp, trust, and process execution rules">
2
+
3
+ ### LSP, trust, and process execution
4
+
5
+ - `safeSpawnAsync` is the subprocess seam. It carries ambient abort behavior,
6
+ process-tree cleanup, output caps, typed failure kinds, and bounded timeouts.
7
+ Installs pass `ignoreAmbientSignal: true` and remain trust-gated.
8
+ It is also the lookup chokepoint. Under pi trust other than
9
+ `trusted`, every child's search path loses the session repository's own
10
+ directories, and a bare command that still resolves into them is refused
11
+ with a typed `trust-refused` result. "Session repository" is one rule in
12
+ `clients/session-repository.ts`, never a caller-threaded root: the kernel-real
13
+ path lies under `process.cwd()`, under a project-local bin dir of its
14
+ ancestors below HOME, or in a checkout sharing its git commondir; the data
15
+ dir never counts and a session at or above HOME owns nothing. Lookups that
16
+ start a path rather than a name (`which` answers, global bin dirs, the
17
+ installer's PATH walk, the LSP launcher) ask `isUntrustedProjectPath` or
18
+ `admittedLookupAnswer` for the same judgment, and every refusal writes one
19
+ `trust-refusal` row per target. A raw `node:child_process` start in the
20
+ runtime trees is a hole by construction:
21
+ `tests/config/spawn-chokepoint-sweep.test.ts` derives them from the module
22
+ binding and requires each to be routed, or admitted with a reason, evidence
23
+ and a pinned site count. Extend the seam; never add a per-caller guard. A
24
+ non-pi maintenance host that starts the checkout's own tools adopts trust at
25
+ its entry, as the MCP entry points do.
26
+ - Under pi, project trust is consumed through `isProjectTrusted`; pi-lens never
27
+ registers the host's trust-answer handler. `compileLspRegistry` is the one admission
28
+ seam for LSP executable fields: global config and built-ins remain allowed,
29
+ while project `command`, command overrides, `env`, and
30
+ `initializationOptions` require pi's `trusted` answer. Missing trust APIs are
31
+ fail-closed for those project fields with one bounded notice; installs keep
32
+ their existing compatibility policy. `tests/clients/lsp/lsp-registry-trust.test.ts`
33
+ and the LSP config/service suites pin the boundary.
34
+ Non-pi process entry points (`mcp/server.ts`, `mcp/worker.ts`,
35
+ `mcp/analyze-cli.ts`, and `mcp/cli.ts`) declare trusted execution once at
36
+ startup through `setProjectTrustState`: workspace trust belongs to their
37
+ calling client, and pi trust is not consulted.
38
+ `tests/mcp/server.smoke.test.ts` and `tests/mcp/analyze-cli.test.ts` pin it.
39
+ The standalone harness scripts that drive the built `dist/clients/lsp/`
40
+ service (`scripts/characterize-lsp.mjs`, `probe-clean-signal.mjs`,
41
+ `server-capabilities.mjs`, `measure-lsp-idle-eviction.mjs`, `bench-lsp.mjs`,
42
+ `smoke-tools.mjs`) are the same kind of entry point: each adopts trust once
43
+ through `adoptFixtureProjectTrust` (`scripts/lib/lsp-fixture-workspace.mjs`),
44
+ because a script that leaves trust `unknown` measures every refused server as
45
+ absent. `tests/config/lsp-script-trust-census.test.ts` fails a
46
+ `scripts/*.mjs` that reaches `dist/clients/lsp/` without it. The four nightly
47
+ producers that run under `continue-on-error` also report what they evaluated
48
+ to `scripts/lib/assert-evaluated.mjs` (one pure count function per producer,
49
+ called by the script and by its test); the nightly's floor step fails below
50
+ each measured floor and when a matrix cell classified at HEAD turned
51
+ `unknown` without a HEAD `firstMissed` stamp at least
52
+ `FIRST_PUBLISH_EXPIRY_DAYS` old (`tests/config/nightly-evaluated-floors.test.ts`).
53
+ Every other
54
+ `continue-on-error` producer either calls the same helper (`--count
55
+ <producer>=<n> --floor <m>` from a workflow step; `--min-pass`, the
56
+ complexity file count and the shuffle census's missing starts already do) or
57
+ needs none, and one census decides that: every `continue-on-error` site in a
58
+ `.github/workflows/*.yml` or `*.yaml` file and in a composite
59
+ `.github/actions/**/action.yml` or `action.yaml` is registered in
60
+ `tests/fixtures/nightly-floors/continue-on-error-sites.json` as `floored`
61
+ (naming the gating step and the floor text, which must sit in the argument
62
+ list of a named measuring invocation — `scripts/assert-evaluated.mjs`,
63
+ `scripts/smoke-tools.mjs`, `scripts/complexity-report.mjs` — on a top-level
64
+ line the shell executes, of a step whose `if:` is absent or a conjunction of
65
+ `always()`, `success()`, `!cancelled()` and one `github.event_name` or
66
+ `matrix.<name>` comparison the parsed document settles (the workflow's `on:`
67
+ keys, that job's `strategy.matrix` list), so
68
+ `!cancelled() && matrix.os == 'macos-latest'` counts only where the matrix
69
+ declares that leg; every other `if:` expression, including a trivially true
70
+ literal and a comparison no declared value satisfies, leaves the floor
71
+ unproven, and so does a job whose own `if:` the document proves never true).
72
+ A `\`-continued line and a line the previous one left unfinished with `&&`,
73
+ `||` or `|` are one command, so the measuring invocation must start the
74
+ joined command; an `exit` ends the script only in command position. A
75
+ `no-floor` row states the reader that makes an empty result visible, or
76
+ `governed-by` (naming the issue and the live tests that own the site, in
77
+ files vitest collects). The reader derives the population from the parsed
78
+ files, so it fails closed on a site the registry
79
+ does not name, on a producer file or a non-file entry it does not classify,
80
+ on a `continue-on-error` key in a location that is not a job or a step, and
81
+ on a floor whose evidence is not in the argument list of such an invocation
82
+ on a top-level command (a comment, a quoted command, a heredoc body, a
83
+ printed command, a function or block body, a subshell, a chained command, or
84
+ a line after an `exit`), or that names a step whose `if:` is outside that
85
+ allowlist; a floor comes from a run recorded in
86
+ `tests/fixtures/nightly-floors/measurements.json`. A
87
+ `# No floor (<issue>): <reason>` header above a job is human-facing copy
88
+ where one exists, not the record: six sites keep one (the five `lint.yml`
89
+ jobs and `install-smoke.yml`'s `mise-repro`), and the registry row the
90
+ census requires is the record.
91
+ The helper must stay importable without `dist/` (the refresh-PR job runs it
92
+ on a fresh checkout).
93
+ - LSP service generations, workspace-sweep holds, and repair latches use
94
+ versioned process singletons. Reset tears down the old generation before a
95
+ replacement can spawn. Idle eviction is lease-guarded and clears ownership
96
+ timers on every removal path.
97
+ - Production callers use the grouped experimental `LspCapabilities` adapter in
98
+ `clients/lsp/capabilities.ts`; direct `LSPService` module imports are limited
99
+ to that adapter and are enforced by
100
+ `tests/config/lsp-capabilities-import-sweep.test.ts` (#2372/#277).
101
+ - Idle-eviction policy is the registry's `idleEviction` field, declared per
102
+ server. The nightly (`scripts/measure-lsp-idle-eviction.mjs`) measures every
103
+ registry server's eviction cost and respawn safety into
104
+ `docs/lsp-idle-eviction.md` and changes no policy; a declaration change is a
105
+ follow-up that cites its row, or the nightly's draft promotion PR
106
+ (`bot/lsp-idle-evict-promote`, #3989: two consecutive eligible nights, idle
107
+ RSS floor, cold-start cap, hold list in
108
+ `scripts/lib/lsp-idle-eviction-promote.mjs`, derived from the registry test's
109
+ `HOLD_INDEXER_IDS` class; the PR also moves the id into
110
+ the registry test's `TRANSPARENT_IDS`; night memory in the matrix doc's
111
+ refresh-state block; never auto-merged, never demotes). `tests/config/lsp-idle-eviction-measurement.test.ts`
112
+ fails when a registry server can go unmeasured without an admission or when
113
+ the committed measurement vetoes a server declared `transparent`.
114
+ - The compiled registry holds the CATALOG ENTRY for every built-in with no
115
+ command override (`compileLspRegistry`), so the object the client registry
116
+ keeps (`SpawnedServer.info`) is the object `LSP_SERVERS`/`getServerById`
117
+ exposes; an overridden server keeps its own copy so its `spawn` and trust
118
+ admission never reach the catalog. A copy here is not a safe container: it is
119
+ a second registry whose entries swallow every arm a caller applies to the
120
+ first (history: `HISTORY.md`, 2026-10-19).
121
+ `tests/clients/lsp/lsp-registry-trust.test.ts` pins both directions;
122
+ `scheduleIdleEviction` records `lsp-idle-eviction-declined` once per server
123
+ per session when it arms no timer.
124
+ - The server-role vocabulary and the declared trait table have one owner,
125
+ `clients/lsp/server-traits.ts` (#1488, #1756 stage 1). Ask `isAuxiliary`,
126
+ never a comparison against the role literal, and read `notifyInflightLimit`
127
+ or `replyOrdering` through `serverTraits`, never by re-deriving a default;
128
+ `LspServerRole` is declared there and nowhere else, so a second
129
+ `"primary" | "auxiliary"` is a re-fork. `LSPServerInfo.role` is
130
+ non-optional: a row declares it, or the factory and custom-server builders
131
+ apply `DEFAULT_LSP_SERVER_ROLE`. Measured-behaviour markers (`silentOnClean`
132
+ and the census siblings named by `STRATEGY_TABLE_TRAITS`) stay on
133
+ `wait-policy/strategies.ts`, which their probes and expiry tests own; the two
134
+ tables stay disjoint. The auxiliary lifecycle and wait policy lives in
135
+ `clients/lsp/auxiliary-lifecycle.ts`, the diagnostic policy in
136
+ `clients/dispatch/auxiliary-lsp.ts`. Enforced by
137
+ `tests/config/lsp-role-predicate-sweep.test.ts` (production and `scripts/`
138
+ trees at zero inlined predicates) and
139
+ `tests/config/lsp-server-trait-table.test.ts` (registered-or-fail).
140
+ - Which auxiliaries the operator's configuration switches off (a kill switch
141
+ such as `--no-opengrep` / `opengrep.enabled=false`) has one owner,
142
+ `configDisabledAuxiliaryLspServerIds` in `clients/dispatch/auxiliary-lsp.ts`.
143
+ The explicit `lsp_diagnostics` probe and `lsp_navigation workspaceDiagnostics`
144
+ pass that set as `excludeServerIds` to both the touch and `getDiagnostics`,
145
+ through the flag resolver each host injects; the session's resource degrade
146
+ is not part of it. The probe's batch cache key comes from
147
+ `buildProbeScopeKey`, never equal to the workspace sweep's key, because the
148
+ sweep records before `pi-lens-ignore` and the probe after it.
149
+ - Every diagnostics entry route starts the same server set and gives the same
150
+ confirmation verdict under each server-selecting switch (`--no-opengrep`,
151
+ `opengrep.enabled=false`, a disabled or missing primary). Enforced by
152
+ `tests/tools/diagnostics-route-switch-matrix.test.ts`, which derives the
153
+ routes from every production access to an `LSPService` diagnostics member
154
+ and fails closed on an access it cannot classify, so a new read joins the
155
+ matrix or carries a reasoned exemption keyed by its `clientScope` and
156
+ `diagnostics` options. Each cell asserts the exact lines the route shows.
157
+ - A file no primary answered for is unconfirmed, never clean, whether the
158
+ primary could not start, was still starting, or is in `lsp.disabledServers`.
159
+ The one rule is `unansweredPrimaries` (clients/lsp/index.ts), which names
160
+ the disabled ones through `disabledPrimaries`
161
+ (clients/lsp/session-roots.ts, not `config.js`, whose import surface the
162
+ test mocks mirror). A `fallbackFor` alternate standing in for a disabled
163
+ owner keeps the denial as the cause when it cannot answer either; the
164
+ cascade names such a server once per session, not per neighbour.
165
+ Every route words the cause through `primaryUnavailableCause` and
166
+ `PRIMARY_UNAVAILABLE_CAUSE` (clients/lsp/diagnostic-binding.ts), never its
167
+ own sentence. A later write of such a file prints a one-line unconfirmed
168
+ status naming the cause, never the clean line.
169
+ - LSP roots never exceed the session-cwd ceiling. Root/config discovery uses
170
+ shared marker seams. Child cwd resolution uses `resolveToolCwd` and its
171
+ caller-specific markers.
172
+ - Temporary roots (#1129) are classified once per process by
173
+ `clients/ephemeral-root.ts`, on real paths on both sides. A directory inside
174
+ a real git checkout below `os.tmpdir()` (root or subdirectory) is a normal
175
+ LSP root with the ephemeral idle window, and `getProjectDataDir` gives it
176
+ its usual slug under `<base>/.ephemeral/<pid>-<8 hex>/`: normal within the
177
+ process, never read by another one, removed by the exit hook and, for a
178
+ dead pid, by the session-start sweep. A `pi-agent-*` path below the tmpdir
179
+ that no checkout owns is declined at `resolveLspServerCwd` with one
180
+ `lsp-root-declined` record per staging root per session.
181
+ - Per-path LSP notifications serialize read/build/send/record work. Pull
182
+ cancellation blocks a same-path replacement until settlement. Waits are
183
+ deadline- and abort-bounded, and silence is never clean.
184
+ - Document line addressing has one owner, `clients/lsp/content-scan.ts`: the
185
+ `\n` count behind the `lsp_document_send` record's `contentLineCount` and the
186
+ LSP sync bound (`countLfNewlines`), the last LSP-addressable line an
187
+ Incremental change spans, and one line's text (`lineTextAt`, which the
188
+ diagnostic-conversion call sites read) all come from it. The rule it owns is
189
+ the count and the one-line read: no other module may `split("\n")` document
190
+ content to obtain a line count or a single line — a send, a bound check, and
191
+ a line read ask this owner. A module that needs the whole line array (a
192
+ multi-line table, a per-line scan of its own document) keeps its `split`; the
193
+ array is the value it consumes, never a way to count or to reach one line.
194
+ - `touchFile` fires a type-2 watched-file announcement at entry for the first
195
+ seen content hash of a path, before the owner's didChange; it reaches every
196
+ other live client of the same server across package roots through the client
197
+ watch queue. Content hashes are session-scoped and bounded (#4156).
198
+ - A capability the client advertises has a sender, or the advertisement states
199
+ why it has none. `textDocument/didSave` follows a landed didOpen/didChange
200
+ only when the server declared `textDocumentSync.save` and the caller declared
201
+ the touch a save — the post-write sync, the explicit `lsp_diagnostics` query
202
+ and the MCP analysis's first touch (`analyzeFile`, the MCP hosts' post-write
203
+ route), never a sweep warm-up, cascade or sweep touch. The touch debounce
204
+ reads one rule: skip only when the bytes the server will hold once the path's
205
+ notify queue drains are this touch's content. The evidence is the client's
206
+ own sent-content record (`getSentContent`) AND `hasNotifyInFlight`, because
207
+ that record reports what landed and a send still running lands after a skip.
208
+ `hasNotifyInFlight` counts a content send only: a save-only send
209
+ (`sendDidSaveForHeldDocument`) cannot change the bytes or remove the document,
210
+ so it leaves the record final, while a didClose always counts. A client that
211
+ cannot answer either question is pushed, never skipped: the elapsed window
212
+ that used to decide there is gone (`formal/lsp-server-content`
213
+ `GateWindowReopen` is why). Its key is (path, server): the client scope never
214
+ re-pushes bytes a server holds. The debounce never drops a save: a saved touch
215
+ whose push it skipped sends the save alone (`notify.save`), and the save mark
216
+ names the content a `didSave` LANDED for, owned by the client's document
217
+ record and written only by the send continuation. Every rebuild of that
218
+ record carries the mark with the rest of the binding: Incremental's
219
+ text-budget eviction strips the payload, never the save evidence. A failed
220
+ carried save leaves the save owed; a failed standalone save gets one bounded
221
+ retry (`GateSaveRetry`, `MutGateSaveNoRetry`) and a retry that lands for
222
+ other bytes cannot suppress the save the next saved touch owes.
223
+
224
+ - Every server-produced `WorkspaceEdit` a path applies is bound to the bytes the
225
+ server computed it from. Both rename flows take the request instant before
226
+ they ask (`rename` right before `lspService.rename`, `renameFile` right before
227
+ `workspace/willRenameFiles`) and pass `captureRenameExpectedContent`'s map as
228
+ `expectedContent`; `clients/lsp/edits.ts` compares every bound file inside
229
+ pi's mutation queue before its first write, refuses the whole edit, and
230
+ records one `lsp-edit-stale-content` row naming the file. `renameFile` has no
231
+ target (nothing read the old path), so an unopened file there is best effort
232
+ by mtime, the same remainder the `rename` path carries. The evidence a file
233
+ is compared against the sent-content records of every client that
234
+ contributed a kept edit for that file, keyed by the registry client key; a
235
+ merged edit never falls back to a different client's priority record. The
236
+ records bind the file only when every contributor holds one; a contributor
237
+ with none leaves the file on the mtime rule, and the refusal names it. One
238
+ client's failed `willRenameFiles` never discards another client's answer,
239
+ of the same server id or not. `documentVersions` is
240
+ the other binding axis, for a server-initiated `workspace/applyEdit`. A new
241
+ apply site binds the content or states why it cannot.
242
+ - `touchFile` freezes content-bound auxiliary coverage at merge time. A later
243
+ publication cannot undo a finding drop. Auxiliary gaps narrow coverage and
244
+ never turn a primary answer inconclusive. When a primary touch is
245
+ inconclusive but the merged result contains answered diagnostics, dispatch
246
+ preserves only diagnostics from content-confirmed contributors and carries
247
+ the named primary gap as unconfirmed; only an empty inconclusive result is
248
+ skipped (#4219, #4231). Auxiliaries never confirm a file alone: a touch that
249
+ acquired auxiliaries but no primary that rooted for the file is inconclusive
250
+ with `primary-unavailable`, naming those primaries, and `getDiagnostics`
251
+ records the same ids as `unavailablePrimaryServerIds` (one rule,
252
+ `unansweredPrimaries`; an auxiliary-only language is unaffected).
253
+ - A server's `window/showMessage` is observed once per distinct text per
254
+ session (`lsp_server_message`), and an error-level message reporting that the
255
+ server's own config or rules failed to load records
256
+ `lsp-server-config-load-failed`. An AUXILIARY in that state never evaluated
257
+ the bytes it reports on, so its empty publications are refused as evidence
258
+ (`lsp_publish_dropped_server_config_failed`) and empty answers already stored
259
+ are retracted; a non-empty answer still flows, and a language-role server is
260
+ recorded but never gated. A refused publication still answers its send,
261
+ the server's own `semgrep/rulesRefreshed` clears the failure, and the
262
+ touch's `lsp-scanner-coverage-gap` reason carries the failure text. It
263
+ composes with the hold of the empty publish before the rules load (table:
264
+ `tests/clients/lsp/opengrep-pre-rules-publish-4763.test.ts`). Proven by
265
+ `tests/clients/lsp/opengrep-offline-config-failure.test.ts`. The same gate
266
+ (`auxiliaryEmptyIsNotEvidence`) refuses an auxiliary's UNVERSIONED empty
267
+ publication that lands in the phase of the path's stored or pending finding:
268
+ one rules generation (`semgrep/rulesRefreshed` count) and one client send.
269
+ Opengrep's open-documents scan publishes `[]` for files it did not target, so
270
+ that empty is no scan; a new send or a rules refresh clears as before, and a
271
+ versioned or language-server publication keeps last write wins
272
+ (`lsp-auxiliary-empty-after-finding`).
273
+ - The explicit `lsp_diagnostics` read checks `exceedsLspSyncLimits` once before
274
+ warm attachment or `touchFile`; an over-bound file returns a `too_large`
275
+ result with its byte/line measurement and records
276
+ `lsp-diagnostics-file-too-large` once per file per session.
277
+ - Every new LSP server has a smoke fixture or a documented alternate/toolchain
278
+ exemption. Real LSP-spawn tests belong in the serialized `lsp-spawn-heavy`
279
+ lane.
280
+ - A `fallbackFor` family is one primary for workspace grouping: a selected
281
+ preferred server and its sequential alternate do not disable the workspace-
282
+ pull fast path merely because both registry members match the file. Measure
283
+ the alternate independently; do not attribute the preferred server's
284
+ capabilities or diagnostics to it (#3939).
285
+
286
+ </important>
@@ -0,0 +1,59 @@
1
+ <important if="touching paths, data, and operating systems rules">
2
+
3
+ ### Paths, data, and operating systems
4
+
5
+ - Use `PathKeyedMap` for path-keyed memory. Choose
6
+ `normalizeEphemeralMapKey` for process-local hot indexes and `normalizeMapKey`
7
+ for long-lived shared state. Preserve original display paths separately.
8
+ - Resolve a path's identity once, where it enters (a tool argument, a write
9
+ event, `createDispatchContext`, `FormatService`), and hand it down. The
10
+ widget, delta-baseline and finding stores key a path that is already an
11
+ identity: they keep the syntactic key and resolve nothing per write
12
+ (maintainer decision 2026-10-24; shape 1). A walk or key derived from a caller
13
+ spelling instead answers for the link's project, not the file's.
14
+ - A path a host tool was given resolves through `resolveHostToolPath` (the
15
+ base expansion) or `resolveToolCallFilePath` (base plus pi's variant
16
+ ladder), never a bare `path.resolve(base, raw)`; see shape 74.
17
+ - Windows-shaped paths use `path.win32` functions. Use `toPosix`,
18
+ `splitPathSegments`, `isUnderDir`, `isSameOrWithin`, and
19
+ `isAtOrAboveHomeDir` instead of inline separator or containment logic.
20
+ - Data and log locations follow **Data directories and logs**; never hardcode
21
+ `.pi-lens` paths in writes or user-facing text.
22
+ - Probes and child processes pin `PI_LENS_HOME`, `PILENS_DATA_DIR`, `HOME`, and
23
+ install/log/cache directories to `.probe-home` under the worktree; never the
24
+ maintainer's real home, and never via `TMPDIR`/`TMP`/`TEMP`, which moves the
25
+ vitest harness home into the checkout (#3026).
26
+ - Scratch checkouts and `mktemp -d` never land under `/tmp` (tmpfs; #3526). Use
27
+ `~/.local/share/pi-lens-orchestrator/tmp/<lane>` for orchestrator and
28
+ reviewer scratch, `<worktree>/../probes-<pr>` for probes, and
29
+ `.claude/worktrees/` for a fixer's own worktree.
30
+ - Vitest also pins `HOME`, `USERPROFILE`, `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`
31
+ and `XDG_DATA_HOME` per worker, to a scratch directory under
32
+ `pi-lens-scratch`, so `os.homedir()` and every child a test spawns
33
+ resolve inside it. A test that sets `HOME` itself (`pinFixtureHome`) wins. The
34
+ real home stays reachable only as `REAL_HOME` from `tests/support/vitest-setup.ts`
35
+ (or `os.userInfo()`), and a file that spells either is a named row in
36
+ `tests/support/real-home-readers.ts` with a `// real-home: <reason>` header.
37
+ The managed bin directory refuses to resolve outside a pinned `PI_LENS_HOME`
38
+ (`assertManagedBinDirInsidePinnedHome`, `clients/installer/index.ts`).
39
+ - Vitest gives every worker its own `PI_LENS_HOME`, `<run-shared home>/worker-home-<run>-<pid>`
40
+ (#3721); log sinks bind their path at module load, so a `PI_LENS_HOME` assigned
41
+ in `beforeEach`/an `it` body moves nothing. A test process never truncates a log
42
+ under the real `~/.pi-lens` (`isTestProcessTargetingRealHome`); the first refusal
43
+ emits one `process.emitWarning` (visible on stderr) and folds a
44
+ `log-sink-truncate-refused` row into `pilens_health`. `vitest-setup.ts` also pins the orphan-backstop
45
+ directory through `resolveBackstopStateDir` (#3083) when the home IS the
46
+ run-shared one. Explicit per-case homes remain authoritative. Never bypass this
47
+ seam for its lock or stamp.
48
+ - Test tmp roots are swept by the worker that made them (#2912):
49
+ `tests/support/vitest-setup.ts` removes every `setupTestEnvironment` root at
50
+ `afterAll` and on SIGTERM; any other straggler reds its owner, so do not widen
51
+ the sweep. Registry: `tests/support/tmp-root-registry.ts`.
52
+ - Two vitest invocations may share one `TMPDIR`. An invocation judges and
53
+ sweeps only tmp entries owned by files its own workers loaded (#3314), so a
54
+ tmp fixture names its family in the prefix at its own `mkdtempSync` or
55
+ `setupTestEnvironment` call (#3306).
56
+ - New filesystem walkers use shared exclusions and ignore matching, cap
57
+ walk-down work, and use the correct home-ceiling policy for walk-up discovery.
58
+
59
+ </important>
@@ -0,0 +1,74 @@
1
+ <important if="touching session, telemetry, and delivery rules">
2
+
3
+ ### Session, telemetry, and delivery
4
+
5
+ - Registry root ownership (#3849): each holder's record in a pid entry's
6
+ `projectRootHolders` lists exactly the roots THAT holder registered (`host`
7
+ for `registerInstance`, a per-activation id for a declined secondary). Only
8
+ its own `deregisterInstanceRoot`, whole-entry removal, or cap eviction ends
9
+ a record; a root stays while any record lists it. No anonymous counts; one
10
+ settle (`settleRootHolders`) for every writer; `getInstanceRoots` reads.
11
+ - Session state is owned by the stable session identity and activation owner.
12
+ Detached callbacks resolve live emitters at delivery time and pair them with
13
+ their own activation context. Never use a process-global latest session.
14
+ - Process-global bridge dependencies and the quiet-window turn-summary holder
15
+ bind only from a live primary `SessionScope`; `clients/process-bridge.ts`
16
+ accepts only a strictly newer scope ticket, so a concurrent secondary or
17
+ stale activation cannot rebind a held bridge/task to its runtime (#4258).
18
+ - Session degradation uses the ledger's bounded once/count APIs and resets at
19
+ the correct primary session boundary. `SessionStartClassification`
20
+ (`clients/session-lifecycle.ts`): `primary` and `sequential-replacement`
21
+ (resume and reload) both run the full start and reset; only
22
+ `concurrent-secondary` skips the reset, since a subagent reset tears down the
23
+ primary's warm state. `secondary` belongs to the shutdown classification. A process-lifetime latch cannot store a
24
+ session fact without an explicit reset.
25
+ - Turn state is the turn's session's (#3613): `RuntimeCoordinator.beginTurn`
26
+ takes the ctx's stable session id and moves the coordinator's counters,
27
+ write-order turn and change window only for its own session, and per-turn
28
+ warnings are partitioned by the session that recorded them. Every
29
+ producer and reader passes that id (`tool_result`, a partial apply's
30
+ pipeline, `turn_end`). A concurrent secondary still shares the read guard
31
+ and the turn-end worklist (the open half of #3613). State `turn_end` parks
32
+ in a scope cell for a later turn lives on the activation's own scope
33
+ (`TurnEndDeps.sessionScope`, passed by `index.ts`), never on
34
+ `runtime.sessionScope`, which is the primary's during a secondary's turn
35
+ (#4154: the late dead-code scan). A turn-end drain or write-back is fenced
36
+ by the scope that owns the store, taken at entry (#4161, #4168 round 3):
37
+ the coordinator's for the coordinator and module stores a secondary
38
+ shares, the activation's for its own scope cell. One store never answers
39
+ to two scopes, and a secondary's end fences only its cell.
40
+ - Every session-scope hand-off decision leaves one `latency.log` row per
41
+ lifecycle event, never one per occurrence in a loop (#3873):
42
+ `session_handoff_slot`, `session_handoff_adopt`, `session_store_action`
43
+ (a store's `restore` returns its `StoreCarry`, items in and kept),
44
+ `session_scope_transition` (`end`, `demote`) and `session_end_fence_rollup`.
45
+ `docs/pi-lens-monitor.md` lists the fields; a new session store or hand-off
46
+ branch adds its row there in the same change.
47
+ - Logger writes use `createNdjsonLogger`; flush before reading a log. Redact at
48
+ the sink. New failure records preserve the discriminating file/tool/record
49
+ identity and retain dropped counts.
50
+ - `memory_sample` remains one bounded latency record. Its heap, external,
51
+ worker-isolate, tree-sitter, and word-index fields are latest-value or O(1)
52
+ reads; sampler assembly time is recorded in `samplerDurationMs`.
53
+ - Delivery surfaces are registered in `clients/finding-delivery-gate.ts`.
54
+ Every model-facing diagnostic, blocker, advisory, widget, nudge, and snapshot
55
+ either passes the shared freshness/disposition gate or carries an explicit
56
+ bounded age label.
57
+ - The dispatcher coverage notice (`buildCoverageNotice`) latches once per
58
+ session (`coverageNoticeSeen`) for the pi push surface; pull surfaces
59
+ (`pilens_analyze`, including its warm PostToolUse hook route) pass
60
+ `dedupeCoverageNotice: false` so every call carries the notice and the push
61
+ latch stays untouched (#3791). The warm hook deliberately repeats the notice
62
+ on every edit, matching its cold hook route. A primary off in
63
+ `lsp.disabledServers` gets one "disabled in config" note per server per
64
+ session instead of the per-file notice.
65
+ - `pilens:files:touched` publishers are `clients/pipeline.ts` and
66
+ `clients/runtime-agent-end.ts`; `clients/agent-nudge.ts` is the subscriber.
67
+ `clients/lsp-mutation.ts` has an optional callback but is not a publisher until
68
+ it is wired. Update `tests/config/files-touched-bus-conformance.test.ts` for
69
+ any publisher or subscriber change.
70
+ - Deferred work has a bounded queue, wall budget, abort path, carry-forward
71
+ identity, and honest partial/deferred delivery. It never publishes a false
72
+ clean result after cutting work.
73
+
74
+ </important>
@@ -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":{"typescript":{"pendingFirstPublish":"direct","runs":1}}}
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
  ```