pi-lens 4.1.2 → 4.1.4

package/dist/tools/lsp-diagnostics.js

@@ -23,39 +23,7 @@ import { isBlocking, reconcileScanDiagnostics, } from "../clients/widget-state.j
 import { baseName, compactRenderResult } from "./render-compact.js";
 import { makeProgressReporter, scanningSummaryLine } from "./scan-progress.js";
 import { isWarmAttached, tryWarmAttachedDiagnostics, } from "../clients/warm-attach.js";
-const LANG_EXTENSIONS = {
-    ".ts": [".ts", ".tsx", ".mts", ".cts"],
-    ".tsx": [".ts", ".tsx", ".mts", ".cts"],
-    ".js": [".js", ".jsx", ".mjs", ".cjs"],
-    ".py": [".py", ".pyi"],
-    ".rs": [".rs"],
-    ".go": [".go"],
-    ".rb": [".rb", ".rake", ".gemspec"],
-    ".java": [".java"],
-    ".kt": [".kt", ".kts"],
-    ".swift": [".swift"],
-    ".cs": [".cs"],
-    ".cpp": [".cpp", ".cc", ".cxx", ".hpp", ".hxx"],
-    ".c": [".c", ".h"],
-    ".zig": [".zig", ".zon"],
-    ".hs": [".hs", ".lhs"],
-    ".ex": [".ex", ".exs"],
-    ".gleam": [".gleam"],
-    ".tf": [".tf", ".tfvars"],
-    ".nix": [".nix"],
-    ".sh": [".sh", ".bash", ".zsh"],
-    ".php": [".php"],
-    ".lua": [".lua"],
-    ".dart": [".dart"],
-    ".vue": [".vue"],
-    ".svelte": [".svelte"],
-    ".css": [".css", ".scss", ".less"],
-    ".html": [".html", ".htm"],
-    ".json": [".json", ".jsonc"],
-    ".yaml": [".yaml", ".yml"],
-    ".toml": [".toml"],
-    ".prisma": [".prisma"],
-};
+import { extensionsForLanguage, SCAN_LANGUAGE_PRIORITY, } from "../clients/language-registry.js";
 const MAX_FILES = 100;
 const MAX_BATCH_FILES = 100;
 const MAX_DIAGNOSTICS = 200;
@@ -192,9 +160,10 @@ function projectIgnorePredicate(root) {
  * This walk was fully synchronous with NO yielding of any kind, bounded only by
  * `maxFiles` *kept* — an ignored-heavy or cloud-backed (OneDrive/network) tree
  * could traverse unboundedly many entries, and a single stalled `readdirSync`
- * held the loop for the whole stall. It is also called once PER LANGUAGE in
- * `runDirectoryDiagnostics`'s `LANG_EXTENSIONS` loop, so a directory-mode
- * `lsp_diagnostics` could pay that cost several times over.
+ * held the loop for the whole stall. It is also called once PER FAMILY in
+ * `runDirectoryDiagnostics`'s `SCAN_LANGUAGE_PRIORITY` loop (#2434, grouped by
+ * family since #2458 fix-round F1), so a directory-mode `lsp_diagnostics`
+ * could pay that cost several times over.
  *
  * The traversal is deliberately still **depth-first with immediate descent**
  * (not the shared stack-based `walkTreeStackAsync`): the `maxFiles` cap makes
@@ -456,13 +425,17 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
     // `touchFile` is the authoritative collection boundary for every scope: it
     // preserves per-touch timeout, content-binding, and silent-clean confirmation
     // metadata while returning diagnostics from only the requested clients. The
-    // legacy openFile/getDiagnostics path remains only for an older/mock service
-    // without touchFile, or when touchFile cannot resolve any clients.
+    // getDiagnostics fallback below remains for the two states a REAL service
+    // still reaches: the file read threw (no content to touch with), or the
+    // touch resolved no clients and returned `undefined` (clients/lsp/index.ts
+    // `touchFile`'s `no_clients`/`destroyed` returns). #2598 deleted the third
+    // reason — "an older/mock service without touchFile" — because the real
+    // `LSPService` has always defined the method unconditionally, so that arm
+    // was reachable only from a partial test double (AGENTS.md shape 7).
     // #1179: the result is an explicit wrapper so side-channel fields survive
     // array copies; confirmation was added when Marksman's lower-level clean verdict
     // proved that a successful empty collection also needs explicit provenance.
     let touched;
-    let usedTouch = false;
     try {
         content = fs.readFileSync(absPath, "utf-8");
         if (isWarmAttached()) {
@@ -501,35 +474,25 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
                 };
             }
         }
