pi-lens 4.2.1 → 4.4.0

package/docs/language-coverage.md

@@ -50,6 +50,8 @@ Dispatch is diagnostics-oriented: automatic formatting and safe autofix happen i
 | CMake                 | ✓ (cmake-language-server) | lsp                                                                                      | cmake-format            |
 | CUE                   | ✓ (syntax via cue lsp, evaluation via cue vet) | lsp, cue-vet                                                              | cue fmt                 |
 
+### CUE tree-sitter grammar
+
 `cue lsp` reports load and parse errors as you type but leaves conflicting
 values and failed constraints to `cue vet` — the `cue-vet` auxiliary runner
 (#1522) covers that gap, so together they give full coverage: syntax/parse
@@ -79,6 +81,21 @@ Both are upstream grammar limitations (tracked among
 [eonpatapon/tree-sitter-cue](https://github.com/eonpatapon/tree-sitter-cue)'s
 open issues), not something a query change here can fix.
 
+## Non-core grammars
+
+The `tree-sitter` runner and `symbol_search`/`module_report` structural
+extraction ship a fixed set of core grammars; grammars for the other
+languages in the table above (CUE included) are fetched lazily on first use
+into web-tree-sitter's resolved package directory, verified against
+`scripts/grammars.lock.json`. This resolution works on a runtime that cannot
+resolve a bare package specifier — pi shipped as a `bun build --compile`
+binary — via one shared subpath-based ladder
+(`scripts/lib/web-tree-sitter-dir.mjs`, #3409); before that fix, non-core
+languages could never be analysed on those hosts. A grammar that never loads
+(fetch failure, unwritable target, an unsupported runtime) is recorded as a
+`grammar_unavailable` **skip**, never a clean pass
+(`clients/dispatch/runners/tree-sitter.ts`).
+
 ## Considered and skipped (2026-08-20 survey, closed out by #1757)
 
 Recorded so these are not re-litigated. The 2026-08-20 survey's first pass

package/docs/lsp-capability-matrix.md

@@ -9,7 +9,8 @@ confirmed against Neovim's LSP client, which sidesteps this entirely by being as
 
 Generate/refresh this matrix with `node scripts/characterize-lsp.mjs [--install]`
 (the `mode` column) and `node scripts/probe-clean-signal.mjs [--install]` (the
-`clean-behavior` column — 4-way: 2 / 2* / 3 / unknown). Both **merge** in place: a server the
+`clean-behavior` column — 4-way: 2 / 2* / 3 / unknown — and the `first-publish`
+column, #3310). Both **merge** in place: a server the
 running host couldn't spawn keeps its prior row, so an ubuntu-poor run can't
 regress a richer one (#390). The nightly **tool-smoke** workflow runs both (plus
 `server-capabilities.mjs`) and opens/updates a single auto-PR
@@ -27,13 +28,56 @@ anything). The native TS7 launch variant (`typescript7`/`typescript7-clean`,
 #524/#526) is deliberately excluded from comparison against classic's marker —
 they share a server id but not a verified clean-signal behavior.
 
+What IS gated is the pair of COMMITTED sources:
+`tests/config/lsp-clean-behavior-census.test.ts` (#3347) compares the
+`clean-behavior` column below against the `silentOnClean` markers in both
+directions — every measured push row against its marker, and every marker
+against a push row measured `silent` — so a nightly refresh cannot merge a
+re-measured server until its marker moves with it, and a marker cannot outlive
+the measurement that justified it. Push rows the probe has not classified are
+admitted by name in that file, and an admission reds once its row becomes
+measured.
+
+## First publish: is the first push an answer? (#3310)
+
+A second, ORTHOGONAL axis to the tiers below, measured from the same probe run
+and written as the `first-publish` column:
+
+| value | meaning | wait policy |
+|---|---|---|
+| `direct` | the first publish for a dirty file carries the findings | the first publish resolves the wait, as it always did |
+| `empty-first` | the server answers `didOpen` with an EMPTY set while a one-time index builds, then publishes again once indexing ends | the client HOLDS that first empty publish (`emptyFirstPublish: "indexing"` in `clients/lsp/wait-policy/strategies.ts`); the server's own next publish releases it, and the hold is one-shot per client session |
+| `empty-only` | every publish on the dirty fixture was empty | not classifiable on this axis — an undiagnosed dirty fixture looks exactly like an unfinished index, so nothing is inferred in either direction |
+| `n/a (pull)` / `TBD` | pull-mode, or not measured on a host that could reach the server | no behavior change |
+
+Why this axis had to exist at all: the wait needs a positive signal, and an
+empty publish is a positive signal for a Tier 2/2\* server (a genuinely clean
+file) and a MEANINGLESS one for a server that has not finished indexing. The two
+are identical on the wire, so the difference is a measurement, not an inference.
+intelephense is the measured member (2026-09-23, v1.18.5): `[]` at +295ms,
+`indexingStarted` at +301ms — i.e. AFTER the empty publish, so no
+work-in-progress signal is available at the moment the decision must be made —
+`indexingEnded` at +689ms and the real 2-diagnostic set at +696ms. On a
+genuinely clean file the same session publishes `[]` twice (at +304ms and again
+at +663ms, right after indexing), which is what lets the held publish be
+released by the server itself rather than by a timer; a WARM touch publishes the
+real set first, so the hold costs nothing once the session is warm. pi-lens does
+not advertise `window.workDoneProgress` (#974: advertising it crash-loops
+opengrep's `--experimental` LSP mode), so `$/progress` is not an available
+discriminator either.
+
+`tests/config/lsp-first-publish-census.test.ts` compares this column against the
+`emptyFirstPublish` markers and reds in BOTH directions, which is the expiry
+check: when the nightly re-measures a server into a different class, the docs
+refresh cannot merge until the marker is updated with it.
+
 ## The strategies
 
 | Tier | Signal | Affirmative clean? | Example |
 |---|---|---|---|
 | **1 — pull** | `textDocument/diagnostic` returns an authoritative report (empty = clean) | YES, deterministic | rust-analyzer |
 | **2 — push, publishes-versioned** | `publishDiagnostics([])` **with version** on every scan, incl. clean→clean | YES, currency-proven via version | ast-grep |
-| **2\* — push, publishes-unversioned** | re-publishes on a clean scan but **version-less** — the wait still early-returns (the client accepts a version-less publish as fresh: it can't be proven stale), but currency is only *temporally correlated*, not proven | YES at runtime, with a staleness-risk caveat (not a latency cost) | opengrep |
+| **2\* — push, publishes-unversioned** | re-publishes on a clean scan but **version-less** — the wait still early-returns (the client accepts a version-less publish as fresh: it can't be proven stale), but currency is only *temporally correlated*, not proven. Since #3484 the client fences a server measured to answer a `documentSymbol` fence before it publishes (`diagnosticsFence: "reply-first"`: yaml, intelephense): a pre-edit publish is dropped until the fence's reply. Every other 2\* server (docker publishes before answering; prisma, taplo, zls, dart, gleam, clojure unmarked) keeps this behaviour | YES at runtime, with a staleness-risk caveat (not a latency cost) | opengrep |
 | **3 — push, silent on clean** | server publishes nothing when nothing changed | **NO** — budget-wait floor (safe; a timeout is *not* a false clean). **This tier is #458's learned-deadline target set.** | typescript-language-server |
 | **Navigation-only — custom, no evidence** | custom `lsp.servers.*` entry has no pull provider and has not published in this session | **NO** — diagnostics are unsupported; skip the wait and report navigation-only | Dexter |
 
@@ -48,7 +92,7 @@ the next touch probes again. Only silence through the full push budget latches
 that server id as navigation-only for the service session. A publish upgrades it
 to the ordinary push-wait policy.
 
-## Matrix (dev box + CI nightly; mode last refreshed 2026-06-17 from run 27713958681, clean-behavior probed on the dev box 2026-07-08 — #460)
+## Matrix (dev box + CI nightly; mode last refreshed 2026-06-17 from run 27713958681, clean-behavior probed in run 35914033696 — #460)
 
 `mode` from cached capabilities; `clean-behavior` from the phase-aware publish-trace
 probe. The probe attributes publishes to two phases — the **dirty touch** (proves the
@@ -63,37 +107,71 @@ nightly steps, **dev** = the dev box (a row measured on both reads `dev+ci`).
 Merges never blank a prior good value, so a CI non-result leaves the dev
 classification standing.
 
-| lang | server | mode | clean-behavior | tier | src |
-|---|---|---|---|---|---|
-| json | vscode-json-language-server | pull | — | 1 | dev+ci |
-| css | vscode-css-language-server | pull | — | 1 | dev+ci |
-| html | vscode-html-language-server | pull | — | 1 | dev+ci |
-| rust | rust-analyzer | pull | — | 1 | dev |
-| svelte | svelte-language-server | pull | — | 1 | dev+ci |
-| deno | deno (alt of typescript) | pull | — | 1 | dev+ci |
-| ruby | ruby-lsp | pull | — | 1 | ci |
-| csharp | csharp-ls | pull | — | 1 | ci |
-| typescript | typescript-language-server | push-only | silent | 3 | dev+ci |
-| python | pyright | push-only | publishes-versioned | 2 | dev+ci |
-| jedi | jedi-language-server (alt of python) | push-only | publishes-versioned | 2 | ci |
-| yaml | yaml-language-server | push-only | publishes-unversioned | 2* | dev+ci |
-| shell | bash-language-server | push-only | publishes-versioned | 2 | dev+ci |
-| dockerfile | docker-langserver | push-only | publishes-unversioned | 2* | dev+ci |
-| toml | taplo | push-only | publishes-unversioned | 2* | dev+ci |
-| terraform | terraform-ls | push-only | TBD | 2/3? | dev+ci |
-| prisma | @prisma/language-server | push-only | publishes-unversioned | 2* | dev+ci |
-| php | intelephense | push-only | TBD | 2/3? | dev+ci |
-| zig | zls | push-only | publishes-unversioned | 2* | dev+ci |
-| vue | @vue/language-server | push-only | TBD | 2/3? | dev+ci |
-| dart | dart language-server | push-only | publishes-unversioned | 2* | ci |
-| gleam | gleam lsp | push-only | publishes-unversioned | 2* | ci |
-| clojure | clojure-lsp | push-only | publishes-unversioned | 2* | ci |
-| opengrep | opengrep (aux) | push-only | publishes-unversioned | 2* | dev+ci |
-| ast-grep | ast-grep (aux) | push-only | publishes-versioned | 2 | dev+ci |
+Two bounded guards keep that preservation from hiding a dead instrument
+(#3401). A `direct` `first-publish` cell whose axis the nightly probe does not
+re-observe is stamped once with the date of its first miss and degrades to
+`unknown` once five calendar days have elapsed since it (skipped nights do not
+stall it, and a re-observation clears the stamp). `empty-first` cells are never
+expired: they back the live `emptyFirstPublish` markers (php, terraform) and
+expiring one would erase the measurement behind a marker. A `clean-behavior`/
+`tier` change is written only after two consecutive nightly runs observe the
+same new value, so one flapping nightly (ast-grep went 2 → 2* → 3 → 2* across
+four runs) cannot rewrite a cell; a night that measured nothing for the lang
+resets the hold. A subset probe (`probe-clean-signal.mjs <langs>`) leaves the
+bookkeeping of the langs it did not probe untouched.
+
+The bookkeeping lives in the generated `## Capability matrix refresh state`
+section at the end of this doc, the only state the refresh persists. The clock
+is the nightly run, not the bot PR's merge: each nightly starts from the last
+`bot/lsp-docs-refresh` doc when that branch is ahead of master and was built on
+master's current doc (`scripts/seed-matrix-from-bot-branch.mjs`), and from
+master's doc otherwise (branch absent, squash-merged, or master edited the doc
+since). Closing the bot PR unmerged does not reset the bookkeeping: the branch
+is kept and keeps seeding, so only deleting `bot/lsp-docs-refresh` resets it.
+
+`vue`'s `clean-behavior` was hand-reset to `unknown` (#3390): its
+`publishes-unversioned` cell came from 58/45 publishes that the shared
+`extension.log` window had attributed to vue but that belonged to `tinymist`.
+With the sink scoped per server, nightly 36046209160 measured vue 0/0, and an
+`unknown` result is never written by the merge above — so the refuted value had
+to be cleared by hand. It stays `unknown` until a run observes
+`@vue/language-server` publish; `tests/config/lsp-clean-behavior-census.test.ts`
+carries the named admission until then.
+
+| lang | server | mode | clean-behavior | first-publish | tier | src |
+|---|---|---|---|---|---|---|
+| json | vscode-json-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| css | vscode-css-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| html | vscode-html-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| rust | rust-analyzer | pull | — | n/a (pull) | 1 | dev+ci |
+| svelte | svelte-language-server | pull | — | n/a (pull) | 1 | dev+ci |
+| deno | deno (alt of typescript) | pull | — | n/a (pull) | 1 | dev+ci |
+| ruby | ruby-lsp | pull | — | n/a (pull) | 1 | ci |
+| csharp | csharp-ls | pull | — | n/a (pull) | 1 | ci |
+| typescript | typescript-language-server | push-only | silent | direct | 3 | dev+ci |
+| markdown | marksman | push-only | silent | direct | 3 | ci |
+| lua | lua-language-server | push-only | silent | direct | 3 | dev+ci |
+| python | pyright | push-only | publishes-versioned | direct | 2 | dev+ci |
+| jedi | jedi-language-server (alt of python) | push-only | publishes-versioned | direct | 2 | ci |
+| yaml | yaml-language-server | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| shell | bash-language-server | push-only | publishes-versioned | direct | 2 | dev+ci |
+| dockerfile | docker-langserver | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| toml | taplo | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| terraform | terraform-ls | push-only | publishes-unversioned | empty-first | 2* | dev+ci |
+| prisma | @prisma/language-server | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| php | intelephense | push-only | publishes-unversioned | empty-first | 2* | dev+ci |
+| zig | zls | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| vue | @vue/language-server | push-only | unknown | unknown | 2/3? | dev+ci |
+| dart | dart language-server | push-only | publishes-unversioned | direct | 2* | ci |
+| gleam | gleam lsp | push-only | publishes-unversioned | direct | 2* | ci |
+| clojure | clojure-lsp | push-only | publishes-unversioned | direct | 2* | ci |
+| opengrep | opengrep (aux) | push-only | publishes-unversioned | direct | 2* | dev+ci |
+| ast-grep | ast-grep (aux) | push-only | publishes-versioned | direct | 2 | dev+ci |
+| cue | CUE Language Server (cue lsp serve) | push-only | publishes-versioned | direct | 2 | dev+ci |
 
 **Unknown — fixture exists, mode not yet captured.** The toolchain-gated family
 (no auto-install today; tracked in #241) — `go` (gopls), `java` (jdtls),
-`kotlin`, `swift` (sourcekit-lsp), `lua`, `cpp` (clangd), `haskell`, `elixir`,
+`kotlin`, `swift` (sourcekit-lsp), `cpp` (clangd), `haskell`, `elixir`,
 `ocaml`, `nix` (nixd), `fsharp`. Their servers don't install in the nightly, so
 characterize reports `unknown` (a non-failure ⚠). Once #241 lands they'll fill in
 the same way clojure-lsp/gleam now do (both auto-install via the github strategy
@@ -103,7 +181,8 @@ and were characterized `push-only` in the run above).
 - **Mode ≠ tier, and the split needs BOTH axes.** Push-only further splits along
   latency (does anything publish on a clean transition? — silence is the only
   budget-wait case, because pi-lens's publish handler emits and early-returns the
-  wait on EVERY publish, versioned or not) and currency-proof (is the publish
+  wait on every publish, versioned or not, with the single #3310 exception of a
+  held empty FIRST publish from an `empty-first` server) and currency-proof (is the publish
   versioned, i.e. provably about the live edit?). The 4-way
   `probe-clean-signal.mjs` measurement drives this: ast-grep → 2, yaml/opengrep →
   2\*, typescript (clean file) → 3.
@@ -121,6 +200,16 @@ and were characterized `push-only` in the run above).
   fixtures for exactly this reason. Corollary: a 2\* measured only on a dirty
   fixture may overstate a server whose publishes stop when its set goes empty —
   langs without a clean fixture carry that caveat.
+- **The probe's publish capture was dead, and the column looked alive anyway
+  (#3310).** `probe-clean-signal.mjs` intercepted `console.error` for the
+  `[lsp-pub]` trace, but #1333 moved that trace's sink to `extension.log` — so
+  every phase counted zero publishes, every server classified `unknown`, and the
+  #390 merge guard then preserved the July 2026 values verbatim. A dead
+  instrument and a healthy one are indistinguishable when non-results are
+  discarded by design. The probe now reads the sink the client actually writes;
+  `first-publish` measurements on the dev box, 2026-09-23: php `empty-first`,
+  typescript / opengrep / ast-grep / marksman `direct` (so the class does not
+  extend to them on the measurement, whatever their comments suggest).
 - **#458's learned-deadline target set = the tier-3 rows only.** 2\* rows resolve
   the wait at runtime and must NOT be given learned deadlines.
 - **Tier 3 is budget-bound by necessity**, not laziness: a silent server's silence is
@@ -163,3 +252,13 @@ marker; a mismatch means the marker may need a human update (#529). `unknown`
 observations are never compared (a slow/absent server is not evidence either way).
 
 _None observed as of the last probe run._
+
+## Capability matrix refresh state (nightly-generated)
+
+Bookkeeping for the date-based `direct` `first-publish` expiry (#3401), the
+two-run `clean-behavior` hysteresis and the consecutive-night `idle-eviction`
+counts (#3989). Regenerated every run; never a measurement.
+
+```json
+{"idle-eviction":{"docker":{"nights":[{"day":"2026-10-07","rssMb":64,"coldMs":566}]},"json":{"nights":[{"day":"2026-10-07","rssMb":67,"coldMs":1116}]},"powershell":{"nights":[{"day":"2026-10-07","rssMb":155,"coldMs":2601}]},"python-jedi":{"nights":[{"day":"2026-10-07","rssMb":51,"coldMs":1796}]},"zizmor":{"nights":[{"day":"2026-10-07","rssMb":58,"coldMs":608}]}}}
+```

package/docs/lsp-idle-eviction.md

@@ -0,0 +1,124 @@
+# LSP idle-eviction measurement
+
+Per-server cost and safety of releasing an idle language-server client, measured
+by the nightly so each server's `idleEviction` declaration in
+`clients/lsp/server.ts` can be made from evidence (#3645). Generated by
+`node scripts/measure-lsp-idle-eviction.mjs [--install]` (requires
+`npm run build:dist`); it changes no server's policy.
+
+For each registry server the probe spawns the server on its smoke fixture,
+records the first diagnostics, then makes the server evictable in the probe
+process only and lets the real idle-eviction timer release it. The next request
+respawns it through the ordinary path. A server is `eligible` only when the
+respawned server reports every finding it reported before eviction; the
+`coverage` column is that comparison, and for an auxiliary scanner it is the
+content-bound coverage check the auxiliary freeze depends on. A server that
+cannot demonstrate it is never proposed for eviction on perf grounds alone.
+
+_Last generated: 2026-10-07 on linux; 48 registry servers: 32 eligible, 0 vetoed, 2 inconclusive, 14 unavailable (0 not reached: budget)._
+
+## Per-server rows
+
+Only stable columns are committed, so the nightly refresh changes this file
+only when a server's outcome changes. The measured init duration, resident
+memory of the server's process tree and post-eviction cold start are in the
+nightly run's step log and job summary, one row per server. `n/a` means not
+measured, never zero: **respawn** is whether the next request after eviction
+brought the server back, **coverage** is whether the respawned server kept
+every baseline finding.
+
+A server that reports extra findings after the respawn (`widened`) still reads
+`preserved`, because nothing was lost, but a first scan that grows on respawn
+is a sign the baseline was partial. Any policy flip needs `preserved` on
+several nights, not one; a `widened` disclosure is per run and is shown in the
+step log only, because it flaps.
+
+| server | role | declared | result | reason | respawn | coverage |
+|---|---|---|---|---|---|---|
+| ast-grep | auxiliary | unmeasured | eligible | · | ok | preserved |
+| bash | primary | transparent | eligible | · | ok | preserved |
+| clojure | primary | transparent | eligible | · | ok | preserved |
+| cmake | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
+| cpp | primary | transparent | eligible | · | ok | preserved |
+| csharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| css | primary | transparent | eligible | · | ok | preserved |
+| cue | primary | unmeasured | eligible | · | ok | preserved |
+| dart | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| deno | primary | transparent | eligible | · | ok | preserved |
+| docker | primary | unmeasured | eligible | · | ok | preserved |
+| docker-official | primary | unmeasured | unavailable | no-fixture | n/a | n/a |
+| elixir | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| expert | primary | unmeasured | eligible | · | ok | preserved |
+| fish | primary | transparent | eligible | · | ok | preserved |
+| fsharp | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| gleam | primary | unmeasured | eligible | · | ok | preserved |
+| go | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| haskell | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| html | primary | transparent | eligible | · | ok | preserved |
+| java | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| json | primary | unmeasured | eligible | · | ok | preserved |
+| kotlin | primary | unmeasured | eligible | · | ok | preserved |
+| lua | primary | unmeasured | eligible | · | ok | preserved |
+| marksman | primary | transparent | eligible | · | ok | preserved |
+| nix | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| ocaml | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| omnisharp | primary | unmeasured | unavailable | no-fixture | n/a | n/a |
+| opengrep | auxiliary | transparent | eligible | · | ok | preserved |
+| php | primary | transparent | eligible | · | ok | preserved |
+| powershell | primary | unmeasured | eligible | · | ok | preserved |
+| prisma | primary | transparent | eligible | · | ok | preserved |
+| python | primary | transparent | eligible | · | ok | preserved |
+| python-jedi | primary | unmeasured | eligible | · | ok | preserved |
+| ruby | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| rust | primary | unmeasured | eligible | · | ok | preserved |
+| shuck | primary | unmeasured | unavailable | server-not-started | n/a | n/a |
+| svelte | primary | unmeasured | eligible | · | ok | preserved |
+| swift | primary | unmeasured | unavailable | tool-unavailable | n/a | n/a |
+| terraform | primary | unmeasured | eligible | · | ok | preserved |
+| tinymist | primary | unmeasured | eligible | · | ok | preserved |
+| toml | primary | unmeasured | eligible | · | ok | preserved |
+| typescript | primary | transparent | eligible | · | ok | preserved |
+| typos | auxiliary | unmeasured | eligible | · | ok | preserved |
+| vue | primary | unmeasured | inconclusive | no-baseline | n/a | unproven |
+| yaml | primary | transparent | eligible | · | ok | preserved |
+| zig | primary | unmeasured | eligible | · | ok | preserved |
+| zizmor | auxiliary | unmeasured | eligible | · | ok | preserved |
+
+## Declared versus measured
+
+`drift` means the registry evicts a server the measurement vetoes. A `proposal`
+or `info` line is for a maintainer to act on in a follow-up; this run changed
+nothing.
+
+- **ast-grep** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **cue** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **docker** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **expert** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **gleam** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **json** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **kotlin** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **lua** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **powershell** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **python-jedi** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **rust** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **svelte** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **terraform** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **tinymist** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **toml** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **typos** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **zig** [proposal] declared unmeasured but eviction and respawn preserved its findings
+- **zizmor** [proposal] declared unmeasured but eviction and respawn preserved its findings
+
+## Reasons
+
+- `no-fixture`: No smoke fixture routes to this server, so there is nothing to spawn.
+- `tool-unavailable`: A tool this server's fixture needs could not be installed or found on the generating host.
+- `setup-failed`: The fixture's workspace setup step failed.
+- `server-not-started`: The fixture ran but this server never became a live client.
+- `budget-exhausted`: The run's wall-clock budget ended before this server was reached.
+- `probe-error`: The probe itself threw before it had a baseline.
+- `no-baseline`: The server produced no finding on the fixture, so nothing can show its coverage survives eviction.
+- `not-evicted`: The idle-eviction timer did not release the client within the bound.
+- `client-died`: The client went away without an idle-eviction record, so the release was a crash, not the eviction path.
+- `respawn-failed`: After eviction the next request could not bring the server back.
+- `findings-narrowed`: After the respawn the server reported fewer findings than before eviction.

package/docs/mcp.md

@@ -112,7 +112,7 @@ New files:
 
 | tool | maps to | purpose |
 |------|---------|---------|
-| `pilens_analyze` | `analyzeFile` (warm) / worker (fresh) | run the per-edit pipeline on a file; returns diagnostics + timing. `mode: warm\|fresh`. **Correctness + mechanism probe.** |
+| `pilens_analyze` | `analyzeFile` (warm) / worker (fresh) | run the per-edit pipeline on a file; returns diagnostics + timing. `mode: warm\|fresh`. **Correctness + mechanism probe.** Each `latency.runners[]` row carries `failureKind` when the runner set one: `failed` + `blocking_diagnostics` is a run whose findings failed the check; `failed` with any other kind, or none, is a runner that produced no usable result. |
 | `pilens_ast_grep_search` | `ast_grep_search` | AST-aware structural search. |
 | `pilens_ast_grep_replace` | `ast_grep_replace` | AST-aware structural replace. |
 | `pilens_diagnostics` | `lens_diagnostics` | session or LSP diagnostics, selected by `source`, `scope`, and `severity`. |
@@ -131,6 +131,17 @@ New files:
 | `pilens_symbol_search` | `symbol_search` | search the persisted symbol index. |
 | `pilens_turn_end` | turn lifecycle | settle turn-end work and return findings. |
 
+Every tool's `inputSchema` (from `tools/list`) is also the set of argument keys
+the dispatcher accepts without comment: an undeclared key is reported in the
+result (a leading `Ignored unknown argument(s) ...` line, plus
+`structuredContent.ignoredArguments`). An ignored key that leaves a required
+input missing, or that is a declared parameter the call did not send written
+another way (`pilens_diagnostics {"filePath": ...}` for `path`; predicate in
+[public-api-stability.md](public-api-stability.md)), turns the call into an error
+instead of a run on defaults; a looser "did you mean" stays a warning (#3749;
+details in [agent-tools.md](agent-tools.md)). The check is the one seam in
+`mcp/server.ts` `tools/call`, through `mcp/tool-arguments.ts`.
+
 ## Packaging / wiring
 
 - `package.json`: add `"bin": { "pi-lens-mcp": "./dist/mcp/server.js" }`; add
@@ -383,9 +394,14 @@ be exercised + debugged directly through Claude Code without running pi.
   hook (reads the tool payload from stdin → `tool_input.path`/`file_path` + cwd)
   AND as a plain CLI (`--file=`). Defaults to `no-lsp` (FAST: ~1-2s, the cold
   LSP would cost ~5s/edit and under-report anyway — pull `pilens_analyze` on the
-  warm server for type errors). Silent on clean files; advisory (always exit 0).
-  `--hook` emits a PostToolUse `additionalContext` envelope; plain mode prints a
-  report. 4 bin tests (CLI, --hook envelope, clean-file silence, stdin payload).
+  warm server for type errors). Silent on clean files. Clean scans and findings
+  exit 0; an invocation that cannot run reports its failure on stdout and stderr.
+  Plain CLI failures exit 2. `--hook`, stdin hook payloads, and `--turn-end` stay
+  advisory and exit 0, including on failure. `--hook` emits a PostToolUse
+  `additionalContext` envelope; plain mode and Stop hooks print text.
+  `pilens_health` reports failed invocation counts and the last operation,
+  timestamp, and bounded, redacted reason from the workspace status record.
+  These counters are best-effort history, not a current readiness verdict.
 
   Wire it in Claude Code `settings.json`:
 
@@ -443,7 +459,7 @@ be exercised + debugged directly through Claude Code without running pi.
   in the server, and concurrent turn-ends cannot race the turn-state clear.
   **Warm-only, no cold fallback**: only the server process owns the session state
   and pending turn work, so a local pass would report a false clean — no warm
-  server means one stderr line, silent stdout, exit 0.
+  server means a skip reason on stdout and stderr, exit 0.
   The client waits 55s so it gives up inside Claude Code's 60s hook timeout.
   `SubagentStop` is deliberately NOT registered: subagent edits already fire
   PostToolUse into the shared turn-state, the consume bridges are one-shot (a

package/docs/merge-queue-rollout.md

@@ -0,0 +1,77 @@
+# Merge queue rollout
+
+Adopting GitHub's merge queue for `master` (#3754). The repository side is in
+the same change as this page; the settings below are the maintainer's step and
+are deliberately not applied by any script or workflow.
+
+## Why
+
+Every master move forced `gh pr update-branch` and a full CI re-run on every
+open PR. A queue tests each PR merged onto the latest master, in order, so
+neither is needed. Sharded Unit tests (#3753) keep one queue run short.
+
+## Repository side (already in this change)
+
+- `ci.yml` and `lint.yml` run on `merge_group` (`types: [checks_requested]`).
+  Together they produce every required check: `Lint & type-check`,
+  `Unit tests`, `Install test (ubuntu-latest)`, `Install test (windows-latest)`,
+  `Install test (macos-latest)`, `knip`, `oxfmt format check`, `TLA+ models`.
+- PR-only jobs (PR title, PR body, changelog fast-fail, targeted advisory) are
+  guarded by `github.event_name == 'pull_request'` and are skipped on
+  `merge_group`; none of them is required.
+- `tests/config/merge-queue-workflows.test.ts` pins the trigger, the required
+  job names, and that no required job (or a job it `needs:`) is gated off on
+  `merge_group`.
+- `scripts/ci-verdict.mjs` reports a queued PR as kind `in-queue` (exit 3) and
+  a failed queue run as a FAIL event.
+
+## Maintainer settings (Settings, Rules, Rulesets, New branch ruleset)
+
+| Setting | Value | Why |
+| --- | --- | --- |
+| Ruleset name | `master merge queue` | |
+| Enforcement status | Active | |
+| Target branches | Include default branch (`master`) | |
+| Require status checks to pass | the eight names above, source GitHub Actions | unchanged from branch protection today |
+| Require branches to be up to date | off | the queue replaces it |
+| Require merge queue | on | |
+| Merge method | Merge commit | repo convention (`gh pr merge --merge`) |
+| Build concurrency (maximum pull requests to build) | 3 | queue builds run three required-check sets at once on hosted runners |
+| Minimum pull requests to merge | 1 | never hold a green PR waiting for company |
+| Maximum pull requests to merge | 3 | a failing group costs at most three re-tests |
+| Wait time to meet minimum group size | 1 minute | |
+| Only merge non-failing pull requests | All commits must pass (`ALLGREEN`) | a red group member ejects only itself |
+| Status check timeout | 30 minutes | the required set took about 10 minutes at the median and about 12 at the maximum over 30 runs before sharding; 30 minutes is 2.5x that |
+
+Branch protection on `master` today is classic (no ruleset exists).
+`scripts/ci-verdict.mjs` reads the live required-check names from classic
+branch protection; if you move the required checks into the ruleset it falls
+back to the static list (`Unit tests`, `Lint & type-check`) and still gates on
+every non-advisory check-run from a PR/push run it discovers. Either keep the classic rule
+(enable "Require merge queue" there) or accept the narrower absent-check
+detection.
+
+## Rollout steps
+
+1. Merge #3753 (sharded Unit tests) first, then this change.
+2. Create the ruleset above.
+3. Enqueue one low-risk PR: `gh pr merge <N> --merge`.
+4. Confirm in `gh run list --event merge_group` that `CI` and `Lint` ran on the
+   `gh-readonly-queue/master/pr-<N>-<sha>` ref and that all seven required
+   checks reported there. A required check that never reports stalls the queue
+   until the 30-minute timeout.
+5. Stop using `gh pr update-branch` and "re-arm" pushes; both are moot and a
+   push to a queued PR ejects it.
+
+## Rollback
+
+Disable the ruleset's "Require merge queue" rule. PRs merge directly again;
+nothing in the repository needs reverting, because `merge_group` triggers and
+the ci-verdict queue reads are inert without a queue.
+
+## Known remainder
+
+The `train:approved` lane that merged through the REST merge API was retired
+(#3837), so no competing lane holds a merge the queue would refuse. Every
+merge goes through `gh pr merge` (auto-merge or direct), which the queue
+intercepts when the base branch requires one.