@herbertgao/pi-extensions 2026.8.7 → 2026.8.8

package/node_modules/pi-lens/dist/clients/ndjson-logger.js

@@ -131,6 +131,35 @@ export function getRegisteredLogFiles() {
 export function _resetRegisteredLogFilesForTest() {
     registeredLogFiles.clear();
 }
+/**
+ * Snapshot of unrecovered write losses, one entry per sink that has any
+ * (#1970). Pure in-memory read — no I/O, so a caller (`degradation-ledger.ts`)
+ * can fold this into a durable ledger entry without this module ever writing
+ * a record about its own failure through the sink that is failing. See
+ * `NdjsonWriterState.writeFailures` for the recursion-hazard rationale.
+ */
+export function getSinkWriteFailures() {
+    if (!ndjsonGlobalState)
+        return [];
+    const result = [];
+    for (const state of ndjsonGlobalState.writers.values()) {
+        if (state.writeFailures > 0) {
+            result.push({ file: state.file, droppedCount: state.writeFailures });
+        }
+    }
+    return result;
+}
+/**
+ * Session-boundary reset (catalog shape 17: a process-lifetime latch must
+ * re-arm at session_start). Wired into `resetDegradationLedger()` so both
+ * reset together; also used directly by tests.
+ */
+export function resetSinkWriteFailures() {
+    if (!ndjsonGlobalState)
+        return;
+    for (const state of ndjsonGlobalState.writers.values())
+        state.writeFailures = 0;
+}
 function requireCurrentGlobalState() {
     if (ndjsonGlobalState)
         return ndjsonGlobalState;
@@ -159,17 +188,46 @@ function assertCompatibleWriterOptions(existing, maxBytes, backupPath) {
     throw new Error(`createNdjsonLogger: incompatible options for shared path ${existing.file}; ` +
         `the first writer's maxBytes/backupPath must be reused`);
 }
+function writeQueueItemSync(state, item) {
+    if (item.kind === "truncate") {
+        fs.writeFileSync(state.file, "");
+    }
+    else {
+        rotateIfNeeded(state);
+        fs.appendFileSync(state.file, item.line);
+    }
+}
+/**
+ * The pi-analyze #15 shape (#1970): a write that throws — including the
+ * `ERR_STREAM_DESTROYED` a torn-down sink produces — gets one reopen-and-
+ * retry before it counts as a loss. There is no persistent handle to close
+ * here (every write already opens, writes, and closes in one call), so
+ * "reopen" means dropping the cached `ensuredDir` assumption and
+ * re-verifying the parent directory before the retry — the one piece of
+ * cross-write state this module holds that a destroyed sink could have
+ * invalidated. An unrecovered write is counted, never thrown or retried a
+ * second time (`applyQueueItemSync`, `applyQueueItemAsync`, and the batched
+ * write in `drainLoop` skip DIFFERENT amounts of work per queue item, so
+ * each keeps its own copy of this two-step shape rather than sharing one
+ * generic retry wrapper across sync/async).
+ */
 function applyQueueItemSync(state, item) {
     ensureDirSync(state);
-    runBestEffort(() => {
-        if (item.kind === "truncate") {
-            fs.writeFileSync(state.file, "");
-        }
-        else {
-            rotateIfNeeded(state);
-            fs.appendFileSync(state.file, item.line);
-        }
-    });
+    try {
+        writeQueueItemSync(state, item);
+        return;
+    }
+    catch {
+        // fall through to the one reopen-and-retry
+    }
+    state.ensuredDir = false;
+    ensureDirSync(state);
+    try {
+        writeQueueItemSync(state, item);
+    }
+    catch {
+        state.writeFailures += 1;
+    }
 }
 function flushStateSync(state) {
     // Drain the in-memory queue synchronously — safe at process exit.
@@ -208,6 +266,9 @@ function createWriterState(file, maxBytes, backupPath) {
         assertCompatibleWriterOptions(existing, maxBytes, backupPath);
         if (!exitFlushers.has(existing.exitFlusher))
             registerWriter(existing);
+        // A state adopted from a pre-#1970 module graph predates this field.
+        if (typeof existing.writeFailures !== "number")
+            existing.writeFailures = 0;
         return existing;
     }
     const state = {};
@@ -220,6 +281,7 @@ function createWriterState(file, maxBytes, backupPath) {
     state.syncRepairItems = null;
     state.ensuredDir = false;
     state.exitFlusher = () => flushStateSync(state);
+    state.writeFailures = 0;
     globalState.writers.set(file, state);
     registerWriter(state);
     return state;
@@ -258,23 +320,36 @@ function rotateIfNeeded(state) {
         // no file yet, or rename raced — nothing to rotate
     }
 }
+async function writeQueueItemAsync(state, item) {
+    if (item.kind === "truncate") {
+        await fs.promises.writeFile(state.file, "");
+    }
+    else {
+        // Rotation is deliberately synchronous here. This function is only
+        // reached from the already-deferred drain, and keeping stat/rm/rename
+        // in one synchronous section prevents flushSync from racing a late
+        // async rename after it has written new data.
+        rotateIfNeeded(state);
+        await fs.promises.appendFile(state.file, item.line);
+    }
+}
+/** See `applyQueueItemSync`'s doc comment for the reopen-and-retry-once shape. */
 async function applyQueueItemAsync(state, item) {
     await ensureDirAsync(state);
     try {
-        if (item.kind === "truncate") {
-            await fs.promises.writeFile(state.file, "");
-        }
-        else {
-            // Rotation is deliberately synchronous here. This function is only
-            // reached from the already-deferred drain, and keeping stat/rm/rename
-            // in one synchronous section prevents flushSync from racing a late
-            // async rename after it has written new data.
-            rotateIfNeeded(state);
-            await fs.promises.appendFile(state.file, item.line);
-        }
+        await writeQueueItemAsync(state, item);
+        return;
     }
     catch {
-        // telemetry is best-effort
+        // fall through to the one reopen-and-retry
+    }
+    state.ensuredDir = false;
+    await ensureDirAsync(state);
+    try {
+        await writeQueueItemAsync(state, item);
+    }
+    catch {
+        state.writeFailures += 1;
     }
 }
 async function drainLoop(state) {
@@ -292,7 +367,7 @@ async function drainLoop(state) {
             ? [item]
             : state.queue.slice(0, pendingEnd);
         state.inFlightBatch = pending;
-        try {
+        const writeBatch = async () => {
             if (item.kind === "truncate") {
                 await fs.promises.writeFile(state.file, "");
             }
@@ -305,9 +380,25 @@ async function drainLoop(state) {
                     .map((queued) => queued.line)
                     .join(""));
             }
+        };
+        try {
+            await writeBatch();
         }
         catch {
-            // telemetry is best-effort
+            // Reopen-and-retry once (#1970, pi-analyze #15 shape): a destroyed
+            // sink (ERR_STREAM_DESTROYED) or a directory that vanished mid-session
+            // gets exactly one recovery attempt before the batch counts as a loss.
+            state.ensuredDir = false;
+            await ensureDirAsync(state);
+            try {
+                await writeBatch();
+            }
+            catch {
+                // Unrecovered: count every line in this batch as dropped. Purely
+                // in-memory — see `writeFailures`'s doc comment for why this must
+                // never itself attempt a durable write through this same sink.
+                state.writeFailures += pending.length;
+            }
         }
         for (const written of pending) {
             // flushSync may have drained this prefix while the append is in

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

@@ -288,17 +288,26 @@ async function scanFileMajorRules(cwd, files, signal) {
             // phase-major scans.
             durationMs: Date.now() - startedAt - astGrepDurationMs,
             stats,
+            // #1935 review: ast-grep's own cost is often a scan's most expensive
+            // phase (production evidence: 13168ms over 86 files, the single
+            // biggest contributor). Its duration is subtracted above so it stays
+            // comparable to the historical phase-major scans; carry it here too
+            // so it stays visible SOMEWHERE instead of disappearing when the
+            // vacuous `project_diagnostics_ast_grep_scan` cache_stats record
+            // (below) was removed.
+            astGrep: { durationMs: astGrepDurationMs, fileCount: astGrepFilesScanned },
         });
     });
-    await client.withParseCacheMeasurement(async () => { }, (stats) => {
-        logTreeSitterCacheStats({
-            scope: "project_diagnostics_ast_grep_scan",
-            filePath: cwd,
-            fileCount: astGrepFilesScanned,
-            durationMs: astGrepDurationMs,
-            stats,
-        });
-    });
+    // #1935: no `project_diagnostics_ast_grep_scan` cache_stats record here.
+    // `scanAstGrepFile` parses through ast-grep-napi's own `lang.parse()` — a
+    // separate native engine, not `TreeSitterClient`'s WASM `TreeCache` — so a
+    // cache_stats record for this scope would always read all-zero (0
+    // lookups, 0 hits, every counter 0) no matter how the scan behaves. That
+    // was a vacuous observability record, not a real one: it looked like a
+    // signal but could never carry information. `astGrepDurationMs` and
+    // `astGrepFilesScanned` still feed the `project_diagnostics_scan` record
+    // above (`astGrep` sub-field), so this cost stays observable without a
+    // second, always-zero record to carry it.
     return { treeSitter, factRules, astGrep, filesScanned, wasmAborted };
 }
 export async function scanProjectDiagnostics(options) {

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

@@ -36,6 +36,7 @@
 import * as path from "node:path";
 import { normalizeMapKey, toProjectRelativePath } from "./path-utils.js";
 import { loadProjectSnapshotWithoutWordIndex } from "./project-snapshot.js";
+import { formatReviewGraphRevisionDriftNote, } from "./review-graph/revision-drift.js";
 const DEFAULT_LIMIT = 10;
 const STALE_THRESHOLD_MS = 15 * 60_000; // 15 minutes
 const LOW_COVERAGE_THRESHOLD = 0.8;
@@ -113,7 +114,11 @@ function buildFileDegrees(graph) {
     return { fanIn, fanOut };
 }
 // --- section 1: trust header --------------------------------------------------
-function computeTrust(graph, cwd) {
+function computeTrust(graph, cwd, 
+// Passed in rather than looked up here: the builder is imported dynamically
+// by `projectReport` to keep the module graph acyclic, and the value must be
+// computed per render, never cached (#1961 review F3).
+drift) {
     const filesCovered = graph.fileNodes.size;
     const snapshot = loadProjectSnapshotWithoutWordIndex(cwd);
     const snapshotFileCount = snapshot ? Object.keys(snapshot.files).length : 0;
@@ -151,6 +156,11 @@ function computeTrust(graph, cwd) {
     const lowCoverage = coverage < LOW_COVERAGE_THRESHOLD ||
         graph.persistCoverage?.partial === true;
     const notes = [];
+    // #1961: the blind read now SERVES a snapshot stamped at a different HEAD
+    // rather than dropping it. Age alone would not catch a branch switch made
+    // minutes ago, so the revision difference gets its own note.
+    if (drift)
+        notes.push(formatReviewGraphRevisionDriftNote(drift));
     if (stale) {
         const ageMin = Math.round(ageMs / 60_000);
         notes.push(`Graph is stale: built ${ageMin}m ago. Sections below may miss recent edits — run pilens_rebuild or re-analyze to refresh.`);
@@ -184,6 +194,7 @@ function computeTrust(graph, cwd) {
             sampleSize,
         },
         stale,
+        ...(drift ? { revisionDrift: drift } : {}),
         lowCoverage,
         persistCoverage: graph.persistCoverage?.partial
             ? graph.persistCoverage
@@ -493,25 +504,23 @@ const inFlightGraphBuilds = new Set();
 export function _resetProjectReportBuildGuardForTests() {
     inFlightGraphBuilds.clear();
 }
-function triggerBackgroundGraphBuild(cwd) {
+function triggerBackgroundGraphBuild(cwd, deps) {
     const key = normalizeMapKey(path.resolve(cwd));
     if (inFlightGraphBuilds.has(key))
-        return false;
+        return "already_running";
+    // Ask the builder, not just this module's own guard: a build kicked off by
+    // the edit pipeline or another reader never touches `inFlightGraphBuilds`.
+    // The probe and the call are in ONE synchronous block on purpose — awaiting
+    // between them (the pre-#1962 dynamic imports did) reopens the race.
+    const deduped = deps.isGraphBuildInFlight(key, []);
     inFlightGraphBuilds.add(key);
-    void (async () => {
-        try {
-            const { buildOrUpdateGraph } = await import("./review-graph/builder.js");
-            const { FactStore } = await import("./dispatch/fact-store.js");
-            await buildOrUpdateGraph(key, [], new FactStore());
-        }
-        catch {
-            // buildOrUpdateGraph records the durable failure and surfaced status.
-        }
-        finally {
-            inFlightGraphBuilds.delete(key);
-        }
-    })();
-    return true;
+    const build = deps
+        .buildOrUpdateGraph(key, [], new deps.FactStore())
+        .catch(() => {
+        // buildOrUpdateGraph records the durable failure and surfaced status.
+    });
+    void build.finally(() => inFlightGraphBuilds.delete(key));
+    return deduped ? "already_running" : "started";
 }
 // --- entry point ---------------------------------------------------------------
 /**
@@ -523,7 +532,7 @@ export async function projectReport(cwd, options) {
     const limit = clampLimit(options?.limit);
     const focusTerms = normalizeFocus(options?.focus);
     const view = options?.view;
-    const { getCachedReviewGraph, getReviewGraphSizeSkipVerdict, getLastReviewGraphBuildAttempt, } = await import("./review-graph/builder.js");
+    const { getCachedReviewGraph, getReviewGraphSizeSkipVerdict, getLastReviewGraphBuildAttempt, buildOrUpdateGraph, isGraphBuildInFlight, getReviewGraphRevisionDrift, } = await import("./review-graph/builder.js");
     let graph;
     try {
         graph = getCachedReviewGraph(cwd);
@@ -556,22 +565,48 @@ export async function projectReport(cwd, options) {
             };
         }
         const previousAttempt = getLastReviewGraphBuildAttempt(cwd);
-        const kickedOff = triggerBackgroundGraphBuild(cwd);
-        const lastBuildAttempt = previousAttempt ?? getLastReviewGraphBuildAttempt(cwd);
+        const { FactStore } = await import("./dispatch/fact-store.js");
+        const trigger = triggerBackgroundGraphBuild(cwd, {
+            buildOrUpdateGraph,
+            isGraphBuildInFlight,
+            FactStore,
+        });
+        const started = trigger === "started";
+        // #1962: report the attempt that is CURRENT. When this call started a
+        // build, `buildOrUpdateGraph` has already recorded a fresh `running`
+        // attempt synchronously, and the previous outcome belongs in the hint
+        // text, not in a field labelled "last attempt". When no build started,
+        // the earlier attempt genuinely IS the current one.
+        const lastBuildAttempt = started
+            ? (getLastReviewGraphBuildAttempt(cwd) ?? previousAttempt)
+            : previousAttempt;
+        // A terminal previous outcome is the useful half of the message: it says
+        // WHY the graph is missing. It is prefixed to whichever verdict follows,
+        // rather than selecting between two parallel sentence pairs — the first
+        // version of this branch did that, and its terminal-plus-deduped arm was
+        // unreachable (#1962 review F1). A pending build always records a
+        // `running` attempt synchronously, so "terminal" and "not started" cannot
+        // both hold for the same key.
+        const terminal = previousAttempt?.outcome === "failed" ||
+            previousAttempt?.outcome === "skipped";
+        const cause = terminal
+            ? `Review graph unavailable: ${previousAttempt?.reason ?? previousAttempt?.outcome}. `
+            : "";
         return {
             available: false,
-            hint: lastBuildAttempt?.outcome === "failed" ||
-                lastBuildAttempt?.outcome === "skipped"
-                ? `Review graph unavailable: ${lastBuildAttempt.reason ?? lastBuildAttempt.outcome}. A retry was ${kickedOff ? "started" : "not started"}.`
-                : kickedOff
-                    ? "No review graph cached for this workspace yet — a build was kicked off in the background; retry this call shortly."
-                    : "No review graph cached for this workspace yet — the background build is still running; retry this call shortly.",
+            hint: started
+                ? terminal
+                    ? `${cause}A retry was started.`
+                    : "No review graph cached for this workspace yet — a build was kicked off in the background; retry this call shortly."
+                : `${cause}A build is already running for this workspace; retry this call shortly.`,
             ...(lastBuildAttempt ? { lastBuildAttempt } : {}),
             ...(view ? { view } : {}),
         };
     }
     const degrees = buildFileDegrees(graph);
-    const trust = computeTrust(graph, cwd);
+    // Computed on THIS render, from the workspace entry's stamped commit and the
+    // worktree's HEAD right now — never from a value cached beside the graph.
+    const trust = computeTrust(graph, cwd, getReviewGraphRevisionDrift(cwd));
     const hubs = await computeHubs(graph, degrees, cwd, limit, focusTerms);
     const { entryPoints, entryPointFiles } = computeEntryPoints(graph, degrees, cwd, limit, focusTerms);
     const subsystems = computeSubsystems(graph, cwd, limit);

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

@@ -112,7 +112,7 @@ export function createReadGuardEditBatchSummary(args) {
         durationMs: Math.max(0, Math.min(args.durationMs ?? 0, 86_400_000)),
     };
 }
-function shouldLogEvent(event) {
+export function shouldLogEvent(event) {
     if (VERBOSE_READ_GUARD_LOG)
         return true;
     if (event === "edit_allowed")
@@ -134,7 +134,12 @@ function shouldLogEvent(event) {
         event === "edit_post_edit_pipeline_failed" ||
         event === "edit_batch_summary" ||
         event === "edit_batch_summary_overflow" ||
-        event === "touched_lines_missing");
+        event === "touched_lines_missing" ||
+        // #1913: read-guard record-cap evictions are rare by construction (only
+        // 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");
 }
 const MAX_TELEMETRY_STRING = 512;
 const MAX_TELEMETRY_KEYS = 64;

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

@@ -10,6 +10,7 @@
  * 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 { normalizeEphemeralMapKey, normalizeFilePath } from "./path-utils.js";
@@ -48,29 +49,22 @@ const READ_GUARD_MAX_FILES = 256;
  * 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.
- */
+const NO_TRIM = {
+    evictedCount: 0,
+    evictedCreditCount: 0,
+    evictedGenuineCount: 0,
+};
 function enforceRecordCapForFile(records) {
     if (records.length <= READ_GUARD_MAX_RECORDS_PER_FILE)
-        return 0;
+        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)
+        if (records[i].searchCredit !== undefined) {
             evicted.add(i);
+            evictedCreditCount++;
+        }
     }
     for (let i = 0; i < records.length && evicted.size < excess; i++) {
         evicted.add(i);
@@ -79,7 +73,11 @@ function enforceRecordCapForFile(records) {
     records.length = 0;
     for (const record of kept)
         records.push(record);
-    return excess;
+    return {
+        evictedCount: excess,
+        evictedCreditCount,
+        evictedGenuineCount: excess - evictedCreditCount,
+    };
 }
 /**
  * #1904 class sweep: `this.edits` is the same shape as `this.reads` — a
@@ -285,6 +283,8 @@ export class ReadGuard {
     // 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 = {}) {
@@ -399,7 +399,7 @@ export class ReadGuard {
         // eviction starts, so it stops showing growth. `rawReadCountForFile` keeps
         // the real arrival count observable alongside `evictedRecordCount`.
         const rawReadCountForFile = arr.length;
-        const evictedRecordCount = enforceRecordCapForFile(arr);
+        const { evictedCount: evictedRecordCount, evictedCreditCount, evictedGenuineCount } = enforceRecordCapForFile(arr);
         this.touchFile(storedRecord.filePath);
         this.enforceFileCap();
         logReadGuardEvent({
@@ -434,6 +434,63 @@ export class ReadGuard {
                 }),
             },
         });
+        // #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);
     }
@@ -828,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