-        const serviceWithTouch = lspService;
-        if (typeof serviceWithTouch.touchFile === "function") {
-            usedTouch = true;
-            touched = await serviceWithTouch.touchFile(absPath, content, {
-                diagnostics: "document",
-                collectDiagnostics: true,
-                maxClientWaitMs: waitMs,
-                source: "lsp_diagnostics",
-                clientScope: serverScope,
-            });
-            timedOut = touched?.inconclusive === true;
-        }
-        else {
-            await lspService.openFile(absPath, content, {
-                preserveDiagnostics: false,
-            });
-        }
+        touched = await lspService.touchFile(absPath, content, {
+            diagnostics: "document",
+            collectDiagnostics: true,
+            maxClientWaitMs: waitMs,
+            source: "lsp_diagnostics",
+            clientScope: serverScope,
+        });
+        timedOut = touched?.inconclusive === true;
     }
     catch {
         // Non-fatal: getDiagnostics may still have stale/health information.
     }
     // Only fall through to the unscoped getDiagnostics() read when the touch
-    // branch wasn't taken (openFile-only path, which never collected anything
-    // and genuinely needs the follow-up call) or couldn't resolve any clients
-    // at all (touched stays undefined despite usedTouch). When touched IS
-    // defined it's already the answer — reusing it is what makes
-    // serverScope:"primary" actually skip auxiliary scanners and drops the
-    // common case back to a single LSP round trip instead of two.
-    const diagnostics = usedTouch && touched !== undefined
+    // produced nothing to read — it threw, the file read threw before it ran, or
+    // it resolved no clients at all. When touched IS defined it's already the
+    // answer — reusing it is what makes serverScope:"primary" actually skip
+    // auxiliary scanners and drops the common case back to a single LSP round
+    // trip instead of two.
+    const diagnostics = touched !== undefined
         ? touched.diags
         : await lspService.getDiagnostics(absPath, waitMs !== undefined ? "document" : "full");
     // #586: honor each auxiliary profile's native inline-suppression comment
@@ -546,24 +509,25 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
             fileRole: detectFileRole(absPath, content),
         })
         : diagnostics;
-    // #1095: surface the touch's content binding (only the touch path carries
-    // one; the openFile-only / getDiagnostics fallback leaves it undefined →
+    // #1095: surface the touch's content binding (only a touch that resolved
+    // clients carries one; the getDiagnostics fallback leaves it undefined →
     // "unknown", no demotion).
-    const binding = usedTouch ? touched?.binding : undefined;
+    const binding = touched?.binding;
     // #1470: `"partial"` counts here. `confirmedByTouch` feeds
     // `canTrustTouchConfirmation`, which asks about the PRIMARY's own verdict —
     // and a partial touch is one whose primary confirmed while an auxiliary was
     // cut off. Excluding it would render "Primary LSP: unconfirmed" for a primary
     // that did confirm. The coverage gap is carried separately, below.
-    const confirmedByTouch = usedTouch && touchCompletedConfirmationPolicy(touched);
+    const confirmedByTouch = touchCompletedConfirmationPolicy(touched);
     return {
         diagnostics: filtered,
         timedOut,
+        skipReason: touched?.skipReason,
         confirmedByTouch,
-        // #1470: only a touch actually contributes a coverage gap; the
-        // openFile+getDiagnostics fallback never reports one, which is honest —
-        // that path claims no confirmation at all.
-        unconfirmedServerIds: usedTouch ? touchCoverageGap(touched) : [],
+        // #1470: only a touch that resolved clients contributes a coverage gap;
+        // the getDiagnostics fallback never reports one, which is honest — that
+        // path claims no confirmation at all.
+        unconfirmedServerIds: touchCoverageGap(touched),
         content,
         binding,
     };
@@ -813,7 +777,7 @@ onConfirmedNoBlockers) {
             };
         }
     }
