pi-lens 4.1.0 → 4.1.2

package/CHANGELOG.md

@@ -16,6 +16,191 @@ All notable changes to pi-lens will be documented in this file.
 
 ### Security
 
+## [4.1.2] - 2026-08-24
+
+### Added
+
+- **Prompt-cache misses now say why, and mixed injections split by source (refs #1071)** — a `cache_usage` record carries `interTurnGapMs` and a `cacheMissCause` verdict of `ttl-expired`, `prefix-broke`, `partial-eviction`, or `unknown`, so the dominant cache cost is readable from `latency.log` instead of reconstructed by hand-joining timestamps. The gap is measured to request time, so a slow response is not mistaken for idle time; `gapBasis` names which endpoint produced the value. A `cache_context` record splits a mixed injection payload by contributing source, with per-source message count, characters, bytes, and an estimated token count. Token figures use a documented four-chars-per-token estimate and are never presented as provider-measured. The TTL threshold defaults to 60s and is overridable via `PI_LENS_PROVIDER_CACHE_TTL_MS`.
+
+- **Quick-mode session_start now logs which steps it skipped (closes #1911)** — quick mode silently skipped slow tool probes, language profiling, preinstall, startup scans, and the error-debt baseline, with no record either way. `session_start` now emits one bounded `session_start_skipped_steps` latency record naming the skipped step set, so a reader can tell "quick mode correctly skipped these" from "the probes silently never ran".
+
+- **Runner parsers are now held to real binary output (refs #1937)** — a parser written from documentation can be wrong in a way no hand-authored test sees, because the test asserts the same imagined shape. Captured real-bytes fixtures now live in `tests/fixtures/runner-output/`, each with a machine-generated provenance header naming the tool, version, and exact argv; a replay suite feeds those bytes through the runner, fails when the parser finds nothing, and fails when the runner's invocation drifts from the argv the fixture recorded. The sweep found four live instances: taplo spawned a `--output=json` flag taplo rejects, stylelint read stdout while stylelint 16+ reports on stderr, phpstan read the error COUNT as if it were the error array and discarded its file-independent findings entirely, and sqlfluff inserted `--dialect` between `--format` and its value so no unconfigured SQL project was ever linted. A scheduled `parser-smoke` lane now runs the tier-1 tools' real binaries over a planted violation, with a pass floor so a run that installed nothing cannot report green.
+
+- **A runner that reads nothing out of a failing tool's output now leaves a record (closes #1948)** — when a dispatch runner's tool exits nonzero, prints output, and the runner's parser extracts zero diagnostics, the degradation ledger gets a bounded `runner-parsed-nothing` row naming the tool, the exit status, the output length, and the first output line. Until now that case was byte-for-byte identical to a clean file in the worklog, which is how five parser bugs (vale, taplo, stylelint, phpstan, sqlfluff) reported clean files for months. A genuinely clean run records nothing, so the ledger does not fill up with one row per save. The gate lives in one shared helper, `parseToolRun`, that fourteen runners now share, and a sweep test keeps a new runner from silently opting out through any of the older spawn-outcome primitives.
+
+- **Mechanical lint batch: actionlint, PR-title lint, markdownlint, OSV scan (refs #1844)** — a new `lint.yml` workflow dogfoods actionlint against every workflow file, validates that every PR title carries a conventional prefix and an issue reference **in the title itself** (`scripts/check-pr-title.mjs` — a reference living only in the PR body no longer counts, since it never reaches the merge-commit subject), and lints Markdown docs with `markdownlint-cli2` under a repo-tuned config. A separate `osv-scan.yml` runs an advisory weekly `osv-scanner` sweep plus a scan on lockfile-touching PRs, writing results to the job summary.
+
+- **Vale prose lint with a vendored Google style base (refs #1844)** — `.vale.ini` at the repo root scopes Vale to `docs/`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `CONTRIBUTING.md`, `.claude/agents/*.md`, and `.changelog/*.md`, using the Google style package vendored under `.vale/styles/Google/` (no `vale sync` at CI time) plus a `pi-lens/` style with three house rules: no `please` in instructions, an em-dash-density check, and a long-sentence check. A new advisory `vale` job in `lint.yml` runs it on every PR. Because the in-product `vale` runner (`clients/dispatch/runners/vale.ts`) activates on `.vale.ini` presence, dogfood sessions now surface Vale findings on doc edits too.
+
+- **Husky-managed local git hooks (closes #1804)** — `npm install` now wires
+  a pre-commit hook (changelog fragment validation + `npm run lint`) and a
+  pre-push hook (build + a capped, full-path-resolved targeted `vitest`
+  selection for changed files, never the full suite; degrades to build-only
+  past 25 matched test files or a 2-minute shared test-lock wait). Both are
+  skippable with `PI_LENS_SKIP_HOOKS` set to any non-empty value, which
+  agents and CI should set; humans leave hooks on. Hook install itself is
+  skipped for CI and production/consumer installs, and never fails
+  `npm install` on error.
+
+- **latency.log now says whether the LSP pool reused a client or spawned one (closes #1934)** — `lsp_client_selected` fired 5601 times in a 20.8h dogfood window carrying only `{serverId, candidateCount}`, so nothing in the log said whether the pool served a warm client or paid for a language-server spawn. This is the most expensive cache in pi-lens: a miss costs a process. The only estimate was a cross-record inference against `lsp_launch_candidate_success`, which counts something else, so a regression that halved pool reuse was invisible. The record now carries an `outcome` field with one of three values on the same record and the same denominator. `warm-reuse` means the pool served an already-connected client. `cold-spawn` means this selection waited on a spawn, whether it started that spawn or joined one already in flight, so a session-start burst where many files wait on the same spawn reads as several cold spawns and deflates the apparent reuse rate for that window. `spawn-failure` means a spawn ran and failed. Reuse rate is `warm-reuse / (warm-reuse + cold-spawn)`. A spawn failure is deliberately distinct from a clean decline: no root, a breaker already open, host trust refused, or a binary absent while installs are disabled. Declines emit no outcome record and keep their existing ones, so `lsp_client_unavailable` and the `outcome` field can both describe the same event and are counted separately. `getWarmClientForFile`, the warm-only lookup the cascade quiet window and read expansion call per file, previously returned `undefined` and emitted nothing; it now emits a bounded `lsp_warm_client_missing` record naming the candidate server and root, rising-edge per candidate set with the exact count in the degradation ledger.
+
+- **Dogfood sessions on pi-lens's own repo now activate the oxlint, spellcheck, yamllint, and taplo runner lanes (refs #1844)** — four new root config files (`.oxlintrc.json`, `typos.toml`, `.yamllint`, `taplo.toml`) opt pi-lens's own repository into linters it already ships for every other project. `.oxlintrc.json` pins `oxlint` as a new exact-version devDependency (1.79.0, matching the runner's tested fixture), makes oxlint this repo's sole preferred JS/TS lint runner (dropping the `biome-check-json` fallback — that IS the dogfood intent), and excludes the fixture directories that carry no config override of their own; oxlint's nested-config discovery still finds the two fixture directories that deliberately escalate severity for the runner's own smoke tests, so those stay as they are. The oxlint runner also now tells a config-excluded file (`number_of_files: 0`) apart from a genuinely clean one, reporting `skipped` instead of a false `succeeded`. `typos.toml` allowlists evidenced false positives (a routine "mis-" prefix, HashiCorp's brand abbreviation, and similar); its presence enables typos-lsp's blocking opt-in, but findings stay advisory in practice since typos-lsp's own default diagnostic severity is warning. `.yamllint` scopes yamllint to hand-authored YAML (GitHub Actions workflows, top-level config), downgrades line-length to a warning rather than raising its threshold, and defuses the `on:` truthy false positive. `taplo.toml` activates both the TOML linter and the `taplo fmt` autofix formatter, and this PR runs that formatter once so activation doesn't start the lane red. Markdown linting was already live via the pre-existing `.markdownlint-cli2.jsonc` (since #1917) — confirmed with a real `markdownlint-cli2` run, no new config needed.
+
+- **Memory-sample observability upgrades (refs #1999)** — The periodic
+  `memory_sample` latency.log line gains three fields. `peakWorkingSetBytes`
+  records the OS high-water working set from `process.resourceUsage().maxRSS`,
+  so an idle-moment rss sample can be told apart from true growth (on Windows
+  libuv backs both counters with one `GetProcessMemoryInfo()` call: rss reads
+  current `WorkingSetSize`, maxRSS reads `PeakWorkingSetSize`). A rising-edge
+  cadence tightens sampling from every 10 turns to every turn while heapUsed
+  grows more than 20% between samples, reverting once growth stabilizes; the
+  state resets at each primary session start. Each sample now also carries
+  session age, session start time, and turn count, so growth-vs-age curves are
+  plottable from logs alone. The `/lens-health` memory line shows peak WS when
+  known.
+
+- **Opaque-write recovery for bash commands (refs #2000 phase 2)** — commands the path extractor does not recognize (python/node/perl/PowerShell internal writes) now get a bounded pre/post stat diff of the project source universe. Recovered files are attributed to the read guard as agent-authored and dispatched through the mutation seam, with explicit coverage-unknown telemetry instead of silent gaps.
+
+- **Collect-later delivery for slow auxiliary LSP servers (closes #2001, refs #2002)** —
+  When an auxiliary scanner such as opengrep misses its aux-grace window,
+  pi-lens now marks the file and server pair in a bounded pending store
+  instead of dropping the scanner's eventual findings. The next turn end
+  probes the auxiliary's client cache through a read-only seam,
+  freshness-gates the result against the mark timestamp, and delivers
+  survivors as a `Late auxiliary diagnostics` advisory. A cited file that was
+  edited or deleted since the mark drops its findings, and both drop arms are
+  counted in the new `late_auxiliary_findings` latency record.
+
+- **Freshness kernel: one comparator, one verdict type for staleness gates (closes #1739)** — `clients/freshness.ts` owns the mtime-vs-reference comparison and shared drift tolerance that six stores had independently reimplemented (three copies carried the identical #1710/#1711 tolerance defect). `freshnessFromMtime` returns an explicit verdict (`fresh` / `stale: modified-after-reference` / `indeterminate: no-mtime-evidence`) so each caller keeps its own no-evidence policy while sharing the comparison. A registered-or-fail sweep fails on any new out-of-kernel mtime-vs-reference comparison in `clients/`.
+
+- **Shared fault-injection test kit (closes #1838)** — `tests/support/fault-injection.ts` promotes the bespoke fault probes reviewers kept rebuilding by hand into four one-call primitives: `spawnWedgedChild` (a real child whose stdin pipe is genuinely full — the #1811 fixture generalized, with its fail-fast-instead-of-hang trap asserted against), `delayInside` (deterministic completion delay inside any mocked async seam), `fireResetAt` (fire a lifecycle hook from inside a seam's implementation at a chosen call — the #1746-R2-F1 shape), and `starveBudget` plus `gatedPromise` (the tiny-budget starvation repro). Every primitive carries its own fidelity test in `fault-injection.test.ts`, so a neutered primitive goes red in CI instead of silently weakening every consumer.
+
+- **Adversarial garbage battery for every CLI lint runner (closes #1839)** — Twenty runners now meet a 12-case battery of hostile outputs (truncated JSON, usage prose on the findings stream, unknown severities, hostile numbers) under format-blind invariants: never crash, never emit malformed diagnostics, never report clean on a nonzero exit carrying bytes. The first pass found 79 violations of that last invariant across 14 runners — all fixed by consolidating their identical tails onto one shared `finishParsedRun` seam. Also fixes htmlhint's `--rules` flag being fed JSON (the tool wants a ruleid list), which left zero rules enabled so every file read clean.
+
+### Changed
+
+- **pi-lens formats its own TypeScript with oxfmt (refs #1844)** — The
+  repository now carries an `.oxfmtrc.json` and an `oxfmt` devDependency, and
+  an advisory `oxfmt --check` job runs in CI. Because `hasOxfmtConfig` gates
+  the oxfmt formatter on exactly that config file, a pi-lens session opened on
+  this repository now dispatches oxfmt as the format runner for edited
+  TypeScript and JavaScript files.
+
+- **Opaque-write recovery goes git-first (refs #2000)** — inside a git worktree the pre side records only a timestamp and `git status --porcelain` plus an mtime window answers what changed, with no file-universe cap: recovery now works on any repo size, including large monorepos where the stat-walk previously degraded every command to coverage-unknown. The bounded stat-diff path remains for small non-git trees.
+
+- **ONE mutation seam: `RuntimeCoordinator.recordProjectMutation` (refs #2000 phase 1)** — the triplicated bump+change-log pairing (runtime-tool-result, runtime-agent-end, lsp-mutation) is consolidated onto one seam that bumps the seq store, appends a bounded attributed receipt ring (`getMutationsSince`, cap 512 with a surfaced dropped-count), and appends the durable change-log entry. Consumers derive touched-files answers from one store instead of three hand-copied pairings; phase 2's opaque-write recovery feeds the same seam.
+
+### Fixed
+
+- **Search credit ignores pipe truncation (closes #1908)** — `grep -C2 pattern
+  file | head -1` no longer credits context lines the pipe cut off. The
+  read-guard now detects a truncating pipe tail (`head`, `tail`, `sed q`)
+  downstream of a line-numbered grep and falls back to match-line-only
+  credit, so a later edit to the uncredited context still requires a read.
+
+- **Cascade tier-3 registry now resets at session_start (closes #1910)** — the outstanding-touch registry and its sweep-scoped expired/evicted counters (`clients/lsp/cascade-tier.ts`) used to survive a session replacement, so a new session inherited the prior session's outstanding touches and a stray eviction or expiry landed on the next session's first reconcile gauge. `handleSessionStart` now clears both, primary-only, same as every other per-session latch in that reset block.
+
+- **Read-guard eviction telemetry is now always on (closes #1913)** — the
+  first time a file's read-guard record cap trims in a session, it now emits
+  a `read_cap_trimmed` log line (file, evicted count, credit-vs-genuine
+  split, raw read count) regardless of `PI_LENS_READ_GUARD_VERBOSE`, so a
+  live eviction regression is visible by default instead of only under
+  verbose logging. Later trims on the same file keep updating the running
+  totals (queryable via `ReadGuard.getTrimStats`, and via the degradation
+  ledger's own tally) without flooding the log on every subsequent trim.
+
+- **agent_settled no longer crashes with extension_error when the session is replaced mid-run** —
+  stale extension ctx reads are guarded and the ambient abort signal is
+  cleared (closes #1924; thanks @Pluto-Yt).
+
+- **A session event on a replaced session no longer reports a pi-lens handler error (closes #1925)** — pi invalidates a captured extension ctx on `newSession`/`fork`/`switchSession`/`reload`, and an event already queued when that happens still reaches pi-lens carrying the dead ctx. `tool_result`, `turn_start`, `agent_end`, and `turn_end` each read a ctx property before any guard, so the SDK's `assertActive()` error was caught by `ExtensionRunner.emit` and reported as an extension error against pi-lens. That report named the wrong cause, said nothing about which handler was affected, and counted nothing. All five session-event registrations, including `agent_settled` (#1924), now go through one wrapper in `clients/session-event-guard.ts`: it probes the ctx once before dispatch, still classifies a stale error that arrives mid-handler, and records every skip in the degradation ledger under `extension-ctx-stale` plus a bounded `session_event_stale_ctx_skip` row in `latency.log`, keyed by event name. A new registered-or-fail sweep reds any future `pi.on` or `pi.on?.` registration that is neither wrapped nor given a stated reason.
+
+- **Git installs start about 750ms faster (refs #1926)** — pi supplies `typebox` and `@earendil-works/pi-tui` from its own runtime, but pi-lens declared both as runtime dependencies. A `git:` install therefore vendored a private second copy of each, and Node evaluated that whole extra module graph every time the extension loaded. Both are now optional peer dependencies, so nothing vendors them. The `PI_TIMING` module import for the dogfood git install drops from 941ms to 147-196ms, and the extensions block drops from 2165ms to 1449ms. One trade-off, stated plainly: because the bare specifiers no longer resolve on disk, pi loads the entry through jiti's transform path instead of a native import, so the FIRST start after an install, an update, or a jiti cache eviction is slower, around 5.6 to 8.2 seconds on the 4MB bundle. Every start after that is the fast one.
+
+- **Updating pi-lens no longer costs a five-second first session (refs #1926)** — pi loads the extension through jiti, which transforms the ~4MB `dist/index.js` bundle and caches the result. Every `git:` install or update produced a new bundle, so the next interactive session paid that transform: 4847ms of `module import`, against a 138ms steady state. The `prepare` chain now runs the transform itself, in `scripts/warm-loader-cache.mjs`, writing the same cache entry pi reads. The first session after an update is warm. The step runs last, is best-effort, and never fails an install; set `PI_LENS_SKIP_WARM_CACHE` to skip it. Each run appends one line to `~/.pi-lens/install.log`.
+
+- **A session swap that starves `session_start` or `context` is now counted, not misreported as a pi-lens crash (closes #1929)** — both handlers survived a dead extension ctx already, but each logged it as `session_start crashed: …` or `context event error: …` and recorded nothing, so a replacement that kept starving them was invisible in aggregate. Both now run through the shared stale-ctx wrapper and leave one bounded `extension-ctx-stale` record keyed to the event name. `context` uses a new value-returning wrapper variant that states its stale-path answer explicitly: `undefined`, pi's "this extension contributed nothing", so the host keeps its own message list rather than receiving a half-built injection. Seven of twelve `pi.on` registrations are now wrapped, up from five.
+
+- **Diagnostics scans stop logging a phantom ast-grep cache-stats record (closes #1935)** — `#1715` already grows the tree-sitter parse cache to span a project scan's file count, so the diagnostics-scan path does not run at the 50-entry interactive default; that part of `#1935` was resolved before this fix landed. What was still broken: every scan logged a second `cache_stats` record under scope `project_diagnostics_ast_grep_scan`, always all-zero, because ast-grep-napi parses through its own native engine and never touches the WASM tree cache that record claimed to measure. That vacuous record is now removed instead of wired to a cache it structurally cannot use; its one real value — ast-grep's own duration and file count, often a scan's most expensive phase — now rides an `astGrep` sub-field on the surviving `project_diagnostics_scan` record instead of disappearing. Added a memory-safety test pinning `treeCacheTotalBytes` at the existing 500-entry scan ceiling (`TREE_CACHE_SCAN_CAPACITY_CEILING`) using realistic, varying per-file sizes: worst case is 6-18MB of resident source bytes at that ceiling, and `TreeCache` enforces no per-entry byte cap of its own, only the entry count. A regression test pins the scanner to never emit the dead ast-grep scope.
+
+- **`cache_context` no longer logs an unusable `unknown` prefix pair on nearly every record (closes #1938)** — `prefixObservation` and `firstMessageChange` were computed from a hash of the pre-injection prefix capped at 64 messages / 2,048 characters. Any transcript past that cap set `prefixHashTruncated`, which forced both fields to `"unknown"`. Every real session outgrows the cap within the first few turns, so the pair reported `unknown` on 97.2% and 7.6% of records respectively — cost without signal. This PR removes the whole family that existed only to support that pair: `prefixObservation`, `prefixObservationUnknown`, `prefixBaseline`, `firstMessageChanged`, `firstMessageChange`, `firstMessageHashTruncated`, `beforeFirstMessageHash`, `afterFirstMessageHash`, `beforePrefixHash`, `afterPrefixHash`, `prefixHashTruncated`, `prefixMessageCountTruncated`, `prefixContentHashTruncated` — 13 fields in all. `cache_prefix_break` already tracks first-message stability with an unbounded hash and never truncates; it remains the source of truth for cache-prefix breaks.
+
+- **Review-graph Tier-3 build never grew the tree cache past the 50-entry default (closes #1941)** —
+  `builder.ts`'s full-project rebuild parses every non-jsts file through the
+  shared `TreeSitterClient`'s parse-tree cache but never called
+  `ensureTreeCacheCapacity`, the #1715 fix already wired into the
+  diagnostics scanner. A project with more than 50 non-jsts files evicted
+  and re-parsed files past the 50th on every Tier-3 build. The build now
+  grows the cache to its actual per-parse working set before extraction
+  starts — the full file list on a cold build, or the checkpoint's remaining
+  files on a resumed build, since resumed files are reused from the
+  checkpoint graph and never re-parsed.
+
+- **A demoted blocker no longer shouts STOP, and it stops re-serving forever (closes #1944)** — the past-EOF gate moved a blocker whose file had shrunk past the cited lines into the advisory channel, but the advisory embedded the blocker body verbatim, so the agent still read "🔴 STOP — 11 issue(s) must be fixed" with line numbers the file no longer had. Nothing retired the record either, so it re-served on every turn end for the rest of the session (measured live at 80+ minutes). A demoted body now drops the STOP banner and the "must be fixed" imperative, renders a dead coordinate as `L<n> (line no longer exists)`, and — when no re-run could ever confirm it — is delivered once and then retired, with the suppression recorded in the degradation ledger under `demoted-finding-retired`. `lens_diagnostics mode=delta` also stops printing 🔴 on a row whose coordinate it just replaced with the stale marker.
+
+- **The oxlint runner now surfaces warning-severity findings instead of discarding them (closes #1947)** — oxlint exits 0 whenever nothing at error severity was found, and warning is oxlint's own default severity. The runner treated any exit 0 as "no findings" and returned early, so a real capture of oxlint on an unused variable — a full JSON report, exit 0 — was thrown away. The runner now parses stdout unconditionally and decides on the parsed diagnostic count instead of the exit code: zero diagnostics is still a clean `succeeded`/`none`, one or more is `failed` with `semantic: "warning"` (or `"blocking"` when a diagnostic is error severity), matching the mapping the runner already used for the nonzero-exit case. A captured real-bytes fixture (`tests/fixtures/runner-output/oxlint/warning-exit-zero.captured.json`, oxlint 1.79.0, exit 0) pins the behavior.
+
+- **Merge-train warden's `update-branch` kick 403s under branch protection (#1959)** — the workflow's job permissions granted `pull-requests: write` but not `contents: write`. The PUT `pulls/N/update-branch` endpoint has GitHub create a merge commit on the PR branch, which needs write access to repository contents, not just to the pull request object; the inline comment attributing it to `pull-requests: write` was wrong. The warden also now tells apart the two reasons update-branch can 403: a fork-owned head PR records a distinct benign outcome (`update-branch-forbidden-fork`, logged, not a run failure), while an own-branch PR still fails the run loudly, since that case is a real permissions bug like this one.
+
+- **The blind review-graph read no longer drops a valid snapshot on a HEAD-only move (closes #1961)** — `getCachedReviewGraph` verified the persisted snapshot's git stamp against the current HEAD, so a plain `git commit` made every reader see "graph: cold" until something rebuilt in-process. Measured stamp lifetime across four workspaces was 737s to 1562s (median), and two of the four were already missing at probe time. The read path now verifies tree IDENTITY, never revision — the same policy the build path's tier-2 load has followed since #300. A snapshot stamped for a different worktree is still dropped, since nothing downstream of this read content-verifies it. A snapshot stamped at a different HEAD is served, and both `project_report`'s trust notes and `module_report`'s warnings say which commit it was built at. That caveat is derived per call from the snapshot's stamped commit and the worktree's HEAD right now, so it never names a commit that has stopped being HEAD and it clears itself when HEAD returns to the stamped one. The mid-build resume checkpoint carried the same defect and got the same fix: it hashes every processed file on resume, so revision equality proved nothing the hashes did not. Both read verdicts now write a bounded `review-graph.log` record (`snapshot_read_dropped`, `snapshot_read_drifted`), rising-edge per workspace off the `review-graph-snapshot-read` ledger kind — the drop used to be silent, which is why it hid for weeks.
+
+- **A settled review-graph build no longer suppresses every later build, and `project_report` only claims a retry when one started (closes #1962)** — `buildOrUpdateGraph`'s dedupe cache deleted its entry on rejection only, so a settled promise for a skipped or completed build answered every later call for the same key for the rest of the process. Only the dispatch pipeline's per-invocation `clearGraphCache()` ever removed it, and the background build `project_report` kicks off never goes through the pipeline: four calls over 37s produced one `build_started` record and three "A retry was started." messages with no retry behind them. The entry now lives only while its build is pending, so genuine concurrency still dedupes and a settled build never latches. `project_report` asks the builder whether a build is already in flight before it claims one started, and reports the current attempt rather than replaying the first one as if it were fresh. A `.pi-lens.json` at the repo root raises `reviewGraph.maxFiles` above the derived 1000-file cap this repo trips, so the tool works on this repo at all.
+
+- **A language server that dies mid-session now records why, and the liveness probe stops provoking the deaths (closes #1969)** — an ast-grep child closed with `code=1` and empty stderr 14 times in one day. The visible fallout was 19 `lsp_client_skipped_broken` cooldowns and 32 coverage gaps; the cause was recorded nowhere. Two changes. First, an unprompted process `close` now writes an `lsp-server-unexpected-close` degradation-ledger entry naming the server, the exit code, the signal, and whether stderr carried anything. It is written on `close` rather than `exit`, so "stderr was empty" is a fact about the server and not a race with the pipe, and it is gated on `shutdownRequested`, so evictions and ordinary teardown record nothing. Second, the `pingLiveness` round-trip (#1277) no longer hardcodes `workspace/symbol`. It picks a method the server advertised, best first: `workspace/symbol`, then `textDocument/documentSymbol` or `textDocument/hover` on an already-open document, then nothing. ast-grep's tower_lsp backend logged "got a 'workspace/symbol' request, but it is not implemented" on every probe; it advertises `hoverProvider`, so it keeps a real round-trip. When no probe is available the ledger records `lsp-liveness-probe-unsupported`, because liveness derived from process and connection state alone is the weaker verdict and must not pass as the strong one. Also fixed on the same path: `createLSPClient`'s initialize-timeout catch killed the hung child without claiming the kill, so its own teardown reported as a crash. That fabricated the exact `code=1 signal=none stderr=empty` signature this change exists to make trustworthy, and it had been writing a false `lsp_server_unexpected_exit` latency line on every failed handshake since the #615 follow-up.
+
+- **Log writer reopens and retries once on a failed write instead of dropping records silently (refs #1970)** — `ndjson-logger.ts` is the shared write-plumbing behind every NDJSON sink (`latency.log`, `extension.log`, `tree-sitter.log`, `cascade.log`, `word-index.log`, `review-graph.log`, and any other `createNdjsonLogger` caller). This hardens the sink against reachable `appendFile` failures (ENOENT after the parent directory is deleted, EBUSY/EPERM under a syncing OneDrive folder or antivirus lock, EMFILE, ENOSPC) — the specific `ERR_STREAM_DESTROYED` reports that motivated this issue were root-caused to a different process's persistent-stream logger, not this sink, but the reachable-failure classes above land here today with no recovery and no observability. A write that throws now gets one reopen-and-retry (re-verify the parent directory, then retry the write once) before it counts as a loss, matching the `pi-analyze#15` shape. An unrecovered write is counted in a per-sink, in-memory tally (`writeFailures`) rather than thrown or silently discarded, and `degradation-ledger.ts` folds that tally into `getDegradationSummary()` at READ time under a new `log-sink-write-failure` kind — so `pilens_health` names the sink and the dropped-write count. The fold happens by reading ndjson-logger's own tally, never by writing a durable ledger row back through the sink that just failed, so a permanently dead sink cannot recurse into an unbounded chain of self-reporting writes. The tally resets alongside the rest of the ledger at `session_start`.
+
+- **Warmup and workspace-scan walkers gate by file extension before consulting the ignore matcher, cutting a 31.7s stall to sub-second on repos with large ignored file piles (closes #1974, reported by @0xkite)** — `isIgnored` recompiles minimatch patterns per ancestor directory on every call; a runtime-output directory like `wal/` holding tens of thousands of `.log` files, gitignored only by a file-level `*.log` pattern (so the directory itself is never pruned), forced every one of those files through that cost. Six walkers checked `isIgnored` before their own cheap extension gate, paying the expensive check for files the gate would have dropped anyway: `collectSourceFilesForWarmup` (`language-profile.ts`, the reported 31.7s case), `JscpdClient.hasSourceFilesRecursive` (`jscpd-client.ts`), `classifyEntry` (`source-filter.ts`), `makeSourceCountVisitor` (`startup-scan.ts`), `getModuleSourceFiles` (`review-graph/workspace-modules.ts`), and `collectWorkspaceDiagnosticFiles` (`lsp/index.ts`). All six now run their extension (or LSP-server) gate first; output is unchanged, since both gates still have to pass to keep a file — only the order changed. A repo-wide sweep of all 14 files that call `isIgnored` found `tree-sitter-client.ts` and `tools/lsp-diagnostics.ts` already extension-first, and cleared the remaining per-event/no-ext-gate sites by construction; see the PR body for the full per-site table.
+
+- **oxfmt no longer fails on a file its own config ignores (refs #1844)** —
+  pi-lens offers oxfmt for every extension oxfmt supports, so in a project
+  whose oxfmt config carries `ignorePatterns`, oxfmt was selected for files it
+  then refused to touch. It exits 2 with "Expected at least one target file",
+  which the strict exit-code posture read as a formatting failure, so every
+  edit to an ignored file surfaced an error. pi-lens now passes
+  `--no-error-on-unmatched-pattern`, which makes an empty target set a clean
+  no-op. Every other nonzero exit, including an unparseable file, still fails.
+
+- **ESLint warnings are no longer discarded (closes #1954)** — The eslint runner treated every exit 0 as "nothing found". ESLint exits 0 whenever no rule reaches error severity, so a run that produced only warning-severity findings was thrown away silently. The runner now parses stdout unconditionally and surfaces the findings; a clean file still reports clean, and exit 2 stays an unavailable skip.
+
+- **Registered tools now always have descriptions in child/subagent sessions (closes #1988)** — the final registration boundary fills missing, empty, and
+  whitespace-only descriptions for active, lazy, activation, and wrapped tool
+  definitions.
+
+- **mode=full no longer replays stale mid-edit blockers (refs #1993)** — a confirmed, fully-covered LSP sweep is now authoritative for its files: widget-store diagnostics captured from a since-fixed broken intermediate state are retired instead of rendering as current 🔴 blockers beside a clean sweep. Unconfirmed or timed-out sweeps keep the fail-open behavior.
+
+- **Cache-miss attribution stays useful in long sessions (closes #1996)** — classify full model/provider identities and split unexplained or malformed cache evidence by bounded reason, with fail-closed request hashing, activation-owned primary/secondary isolation, sanitized numeric metadata, and a per-session cause summary.
+
+- **Project snapshots no longer rewrite unchanged same-generation bodies (closes #1997)** — Persistence now coalesces concurrent requests and computes semantic identity on its worker before gzip or staging. Same-generation content changes and failed-write repairs still publish.
+
+- **Classify oxlint no-match results as expected skips (closes #1998)**. Oxlint now carries `no-files-matched` through runner telemetry without emitting an extension error or claiming the file is clean. A single fail-closed state machine validates process completion, exit status, stderr, the captured banner, and every JSON summary field's type and range; truncated, malformed, wrong-status, or error-bearing lookalikes retain failure or unconfirmed telemetry.
+
+- **Project-snapshot persistence validates gzip body integrity before skipping (closes #2008)** —
+  The skip decision trusted the meta sidecar and a fingerprint match alone, so a torn or
+  truncated gzip under an intact meta kept winning unchanged-dedupe and stayed canonical until
+  the project sequence advanced. The meta sidecar now records the on-disk gz byte length
+  (`gzBytes`) at every successful persist, and the dedupe baselines compare it against a live
+  stat: a size mismatch, or a legacy meta without the field, withholds the dedupe fingerprints
+  so the pending save republishes and rewrites the body. A skip that would honor evidence
+  failing this gate between dispatch and promotion is refused and rewritten synchronously.
+  Detections emit one `project_snapshot_body_integrity` latency record plus a bounded
+  `snapshot-integrity` degradation-ledger entry per corrupted body path. The baselines read is
+  also now a pure read: its in-process seeding write moved to the single dispatch seam that
+  owns the persist lifecycle.
+
+- **Installer verify loop broken at the root (closes #2015)** — `verifyToolBinary` now spawns through `safeSpawnAsync` (tree-kill on timeout, typed kill-reason) instead of raw spawn whose SIGTERM orphaned grandchild node processes on Windows `.cmd` shims. A killed/inconclusive prober no longer counts as a verdict: the freshly installed binary is KEPT for cheap re-probe instead of deleted, ending the install/verify/reinstall churn (23 SIGTERMs and 4 cleanups observed in one day).
+
+- **Windows `.cmd`/`.bat` spawns no longer fail when System32 is absent from the child PATH (closes #2023)** — The cmd.exe wrapper prefixed every spawn
+  with a bare `chcp 65001 &&`. When the child environment's PATH could not
+  resolve `chcp.com`, the lookup failed and `&&` short-circuited, so the whole
+  spawn exited 1 with empty output. chcp is now invoked via its pinned
+  `%SystemRoot%\System32\chcp.com` absolute path and chained with `&`, so a
+  code-page failure can never suppress the real command.
+
+- **Register remaining agent-facing delivery surfaces (#2028)** — The per-edit 🔴 STOP block now drops blockers whose cited file no longer exists, so a deleted file's stale blocker no longer re-blocks the agent with no remediation. All five previously unregistered surfaces (stop blocker, `lsp_diagnostics` output, git-guard verdicts, read-guard preflight errors, thrashing notices) are registered in the finding-delivery gate registry.
+
+- **Wall-clock budget tests get a quiet serial phase (closes #1920)** — Five test files asserting real elapsed-time budgets ran inside the default project's fork storm, measuring scheduler contention instead of code speed (`startup-overhead` measured 659-2321ms against a 500ms budget under load, green solo every time). They now run in a dedicated fully-serialized `wall-clock-budget` Vitest project that phases dead last on a quiet host. A coverage guard keeps the new include list from silently dropping renamed files.
+
 ## [4.1.0] - 2026-08-20
 
 ### Added

package/README.md

@@ -34,6 +34,112 @@ pi-lens gives AI coding agents fast, language-aware feedback while they write/ed
 - MCP server (experimental) so Claude Code or any MCP client can drive the
   same diagnostics/read-substitute tools pi-lens exposes to pi
 
+## Architecture
+
+Most lifecycle events enter through one wrapper, which drops and counts events
+that arrive on a replaced session. `tool_call` registers raw: it delegates
+straight to a handler that owns its own total guard. Events fan out into the
+edit-time lane and the LSP lane. Both lanes write into the findings stores.
+Nothing reaches the agent from those stores until a freshness gate or an
+explicit age label clears it.
+
+```mermaid
+flowchart TD
+    subgraph host["pi host"]
+        HOST["Host events<br/>tool_call, tool_result, turn_start/end,<br/>session_start/shutdown, agent_end, context"]
+        WRAP["Stale-ctx wrapper<br/>skips and counts events on a replaced session<br/>tool_result, turn_start, turn_end, agent_end,<br/>agent_settled, session_start, context"]
+    end
+
+    subgraph guards["Guards"]
+        RG["Read-guard<br/>blocks edits that lack prior reading"]
+        GG["Git-guard<br/>holds commit/push while findings stay unresolved"]
+    end
+
+    subgraph edit["Edit-time lane"]
+        PIPE["Post-write pipeline<br/>secrets, format, autofix, sync, lint, tests"]
+        PLAN["Dispatch plan<br/>per file kind, per capability group"]
+        RUN["Runners<br/>format, lint, types, security, smells, docs"]
+        STRUCT["Structural rules<br/>tree-sitter queries and ast-grep"]
+        BUS["files-touched bus<br/>tells extensions which paths moved"]
+    end
+
+    subgraph lsp["LSP lane"]
+        POOL["Client pool<br/>warm reuse, idle eviction"]
+        DIAGS["File and workspace diagnostics"]
+        CASC["Impact cascade<br/>tiered wait policy"]
+    end
+
+    STORES["Findings stores<br/>widget state, warning caches, project snapshot"]
+
+    subgraph gate["Freshness gating"]
+        FRESH["Path freshness<br/>mtime vs scan time, past-EOF, dependency drift"]
+        DISPO["Dispositions<br/>false-positive, suppress, defer, flagged"]
+        LABEL["Explicit age label<br/>for findings no path gate can check"]
+    end
+
+    subgraph deliver["Delivery surfaces"]
+        TURN["Turn-end findings injection"]
+        WIDGET["Widget and footer tally"]
+        TOOLS["lens_diagnostics tool"]
+        NUDGE["Agent nudges"]
+    end
+
+    SESSION["Session lifecycle<br/>primary, sequential replacement, concurrent secondary"]
+    SINKS["Observability sinks<br/>latency.log, degradation ledger, bounded telemetry,<br/>cache observability, cascade and tree-sitter logs"]
+
+    HOST --> WRAP
+    HOST -->|tool_call, raw| RG
+    HOST -->|tool_call, raw| GG
+    WRAP -->|session_start| SESSION
+    WRAP -->|tool_result| PIPE
+    WRAP -->|tool_result, records reads and writes| RG
+    SESSION --> POOL
+    SESSION --> STORES
+    PIPE --> PLAN
+    PLAN --> RUN
+    PLAN --> STRUCT
+    PIPE --> POOL
+    PIPE --> BUS
+    POOL --> DIAGS
+    DIAGS --> CASC
+    RUN --> STORES
+    STRUCT --> STORES
+    DIAGS --> STORES
+    CASC --> STORES
+    BUS --> NUDGE
+    RG -->|read and edit history filter| NUDGE
+    STORES --> FRESH
+    STORES --> LABEL
+    FRESH --> DISPO
+    DISPO --> TURN
+    DISPO --> WIDGET
+    DISPO --> TOOLS
+    LABEL --> TURN
+    TURN --> GG
+    WRAP --> SINKS
+    PIPE --> SINKS
+    RUN --> SINKS
+    STRUCT --> SINKS
+    POOL --> SINKS
+    CASC --> SINKS
+    RG --> SINKS
+    GG --> SINKS
+    FRESH --> SINKS
+```
+
+Architecture-level view, updated when a lane changes. Per-tool inventories live
+in [features](docs/features.md) and
+[language coverage](docs/language-coverage.md). Today the edit-time lane carries
+45+ runner modules over 35+ file kinds, and the LSP lane speaks to a dozen-plus
+language servers.
+
+The gating box is an abstraction, not a call order. Freshness covers several
+independent mechanisms: path freshness against scan time, past-EOF line checks,
+and forward-import dependency drift. Dispositions are one more filter alongside
+them, not a second stage every finding walks through. Read the box as "a finding
+passes the gates that apply to it", and see `clients/finding-delivery-gate.ts`
+for the per-surface contract.
+
 ## Install
 
 ```bash

package/dist/clients/actionable-warnings-logger.js

@@ -5,7 +5,8 @@ import { createNdjsonLogger } from "./ndjson-logger.js";
 const AW_LOG_DIR = getGlobalPiLensDir();
 const AW_LOG_FILE = path.join(AW_LOG_DIR, "actionable-warnings.log");
 const AW_LOG_BACKUP_FILE = path.join(AW_LOG_DIR, "actionable-warnings.log.1");
-const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_AW_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);
+const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_AW_LOG_MAX_BYTES ?? "1048576", 10) ||
+    1048576);
 const writer = createNdjsonLogger({
     filePath: AW_LOG_FILE,
     maxBytes: MAX_LOG_BYTES,

package/dist/clients/actionable-warnings.js

@@ -633,7 +633,12 @@ export async function applyConservativeActionableWarningFixes(args) {
                 }
                 const edit = selected.edit;
                 const applied = await applyWorkspaceEdit(edit, args.cwd, args.mutationContext
-                    ? { mutationContext: { ...args.mutationContext, emitSummary: false } }
+                    ? {
+                        mutationContext: {
+                            ...args.mutationContext,
+                            emitSummary: false,
+                        },
+                    }
                     : undefined);
                 appliedResults.push(applied);
                 for (const changedFile of applied.files)
@@ -642,8 +647,7 @@ export async function applyConservativeActionableWarningFixes(args) {
             }
             catch (err) {
                 failedCount++;
-                const partial = err
-                    .appliedWorkspaceEdit;
+                const partial = err.appliedWorkspaceEdit;
                 if (partial) {
                     appliedResults.push(partial);
                     for (const changedFile of partial.files)
@@ -656,13 +660,18 @@ export async function applyConservativeActionableWarningFixes(args) {
         }
     }
     summary.changedFiles = [...changedFiles];
-    if (args.mutationContext && (summary.considered > 0 || appliedResults.length > 0)) {
+    if (args.mutationContext &&
+        (summary.considered > 0 || appliedResults.length > 0)) {
         recordLspMutationBatch(args.mutationContext, {
             results: appliedResults,
             considered: summary.considered,
             completed: summary.applied,
             failedCount,
-            status: failedCount > 0 ? "failed" : appliedResults.length > 0 ? "success" : "skipped",
+            status: failedCount > 0
+                ? "failed"
+                : appliedResults.length > 0
+                    ? "success"
+                    : "skipped",
             bookkeep: false,
         });
     }

package/dist/clients/advisory-provenance.js

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { logLatency } from "./latency-logger.js";
 import { normalizeMapKey, toProjectRelativePath } from "./path-utils.js";
 import { resolveRunnerPath } from "./dispatch/runner-context.js";
-import { MTIME_DRIFT_TOLERANCE_MS } from "./blocker-freshness.js";
+import { freshnessFromMtime } from "./freshness.js";
 export const MAX_ADVISORY_AFFECTED_FILES = 256;
 export function advisoryPathKey(filePath, cwd) {
     return normalizeMapKey(path.resolve(cwd, filePath));
@@ -68,25 +68,41 @@ function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
 function isCapturedHash(value) {
-    return typeof value === "string" &&
-        (/^[a-f0-9]{64}$/.test(value) || value === "missing" || value.startsWith("unreadable:"));
+    return (typeof value === "string" &&
+        (/^[a-f0-9]{64}$/.test(value) ||
+            value === "missing" ||
+            value.startsWith("unreadable:")));
 }
 function isWellFormed(value) {
     if (!value || typeof value !== "object")
         return false;
     const record = value;
     const revision = record.revision;
-    return !!revision && typeof revision.sessionId === "string" &&
-        isFiniteNumber(revision.projectSeq) && isFiniteNumber(revision.turnIndex) &&
-        isFiniteNumber(revision.generation) && isFiniteNumber(revision.capturedAt) &&
-        Array.isArray(record.files) && record.files.length > 0 && record.files.every((file) => !!file && typeof file.path === "string" &&
-        (file.role === "source" || file.role === "test" || file.role === "affected") &&
-        isFiniteNumber(file.mtimeMs) && isFiniteNumber(file.size) &&
-        isCapturedHash(file.sha256));
+    return (!!revision &&
+        typeof revision.sessionId === "string" &&
+        isFiniteNumber(revision.projectSeq) &&
+        isFiniteNumber(revision.turnIndex) &&
+        isFiniteNumber(revision.generation) &&
+        isFiniteNumber(revision.capturedAt) &&
+        Array.isArray(record.files) &&
+        record.files.length > 0 &&
+        record.files.every((file) => !!file &&
+            typeof file.path === "string" &&
+            (file.role === "source" ||
+                file.role === "test" ||
+                file.role === "affected") &&
+            isFiniteNumber(file.mtimeMs) &&
+            isFiniteNumber(file.size) &&
+            isCapturedHash(file.sha256)));
 }
 export function validateAdvisoryProvenance(record, cwd, runtime) {
     if (!isWellFormed(record.provenance)) {
-        return { status: "unknown", reasons: ["malformed-or-legacy-provenance"], allFilesDeleted: false, changedPathCount: 0 };
+        return {
+            status: "unknown",
+            reasons: ["malformed-or-legacy-provenance"],
+            allFilesDeleted: false,
+            changedPathCount: 0,
+        };
     }
     const provenance = record.provenance;
     const reasons = [];
@@ -149,9 +165,19 @@ export function validateAdvisoryProvenance(record, cwd, runtime) {
     }
     const allFilesDeleted = deletedFiles === provenance.files.length;
     if (unknown)
-        return { status: "unknown", reasons, allFilesDeleted, changedPathCount: changedPaths.size };
+        return {
+            status: "unknown",
+            reasons,
+            allFilesDeleted,
+            changedPathCount: changedPaths.size,
+        };
     return reasons.length > 0
-        ? { status: "superseded", reasons, allFilesDeleted, changedPathCount: changedPaths.size }
+        ? {
+            status: "superseded",
+            reasons,
+            allFilesDeleted,
+            changedPathCount: changedPaths.size,
+        }
         : { status: "current", reasons: [], allFilesDeleted, changedPathCount: 0 };
 }
 // ── Finding-cited path existence (#1461 slice 1) ──────────────────────────────
@@ -224,11 +250,15 @@ const MAX_LOGGED_DEAD_PATHS = 3;
 export function findingPathFreshness(resolvedPath, scannedAtMs) {
     try {
         const stat = fs.statSync(resolvedPath);
-        if (scannedAtMs !== undefined &&
-            stat.mtimeMs > scannedAtMs + MTIME_DRIFT_TOLERANCE_MS) {
-            return "stale";
-        }
-        return "live";
+        // No scan timestamp recorded: the pre-kernel behavior treated the
+        // path as live (no reference to be stale against) - preserved.
+        if (scannedAtMs === undefined)
+            return "live";
+        const verdict = freshnessFromMtime({
+            mtimeMs: stat.mtimeMs,
+            referenceMs: scannedAtMs,
+        });
+        return verdict.verdict === "stale" ? "stale" : "live";
     }
     catch (error) {
         const code = error.code ?? "unknown";

package/dist/clients/ast-grep-client.js

@@ -113,9 +113,7 @@ export class AstGrepClient {
                 (fs.existsSync(projectRuleDir)
                     ? projectRuleDir
                     : resolvePackagePath(import.meta.url, "rules"));
-        this.log = verbose
-            ? createSubsystemLogger("ast-grep")
-            : () => { };
+        this.log = verbose ? createSubsystemLogger("ast-grep") : () => { };
         this.ruleManager = new AstGrepRuleManager(this.ruleDir, this.log);
         this.runner = new SgRunner(verbose);
     }

package/dist/clients/atomic-write-staging.js

@@ -19,7 +19,13 @@ export function stageOwnerPidFromName(name) {
 }
 export async function sweepOwnStagingFiles(directories, options) {
     const uniqueDirectories = [...new Set(directories)].filter(Boolean);
-    const result = { directories: uniqueDirectories.length, scanned: 0, removed: 0, liveSkipped: 0, truncated: false };
+    const result = {
+        directories: uniqueDirectories.length,
+        scanned: 0,
+        removed: 0,
+        liveSkipped: 0,
+        truncated: false,
+    };
     for (const directory of uniqueDirectories) {
         let handle;
         try {
@@ -47,14 +53,20 @@ export async function sweepOwnStagingFiles(directories, options) {
                     continue;
                 }
                 try {
-                    await fs.promises.rm(path.join(directory, entry.name), { force: true });
+                    await fs.promises.rm(path.join(directory, entry.name), {
+                        force: true,
+                    });
                     result.removed++;
                 }
-                catch { /* leave it for the next bounded sweep */ }
+                catch {
+                    /* leave it for the next bounded sweep */
+                }
             }
             result.truncated ||= reachedEntryCap;
         }
-        catch { /* best-effort directory scan */ }
+        catch {
+            /* best-effort directory scan */
+        }
         finally {
             await handle.close().catch(() => { });
         }