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.
- package/CHANGELOG.md +477 -0
- package/README.md +45 -3
- package/config/biome/core.jsonc +3 -3
- package/config/dependency-cruiser-eager-allowlist.json +1 -0
- package/dist/{chunk-UBOQLVT2.js → chunk-2DDDCJDL.js} +4 -4
- package/dist/{chunk-RKKOYPRA.js → chunk-2DMLM3ZO.js} +13 -15
- package/dist/chunk-2F47TQOA.js +73 -0
- package/dist/{chunk-O4NWQT6I.js → chunk-2PHMIAKO.js} +4 -4
- package/dist/{chunk-DGUKIYSI.js → chunk-2RLWJO5K.js} +8 -10
- package/dist/{chunk-S67KYG37.js → chunk-2X4VLOCC.js} +2 -2
- package/dist/{chunk-TIQ2PKDW.js → chunk-3MYEA7QD.js} +4 -4
- package/dist/{chunk-3DA2JDOL.js → chunk-3WEPUD2V.js} +551 -203
- package/dist/{chunk-AMERCH6V.js → chunk-4AVZ3TG7.js} +15 -16
- package/dist/{chunk-IYNJ6YPZ.js → chunk-4PCQCU47.js} +4 -4
- package/dist/chunk-4WX4CTUE.js +57 -0
- package/dist/{chunk-P63GXC37.js → chunk-5APMQ2IJ.js} +31 -4
- package/dist/{chunk-ZIVJBOO3.js → chunk-5CV5ITZF.js} +2 -2
- package/dist/{chunk-6DLWKFEX.js → chunk-5ZR3APIM.js} +41 -42
- package/dist/{chunk-XTBDCR27.js → chunk-63RIVFQI.js} +4 -4
- package/dist/{chunk-GSLNCYGG.js → chunk-75SY4F24.js} +13 -14
- package/dist/{chunk-U44DJXQP.js → chunk-7RQXA5GG.js} +15 -18
- package/dist/chunk-A3YNG5KP.js +45 -0
- package/dist/{chunk-5OFV52AM.js → chunk-AE37FEGH.js} +1 -1
- package/dist/{chunk-BWD5EPKO.js → chunk-AMXIUN2R.js} +4 -6
- package/dist/{chunk-3KAZU3VR.js → chunk-ARD426WI.js} +2 -2
- package/dist/{chunk-BW5KFIQC.js → chunk-AWQWXSW4.js} +1 -0
- package/dist/{chunk-YH5MVY2U.js → chunk-BHUWL2Y3.js} +7 -7
- package/dist/{chunk-CT4MN5IU.js → chunk-BI5LAQ3Y.js} +353 -359
- package/dist/{chunk-KAPJINKN.js → chunk-BM5GS6ZH.js} +2 -2
- package/dist/{chunk-TLX72JTG.js → chunk-BWYQUPOS.js} +1 -1
- package/dist/chunk-CFRQMBGP.js +49 -0
- package/dist/{chunk-RMLC67LF.js → chunk-CJYKEW2L.js} +2 -30
- package/dist/chunk-CKEQFGLT.js +32 -0
- package/dist/{chunk-IWDLU6K3.js → chunk-DC4CFXM5.js} +4 -6
- package/dist/{chunk-ZVUL7QYY.js → chunk-DMSLNKF7.js} +29 -32
- package/dist/{chunk-KN35K52N.js → chunk-DQXSPYRI.js} +3 -3
- package/dist/{chunk-HYGZEMX6.js → chunk-EVDGNG4F.js} +11 -5
- package/dist/{chunk-SRYEJNES.js → chunk-F5Z6URKM.js} +2 -2
- package/dist/{chunk-UMS2MFPZ.js → chunk-F6X3YJWD.js} +2 -3
- package/dist/{chunk-XYURS6EN.js → chunk-FA5LDARD.js} +15 -17
- package/dist/{chunk-24AKHFGP.js → chunk-FFL3A2VP.js} +6 -6
- package/dist/chunk-FJIVKLPH.js +31 -0
- package/dist/chunk-G2B7F6ZU.js +88 -0
- package/dist/{chunk-US7ECLD7.js → chunk-GAACZY6R.js} +131 -41
- package/dist/{chunk-MZGQNL3Y.js → chunk-GMTFDAOK.js} +12 -13
- package/dist/{chunk-VOOAPROD.js → chunk-GNSIWBAT.js} +3 -3
- package/dist/chunk-GTAI2J6U.js +27 -0
- package/dist/{chunk-RVK72CZX.js → chunk-GZE7WOI4.js} +1362 -459
- package/dist/{chunk-IUE7SSKV.js → chunk-H7HTEQUZ.js} +13 -7
- package/dist/{chunk-EUXZEFTV.js → chunk-HK6JVFZC.js} +3 -3
- package/dist/chunk-IPDG45G5.js +26 -0
- package/dist/{chunk-5HSRT26B.js → chunk-J6JP25XU.js} +16 -15
- package/dist/{chunk-HWCCCQNX.js → chunk-JL6CXUMW.js} +13 -6
- package/dist/{chunk-EBC36LNN.js → chunk-K2YGBXOA.js} +17 -17
- package/dist/{chunk-WMYE35PX.js → chunk-KLQVC3XC.js} +7 -5
- package/dist/{chunk-ATKJFDQN.js → chunk-KSR7RGQY.js} +12 -14
- package/dist/{chunk-POMLXPMY.js → chunk-KXF5R4UN.js} +1 -1
- package/dist/{chunk-LLJNQKQW.js → chunk-LEJOJDXL.js} +20 -13
- package/dist/{chunk-JUKMK5Y4.js → chunk-MA77RSFN.js} +10 -11
- package/dist/{chunk-GAQ7OQG6.js → chunk-MKVZQUEG.js} +85 -96
- package/dist/{chunk-2EECBNC5.js → chunk-MN7MHUXQ.js} +75 -0
- package/dist/{chunk-DEL2U6CM.js → chunk-MT6BVNFW.js} +16 -14
- package/dist/chunk-NDMCVUYK.js +507 -0
- package/dist/{chunk-HRNHZA3N.js → chunk-NIU2IPC5.js} +12 -16
- package/dist/{chunk-AGSS7277.js → chunk-NNKXDXXS.js} +7 -24
- package/dist/{chunk-V35JG4JB.js → chunk-OJLTLYHB.js} +152 -334
- package/dist/{chunk-J6MPGQTS.js → chunk-OLAWH5UQ.js} +81 -15
- package/dist/{chunk-T57LYLZT.js → chunk-OOU2WZZE.js} +1 -1
- package/dist/{chunk-CYRKQRPM.js → chunk-OSTKYB55.js} +2 -4
- package/dist/chunk-P4QNXS6I.js +27 -0
- package/dist/chunk-PKES3ISE.js +297 -0
- package/dist/{chunk-ROYSX2S5.js → chunk-PO45POGF.js} +2 -2
- package/dist/{chunk-T7FEBKXN.js → chunk-PPIBVH4R.js} +7 -9
- package/dist/{chunk-3RKP3FMS.js → chunk-PQJFG24Z.js} +295 -23
- package/dist/{chunk-KUA4OJ5Y.js → chunk-Q3UZHW6N.js} +846 -350
- package/dist/{chunk-N5FLEO7W.js → chunk-Q4EMRFNA.js} +37 -37
- package/dist/{chunk-5IUSNGOC.js → chunk-Q4FCYCRE.js} +28 -21
- package/dist/chunk-Q6D6VMI4.js +22 -0
- package/dist/{chunk-UZ2XCLYS.js → chunk-QGSTQH4D.js} +8 -8
- package/dist/{chunk-DUO2TU77.js → chunk-RZOXUSPC.js} +10 -4
- package/dist/{chunk-JMYYOTQG.js → chunk-S26LC76R.js} +13 -1
- package/dist/{chunk-GMX5OS7B.js → chunk-S67UJDGQ.js} +11 -12
- package/dist/chunk-SCIUNBPF.js +44 -0
- package/dist/{chunk-RKBXZN3A.js → chunk-SJJYRZB4.js} +2 -2
- package/dist/chunk-SXGD4ANG.js +25 -0
- package/dist/{chunk-YCWYO6TQ.js → chunk-T7FTXGS3.js} +48 -45
- package/dist/{chunk-FM4RDMKT.js → chunk-TIQJPRDD.js} +115 -61
- package/dist/{chunk-XHJBS436.js → chunk-TIYGSODX.js} +25 -25
- package/dist/{chunk-S2HEXIWI.js → chunk-U2SDMG7C.js} +10 -6
- package/dist/{chunk-2KXTHF3M.js → chunk-U6OC3QEM.js} +253 -33
- package/dist/{chunk-AWSCPCN2.js → chunk-UCGQT677.js} +19 -19
- package/dist/chunk-UHGF5UT5.js +32 -0
- package/dist/{chunk-JW3YWBVB.js → chunk-UN4TEBWN.js} +17 -19
- package/dist/{chunk-ZHH37KZL.js → chunk-V3APN3DY.js} +17 -17
- package/dist/{chunk-ED36RF6Y.js → chunk-V63BC55Q.js} +1 -1
- package/dist/{chunk-XBJVAEEO.js → chunk-VG5JS5SW.js} +3 -2
- package/dist/{chunk-W66O5E25.js → chunk-VPBIMOAQ.js} +13 -15
- package/dist/chunk-VQH24FIP.js +37 -0
- package/dist/{chunk-YNE3RP52.js → chunk-VSFLRN5Y.js} +8 -1
- package/dist/{chunk-7D6L4MTX.js → chunk-W2V54OCL.js} +3 -3
- package/dist/{chunk-2FN63LPV.js → chunk-W5LGKNET.js} +13 -14
- package/dist/{chunk-IQWN5JCP.js → chunk-W5R5SABV.js} +13 -14
- package/dist/{chunk-R3T7CLQ2.js → chunk-WIZWZR4C.js} +41 -41
- package/dist/{chunk-TOY6QKOH.js → chunk-WQOIR3QY.js} +17 -17
- package/dist/{chunk-Y6GZHWSJ.js → chunk-XAIT2YGS.js} +6 -6
- package/dist/chunk-XCUHKYCQ.js +23 -0
- package/dist/{chunk-GSM5UU7A.js → chunk-XQCSWV2G.js} +44 -35
- package/dist/{chunk-OHKJ7PQF.js → chunk-YBSONGSZ.js} +43 -39
- package/dist/{chunk-GXFV6MYU.js → chunk-YISME6ON.js} +72 -39
- package/dist/chunk-YRD4ISED.js +30 -0
- package/dist/{chunk-SD4I7ZO4.js → chunk-YSBHPOY6.js} +43 -53
- package/dist/{chunk-QBFBRV2B.js → chunk-Z2XAOKHK.js} +4 -2
- package/dist/{chunk-5VSF4UUQ.js → chunk-Z7IGUAXL.js} +34 -39
- package/dist/{chunk-MPNJLASA.js → chunk-ZKXQKGWZ.js} +10 -13
- package/dist/{chunk-J64T55EI.js → chunk-ZQ6NZZTB.js} +75 -9
- package/dist/chunk-ZUUI3ZSA.js +38 -0
- package/dist/{chunk-7HXE67BN.js → chunk-ZYNI26MI.js} +2 -2
- package/dist/index.js +32674 -27567
- package/dist/mcp/analyze-cli.js +11 -12
- package/dist/mcp/cli.js +46 -45
- package/dist/mcp/server.js +1210 -574
- package/dist/mcp/worker.js +65 -65
- package/dist/probes/installer.js +21 -23
- package/docs/adr/0010-trace-validation-session-lifecycle.md +390 -0
- package/docs/adr/README.md +1 -0
- package/docs/agent-tools.md +28 -7
- package/docs/ast-grep_rules_catalog.md +5 -3
- package/docs/configuration.md +12 -1
- package/docs/defect-shapes.md +738 -0
- package/docs/engineering-principles.md +12 -0
- package/docs/environment-variables.md +20 -0
- package/docs/features.md +16 -1
- package/docs/globalconfig.md +37 -8
- package/docs/invariants/caches-stores.md +30 -0
- package/docs/invariants/dispatch-runners.md +164 -0
- package/docs/invariants/git-guard-host.md +53 -0
- package/docs/invariants/language-config.md +31 -0
- package/docs/invariants/lsp-trust-exec.md +286 -0
- package/docs/invariants/paths-os.md +59 -0
- package/docs/invariants/session-telemetry.md +74 -0
- package/docs/lsp-capability-matrix.md +105 -12
- package/docs/lsp-idle-eviction.md +37 -18
- package/docs/pi-lens-fixer.md +24 -2
- package/docs/pi-lens-investigator.md +14 -0
- package/docs/pi-lens-merge-policy.md +32 -17
- package/docs/pi-lens-monitor.md +66 -10
- package/docs/pi-lens-orchestration.md +41 -0
- package/docs/pi-lens-release.md +20 -0
- package/docs/pi-lens-retro.md +5 -4
- package/docs/pi-lens-reviewer.md +54 -7
- package/docs/pi-lens-subagent.md +10 -3
- package/docs/release-qa-baseline.md +19 -7
- package/docs/servercapabilities.md +47 -47
- package/docs/settings.md +9 -5
- package/docs/subagent-compat.md +1 -1
- package/docs/usage.md +1 -0
- package/package.json +8 -5
- package/rules/ast-grep-rules/rule-tests/no-return-value-in-generator-test.yml +17 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-js-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/no-sql-in-code-execute-test.yml +86 -0
- package/rules/ast-grep-rules/rule-tests/unchecked-numeric-parse-python-test.yml +15 -0
- package/rules/ast-grep-rules/rules/no-return-value-in-generator.yml +9 -4
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute-js.yml +119 -0
- package/rules/ast-grep-rules/rules/no-sql-in-code-execute.yml +119 -0
- package/rules/ast-grep-rules/rules/unchecked-numeric-parse-python.yml +13 -2
- package/rules/rule-catalog.json +25 -1
- package/scripts/analyze-pi-lens-logs.mjs +15 -5
- package/scripts/lib/is-main-module.mjs +27 -0
- package/scripts/lib/scratch-home-env.mjs +21 -0
- package/scripts/rpc-load-check.mjs +4 -6
- package/scripts/warm-loader-cache.mjs +2 -5
- package/dist/chunk-3PTHXJXR.js +0 -28
- package/dist/chunk-3QED2P4V.js +0 -31
- package/dist/chunk-5WRPDP2A.js +0 -47
- package/dist/chunk-ABBOA7UD.js +0 -157
- package/dist/chunk-CUHSHSB6.js +0 -273
- package/dist/chunk-GL5LUMZE.js +0 -51
- package/dist/chunk-HAD7QRQI.js +0 -30
- package/dist/chunk-JORED7EX.js +0 -44
- package/dist/chunk-KYUB6QDC.js +0 -72
- package/dist/chunk-LZSEQW6A.js +0 -57
- package/dist/chunk-M2IFVFWU.js +0 -79
- package/dist/chunk-M2UD3LPU.js +0 -88
- package/dist/chunk-MBKQHGA7.js +0 -39
- package/dist/chunk-R7YOCSNV.js +0 -23
- package/dist/chunk-SKAMFC7A.js +0 -28
- package/dist/chunk-SYE6T2EB.js +0 -28
- package/dist/chunk-TRETHTQO.js +0 -26
- package/dist/chunk-UA7ZXYDR.js +0 -184
- package/dist/chunk-XTFDJI3T.js +0 -24
- 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
|
|
135
|
-
expiring one would erase the measurement behind a marker.
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
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 |
|
|
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 |
|
|
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
|
|
205
|
-
|
|
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
|
-
|
|
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
|
-
{"
|
|
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
|
```
|