@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/project-diagnostics/runner-adapters/madge.js

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { compareOrdinal } from "../../string-utils.js";
 function resolveCyclePath(cwd, file) {
     return path.isAbsolute(file) ? file : path.resolve(cwd, file);
 }
@@ -36,7 +37,7 @@ export function circularDepsToProjectDiagnostics(cwd, circular) {
     for (const dep of circular) {
         const key = cycleMembers(dep)
             .map((f) => resolveCyclePath(cwd, f))
-            .sort((a, b) => a.localeCompare(b))
+            .sort(compareOrdinal)
             .join("|");
         if (seen.has(key))
             continue;

package/node_modules/pi-lens/dist/clients/project-diagnostics/scanner.js

@@ -5,6 +5,7 @@ import { evaluateRules } from "../dispatch/fact-rule-runner.js";
 import { runProviders } from "../dispatch/fact-runner.js";
 import { FactStore } from "../dispatch/fact-store.js";
 import { canHandle as astGrepCanHandle, getLang as astGrepGetLang, evaluateAstGrepRules, loadSg, } from "../dispatch/runners/ast-grep-napi.js";
+import { detectFileKind } from "../file-kinds.js";
 import { isTestFile } from "../file-utils.js";
 import { isAtOrAboveHomeDir } from "../path-utils.js";
 import { getProjectDiagnosticsScannerMaxFiles } from "../project-scale.js";
@@ -100,7 +101,9 @@ async function scanFileMajorRules(cwd, files, signal) {
     const queryMap = treeSitterReady
         ? await queryLoader.loadQueries(cwd)
         : undefined;
-    const facts = new FactStore();
+    // Subject labels this store's capacity-eviction telemetry distinctly from
+    // the other five production FactStore instances (#2243 review round 3, F1).
+    const facts = new FactStore("project-diagnostics-scanner");
     const pi = { getFlag: () => undefined };
     const treeSitter = [];
     const factRules = [];
@@ -141,7 +144,7 @@ async function scanFileMajorRules(cwd, files, signal) {
         }
     };
     const scanFactRulesFile = async (filePath, content) => {
-        facts.clearFileFactsFor(filePath);
+        facts.dropFileFacts(filePath);
         // Seed the exact bytes already supplied to tree-sitter so the file-content
         // provider is skipped by runProviders.
         facts.setFileFact(filePath, "file.content", content);
@@ -160,7 +163,7 @@ async function scanFileMajorRules(cwd, files, signal) {
         const startedAt = Date.now();
         try {
             const rootNode = lang.parse(content).root();
-            const fileDiagnostics = evaluateAstGrepRules(filePath, rootNode, cwd, "jsts", {
+            const fileDiagnostics = evaluateAstGrepRules(filePath, rootNode, cwd, detectFileKind(filePath), {
                 maxMatchesPerRule: AST_GREP_SCAN_MAX_MATCHES_PER_RULE,
                 maxTotalDiagnostics: AST_GREP_SCAN_MAX_DIAGNOSTICS_PER_FILE,
             });
@@ -264,7 +267,10 @@ async function scanFileMajorRules(cwd, files, signal) {
             finally {
                 // This store belongs to the scan, and every consumer of this file's
                 // content and derived facts has completed by the end of the iteration.
-                facts.clearFileFactsFor(filePath);
+                // Drop without pinning: the scan is sequential and owns this store, so
+                // there is no concurrent walk to guard against, and pinning every
+                // scanned file would exempt it from the capacity cap (#2243).
+                facts.dropFileFacts(filePath);
             }
         }
         if (wasmAborted) {

package/node_modules/pi-lens/dist/clients/project-snapshot.js

@@ -533,11 +533,22 @@ export function loadProjectSnapshotExportsAndRules(cwd) {
     const body = resolveSnapshotBodyPath(cwd);
     const authoritative = authoritativeSnapshots.get(key);
     if (authoritative) {
-        const diskMtime = body ? body.mtimeMs : Number.NEGATIVE_INFINITY;
-        if (diskMtime <= authoritative.knownMtime) {
+        // `body === null` means nothing is on disk — that is never "the body
+        // changed size", so it must not be read as superseding our own write.
+        // See the matching comment in loadProjectSnapshotInternal.
+        const notSuperseded = body === null ||
+            (body.mtimeMs <= authoritative.knownMtime &&
+                body.size === authoritative.knownSize);
+        if (notSuperseded) {
             const { version, seq, cachedExports, projectRulesScan } = authoritative.snapshot;
             return { version, seq, cachedExports, projectRulesScan };
         }
+        // On mismatch, unlike the full loader, this narrow loader neither
+        // deletes the entry nor touches its idle timer (it never calls
+        // touchAuthoritativeSnapshot even on a hit). The stale entry is safe to
+        // leave in place: nothing here re-arms its eviction, so it is still
+        // bounded by whatever idle window the full loader (or the original
+        // write) last set, not left to live indefinitely.
     }
     if (!body)
         return null;
@@ -547,18 +558,22 @@ function loadProjectSnapshotInternal(cwd, requireWordIndex) {
     const key = normalizeMapKey(cwd);
     const body = resolveSnapshotBodyPath(cwd);
     // Authoritative in-process write wins while our own (possibly still
-    // in-flight) write has not been superseded on disk by a newer external
-    // mtime. `body === null` means nothing is on disk yet — our just-scheduled
-    // write is the only truth, so serve it.
+    // in-flight) write has not been superseded on disk by a newer external mtime
+    // or a different-size body in the same/coarser bucket. `body === null` means
+    // nothing is on disk — either our just-scheduled write hasn't landed yet, or
+    // something removed the body after we wrote it (e.g. a cleared cache dir).
+    // Neither case is "the body changed size", so serve the in-process object.
     const authoritative = authoritativeSnapshots.get(key);
     if (authoritative) {
-        const diskMtime = body ? body.mtimeMs : Number.NEGATIVE_INFINITY;
-        if (diskMtime <= authoritative.knownMtime) {
+        const notSuperseded = body === null ||
+            (body.mtimeMs <= authoritative.knownMtime &&
+                body.size === authoritative.knownSize);
+        if (notSuperseded) {
             touchAuthoritativeSnapshot(key, authoritative);
             return authoritative.snapshot;
         }
-        // An external writer moved past our write — honor disk and stop
-        // serving the now-stale in-memory object.
+        // An external writer changed the body beyond our metadata stamp — honor
+        // disk and stop serving the now-stale in-memory object.
         deleteAuthoritativeSnapshot(key);
     }
     if (!body) {
@@ -907,10 +922,12 @@ function reconcileAuthoritativeAfterWrite(pending, rawBytes) {
         return;
     }
     try {
-        entry.knownMtime = fs.statSync(pending.gzPath).mtimeMs;
+        const stat = fs.statSync(pending.gzPath);
+        entry.knownMtime = stat.mtimeMs;
+        entry.knownSize = stat.size;
     }
     catch {
-        // If we can't stat our own write, leave knownMtime as-is; the worst case
+        // If we can't stat our own write, leave the metadata as-is; the worst case
         // is one extra disk re-parse on the next load.
     }
 }
@@ -1368,11 +1385,16 @@ export function saveProjectSnapshot(cwd, snapshot) {
     // legacy body to a merge-consumer, silently dropping this snapshot's fields.
     const priorBody = resolveSnapshotBodyPath(cwd);
     const knownMtime = priorBody ? priorBody.mtimeMs : Number.NEGATIVE_INFINITY;
+    const knownSize = priorBody ? priorBody.size : Number.NEGATIVE_INFINITY;
     const authoritativeEntry = {
         snapshot,
         knownMtime,
+        knownSize,
         lastUsedAt: Date.now(),
     };
+    const previousAuthoritativeEntry = authoritativeSnapshots.get(key);
+    if (previousAuthoritativeEntry)
+        clearAuthoritativeSnapshotTimer(previousAuthoritativeEntry);
     authoritativeSnapshots.set(key, authoritativeEntry);
     scheduleAuthoritativeSnapshotEviction(key, authoritativeEntry);
     enforceAuthoritativeSnapshotCap();

package/node_modules/pi-lens/dist/clients/read-guard-logger.js

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import { isTestMode } from "./env-utils.js";
 import { getGlobalPiLensDir } from "./file-utils.js";
 import { createNdjsonLogger } from "./ndjson-logger.js";
+import { normalizeFilePath } from "./path-utils.js";
 const READ_GUARD_LOG_DIR = getGlobalPiLensDir();
 const READ_GUARD_LOG_FILE = path.join(READ_GUARD_LOG_DIR, "read-guard.log");
 const READ_GUARD_LOG_BACKUP_FILE = path.join(READ_GUARD_LOG_DIR, "read-guard.log.1");
@@ -140,7 +141,18 @@ export function shouldLogEvent(event) {
         // READ_GUARD_MAX_RECORDS_PER_FILE overflow triggers one), so this trim
         // record bypasses the per-read verbosity gate — a live eviction
         // regression must be visible without PI_LENS_READ_GUARD_VERBOSE=1.
-        event === "read_cap_trimmed");
+        event === "read_cap_trimmed" ||
+        // #1918: the record-cap trim's population siblings — whole-file
+        // eviction under real pressure (file cap or an external delete) and
+        // the per-file edits-cap trim. Idle-timeout eviction is deliberately
+        // EXCLUDED from this event (see read-guard.ts's evictFile doc
+        // comment) — it's routine housekeeping, not a fault, and its
+        // per-file cardinality is unbounded in a healthy session. Same
+        // rarity argument as #1913 for the reasons that DO fire: each is
+        // rising-edge gated once per file per session, so always-on
+        // visibility costs nothing.
+        event === "read_file_evicted" ||
+        event === "edits_cap_trimmed");
 }
 const MAX_TELEMETRY_STRING = 512;
 const MAX_TELEMETRY_KEYS = 64;
@@ -205,7 +217,17 @@ export function logReadGuardEvent(entry) {
             ? bounded.value
             : undefined;
     const { correlationId: _correlationId, ...logEntry } = entry;
-    writer.log({ ts: new Date().toISOString(), ...logEntry, metadata });
+    // #2219 (the #2141 class): `filePath` reaches here from
+    // `runtime-tool-result.ts`'s raw `path.resolve()`/`path.isAbsolute()`
+    // arithmetic (never `normalizeFilePath`-passed), always a genuine file —
+    // this field carries no non-path sentinel. Normalize once at this single
+    // emit seam, matching `review-graph-logger.ts`'s `logReviewGraph`.
+    writer.log({
+        ts: new Date().toISOString(),
+        ...logEntry,
+        filePath: normalizeFilePath(logEntry.filePath),
+        metadata,
+    });
 }
 export function getReadGuardLogPath() {
     return READ_GUARD_LOG_FILE;

package/node_modules/pi-lens/dist/clients/read-guard.js

@@ -318,7 +318,33 @@ export class ReadGuard {
             clearTimeout(timer);
         this.fileIdleTimers.delete(filePath);
     }
-    evictFile(filePath) {
+    /**
+     * #1918: `enforceRecordCapForFile` (the per-file record cap) is the only
+     * `read-guard.ts` eviction path #1913 gave a bounded record. This whole-file
+     * evictor has four call sites — `enforceFileCap`'s consumed-file cap, its
+     * unconsumed-file cap, `touchFile`'s idle timer, and `forgetPath`'s
+     * external-delete cleanup — and none of them left any trace. A live
+     * regression in any of the four (e.g. a cap set too low) dropped a file's
+     * read/edit history with nothing in `~/.pi-lens/read-guard.log` to show it
+     * happened.
+     *
+     * Follows #1913's aggregate-after-first pattern for the three PRESSURE
+     * reasons (cap exhaustion, external delete): `incrementDegradationCount`
+     * keeps the exact per-file eviction tally (and its own power-of-two
+     * milestone rows in latency.log) while the read-guard.log line fires only
+     * on the rising edge, so a file evicted repeatedly across a session can't
+     * flood the log.
+     *
+     * `idle-timeout` is deliberately excluded from both the ledger tally and
+     * the log line (#1918 review F2): idle eviction is designed housekeeping,
+     * not a fault signal — a read-only session that idles out N files is
+     * healthy, ordinary behavior, and N is unbounded (every distinct file path
+     * touched that session is its own ledger subject). Recording it here would
+     * grow the ledger's tally map without bound and spam `pilens_health` in
+     * every healthy session, unlike the other three reasons, which are rare by
+     * construction (only real pressure or an explicit delete reaches them).
+     */
+    evictFile(filePath, reason) {
         this.clearFileTimer(filePath);
         this.reads.delete(filePath);
         this.edits.delete(filePath);
@@ -331,6 +357,21 @@ export class ReadGuard {
             if (stored === filePath)
                 this.knownPathIndex.delete(syntacticKey);
         }
+        if (reason === "idle-timeout")
+            return;
+        const isRisingEdge = incrementDegradationCount({
+            kind: "read-guard-file-evicted",
+            subject: filePath,
+            reason: `evicted (${reason})`,
+        });
+        if (isRisingEdge) {
+            logReadGuardEvent({
+                event: "read_file_evicted",
+                sessionId: this.sessionId,
+                filePath,
+                metadata: { reason },
+            });
+        }
     }
     touchFile(filePath) {
         const now = Date.now();
@@ -348,7 +389,12 @@ export class ReadGuard {
             // eviction. Only consumed reads and rebuildable edit history may expire.
             if (this.reads.has(filePath) && !this.consumedReadFiles.has(filePath))
                 return;
-            this.evictFile(filePath);
+            // #1918 review F2: this reason is intentionally silent inside
+            // evictFile — idle eviction is routine housekeeping, not a fault, and
+            // every distinct file idling out this session is its own ledger
+            // subject, so recording it would grow unbounded and flood
+            // pilens_health on every healthy session. See evictFile's doc comment.
+            this.evictFile(filePath, "idle-timeout");
         }, this.idleEvictMs());
         timer.unref?.();
         this.fileIdleTimers.set(filePath, timer);
@@ -360,7 +406,7 @@ export class ReadGuard {
                 .sort((a, b) => (this.fileLastUsed.get(a) ?? 0) - (this.fileLastUsed.get(b) ?? 0))[0];
             if (!victim)
                 break;
-            this.evictFile(victim);
+            this.evictFile(victim, "file-cap-consumed");
         }
         while (this.reads.size > READ_GUARD_MAX_UNCONSUMED_FILES) {
             const victim = [...this.reads.keys()]
@@ -370,7 +416,7 @@ export class ReadGuard {
                 break;
             // This is a normal read miss: a later edit must require a fresh read,
             // never silently allow and never become a permanent hard-block.
-            this.evictFile(victim);
+            this.evictFile(victim, "file-cap-unconsumed");
         }
     }
     // --- Public API ---
@@ -575,7 +621,7 @@ export class ReadGuard {
                 });
                 return verdict;
             }
-            const verdict = this.blockOrWarn("zero-read", `🔄 RETRYABLE — Edit without read\n\nYou are trying to edit \`${filePath}\` but have not read it in this conversation.\n\nRead the file first, then retry the edit: \`read path="${filePath}"\``, undefined, effectiveMode);
+            const verdict = this.blockOrWarn("zero-read", `🔄 RETRYABLE — Edit without read: you have not read \`${filePath}\` in this conversation. Read it first, then retry: \`read path="${filePath}"\`.`, undefined, effectiveMode);
             this.recordVerdict(filePath, "edit", touchedLines, verdict, {
                 reasonKind: "zero_read",
             });
@@ -791,7 +837,7 @@ export class ReadGuard {
      */
     forgetPath(filePath) {
         const stored = this.knownPathIndex.get(normalizeEphemeralMapKey(filePath));
-        this.evictFile(stored ?? this.key(filePath));
+        this.evictFile(stored ?? this.key(filePath), "external-delete");
     }
     /**
      * Mark a file as pending creation (Write tool to a non-existing file).
@@ -1358,7 +1404,28 @@ export class ReadGuard {
             timestamp: Date.now(),
         });
         if (arr.length > READ_GUARD_MAX_EDITS_PER_FILE) {
-            arr.splice(0, arr.length - READ_GUARD_MAX_EDITS_PER_FILE);
+            const trimmedCount = arr.length - READ_GUARD_MAX_EDITS_PER_FILE;
+            arr.splice(0, trimmedCount);
+            // #1918: the #282-289 doc comment argues this trim is inert in
+            // practice (every consumer reads only the last record or a
+            // bounded relocation window), but an argument is not a record —
+            // if that assumption ever breaks, this is the only signal. Same
+            // aggregate-after-first shape as `read_cap_trimmed` (#1913):
+            // `incrementDegradationCount` keeps the exact per-file tally,
+            // the read-guard.log line fires once on the rising edge.
+            const isRisingEdge = incrementDegradationCount({
+                kind: "read-guard-edits-cap-trim",
+                subject: filePath,
+                reason: `trimmed ${trimmedCount} edit record(s) past cap`,
+            });
+            if (isRisingEdge) {
+                logReadGuardEvent({
+                    event: "edits_cap_trimmed",
+                    sessionId: this.sessionId,
+                    filePath,
+                    metadata: { trimmedCount, cappedLength: arr.length },
+                });
+            }
         }
         this.edits.set(filePath, arr);
     }

package/node_modules/pi-lens/dist/clients/recent-touches.js

@@ -56,6 +56,7 @@ export function isRecentTouchesEnabled() {
 export function _resetRecentTouchesForTests() {
     _enabledCache = undefined;
     _lastSeenMtimeMs = undefined;
+    _lastSeenSizeBytes = undefined;
     _lastConsumedCursor.clear();
 }
 // --- Read (never throws — missing file, corrupt JSON, or wrong shape ⇒ empty) ---
@@ -170,10 +171,12 @@ export async function readCrossProcessTouchesForSessionStart(args) {
     }
 }
 // --- Consumer: parent at turn_start (mtime-gated hot path) ---
-// Module state: the last mtime we've already consumed, and a per-cwd cursor
-// (max ts already surfaced) so repeated reads of an unchanged-since-last-
-// check file never re-emit the same entries into the accumulator twice.
+// Module state: the last mtime (+ size, #2300) we've already consumed, and a
+// per-cwd cursor (max ts already surfaced) so repeated reads of an
+// unchanged-since-last-check file never re-emit the same entries into the
+// accumulator twice.
 let _lastSeenMtimeMs;
+let _lastSeenSizeBytes;
 const _lastConsumedCursor = new Map();
 /**
  * Parent-at-turn_start consumer. Hot path: ONE `fs.stat` per call; when the
@@ -198,17 +201,26 @@ export async function readCrossProcessTouchesForTurnStart(args) {
     try {
         const target = recentTouchesPath(args.cwd);
         let mtimeMs;
+        let sizeBytes;
         try {
-            mtimeMs = (await fs.promises.stat(target)).mtimeMs;
+            const stat = await fs.promises.stat(target);
+            mtimeMs = stat.mtimeMs;
+            sizeBytes = stat.size;
         }
         catch {
             // No record file yet (ENOENT) or inaccessible (EACCES) — nothing to
             // report; do not disturb the mtime watermark.
             return [];
         }
-        if (_lastSeenMtimeMs === mtimeMs)
+        // #2300: size alongside mtime — a same-mtime-bucket rewrite (a sibling
+        // process's write landing in the same coarse-granularity mtime tick)
+        // changes the file's length, so mtime equality alone would wrongly
+        // short-circuit to "nothing new" and drop its entries.
+        if (_lastSeenMtimeMs === mtimeMs && _lastSeenSizeBytes === sizeBytes) {
             return [];
+        }
         _lastSeenMtimeMs = mtimeMs;
+        _lastSeenSizeBytes = sizeBytes;
         const selfPid = args.selfPid ?? process.pid;
         const now = args.now ?? Date.now();
         const freshnessMs = args.freshnessMs ?? RECENT_TOUCHES_FRESHNESS_MS;