@herbertgao/pi-extensions 2026.8.5 → 2026.8.6

package/node_modules/pi-lens/dist/mcp/server.js

@@ -29,6 +29,7 @@ import { acknowledgeTurnEnd, analyzeFile, analyzeFileFresh, canRebuildPiLens, cr
 import { createAstGrepReplaceTool } from "../tools/ast-grep-replace.js";
 import { createAstGrepSearchTool } from "../tools/ast-grep-search.js";
 import { createLensDiagnosticsTool } from "../tools/lens-diagnostics.js";
+import { peekMcpSessionRuntime } from "../clients/mcp/session.js";
 import { createLspDiagnosticsTool } from "../tools/lsp-diagnostics.js";
 import { createLspNavigationTool } from "../tools/lsp-navigation.js";
 import { computeBuildStamp, STALE_SERVED_BY_FRESH, STALE_WARN_ONLY, StalenessGate, stalenessCheckEnabled, } from "./build-staleness.js";
@@ -411,7 +412,12 @@ const cacheManager = new CacheManager();
 // nothing — a no-op dressed as a fix, not a real parity gap. The 4th arg is left
 // at its default (`async () => {}`, already a no-op) rather than importing and
 // wiring a flush with nothing to flush.
-const lensDiagnosticsTool = createLensDiagnosticsTool(cacheManager, () => DEFAULT_CWD);
+const lensDiagnosticsTool = createLensDiagnosticsTool(cacheManager, () => DEFAULT_CWD, undefined, undefined, undefined, undefined, 
+// #1413 surface parity: validate cached test-runner findings against the
+// same session identity the in-process path uses. Resolved lazily — until
+// an MCP session context exists there is no session to compare against and
+// validation skips the check, which is the honest classification.
+() => peekMcpSessionRuntime());
 const astGrepClient = new AstGrepClient();
 const astGrepSearchTool = createAstGrepSearchTool(astGrepClient);
 const astGrepReplaceTool = createAstGrepReplaceTool(astGrepClient);
@@ -544,7 +550,7 @@ const ALL_TOOLS = [
             properties: {
                 query: {
                     type: "string",
-                    description: "Identifier-ish query, e.g. 'authenticate user'.",
+                    description: "Identifier-ish query, e.g. 'authenticate user'. Mix in composable prefix filters: lang:<kind> (e.g. lang:jsts, lang:python — kinds from file-kinds.ts), file:<substr> (path substring), ext:<ext> (e.g. ext:ts or ext:.ts), each optionally negated with a leading '-' (-file:test). Filters apply before ranking; e.g. 'lang:jsts file:clients/ -file:test rank'. Unknown prefixes/kinds error with the supported list.",
                 },
                 cwd: { type: "string" },
                 limit: {

package/node_modules/pi-lens/dist/tools/activate-tools.js

@@ -18,7 +18,7 @@
  * instead, so calling this tool is harmless, just unnecessary.
  */
 import { Type } from "../clients/deps/typebox.js";
-export function createActivateToolsTool(pi, lazyTools) {
+export function createActivateToolsTool(pi, lazyTools, options = {}) {
     const lazyNames = lazyTools.map((t) => t.name);
     const lazyNameSet = new Set(lazyNames);
     const catalog = lazyTools.map((t) => `${t.name} — ${t.summary}`).join("\n");
@@ -35,7 +35,7 @@ export function createActivateToolsTool(pi, lazyTools) {
                 description: "Names of situational tools to activate (see this tool's description for the catalog).",
             }),
         }),
-        async execute(_toolCallId, params, _signal, _onUpdate) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const requested = Array.isArray(params.tools)
                 ? params.tools.filter((t) => typeof t === "string" && lazyNameSet.has(t))
                 : [];
@@ -53,10 +53,22 @@ export function createActivateToolsTool(pi, lazyTools) {
             }
             // Additive only, per the docs' contract: never drop currently active
             // tools in the same call.
+            // Remember every requested tool, not just the newly-added ones: a
+            // tool that is already active still has to survive the next
+            // fork/reload/resume restore.
+            options.onActivated?.(requested);
             const active = typeof pi.getActiveTools === "function" ? pi.getActiveTools() : [];
-            const merged = [...new Set([...active, ...requested])];
-            if (typeof pi.setActiveTools === "function") {
+            const activeSet = new Set(active);
+            const added = requested.filter((name) => !activeSet.has(name));
+            const merged = [...new Set([...active, ...added])];
+            if (added.length > 0 && typeof pi.setActiveTools === "function") {
                 pi.setActiveTools(merged);
+                options.onMutation?.({
+                    addedCount: added.length,
+                    removedCount: 0,
+                    reason: "lazy_activation",
+                    deferralApplies: options.deferredToolSupport?.(ctx) ?? false,
+                });
             }
             return {
                 content: [
@@ -65,7 +77,7 @@ export function createActivateToolsTool(pi, lazyTools) {
                         text: `Activated: ${requested.join(", ")}. Available starting next turn.`,
                     },
                 ],
-                details: { matches: requested, added: requested },
+                details: { matches: requested, added },
             };
         },
     };

package/node_modules/pi-lens/dist/tools/ast-grep-replace.js

@@ -67,7 +67,12 @@ export function createAstGrepReplaceTool(astGrepClient) {
             }),
             paths: Type.Optional(Type.Array(Type.String(), { description: "Specific files/folders" })),
             insideKind: Type.Optional(Type.String({ description: "Restrict matches to nodes inside an ancestor of this AST node kind. Synthesizes a YAML rule." })),
-            hasKind: Type.Optional(Type.String({ description: "Restrict matches to nodes that contain a descendant of this AST node kind." })),
+            hasKind: Type.Optional(Type.String({
+                description: 'Restrict matches to nodes whose immediate child has this AST node kind (ast-grep default stopBy: neighbor). Example: `hasKind: "await_expression"`.',
+            })),
+            hasDescendantKind: Type.Optional(Type.String({
+                description: "Restrict matches to nodes containing this AST node kind anywhere in their descendants. Explicit recursive form (`stopBy: end`); use this instead of `hasKind` when nesting is not immediate.",
+            })),
             follows: Type.Optional(Type.String({ description: "Restrict matches to nodes that immediately follow a sibling matching this pattern." })),
             precedes: Type.Optional(Type.String({ description: "Restrict matches to nodes that immediately precede a sibling matching this pattern." })),
             apply: Type.Optional(Type.Boolean({ description: "Apply changes (default: false)" })),
@@ -78,7 +83,7 @@ export function createAstGrepReplaceTool(astGrepClient) {
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const startedAt = Date.now();
-            const { pattern, rewrite, paths, apply, strictness, insideKind, hasKind, follows, precedes } = params;
+            const { pattern, rewrite, paths, apply, strictness, insideKind, hasKind, hasDescendantKind, follows, precedes } = params;
             const lang = (params.lang ?? "").replace(/^"|"$/g, "");
             const pathsCount = paths?.length ?? 1;
             const applyFlag = apply ?? false;
@@ -122,10 +127,10 @@ export function createAstGrepReplaceTool(astGrepClient) {
             }
             const searchPaths = paths?.length ? paths : [ctx.cwd || "."];
             // Phase 3: structural-intent params → synthesize YAML with fix: field
-            if (hasStructuralIntent({ insideKind, hasKind, follows, precedes })) {
+            if (hasStructuralIntent({ insideKind, hasKind, hasDescendantKind, follows, precedes })) {
                 let ruleYaml;
                 try {
-                    ruleYaml = synthesizeReplaceRule({ pattern, lang, rewrite, insideKind, hasKind, follows, precedes });
+                    ruleYaml = synthesizeReplaceRule({ pattern, lang, rewrite, insideKind, hasKind, hasDescendantKind, follows, precedes });
                 }
                 catch (err) {
                     logOutcome("error", { errorRaw: String(err) });

package/node_modules/pi-lens/dist/tools/lens-diagnostic-mark.js

@@ -162,7 +162,10 @@ function verifyLine(content, absPath, tool, rule, message, callerLine) {
         };
     }
 }
-export function createLensDiagnosticMarkTool(getCwd) {
+export function createLensDiagnosticMarkTool(getCwd, 
+/** Runtime telemetry identity, when known (#1448 class sweep) — attributed
+ * onto the disposition log alongside the mark. */
+getIdentity) {
     return {
         name: "lens_diagnostic_mark",
         label: "Mark Diagnostic",
@@ -326,7 +329,7 @@ export function createLensDiagnosticMarkTool(getCwd) {
                 message,
                 line: verifiedLine,
                 content,
-            }, disposition, reason);
+            }, disposition, reason, getIdentity?.());
             const verb = disposition === "suppress"
                 ? `suppressed (inline pi-lens-ignore comment written above line ${verifiedLine})`
                 : disposition === "defer"

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

@@ -118,7 +118,7 @@ nextWriteIndex,
 // #798/#338: capture host UI methods synchronously from the active tool event.
 // The returned closure is safe for the later async sweep to invoke because it
 // never dereferences the session-guarded ctx.ui getter.
-captureLspStatusRepaint) {
+captureLspStatusRepaint, getRuntime) {
     return {
         name: "lens_diagnostics",
         label: "Project Diagnostics",
@@ -293,6 +293,7 @@ captureLspStatusRepaint) {
                     onServerReady: repaintLspStatus,
                     pathsScope,
                     nextWriteIndex,
+                    runtime: getRuntime?.(),
                 });
             }
             return formatDeltaMode(cacheManager, cwd, severity, pathsScope);
@@ -935,7 +936,7 @@ async function formatFullMode(cwd, severity, lspService, cacheManager, options =
     // scan, makes it genuinely concurrent — all three phases now race the SAME
     // signal from the same starting point instead of stacking.
     const analyzersPromise = shouldIncludeProjectRunners(options.refreshRunners)
-        ? loadBootstrapClients().then((clients) => fetchFreshProjectDiagnostics(cacheManager, cwd, clients, signal))
+        ? loadBootstrapClients().then((clients) => fetchFreshProjectDiagnostics(cacheManager, cwd, clients, signal, { runtime: options.runtime }))
         : Promise.resolve({
             diagnostics: [],
             runners: [],

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

@@ -14,7 +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 { hashDiagnosticContent, touchCompletedConfirmationPolicy, touchCoverageGap, } 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";
@@ -471,8 +471,15 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
                     // 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" &&
+                    // #1470: `"partial"` counts, for the same reason the local touch
+                    // branch below accepts it — the incumbent's primary confirmed; only
+                    // a named auxiliary did not.
+                    confirmedByTouch: attached.response.confirmation !== undefined &&
                         primaryServerId(absPath) !== "typescript",
+                    // #1470: the incumbent's narrowed verdict, carried as an explicit DTO
+                    // field across the socket. An older incumbent omits it → empty → the
+                    // pre-#1470 handling, unchanged.
+                    unconfirmedServerIds: attached.response.unconfirmedServerIds ?? [],
                     content,
                 };
             }
@@ -526,11 +533,20 @@ async function collectDiagnosticsForFile(absPath, lspService, waitMs, serverScop
     // one; the openFile-only / getDiagnostics fallback leaves it undefined →
     // "unknown", no demotion).
     const binding = usedTouch ? touched?.binding : undefined;
-    const confirmedByTouch = usedTouch && touched?.confirmation === "confirmed";
+    // #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);
     return {
         diagnostics: filtered,
         timedOut,
         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) : [],
         content,
         binding,
     };
@@ -733,7 +749,7 @@ cwd = process.cwd()) {
             };
         }
     }
