pi-lens 4.2.1 → 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,76 +6,93 @@ 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-09 on linux; 31 servers captured, 13 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 |
-| csharp | pull | ✓ | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 0 |
-| css | pull | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 0 |
-| cue | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | · | ✓ | ✓ | · | · | 1 |
-| dart | push-only | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 18 |
-| deno | pull | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 2 |
-| docker | push-only | · | ✓ | · | · | · | ✓ | ✓ | ✓ | · | · | ✓ | · | · | 0 |
-| expert | push-only | · | ✓ | · | · | ✓ | ✓ | · | ✓ | ✓ | ✓ | · | · | · | 2 |
-| 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 |
-| 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 |
-| 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
 - **cue**: codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, referencesProvider, renameProvider, textDocumentSync, workspace
 - **dart**: callHierarchyProvider, codeActionProvider, codeLensProvider, colorProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, experimental, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, inlineValueProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, typeHierarchyProvider, workspace, workspaceSymbolProvider
 - **deno**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, definitionProvider, diagnosticProvider, documentFormattingProvider, documentHighlightProvider, documentSymbolProvider, executeCommandProvider, experimental, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, notebookDocumentSync, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace, workspaceSymbolProvider
 - **docker**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, renameProvider, signatureHelpProvider, textDocumentSync
+- **emmylua**: codeActionProvider, definitionProvider, diagnosticProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, referencesProvider, textDocumentSync, workspaceSymbolProvider
 - **expert**: codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentSymbolProvider, executeCommandProvider, experimental, hoverProvider, referencesProvider, textDocumentSync, workspace, workspaceSymbolProvider
+- **fish**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
 - **fsharp**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspaceSymbolProvider
 - **gleam**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, referencesProvider, renameProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace
 - **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
 - **php**: codeActionProvider, completionProvider, declarationProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlineValueProvider, referencesProvider, renameProvider, selectionRangeProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, typeHierarchyProvider, workspace, workspaceSymbolProvider
-- **prisma**: completionProvider, definitionProvider, documentFormattingProvider, documentSymbolProvider, hoverProvider, referencesProvider, renameProvider, textDocumentSync
+- **powershell**: codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, experimental, foldingRangeProvider, hoverProvider, referencesProvider, renameProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
+- **prisma**: codeActionProvider, completionProvider, definitionProvider, documentFormattingProvider, documentSymbolProvider, hoverProvider, referencesProvider, renameProvider, textDocumentSync
 - **python**: callHierarchyProvider, codeActionProvider, completionProvider, declarationProvider, definitionProvider, documentHighlightProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, referencesProvider, renameProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace, workspaceSymbolProvider
 - **python-jedi**: codeActionProvider, completionProvider, declarationProvider, definitionProvider, documentHighlightProvider, documentSymbolProvider, executeCommandProvider, hoverProvider, positionEncoding, referencesProvider, renameProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace, workspaceSymbolProvider
 - **ruby**: codeActionProvider, codeLensProvider, completionProvider, definitionProvider, diagnosticProvider, documentHighlightProvider, documentLinkProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, experimental, foldingRangeProvider, hoverProvider, inlayHintProvider, positionEncoding, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeHierarchyProvider, workspaceSymbolProvider
 - **rust**: callHierarchyProvider, codeActionProvider, codeLensProvider, completionProvider, declarationProvider, definitionProvider, diagnosticProvider, documentFormattingProvider, documentHighlightProvider, documentOnTypeFormattingProvider, documentRangeFormattingProvider, documentSymbolProvider, experimental, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, positionEncoding, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace, workspaceSymbolProvider
 - **svelte**: callHierarchyProvider, codeActionProvider, codeLensProvider, colorProvider, completionProvider, definitionProvider, diagnosticProvider, documentFormattingProvider, documentHighlightProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, linkedEditingRangeProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspaceSymbolProvider
 - **terraform**: codeActionProvider, codeLensProvider, completionProvider, declarationProvider, definitionProvider, documentFormattingProvider, documentLinkProvider, documentSymbolProvider, executeCommandProvider, experimental, hoverProvider, referencesProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