-    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, content: collectedContent, binding, } = await collectDiagnosticsForFile(file, lspService, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(file, lspService, waitMs, serverScope);
     const health = lspService.getDiagnosticsHealth?.(file);
     // #570: a timed-out priming check is never a confirmed "clean" — treat it
     // as unconfirmed without consulting the (unrelated) silent-tier
@@ -824,7 +788,10 @@ onConfirmedNoBlockers) {
     // be merged in rather than discarded.
     let effectiveRawDiags = rawDiags;
     let confirmation;
-    if (timedOut) {
+    if (skipReason !== undefined) {
+        confirmation = "unconfirmed";
+    }
+    else if (timedOut) {
         if (applySeverityFilter(rawDiags, severity).length === 0) {
             confirmation = "unconfirmed";
         }
@@ -887,7 +854,7 @@ onConfirmedNoBlockers) {
         unconfirmedServerIds.length === 0) {
         cacheCtx.record(file, scopeKey, effectiveRawDiags, stat.mtimeMs, collectedContent !== undefined
             ? hashDiagnosticContent(collectedContent)
-            : undefined);
+            : undefined, stat.size);
     }
     return {
         file,
@@ -895,6 +862,7 @@ onConfirmedNoBlockers) {
         unavailable: lspUnavailableMessage(file, health),
         confirmation,
         timedOut: confirmation === "unconfirmed" ? timedOut : undefined,
+        ...(skipReason !== undefined && { skipReason }),
         primaryServerId: primaryServerId(file),
     };
 }
@@ -905,7 +873,7 @@ onConfirmedNoBlockers) {
     // Reserve the token before awaiting this file's LSP result. The direct-file
     // path performs its own confirmation/reconciliation below (#1198).
     const writeIndex = nextWriteIndex?.();
-    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, content: collectedContent, binding, } = await collectDiagnosticsForFile(absPath, lspService, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, content: collectedContent, binding, skipReason, } = await collectDiagnosticsForFile(absPath, lspService, waitMs, serverScope);
     const lspHealth = lspService.getDiagnosticsHealth?.(absPath);
     const unavailable = lspUnavailableMessage(absPath, lspHealth);
     // #533: an empty result needs a confirmed/unconfirmed verdict — a push-only,