-    const { diagnostics: rawDiags, timedOut, confirmedByTouch, content: collectedContent, binding, } = await collectDiagnosticsForFile(file, lspService, waitMs, serverScope);
+    const { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, 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
@@ -773,6 +789,14 @@ cwd = process.cwd()) {
     const boundMismatch = binding?.boundToCurrentDisk === false;
     if (boundMismatch)
         confirmation = "unconfirmed";
+    // #1470: an auxiliary cut off by the aux grace timer contributed no evidence
+    // about this file, so a "clean" verdict computed from the merged result would
+    // be claiming coverage this batch does not have. Demote it — that also keeps
+    // the entry out of the workspace cache below, which would otherwise replay the
+    // partial answer as a confirmed clean on every later sweep.
+    if (unconfirmedServerIds.length > 0 && confirmation === "clean") {
+        confirmation = "unconfirmed";
+    }
     const filteredDiags = applySeverityFilter(effectiveRawDiags, severity);
     reconcileWidgetFromLspResult(file, effectiveRawDiags, confirmation, writeIndex, cwd, collectedContent, boundMismatch);
     // #671: only a CONFIRMED outcome ("clean", or a non-empty result — either
@@ -800,7 +824,7 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
     // 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 { diagnostics: rawDiags, timedOut, confirmedByTouch, unconfirmedServerIds, 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,
@@ -842,6 +866,15 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
     const boundMismatch = binding?.boundToCurrentDisk === false;
     if (boundMismatch)
         confirmation = "unconfirmed";
+    // #1470: NARROWED, not collapsed. An auxiliary the aux grace timer cut off makes
+    // the FILE-level verdict unconfirmed — the merged result is missing whatever that
+    // scanner would have said, and this tool is the security lane's read surface. The
+    // PRIMARY's own verdict is untouched (`primaryCoverageGapOnly` below), so a
+    // TypeScript answer stays "confirmed clean" on its own line while an explicit
+    // line names the scanner whose coverage is absent.
+    const primaryCoverageGapOnly = unconfirmedServerIds.length > 0 && confirmation === "clean";
+    if (primaryCoverageGapOnly)
+        confirmation = "unconfirmed";
     const filtered = applySeverityFilter(effectiveRawDiags, severity);
     const total = filtered.length;
     const truncated = total > MAX_DIAGNOSTICS;
@@ -860,7 +893,11 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
                 "file may still have errors that just hadn't been reported yet. " +
                 "Re-check after the server settles, or increase waitMs.");
         }
