@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

package/node_modules/pi-lens/README.md

@@ -28,6 +28,11 @@ pi-lens gives AI coding agents fast, language-aware feedback while they write/ed
 - `/lens-map` — interactive HTML dependency map of the project
 - Read-guard and edit-autopatch support to reduce bad edits
 - Background security/dependency scans for opted-in projects
+- Runtime health telemetry (`/lens-health`) including a bounded degradation
+  ledger for silently-degraded behavior (LSP breakers, formatter
+  skips/failures, idle evictions, timeouts)
+- MCP server (experimental) so Claude Code or any MCP client can drive the
+  same diagnostics/read-substitute tools pi-lens exposes to pi
 
 ## Install
 
@@ -70,6 +75,8 @@ pi install git:github.com/apmantza/pi-lens
   and formatters
 - [Dependencies](docs/dependencies.md) — auto-install policy and external tools
 - [Custom rules](docs/custom-rules.md) — project ast-grep and tree-sitter rules
+- [MCP server](docs/mcp.md) — experimental MCP server for Claude Code and
+  other MCP clients
 
 ## Contributing
 
@@ -206,6 +213,12 @@ Thanks goes to these wonderful people:
     </tr>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/pppobear"><img src="https://avatars.githubusercontent.com/u/21952175?v=4" width="100px;" alt=""/><br /><sub><b>pppobear</b></sub></a><br /><a href="#bug-pppobear" title="Bug reports">🐛</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/3choBoomer"><img src="https://avatars.githubusercontent.com/u/521828?v=4" width="100px;" alt=""/><br /><sub><b>Nathan Cooke</b></sub></a><br /><a href="#code-3choBoomer" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/white-hat"><img src="https://avatars.githubusercontent.com/u/922988?v=4" width="100px;" alt=""/><br /><sub><b>Eli Stark</b></sub></a><br /><a href="#code-white-hat" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/marvtub"><img src="https://avatars.githubusercontent.com/u/33159023?v=4" width="100px;" alt=""/><br /><sub><b>Marvin Aziz</b></sub></a><br /><a href="#code-marvtub" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/mjfaga"><img src="https://avatars.githubusercontent.com/u/7584015?v=4" width="100px;" alt=""/><br /><sub><b>Mark Faga</b></sub></a><br /><a href="#code-mjfaga" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/aeturnal"><img src="https://avatars.githubusercontent.com/u/219271200?v=4" width="100px;" alt=""/><br /><sub><b>aeturnal</b></sub></a><br /><a href="#code-aeturnal" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/floatGray"><img src="https://avatars.githubusercontent.com/u/44295302?v=4" width="100px;" alt=""/><br /><sub><b>floatGray</b></sub></a><br /><a href="#code-floatGray" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

package/node_modules/pi-lens/dist/clients/actionable-warnings.js

@@ -4,9 +4,16 @@ import * as path from "node:path";
 import { applyWorkspaceEdit } from "./lsp/edits.js";
 import { getLSPService } from "./lsp/index.js";
 import { normalizeMapKey } from "./path-utils.js";
+import { recordLspMutationBatch, } from "./lsp-mutation.js";
 import { toRunnerDisplayPath } from "./dispatch/runner-context.js";
 import { logActionableWarningsEvent } from "./actionable-warnings-logger.js";
 import { getProjectDataDir } from "./file-utils.js";
+import { commitDurableStore } from "./durable-store.js";
+let beforeWarningStateLockForTests = null;
+/** Test seam for a sibling process commit immediately before lock acquisition. */
+export function _setBeforeWarningStateLockForTests(hook) {
+    beforeWarningStateLockForTests = hook;
+}
 function normalizeMessage(message) {
     return message.replace(/\s+/g, " ").trim().toLowerCase();
 }
@@ -53,10 +60,9 @@ function serializeAction(action) {
         skipReason: safety.reason,
     };
 }