+- **tinymist**: codeActionProvider, codeLensProvider, colorProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentLinkProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, experimental, foldingRangeProvider, hoverProvider, inlayHintProvider, positionEncoding, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, workspace, workspaceSymbolProvider
 - **toml**: completionProvider, documentFormattingProvider, documentLinkProvider, documentSymbolProvider, foldingRangeProvider, hoverProvider, renameProvider, semanticTokensProvider, textDocumentSync, workspace
 - **typescript**: codeActionProvider, codeLensProvider, completionProvider, definitionProvider, documentFormattingProvider, documentHighlightProvider, documentRangeFormattingProvider, documentSymbolProvider, executeCommandProvider, foldingRangeProvider, hoverProvider, implementationProvider, inlayHintProvider, linkedEditingRangeProvider, referencesProvider, renameProvider, selectionRangeProvider, semanticTokensProvider, signatureHelpProvider, textDocumentSync, typeDefinitionProvider, workspace, workspaceSymbolProvider
 - **typos**: codeActionProvider, executeCommandProvider, positionEncoding, textDocumentSync, workspace
@@ -83,23 +100,25 @@ 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
 
 - **ast-grep** (1): ast-grep.applyAllFixes
 - **clojure** (62): add-import-to-namespace, add-missing-import, add-missing-libspec, add-require-suggestion, as-to-refer, backward, backward-barf, backward-select, backward-slurp, change-coll, clean-ns, cond->if-refactor, create-function, create-test, cursor-info, cycle-coll, cycle-keyword-auto-resolve, cycle-privacy, demote-fn, destructure-keys, drag-backward, drag-forward, drag-param-backward, drag-param-forward, expand-let, extract-function, extract-to-def, forward, forward-barf, forward-select, forward-slurp, get-in-all, get-in-less, get-in-more, get-in-none, if->cond-refactor, inline-function, inline-symbol, introduce-let, kill-sexp, …
+- **cpp** (3): clangd.applyFix, clangd.applyRename, clangd.applyTweak
 - **cue** (1): cuelsp.externalvalidate
-- **dart** (18): dart.edit.codeAction.apply, dart.edit.sortMembers, dart.edit.organizeImports, dart.edit.fixAll, dart.edit.fixAllInWorkspace.preview, dart.edit.fixAllInWorkspace, dart.edit.sendWorkspaceEdit, refactor.perform, refactor.validate, dart.logAction, dart.refactor.add_constructor_name, dart.refactor_add.import_prefix, dart.refactor.convert_all_formal_parameters_to_named, dart.refactor.convert_selected_formal_parameters_to_named, dart.refactor.move_selected_formal_parameters_left, dart.refactor.move_top_level_to_file, dart.refactor.remove_constructor_name, dart.refactor.remove_import_prefix
+- **dart** (18): dart.edit.codeAction.apply, dart.edit.fixAll, dart.edit.fixAllInWorkspace, dart.edit.fixAllInWorkspace.preview, dart.edit.organizeImports, dart.edit.sendWorkspaceEdit, dart.edit.sortMembers, dart.logAction, dart.refactor.add_constructor_name, dart.refactor.convert_all_formal_parameters_to_named, dart.refactor.convert_selected_formal_parameters_to_named, dart.refactor.move_selected_formal_parameters_left, dart.refactor.move_top_level_to_file, dart.refactor.remove_constructor_name, dart.refactor.remove_import_prefix, dart.refactor_add.import_prefix, refactor.perform, refactor.validate
 - **deno** (2): deno.cache, deno.reloadImportRegistries
+- **emmylua** (4): fake.applyEdit, fake.applyEditDeferred, fake.doThing, fake.releaseDeferredApplyEdit
 - **expert** (2): Reindex, connectionDetails