-        if (unconfirmed) {
+        // #1470: a file demoted ONLY because an auxiliary was cut off must not render
+        // the silent-on-clean text — the primary did confirm, and saying otherwise is
+        // the same overclaim in the opposite direction. The coverage line below names
+        // what is actually missing.
+        if (unconfirmed && !primaryCoverageGapOnly) {
             return (`Primary LSP${primaryId ? ` (${primaryId})` : ""}: unconfirmed — ` +
                 "cannot confirm clean (push-only, silent-on-clean, e.g. classic " +
                 "typescript-language-server never publishes on a clean re-check). " +
@@ -872,9 +909,20 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
         }
         return `Primary LSP${primaryId ? ` (${primaryId})` : ""}: ${primaryDiags.length} diagnostic${primaryDiags.length === 1 ? "" : "s"}.`;
     })();
+    // #1470: this is the narrowing made readable. It states exactly which servers
+    // this result does NOT speak for, so "no auxiliary findings" can never be read
+    // as "the security scanners found nothing".
+    const coverageLine = unconfirmedServerIds.length > 0
+        ? `Auxiliary coverage INCOMPLETE — ${[...unconfirmedServerIds].join(", ")} did not answer within the wait budget, so ${unconfirmedServerIds.length === 1 ? "its findings are" : "their findings are"} NOT included here. This is not a clean bill of health for ${unconfirmedServerIds.length === 1 ? "that scanner" : "those scanners"}; re-check after the next edit, or use waitMs to wait longer.`
+        : undefined;
     let text;
     if (total === 0) {
-        text = [primaryLine, "", unavailable ?? "No auxiliary findings."].join("\n");
+        text = [
+            primaryLine,
+            "",
+            unavailable ?? "No auxiliary findings.",
+            ...(coverageLine ? [coverageLine] : []),
+        ].join("\n");
     }
     else {
         const lines = [primaryLine, ""];
@@ -885,6 +933,8 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
             lines.push(`Auxiliary findings (${auxiliaryDiags.length}):`);
             lines.push(...auxiliaryDiags.map(formatDiag));
         }
