@herbertgao/pi-extensions 2026.8.6 → 2026.8.8

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

@@ -10,9 +10,10 @@
  * Falls back safely when LSP is unavailable.
  */
 import * as fs from "node:fs";
+import { incrementDegradationCount } from "./degradation-ledger.js";
 import { createFileTime } from "./file-time.js";
 import { hashDiagnosticContent } from "./lsp/diagnostic-binding.js";
-import { normalizeFilePath } from "./path-utils.js";
+import { normalizeEphemeralMapKey, normalizeFilePath } from "./path-utils.js";
 import { logReadGuardEvent } from "./read-guard-logger.js";
 export const READ_GUARD_STATE_VERSION = 1;
 // --- Constants ---
@@ -35,6 +36,58 @@ const READ_HASH_MAX_LINES = Math.max(0, Number.parseInt(process.env.PI_LENS_READ
  */
 const READ_BINDING_MAX_BYTES = 4 * 1024 * 1024;
 const READ_GUARD_MAX_FILES = 256;
+/**
+ * #1904 item 3: `enforceFileCap` bounds how many FILES the store holds, not how
+ * many records each file holds. One hot file reached 268 hash-bearing records in
+ * 75 minutes, and every record carries a `lineHashes` map, so a long session on
+ * a few files grows without bound. Cap records per file and drop oldest-first.
+ *
+ * Eviction is safe in the blocking direction: it narrows the staleness-rescue
+ * path — a stale edit rescued by an older snapshot that still matches — and can
+ * turn an allow into a "re-read and retry" block. It never turns a block into
+ * an allow. See `enforceRecordCapForFile` for which records go first, and why
+ * age alone is the wrong order.
+ */
+const READ_GUARD_MAX_RECORDS_PER_FILE = 128;
+const NO_TRIM = {
+    evictedCount: 0,
+    evictedCreditCount: 0,
+    evictedGenuineCount: 0,
+};
+function enforceRecordCapForFile(records) {
+    if (records.length <= READ_GUARD_MAX_RECORDS_PER_FILE)
+        return NO_TRIM;
+    const excess = records.length - READ_GUARD_MAX_RECORDS_PER_FILE;
+    const evicted = new Set();
+    let evictedCreditCount = 0;
+    for (let i = 0; i < records.length && evicted.size < excess; i++) {
+        if (records[i].searchCredit !== undefined) {
+            evicted.add(i);
+            evictedCreditCount++;
+        }
+    }
+    for (let i = 0; i < records.length && evicted.size < excess; i++) {
+        evicted.add(i);
+    }
+    const kept = records.filter((_, i) => !evicted.has(i));
+    records.length = 0;
+    for (const record of kept)
+        records.push(record);
+    return {
+        evictedCount: excess,
+        evictedCreditCount,
+        evictedGenuineCount: excess - evictedCreditCount,
+    };
+}
+/**
+ * #1904 class sweep: `this.edits` is the same shape as `this.reads` — a
+ * per-file array that only ever grows. Its cap sits far above every consumer's
+ * reach, so trimming is inert: `canTreatStalenessAsOwnPriorEdit` reads only the
+ * last record, and `findRelocation`'s window saturates at
+ * RELOCATION_WINDOW_MAX / RELOCATION_WINDOW_PER_EDIT (20) applied edits. Only
+ * `getStats`, a debug surface, sees the older records at all.
+ */
+const READ_GUARD_MAX_EDITS_PER_FILE = 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;
@@ -213,6 +266,25 @@ export class ReadGuard {
     // pi Write tool authored, independent of filesystem mtime granularity
     // or clock skew (NFS, FAT32, etc.).
     writtenThisSession = new Set();
+    // Existence-independent index for hasKnownPath/forgetPath (#1668 review
+    // F1). `this.key()` (normalizeFilePath) branches on whether `filePath`
+    // currently exists on disk: an existing file resolves to realpathSync
+    // canonical casing, a missing one to a lowercased tail. recordRead/
+    // recordWritten always key while the file is still on disk (real
+    // casing); hasKnownPath/forgetPath are queried AFTER an external delete
+    // already landed, when the path no longer exists — recomputing
+    // `this.key()` at that point returns a DIFFERENT string for any
+    // mixed-case basename (`MyModule.ts` → `mymodule.ts`), so a lookup
+    // against `reads`/`writtenThisSession` silently misses. This index maps
+    // a purely syntactic key (`normalizeEphemeralMapKey` — slash-fold +
+    // lowercase, no filesystem access, so it never depends on current disk
+    // state) to the REAL key `reads`/`writtenThisSession` used at record
+    // time, so a post-delete lookup finds the same entry regardless of what
+    // happened to the file since. Pruned inside `evictFile` so it never
+    // outlives the record it points at.
+    knownPathIndex = new Map();
+    /** Running per-file record-cap trim totals for this session (#1913 F1). */
+    trimAccumulators = new Map();
     sessionId;
     sessionStartMs;
     constructor(sessionId, config = {}) {
@@ -236,7 +308,9 @@ export class ReadGuard {
     }
     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;
+        return Number.isSafeInteger(value) && value > 0
+            ? value
+            : READ_GUARD_IDLE_EVICT_MS_DEFAULT;
     }
     clearFileTimer(filePath) {
         const timer = this.fileIdleTimers.get(filePath);
@@ -251,6 +325,12 @@ export class ReadGuard {
         this.fileLastUsed.delete(filePath);
         this.consumedReadFiles.delete(filePath);
         this.writtenThisSession.delete(filePath);
+        // #1668 review F1: prune the reverse-pointing knownPathIndex entries
+        // too, so it never outlives the record it points at.
+        for (const [syntacticKey, stored] of this.knownPathIndex) {
+            if (stored === filePath)
+                this.knownPathIndex.delete(syntacticKey);
+        }
     }
     touchFile(filePath) {
         const now = Date.now();
@@ -285,8 +365,7 @@ export class ReadGuard {
         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];
+                .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,
@@ -301,6 +380,11 @@ export class ReadGuard {
      */
     recordRead(record) {
         const filePath = this.key(record.filePath);
+        // #1668 review F1: index by the existence-independent syntactic key
+        // while the file is (presumably) still on disk, so a later
+        // hasKnownPath/forgetPath lookup after an external delete can still
+        // find this entry's real key.
+        this.knownPathIndex.set(normalizeEphemeralMapKey(record.filePath), filePath);
         const storedRecord = {
             ...record,
             filePath,
@@ -311,6 +395,11 @@ export class ReadGuard {
         this.consumedReadFiles.delete(storedRecord.filePath);
         arr.push(storedRecord);
         this.reads.set(storedRecord.filePath, arr);
+        // Capture BEFORE the trim: `readCountForFile` saturates at the cap once
+        // eviction starts, so it stops showing growth. `rawReadCountForFile` keeps
+        // the real arrival count observable alongside `evictedRecordCount`.
+        const rawReadCountForFile = arr.length;
+        const { evictedCount: evictedRecordCount, evictedCreditCount, evictedGenuineCount } = enforceRecordCapForFile(arr);
         this.touchFile(storedRecord.filePath);
         this.enforceFileCap();
         logReadGuardEvent({
@@ -334,8 +423,74 @@ export class ReadGuard {
                 ...(storedRecord.source !== undefined && {
                     source: storedRecord.source,
                 }),
+                ...(storedRecord.searchCredit !== undefined && {
+                    searchCreditReason: storedRecord.searchCredit.reason,
+                    searchCreditMarginBefore: storedRecord.searchCredit.marginBefore,
+                    searchCreditMarginAfter: storedRecord.searchCredit.marginAfter,
+                }),
+                ...(evictedRecordCount > 0 && {
+                    evictedRecordCount,
+                    rawReadCountForFile,
+                }),
             },
         });
+        // #1913: the eviction counters above ride `read_recorded`, which is
+        // gated behind PI_LENS_READ_GUARD_VERBOSE — off by default. That left a
+        // live eviction regression with no trace at default verbosity.
+        //
+        // review F1: a naive "emit every trim" fix floods read-guard.log once a
+        // hot file sits past the cap — every later push trims exactly 1 record
+        // (the array is always AT the cap before the push, so `excess` is
+        // always exactly 1), so 300 recordRead calls on one file is ~172
+        // identical always-on lines, and can rotate `edit_blocked` records out
+        // of the 1MB cap. `rawReadCountForFile` also freezes at cap+1 forever,
+        // so a raw per-trim record can't even discriminate thrash severity.
+        //
+        // Fix: emit the read-guard.log line ONCE per file per session, on the
+        // FIRST trim only. `trimAccumulators` still updates on every trim,
+        // queryable via `getTrimStats` — the running totals a health surface or
+        // a future emission point would need are never lost, even though
+        // read-guard.log stops re-announcing them. "Have we already logged
+        // this file's first trim" routes through the degradation ledger's own
+        // rising-edge tally (`incrementDegradationCount` — the pattern
+        // CLAUDE.md names for repeated degradations) instead of a hand-rolled
+        // per-file Set; subsequent trims still call it, so the ledger's own
+        // entry for this (kind, subject) keeps its reason text and count
+        // current for the health/degradation summary even after read-guard.log
+        // goes quiet.
+        if (evictedRecordCount > 0) {
+            const key = storedRecord.filePath;
+            const acc = this.trimAccumulators.get(key) ?? {
+                totalEvicted: 0,
+                evictedCreditCount: 0,
+                evictedGenuineCount: 0,
+                trimEventCount: 0,
+            };
+            acc.totalEvicted += evictedRecordCount;
+            acc.evictedCreditCount += evictedCreditCount;
+            acc.evictedGenuineCount += evictedGenuineCount;
+            acc.trimEventCount += 1;
+            this.trimAccumulators.set(key, acc);
+            const isRisingEdge = incrementDegradationCount({
+                kind: "read-guard-record-cap-trim",
+                subject: key,
+                reason: `trim #${acc.trimEventCount}: evicted ${evictedRecordCount} (credit ${evictedCreditCount}, genuine ${evictedGenuineCount})`,
+            });
+            if (isRisingEdge) {
+                logReadGuardEvent({
+                    event: "read_cap_trimmed",
+                    sessionId: this.sessionId,
+                    filePath: storedRecord.filePath,
+                    metadata: {
+                        trimEventCount: acc.trimEventCount,
+                        evictedRecordCount: acc.totalEvicted,
+                        evictedCreditCount: acc.evictedCreditCount,
+                        evictedGenuineCount: acc.evictedGenuineCount,
+                        rawReadCountForFile,
+                    },
+                });
+            }
+        }
         // Also update FileTime stamp for this file
         this.fileTime.read(storedRecord.filePath);
     }
@@ -442,9 +597,17 @@ export class ReadGuard {
         // 2. FileTime check (actual staleness)
         let ignoredOwnEditStaleness = false;
         let ignoredHashStaleness = false;
+        let ignoredOldTextResolvedStaleness = false;
         if (this.fileTime.hasChanged(filePath)) {
             const lastRead = fileReads[fileReads.length - 1];
-            if (this.canTreatStalenessAsOwnPriorEdit(filePath, lastRead.timestamp)) {
+            if (options?.oldTextResolved === true) {
+                // The host-facing preflight sets this only after oldText resolves to
+                // exactly one span in the live bytes. That content evidence is newer
+                // and stronger than FileTime's coarse external-write signal, matching
+                // the skipSnapshotCheck exception at the later range-stale gate.
+                ignoredOldTextResolvedStaleness = true;
+            }
+            else if (this.canTreatStalenessAsOwnPriorEdit(filePath, lastRead.timestamp)) {
                 ignoredOwnEditStaleness = true;
             }
             else if (this.canIgnoreStalenessByHashes(filePath, fileReads, touchedLines, editRanges)) {
@@ -474,7 +637,7 @@ export class ReadGuard {
         const rangesToCheck = editRanges && editRanges.length > 1 ? editRanges : [touchedLines];
         let viaSymbol = false;
         for (const range of rangesToCheck) {
-            const snapshotValidation = this.validateRangeSnapshot(filePath, range);
+            const snapshotValidation = this.validateRangeSnapshot(filePath, range, !!options?.skipSnapshotCheck);
             const coverage = this.checkCoverage(filePath, range);
             if (!coverage.covered) {
                 const lastRead = fileReads[fileReads.length - 1];
@@ -568,10 +731,15 @@ export class ReadGuard {
         }
         const verdict = this.allow();
         this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-            reasonKind: viaSymbol ? "symbol_coverage" : "range_coverage",
+            reasonKind: ignoredOldTextResolvedStaleness
+                ? "file_modified_oldtext_unique"
+                : viaSymbol
+                    ? "symbol_coverage"
+                    : "range_coverage",
             viaSymbol,
             ignoredOwnEditStaleness,
             ignoredHashStaleness,
+            oldTextResolved: ignoredOldTextResolvedStaleness,
         });
         return verdict;
     }
@@ -587,6 +755,44 @@ export class ReadGuard {
             return true; // Assume new if we can't stat
         }
     }
+    /**
+     * Whether pi-lens has any record of this path from a read or write this
+     * session (#1668). Gates external-delete detection: a path pi-lens never
+     * read or wrote is one no LSP server's cache was ever told about through
+     * us, so an `rm` naming it carries no signal worth checking disk for —
+     * this is a lookup against state already being tracked, never a fresh
+     * filesystem stat over an unbounded path set.
+     *
+     * MUST go through `knownPathIndex`, not `this.key(filePath)` directly
+     * (#1668 review F1): this is called AFTER a bash delete has already
+     * landed, when `filePath` no longer exists — `this.key()` at that point
+     * returns a lowercased-tail key, not the real-casing key `recordRead`/
+     * `recordWritten` stored while the file was still on disk. For a
+     * mixed-case basename (`MyModule.ts`) the two keys differ and a direct
+     * `this.key()` lookup always misses.
+     */
+    hasKnownPath(filePath) {
+        const stored = this.knownPathIndex.get(normalizeEphemeralMapKey(filePath));
+        return (stored !== undefined &&
+            (this.reads.has(stored) || this.writtenThisSession.has(stored)));
+    }
+    /**
+     * Drop all record of a path pi-lens confirmed no longer exists on disk
+     * (#1668, external delete). Without this a later write reusing the same
+     * path would inherit a stale writtenThisSession/reads entry from before
+     * the delete, and a repeat `rm` of the same already-gone path would keep
+     * matching {@link hasKnownPath} and re-emitting a type-3 notification.
+     *
+     * MUST evict through `knownPathIndex`, not `this.key(filePath)` directly
+     * (#1668 review F1) — same reasoning as {@link hasKnownPath}: `filePath`
+     * is already gone from disk by the time this runs, so recomputing
+     * `this.key()` targets the wrong (lowercased-tail) key for a mixed-case
+     * basename and leaves the real entry behind un-evicted.
+     */
+    forgetPath(filePath) {
+        const stored = this.knownPathIndex.get(normalizeEphemeralMapKey(filePath));
+        this.evictFile(stored ?? this.key(filePath));
+    }
     /**
      * Mark a file as pending creation (Write tool to a non-existing file).
      * Must be called from the tool_call handler before the write lands so
@@ -601,8 +807,12 @@ export class ReadGuard {
      * Call this from the tool_result handler so the next checkEdit on the same
      * file doesn't see "file_modified" caused by our own previous edit.
      */
-    recordWritten(filePath) {
-        filePath = this.key(filePath);
+    recordWritten(rawFilePath) {
+        const filePath = this.key(rawFilePath);
+        // #1668 review F1: index by the existence-independent syntactic key
+        // (see `knownPathIndex`) so a later hasKnownPath/forgetPath lookup
+        // after an external delete can still find this entry's real key.
+        this.knownPathIndex.set(normalizeEphemeralMapKey(rawFilePath), filePath);
         this.fileTime.read(filePath);
         this.writtenThisSession.add(filePath);
         if (this.reads.has(filePath))
@@ -675,6 +885,18 @@ export class ReadGuard {
             this.touchFile(key);
         return this.reads.get(key) ?? [];
     }
+    /**
+     * Session-lifetime record-cap trim totals for a file (#1913 review F1).
+     * `recordRead` only writes ONE `read_cap_trimmed` read-guard.log line per
+     * file per session (on the first trim), so this is the running-totals
+     * surface for everything after that — the exact split this class already
+     * computes on every trim, not re-derivable from `getReadHistory` alone
+     * (which only shows the SURVIVING records, not what was evicted).
+     */
+    getTrimStats(filePath) {
+        const stats = this.trimAccumulators.get(this.key(filePath));
+        return stats ? { ...stats } : undefined;
+    }
     /**
      * Snapshot the read-set for persistence across a session resume (#1041).
      * Mirrors widget-state's `exportWidgetState`: the Map is emitted as
@@ -838,7 +1060,13 @@ export class ReadGuard {
         return (read.enclosingSymbol.startLine <= editStart &&
             read.enclosingSymbol.endLine >= editEnd);
     }
-    validateRangeSnapshot(filePath, range) {
+    validateRangeSnapshot(filePath, range, 
+    /**
+     * What the CALLER will do with the verdict. `checkEdit` honours
+     * `skipSnapshotCheck` for content-validated (oldText) edits, so a
+     * `shouldBlock` verdict may never reach the gate (#1904 item 1).
+     */
+    snapshotCheckSkipped) {
         const reads = this.reads.get(filePath) ?? [];
         const candidates = reads.filter((read) => this.readCoversRange(read, range));
         let status = "unavailable";
@@ -886,6 +1114,17 @@ export class ReadGuard {
             lastUnavailableTimestamp <= lastMismatchTimestamp &&
             checkedCandidateCount > 0 &&
             hashUnavailableCandidateCount === 0;
+        // `enforced` below states INTENT — whether this validation reached a
+        // decidable verdict. It says nothing about what the caller did with it.
+        // `outcome` states the caller's actual behaviour, which is what an
+        // enforcement rate must be computed from (#1904 item 1).
+        const outcome = shouldBlock
+            ? snapshotCheckSkipped
+                ? "bypassed-content-match"
+                : "enforced-block"
+            : status === "match"
+                ? "enforced-pass"
+                : "not-decidable";
         logReadGuardEvent({
             event: "range_snapshot_validation",
             sessionId: this.sessionId,
@@ -903,6 +1142,7 @@ export class ReadGuard {
                 missingLines: missingLines.slice(0, 20),
                 mismatchedLines: mismatchedLines.slice(0, 20),
                 enforced: shouldBlock || status === "match",
+                outcome,
             },
         });
         return {
@@ -1117,6 +1357,9 @@ export class ReadGuard {
             reason: verdict.reason,
             timestamp: Date.now(),
         });
+        if (arr.length > READ_GUARD_MAX_EDITS_PER_FILE) {
+            arr.splice(0, arr.length - READ_GUARD_MAX_EDITS_PER_FILE);
+        }
         this.edits.set(filePath, arr);
     }
     recordVerdict(filePath, tool, touchedLines, verdict, metadata = {}) {

package/node_modules/pi-lens/dist/clients/resource-sampler.js

@@ -45,7 +45,18 @@
  */
 import * as path from "node:path";
 import pidusage from "pidusage";
-import { spawnCollectStdout } from "./child-unref.js";
+import { spawnCollectStdoutResult } from "./child-unref.js";
+import { recordDegradationOnce } from "./degradation-ledger.js";
+import { terminateScannerChild } from "./instance-reaper.js";
+export const RESOURCE_SAMPLE_QUERY_TIMEOUT_MS = 2_000;
+function recordQueryFailure(subject, status, exitCode) {
+    const exitReason = status === "exit-error" ? ` (exit code ${exitCode ?? "unknown"})` : "";
+    recordDegradationOnce({
+        kind: "resource-sampler-query-failed",
+        subject,
+        reason: `process-table query ${status}${exitReason}`,
+    });
+}
 // Read the platform live (not a module-load const) so both the Windows and the
 // POSIX sampling paths are exercisable in unit tests regardless of the host OS.
 function runningOnWindows() {
@@ -113,12 +124,18 @@ async function findDescendantPidsWindows(rootPid) {
     // reaper's identical spawn→collect plumbing (#1153/#1160). Sampling still
     // works normally in an interactive/long-lived session: unref only means
     // "don't hold the loop open FOR this alone," the collected stdout is still
-    // delivered whenever `close` fires. Resolves to `""` on any spawn/`error`
-    // failure, which the parse below turns into an empty pairs list (same
-    // result the old inline `resolve([])` error path produced).
-    const out = await spawnCollectStdout(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+    // delivered whenever `close` fires. The result status keeps a failed query
+    // distinct from a successful empty process table.
+    const result = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, {
+        timeoutMs: RESOURCE_SAMPLE_QUERY_TIMEOUT_MS,
+        onTimeout: (child) => terminateScannerChild(child, {}),
+    });
+    if (result.status !== "ok") {
+        recordQueryFailure("windows-descendant-process-table", result.status, result.exitCode);
+        return null;
+    }
     const pairs = [];
-    for (const line of out.split(/\r?\n/)) {
+    for (const line of result.stdout.split(/\r?\n/)) {
         const [pidStr, ppidStr] = line.split(",");
         const pid = Number(pidStr);
         const ppid = Number(ppidStr);
@@ -142,7 +159,7 @@ export function __resetWindowsCpuHistoryForTests() {
  * Windows-only CPU%/RSS sampling via a FULLY GUARDED `Get-CimInstance
  * Win32_Process` query (mirrors `findDescendantPidsWindows`): a synchronous
  * throw from `spawn` (the `spawn UNKNOWN` crash vector, #620), a `child`
- * `error` event, or a non-zero/garbage exit all resolve to a partial/empty
+ * `error` event, or a non-zero/garbage exit all resolve to an errored/absent
  * map — this function can NEVER throw or reject. Deliberately does NOT call
  * `pidusage`, whose unguarded internal `gwmi` spawn is the crash we're fixing.
  *
@@ -153,9 +170,9 @@ export function __resetWindowsCpuHistoryForTests() {
  * reported as 0 for that tick and a real rate lands on the next one.
  */
 async function sampleProcessesWindows(valid) {
-    const result = new Map();
+    const samples = new Map();
     if (valid.length === 0)
-        return result;
+        return samples;
     // pids are pre-validated finite positive integers, so this WQL filter is
     // injection-safe. One line per pid: "pid,workingSet,kernel100ns,user100ns".
     const filter = valid.map((p) => `ProcessId=${p}`).join(" or ");
@@ -169,15 +186,21 @@ async function sampleProcessesWindows(valid) {
     // reaper's identical spawn→collect plumbing (#1153/#1160). It also absorbs
     // both failure modes this function used to guard inline — a synchronous
     // `spawn` throw (the `spawn UNKNOWN` crash vector, #620) and an async
-    // `error` event — resolving to `""` either way, which the parse below
-    // turns into the same empty/partial `result` map the old inline handlers
-    // produced. Sampling still works normally in an interactive/long-lived
+    // `error` event, or a non-zero exit — the result status keeps failure distinct
+    // map. Sampling still works normally in an interactive/long-lived
     // session: unref only means "don't hold the loop open FOR this alone."
-    const out = await spawnCollectStdout(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+    const query = await spawnCollectStdoutResult(powershell, ["-NoProfile", "-NonInteractive", "-Command", psScript], { shell: false, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }, {
+        timeoutMs: RESOURCE_SAMPLE_QUERY_TIMEOUT_MS,
+        onTimeout: (child) => terminateScannerChild(child, {}),
+    });
+    if (query.status !== "ok") {
+        recordQueryFailure("windows-process-table", query.status, query.exitCode);
+        return null;
+    }
     try {
         const now = Date.now();
         const seen = new Set();
-        for (const line of out.split(/\r?\n/)) {
+        for (const line of query.stdout.split(/\r?\n/)) {
             const parts = line.split(",");
             if (parts.length < 4)
                 continue;
@@ -202,7 +225,7 @@ async function sampleProcessesWindows(valid) {
             }
             windowsCpuHistory.set(pid, { cpuMs, ts: now });
             seen.add(pid);
-            result.set(pid, { rssBytes: workingSet, cpuPercent });
+            samples.set(pid, { rssBytes: workingSet, cpuPercent });
         }
         // Prune stale history so pids that have gone away don't accumulate.
         for (const [pid, entry] of windowsCpuHistory) {
@@ -214,7 +237,7 @@ async function sampleProcessesWindows(valid) {
     catch {
         // Parsing must never throw into the caller; best-effort.
     }
-    return result;
+    return samples;
 }
 /**
  * Sample CPU%/RSS for a set of pids. Best-effort: a pid that can't be resolved
@@ -248,8 +271,10 @@ export async function sampleProcesses(pids) {
         }
     }
     catch {
+        recordQueryFailure("posix-pidusage-process-table", "spawn-error");
         // Best-effort: sampling failure loses this tick's data for every pid in
         // the batch, but must never throw into the heartbeat/spawn path.
+        return null;
     }
     return result;
 }
@@ -321,10 +346,17 @@ export function startSpawnUsageSampler(pid, intervalMs = 750) {
         if (stopped)
             return;
         try {
+            const descendants = runningOnWindows()
+                ? await findDescendantPidsWindows(targetPid)
+                : [];
+            if (descendants === null)
+                return;
             const pids = runningOnWindows()
-                ? [targetPid, ...(await findDescendantPidsWindows(targetPid))]
+                ? [targetPid, ...descendants]
                 : [targetPid];
             const usageByPid = await sampleProcesses(pids);
+            if (usageByPid === null)
+                return;
             if (stopped || usageByPid.size === 0)
                 return;
             let rssBytes = 0;

package/node_modules/pi-lens/dist/clients/reverse-deps.js

@@ -33,14 +33,30 @@ function addEdge(index, fromFile, toFile) {
     (index.importedBy[to] ??= []).push(from);
 }
 function normalizeIndex(index) {
-    const fileKeys = new Set([
-        ...Object.keys(index.imports),
+    // #1814 F2: `imports[file]` asserts "we know file's complete import
+    // list" — true only when `index.imports` already has a raw entry for
+    // `file` (from a real per-file scan). `importedBy[file]` asserts "we
+    // know SOME importer of file", which holds regardless of whether `file`
+    // itself was ever scanned. Materializing `imports[file] = []` for every
+    // key in their UNION (the pre-fix behavior) fabricated the first claim
+    // for a file that is only an `importedBy` target — imported by
+    // something, never itself scanned — indistinguishable downstream from a
+    // file the scan confirmed has zero imports.
+    // `clients/lsp/workspace-diagnostics-cache.ts`'s `getImports` reads this
+    // map directly and relies on `undefined` meaning "not covered". Only
+    // `importedBy` keeps the union treatment: "who imports me" has no
+    // equivalent "was I scanned" precondition to fabricate.
+    const importFileKeys = [...new Set(Object.keys(index.imports))].sort((a, b) => a.localeCompare(b));
+    const allFileKeys = new Set([
+        ...importFileKeys,
         ...Object.keys(index.importedBy),
     ]);
     const imports = {};
-    const importedBy = {};
-    for (const file of [...fileKeys].sort((a, b) => a.localeCompare(b))) {
+    for (const file of importFileKeys) {
         imports[file] = sortedUnique(index.imports[file] ?? []);
+    }
+    const importedBy = {};
+    for (const file of [...allFileKeys].sort((a, b) => a.localeCompare(b))) {
         importedBy[file] = sortedUnique(index.importedBy[file] ?? []);
     }
     return { ...index, imports, importedBy };
@@ -120,12 +136,24 @@ export function buildReverseDependencyIndexFromSnapshot(snapshot) {
     };
     for (const [filePath, file] of fileEntries) {
         const normalized = normalizeMapKey(file.path || filePath);
-        index.imports[normalized] = sortedUnique(file.imports ?? []);
-        index.importedBy[normalized] ??= [];
-        for (const imported of index.imports[normalized]) {
-            index.importedBy[imported] ??= [];
-            index.importedBy[imported].push(normalized);
+        // #1814 F2: only materialize `imports[normalized]` when this
+        // snapshot entry genuinely recorded an import list. `file.imports`
+        // absent means this file was captured in the snapshot (e.g. a
+        // lightweight touch) but never had its own imports scanned —
+        // defaulting to `[]` here fabricated the "covered, zero imports"
+        // claim `getImports` (workspace-diagnostics-cache.ts) distinguishes
+        // from "not covered". `hasFileImports` above already anticipates a
+        // mixed snapshot with entries in both states; this closes the gap
+        // per entry.
+        if (Array.isArray(file.imports)) {
+            const imports = sortedUnique(file.imports);
+            index.imports[normalized] = imports;
+            for (const imported of imports) {
+                index.importedBy[imported] ??= [];
+                index.importedBy[imported].push(normalized);
+            }
         }
+        index.importedBy[normalized] ??= [];
     }
     for (const [filePath, importers] of Object.entries(reverseDeps)) {
         const normalized = normalizeMapKey(filePath);
@@ -133,9 +161,20 @@ export function buildReverseDependencyIndexFromSnapshot(snapshot) {
             ...(index.importedBy[normalized] ?? []),
             ...importers,
         ]);
-        index.imports[normalized] ??= [];
+        // #1814 F2 (class sweep): do NOT fabricate `imports[normalized] = []`
+        // here — `reverseDeps` records who imports `normalized`, not what
+        // `normalized` itself imports. Leave `imports[normalized]` exactly
+        // as the fileEntries loop above established it: present and real
+        // from a scan, or absent because this file was never scanned.
         for (const importer of index.importedBy[normalized]) {
-            index.imports[importer] ??= [];
+            // #1814 F2: only record this edge on `importer`'s own imports
+            // list when that list is already genuinely known (a real
+            // per-file scan from the fileEntries loop above) — appending to
+            // an absent list would silently promote "we know ONE edge from
+            // reverseDeps" into "we know importer's COMPLETE import list",
+            // the same false-coverage claim closed above.
+            if (index.imports[importer] === undefined)
+                continue;
             if (!index.imports[importer].includes(normalized)) {
                 index.imports[importer].push(normalized);
             }