@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/quiet-window-config.js

@@ -0,0 +1,47 @@
+/**
+ * Quiet-window kill switch and wait budget, split out of `quiet-window.ts` so a
+ * caller that only needs the NUMBERS does not have to import the scheduler.
+ *
+ * `cascade-budget.ts` is the caller that forced it (#1462): it reads both knobs
+ * to decide how much drain is really left, and depending on `quiet-window.ts`
+ * for that would point a pure arithmetic module at a task registry — module
+ * state (`_tasks`, `_inProgress`), a heartbeat sampler, latency logging, none
+ * of which it wants. Config belongs below the scheduler, not beside it.
+ *
+ * NOT a load-time win, despite what the first version of this comment claimed:
+ * `cascade-budget.ts` imports `runtime-config.ts` for `cascadeMaxFiles`, and
+ * that reaches `pidusage` through `lens-config.ts` regardless — probed, and
+ * `dispatch/integration.ts` already imported `runtime-config.ts` before #1462.
+ * The split is a dependency-direction fix and nothing more.
+ *
+ * `quiet-window.ts` re-exports all three, so every existing importer keeps
+ * working and there is still exactly one memo behind `isQuietWindowEnabled`.
+ */
+import { toPositiveFinite } from "./env-utils.js";
+let _enabledCache;
+/** `PI_LENS_QUIET_WINDOW=0` disables the whole scheduler (no-op, no logging). */
+export function isQuietWindowEnabled() {
+    if (_enabledCache !== undefined)
+        return _enabledCache;
+    _enabledCache = process.env.PI_LENS_QUIET_WINDOW !== "0";
+    return _enabledCache;
+}
+/** Test-only: clear the memoized kill-switch read. */
+export function _resetQuietWindowEnabledForTests() {
+    _enabledCache = undefined;
+}
+const DEFAULT_QUIET_WINDOW_WAIT_MS = 15_000;
+/**
+ * Bounded wait for the quiet-window's own settle attempts (currently just
+ * the carried-over cascade drain). Lazy env read, `Number.isFinite`-guarded
+ * so a malformed value falls back to the default instead of poisoning
+ * `Math.max`/`setTimeout` with `NaN` (see PR #109).
+ *
+ * This is the task's BUDGET, not a statement that the task runs — it keeps
+ * returning the default when `isQuietWindowEnabled()` is false. Callers asking
+ * "how long will the pipeline actually keep working on this" must check both.
+ */
+export function quietWindowWaitMs() {
+    const raw = toPositiveFinite(process.env.PI_LENS_QUIET_WINDOW_WAIT_MS);
+    return raw > 0 ? raw : DEFAULT_QUIET_WINDOW_WAIT_MS;
+}

package/node_modules/pi-lens/dist/clients/quiet-window.js

@@ -32,7 +32,7 @@
 import { readInstanceRegistry, updateHeartbeat, } from "./instance-registry.js";
 import { logLatency } from "./latency-logger.js";
 import { sampleProcesses } from "./resource-sampler.js";
-import { toPositiveFinite } from "./env-utils.js";
+import { _resetQuietWindowEnabledForTests, isQuietWindowEnabled, quietWindowWaitMs, } from "./quiet-window-config.js";
 // Module-level registry so future work (#458 Tier-3 reconcile, #236
 // enrichment) can plug into the same scheduler without touching it.
 const _tasks = [];