+- **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, …
-- **lua** (6): lua.removeSpace, lua.solve, lua.jsonToLua, lua.setConfig, lua.getConfig, lua.autoRequire
-- **opengrep** (2): semgrep/ignore, semgrep/autofix
+- **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
-- **typescript** (8): _typescript.applyRefactoring, _typescript.configurePlugin, _typescript.organizeImports, _typescript.applyRenameFile, _typescript.goToSourceDefinition, _typescript.applyCodeActionCommand, _typescript.applyFixAllCodeAction, typescript.tsserverRequest
+- **tinymist** (29): tinymist.doClearCache, tinymist.doGetTemplateEntry, tinymist.doInitTemplate, tinymist.doKillPreview, tinymist.doStartBrowsingPreview, tinymist.doStartPreview, tinymist.exportAnsiHighlight, tinymist.exportAst, tinymist.exportBundle, tinymist.exportHtml, tinymist.exportMarkdown, tinymist.exportPdf, tinymist.exportPng, tinymist.exportQuery, tinymist.exportSvg, tinymist.exportTeX, tinymist.exportText, tinymist.focusMain, tinymist.getDocumentMetrics, tinymist.getDocumentTrace, tinymist.getResources, tinymist.getServerInfo, tinymist.getWorkspaceLabels, tinymist.interactCodeContext, tinymist.pinMain, tinymist.scrollPreview, tinymist.startDefaultPreview, tinymist.startServerProfiling, tinymist.stopServerProfiling
+- **typescript** (8): _typescript.applyCodeActionCommand, _typescript.applyFixAllCodeAction, _typescript.applyRefactoring, _typescript.applyRenameFile, _typescript.configurePlugin, _typescript.goToSourceDefinition, _typescript.organizeImports, typescript.tsserverRequest
 - **typos** (1): ignore-in-project
 - **yaml** (1): jumpToSchema
 
@@ -108,16 +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):
 
-- @prisma/language-server
-- PowerShell Editor Services (pwsh Start-EditorServices.ps1 -Stdio)
-- clangd
-- cmake-language-server
-- fish-lsp
+- elixir-ls
 - haskell-language-server
 - jdtls
 - jdtls + lombok javaagent
-- kotlin-language-server
 - nixd
 - ocamllsp
-- rust-analyzer
+- shuck
 - sourcekit-lsp

package/docs/settings.md

@@ -29,7 +29,8 @@ contract.
    CI-scoped switches and for the handful of tuning knobs that have no config key.
 2. **CLI flags** (`--no-lsp`, `--immediate-format`, …) — per-session, passed on
    the pi command line.
-3. **Config JSON** — a per-user global file (`~/.pi-lens/config.json`) and an
+3. **Config JSON** — a per-user global file selected by the
+   [global-location table](configuration.md#global-config-location) and an
    optional per-project file (`.pi-lens.json` at the repo root).
 
 Every runtime toggle is settable **both** from the CLI and from `config.json`;
@@ -86,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) |
@@ -108,6 +110,9 @@ tool. The loader `pi_lens_activate_tools` and MCP lifecycle tools
 required by their host protocols and cannot be disabled. Unknown or
 non-disableable names emit `PILENS_CFG_0009`.
 
+When a lower-precedence supported global config file is shadowed by the
+winning file, pi-lens records the notice once with `PILENS_CFG_0010`.
+
 Valid names for `tools.<name>.enabled` include `ast_grep_search`,
 `ast_grep_replace`, `ast_grep_outline`, `lsp_navigation`,
 `lens_diagnostics`, `lens_diagnostic_mark`, `symbol_search`,
@@ -149,9 +154,10 @@ field docs.
 
 ## Global vs project config
 
-### Global — `~/.pi-lens/config.json`
+### Global — winning location
 
-User-level. Applies to **every** project. Honors **all** flag keys from the
+User-level. The file is selected by the [global-location table](configuration.md#global-config-location)
+and applies to **every** project. It honors **all** flag keys from the
 table above plus the non-flag global knobs (`ignore`, `widget.visible`,
 `dispatch.runnerTimeoutFloorMs`, `format.mode`,
 `actionableWarnings.autoFix.maxFixes`). On Windows the path is
@@ -238,6 +244,10 @@ manager, or CI config. The handful you are most likely to reach for:
   review graph) out of the workspace.
 - `PI_LENS_HOME` — relocate the machine-global root (logs, tool binaries, install
   caches, instance registry).
