pi-lens 4.3.0 → 4.4.0

package/docs/rfcs/3654-unified-io-bridge-v2.md

@@ -0,0 +1,316 @@
+# RFC 3654: Unified File I/O Lifecycle Bridge (v2 Specification)
+
+**Status:** Accepted by the maintainer on #4145 (2026-10-08)  
+**Tracking Issue:** [apmantza/pi-lens#3654](https://github.com/apmantza/pi-lens/issues/3654)  
+**Related Issues/PRs:** #3651 (multi-span batching), #3652 (0-line reads), #3650 (mutating-tool path), #3785 (read-guard evidence & FileTime), #2465 (no-read-guard split), #3620 (lineage fence)  
+**Authors:** Architecture Council (`lens-orchestrator`, `council-peer`)  
+
+---
+
+## 1. Executive Summary & Teleological Frame
+
+### Problem
+Pi coding-agent extensions interacting with the filesystem outside pi-lens's native tool hooks currently face severe friction and architectural fragmentation:
+1. **Dual Bridge Overhead**: Producers performing atomic edit + preview-diff turns must call two separate global symbol bridges: `Symbol.for("pi-lens:mutation-bridge")` then `Symbol.for("pi-lens:read-bridge")`.
+2. **Redundant Synchronous I/O (#3651)**: `ReadBridge.recordRead` executes two synchronous `fs.readFileSync` calls per read (one for `captureReadContentBinding` and one for `captureLineHashes`), even when the producer already holds file content in memory.
+3. **Absence of Delete Lifecycle**: Programmatic file deletion is unrepresented in existing bridges, leaving zombie records in `readGuard.reads`, `writtenThisSession`, and `knownPathIndex`.
+4. **Ordering & Freshness Hazards**: Concurrent writers and multi-window reads risk desynchronizing `FileTime` and read evidence if the mutation and read facets are not executed in strict atomic sequence.
+
+### Proposed Outcome
+A unified, cohesive File I/O Lifecycle Bridge mounted at `Symbol.for("pi-lens:io-bridge")` carrying `readonly version: 2`, consolidating file observation (`read`), partial modification (`edit`), whole-file authorship (`write`), and deletion (`delete`) into an atomic, synchronous, non-throwing contract. Existing v1 bridges are preserved as zero-overhead shims mounted in the same first-wins pass.
+
+---
+
+## 2. Non-Negotiable Architectural Decisions (D1–D13)
+
+| ID | Decision | Invariant & Enforcement |
+|---|---|---|
+| **D1** | **Symbol Key & Version** | `Symbol.for("pi-lens:io-bridge")` + `readonly version: 2`. Policy: `version` covers minors; breaking majors require a new symbol key (first-wins frozen per-process slot). In the same first-wins pass, mount v1 shims for `pi-lens:read-bridge` and `pi-lens:mutation-bridge` preserving v1 return types (`void` and `boolean`). |
+| **D2** | **Mutation Umbrella Name** | The mutation facet is named **`mutate`** (not `write`), because `delete` is an absence event, not a write. |
+| **D3** | **`delete` Primitive** | `delete` is a `kind` under `mutate` (`mutate: { kind: "delete" }`), wrapped by the enclosing `!getFlag("no-read-guard")` gate, followed by the 4 confirmed-delete gates in production order, shared with the native bash path through `judgeConfirmedDelete` (`clients/confirmed-delete.ts`): (1) `isExternalOrVendorFile`, (2) `isPathIgnoredByProject`, (3) `readGuard.hasKnownPath`, (4) `!existsSync` confirm. Action: `readGuard.forgetPath(filePath)` and, when `!getFlag("no-lsp")`, `notifyExternalFileChange(filePath, 3)`. `no-lsp` suppresses only the notification; the native bash path skips the whole delete under `no-lsp`. Bypasses `recordWritten` and `addModifiedRange`; emits no change-log receipt. |
+| **D4** | **`rename` Deferred** | Compose as `delete(old)` + `write(new)`. Dead fields like `renamedFrom` are omitted from v2 until an active consumer exists. |
+| **D5** | **Read Evidence Policy** | Default is **coverage-only** (`evidence: "caller"` with no content/hashes binds range without line hashes). `"disk"` is an explicit opt-in for bridge-initiated disk hashing. The bridge never synthesizes hash evidence unless `"disk"` is passed. |
+| **D6** | **`content` Semantics** | Delivered raw text starting at `ranges[0][0]` (span-relative). No caller-fabricated `contentBinding`; whole-file staleness checks stay disk-derived only. |
+| **D7** | **Span Constraints** | `lineHashes` is keyed by absolute 1-indexed line numbers and supports multi-span reads. `content` is valid **only** with a single contiguous range (`ranges.length === 1`). |
+| **D8** | **Hash Map Typing** | `lineHashes` is `Record<number, string>` (keys integers $\ge 1$), matching `ReadRecord.lineHashes`. |
+| **D9** | **Never Throws** | `record()` never throws. Malformed, out-of-scope, or ignored calls return `{ accepted: false, reason: RecordReason }`. Hash keys outside declared ranges are rejected with `"malformed"`. |
+| **D10** | **Independent Facet Outcomes** | Facets apply independently; `record()` returns `{ read?: RecordOutcome, mutate?: RecordOutcome }`. |
+| **D11** | **Accessor Idiom** | `getIOBridge()` returns `undefined` on version mismatch (mirroring v1). |
+| **D12** | **Public API Stability** | Add section to `docs/public-api-stability.md` designating `PiLensIOBridge` as public API from day one, linking `docs/io-bridge-v2-migration.md`, with changelog fragment audience `user`. |
+| **D13** | **TLA+ & Governance Plan** | PR implementation must add row in `formal/coverage-map.json` mapping `clients/io-bridge.ts` to `[session-lifecycle, read-guard]`; verify write-before-read and lineage fence invariants, or cite `TLA+ unaffected`. |
+| **D14** | **Backward-Compatible Refinement** | v1 behavior may be refined in v2, but v1's observable behavior MUST NOT break. v1 shims (`read-bridge`, `mutation-bridge`) are a frozen compatibility layer. Every input v1 accepted, v1 accepts; same return types; same effective guard/cache key; same display path. Detailed mappings live in `docs/io-bridge-v2-migration.md`. |
+
+---
+
+## 3. Normative TypeScript Interface
+
+```typescript
+/**
+ * Generic File I/O Lifecycle Bridge for pi-lens (v2).
+ * Mounts at globalThis[IO_BRIDGE_SYMBOL].
+ */
+
+export const IO_BRIDGE_SYMBOL = Symbol.for("pi-lens:io-bridge");
+export const IO_BRIDGE_VERSION = 2 as const;
+
+/** 1-indexed closed line interval: [start, end] where start <= end. */
+export type LineRange = [start: number, end: number];
+
+/** Map of 1-indexed line numbers to alphanumeric line-content hashes. */
+export type LineHashMap = Record<number, string>;
+
+export interface ReadFacet {
+  /**
+   * 1-indexed line ranges delivered to the model. REQUIRED.
+   * `[]` represents an explicit zero-line / 0-byte read (#3652).
+   * Full-file read is represented by `[[1, lineCount]]`.
+   */
+  ranges: LineRange[];
+
+  /**
+   * Delivered raw text starting at ranges[0][0].
+   * Valid ONLY when ranges.length === 1 (single contiguous span).
+   */
+  content?: string;
+
+  /**
+   * Precomputed alphanumeric line hashes keyed by absolute 1-indexed line numbers.
+   * Supports multi-span reads. All keys must fall within declared ranges.
+   */
+  lineHashes?: LineHashMap;
+
+  /**
+   * Evidence collection mode:
+   * - "caller" (default): Use content / lineHashes if provided. If neither is provided,
+   *   records coverage-only with NO hashes (no disk reads performed).
+   * - "disk": Bridge synchronously disk-reads and hashes the declared ranges.
+   */
+  evidence?: "caller" | "disk";
+}
+
+export type MutationFacet =
+  | {
+      /** Partial file modification (line replacement / splice). */
+      kind: "edit";
+      /** 1-indexed line ranges modified. Must be non-empty. */
+      ranges: LineRange[];
+      /**
+       * Whether to queue deferred autofix and formatting for agent_settled.
+       * Defaults to true. When true, publishes `pilens:format:queued` on `pi.events`
+       * for newly-queued files (resolving the v1 event drop in mutation-bridge).
+       * Set to false to suppress both queueing and event emission.
+       */
+      deferAutofix?: boolean;
+      importsChanged?: boolean;
+    }
+  | {
+      /** Whole-file authorship (creation or complete replacement). */
+      kind: "write";
+      // The authored bytes are not part of v2 yet: binding creation read
+      // evidence from them is #3524's design (G9), and the field had no
+      // consumer (#4145 review F4).
+      /**
+       * Whether to queue deferred autofix and formatting for agent_settled.
+       * Defaults to true. When true, publishes `pilens:format:queued` on `pi.events`
+       * for newly-queued files. Set to false to suppress both queueing and event emission.
+       */
+      deferAutofix?: boolean;
+      importsChanged?: boolean;
+    }
+  | {
+      /**
+       * Lifecycle deletion: removes file from read records, writtenThisSession,
+       * and knownPathIndex, and notifies LSP DidClose / FileChangeType.Deleted (3).
+       * Mutually exclusive with `read`. Never calls recordWritten and emits no change-log receipt.
+       * Requires file to no longer exist on disk at the moment of recording.
+       */
+      kind: "delete";
+    };
+
+export interface BridgeEntry {
+  /**
+   * Path to the file. Non-empty string.
+   * Preserves caller's raw display path verbatim (matching v1 read-bridge.ts:137-139
+   * and mutation-bridge.ts:322). Scope check runs deps.isRecordable(filePath) directly
+   * on the input string without pre-resolving; internal map keying is handled downstream
+   * via normalizeFilePath / normalizeEphemeralMapKey.
+   */
+  filePath: string;
+
+  /** Optional caller identity for logging and telemetry (e.g. "my-tool"). */
+  consumer?: string;
+
+  /** Mutation facet (at most one). */
+  mutate?: MutationFacet;
+
+  /** Read facet (at most one). Mutually exclusive with mutate.kind: "delete". */
+  read?: ReadFacet;
+}
+
+export type RecordReason =
+  | "malformed"
+  | "out-of-scope"
+  | "ignored"
+  | "no-read-guard"
+  | "stale-lineage"
+  | "bookkeeping-error";
+
+export type RecordOutcome =
+  | { accepted: true }
+  | { accepted: false; reason: RecordReason };
+
+export interface RecordResult {
+  read?: RecordOutcome;
+  mutate?: RecordOutcome;
+}
+
+export interface PiLensIOBridge {
+  readonly version: 2;
+  /**
+   * Synchronously records file I/O operations.
+   * Atomic: executes mutate before read.
+   * Evaluates per-facet scope and #2465 flag gates.
+   * Never throws.
+   */
+  record(entry: BridgeEntry): RecordResult;
+}
+
+/** Convenience accessor performing symbol lookup + version === 2 check. */
+export function getIOBridge(): PiLensIOBridge | undefined;
+```
+
+---
+
+## 4. Keel Architectural Review
+
+| Keel Dimension | Concern | Current Design / Trap | Defect / Risk | Proposed Normative Rule | Justification |
+|---|---|---|---|---|---|
+| **Authority** | Path Normalization (§3, F1) | Pre-resolving `filePath` against `deps.getProjectRoot()` at the bridge entry. | Clobbers the caller's raw display path and creates key divergence if resolution semantics drift from `ReadGuard.key()` / `normalizeFilePath`. Violates AGENTS Shape #1 and display-path preservation. | `filePath` MUST be a non-empty string (`typeof filePath === "string" && filePath.length > 0`). Evaluated via `deps.isRecordable(filePath)` directly. The bridge NEVER pre-resolves or clobbers `filePath`. Internal canonicalization and map keying remain strictly encapsulated in downstream owners (`ReadGuard.key()` via `normalizeFilePath` and `normalizeEphemeralMapKey`). | Preserves exact v1 shim parity (`read-bridge.ts:137-139`, `mutation-bridge.ts:322`), preserves original caller display paths, and prevents divergent path keys. |
+| **Negative Path** | Invariant Conflict (§5) | `mutate: { kind: "delete" }` combined with `read`. | Contradictory state: deleting a file while binding a read on it creates a zombie read record on an absent file. | Validation strictly rejects `mutate.kind === "delete" && read !== undefined` with `{ accepted: false, reason: "malformed" }` for both facets. | Preserves invariant closure: an absent file has no read coverage. |
+| **Negative Path** | Contiguous Span Bounds (§5) | `content` passed with `ranges.length !== 1`. | Unclear line mapping if multiple disjoint ranges are passed with one text buffer. | If `content !== undefined`, require `ranges.length === 1`. If `ranges.length === 0`, `content` must be omitted or `""`. Else reject with `"malformed"`. | Enforces D7 deterministically; eliminates semantic ambiguity. |
+| **Negative Path** | Disk Failure in "disk" mode (§5) | `evidence: "disk"` on unreadable or deleted file. | Synchronous `fs.readFileSync` could throw an uncaught exception, crashing the host. | Disk reads in `"disk"` mode wrapped in try/catch. On failure, return `read: { accepted: false, reason: "bookkeeping-error" }`. | Preserves D9 (never throws). |
+| **Negative Path** | Delete Confirmation & Seam (F3) | Fabricating a change-log receipt, omitting enclosing flag gates (!no-read-guard, !no-lsp), or misordering confirmation gates. | Emitting LSP notifications when no-lsp is active (regression against v1 tool-result), or leaving zombie records in readGuard.reads when files are deleted on disk. | Wrapped by the enclosing `!getFlag("no-read-guard")` gate, followed by the 4 confirmed-delete gates in production order, shared with the native bash path (`judgeConfirmedDelete`, `clients/confirmed-delete.ts`): (1) `isExternalOrVendorFile` -> `"out-of-scope"`; (2) `isPathIgnoredByProject` -> `"ignored"`; (3) `hasKnownPath`: an untracked path that is absent returns `{ accepted: true }` without notifying LSP, and one still on disk returns `bookkeeping-error`; (4) `existsSync` confirm: a tracked file still on disk returns `{ accepted: false, reason: "bookkeeping-error" }` (v2 refinement; the bash path skips it). Action: `forgetPath(filePath)` and, unless `no-lsp`, `notifyExternalFileChange(filePath, 3)`; `no-lsp` suppresses only the notification. Bypasses `recordWritten` and emits NO change-log receipt. | Aligns with tool-result delete lifecycle and flags; refines disk-still-exists into explicit bookkeeping-error; closes zombie-record leaks without fabricated receipts. |
+| **State & Timing** | Lineage / Branch Fence (§3, §5) | Delayed write arriving after session `/tree` or shutdown. | Stale write accepted across epoch boundary, corrupting branch turn state (#3620). | `mutate` validates `runtime.readGuard.currentBranchEpoch`. If branch changed or lineage retired, call `recordDroppedRead` (`clients/session-scope.ts:281-301`, emitting `session-scope-read-dropped` at `clients/session-scope.ts:297`) and return `mutate: { accepted: false, reason: "stale-lineage" }`. If epoch is malformed, call `recordDegradationOnce` (`clients/mutation-bridge.ts:264`, emitting `mutation-bridge-invalid-branch-epoch`). | Preserves TLA+ `session-lifecycle` model and degradation accounting. |
+| **Boundaries** | Flag & Scope Gating (§4) | Collapsing `isRecordable` into a single combined check. | If `no-read-guard` is set, a single gate drops mutation turn-state and change logs (#2465). | Gating is strictly per-facet: `read` gates on `!noReadGuard && isRecordable`; `mutate` gates on `isRecordable`; read-guard write stamp gates on `!noReadGuard`. | Preserves independent accountability of turn-state vs read-guard. |
+| **Retirement** | Legacy Shims & First-Wins (§8) | Old extensions calling `read-bridge` or `mutation-bridge`. | In fresh processes, mounts v1 shims delegating to `ioBridge.record()`. If a dirty process already mounted legacy v1, first-wins retains incumbent. | Mount shims for `Symbol.for("pi-lens:read-bridge")` and `Symbol.for("pi-lens:mutation-bridge")` delegating to `ioBridge.record()`. Document first-wins behavior. | Zero-friction backward compatibility. |
+| **Observability** | Pull-Only Observability (Shape #31, F5) | Unobservable drops or citing non-existent degradation IDs. | Blind spots in monitors and analyzers; silent drops violate Shape #31. | State exact sinks with literal citations: (1) Read log provenance: v1 shim sets `source: "bridge:<consumer>"` (`clients/read-bridge.ts:207`); v2 native sets `source: "io-bridge:<consumer>"` (`[NEW]` in `clients/io-bridge.ts:NEW`, matching `ReadRecord.source` type at `clients/read-guard.ts:55`), written to `read-guard.log`; (2) `turn-state.json` via `deps.getCacheManager().addModifiedRange` (`clients/mutation-bridge.ts:382`); (3) Change-log receipt via `runtime.recordProjectMutation` (`clients/mutation-bridge.ts:393`, edit/write only); (4) Stale lineage write: `session-scope-read-dropped` (`clients/session-scope.ts:297`); (5) Foreign epoch: `mutation-bridge-invalid-branch-epoch` (`clients/mutation-bridge.ts:264`); (6) [NEW] Bridge-level drop telemetry: declare NEW `DegradationKind` union members in `clients/degradation-ledger.ts:40+`: `"io-bridge-read-dropped"` and `"io-bridge-mutate-dropped"`. Caller-synchronous outcome is also immediately returned in `RecordResult`. | Total observability across existing and new streams; fully verifiable by automated tests. |
+| **Side Channels** | Event Bus Parity (`pi.events`) | `mutation-bridge.ts:431` calls `runtime.deferMutation` without calling `publishFormatQueued`. | Tools listening on `pi.events` for `pilens:format:queued` never receive notice when mutations are recorded through the bridge, causing unexpected formatting at `agent_settled` to invalidate in-process line leases and anchors mid-session (AGENTS Shape #5; refs Rianico/pi-better-edit#32). | When `mutate` queues deferred format/autofix (`deferAutofix !== false`), `io-bridge` MUST invoke `publishFormatQueued` (`clients/format-events-publish.ts:187`) for newly-queued files. Passing `deferAutofix: false` suppresses both queueing and bus emission. | Closes the side-channel drop between native tool results and bridge mutations; provides deterministic warning before `agent_settled` rewrites. |
+
+---
+
+## 5. AI Engineering & Usability Review
+
+### 1. One-Page Learnability
+The interface is compact, strongly typed, and self-documenting. The four operations (`read`, `edit`, `write`, `delete`) map directly to the developer's mental model.
+
+### 2. Ordered Producer Guide
+Producers follow a clean 3-step lifecycle:
+```typescript
+// 1. Discover
+const bridge = getIOBridge();
+if (!bridge) return; // Bridge absent or unsupported version
+
+// 2. Formulate Entry (e.g. Hashline Edit + Preview)
+const result = bridge.record({
+  filePath: "src/app.ts", // relative or absolute string preserved
+  consumer: "my-tool",
+  mutate: {
+    kind: "edit",
+    ranges: [[12, 15]],
+  },
+  read: {
+    ranges: [[8, 25]],
+    content: previewText, // raw lines 8-25
+  },
+});
+
+// 3. Inspect Result
+if (!result.mutate?.accepted) countDrop("mutate", result.mutate?.reason);
+if (!result.read?.accepted) countDrop("read", result.read?.reason);
+```
+
+### 3. D5 Evidence Disambiguation
+- **Coverage-Only (Default)**: Passing `read: { ranges: [[10, 20]] }` without `content` or `lineHashes` credits lines 10–20 in `ReadGuard` coverage math, but does **not** read disk or bind line hashes. If lines 10–20 are modified externally, `FileTime` flags staleness and blocks the next edit.
+- **In-Memory Hash Evidence**: Passing `content` (or `lineHashes`) hashes the text in memory via `deliveredLineEvidence(text, offset)` and populates `lineHashes`. If the file is modified externally but lines 10–20 remain intact, `canIgnoreStalenessByHashes` allows the next edit without blocking.
+- **Disk Evidence (`evidence: "disk"`)**: Explicitly requests pi-lens to read the file from disk and compute line hashes.
+
+### 4. Full-File Read vs Content Binding (F7 Clarification)
+For a whole-file read `ranges: [[1, lineCount]]`, passing `content` derives in-memory line hashes for lines $1 \dots lineCount$. It does **not** synthesize a whole-file `contentBinding` (which binds `mtime` and `sha256` from disk). In `evidence: "caller"` mode, `contentBinding` is omitted, cleanly avoiding the #3652 false-block hazard.
+
+### 5. Producer Footguns & Safeguards
+- **Footgun: 0-indexed line numbers**: Bridge requires 1-indexed line numbers (`[1, 10]`). Ranges with $start < 1$ or $start > end$ are deterministically rejected as `"malformed"`.
+- **Footgun: Diff markers in `content`**: If a tool passes diff output (`+const x = 1`) instead of raw file lines, line hashes will not match on-disk bytes. Docs prominently warn: *`content` must be raw file text, never diff hunks*.
+- **Footgun: Delete followed by edit**: Deleting a file clears read coverage. Re-creating a file must be submitted as `mutate: { kind: "write" }`.
+- **Footgun: Deleting a file that still exists on disk**: If a caller calls `mutate: { kind: "delete" }` before removing the file from the filesystem, `nodeFs.existsSync(filePath)` fails the confirm gate and returns `{ accepted: false, reason: "bookkeeping-error" }`. The on-disk deletion must precede or occur synchronously with the bridge call.
+
+---
+
+## 6. Verification Plan
+
+### A. Unit Tests (`tests/clients/io-bridge.test.ts`)
+- **Facet Validation Matrix**: Exhaustive testing of invalid inputs returning `"malformed"`:
+  - Empty path string `""`.
+  - Zero-indexed ranges (`[0, 10]`), inverted ranges (`[10, 5]`), non-integer ranges.
+  - Multi-range with `content` (`ranges: [[1, 5], [10, 15]]` + `content`).
+  - `delete` combined with `read`.
+  - `lineHashes` with out-of-range keys (e.g. key `30` when range is `[1, 10]`).
+- **Path Parity & Display Preservation Matrix (F1)**:
+  - Red-before-green witness: pass a relative path (`"src/app.ts"`) through:
+    1. v1 shim `recordRead`: verify `deps.isRecordable("src/app.ts")` called; verify `ReadRecord.filePath === "src/app.ts"`; verify `ReadGuard.key("src/app.ts")` normalization.
+    2. v1 shim `recordMutation`: verify `deps.isRecordable("src/app.ts")` called; verify `addModifiedRange` called with `"src/app.ts"`.
+    3. v2 bridge `record`: verify identical outcomes, with display path preserved verbatim and no clobbering.
+- **Scope & Flag Gating Matrix (#2465)**:
+  - Out-of-project paths return `{ accepted: false, reason: "out-of-scope" }`.
+  - `no-read-guard` flag active: `read` returns `{ accepted: false, reason: "no-read-guard" }`; `mutate` returns `{ accepted: true }` but skips `ReadGuard.recordWritten`.
+- **Delete Seam & Flag Gates Matrix (F3)**:
+  - Enclosing flag gates:
+    - `no-read-guard` active: skips read-guard eviction, returns `{ accepted: false, reason: "no-read-guard" }`.
+    - `no-lsp` active: eviction `readGuard.forgetPath` runs, but `notifyExternalFileChange(filePath, 3)` is suppressed.
+  - 4 inner gates in production order (`judgeConfirmedDelete`, `clients/confirmed-delete.ts`, shared with the native bash path):
+    1. External / vendor path (`isExternalOrVendorFile`): returns `{ accepted: false, reason: "out-of-scope" }`.
+    2. Ignored path (`isPathIgnoredByProject`): returns `{ accepted: false, reason: "ignored" }`.
+    3. Untracked path (`!hasKnownPath`): if file absent, returns `{ accepted: true }`; zero LSP notifications sent. If it is still on disk, returns `{ accepted: false, reason: "bookkeeping-error" }`.
+    4. Disk confirm (`nodeFs.existsSync`): if file still exists on disk, returns `{ accepted: false, reason: "bookkeeping-error" }`.
+  - Confirmed delete on tracked path: calls `forgetPath(filePath)` and `notifyExternalFileChange(filePath, 3)`. Asserts NO `recordProjectMutation` or `addModifiedRange` invoked.
+- **Observability & Degradation Ledger Matrix (F5)**:
+  - Telemetry witness: trigger bridge drop on read and mutate; flush `latency.log` (via `getGlobalPiLensLogDir()` sink) and read back records, asserting:
+    - `kind: "io-bridge-read-dropped"`, `subject: "${consumer}:${reason}"`.
+    - `kind: "io-bridge-mutate-dropped"`, `subject: "${consumer}:${reason}"`.
+  - Stale lineage write: asserts emission of `session-scope-read-dropped` (`clients/session-scope.ts:297`).
+  - Malformed branch epoch: asserts emission of `mutation-bridge-invalid-branch-epoch` (`clients/mutation-bridge.ts:264`).
+
+### B. Seam Integration Probes & Red-Before-Green Witnesses
+
+#### 1. Witness for Write-Before-Read Atomic Ordering
+- **Production Seam**: `ReadGuard.checkEdit` -> `ioBridge.record(...)` -> `ReadGuard.checkEdit`.
+- **Probe Scenario**: An edit occurs to a file that was previously read. The producer submits a compound entry:
+  ```typescript
+  ioBridge.record({
+    filePath,
+    mutate: { kind: "edit", ranges: [[10, 15]] },
+    read: { ranges: [[5, 25]], content: postMutationContext }
+  });
+  ```
+- **Red Witness (Order Inversion)**: The order does not change an immediate `checkEdit`: the #4145 probe found the same verdict for every order, and there is no `file_time_stale` reason. What it changes is `consumedReadFiles`. `recordWritten` marks a file's existing reads consumed, and `recordRead` makes them outstanding again. Read-then-mutate therefore leaves the preview read consumed, and a consumed read is evictable on idle and under the file cap: after the idle window the read is gone and the next edit blocks as never read.
+- **Green Witness**: With `mutate` running before `read`, the preview read is the last word and stays outstanding, so idle eviction cannot drop it. `tests/clients/io-bridge.test.ts` "keeps the compound call's preview read outstanding through idle eviction" pins this; swapping the facets reds it (`expected [] to have a length of 1`).
+
+#### 2. Witness for D5 Coverage-Only Default
+- **Production Seam**: `ioBridge.record` -> `readGuard.reads.get(filePath)`.
+- **Probe Scenario**: Record a read with `read: { ranges: [[1, 10]] }` without `content` or `lineHashes`.
+- **Red Witness (Unwanted Disk Hashing)**: If the bridge silently read disk, `storedRecord.lineHashes` would be populated.
+- **Green Witness**: `storedRecord.lineHashes` is strictly `undefined`. Zero disk reads occur.
+
+#### 3. Witness for Delete Lifecycle Eviction (F3)
+- **Production Seam**: `ioBridge.record` -> `readGuard.hasKnownPath` + `notifyExternalFileChange`.
+- **Probe Scenario**: A file with existing read records is deleted via `mutate: { kind: "delete" }` after on-disk removal.
+- **Witness**: `readGuard.hasKnownPath(filePath) === false`, `readGuard.reads.has(filePath) === false`, `writtenThisSession.has(filePath) === false`, and mock LSP receives FileChangeType 3. Asserts NO change log receipt was appended.
+
+---
+
+## 7. Issues & Status
+
+- **Open Defects / Ambiguities**: **None**.
+  - **F1 (Path Resolution & Display Parity)**: Fully resolved. `filePath` non-empty string preserved verbatim without re-resolving or clobbering at bridge layer; unit test matrix verifies v1 parity.
+  - **F3 (Delete Seam & Flag Gates)**: Fully resolved. The enclosing `!getFlag("no-read-guard")` gate, then the 4 confirmed-delete gates shared with the native bash path (`clients/confirmed-delete.ts`), followed by `forgetPath` and, unless `no-lsp`, `notifyExternalFileChange`. Dropped fabricated change-log receipt.
+  - **F5 (Observability & Exact Citations)**: Fully resolved. Read log provenance uses `bridge:<consumer>` for v1 shim (`clients/read-bridge.ts:207`) and `io-bridge:<consumer>` as `[NEW]` for v2 native (`ReadRecord.source` type at `clients/read-guard.ts:55`). Re-uses existing `session-scope-read-dropped` (`clients/session-scope.ts:297`) and `mutation-bridge-invalid-branch-epoch` (`clients/mutation-bridge.ts:264`); explicitly declares `[NEW]` `DegradationKind` union members `"io-bridge-read-dropped"` and `"io-bridge-mutate-dropped"` in `clients/degradation-ledger.ts:40+` with test reading `latency.log`.
+- **Maintainer Decisions**: the maintainer accepted this design on #4145 (2026-10-08): the D5/D6 evidence model, the public field set, relative paths out of scope, and a tracked `docs/rfcs/`.

package/docs/servercapabilities.md

@@ -6,58 +6,64 @@ server's `initialize` handshake. Generated by `node scripts/server-capabilities.
 absent on the generating host are listed under *Unavailable* — run in a
 provisioned environment (the nightly) to capture those rows.
 
-_Last generated: 2026-09-23 on linux; 37 servers captured, 9 unavailable._
+_Last generated: 2026-10-07 on linux; 40 servers captured, 8 unavailable._
 
 ## Diagnostic mode + navigation/edit operations
 
-Legend: ✓ advertised, · not. **mode** = document diagnostics (`pull` = `textDocument/diagnostic`, else push-only); **ws-pull** = advertises `workspace/diagnostic` (one project-wide pull — the #387 Item 2 fast path). **def**=definition, **tDef**=typeDefinition, **decl**=declaration, **ref**=references, **hov**=hover, **sig**=signatureHelp, **dSym**=documentSymbol, **wSym**=workspaceSymbol, **cAct**=codeAction, **rnm**=rename, **impl**=implementation, **cHir**=callHierarchy; **cmds** = executeCommand allowlist size.
+Legend: ✓ advertised, · not. **mode** = document diagnostics (`pull` = `textDocument/diagnostic`, else push-only); **ws-pull** = advertises `workspace/diagnostic` (one project-wide pull — the #387 Item 2 fast path); **save** = `textDocumentSync.save` (#3407): `save` gets `textDocument/didSave`, `save+text` gets it with the document text (`includeText`), · declares none, ? not captured. **def**=definition, **tDef**=typeDefinition, **decl**=declaration, **ref**=references, **hov**=hover, **sig**=signatureHelp, **dSym**=documentSymbol, **wSym**=workspaceSymbol, **cAct**=codeAction, **rnm**=rename, **impl**=implementation, **cHir**=callHierarchy; **cmds** = executeCommand allowlist size.
 
-| server | mode | ws-pull | def | tDef | decl | ref | hov | sig | dSym | wSym | cAct | rnm | impl | cHir | cmds |
-|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
-| ast-grep | push-only | · | · | · | · | · | ✓ | · | · | · | ✓ | · | · | · | 1 |
-| bash | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
-| clojure | push-only | · | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 62 |
-| cpp | push-only | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 3 |
-| csharp | pull | ✓ | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
-| css | pull | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
-| cue | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 1 |
-| dart | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 18 |
-| deno | pull | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 2 |
-| docker | push-only | · | ✓ | · | · | · | ✓ | ✓ | ✓ | · | · | ✓ | · | · | 0 |
-| emmylua | pull | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | · | · | 4 |
-| expert | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | · | · | 2 |
-| fish | push-only | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | 22 |
-| fsharp | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
-| gleam | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | · | 0 |
-| go | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 47 |
-| html | pull | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | · | · | ✓ | · | · | 0 |
-| json | pull | · | · | · | · | · | ✓ | · | ✓ | · | ✓ | · | · | · | 0 |
-| lua | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | 6 |
-| marksman | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
-| opengrep | push-only | · | · | · | · | · | ✓ | · | · | · | ✓ | · | · | · | 2 |
-| php | push-only | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | · | · | 0 |
-| powershell | push-only | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
-| prisma | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
-| python | push-only | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | 0 |
-| python-jedi | push-only | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
-| ruby | pull | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
-| rust | pull | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
-| svelte | pull | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
-| terraform | push-only | · | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | · | 7 |
-| tinymist | push-only | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 29 |
-| toml | push-only | · | · | · | · | · | ✓ | · | ✓ | · | · | ✓ | · | · | 0 |
-| typescript | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | 8 |
-| typos | push-only | · | · | · | · | · | · | · | · | · | ✓ | · | · | · | 1 |
-| vue | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
-| yaml | push-only | · | ✓ | · | · | · | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 1 |
-| zig | push-only | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
-| zizmor | push-only | · | · | · | · | · | · | · | · | · | · | · | · | · | 0 |
+| server | mode | ws-pull | save | def | tDef | decl | ref | hov | sig | dSym | wSym | cAct | rnm | impl | cHir | cmds |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| ast-grep | push-only | · | · | · | · | · | · | ✓ | · | · | · | ✓ | · | · | · | 1 |
+| bash | push-only | · | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
+| clojure | push-only | · | save+text | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 62 |
+| cmake | push-only | · | save | · | · | · | · | ✓ | · | · | · | · | · | · | · | 0 |
+| cpp | push-only | · | save | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 3 |
+| csharp | pull | ✓ | save+text | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
+| css | pull | · | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
+| cue | push-only | · | save | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 1 |
+| dart | push-only | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 18 |
+| deno | pull | · | save | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 2 |
+| docker | push-only | · | · | ✓ | · | · | · | ✓ | ✓ | ✓ | · | · | ✓ | · | · | 0 |
+| emmylua | pull | · | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | · | · | 4 |
+| expert | push-only | · | save | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | · | · | 2 |
+| fish | push-only | · | save+text | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | 23 |
+| fsharp | push-only | · | save+text | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
+| gleam | push-only | · | save | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | · | ✓ | ✓ | · | · | 0 |
+| go | push-only | · | save | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 47 |
+| html | pull | · | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | · | · | ✓ | · | · | 0 |
+| json | pull | · | · | · | · | · | · | ✓ | · | ✓ | · | ✓ | · | · | · | 0 |
+| kotlin | push-only | · | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 1 |
+| lua | push-only | · | save | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | 6 |
+| marksman | push-only | · | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
+| opengrep | push-only | · | save | · | · | · | · | ✓ | · | · | · | ✓ | · | · | · | 2 |
+| php | push-only | · | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | · | · | 0 |
+| powershell | push-only | · | save+text | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
+| prisma | push-only | · | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
+| python | push-only | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | ✓ | 0 |
+| python-jedi | push-only | · | save | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
+| ruby | pull | · | · | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
+| rust | pull | · | save | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
+| svelte | pull | · | save | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
+| terraform | push-only | · | save | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | · | 7 |
+| tinymist | push-only | · | save | ✓ | · | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 29 |
+| toml | push-only | · | · | · | · | · | · | ✓ | · | ✓ | · | · | ✓ | · | · | 0 |
+| typescript | push-only | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | 8 |
+| typos | push-only | · | · | · | · | · | · | · | · | · | · | ✓ | · | · | · | 1 |
+| vue | push-only | · | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
+| yaml | push-only | · | · | ✓ | · | · | · | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 1 |
+| zig | push-only | · | save | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | · | · | 0 |
+| zizmor | push-only | · | · | · | · | · | · | · | · | · | · | · | · | · | · | 0 |
 
 ## Raw advertised capability keys
 
+Top-level keys of each server's `ServerCapabilities` — the full advertised
+surface, including providers pi-lens does not yet consume.
+
 - **ast-grep**: codeActionProvider, executeCommandProvider, hoverProvider, textDocumentSync
 - **bash**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentSymbolProvider, hoverProvider, referencesProvider, renameProvider, textDocumentSync, workspaceSymbolProvider
 - **clojure**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, declarationProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, experimental, foldingRangeProvider, hoverProvider, implementationProvider, linkedEditingRangeProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
+- **cmake**: completionProvider, executeCommandProvider, hoverProvider, positionEncoding, textDocumentSync, workspace
 - **cpp**: astProvider, callHierarchyProvider, clangdInlayHintsProvider, codeActionProvider, compilationDatabase, completionProvider, declarationProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, foldingRangeProvider, hoverProvider, implementationProvider, inactiveRegionsProvider, inlayHintProvider, memoryUsageProvider, positionEncoding, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, standardTypeHierarchyProvider, textDocumentSync, typeDefinitionProvider, typeHierarchyProvider, workspaceSymbolProvider
 - **csharp**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, definitionProvider, diagnosticProvider, documentFormattingProvider, documentHighlightProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, referencesProvider, renameProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, typeHierarchyProvider, workspace, workspaceSymbolProvider
 - **css**: codeActionProvider, colorProvider, definitionProvider, diagnosticProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, referencesProvider, renameProvider, selectionRangeProvider, textDocumentSync
@@ -73,6 +79,7 @@ Legend: ✓ advertised, · not. **mode** = document diagnostics (`pull` = `textD
 - **go**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentSymbolProvider, executeCommandProvider, experimental, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, typeHierarchyProvider, workspace, workspaceSymbolProvider
 - **html**: colorProvider, definitionProvider, diagnosticProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, linkedEditingRangeProvider, referencesProvider, renameProvider, selectionRangeProvider, signatureHelpProvider, textDocumentSync
 - **json**: codeActionProvider, colorProvider, diagnosticProvider, documentFormattingProvider, documentLinkProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, selectionRangeProvider, textDocumentSync
+- **kotlin**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, inlayHintProvider, referencesProvider, renameProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
 - **lua**: codeActionProvider, codeLensProvider, colorProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, offsetEncoding, referencesProvider, renameProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace, workspaceSymbolProvider
 - **marksman**: codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, referencesProvider, renameProvider, semanticTokensProvider, textDocumentSync, workspace, workspaceSymbolProvider
 - **opengrep**: codeActionProvider, executeCommandProvider, hoverProvider, textDocumentSync, workspace
@@ -93,9 +100,6 @@ Legend: ✓ advertised, · not. **mode** = document diagnostics (`pull` = `textD
 - **yaml**: codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentLinkProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, foldingRangeProvider, hoverProvider, renameProvider, selectionRangeProvider, textDocumentSync, workspace
 - **zig**: codeActionProvider, colorProvider, completionProvider, declarationProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, positionEncoding, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace, workspaceSymbolProvider
 - **zizmor**: textDocumentSync
-Top-level keys of each server's `ServerCapabilities` — the full advertised
-surface, including providers pi-lens does not yet consume.
-
 
 ## Advertised executeCommand allowlists
 
@@ -107,8 +111,9 @@ surface, including providers pi-lens does not yet consume.
 - **deno** (2): deno.cache, deno.reloadImportRegistries
 - **emmylua** (4): fake.applyEdit, fake.applyEditDeferred, fake.doThing, fake.releaseDeferredApplyEdit
 - **expert** (2): Reindex, connectionDetails
-- **fish** (22): fish-lsp.checkHealth, fish-lsp.createTheme, fish-lsp.execute, fish-lsp.executeBuffer, fish-lsp.executeLine, fish-lsp.executeRange, fish-lsp.fixAll, fish-lsp.generateEnvVariables, fish-lsp.showEnvVariables, fish-lsp.showInfo, fish-lsp.showReferences, fish-lsp.showStatusDocs, fish-lsp.showWorkspaceMessage, fish-lsp.toggleSingleWorkspaceSupport, fish-lsp.updateWorkspace, quickfix.delete, quickfix.disable, quickfix.fix, quickfix.fixAll, refactor.extract, refactor.rewrite, source.rename
+- **fish** (23): fish-lsp.checkHealth, fish-lsp.createTheme, fish-lsp.execute, fish-lsp.executeBuffer, fish-lsp.executeLine, fish-lsp.executeRange, fish-lsp.fixAll, fish-lsp.generateEnvVariables, fish-lsp.selectQuickFixPosition, fish-lsp.showEnvVariables, fish-lsp.showInfo, fish-lsp.showReferences, fish-lsp.showStatusDocs, fish-lsp.showWorkspaceMessage, fish-lsp.toggleSingleWorkspaceSupport, fish-lsp.updateWorkspace, quickfix.delete, quickfix.disable, quickfix.fix, quickfix.fixAll, refactor.extract, refactor.rewrite, source.rename
 - **go** (47): gopls.add_dependency, gopls.add_import, gopls.add_telemetry_counters, gopls.add_test, gopls.apply_fix, gopls.assembly, gopls.change_signature, gopls.check_upgrades, gopls.client_open_url, gopls.diagnose_files, gopls.doc, gopls.edit_go_directive, gopls.extract_to_new_file, gopls.fetch_vulncheck_result, gopls.free_symbols, gopls.gc_details, gopls.generate, gopls.go_get_package, gopls.implement_interface, gopls.list_imports, gopls.list_known_packages, gopls.lsp, gopls.maybe_prompt_for_telemetry, gopls.mem_stats, gopls.modify_tags, gopls.modules, gopls.move_type, gopls.package_symbols, gopls.packages, gopls.regenerate_cgo, gopls.remove_dependency, gopls.reset_go_mod_diagnostics, gopls.run_go_work_command, gopls.run_govulncheck, gopls.run_tests, gopls.scan_imports, gopls.split_package, gopls.start_debugging, gopls.start_profile, gopls.stop_profile, …
+- **kotlin** (1): convertJavaToKotlin
 - **lua** (6): lua.autoRequire, lua.getConfig, lua.jsonToLua, lua.removeSpace, lua.setConfig, lua.solve
 - **opengrep** (2): semgrep/autofix, semgrep/ignore
 - **terraform** (7): terraform-ls.module.callers, terraform-ls.module.calls, terraform-ls.module.providers, terraform-ls.module.terraform, terraform-ls.rootmodules, terraform-ls.terraform.init, terraform-ls.terraform.validate
@@ -122,12 +127,11 @@ surface, including providers pi-lens does not yet consume.
 Toolchain/binary not installed here, so capabilities weren't captured
 (many are the toolchain-gated family tracked in #241):
 
-- cmake-language-server
+- elixir-ls
 - haskell-language-server
 - jdtls
 - jdtls + lombok javaagent
-- kotlin-language-server
 - nixd
 - ocamllsp
-- rust-analyzer
+- shuck
 - sourcekit-lsp

package/docs/settings.md

@@ -87,6 +87,7 @@ column is the effective behavior when nothing is set.
 | `--lens-compact-tool-line` | `ui.compactToolLine` | global | **off** (two-row tool rendering) |
 | `--lens-compact-lsp-status` | `ui.compactLspStatus` | global | **off** (footer lists the active server names) |
 | `--lens-hide-lsp-status` | `ui.hideLspStatus` | global | **off** (footer publishes the `pi-lens-lsp` status; outranks `ui.compactLspStatus` when both are set) |
+| `--lens-compact-widget` | `ui.compactWidget` | global | **off** (widget stacks file rows, suppressed count and blocker details below its summary header; **on** renders only that header — languages + totals, plus the `LSP↑` chip while servers are spawning) |
 | `--no-lazy-tools` | `tools.lazy` | global | lazy tools **on** (five situational tools start inactive) |
 | `--no-tool=<name>` | `tools.<name>.enabled` | project | every lens tool **on** |
 | `--lens-turn-end-madge` | `turnEnd.madge.enabled` | global | **off** (madge runs at session start, not per turn) |

package/docs/usage.md

@@ -114,6 +114,7 @@ pi --lens-turn-summary   # Persist a per-turn summary of diagnostics, autofixes,
 pi --lens-compact-tool-line   # Render tool results as one compact, theme-aware line (closes #1327)
 pi --lens-compact-lsp-status  # Collapse the footer LSP status to one state glyph instead of the server names (refs #3099)
 pi --lens-hide-lsp-status     # Publish no pi-lens-lsp footer status at all, so a status-rendering host stops showing the key (closes #3099)
+pi --lens-compact-widget      # Render the widget as one summary line (languages + totals, LSP↑ chip while servers spawn) with no file rows or blocker details (refs #3959)
 pi --no-lazy-tools       # Keep every pi-lens tool active instead of activating the situational ones on demand
 pi --lens-turn-end-madge # Run the madge circular-dependency check at every turn end, not just at session start
 pi --no-knip             # Disable the knip session-start analyzer
@@ -199,4 +200,7 @@ turn-end is skipped, not faked: one line on stderr and nothing on stdout.
 - Check `~/.pi-lens/sessionstart.log`, `~/.pi-lens/latency.log`, and
   `~/.pi-lens/cascade.log` for lifecycle/performance/debug traces.
 - For live tool validation, use `node scripts/smoke-tools.mjs` with the relevant
-  `--lsp`, `--format`, or `--autofix` layer.
+  `--lsp`, `--format`, or `--autofix` layer. `--resolution` checks, without
+  installing or spawning anything, that the resolvers find project-local tools in
+  `.venv/bin`, `vendor/bin` and `node_modules/.bin` (it runs nightly in
+  tool-smoke).

package/grammars/tree-sitter-bash.wasm.json

@@ -1,5 +1,5 @@
 {
-  "npmPackage": "tree-sitter-wasms",
-  "version": "0.1.13",
-  "sha256": "sha256:807dcdb1380a59befb112ed8fbd3d3872c7fadaf5903a769282b50973b30696d"
+  "npmPackage": "tree-sitter-bash",
+  "version": "0.25.1",
+  "sha256": "sha256:8292919c88a0f7d3fb31d0cd0253ca5a9531bc1ede82b0537f2c63dd8abe6a7a"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "4.3.0",
+	"version": "4.4.0",
 	"type": "module",
 	"description": "Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo",
 	"repository": {
@@ -17,7 +17,7 @@
 		"build": "tsc --project tsconfig.build.json",
 		"build:dist": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && node scripts/build-dist-tsc.mjs tsconfig.dist.json && npm run bundle:dist",
 		"bundle:dist": "node scripts/bundle-dist.mjs",
-		"prepare": "npm run build:dist && node scripts/download-grammars.js --core --dest grammars && node scripts/setup-git-hooks.mjs && node scripts/warm-loader-cache.mjs",
+		"prepare": "npm run build:dist && node scripts/download-grammars.js --core --dest grammars && node scripts/setup-git-hooks.mjs && node scripts/stamp-package-lock.mjs && node scripts/warm-loader-cache.mjs",
 		"prepack": "node scripts/strip-dev-deps-for-pack.mjs --strip",
 		"postpack": "node scripts/strip-dev-deps-for-pack.mjs --restore",
 		"lint": "tsc --project tsconfig.json && npm run lint:js && npm run lint:js:tests",
@@ -40,6 +40,7 @@
 		"check": "node scripts/check-extensions.mjs",
 		"selftest:install": "node scripts/install-selftest.mjs",
 		"check:lockfile": "node scripts/check-lockfile-sync.mjs",
+		"check:allow-scripts": "node scripts/check-allow-scripts.mjs",
 		"preflight": "node scripts/pr-preflight.mjs",
 		"knip": "node scripts/run-knip.mjs",
 		"check:grammars": "node scripts/check-grammar-provenance.mjs",
@@ -48,6 +49,7 @@
 		"audit:rule-catalog": "node scripts/validate-rule-catalog.mjs",
 		"audit:astgrep-rule-pairs": "node scripts/audit-astgrep-rule-pairs.mjs",
 		"astgrep:self-scan": "node scripts/run-astgrep-pi-lens.mjs",
+		"lane:check": "node scripts/lane-check.mjs",
 		"astgrep:self-scan:update-baseline": "node scripts/run-astgrep-pi-lens.mjs --update-baseline",
 		"audit:playground": "node scripts/playground-verify-rule.mjs",
 		"bench:cascade-budget": "node scripts/bench-cascade-budget.mjs",
@@ -55,6 +57,7 @@
 		"logs:smells": "node scripts/analyze-pi-lens-logs.mjs",
 		"complexity": "node scripts/complexity-report.mjs",
 		"changelog:check": "node scripts/rollup-changelog.mjs --check",
+		"contributors:update": "node scripts/update-contributors.mjs",
 		"test:regen": "node scripts/regen-test-baseline.mjs",
 		"changelog:release": "node scripts/changelog-release.mjs",
 		"changelog:extract": "node scripts/changelog-extract.mjs",
@@ -91,7 +94,14 @@
 	},
 	"packageManager": "npm@11.18.0",
 	"files": [
-		"dist/",
+		"dist/index.js",
+		"dist/chunk-*.js",
+		"dist/mcp/cli.js",
+		"dist/mcp/server.js",
+		"dist/mcp/analyze-cli.js",
+		"dist/mcp/worker.js",
+		"dist/workers/",
+		"dist/probes/",
 		"docs/",
 		"grammars/",
 		"vendor/grammars/",
@@ -114,7 +124,7 @@
 		"banner.png"
 	],
 	"dependencies": {
-		"@ast-grep/cli": "^0.45.0",
+		"@ast-grep/cli": "0.45.3",
 		"@ast-grep/napi": "^0.45.0",
 		"js-yaml": "^5.2.2",
 		"minimatch": "^10.2.6",
@@ -123,7 +133,7 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "^0.84.1 || ^0.85.0",
+		"@earendil-works/pi-tui": "*",
 		"typebox": "^1.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -151,8 +161,10 @@
 	},
 	"allowScripts": {
 		"@ast-grep/cli@0.45.3": true,
-		"@google/genai@1.52.0": true,
-		"protobufjs@7.6.5": true
+		"@google/genai@2.21.0": true,
+		"esbuild@0.28.2": true,
+		"fsevents@2.3.3": false,
+		"protobufjs@7.6.6": true
 	},
 	"overrides": {
 		"qs": "^6.15.4"