@@ -48,30 +48,14 @@ export function registerQuietWindowTask(name, fn) {
 export function _resetQuietWindowTasksForTests() {
     _tasks.length = 0;
 }
-// --- Kill switch (lazy, memoized — house style per clients/runtime-config.ts) ---
-let _enabledCache;
-/** `PI_LENS_QUIET_WINDOW=0` disables the whole scheduler (no-op, no logging). */
-export function isQuietWindowEnabled() {
-    if (_enabledCache !== undefined)
-        return _enabledCache;
-    _enabledCache = process.env.PI_LENS_QUIET_WINDOW !== "0";
-    return _enabledCache;
-}
-/** Test-only: clear the memoized kill-switch read. */
-export function _resetQuietWindowEnabledForTests() {
-    _enabledCache = undefined;
-}
-const DEFAULT_QUIET_WINDOW_WAIT_MS = 15_000;
-/**
- * Bounded wait for the quiet-window's own settle attempts (currently just
- * the carried-over cascade drain). Lazy env read, `Number.isFinite`-guarded
- * so a malformed value falls back to the default instead of poisoning
- * `Math.max`/`setTimeout` with `NaN` (see PR #109).
- */
-export function quietWindowWaitMs() {
-    const raw = toPositiveFinite(process.env.PI_LENS_QUIET_WINDOW_WAIT_MS);
-    return raw > 0 ? raw : DEFAULT_QUIET_WINDOW_WAIT_MS;
-}
+// --- Kill switch and wait budget ---
+//
+// #1462 review (N4): both live in `quiet-window-config.ts` now, so a caller
+// that needs only the numbers (`cascade-budget.ts`, on the dispatch load path)
+// does not drag this module's `resource-sampler` → `pidusage` import in with
+// them. Re-exported here so every existing importer is unaffected and there is
+// still one memo behind `isQuietWindowEnabled`.
+export { isQuietWindowEnabled, quietWindowWaitMs, _resetQuietWindowEnabledForTests, };
 // Re-entrancy guard: agent_settled can fire multiple times per session
 // (once per completed/aborted run). If a previous quiet-window run is still
 // in flight when the next fires, skip rather than queue/overlap.
@@ -224,6 +208,8 @@ async function buildHeartbeatResourcePatch() {
         const self = instances.find((instance) => instance.pid === process.pid);
         const childPids = self?.lspChildren.map((child) => child.pid) ?? [];
         const usage = await sampleProcesses([process.pid, ...childPids]);
+        if (usage === null)
+            return {};
         const childUsage = {};
         for (const pid of childPids) {
             const sample = usage.get(pid);

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

@@ -19,7 +19,7 @@ const SNAPSHOT_LOG_SETTING = (process.env.PI_LENS_READ_GUARD_LOG_SNAPSHOTS ?? "1
 const LOG_SNAPSHOT_VALIDATION = !["0", "false", "off"].includes(SNAPSHOT_LOG_SETTING);
 export const MAX_EDIT_BATCH_ITEMS = 100;
 let generatedCorrelationCounter = 0;
-function sanitizeCorrelationId(value) {
+export function sanitizeCorrelationId(value) {
     if (typeof value !== "string" && typeof value !== "number")
         return undefined;
     const sanitized = String(value)

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

@@ -12,7 +12,7 @@
 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 { normalizeEphemeralMapKey, normalizeFilePath } from "./path-utils.js";
 import { logReadGuardEvent } from "./read-guard-logger.js";
 export const READ_GUARD_STATE_VERSION = 1;
 // --- Constants ---
@@ -35,6 +35,61 @@ 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;
+/**
+ * Trim a single file's read list to the per-file cap. Returns how many records
+ * were dropped so the ledger can show the trim.
+ *
+ * Eviction is NOT purely by age. The shape that overflows this cap is
+ * read-once-then-grep-often: one whole-file read followed by hundreds of cheap
+ * search credits. Pure age order evicts that whole-file read first, and it is
+ * the record `canIgnoreStalenessByHashes` needs to rescue an edit after an
+ * unrelated mtime touch. So spend the search credits first, oldest among them
+ * first, and only fall through to genuine reads when the credits run out.
+ * Genuine reads are then evicted oldest-first as before.
+ *
+ * Records are trimmed IN PLACE: `EditRecord.precedingReads` holds a reference
+ * to this same array, so a replacement array would silently detach it.
+ */
+function enforceRecordCapForFile(records) {
+    if (records.length <= READ_GUARD_MAX_RECORDS_PER_FILE)
+        return 0;
+    const excess = records.length - READ_GUARD_MAX_RECORDS_PER_FILE;
+    const evicted = new Set();
+    for (let i = 0; i < records.length && evicted.size < excess; i++) {
+        if (records[i].searchCredit !== undefined)
+            evicted.add(i);
+    }
+    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 excess;
+}
+/**
+ * #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 +268,23 @@ 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();
     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 evictedRecordCount = enforceRecordCapForFile(arr);
         this.touchFile(storedRecord.filePath);
         this.enforceFileCap();
         logReadGuardEvent({
@@ -334,6 +423,15 @@ 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,
+                }),
             },
         });
         // Also update FileTime stamp for this file
@@ -442,9 +540,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 +580,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 +674,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 +698,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 +750,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))
@@ -838,7 +991,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 +1045,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 +1073,7 @@ export class ReadGuard {
                 missingLines: missingLines.slice(0, 20),
                 mismatchedLines: mismatchedLines.slice(0, 20),
                 enforced: shouldBlock || status === "match",
+                outcome,
             },
         });
         return {
@@ -1117,6 +1288,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);
             }