@herbertgao/pi-extensions 2026.8.7 → 2026.8.9

package/node_modules/@pi-plugins/fast-mode/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-plugins/fast-mode",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Fast service-tier extension for pi-agent.",
   "keywords": [
     "fast",
@@ -40,6 +40,7 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
     "@types/node": "26.1.2",
     "oxfmt": "0.62.0",
     "oxlint": "1.77.0",
@@ -51,17 +52,14 @@
     "@pi-plugins/tsconfig": "0.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   },
   "pi": {
     "extensions": [
       "./dist/index.mjs"
     ]
   },
-  "inlinedDependencies": {
-    "@earendil-works/pi-tui": "0.83.0",
-    "marked": "18.0.5"
-  },
   "scripts": {
     "build": "tsdown",
     "check": "pnpm run lint && pnpm run check-types && pnpm run format:check",

package/node_modules/pi-lens/CHANGELOG.md

@@ -16,6 +16,96 @@ All notable changes to pi-lens will be documented in this file.
 
 ### Security
 
+## [4.1.1] - 2026-08-21
+
+### 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.
+
+### 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.
+
 ## [4.1.0] - 2026-08-20
 
 ### Added

package/node_modules/pi-lens/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/node_modules/pi-lens/dist/clients/bash-file-access.js

@@ -45,10 +45,10 @@ export function tokenizeShellCommand(command) {
         word = "";
         atTokenStart = true;
     };
-    const flushSegment = () => {
+    const flushSegment = (terminator) => {
         flushWord();
         if (tokens.length > 0 || unsupported)
-            segments.push({ tokens, unsupported });
+            segments.push({ tokens, unsupported, terminator });
         tokens = [];
         unsupported = false;
         atTokenStart = true;
@@ -122,13 +122,18 @@ export function tokenizeShellCommand(command) {
         }
         if (ch === ";" || ch === "\n" || ch === "|" || ch === "&") {
             flushWord();
+            let terminator;
             if (ch === "|" && next === "|")
                 i++;
             else if (ch === "&" && next === "&")
                 i++;
-            else if (ch === "|" || ch === "&")
+            else if (ch === "|") {
                 unsupported = true;
-            flushSegment();
+                terminator = "pipe";
+            }
+            else if (ch === "&")
+                unsupported = true;
+            flushSegment(terminator);
             continue;
         }
         if (ch === "<" || ch === ">") {
@@ -514,6 +519,83 @@ function parseGrepLineWithoutFile(line, file) {
         return undefined;
     return { file, startLine: lineNumber, endLine: lineNumber };
 }
+/**
+ * Verbs that DROP printed lines from a piped stream (#1908, review F4): a
+ * hit that survives such a tail cannot be trusted to still carry the
+ * -A/-B/-C context grep's flags declared, because that context may have
+ * been among the dropped lines. `head`/`tail` drop by position (even bare,
+ * since both default to a 10-line window); `sed` with a `q` command drops
+ * everything after the addressed line; `uniq` drops adjacent duplicate
+ * lines, which can include a context line that happens to repeat.
+ *
+ * The criterion is DROPPING, not "changes grep's output shape" — a review
+ * finding (#1913 F4) caught this file previously conflating the two:
+ *   - `head`/`tail`/`sed q`/`uniq` downstream of a matching grep → some
+ *     printed lines are genuinely gone, so credit falls back to
+ *     match-line-only (the same conservative default already used for
+ *     unparseable commands) rather than trusting the declared flags.
+ *   - `sort` and other REORDER-ONLY filters keep every line grep printed,
+ *     just in a different order — a surviving `file:line:` match still
+ *     carries the full context grep actually printed, so no special case is
+ *     needed (proven by the "still credits full context through a
+ *     non-truncating pipe tail" test below).
+ *   - `wc` and similar filters that REPLACE grep's output entirely (with a
+ *     count, say) leave no `file:line:`-shaped line at all, so
+ *     `parseGrepOutputSearchReads` already finds zero matches in the real
+ *     captured stdout. Also no special case needed, but for the OPPOSITE
+ *     reason from `sort`: nothing survives to credit, rather than
+ *     everything surviving intact.
+ *   - A pass-through filter (`cat`, `grep -v`, ...) between grep and a
+ *     dropping tail still counts: the walk below follows the whole pipe
+ *     chain, not just the immediate next segment.
+ *   - Out of scope, deliberately: `sed -n 'Np'` range-address filtering
+ *     without `q`, and `sort -u`, also drop lines but aren't in #1908's
+ *     stated scope — revisit if they recur in the field. Also out of
+ *     scope: a truncating tail hidden inside a subshell/brace-group
+ *     (`( ... )`, `{ ...; }`) or reimplemented in `awk`/`perl` — the shared
+ *     tokenizer this file uses doesn't parse inside those, matching its
+ *     documented "small conservative shell lexer" scope.
+ */
+const LINE_DROPPING_TAIL_VERBS = new Set(["head", "tail", "uniq"]);
+function isSedQuitCommand(args) {
+    for (const arg of args) {
+        const token = stripQuotes(arg);
+        if (token.startsWith("-"))
+            continue;
+        // A `q` command anchored at the start of the script or after a `;`/
+        // newline separator, optionally preceded by a numeric/`$` address
+        // (`q`, `1q`, `$q`, `1,3p;q`). Deliberately not a full sed parser.
+        if (/(^|[;\n])\s*(\d+|\$)?\s*q\b/.test(token))
+            return true;
+    }
+    return false;
+}
+function isLineDroppingTailCommand(tokens) {
+    const verb = path.basename(stripQuotes(tokens[0] ?? ""));
+    if (LINE_DROPPING_TAIL_VERBS.has(verb))
+        return true;
+    if (verb === "sed")
+        return isSedQuitCommand(tokens.slice(1));
+    return false;
+}
+/**
+ * True when the grep segment starting at `index` feeds — directly or through
+ * a chain of pipes — into a line-dropping tail (#1908). Only an unquoted `|`
+ * counts: a `;`/`&&`/`&`-separated command downstream never receives grep's
+ * stdout, so it must not downgrade credit (#1913 F2 — this was previously
+ * unverified by any test that could tell a real pipe from mere adjacency).
+ */
+function grepPipesIntoTruncatingTail(segments, index) {
+    if (segments[index]?.terminator !== "pipe")
+        return false;
+    for (let j = index + 1; j < segments.length; j++) {
+        if (isLineDroppingTailCommand(segments[j].tokens))
+            return true;
+        if (segments[j].terminator !== "pipe")
+            return false;
+    }
+    return false;
+}
 function collectGrepCommandFiles(command, cwd) {
     const files = new Set();
     let hasLineNumberGrep = false;
@@ -522,7 +604,14 @@ function collectGrepCommandFiles(command, cwd) {
     // contributing grep printed, so no line is credited that a hit from the
     // narrowest grep never delivered.
     let context;
-    for (const tokens of commandSegments(command)) {
+    // #1908: if ANY contributing grep pipes into a truncating tail, fall back
+    // to match-line-only credit for the whole command — the parsed hits carry
+    // no segment identity, so a per-segment override isn't representable in
+    // the aggregate `context` this function returns.
+    let truncated = false;
+    const segments = tokenizeShellCommand(command);
+    for (let i = 0; i < segments.length; i++) {
+        const tokens = segments[i].tokens;
         const verb = path.basename(stripQuotes(tokens[0] ?? ""));
         if (verb !== "grep" && verb !== "egrep" && verb !== "fgrep")
             continue;
@@ -539,11 +628,13 @@ function collectGrepCommandFiles(command, cwd) {
             : segmentContext;
         for (const file of extractGrepSearchFiles(args, cwd))
             files.add(file);
+        if (grepPipesIntoTruncatingTail(segments, i))
+            truncated = true;
     }
     return {
         hasLineNumberGrep,
         files,
-        context: context ?? { before: 0, after: 0 },
+        context: truncated ? { before: 0, after: 0 } : (context ?? { before: 0, after: 0 }),
     };
 }
 function dedupePushSearchRead(out, seen, loc) {

package/node_modules/pi-lens/dist/clients/blocker-past-eof.js

@@ -56,7 +56,7 @@ export function sweepInlineBlockerPastEof(runtime, cwd, options) {
         total: 0,
         checked: 0,
         demoted: 0,
-        healed: 0,
+        deadLinesByPath: new Map(),
     };
     const resync = options?.resync ?? resyncDocumentOnPastEof;
     let entries;
@@ -101,15 +101,25 @@ export function sweepInlineBlockerPastEof(runtime, cwd, options) {
             // The record cites any of its lines being past EOF as a whole-record
             // demotion — one summary string, not one flag per line.
             const isPastEof = diagnostics.some((d) => d.stale);
+            if (isPastEof) {
+                // #1944: record WHICH cited lines died, before the transition check
+                // below short-circuits. A record demoted on an earlier turn does not
+                // transition, yet its dead lines are exactly what the delivery
+                // surface must annotate and retire on.
+                counts.deadLinesByPath.set(entry.filePath, diagnostics
+                    .filter((d) => d.stale)
+                    .map((d) => d.line)
+                    .filter((line) => typeof line === "number"));
+            }
             const transitioned = runtime.setInlineBlockerPastEofStale(entry.filePath, isPastEof);
             if (!transitioned)
                 continue;
-            if (isPastEof) {
+            // Only the rising edge is countable here — see `BlockerPastEofCounts`
+            // for why the falling edge cannot occur on this store anymore. The
+            // call below still un-demotes, so the STORE stays honest even though
+            // nothing can observe the transition.
+            if (isPastEof)
                 counts.demoted += 1;
-            }
-            else {
-                counts.healed += 1;
-            }
         }
         catch {
             // Per-entry failure: leave the entry as-is.

package/node_modules/pi-lens/dist/clients/bounded-telemetry.js

@@ -77,12 +77,26 @@ export const BOUNDED_TELEMETRY_PHASES = [
     "lsp_client_skipped_broken",
     /** #1743 review: the same skip, for a temporarily unavailable command. */
     "lsp_client_skipped_unavailable_command",
+    /**
+     * #1934: `getWarmClientForFile` found no live client for a file that has at
+     * least one language server with a resolvable root. Its callers run per
+     * file (the cascade quiet window, read expansion, `hasWarmLSP`), so it is
+     * rising-edge per candidate (server, root) set, with the ledger holding the
+     * exact count.
+     */
+    "lsp_warm_client_missing",
     /**
      * #1723: an event-loop block at or above the floor. Not a degradation, so
      * no ledger kind; bounded by call cadence (one `turn_end` runs it once per
      * turn) rather than by an option here.
      */
     "loop_block",
+    /**
+     * #1925: a session event skipped because its ctx was invalidated by a
+     * session replacement or reload. A replaced session can drain a whole
+     * queue of them, so it is rising-edge per event name.
+     */
+    "session_event_stale_ctx_skip",
 ];
 const REGISTERED_PHASES = new Set(BOUNDED_TELEMETRY_PHASES);
 /** Report whether a phase name is in the registry (used by the sweep). */