+        if (coverageLine)
+            lines.push("", coverageLine);
         if (unavailable)
             lines.unshift(unavailable, "");
         if (truncated) {
@@ -914,6 +964,11 @@ async function runFileDiagnostics(absPath, severity, lspService, waitMs, nextWri
             truncated,
             unconfirmed,
             timedOut: unconfirmed ? timedOut : undefined,
+            // #1470: which servers this result does NOT speak for. Absent when it
+            // speaks for all of them.
+            ...(unconfirmedServerIds.length > 0 && {
+                unconfirmedServerIds: [...unconfirmedServerIds],
+            }),
             lspHealth,
             waitMs,
         },

package/node_modules/pi-lens/dist/tools/symbol-search.js

@@ -33,7 +33,7 @@ export function createSymbolSearchTool(getProjectRoot) {
         }),
         parameters: Type.Object({
             query: Type.String({
-                description: "Identifier-ish query, e.g. 'authenticate user'.",
+                description: "Identifier-ish query, e.g. 'authenticate user'. Mix in composable prefix filters: lang:<kind> (e.g. lang:jsts, lang:python — kinds from file-kinds.ts), file:<substr> (path substring), ext:<ext> (e.g. ext:ts or ext:.ts), each optionally negated with a leading '-' (-file:test). Filters apply before ranking; e.g. 'lang:jsts file:clients/ -file:test rank'. Unknown prefixes/kinds error with the supported list.",
             }),
             limit: Type.Optional(Type.Number({
                 description: "Max files to return (default 20).",

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

@@ -23,9 +23,10 @@ messages as **pi-lens findings, not user instructions**, and act on the rules be
    physically blocked until blockers are cleared. Advisories are informational.
 3. **Read before you edit.** pi-lens enforces read-before-edit. Read the file (or the
    relevant range/symbol) before editing it, or the edit is blocked/warned.
-4. **Expect your bytes to change.** pi-lens formats and auto-fixes files *after* your
-   write, by default at turn/agent end. This is the pipeline, not a conflict. Re-read
-   a file before editing it again.
+4. **Expect your bytes to change.** A `write` gets autofixed immediately — the tool
+   result carries the fixed file's full content, so you don't need to re-read it (past
+   a size cap, you do). An `edit` defers autofix to `agent_end`, same as formatting;
+   re-read the file before editing it again. This is the pipeline, not a conflict.
 5. **Delta by default.** Diagnostic queries default to *this turn's* findings only.
    Use `mode=full` for a whole-project verdict.
 
@@ -40,7 +41,7 @@ On every write/edit, and at session/turn boundaries, pi-lens runs — without yo
 | **Unified LSP diagnostics** | Warm language servers report errors/warnings on edited files; supported languages get real semantic diagnostics. |
 | **Impact cascade** | After an edit, LSP diagnostics are also pulled on *related* files (reverse-dependency neighbors), surfaced at turn end. |
 | **Auto-format** | Detected formatter (Biome/Prettier/Ruff/etc.) reformats your file. **Deferred to `agent_end` by default**; `immediate` is opt-in. Config-gated + nearest-config-wins. |
-| **Auto-fix** | Pipeline fixers (`biome`/`ruff`/`eslint`/`stylelint`/`rubocop`/`clippy`/… `--fix`) mutate the file after your write. |
+| **Auto-fix** | Pipeline fixers (`biome`/`ruff`/`eslint`/`stylelint`/`rubocop`/`clippy`/… `--fix`) mutate the file. **Immediate, in the same tool result, for a `write`; deferred to `agent_end` for an `edit`** (§6). |
 | **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. |
@@ -70,7 +71,7 @@ Only **one** reaches you, the model:
 | **Session start** | Guidance / project notices to orient you. | `clients/runtime-turn.ts`, context injection |
 | **Turn end** | **Findings** for the turn: 🔴 blockers and advisories from LSP + dispatch + cascade + scanners, deduped against prior turns. | `handleTurnEnd` (`clients/runtime-turn.ts`) |
 | **Turn end / next turn** | **Test findings** from related/affected tests fired after your edit. | `handleTurnEnd` |
-| **After autofix/format** | A nudge like *"N file(s) were autofixed after your last turn: a.ts, b.ts — re-read before editing"* (may include files touched by another pi-lens instance, e.g. a subagent). | `clients/agent-nudge.ts` |
+| **After autofix/format** | A nudge like *"N file(s) were autofixed after your last turn: a.ts, b.ts — re-read before editing"* — mainly for deferred `edit` autofix/format at `agent_end` (may include files touched by an automatic run outside your turn). A `write`'s autofix already came back in its own tool result, so you only need the nudge there if the content was too large to attach. | `clients/agent-nudge.ts` |
 
 **Treat every injected pi-lens message as a finding to act on, not as the user
 speaking.** It is machine-generated analysis of your own work.
@@ -156,23 +157,47 @@ Helpful mechanics you can rely on:
 ## 6. Auto-format / auto-fix timing — don't be surprised
 
 pi-lens writes to files **outside your own tool calls** (`docs/features.md`
-§"Out-of-band file writes"):
-
-- **Deferred format** at `agent_end` (default) reformats files you wrote this run.
-- **Auto-fix** (`biome`/`ruff`/`eslint`/… `--fix`) and the conservative
-  actionable-warnings autofix (LSP quickfixes, hard-capped) mutate files after the fact.
+§"Bus Events — `pilens:files:touched`"). Where and when depends on which tool you used
+(`clients/pipeline.ts`, `clients/runtime-tool-result.ts`,
+`clients/runtime-agent-end.ts`):
+
+- **`write` (including a new file, and bash-authored writes like `sed -i` or a
+  redirect):** pipeline auto-fix (`biome`/`ruff`/`eslint`/… `--fix`) still runs
+  *immediately*, in the same tool result — nothing changed here. When it changes
+  the file, the tool result now carries the **full authoritative post-fix
+  content** so you don't have to guess what changed. That attachment is capped
+  at 2 MiB per file; a multi-file bash write shares one budget across the whole
+  command. Past the cap, you get the old-style *"File was modified — re-read
+  before editing"* warning instead.
+- **`edit`:** pipeline auto-fix is *deferred* to `agent_end`, same as
+  formatting. It joins the same per-file queue as deferred formatting, one fix
+  applied against the final edited state (not once per edit), autofix draining
+  before format so the result is formatter-stable. Diagnostics computed at edit
+  time reflect the *unfixed* disk state — a lint finding that autofix would have
+  cleared may show up and then quietly disappear once `agent_end` drains.
+- **`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.
+- The conservative actionable-warnings autofix (LSP quickfixes, hard-capped)
+  is unchanged: it always runs at `agent_end`.
 
 Consequences for you:
 
 - Your exact written bytes may be reformatted/fixed. **This is expected pipeline
   behavior, not a conflict or a failed write.**
-- A file you wrote last turn may have changed on disk. **Re-read before editing it
-  again** (this also keeps the read-guard happy — the autofix nudge tells you which
-  files changed).
+- **`write`:** trust the authoritative content attached to the tool result; only
+  re-read if you see the size-cap warning, or if a *different* file (a side
+  effect of the same bash command) was touched.
+- **`edit`:** the file may change on disk after your turn ends. **Re-read before
+  editing it again** (this also keeps the read-guard happy — the autofix nudge
+  tells you which files changed).
 - **Delta mode:** `lens_diagnostics` shows only diagnostics *introduced this turn* by
   default (`mode=delta`). Use `mode=all` (cache-wide) or `mode=full` (fresh scan) for
   the complete picture.
 
+See `AGENTS.md`'s "Per-edit autofix mutation boundary (#1414)" invariant for the
+authoritative routing rules.
+
 ---
 
 ## 7. Tools & commands you can use

package/node_modules/pi-lens/docs/ast-grep_rules_catalog.md

@@ -2,7 +2,7 @@
 
 <!-- GENERATED by scripts/gen-rule-catalogs.mjs — do not edit by hand. Run `npm run docs:rule-catalogs` after changing rules. -->
 
-pi-lens bundles **438 enabled** ast-grep rules (254 pi-lens-authored + 184 vendored from CodeRabbit) across **16 languages**, plus 16 disabled.
+pi-lens bundles **446 enabled** ast-grep rules (262 pi-lens-authored + 184 vendored from CodeRabbit) across **16 languages**, plus 16 disabled.
 
 See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `rules/ast-grep-rules/rules/` (pi-lens), `rules/ast-grep-rules/coderabbit/rules/` (vendored).
 
@@ -133,7 +133,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `use-of-sha1-java` | warning | CodeRabbit | Detected SHA1 hash algorithm which is considered insecure. SHA1 is not collision resistant and is therefore not suitable as a cryptographic… |
 | `weak-ssl-context-java` | warning | CodeRabbit | 'An insecure SSL context was detected. TLS versions 1.0, 1.1, and all SSL versions are considered weak encryption and are deprecated. Use S… |
 
-### JavaScript (76)
+### JavaScript (79)
 
 | Rule | Severity | Source | Description |
 |---|---|---|---|
@@ -161,6 +161,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-case-declarations-js` | error | pi-lens | Unexpected lexical declaration in case block — wrap in braces to restrict scope |
 | `no-compare-neg-zero-js` | error | pi-lens | Disallow comparing against -0 |
 | `no-cond-assign-js` | error | pi-lens | Expected a conditional expression and instead saw an assignment. |
+| `no-conditional-empty-object-spread-js` | hint | pi-lens | Conditional empty-object spread — use an explicit if/else to omit fields |
 | `no-console-except-error-js` | warning | pi-lens | Avoid console.log/debug/warn in production code — use a logger or console.error inside catch only |
 | `no-constant-condition-js` | error | pi-lens | Unexpected constant condition |
 | `no-discarded-error-js` | error | pi-lens | new Error() result discarded — add 'throw' or assign to a variable |
@@ -180,6 +181,8 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-new-wrappers-js` | error | pi-lens | Do not use 'new' with wrapper objects — use literal primitives instead |
 | `no-open-redirect-js` | error | pi-lens | Potential open redirect vulnerability — validate redirect URLs |
 | `no-prototype-builtins-js` | error | pi-lens | Use Object.hasOwn() or Object.prototype.hasOwnProperty.call() instead of calling methods directly on the object |
+| `no-reflect-apply-js` | warning | pi-lens | Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead |
+| `no-reflect-get-js` | warning | pi-lens | Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead |
 | `no-single-promise-in-promise-methods-js` | warning | pi-lens | Promise.all/race with a single promise is unnecessary — await it directly |
 | `no-sql-in-code-js` | error | pi-lens | Raw SQL string in code — use query builder or ORM |
 | `no-throw-string-js` | error | pi-lens | Throw Error objects, not strings |
@@ -401,7 +404,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `redundant-usestate-type` | info | pi-lens | `useState<TYPE>(...)` where TYPE is a primitive redundant — TS can infer it from the initial value |
 | `unnecessary-react-hook` | warning | pi-lens | Function with a `use*` name does not call any other React hook — rename to a plain function |
 
-### TypeScript (120)
+### TypeScript (125)
 
 | Rule | Severity | Source | Description |
 |---|---|---|---|
@@ -431,8 +434,10 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-await-in-promise-methods` | warning | pi-lens | Do not await inside Promise.all/allSettled — pass the promises directly |
 | `no-bare-host-path-in-win32-branch` | warning | pi-lens | Use win32 path operations inside a branch committed to Windows path semantics |
 | `no-case-declarations` | error | pi-lens | Unexpected lexical declaration in case block — wrap in braces to restrict scope |
+| `no-chained-type-assertions` | warning | pi-lens | Chained type assertion (x as A as B) — stacking assertions with no runtime check between them |
 | `no-compare-neg-zero` | error | pi-lens | Disallow comparing against -0 |
 | `no-cond-assign` | error | pi-lens | Expected a conditional expression and instead saw an assignment. |
+| `no-conditional-empty-object-spread` | hint | pi-lens | Conditional empty-object spread — use an explicit if/else to omit fields |
 | `no-console-except-error` | warning | pi-lens | Avoid console.log/debug/warn in production code — use a logger or console.error inside catch only |
 | `no-constant-condition` | error | pi-lens | Unexpected constant condition |
 | `no-demeter-message-chain` | warning | pi-lens | Message chain (Law of Demeter) — navigating 3+ deep through accessors couples the caller to the whole path. |
@@ -458,6 +463,8 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-prototype-builtins` | error | pi-lens | Use Object.hasOwn() or Object.prototype.hasOwnProperty.call() instead of calling methods directly on the object |
 | `no-prototype-builtins-native` | hint | pi-lens | Use Object.hasOwn() instead of hasOwnProperty() — ES2022 standard |
 | `no-raw-json-store-write` | warning | pi-lens | Use the atomic write seam for JSON stores instead of writeFileSync |
+| `no-reflect-apply` | warning | pi-lens | Reflect.apply() — use a typed call (fn.apply(...) or fn(...args)) instead |
+| `no-reflect-get` | warning | pi-lens | Reflect.get(obj, key) — use a typed property access (obj.prop or obj[key]) instead |
 | `no-relative-cross-package-import` | info | pi-lens | Avoid relative imports across package boundaries (../../). Use absolute imports (@app/..., @components/...) for better agent reasoning abou… |
 | `no-return-await` | warning | pi-lens | Unnecessary 'await' in return statement — use direct return instead |
 | `no-single-promise-in-promise-methods` | warning | pi-lens | Promise.all/race with a single promise is unnecessary — await it directly |
@@ -466,6 +473,7 @@ See [`docs/custom-rules.md`](custom-rules.md) to add your own. Rule sources: `ru
 | `no-throw-string` | error | pi-lens | Throw Error objects, not strings |
 | `no-typeof-undefined` | hint | pi-lens | Use === undefined instead of typeof x === 'undefined' |
 | `no-unimplemented-stub` | warning | pi-lens | Unimplemented stub — function was scaffolded but never completed |
+| `no-unknown-laundering` | warning | pi-lens | type alias to bare 'unknown' — give the alias real shape or inline 'unknown' at the one call site that needs it |
 | `no-unnecessary-array-flat-depth` | hint | pi-lens | .flat(1) is the default depth — just use .flat() |
 | `no-useless-length-check` | warning | pi-lens | Use .some() instead of .filter().length check — short-circuits at first match |
 | `no-useless-promise-resolve-reject` | warning | pi-lens | Unnecessary Promise.resolve/reject wrapping — return the value directly |

package/node_modules/pi-lens/docs/features.md

@@ -40,6 +40,19 @@ Repositories can disable all immediate and deferred auto-format mutations with
 keeping formatter detection, lint dispatch, LSP synchronization, and
 diagnostics available.
 
+**Auto-fix timing depends on the tool.** A `write` (new file, full overwrite,
+or a bash-authored write like `sed -i`/a redirect) still gets pipeline autofix
+immediately, in the same tool result; when it changes the file, the result
+carries the full authoritative post-fix content (capped at 2 MiB per file, one
+shared budget across a multi-file bash write — past that it degrades to a
+re-read warning). An `edit` defers autofix to `agent_end`, where it joins the
+same per-file deferred-mutation queue as deferred formatting — one coalesced
+record per file (`kinds: {autofix, format}`), autofix draining before format
+so the final state is formatter-stable. A `write` immediately followed by an
+`edit` on the same file in the same turn demotes the write's autofix to
+deferred too. See `clients/pipeline.ts`, `clients/runtime-tool-result.ts`, and
+`clients/runtime-agent-end.ts`.
+
 Deferred formatting (the `agent_end` default) runs with **bounded
 concurrency**: at most three formatter subprocesses in flight at once, with
 results applied in admission order and cooperative yields between files, so a
@@ -155,7 +168,7 @@ When `actionableWarnings.autoFix.enabled` is set in global or project config (or
 
 ### Bus Events — `pilens:files:touched` (#482)
 
-pi-lens writes files **outside the agent's own tool calls**: dispatch autofix (biome/ruff/eslint/stylelint/sqlfluff/rubocop/ktlint/rust-clippy/dart-fix/golangci-lint/detekt/ktfmt/markdownlint/oxlint --fix) and formatter runs (immediate or deferred-at-`agent_end`) both mutate files after the fact, and the conservative actionable-warnings autofix above applies LSP quickfixes the same way. Other extensions in the same session that track file mutations are otherwise blind to those writes.
+pi-lens writes files **outside the agent's own tool calls**: dispatch autofix (biome/ruff/eslint/stylelint/sqlfluff/rubocop/ktlint/ktfmt/rust-clippy/dart-fix/golangci-lint/detekt/markdownlint/oxlint --fix) mutates the file immediately for a `write` and at `agent_end` for a deferred `edit` (see "Formatters" above); formatter runs (immediate or deferred-at-`agent_end`) do the same; and the conservative actionable-warnings autofix above applies LSP quickfixes at `agent_end` the same way. Other extensions in the same session that track file mutations are otherwise blind to those writes — this event, published either way, is how they find out.
 
 pi-lens broadcasts them on pi's shared in-process event bus (`pi.events`, exposed to every extension via the `ExtensionAPI`) as a single named event:
 

package/node_modules/pi-lens/docs/globalconfig.md

@@ -25,6 +25,17 @@ Each runtime toggle is settable from the CLI *and* from `config.json`. The two a
 | `--lens-actionable-warning-autofix` | `actionableWarnings.autoFix.enabled` | `false` |
 | `--lens-actionable-warning-all` | `actionableWarnings.deltaOnly` (`false`) | `true` |
 | `--lens-compact-tool-line` | `ui.compactToolLine` | `false` |
+| `--no-lazy-tools` | `tools.lazy` | `true` |
+
+By default pi-lens registers six situational tools (the `ast_grep_*` family,
+`lsp_navigation`, `lens_diagnostic_mark`) inactive and exposes a small loader,
+`pi_lens_activate_tools`, that the model calls to activate the ones it needs.
+`--no-lazy-tools` turns that off: every pi-lens tool is active from the first
+turn and pi-lens never changes the tool list. Use it if you would rather spend
+the tokens of a longer tool list than have the list change mid-session. The
+loader tool is still registered and still describes itself as activating
+inactive tools; under this flag those tools are already active, so calling it
+does nothing.
 
 Keys are positive (`"enabled": true` means the feature runs), so a `--no-*` flag corresponds to setting its key `false`. A `no-*` flag on the command line is a one-way switch: it can disable, never re-enable, so `--no-lsp` wins over `lsp.enabled: true` but nothing on the CLI overrides `lsp.enabled: false`. Set the key back to `true` to re-enable.
 

package/node_modules/pi-lens/docs/servercapabilities.md

@@ -6,7 +6,7 @@ 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-08-14 on linux; 29 servers captured, 14 unavailable._
+_Last generated: 2026-08-15 on linux; 29 servers captured, 14 unavailable._
 
 ## Diagnostic mode + navigation/edit operations
 

package/node_modules/pi-lens/docs/settings.md

@@ -70,6 +70,12 @@ column is the effective behavior when nothing is set.
 | `--lens-actionable-warning-autofix` | `actionableWarnings.autoFix.enabled` | project | **off** |
 | `--lens-actionable-warning-all` | `actionableWarnings.deltaOnly` (`false`) | global | `deltaOnly` **on** (report this turn only) |
 | `--lens-compact-tool-line` | `ui.compactToolLine` | global | **off** (two-row tool rendering) |
+| `--no-lazy-tools` | `tools.lazy` | global | lazy tools **on** (six situational tools start inactive) |
+
+`--no-lazy-tools` keeps every pi-lens tool active for the whole session, so the
+advertised tool list never changes. The `pi_lens_activate_tools` loader stays
+registered and keeps its usual description; under this flag the tools it names
+are already active, so calling it is a no-op.
 
 `--lens-guard` is **EXPERIMENTAL and strictly opt-in**. When enabled, actual
 `git commit`/`git push` commands are blocked only for current, structured

package/node_modules/pi-lens/docs/usage.md

@@ -18,17 +18,34 @@ pi-lens hooks into the pi agent lifecycle:
 
 ## On-write pipeline
 
-For each write/edit, pi-lens runs a language-aware pipeline:
-
-1. Format queue / immediate formatting when configured.
-2. Safe autofix from tools with deterministic fix support.
+For each write/edit, pi-lens runs a language-aware pipeline. Format and safe
+autofix (steps 1–2) run on different schedules depending on the tool:
+
+- **`write`** (new file, full overwrite, bash-authored write): autofix runs
+  immediately, in the same tool result, carrying the fixed file's full content
+  back to the agent when it fits under the per-file cap.
+- **`edit`**: autofix defers to `agent_end`, joining the same per-file queue as
+  deferred formatting; autofix drains before format so the final state is
+  formatter-stable. A `write` followed by an `edit` on the same file in the
+  same turn demotes the write's autofix to deferred too.
+
+1. Format queue / immediate formatting when configured (deferred to
+   `agent_end` for an `edit` even under `--immediate-format`, so it lands
+   after autofix reformats the file).
+2. Safe autofix from tools with deterministic fix support — immediate for
+   `write`, deferred to `agent_end` for `edit` (see above).
 3. LSP file sync and diagnostic wait.
 4. Parallel dispatch runners: LSP, ast-grep, tree-sitter, fact rules, and
-   language-specific linters/security scanners.
+   language-specific linters/security scanners. For a deferred `edit`, these
+   run against the not-yet-autofixed disk state, so a lint finding autofix
+   would have cleared may appear here and resolve itself at `agent_end`.
 5. Cascade diagnostics for likely affected neighbors.
 6. Deduplication and routing to blockers, actionable warnings, or code-quality
    history.
 
+See [`docs/agent-guide.md`](agent-guide.md#6-auto-format--auto-fix-timing--dont-be-surprised)
+for the consumer-facing version of this routing.
+
 ## Agent tools
 
 pi-lens exposes these high-value tools to agents:
@@ -92,6 +109,7 @@ pi --no-opengrep         # Disable the Opengrep security scanner (default-on aux
 pi --no-read-guard       # Disable the read-before-edit behavior monitor
 pi --lens-turn-summary   # Persist a per-turn summary of diagnostics, autofixes, and autoformats
 pi --lens-compact-tool-line   # Render tool results as one compact, theme-aware line (closes #1327)
+pi --no-lazy-tools       # Keep every pi-lens tool active instead of activating the situational ones on demand
 
 # Actionable warnings (all default off)
 pi --lens-actionable-warnings          # Report fixable warnings at turn end