pi-lens 3.8.73 → 4.0.0

package/dist/clients/read-guard.js

@@ -11,8 +11,10 @@
  */
 import * as fs from "node:fs";
 import { createFileTime } from "./file-time.js";
+import { hashDiagnosticContent } from "./lsp/diagnostic-binding.js";
 import { normalizeFilePath } from "./path-utils.js";
 import { logReadGuardEvent } from "./read-guard-logger.js";
+export const READ_GUARD_STATE_VERSION = 1;
 // --- Constants ---
 const DEFAULT_CONFIG = {
     enabled: true,
@@ -27,6 +29,66 @@ const DEFAULT_CONFIG = {
 const OWN_EDIT_STALE_GRACE_MS = Math.max(0, Number.parseInt(process.env.PI_LENS_READ_GUARD_OWN_EDIT_GRACE_MS ?? "120000", 10) || 120000);
 /** Avoid hashing very large reads in the hot path. */
 const READ_HASH_MAX_LINES = Math.max(0, Number.parseInt(process.env.PI_LENS_READ_GUARD_HASH_MAX_LINES ?? "3000", 10) || 3000);
+/**
+ * Content bindings are defense in depth on a read-adjacent hot path. Cap the
+ * synchronous disk read so bridge registration never hashes an unbounded file.
+ */
+const READ_BINDING_MAX_BYTES = 4 * 1024 * 1024;
+const READ_GUARD_MAX_FILES = 256;
+// Unconsumed reads remain valid until edit or session end, but this high
+// sanity cap prevents a read-only session from growing without bound.
+const READ_GUARD_MAX_UNCONSUMED_FILES = 4096;
+const READ_GUARD_IDLE_EVICT_MS_DEFAULT = 30 * 60_000;
+export function captureReadContentBinding(filePath, offset, limit) {
+    try {
+        if (fs.statSync(filePath).size > READ_BINDING_MAX_BYTES)
+            return undefined;
+        const content = fs.readFileSync(filePath, "utf-8");
+        // Allocate at most the classification prefix first. For range bindings,
+        // splitting then stops at the requested range end rather than the EOF.
+        const lines = splitLinesThrough(content, READ_HASH_MAX_LINES + 1);
+        if (lines.length <= READ_HASH_MAX_LINES) {
+            return {
+                hash: hashDiagnosticContent(content),
+                fullFile: true,
+                offset: 1,
+                limit: lines.length,
+            };
+        }
+        const scopedOffset = Math.max(1, offset);
+        const scopedLimit = Math.min(Math.max(0, limit), READ_HASH_MAX_LINES);
+        if (scopedLimit === 0)
+            return undefined;
+        const rangeLines = splitLinesThrough(content, scopedOffset - 1 + scopedLimit);
+        const scopedContent = rangeLines
+            .slice(scopedOffset - 1, scopedOffset - 1 + scopedLimit)
+            .join("\n");
+        return {
+            hash: hashDiagnosticContent(scopedContent),
+            fullFile: false,
+            offset: scopedOffset,
+            limit: scopedLimit,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function _currentContentMatchesBindingForTests(filePath, binding) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const boundContent = binding.fullFile
+            ? content
+            : splitLines(content)
+                .slice(binding.offset - 1, binding.offset - 1 + binding.limit)
+                .join("\n");
+        return hashDiagnosticContent(boundContent) === binding.hash;
+    }
+    catch {
+        return false;
+    }
+}
+const currentContentMatchesBinding = _currentContentMatchesBindingForTests;
 // Adaptive relocation window (findRelocation). A globally-unique hash-sequence
 // match always wins; when the content is duplicated elsewhere, we fall back to
 // a match that is unique WITHIN this window of the original position. The window
@@ -39,6 +101,28 @@ const RELOCATION_WINDOW_MAX = Math.max(RELOCATION_WINDOW_MIN, Number.parseInt(pr
 function splitLines(text) {
     return text.split(/\r?\n/);
 }
+/** `splitLines` semantics, but without scanning/allocating beyond `maxLines`. */
+function splitLinesThrough(text, maxLines) {
+    if (maxLines <= 0)
+        return [];
+    const lines = [];
+    let start = 0;
+    while (lines.length < maxLines) {
+        const newline = text.indexOf("\n", start);
+        if (newline === -1) {
+            lines.push(text.slice(start));
+            break;
+        }
+        const end = newline > start && text[newline - 1] === "\r" ? newline - 1 : newline;
+        lines.push(text.slice(start, end));
+        start = newline + 1;
+        if (start === text.length && lines.length < maxLines) {
+            lines.push("");
+            break;
+        }
+    }
+    return lines;
+}
 export function lineContentHash(line) {
     // FNV-1a over whitespace-stripped content. This treats no-op formatter/touch
     // changes as still-valid context while detecting semantic line changes.
@@ -117,6 +201,10 @@ export class ReadGuard {
     config;
     reads = new Map();
     edits = new Map();
+    fileLastUsed = new Map();
+    fileIdleTimers = new Map();
+    /** Reads remain behavior-gating until the corresponding edit is published. */
+    consumedReadFiles = new Set();
     fileTime;
     exemptions = new Set(); // One-time exemptions via /lens-allow-edit
     pendingCreations = new Map();
@@ -146,6 +234,66 @@ export class ReadGuard {
     key(filePath) {
         return normalizeFilePath(filePath);
     }
+    idleEvictMs() {
+        const value = Number.parseInt(process.env.PI_LENS_READ_GUARD_IDLE_EVICT_MS ?? "", 10);
+        return Number.isSafeInteger(value) && value > 0 ? value : READ_GUARD_IDLE_EVICT_MS_DEFAULT;
+    }
+    clearFileTimer(filePath) {
+        const timer = this.fileIdleTimers.get(filePath);
+        if (timer)
+            clearTimeout(timer);
+        this.fileIdleTimers.delete(filePath);
+    }
+    evictFile(filePath) {
+        this.clearFileTimer(filePath);
+        this.reads.delete(filePath);
+        this.edits.delete(filePath);
+        this.fileLastUsed.delete(filePath);
+        this.consumedReadFiles.delete(filePath);
+        this.writtenThisSession.delete(filePath);
+    }
+    touchFile(filePath) {
+        const now = Date.now();
+        this.fileLastUsed.set(filePath, now);
+        this.clearFileTimer(filePath);
+        // An outstanding read is enforcement state, not a rebuildable cache entry.
+        // It must survive idle time and file-cap pressure until the edit consumes it.
+        if (this.reads.has(filePath) && !this.consumedReadFiles.has(filePath))
+            return;
+        const stamp = now;
+        const timer = setTimeout(() => {
+            if (this.fileLastUsed.get(filePath) !== stamp)
+                return;
+            // Never turn an outstanding read into a zero-read block through idle
+            // eviction. Only consumed reads and rebuildable edit history may expire.
+            if (this.reads.has(filePath) && !this.consumedReadFiles.has(filePath))
+                return;
+            this.evictFile(filePath);
+        }, this.idleEvictMs());
+        timer.unref?.();
+        this.fileIdleTimers.set(filePath, timer);
+    }
+    enforceFileCap() {
+        while (this.reads.size > READ_GUARD_MAX_FILES) {
+            const victim = [...this.reads.keys()]
+                .filter((filePath) => this.consumedReadFiles.has(filePath))
+                .sort((a, b) => (this.fileLastUsed.get(a) ?? 0) - (this.fileLastUsed.get(b) ?? 0))[0];
+            if (!victim)
+                break;
+            this.evictFile(victim);
+        }
+        while (this.reads.size > READ_GUARD_MAX_UNCONSUMED_FILES) {
+            const victim = [...this.reads.keys()]
+                .filter((filePath) => !this.consumedReadFiles.has(filePath))
+                .sort((a, b) => (this.fileLastUsed.get(a) ?? 0) -
+                (this.fileLastUsed.get(b) ?? 0))[0];
+            if (!victim)
+                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);
+        }
+    }
     // --- Public API ---
     /**
      * Record that a file was read.
@@ -160,8 +308,11 @@ export class ReadGuard {
                 captureLineHashes(filePath, record.effectiveOffset, record.effectiveLimit),
         };
         const arr = this.reads.get(storedRecord.filePath) ?? [];
+        this.consumedReadFiles.delete(storedRecord.filePath);
         arr.push(storedRecord);
         this.reads.set(storedRecord.filePath, arr);
+        this.touchFile(storedRecord.filePath);
+        this.enforceFileCap();
         logReadGuardEvent({
             event: "read_recorded",
             sessionId: this.sessionId,
@@ -180,6 +331,9 @@ export class ReadGuard {
                 writeIndex: storedRecord.writeIndex,
                 readCountForFile: arr.length,
                 hashLineCount: Object.keys(storedRecord.lineHashes ?? {}).length,
+                ...(storedRecord.source !== undefined && {
+                    source: storedRecord.source,
+                }),
             },
         });
         // Also update FileTime stamp for this file
@@ -227,6 +381,8 @@ export class ReadGuard {
         // Canonicalize once: every map lookup below (and every private helper this
         // passes filePath to) must agree with how recordRead keyed the read.
         filePath = this.key(filePath);
+        if (this.reads.has(filePath) || this.edits.has(filePath))
+            this.touchFile(filePath);
         // Check exemptions
         if (this.exemptions.has(filePath)) {
             this.exemptions.delete(filePath); // One-time use
@@ -270,6 +426,19 @@ export class ReadGuard {
             });
             return verdict;
         }
+        const lastBoundRead = [...fileReads]
+            .reverse()
+            .find((read) => read.contentBinding !== undefined);
+        if (lastBoundRead?.contentBinding &&
+            !currentContentMatchesBinding(filePath, lastBoundRead.contentBinding)) {
+            const verdict = this.blockOrWarn("file-modified", `🔄 RETRYABLE — File modified since read\n\nYou last read \`${filePath}\` at ${new Date(lastBoundRead.timestamp).toISOString()}.\nThe file content no longer matches the bridge-recorded read.\n\nYour mental model is out of sync with the actual file content.\nTo proceed:\n  1. Re-read the file: \`read path="${filePath}"\``, undefined, effectiveMode);
+            this.recordVerdict(filePath, "edit", touchedLines, verdict, {
+                reasonKind: "file_modified",
+                lastReadTimestamp: lastBoundRead.timestamp,
+                contentBindingMismatch: true,
+            });
+            return verdict;
+        }
         // 2. FileTime check (actual staleness)
         let ignoredOwnEditStaleness = false;
         let ignoredHashStaleness = false;
@@ -314,7 +483,9 @@ export class ReadGuard {
                 // If oldText was resolved (content-verified), the model demonstrably
                 // knew the content it's replacing — line drift from prior edits in
                 // the session is the likely cause. Downgrade to warn rather than block.
-                const outOfRangeMode = options?.oldTextResolved ? "warn" : effectiveMode;
+                const outOfRangeMode = options?.oldTextResolved
+                    ? "warn"
+                    : effectiveMode;
                 const verdict = this.blockOrWarn("out-of-range", `🔄 RETRYABLE — Edit outside read range\n\nYou read \`${filePath}\` lines ${lastRead.effectiveOffset}-${lastReadEnd}${lastRead.enclosingSymbol ? ` (${lastRead.enclosingSymbol.kind} \`${lastRead.enclosingSymbol.name}\`)` : ""}, but your edit touches lines ${editStart}-${editEnd}.\n\nRead the relevant section first, then retry the edit:\n  \`read path="${filePath}" offset=${Math.max(1, editStart - 5)} limit=${Math.min(30, editEnd - editStart + 10)}\``, {
                     editRange: range,
                     readRanges: fileReads.map((r) => ({
@@ -434,6 +605,10 @@ export class ReadGuard {
         filePath = this.key(filePath);
         this.fileTime.read(filePath);
         this.writtenThisSession.add(filePath);
+        if (this.reads.has(filePath))
+            this.consumedReadFiles.add(filePath);
+        this.touchFile(filePath);
+        this.enforceFileCap();
         const creation = this.pendingCreations.get(filePath);
         if (creation) {
             this.pendingCreations.delete(filePath);
@@ -495,13 +670,96 @@ export class ReadGuard {
      * Get all read records for a file (for debugging).
      */
     getReadHistory(filePath) {
-        return this.reads.get(this.key(filePath)) ?? [];
+        const key = this.key(filePath);
+        if (this.reads.has(key))
+            this.touchFile(key);
+        return this.reads.get(key) ?? [];
+    }
+    /**
+     * Snapshot the read-set for persistence across a session resume (#1041).
+     * Mirrors widget-state's `exportWidgetState`: the Map is emitted as
+     * `[key, records]` tuples, keys already in `normalizeFilePath` form. Only
+     * `reads` is serialized — it is the payload `checkEdit`'s zero-read/coverage
+     * checks consult. Safe to call even when the guard is disabled (an empty or
+     * never-populated `reads` simply exports zero entries).
+     */
+    exportState() {
+        return {
+            version: READ_GUARD_STATE_VERSION,
+            reads: [...this.reads.entries()].map(([key, records]) => [
+                key,
+                records.map((record) => ({ ...record })),
+            ]),
+        };
+    }
+    /**
+     * Rehydrate a persisted read-set (#1041) into this (fresh, post-resume)
+     * guard, with mandatory staleness reconciliation: each read is re-verified
+     * against the CURRENT on-disk content via its recorded `lineHashes`, and any
+     * read whose file changed (or no longer exists, or that carries no verifiable
+     * hashes) is DROPPED. A rehydrated read must never mask a real staleness — a
+     * resume must not let the agent edit a file that changed on disk while it
+     * believed it held a fresh read. Kept reads are replayed through
+     * {@link recordRead}, which re-keys through {@link key} (idempotent — the
+     * exported keys are already normalized) and re-stamps FileTime so the next
+     * `checkEdit` sees a consistent baseline. Version-guarded and null-safe:
+     * `undefined` / a mismatched version / a missing field loads as "no prior
+     * reads". Returns a count of imported vs dropped reads for logging.
+     */
+    importState(state) {
+        const result = { imported: 0, dropped: 0 };
+        if (!state || state.version !== READ_GUARD_STATE_VERSION)
+            return result;
+        // A corrupt/hand-edited sidecar must degrade to "no prior reads", never
+        // throw: loadSessionState validates only version/widget, so a malformed
+        // `reads` reaches here. If importState threw, the session_start try/catch
+        // would abort the ENTIRE rehydration (incl. widget + mountLensWidget)
+        // rather than just skipping the read-set.
+        if (!Array.isArray(state.reads))
+            return result;
+        for (const entry of state.reads) {
+            // Skip anything that isn't a well-formed [key, records] tuple.
+            if (!Array.isArray(entry) || entry.length !== 2)
+                continue;
+            const [rawPath, records] = entry;
+            if (typeof rawPath !== "string")
+                continue;
+            if (!Array.isArray(records) || records.length === 0)
+                continue;
+            const filePath = this.key(rawPath);
+            let lines;
+            try {
+                lines = splitLines(fs.readFileSync(filePath, "utf-8"));
+            }
+            catch {
+                // File gone since it was read → drop every read for it.
+                result.dropped += records.length;
+                continue;
+            }
+            for (const record of records) {
+                const rehydrated = { ...record, filePath };
+                // readHashesStillMatch returns false when the recorded hashes no
+                // longer match disk OR when the read captured no hashes — both
+                // unverifiable, so both drop (safety over convenience).
+                if (this.readHashesStillMatch(rehydrated, lines)) {
+                    this.recordRead(rehydrated);
+                    result.imported += 1;
+                }
+                else {
+                    result.dropped += 1;
+                }
+            }
+        }
+        return result;
     }
     /**
      * Get all edit records for a file (for debugging).
      */
     getEditHistory(filePath) {
-        return this.edits.get(this.key(filePath)) ?? [];
+        const key = this.key(filePath);
+        if (this.edits.has(key))
+            this.touchFile(key);
+        return this.edits.get(key) ?? [];
     }
     // --- Private helpers ---
     injectCreationRead(filePath, turnIndex, writeIndex) {
@@ -848,6 +1106,7 @@ export class ReadGuard {
         return { action: "allow" };
     }
     recordEdit(filePath, tool, touchedLines, verdict) {
+        this.touchFile(filePath);
         const arr = this.edits.get(filePath) ?? [];
         arr.push({
             filePath,