-function readSuppressionState(cwd) {
-    const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
+function deserializeSuppressionState(contents) {
     try {
-        const parsed = JSON.parse(fs.readFileSync(statePath, "utf-8"));
+        const parsed = JSON.parse(contents ?? "");
         return parsed && typeof parsed === "object"
             ? parsed
             : {};
@@ -65,23 +71,49 @@ function readSuppressionState(cwd) {
         return {};
     }
 }
-function updateWarningState(cwd, warnings) {
+function readSuppressionState(cwd) {
     const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
-    const now = new Date().toISOString();
-    const state = readSuppressionState(cwd);
-    state.warnings ??= {};
-    for (const warning of warnings) {
-        const existing = state.warnings[warning.id] ?? {};
-        state.warnings[warning.id] = {
-            ...existing,
-            status: existing.status ?? "active",
-            firstSeenAt: existing.firstSeenAt ?? now,
-            lastSeenAt: now,
-            seenCount: (existing.seenCount ?? 0) + 1,
-        };
+    try {
+        return deserializeSuppressionState(fs.readFileSync(statePath, "utf8"));
+    }
+    catch {
+        return {};
     }
+}
+function updateWarningState(cwd, warnings) {
+    const statePath = path.join(getProjectDataDir(cwd), "cache", "actionable-warning-state.json");
     fs.mkdirSync(path.dirname(statePath), { recursive: true });
-    fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+    const hook = beforeWarningStateLockForTests;
+    beforeWarningStateLockForTests = null;
+    hook?.();
+    commitDurableStore({
+        path: statePath,
+        deserialize: deserializeSuppressionState,
+        merge: (state) => {
+            const now = new Date().toISOString();
+            state.warnings ??= {};
+            for (const warning of warnings) {
+                const existing = state.warnings[warning.id] ?? {};
+                state.warnings[warning.id] = {
+                    ...existing,
+                    status: existing.status ?? "active",
+                    firstSeenAt: existing.firstSeenAt ?? now,
+                    lastSeenAt: now,
+                    seenCount: (existing.seenCount ?? 0) + 1,
+                };
+            }
+            return state;
+        },
+        serialize: (state) => JSON.stringify(state, null, 2),
+        waitMs: 2_000,
+        retryMs: 10,
+        timeoutMessage: "timed out acquiring actionable warning store lock",
+        onContention: "skip-log",
+        logContention: () => logActionableWarningsEvent({
+            event: "warning_state_write_dropped",
+            metadata: { reason: "lock_contention" },
+        }),
+    });
 }
 function suppressionFor(cwd, id) {
     const entry = readSuppressionState(cwd).warnings?.[id];
@@ -452,6 +484,8 @@ export async function applyConservativeActionableWarningFixes(args) {
         skipped: [],
     };
     const changedFiles = new Set();
+    const appliedResults = [];
+    let failedCount = 0;
     const lspService = getLSPService();
     const maxFixes = Math.max(0, args.maxFixes ?? 5);
     for (const file of args.report.files) {
@@ -504,12 +538,23 @@ export async function applyConservativeActionableWarningFixes(args) {
                     continue;
                 }
                 const edit = selected.edit;
-                const applied = await applyWorkspaceEdit(edit, args.cwd);
+                const applied = await applyWorkspaceEdit(edit, args.cwd, args.mutationContext
+                    ? { mutationContext: { ...args.mutationContext, emitSummary: false } }
+                    : undefined);
+                appliedResults.push(applied);
                 for (const changedFile of applied.files)
                     changedFiles.add(changedFile);
                 summary.applied++;
             }
             catch (err) {
+                failedCount++;
+                const partial = err
+                    .appliedWorkspaceEdit;
+                if (partial) {
+                    appliedResults.push(partial);
+                    for (const changedFile of partial.files)
+                        changedFiles.add(changedFile);
+                }
                 const message = err instanceof Error ? err.message : String(err);
                 args.dbg?.(`actionable_warnings_autofix failed for ${warning.id}: ${message}`);
                 summary.skipped.push({ id: warning.id, reason: "apply_failed" });
@@ -517,6 +562,16 @@ export async function applyConservativeActionableWarningFixes(args) {
         }
     }
     summary.changedFiles = [...changedFiles];
+    if (args.mutationContext && (summary.considered > 0 || appliedResults.length > 0)) {
+        recordLspMutationBatch(args.mutationContext, {
+            results: appliedResults,
+            considered: summary.considered,
+            completed: summary.applied,
+            failedCount,
+            status: failedCount > 0 ? "failed" : appliedResults.length > 0 ? "success" : "skipped",
+            bookkeep: false,
+        });
+    }
     return summary;
 }
 export function formatActionableWarningsAdvisory(report) {

package/node_modules/pi-lens/dist/clients/advisory-provenance.js

@@ -0,0 +1,314 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { logLatency } from "./latency-logger.js";
+import { normalizeMapKey, toProjectRelativePath } from "./path-utils.js";
+import { resolveRunnerPath } from "./dispatch/runner-context.js";
+export const MAX_ADVISORY_AFFECTED_FILES = 256;
+export function advisoryPathKey(filePath, cwd) {
+    return normalizeMapKey(path.resolve(cwd, filePath));
+}
+/** Shared with git guard: there is one SHA-256 implementation for advisories. */
+export function advisoryFileHash(filePath) {
+    try {
+        return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+    }
+    catch (error) {
+        const code = error.code ?? "unknown";
+        return code === "ENOENT" ? "missing" : `unreadable:${code}`;
+    }
+}
+function snapshotOne(filePath, cwd, role) {
+    const resolved = path.resolve(cwd, filePath);
+    try {
+        const stat = fs.statSync(resolved);
+        return {
+            path: resolved,
+            role,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+            sha256: advisoryFileHash(resolved),
+        };
+    }
+    catch (error) {
+        const code = error.code ?? "unknown";
+        return {
+            path: resolved,
+            role,
+            mtimeMs: -1,
+            size: -1,
+            sha256: code === "ENOENT" ? "missing" : `unreadable:${code}`,
+        };
+    }
+}
+export function snapshotAdvisoryProvenance(args) {
+    const seen = new Set();
+    const files = [];
+    for (const file of args.files) {
+        const key = advisoryPathKey(file.path, args.cwd);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        files.push(snapshotOne(file.path, args.cwd, file.role));
+    }
+    return {
+        revision: {
+            sessionId: args.runtime.telemetrySessionId,
+            projectSeq: args.runtime.projectSeq,
+            turnIndex: args.runtime.turnIndex,
+            generation: args.generation,
+            capturedAt: args.capturedAt ?? Date.now(),
+        },
+        files,
+        ...(args.truncated ? { truncated: true } : {}),
+    };
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isCapturedHash(value) {
+    return typeof value === "string" &&
+        (/^[a-f0-9]{64}$/.test(value) || value === "missing" || value.startsWith("unreadable:"));
+}
+function isWellFormed(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    const revision = record.revision;
+    return !!revision && typeof revision.sessionId === "string" &&
+        isFiniteNumber(revision.projectSeq) && isFiniteNumber(revision.turnIndex) &&
+        isFiniteNumber(revision.generation) && isFiniteNumber(revision.capturedAt) &&
+        Array.isArray(record.files) && record.files.length > 0 && record.files.every((file) => !!file && typeof file.path === "string" &&
+        (file.role === "source" || file.role === "test" || file.role === "affected") &&
+        isFiniteNumber(file.mtimeMs) && isFiniteNumber(file.size) &&
+        isCapturedHash(file.sha256));
+}
+export function validateAdvisoryProvenance(record, cwd, runtime) {
+    if (!isWellFormed(record.provenance)) {
+        return { status: "unknown", reasons: ["malformed-or-legacy-provenance"], allFilesDeleted: false, changedPathCount: 0 };
+    }
+    const provenance = record.provenance;
+    const reasons = [];
+    let unknown = provenance.truncated === true;
+    if (unknown)
+        reasons.push("truncated-provenance");
+    if (runtime) {
+        if (provenance.revision.sessionId !== runtime.telemetrySessionId)
+            reasons.push("session-mismatch");
+    }
+    let deletedFiles = 0;
+    const changedPaths = new Set();
+    for (const captured of provenance.files) {
+        const resolved = path.resolve(cwd, captured.path);
+        const reasonsBefore = reasons.length;
+        let stat;
+        try {
+            stat = fs.statSync(resolved);
+        }
+        catch (error) {
+            const code = error.code ?? "unknown";
+            if (code === "ENOENT") {
+                if (captured.sha256 !== "missing") {
+                    deletedFiles += 1;
+                    reasons.push(`missing:${advisoryPathKey(resolved, cwd)}`);
+                    changedPaths.add(advisoryPathKey(resolved, cwd));
+                }
+            }
+            else {
+                unknown = true;
+                reasons.push(`unreadable:${advisoryPathKey(resolved, cwd)}:${code}`);
+                changedPaths.add(advisoryPathKey(resolved, cwd));
+            }
+            continue;
+        }
+        if (captured.sha256.startsWith("unreadable:")) {
+            unknown = true;
+            reasons.push(`capture-unreadable:${advisoryPathKey(resolved, cwd)}`);
+            changedPaths.add(advisoryPathKey(resolved, cwd));
+            continue;
+        }
+        if (captured.sha256 === "missing") {
+            reasons.push(`created:${advisoryPathKey(resolved, cwd)}`);
+            changedPaths.add(advisoryPathKey(resolved, cwd));
+            continue;
+        }
+        if (stat.mtimeMs !== captured.mtimeMs || stat.size !== captured.size) {
+            reasons.push(`metadata-changed:${advisoryPathKey(resolved, cwd)}`);
+        }
+        const currentHash = advisoryFileHash(resolved);
+        if (currentHash.startsWith("unreadable:")) {
+            unknown = true;
+            reasons.push(`${currentHash}:${advisoryPathKey(resolved, cwd)}`);
+        }
+        else if (currentHash !== captured.sha256) {
+            reasons.push(`content-changed:${advisoryPathKey(resolved, cwd)}`);
+        }
+        if (reasons.length > reasonsBefore)
+            changedPaths.add(advisoryPathKey(resolved, cwd));
+    }
+    const allFilesDeleted = deletedFiles === provenance.files.length;
+    if (unknown)
+        return { status: "unknown", reasons, allFilesDeleted, changedPathCount: changedPaths.size };
+    return reasons.length > 0
+        ? { status: "superseded", reasons, allFilesDeleted, changedPathCount: changedPaths.size }
+        : { status: "current", reasons: [], allFilesDeleted, changedPathCount: 0 };
+}
+// ── Finding-cited path existence (#1461 slice 1) ──────────────────────────────
+//
+// `validateAdvisoryProvenance` above answers "did the files the agent EDITED
+// change since capture?". A cached scanner finding asks a different question:
+// "does the file this finding NAMES still exist?". #1460's live case is the gap
+// between them — a gitleaks blocker for a directory deleted eleven minutes
+// earlier shipped as `current` seven consecutive times, because the edited
+// files were all intact and the cited path was never in the envelope.
+//
+// CONTRACT (the five remaining #1461 slices reuse this verbatim):
+//   - Input is any finding shape; the caller supplies `citedPath`, so nothing
+//     here knows about gitleaks, trivy, govulncheck, vulture, or delta mode.
+//   - A finding whose cited path is absent (ENOENT/ENOTDIR) is DROPPED, not
+//     demoted. There is no remediation for a file that is gone — the agent
+//     cannot rotate a credential in it or delete a line from it. Content drift
+//     on a SURVIVING file stays `validateAdvisoryProvenance`'s job, and that
+//     one demotes.
+//   - Fail open, never closed: a finding with no cited path, an unreadable
+//     path (EACCES/EPERM/EBUSY), or a path past the stat budget is DELIVERED.
+//     Unreadable is not absent; a missed drop is noise, a wrong drop is a lost
+//     secret.
+//   - Bounded cost: findings are deduped by their RAW cited string first —
+//     zero filesystem work — before anything pays for `resolveRunnerPath`'s
+//     ancestor walk or `normalizeMapKey`'s realpath. A first cut that deduped
+//     by the resolved/canonical key instead still ran that expensive step
+//     once per FINDING, not once per unique path, because the dedup lookup
+//     came after the cost it was meant to avoid: #1461's live 126-finding
+//     record measured 72.7ms in that shape, all of it before the first
+//     `statSync`. Deduping the raw string first drops the same record to a
+//     ~1.6ms median (this repo, Windows, 10-sample bench) — the remaining
+//     cost is one canonicalization + one stat per distinct cited string,
+//     capped at `MAX_FINDING_PATH_STATS`.
+//   - Path identity uses the guard normalizer (`resolveRunnerPath` →
+//     `normalizeMapKey`) for the canonical-key dedup and the shape-aware
+//     `toProjectRelativePath` for display, so Windows spellings of one path
+//     collapse to one stat and one log entry (defect shapes 1 and 2). This
+//     helper has no zero-I/O contract of its own to protect — it stats.
+//     Slice 3 (delta mode) must find and name its OWN seam before reusing
+//     this shape; `formatDeltaMode` (tools/lens-diagnostics.ts) reads only
+//     actionable-warnings, code-quality-warnings, and the delta report, none
+//     of which any #1461 slice writes yet, so nothing here currently touches
+//     it.
+/** Stat budget: one per unique cited path, sharing the envelope's own cap. */
+export const MAX_FINDING_PATH_STATS = MAX_ADVISORY_AFFECTED_FILES;
+/** How many dead paths a single drop record names before it stops. */
+const MAX_LOGGED_DEAD_PATHS = 3;
+export function findingPathExistence(resolvedPath) {
+    try {
+        fs.statSync(resolvedPath);
+        return "live";
+    }
+    catch (error) {
+        const code = error.code ?? "unknown";
+        // ENOTDIR: an ancestor component is no longer a directory — the cited
+        // path cannot exist either, same as ENOENT.
+        return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "unknown";
+    }
+}
+/**
+ * Partition findings into `{live, dropped}` by whether the path each one names
+ * still exists. Pure apart from the `fs.statSync` probe, which is injectable so
+ * the partition rules are unit-testable without a filesystem.
+ */
+export function partitionFindingsByCitedPath(args) {
+    const limit = args.maxUniquePaths ?? MAX_FINDING_PATH_STATS;
+    const probe = args.existence ?? findingPathExistence;
+    // Two dedup layers, cheapest first. `rawVerdicts` collapses findings that
+    // cite the IDENTICAL string with zero filesystem work — the dominant case
+    // (#1460's live record: 126 findings over a handful of distinct `file`
+    // strings). Only a raw string not seen before pays for
+    // `resolveRunnerPath`/`advisoryPathKey`, which folds FS-confirmed spelling
+    // variants (case, separators, ancestor walk-up) into `verdicts`, the
+    // canonical-key map that `statCount` reports. Keying the expensive work by
+    // the RESOLVED path instead of the raw one (the pre-#1461-HIGH-2 shape)
+    // still called it once per finding, since the dedup lookup came after the
+    // cost it was meant to dedupe.
+    const rawVerdicts = new Map();
+    const verdicts = new Map();
+    const live = [];
+    const dropped = [];
+    const deadPaths = [];
+    let truncated = false;
+    for (const finding of args.findings) {
+        const cited = args.citedPath(finding);
+        if (!cited) {
+            live.push(finding);
+            continue;
+        }
+        let verdict = rawVerdicts.get(cited);
+        if (verdict === undefined) {
+            // Ancestor-tolerant, same as `toRunnerDisplayPath`'s resolution in
+            // runtime-turn.ts — a bare `path.resolve` here would decide the drop
+            // against a different root than the one used to render the survivor,
+            // dropping findings the display path would have shown correctly
+            // (#1461 HIGH-1). `resolveRunnerPath` already runs its result through
+            // `normalizeMapKey`, so the resolved path IS the canonical key — a
+            // second `advisoryPathKey` pass would re-pay the same realpath cost.
+            const resolved = resolveRunnerPath(args.cwd, cited);
+            const key = resolved;
+            verdict = verdicts.get(key);
+            if (verdict === undefined) {
+                if (verdicts.size >= limit) {
+                    // Budget spent on paths we have not seen before — deliver rather
+                    // than guess. Already-probed paths keep their cached verdict.
+                    truncated = true;
+                    verdict = "live";
+                }
+                else {
+                    verdict = probe(resolved);
+                    verdicts.set(key, verdict);
+                    if (verdict === "missing")
+                        deadPaths.push(resolved);
+                }
+            }
+            rawVerdicts.set(cited, verdict);
+        }
+        if (verdict === "missing")
+            dropped.push(finding);
+        else
+            live.push(finding);
+    }
+    return { live, dropped, deadPaths, statCount: verdicts.size, truncated };
+}
+/**
+ * Delivery-seam wrapper: partition, then emit one bounded `finding_dead_path_drop`
+ * record when anything was dropped, and return only what is safe to deliver.
+ *
+ * The record is the #1432 Gap 1 principle applied here — an eviction that logs
+ * nothing is only confirmable by the absence of complaints. One record per
+ * store per delivery, with a capped path sample; never one per finding.
+ */
+export function dropFindingsForMissingPaths(args) {
+    const partition = partitionFindingsByCitedPath(args);
+    if (partition.dropped.length === 0)
+        return partition.live;
+    logLatency({
+        type: "phase",
+        phase: "finding_dead_path_drop",
+        filePath: args.cwd,
+        durationMs: 0,
+        metadata: {
+            store: args.store,
+            droppedDeadPaths: partition.dropped.length,
+            deadPathCount: partition.deadPaths.length,
+            deliveredCount: partition.live.length,
+            statCount: partition.statCount,
+            samplePaths: partition.deadPaths
+                .slice(0, MAX_LOGGED_DEAD_PATHS)
+                .map((deadPath) => toProjectRelativePath(deadPath, args.cwd)),
+            ...(partition.truncated ? { truncated: true } : {}),
+        },
+    });
+    return partition.live;
+}
+export function provenanceStamp(provenance) {
+    if (!isWellFormed(provenance))
+        return "session unknown / turn unknown / generation unknown";
+    return `session ${provenance.revision.sessionId} / turn ${provenance.revision.turnIndex} / generation ${provenance.revision.generation}`;
+}

package/node_modules/pi-lens/dist/clients/agent-behavior-client.js

@@ -2,7 +2,8 @@
  * AgentBehaviorClient for pi-lens
  *
  * Tracks tool call sequences and flags anti-patterns in real-time:
- * - Blind writes: editing or writing without reading first
+ * - Blind writes: editing or writing without reading first (a same-session
+ *   write/edit of the same path counts as file knowledge)
  * - Thrashing: repeated identical tool calls with no progress
  *
  * No external dependencies — purely tracks tool call history.
@@ -23,6 +24,7 @@ export class AgentBehaviorClient {
     lastToolTimestamp = 0;
     // Per-file tracking
     fileEditCount = new Map();
+    static FILE_EDIT_IDLE_MS = 30 * 60_000;
     /**
      * Record a tool call and return any warnings triggered.
      * Called from tool_result handler.
@@ -63,7 +65,14 @@ export class AgentBehaviorClient {
         // Check for blind writes
         if (WRITE_OPS.has(toolName)) {
             const recentWindow = this.toolHistory.slice(-BLIND_WRITE_WINDOW);
-            const hasRecentRead = recentWindow.some((r) => READ_OPS.has(r.toolName));
+            // A read in the window proves file knowledge; so does a same-session
+            // write/edit of THIS path — the agent authored the content, so the
+            // write-then-edit loop on a self-authored file is not a blind write.
+            const hasRecentRead = recentWindow.some((r) => READ_OPS.has(r.toolName) ||
+                (WRITE_OPS.has(r.toolName) &&
+                    r.filePath !== undefined &&
+                    normalizedPath !== null &&
+                    normalizeMapKey(r.filePath) === normalizedPath));
             if (!hasRecentRead && recentWindow.length > 0) {
                 // Count how many writes in the window without reads
                 const writesWithoutRead = recentWindow.filter((r) => WRITE_OPS.has(r.toolName)).length;
@@ -82,7 +91,15 @@ export class AgentBehaviorClient {
             // Track edits per file
             if (filePath) {
                 const key = normalizeMapKey(filePath);
-                this.fileEditCount.set(key, (this.fileEditCount.get(key) ?? 0) + 1);
+                this.fileEditCount.set(key, {
+                    count: (this.fileEditCount.get(key)?.count ?? 0) + 1,
+                    lastUsedAt: now,
+                });
+                for (const [pathKey, entry] of this.fileEditCount) {
+                    if (now - entry.lastUsedAt > AgentBehaviorClient.FILE_EDIT_IDLE_MS) {
+                        this.fileEditCount.delete(pathKey);
+                    }
+                }
             }
         }
         // Add to history (keep last 50 entries)
@@ -104,7 +121,7 @@ export class AgentBehaviorClient {
      * Get edit count for a file in this session.
      */
     getEditCount(filePath) {
-        return this.fileEditCount.get(filePath) ?? 0;
+        return this.fileEditCount.get(normalizeMapKey(filePath))?.count ?? 0;
     }
     /**
      * Reset state (e.g., on session start).

package/node_modules/pi-lens/dist/clients/agent-nudge.js

@@ -169,12 +169,19 @@ export function wireAgentNudgeSubscriber(args) {
  *   - all local         → "after your last turn" (the original #485 wording,
  *                         unchanged — verified by the pre-existing #485
  *                         tests);
- *   - all cross-process → "by another pi-lens instance (e.g. a subagent's)";
- *   - mixed             → "after your last turn (N of them by another
- *                         pi-lens instance)" — the base framing stays local
+ *   - all cross-process → "by an automatic run outside your turn";
+ *   - mixed             → "after your last turn (N of them by an automatic
+ *                         run outside it)" — the base framing stays local
  *                         and the cross-process portion is counted out
- *                         precisely, so no local file is ever misattributed
- *                         to another instance.
+ *                         precisely, so no local file is ever misattributed.
+ *
+ * The cross-process wording names the ACTION, not the process identity. It
+ * used to read "by another pi-lens instance (e.g. a subagent's)", which sent
+ * agents investigating what other instance was running — the exact behavior
+ * this nudge exists to prevent. Which process formatted the file is an
+ * implementation detail the reading agent cannot act on; that it was an
+ * automatic run outside their turn is the whole actionable content. The
+ * origin split stays exact in the telemetry for human debugging.
  *
  * Clears the accumulator ONLY here, on actual injection — never on
  * agent_end/agent_settled/turn_start. Files formatted at the last turn_end of
@@ -222,10 +229,10 @@ export function consumeAgentNudge(dbg) {
         // file to another instance — a mixed batch keeps the local base framing
         // and calls out the cross-process portion by exact count.
         const attribution = localCount === 0
-            ? "by another pi-lens instance (e.g. a subagent's)"
+            ? "by an automatic run outside your turn"
             : crossProcessCount === 0
                 ? "after your last turn"
-                : `after your last turn (${crossProcessCount} of them by another pi-lens instance)`;
+                : `after your last turn (${crossProcessCount} of them by an automatic run outside it)`;
         const message = `pi-lens: ${filesTotal} file(s) were ${verbLabel} ${attribution}: ${nameList} — working-tree changes to these are expected; re-read before editing.`;
         logLatency({
             type: "phase",