+- `PI_LENS_CONFIG_PATH` — point the global config file at an explicit path.
+- `PI_CODING_AGENT_DIR` — when pi sets it, `$PI_CODING_AGENT_DIR/extensions/
+  pi-lens.json` is read when it exists and the default global config file does
+  not; pi-lens does not write the file.
 - `PI_LENS_MAX_PROJECT_FILES` — base project-size scale knob (default `2000`).
 - `PI_LENS_STARTUP_MODE` — force the startup path: `full`, `minimal`, or `quick`.
 

package/docs/subagent-compat.md

@@ -17,7 +17,7 @@ every run.
 
 | # | Contract | Depended on by | Third-party file (as of the versions below) | Verified against |
 |---|----------|-----------------|-------------------------------------------------|-------------------|
-| 1 | `PI_SUBAGENT_CHILD` is set to the literal string `"1"` on every process that hosts a child session. | `clients/subagent-mode.ts` (`isSubagentSession()`, `getSubagentIdentity()`) | `pi-subagents@0.34.0` — co-located in `src/runs/shared/pi-args.ts` (`SUBAGENT_CHILD_ENV` const + the `env[SUBAGENT_CHILD_ENV] = "1"` assignment); as of `pi-subagents@0.66.0` the const moved to `src/runs/shared/child-runtime-config.ts` and the assignment to `src/runs/background/subagent-runner.ts` (#2581) — `compat-contract-locator.mjs`'s `locateContractSources` tries both layouts and concatenates whichever resolves. | `checkNicobailonChildEnv` |
+| 1 | `PI_SUBAGENT_CHILD` is set to the literal string `"1"` on every process that hosts a child session. | `clients/subagent-mode.ts` (`isSubagentSession()`, `getSubagentIdentity()`) | `pi-subagents@0.34.0` — co-located in `src/runs/shared/pi-args.ts` (`SUBAGENT_CHILD_ENV` const + the `env[SUBAGENT_CHILD_ENV] = "1"` assignment); as of `pi-subagents@0.66.0` the const moved to `src/runs/shared/child-runtime-config.ts` and the assignment to `src/runs/background/subagent-runner.ts` (#2581); as of `0.70.0`, the published files are `src/runs/shared/child-runtime-config.js` and `src/runs/background/subagent-runner.js` — `compat-contract-locator.mjs`'s `locateContractSources` tries all layouts and concatenates whichever resolves. | `checkNicobailonChildEnv` |
 | 1b | avtc-pi-subagent sets `PI_SUBAGENT_CHILD_AGENT` + `PI_SUBAGENT_PARENT_PID` (never `PI_SUBAGENT_CHILD`) on the per-spawn subagent env; `isSubagentSession()` treats the PAIR (both non-empty) as an additional subagent signal (#507). | `clients/subagent-mode.ts` (`isSubagentSession()`, `getSubagentIdentity()`) | `avtc-pi-subagent@1.0.3` — `src/process-runner.ts` (`subagentEnv.PI_SUBAGENT_CHILD_AGENT = agent.name` + `subagentEnv.PI_SUBAGENT_PARENT_PID = String(process.pid)`) | `checkAvtcChildEnv` |
 | 2a | The pi SDK's extension loader keeps a **process-global** cache (`extensionCache = new Map()`). This is what makes an in-process `bindExtensions()` reuse pi-lens's own module-scope singletons instead of a fresh isolated instance. | `clients/session-lifecycle.ts` (the whole premise of the concurrent-session guard) | `@earendil-works/pi-coding-agent@0.80.6` — `dist/core/extensions/loader.js` | `checkSdkExtensionCache` |
 | 2b | `AgentSession.bindExtensions()` **unconditionally** emits a `session_start`-typed event (`this._extensionRunner.emit(this._sessionStartEvent)`). | Same as 2a — this is why an in-process subagent bind re-triggers pi-lens's `session_start` handler at all. | `@earendil-works/pi-coding-agent@0.80.6` — `dist/core/agent-session.js` (`bindExtensions()`, ~line 1717) | `checkSdkBindExtensionsEmitsSessionStart` |