@herbertgao/pi-extensions 2026.8.4 → 2026.8.5

package/node_modules/pi-lens/dist/tools/lsp-diagnostics.js

@@ -14,6 +14,7 @@ import { primaryServerId } from "../clients/lsp/config.js";
 import { combineAbortSignals, withDeadline } from "../clients/deadline-utils.js";
 import { applyAuxiliarySuppressions, retagAuxiliaryDiagnostics, } from "../clients/dispatch/auxiliary-lsp.js";
 import { detectFileRole } from "../clients/file-role.js";
+import { hashDiagnosticContent, } from "../clients/lsp/diagnostic-binding.js";
 import { classifyCascadeWaitTier } from "../clients/lsp/wait-policy/index.js";
 import { attemptTsserverSyncDiagnostics, } from "../clients/lsp/tsserver-sync.js";
 import { convertLspDiagnostics } from "../clients/dispatch/utils/lsp-diagnostics.js";
@@ -184,14 +185,30 @@ function projectIgnorePredicate(root) {
         return () => false;
     }
 }
-function collectFiles(dir, extensions, maxFiles, isIgnored = () => false) {
+/**
+ * #1137: async so a directory read never blocks the event loop (and pi's TUI).
+ *
+ * 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.
+ *
+ * The traversal is deliberately still **depth-first with immediate descent**
+ * (not the shared stack-based `walkTreeStackAsync`): the `maxFiles` cap makes
+ * traversal ORDER observable — a stack walk would keep a different subset of
+ * files on an over-large tree. Only scheduling changes here; the returned list
+ * is identical. Awaiting each directory read is itself the yield point.
+ */
+async function collectFiles(dir, extensions, maxFiles, isIgnored = () => false) {
     const files = [];
-    function walk(current) {
+    async function walk(current) {
         if (files.length >= maxFiles)
             return;
         let entries;
         try {
-            entries = fs.readdirSync(current, { withFileTypes: true });
+            entries = await fs.promises.readdir(current, { withFileTypes: true });
         }
         catch {
             return;
@@ -204,7 +221,7 @@ function collectFiles(dir, extensions, maxFiles, isIgnored = () => false) {
             const full = path.join(current, entry.name);
             if (entry.isDirectory()) {
                 if (!isExcludedDirName(entry.name) && !isIgnored(full, true))
-                    walk(full);
+                    await walk(full);
             }
             else if (entry.isFile() && extensions.includes(path.extname(full))) {
                 if (isIgnored(full, false))
@@ -213,15 +230,15 @@ function collectFiles(dir, extensions, maxFiles, isIgnored = () => false) {
             }
         }
     }
-    walk(dir);
+    await walk(dir);
     return files;
 }
 export function createLspDiagnosticsTool(
-// #571: same shared write-ordering token source `lens_diagnostics` mode=full
-// uses (index.ts injects `() => runtime.nextWriteIndex()`) — a confirmed
-// fresh result this tool reconciles into the footer draws a fresh token so
-// `WriteOrderingGuard` can tell it apart from a concurrent, genuinely newer
-// per-edit write for the same file. Optional/undefined in tests.
+// #571/#1198: same shared write-ordering token source `lens_diagnostics`
+// mode=full uses (index.ts injects `() => runtime.nextWriteIndex()`). A
+// confirmed result reconciled into the footer reserves its token when the
+// per-file check starts, so settlement order cannot make an older result look
+// newer. Optional/undefined in tests.
 nextWriteIndex) {
     return {
         name: "lsp_diagnostics",
@@ -419,19 +436,14 @@ nextWriteIndex) {
 async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScope = "all") {
     let timedOut = false;
     let content;
-    // #629: `touched` (when defined) is ALREADY the correctly-scoped,
-    // already-collected diagnostics array for this touch — `touchFile` below
-    // is called with `collectDiagnostics: true` and `clientScope: serverScope`,
-    // so its return value only contains diagnostics from the servers
-    // `serverScope` asked for. Previously this function discarded `touched`
-    // (reading only `.inconclusive` off it) and made a SECOND, unconditionally
-    // -unscoped `getDiagnostics()` call for the actual content — meaning every
-    // touchFile-branch call paid for two LSP round trips instead of one, and
-    // `serverScope: "primary"` never actually skipped the auxiliary scanners
-    // (getDiagnostics always queries every registered server for the file).
-    // `touched` is only undefined when touchFile itself couldn't produce a
-    // result (service destroyed, no clients resolved) — that's the one case
-    // that still needs the getDiagnostics() fallback below.
+    // `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.
+    // #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 {
@@ -447,12 +459,26 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
                     ? attached.response.diagnostics.filter((item) => item.source === primaryServerId(absPath))
                     : attached.response.diagnostics;
                 const filtered = applyAuxiliarySuppressions(scopedDiagnostics, content, { fileRole: detectFileRole(absPath, content) });
-                return { diagnostics: filtered, timedOut: false, content };
+                return {
+                    diagnostics: filtered,
+                    timedOut: false,
+                    // #1253: the incumbent's touch carries the same confirmation
+                    // provenance a local touch does (an `available: true` answer is
+                    // already gated on `fresh && !inconclusive`, but that is NOT
+                    // evidence a silent-on-clean server was confirmed — only the
+                    // explicit flag is). The incumbent always touches with
+                    // `clientScope: "with-auxiliary"`, so this is an AGGREGATE
+                    // confirmation: it carries the same caveat all-scope local
+                    // touches do, and classic TypeScript still needs the primary-only
+                    // tsserver sync check below rather than this verdict.
+                    confirmedByTouch: attached.response.confirmation === "confirmed" &&
+                        primaryServerId(absPath) !== "typescript",
+                    content,
+                };
             }
         }
         const serviceWithTouch = lspService;
-        if ((waitMs !== undefined || serverScope === "primary") &&
-            typeof serviceWithTouch.touchFile === "function") {
+        if (typeof serviceWithTouch.touchFile === "function") {
             usedTouch = true;
             touched = await serviceWithTouch.touchFile(absPath, content, {
                 diagnostics: "document",
@@ -480,7 +506,7 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
     // 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
-        ? touched
+        ? touched.diags
         : await lspService.getDiagnostics(absPath, waitMs !== undefined ? "document" : "full");
     // #586: honor each auxiliary profile's native inline-suppression comment
     // (e.g. opengrep's `// nosemgrep`, #441) the same way the per-edit dispatch
@@ -496,7 +522,18 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
             fileRole: detectFileRole(absPath, content),
         })
         : diagnostics;
-    return { diagnostics: filtered, timedOut, content };
+    // #1095: surface the touch's content binding (only the touch path carries
+    // one; the openFile-only / getDiagnostics fallback leaves it undefined →
+    // "unknown", no demotion).
+    const binding = usedTouch ? touched?.binding : undefined;
+    const confirmedByTouch = usedTouch && touched?.confirmation === "confirmed";
+    return {
+        diagnostics: filtered,
+        timedOut,
+        confirmedByTouch,
+        content,
+        binding,
+    };
 }
 function diagnosticsToFileDiags(file, diagnostics) {
     return diagnostics.map((d) => ({
@@ -567,6 +604,17 @@ async function resolveEmptyResult(file, lspService) {
         return { confirmed: true, diagnostics: [] };
     }
 }
+/**
+ * A primary-scope touch is authoritative because `touchFile` runs that
+ * primary's own confirmation path (including TypeScript's sync fallback). For
+ * all-scope TypeScript touches, the aggregate silent-clean gate can settle
+ * without that primary-only sync request, so preserve `resolveEmptyResult`'s
+ * existing tsserver fallback instead of accepting the aggregate verdict.
+ */
+function canTrustTouchConfirmation(file, serverScope, confirmedByTouch) {
+    return (confirmedByTouch &&
+        (serverScope === "primary" || primaryServerId(file) !== "typescript"));
+}
 /**
  * #571: reconcile this tool's fresh LSP result into the footer cache
  * (`widget-state.ts`'s `allDiagnostics`) — same shared choke point
@@ -574,6 +622,11 @@ async function resolveEmptyResult(file, lspService) {
  * `reconcileScanDiagnostics`). A manual `lsp_diagnostics` check that proves a
  * stale footer error is actually gone (the real-world case that surfaced
  * #571) is exactly the kind of confirmed result that should correct it.
+ * Direct `lsp_diagnostics` deliberately does not perform a second disk read at
+ * this reconciliation seam: its collecting touch already read the content and
+ * supplies the binding verdict. `false` is unconfirmed and is never written;
+ * `true` is trusted, while an absent/`unknown` verdict preserves the legacy
+ * fail-open policy for servers that cannot bind their diagnostics to content.
  *
  * `rawDiags` (pre-severity-filter) is what gets written — the footer records
  * the true known state, independent of this call's display-only severity
@@ -592,8 +645,22 @@ async function resolveEmptyResult(file, lspService) {
  * /skipTestFiles-filtered at write time — an empty string here is then a safe
  * no-op re-check, not a behavior gap).
  */
-function reconcileWidgetFromLspResult(file, rawDiags, confirmation, nextWriteIndex, cwd, content) {
-    const confirmed = rawDiags.length > 0 || confirmation !== "unconfirmed";
+function reconcileWidgetFromLspResult(file, rawDiags, confirmation, writeIndex, cwd, content, 
+// #1095: true when the result's content binding demonstrably mismatches disk
+// (boundToCurrentDisk === false). Such a result — even a NON-EMPTY one, which
+// the pre-#1095 "non-empty is definitionally confirmed" doctrine would have
+// written straight through — must NOT re-cement the footer with a stale view
+// (#1092's window-1 transcript: 17 live-looking diagnostics while tsc exits
+// 0). "unknown"/true bindings leave the doctrine unchanged (fallback preserved
+// for servers that never bind a version).
+boundMismatch = false, 
+// #1093: when these `rawDiags` were actually OBSERVED. Fresh touches observe
+// now (`undefined` → `Date.now()`); a cache HIT replays diagnostics scanned
+// earlier, so its caller passes the cache entry's `scannedAt` here so the
+// footer's `touchedAt` isn't re-armed to now() and the mtime-staleness gate
+// stays live (the #1092 re-arming defect).
+observedAt) {
+    const confirmed = (rawDiags.length > 0 || confirmation !== "unconfirmed") && !boundMismatch;
     if (!confirmed)
         return;
     try {
@@ -603,7 +670,7 @@ function reconcileWidgetFromLspResult(file, rawDiags, confirmation, nextWriteInd
             scanOrigin: "lsp_diagnostics",
         });
         const retagged = retagAuxiliaryDiagnostics(diagnostics, rawDiags, content ?? "", { cwd, fileRole: detectFileRole(file, content) });
-        reconcileScanDiagnostics(file, retagged, true, nextWriteIndex?.());
+        reconcileScanDiagnostics(file, retagged, true, writeIndex, observedAt);
     }
     catch {
         // Never let a footer-reconciliation hiccup fail the diagnostics check.
@@ -621,6 +688,10 @@ cacheCtx, scopeKey,
 // `process.cwd()` for any call site that predates this (there are none
 // today besides the two below, both of which now pass it explicitly).
 cwd = process.cwd()) {
+    // Reserve the ordering token when this diagnostic operation starts, not when
+    // its LSP promise settles. A slower old result must not receive a newer token
+    // merely because it completed later (#1198).
+    const writeIndex = nextWriteIndex?.();
     let stat;
     try {
         stat = fs.statSync(file);
@@ -633,14 +704,27 @@ cwd = process.cwd()) {
     }
     if (cacheCtx && scopeKey !== undefined) {
         const cached = cacheCtx.lookup(file, scopeKey);
-        if (cached) {
+        // #1095: a cached entry whose content binding demonstrably mismatches disk
+        // (bytes changed without the mtime bump the freshness gate would catch) is
+        // NOT served — fall through to a fresh touch instead of replaying a stale
+        // cached result. "unknown"/true bindings serve as before.
+        if (cached && cached.binding.boundToCurrentDisk !== false) {
             const filteredDiags = applySeverityFilter(cached.diagnostics, severity);
             const confirmation = cached.diagnostics.length === 0 ? "clean" : undefined;
             // #692: cached.diagnostics were already suppression-/skipTestFiles-
             // filtered at write time (this same code path); no file content was
             // cached alongside them, so `undefined` here is a safe re-check, not
             // a gap.
-            reconcileWidgetFromLspResult(file, cached.diagnostics, confirmation, nextWriteIndex, cwd, undefined);
+            // #1093: this is a CACHE HIT — a replay of an OLD observation. Stamp the
+            // footer's `touchedAt` with the cache entry's original `scannedAt`, NOT
+            // now(), or a repeat check that only re-serves the cache would keep
+            // re-arming the mtime-staleness gate and a resolved finding would render
+            // forever (the #1092 defect).
+            reconcileWidgetFromLspResult(file, cached.diagnostics, confirmation, writeIndex, cwd, undefined, 
+            // This branch only runs when the cache binding is not a mismatch
+            // (guarded above), so boundMismatch is false; #1093's observedAt is
+            // the cache entry's original scan time.
+            false, cached.scannedAt);
             return {
                 file,
                 diagnostics: diagnosticsToFileDiags(file, filteredDiags),
@@ -649,7 +733,7 @@ cwd = process.cwd()) {
             };
         }
     }
-    const { diagnostics: rawDiags, timedOut, content: collectedContent, } = await collectDiagnosticsForFile(file, lspService, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, content: collectedContent, binding, } = 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
@@ -665,6 +749,11 @@ cwd = process.cwd()) {
             confirmation = "unconfirmed";
         }
     }
+    else if (canTrustTouchConfirmation(file, serverScope, confirmedByTouch)) {
+        if (applySeverityFilter(rawDiags, severity).length === 0) {
+            confirmation = "clean";
+        }
+    }
     else if (rawDiags.length === 0) {
         const resolved = await resolveEmptyResult(file, lspService);
         effectiveRawDiags = resolved.diagnostics;
@@ -677,16 +766,26 @@ cwd = process.cwd()) {
     else if (applySeverityFilter(rawDiags, severity).length === 0) {
         confirmation = await classifyEmptyResult(file, lspService);
     }
+    // #1095: a result whose content binding demonstrably mismatches disk is
+    // demoted to "unconfirmed" — it must neither confirm the footer nor be cached
+    // as clean, regardless of how many diagnostics it carries (the #1092
+    // re-cementing path). "unknown"/true bindings leave the verdict untouched.
+    const boundMismatch = binding?.boundToCurrentDisk === false;
+    if (boundMismatch)
+        confirmation = "unconfirmed";
     const filteredDiags = applySeverityFilter(effectiveRawDiags, severity);
-    reconcileWidgetFromLspResult(file, effectiveRawDiags, confirmation, nextWriteIndex, cwd, collectedContent);
+    reconcileWidgetFromLspResult(file, effectiveRawDiags, confirmation, writeIndex, cwd, collectedContent, boundMismatch);
     // #671: only a CONFIRMED outcome ("clean", or a non-empty result — either
     // is definitionally confirmed per this function's own doctrine above) is
     // safe to cache; "unconfirmed" (timeout OR a silent-tier server's
     // unescapable empty push) must never be persisted as a cacheable clean
     // result — same false-clean bug class `runWorkspaceDiagnostics`'s cache
-    // wiring guards against.
+    // wiring guards against. #1095: the entry carries the content fingerprint so a
+    // later lookup can verify it against disk beyond the mtime proxy.
     if (cacheCtx && scopeKey !== undefined && confirmation !== "unconfirmed") {
-        cacheCtx.record(file, scopeKey, effectiveRawDiags, stat.mtimeMs);
+        cacheCtx.record(file, scopeKey, effectiveRawDiags, stat.mtimeMs, collectedContent !== undefined
+            ? hashDiagnosticContent(collectedContent)
+            : undefined);
     }
     return {
         file,
@@ -698,7 +797,10 @@ cwd = process.cwd()) {
     };
 }
 async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWriteIndex, serverScope = "all", cwd = process.cwd()) {
-    const { diagnostics: rawDiags, timedOut, content: collectedContent, } = await collectDiagnosticsForFile(absPath, lspService, waitMs, serverScope);
+    // 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, content: collectedContent, binding, } = 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,
@@ -717,6 +819,11 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
             confirmation = "unconfirmed";
         }
     }
+    else if (canTrustTouchConfirmation(absPath, serverScope, confirmedByTouch)) {
+        if (applySeverityFilter(rawDiags, severity).length === 0) {
+            confirmation = "clean";
+        }
+    }
     else if (rawDiags.length === 0) {
         const resolved = await resolveEmptyResult(absPath, lspService);
         effectiveRawDiags = resolved.diagnostics;
@@ -729,12 +836,18 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
     else if (applySeverityFilter(rawDiags, severity).length === 0) {
         confirmation = await classifyEmptyResult(absPath, lspService);
     }
+    // #1095: demote a result whose content binding mismatches disk to
+    // "unconfirmed" (the #1092 re-cementing path) — a non-empty stale result is no
+    // longer "definitionally confirmed". "unknown"/true bindings are unchanged.
+    const boundMismatch = binding?.boundToCurrentDisk === false;
+    if (boundMismatch)
+        confirmation = "unconfirmed";
     const filtered = applySeverityFilter(effectiveRawDiags, severity);
     const total = filtered.length;
     const truncated = total > MAX_DIAGNOSTICS;
     const limited = truncated ? filtered.slice(0, MAX_DIAGNOSTICS) : filtered;
     const unconfirmed = confirmation === "unconfirmed";
-    reconcileWidgetFromLspResult(absPath, effectiveRawDiags, confirmation, nextWriteIndex, cwd, collectedContent);
+    reconcileWidgetFromLspResult(absPath, effectiveRawDiags, confirmation, writeIndex, cwd, collectedContent, boundMismatch);
     const primaryId = primaryServerId(absPath);
     const primaryDiags = limited.filter((d) => d.source === primaryId);
     const auxiliaryDiags = limited.filter((d) => d.source !== primaryId);
@@ -1072,7 +1185,7 @@ async function runDirectoryDiagnostics(absPath, severity, lspService, options) {
     let collectedFiles = [];
     const isIgnored = projectIgnorePredicate(absPath);
     for (const [ext, exts] of Object.entries(LANG_EXTENSIONS)) {
-        collectedFiles = collectFiles(absPath, exts, MAX_FILES + 1, isIgnored);
+        collectedFiles = await collectFiles(absPath, exts, MAX_FILES + 1, isIgnored);
         if (collectedFiles.length > 0) {
             extension = ext;
             break;

package/node_modules/pi-lens/dist/tools/lsp-navigation.js

@@ -8,6 +8,7 @@ import * as path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Type } from "../clients/deps/typebox.js";
 import { logLatency } from "../clients/latency-logger.js";
+import { newLspMutationCorrelationId, recordLspMutationOutcome, } from "../clients/lsp-mutation.js";
 import { compactRenderResult } from "./render-compact.js";
 import { applyWorkspaceEdit, summarizeWorkspaceEdit, } from "../clients/lsp/edits.js";
 import { getLSPService } from "../clients/lsp/index.js";
@@ -550,7 +551,7 @@ export function createLspNavigationTool(
  * constructed in; callers that only have a single fixed project root (e.g.
  * pi's own `getLensFlag`) may ignore the second argument.
  */
-getFlag) {
+getFlag, mutationDeps) {
     return {
         name: "lsp_navigation",
         label: "LSP Navigate",
@@ -675,7 +676,15 @@ getFlag) {
             let supported = null;
             let diagnosticsMode = "unknown";
             let columnResolution;
+            let mutationContext;
+            let requestedApply = false;
             const finalize = (payload, meta) => {
+                if (payload.isError &&
+                    requestedApply &&
+                    mutationContext &&
+                    ["rename", "rename_file", "executeCommand"].includes(meta.operation)) {
+                    recordLspMutationOutcome(mutationContext, "failed");
+                }
                 const normalizedFilePath = meta.filePath.replace(/\\/g, "/");
                 logLatency({
                     type: "phase",
@@ -759,6 +768,21 @@ getFlag) {
                 });
             }
             const operation = normalizedOperation;
+            requestedApply = apply === true;
+            if (requestedApply &&
+                ["rename", "rename_file", "executeCommand"].includes(operation)) {
+                const cwd = ctx.cwd || ".";
+                mutationContext = {
+                    cwd,
+                    correlationId: newLspMutationCorrelationId(_toolCallId),
+                    tool: "lsp_navigation",
+                    source: "lsp-edit",
+                    ...mutationDeps,
+                    readGuard: getFlag("no-read-guard", cwd)
+                        ? undefined
+                        : mutationDeps?.readGuard,
+                };
+            }
             const isCallHierarchyTraversal = operation === "incomingCalls" || operation === "outgoingCalls";
             const needsFilePath = operation !== "workspaceDiagnostics" &&
                 operation !== "workspaceSymbol" &&
@@ -1060,7 +1084,7 @@ getFlag) {
                                 edit,
                             };
                         }
-                        const applied = await applyWorkspaceEdit(edit, ctx.cwd || ".");
+                        const applied = await applyWorkspaceEdit(edit, ctx.cwd || ".", { mutationContext });
                         for (const touchedFile of applied.files) {
                             try {
                                 await openFileBestEffort(lspService, touchedFile, false);
@@ -1081,6 +1105,7 @@ getFlag) {
                         const result = await lspService.renameFile(filePath, resolvedNewFilePath, {
                             cwd: ctx.cwd || ".",
                             apply: apply ?? false,
+                            ...(mutationContext ? { mutationContext } : {}),
                         });
                         if (result.applied) {
                             for (const touchedFile of result.files ?? []) {
@@ -1122,7 +1147,7 @@ getFlag) {
                         if (!isAdvertised) {
                             throw new Error(`__UNSUPPORTED__ command "${command}" is not advertised by the active LSP server (advertised: ${advertised.join(", ") || "none"})`);
                         }
-                        return lspService.executeCommand(rawPath ? filePath : undefined, command, commandArguments);
+                        return lspService.executeCommand(rawPath ? filePath : undefined, command, commandArguments, mutationContext);
                     }
                     case "incomingCalls": {
                         if (!callHierarchyItem) {
@@ -1177,6 +1202,24 @@ getFlag) {
                         }
                     }
                 }
+                if (mutationContext &&
+                    requestedApply &&
+                    !mutationContext.summaryEmitted) {
+                    const outcome = operation === "rename_file" &&
+                        result &&
+                        typeof result === "object" &&
+                        "applied" in result &&
+                        result.applied === false
+                        ? "failed"
+                        : operation === "executeCommand" &&
+                            result &&
+                            typeof result === "object" &&
+                            "executed" in result &&
+                            result.executed === false
+                            ? "failed"
+                            : "skipped";
+                    recordLspMutationOutcome(mutationContext, outcome);
+                }
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);

package/node_modules/pi-lens/dist/tools/module-report.js

@@ -29,6 +29,7 @@ export function createModuleReportTool(getProjectRoot) {
         description: "Structured, navigable overview of a source module — a token-efficient substitute for reading the whole file. Returns each symbol's name/kind/signature/line-range (plus a first-line `doc` summary when a doc comment is attached), important inline callbacks/closures/lambdas with stable handles, plus who-uses-this, risk flags, and ranked recommendedReads. To read a symbol's body: call read/read_symbol with offset=startLine, limit=endLine-startLine+1 on THIS report's `path` — those aren't repeated per symbol. Prefer this before a full read; then use read_symbol (or read) for the exact body you need.\n" +
             "Single mode: language-uniform tree-sitter outline + review-graph who-uses-this + inline executable extraction; degrades to outline-only when no cached graph is available. `semantic.source` reports whether graph data was used.\n" +
             'Pass `blastRadius: true` to also get the cross-file blast radius — the transitive dependents of this module aggregated to ranked file `read` args ("if you change this, verify these files"). Read-only over the cached graph; omitted on a cold cache. Supersedes the standalone impact query.\n' +
+            'Pass `callGraph: true` to include bounded derived callers/callees from the cached FunctionCallGraph; unavailable cache state is explicit and never reported as zero calls.\n' +
             '`view: "compact"` returns a line-oriented text rendering (one line per symbol/callback, cheapest option) instead of JSON — same data, roughly a quarter of the token cost; use it for a quick skim. Default view returns JSON. An outline shows shape, not bodies — it does NOT count as having read a symbol\'s body for editing; use read_symbol for that.',
         promptSnippet: "Navigable file outline — a cheap substitute for reading a whole file",
         renderResult: compactRenderResult(({ details, args, isError }) => {
@@ -65,6 +66,12 @@ export function createModuleReportTool(getProjectRoot) {
             blastRadiusDepth: Type.Optional(Type.Number({
                 description: "Max hops for the blast-radius walk (default 3). Only used with blastRadius.",
             })),
+            callGraph: Type.Optional(Type.Boolean({
+                description: "Include bounded derived callers/callees from the cached FunctionCallGraph; cold or stale cache state is explicit.",
+            })),
+            maxCallGraphEntries: Type.Optional(Type.Number({
+                description: "Per-direction cap for call-graph relations (default 20).",
+            })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             // Resolve the file against the agent's cwd (sibling-tool convention); build
@@ -79,6 +86,8 @@ export function createModuleReportTool(getProjectRoot) {
                     view: params.view,
                     blastRadius: params.blastRadius,
                     blastRadiusDepth: params.blastRadiusDepth,
+                    callGraph: params.callGraph,
+                    maxCallGraphEntries: params.maxCallGraphEntries,
                 });
             }
             catch (err) {

package/node_modules/pi-lens/docs/agent-guide.md

@@ -122,7 +122,7 @@ unresolved blockers exist, with:
 > `🔴 COMMIT BLOCKED (--lens-guard): unresolved blockers must be fixed before
 > commit/push. … Run lens_diagnostics mode=all for full details, then commit again.`
 
-Don't try to route around it — clear the blockers, then commit.
+Don't try to route around it — clear the blockers, then commit. The guard is strictly opt-in (off by default) and is marked **EXPERIMENTAL**. It gates only structured blocking findings, including blocking test failures under the current test-runner policy; advisory/no-action-required findings never gate. The blocker state is sequence- and session-bound, so an ambiguous or stale blocker record blocks conservatively until pi-lens runs again; advisory records never gate.
 
 ---
 
@@ -207,7 +207,7 @@ Verified in `index.ts`:
 | `/lens-toggle` | Turn pi-lens on/off for the session. |
 | `/lens-context-toggle` | Toggle context injection (tools/LSP/read-guard/formatting stay active). |
 | `/lens-widget-toggle` | Show/hide the diagnostics footer widget. |
-| `/lens-health` | Runtime health: pipeline crashes, slow runners, last dispatch latency. |
+| `/lens-health` | Runtime health: pipeline crashes, slow runners, last dispatch latency, and a bounded degradation-ledger summary (trust refusals, LSP breakers, formatter skips/failures, idle evictions, WASM aborts, timeout tallies). |
 | `/lens-perf` | Slowest latency-log phases (p50/p99). |
 | `/lens-tools` | Tool installation status (global / auto-installed / npx fallback). |
 | `/lens-tdi` | Technical Debt Index and project health trend. |

package/node_modules/pi-lens/docs/agent-tools.md

@@ -14,9 +14,11 @@ share) — current exceptions: `ast_grep_outline` and `ast_grep_dump`
 are registered but
 inactive by default; the model activates the ones it needs via the always-active
 loader tool `pi_lens_activate_tools`, per pi's dynamic-tool-loading API
-(`pi.setActiveTools`/`pi.getActiveTools`). Feature-detected: on hosts without
-that API, the five situational tools fall back to being statically active,
-exactly as before (`tools/activate-tools.ts`, wired in `index.ts`).
+(`pi.setActiveTools`/`pi.getActiveTools`). The loader explicitly reports
+"Available starting next turn"; do not retry the tool in the same turn.
+Feature-detected: on hosts without that API, the six situational tools fall back
+to being statically active, exactly as before (`tools/activate-tools.ts`, wired
+in `index.ts`).
 
 ## Per-edit
 
@@ -40,13 +42,22 @@ exactly as before (`tools/activate-tools.ts`, wired in `index.ts`).
 - **`ast_grep_search`** — AST-aware structural search across ~40 languages via
   the `sg` CLI. Supports metavariables (`$VAR`, `$$$ARGS`), `strictness`
   modes (`smart`, `relaxed`, `ast`, `cst`, `signature`, `template`), structural
-  constraints (`insideKind`, `hasKind`, `follows`, `precedes`), raw YAML `rule`
-  passthrough, `validateOnly` for compile/shape checks without scanning project
-  files, and pagination via `skip` / `maxMatches` (per-call cap, default 50,
-  max 200; also sets the pagination step). `groupByFile: true` renders a compact
-  one-line-per-file distribution (`L<line>:<col>` locations) instead of each
-  match body — for high-volume searches. `pattern` is optional when a `rule` is
-  given.
+  constraints (`insideKind`, `hasKind`, `hasDescendantKind`, `follows`,
+  `precedes`), raw YAML `rule` passthrough, `validateOnly` for compile/shape
+  checks without scanning project files, and pagination via `skip` / `maxMatches`
+  (per-call cap, default 50, max 200; also sets the pagination step).
+  `nodeKind` is an expert grammar-specific escape hatch: it finds every node of
+  the exact kind used by the target grammar. Node kinds are not universal across
+  languages; use `ast_grep_dump` to discover the kind in the target language. It is mutually exclusive with `pattern` and `rule`.
+  `hasKind` retains ast-grep's immediate-child semantics; use
+  `hasDescendantKind` for an explicit recursive descendant search. A future
+  canonical `find`/`query` facade (call/function/import/etc.) should map to
+  this same synthesized YAML path, with per-language templates and a clear
+  unsupported-concept error — it is intentionally not a second search engine
+  in this patch.
+  `groupByFile: true` renders a compact one-line-per-file distribution
+  (`L<line>:<col>` locations) instead of each match body — for high-volume
+  searches. `pattern` is optional when a `rule` or `nodeKind` is given.
   Results include `details.matchLocations[]` — each hit carries a ready
   `readSlice` (`path`/`offset`/`limit`) for a bounded context read; zero-match
   results include a `suggestedDump` hint pointing at `ast_grep_dump`.