@@ -919,7 +887,10 @@ onConfirmedNoBlockers) {
     // diagnostics it surfaces are merged in, not discarded.
     let effectiveRawDiags = rawDiags;
     let confirmation;
-    if (timedOut) {
+    if (skipReason !== undefined) {
+        confirmation = "unconfirmed";
+    }
+    else if (timedOut) {
         if (applySeverityFilter(rawDiags, severity).length === 0) {
             confirmation = "unconfirmed";
         }
@@ -1060,6 +1031,7 @@ onConfirmedNoBlockers) {
             truncated,
             unconfirmed,
             timedOut: unconfirmed ? timedOut : undefined,
+            ...(skipReason !== undefined && { skipReason }),
             // #1470: which servers this result does NOT speak for. Absent when it
             // speaks for all of them.
             ...(unconfirmedServerIds.length > 0 && {
@@ -1341,18 +1313,42 @@ async function runBatchFileDiagnostics(absPaths, severity, lspService, options)
         },
     };
 }
+/**
+ * The scan-language DECISION `runDirectoryDiagnostics` makes, pulled out as
+ * its own function so `tests/tools/lsp-diagnostics-scan-family.test.ts` can
+ * pin it against the golden `LANG_EXTENSIONS` table for every 1- and
+ * 2-extension combination in that table's universe without spinning up one
+ * real directory (and the full LSP-mocked tool) per combination — `hasMatch`
+ * is the only I/O-shaped seam, so the caller decides whether it is backed by
+ * a real `collectFiles` walk (production) or an in-memory extension-set probe
+ * (tests).
+ *
+ * Walks `SCAN_LANGUAGE_PRIORITY`'s FAMILIES in order and unions each member
+ * id's {@link extensionsForLanguage} into ONE `hasMatch` call — the first
+ * family with any match wins the whole directory for this pass. Grouping by
+ * family (not trying each id alone) is what makes a directory mixing BOTH
+ * extensions of a registry-split pair (`.ts`+`.tsx`, `.css`+`.scss`, ...)
+ * behavior-preserving vs the pre-#2434 bundled-key table: a flat per-id loop
+ * stopped at the first id with ANY match, silently losing the sibling half of
+ * a split pair present in the same directory (#2458 fix-round F1).
+ */
+export async function resolveDirectoryScanExtensions(hasMatch) {
+    for (const family of SCAN_LANGUAGE_PRIORITY) {
+        const exts = family.flatMap((languageId) => extensionsForLanguage(languageId));
+        if (await hasMatch(exts)) {
+            return exts;
+        }
+    }
+    return undefined;
+}
 async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
-    let extension;
     let collectedFiles = [];
     const isIgnored = projectIgnorePredicate(absPath);
-    for (const [ext, exts] of Object.entries(LANG_EXTENSIONS)) {
-        collectedFiles = await collectFiles(absPath, exts, MAX_FILES + 1, isIgnored);
-        if (collectedFiles.length > 0) {
-            extension = ext;
-            break;
-        }
-    }
-    if (!extension || collectedFiles.length === 0) {
+    await resolveDirectoryScanExtensions(async (exts) => {
+        collectedFiles = await collectFiles(absPath, [...exts], MAX_FILES + 1, isIgnored);
+        return collectedFiles.length > 0;
+    });
+    if (collectedFiles.length === 0) {
         return {
             content: [
                 {

package/dist/tools/lsp-navigation.js

@@ -10,6 +10,8 @@ import { Type } from "../clients/deps/typebox.js";
 import { logLatency } from "../clients/latency-logger.js";
 import { newLspMutationCorrelationId, recordLspMutationOutcome, } from "../clients/lsp-mutation.js";
 import { uriToPath } from "../clients/path-utils.js";
+import { escapeRegExp } from "../clients/string-utils.js";
+import { isRecordableProjectPath } from "../clients/file-utils.js";
 import { compactRenderResult } from "./render-compact.js";
 import { applyWorkspaceEdit, summarizeWorkspaceEdit, } from "../clients/lsp/edits.js";
 import { getLSPService, } from "../clients/lsp/index.js";
@@ -106,9 +108,6 @@ function emptyReasonForOperation(operation) {
         return "no-call-hierarchy-results";
     return "no-results";
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function parseSymbolSelector(symbol) {
     const trimmed = symbol.trim();
     const match = /^([^#]*)(?:#(-?\d+))?$/.exec(trimmed);
@@ -467,6 +466,8 @@ function formatCapabilities(snapshots, filePath) {
         ["hover", (s) => !!s.operationSupport.hover],
         ["rename", (s) => !!s.operationSupport.rename],
         ["codeAction", (s) => !!s.operationSupport.codeAction],
+        ["codeAction/resolve", (s) => !!s.operationSupport.codeActionResolve],
+        ["workspace/willRenameFiles", (s) => !!s.operationSupport.willRenameFiles],
         ["workspaceSymbol", (s) => !!s.operationSupport.workspaceSymbol],
         ["implementation", (s) => !!s.operationSupport.implementation],
         ["signatureHelp", (s) => !!s.operationSupport.signatureHelp],
@@ -480,7 +481,7 @@ function formatCapabilities(snapshots, filePath) {
         [
             "rename_file",
             () => true,
-            "willRenameFiles/didRenameFiles helper available",
+            "filesystem rename; preflight support shown above",
         ],
     ];
     const lines = [];
@@ -528,16 +529,16 @@ async function openFileBestEffort(lspService, filePath, waitForDiagnostics = fal
     if (!fileContent)
         return;
     try {
-        if (typeof lspService.touchFile === "function") {
-            await lspService.touchFile(filePath, fileContent, {
-                diagnostics: waitForDiagnostics ? "document" : "none",
-                source: "lsp_navigation",
-                clientScope: waitForDiagnostics ? "all" : "primary",
-            });
-        }
-        else {
-            await lspService.openFile(filePath, fileContent);
-        }
+        // #2598: `touchFile` is defined unconditionally on the real `LSPService`
+        // (clients/lsp/index.ts), so the former `typeof … === "function"` hedge
+        // and its `openFile` arm were reachable only from a partial test double
+        // (AGENTS.md shape 7). Nothing here reads the result — a touch that
+        // resolves no clients is already the no-op this helper wants.
+        await lspService.touchFile(filePath, fileContent, {
+            diagnostics: waitForDiagnostics ? "document" : "none",
+            source: "lsp_navigation",
+            clientScope: waitForDiagnostics ? "all" : "primary",
+        });
     }
     catch {
         /* LSP server may not be ready yet — proceed anyway */
@@ -727,7 +728,7 @@ getFlag, mutationDeps) {
                         },
                     ],
                     details: {
-                        ...(payload.details ?? {}),
+                        ...payload.details,
                         failureKind: meta.failureKind,
                     },
                 };
@@ -777,15 +778,37 @@ getFlag, mutationDeps) {
             if (requestedApply &&
                 ["rename", "rename_file", "executeCommand"].includes(operation)) {
                 const cwd = ctx.cwd || ".";
+                // Name the specific LSP operation in the receipt rather than a
+                // generic "lsp-edit" tag, so a rename's change-log entry reads
+                // differently from an executeCommand-solicited edit (#2450).
+                const mutationSource = operation === "executeCommand" ? "lsp-execute-command" : "lsp-rename";
                 mutationContext = {
                     cwd,
                     correlationId: newLspMutationCorrelationId(_toolCallId),
-                    tool: "lsp_navigation",
-                    source: "lsp-edit",
+                    tool: `lsp_navigation:${operation}`,
+                    source: mutationSource,
                     ...mutationDeps,
                     readGuard: getFlag("no-read-guard", cwd)
                         ? undefined
                         : mutationDeps?.readGuard,
+                    // #2450 review round 2 (F4)/round 3 (F2, F4): the SAME gate
+                    // `registerMutationBridge` applies internally in `index.ts`, so
+                    // this directly-threaded path and the bridge fallback
+                    // (`clients/lsp-mutation.ts`, reached when `mutationDeps` is
+                    // absent/partial — e.g. the MCP server) agree on which files
+                    // count as project source, rather than the direct path
+                    // recording an ignored/vendor write the fallback would drop.
+                    // `no-read-guard` is intentionally NOT checked here (round 3
+                    // F2): it gates only the read-guard stamp above, the same
+                    // canonical split `clients/runtime-tool-result.ts` applies
+                    // (`:1120`, `:1485`) — bookkeeping (turn-state / receipts)
+                    // still runs under `--no-read-guard`. Judge against the
+                    // project root, not the request `cwd` (round 3 F4): a
+                    // sub-package `cwd` must not read a sibling-package rename as
+                    // external.
+                    isRecordable: (filePath) => {
+                        return isRecordableProjectPath(filePath, mutationDeps?.runtime?.projectRoot ?? cwd);
+                    },
                 };
             }
             const isCallHierarchyTraversal = operation === "incomingCalls" || operation === "outgoingCalls";

package/dist/tools/shared.js

@@ -22,7 +22,6 @@ export const LANGUAGES = [
     "ruby",
     "rust",
     "scala",
-    "solidity",
     "swift",
     "tsx",
     "typescript",

package/docs/agent-guide.md

@@ -45,10 +45,20 @@ On every write/edit, and at session/turn boundaries, pi-lens runs — without yo
 | **Structural rules** | ast-grep (NAPI engine) + tree-sitter rules flag correctness/security smells. |
 | **Opengrep security scan** | Always-on: per-edit via an auxiliary LSP, plus a cached project-wide CLI scan for `mode=full`. |
 | **Other scanners** | Config-/presence-gated: gitleaks (secrets), trivy (CVEs/IaC/license), govulncheck (Go), knip/jscpd/madge (JS/TS dead-code/dupes/cycles), vulture (Python), zizmor (GH Actions), typos. |
-| **Test-runner-on-write** | Related/affected tests are run asynchronously for the next turn's findings (edit-scoped, not a full-suite run). |
+| **Test-runner-on-write** | Related/affected tests are run asynchronously for the next turn's findings (edit-scoped, not a full-suite run). Integration/e2e tests are never auto-fired — see below. |
 | **Read-guard** | Tracks that you read a file before editing it; blocks/warns zero-read or stale-range edits. |
 | **Context injection** | Injects session-start guidance and turn-end findings into your context (see §2). |
 
+**Test-runner-on-write scope.** A built-in exclusion list keeps integration/e2e
+suites out of the auto-fired batch — `**/integration/**`, `**/e2e/**`,
+`**/*.integration.*`, `**/*.e2e.*` — since those commonly spawn external
+processes (another CLI, a browser, a live provider) that don't belong on an
+unattended per-edit turn. This is a fixed, built-in list; there is no
+per-project config knob for it. If a runner itself fails to complete (a
+timeout, or a missing provider/binary — not a failing assertion), pi-lens
+delivers it as an advisory ("could not complete last turn"), not as a
+"fix before continuing" blocker — you didn't introduce anything to fix.
+
 You don't invoke these. They happen. Your job is to **read the results** and **respond**.
 
 ---
@@ -143,8 +153,10 @@ Edits fail or warn when:
 
 A blocked edit returns a retryable message, e.g.:
 
-> `🔄 RETRYABLE — Edit without read … Read the file first, then retry the edit:
-> read path="<file>"`
+```text
+🔄 RETRYABLE — Edit without read: you have not read `<file>` in this
+conversation. Read it first, then retry: `read path="<file>"`.
+```
 
 **Correct behavior:** read the file (or the relevant range/symbol) *before* editing.
 Helpful mechanics you can rely on:
@@ -183,9 +195,62 @@ pi-lens writes to files **outside your own tool calls** (`docs/features.md`
 - **`write` then `edit` on the same file, same turn:** the write's autofix
   demotes to deferred too, so the file's mutation history stays coherent. This
   resets at the next turn.
+- **Any other tool that edits a file:** pi-lens recognizes it by the SHAPE of
+  its arguments rather than its name (`clients/mutating-tool.ts`), so a host or
+  extension tool called `replace` or `insert` gets the same chain `edit` gets:
+  a turn-state entry, a change-log receipt attributed to that tool, and a
+  *deferred* auto-fix. Its lines are resolved when the anchor is unambiguous
+  (roughly two-thirds of anchors in practice — `clients/hashline-anchor.ts`);
+  otherwise the mutation is recorded whole-file with lines unknown, and the
+  read-before-edit guard takes its no-line-info arm rather than guessing.
+  Deferred is the default for every edit-shaped tool pi-lens cannot place,
+  because formatting between the steps of a multi-call rewrite fights the tool
+  that is still writing.
+- **A tool whose shape is unrecognized too:** pi-lens watches instead of
+  guessing (`clients/observed-mutation.ts`). A call that names a file gets a
+  bounded pre/post snapshot of THAT PATH — the file itself, or a directory's own
+  entries — and nothing else, so a write landing on a neighbouring file is never
+  attributed to it. Anything that changed is replayed through the same chain,
+  and the tool is then remembered as mutating: for this session on the first
+  sighting, persisted under the project's data directory on the second, so a
+  later session classifies it by name with no snapshot at all. Three quiet
+  observations in a row withdraw a session attribution again, and a withdrawn
+  tool can be learned back from a later real edit. An observation pi-lens could
+  not finish — a directory with more entries than it watches — counts as
+  neither, so a wide codemod is never written off on a look it never took. A
+  call that names
+  no file is caught at `agent_settled` by an incremental content check over the
+  files pi-lens has already read, written, diagnosed or opened on a language
+  server — a rotating window per turn, reading only what actually moved; a file
+  it has never seen has no baseline, so that last-resort net does not cover it,
+  and a file it cannot verify is reported as such rather than reformatted on a
+  timestamp alone.
 - The conservative actionable-warnings autofix (LSP quickfixes, hard-capped)
   is unchanged: it always runs at `agent_end`.
 
+**Extension authors: record your own writes.** If your extension writes files
+outside pi-lens's tool events — its own registered tool, a spawned rewriter —
+tell pi-lens through the in-process mutation bridge, the write-side sibling of
+the read bridge:
+
+```js
+const bridge = globalThis[Symbol.for("pi-lens:mutation-bridge")];
+if (bridge?.version === 1) {
+  bridge.recordMutation({
+    filePath,               // absolute path
+    kind: "edit",           // "write" replaces the whole file; "edit" is partial
+    editRanges: [[12, 18]], // optional, 1-based inclusive
+    consumer: "my-extension",
+  });
+}
+```
+
+Check `version` before calling; a version you do not recognize is unsupported.
+Calling when pi-lens is absent or the guard is disabled is safe — the bridge is
+missing or drops the call. `recordMutation` returns `true` when pi-lens took the
+record and `false` when it dropped it, so you can count your own drops. pi-lens's
+own `ast_grep_replace apply:true` records through this same bridge.
+
 Consequences for you:
 
 - Your exact written bytes may be reformatted/fixed. **This is expected pipeline