@herbertgao/pi-extensions 2026.8.13 → 2026.8.15

package/node_modules/pi-lens/dist/clients/dispatch/dispatcher.js

@@ -17,6 +17,7 @@ import { logExtension } from "../extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { recordRunner } from "../widget-state.js";
+import { incrementDegradationCount } from "../degradation-ledger.js";
 import { detectFileKind } from "../file-kinds.js";
 import { detectFileRole } from "../file-role.js";
 import { isTestFile } from "../file-utils.js";
@@ -24,19 +25,24 @@ import { getPrimaryDispatchGroup } from "../language-policy.js";
 import { resolveLanguageRootForFile } from "../language-profile.js";
 import { logLatency, phaseFinished, phaseStarted } from "../latency-logger.js";
 import { isSpawnableCommand } from "../installer/index.js";
-import { normalizeMapKey } from "../path-utils.js";
+import { normalizeEphemeralMapKey, normalizeMapKey } from "../path-utils.js";
 import { loadPiLensProjectConfig } from "../project-lens-config.js";
 import { RUNTIME_CONFIG, getRunnerTimeoutFloorMs } from "../runtime-config.js";
 import { safeSpawnAsync } from "../safe-spawn.js";
 import { classifyDiagnostic } from "./diagnostic-taxonomy.js";
 import { classifyProbeFailure, logAvailabilityDecision, startHostStallSampler, transientRetryDelayMs, } from "./runners/utils/availability-policy.js";
+import { recordAvailabilityProbeOverrun, getDispatchAvailabilityGeneration, } from "./runners/utils/runner-helpers.js";
+import { createAvailabilityProbeFlight } from "../availability-probe-flight.js";
 import { applyDispositions } from "../diagnostic-dispositions.js";
 import { applyInlineSuppressions } from "./inline-suppressions.js";
 import { getToolPlan } from "./plan.js";
 import { resolveRunnerPath } from "./runner-context.js";
+import { classifyObservedRunner, COLLECT_LATER_THRESHOLD_MS, observeRunnerLatency, } from "./collect-later-tier.js";
+import { deferRunnerFindings } from "./pending-runner-findings.js";
 import { applyRulePolicy, rulePolicyMapFromConfig } from "./rule-policy.js";
 import { getToolProfile } from "./tool-profile.js";
 import { isRunnerSkipReason } from "./types.js";
+const dispatcherProbeFlights = createAvailabilityProbeFlight({ generation: () => getDispatchAvailabilityGeneration() });
 import { formatDiagnostics } from "./utils/format-utils.js";
 // --- Runner Registry ---
 export class RunnerRegistry {
@@ -134,15 +140,19 @@ export async function checkToolAvailability(command, facts) {
         const startedAt = Date.now();
         let result;
         let hostStallMs;
+        let probeJoined = false;
         try {
-            result = await safeSpawnAsync(command, ["--version"], {
+            const shared = dispatcherProbeFlights.run(`dispatcher:${key}`, () => safeSpawnAsync(command, ["--version"], {
                 timeout: TOOL_PROBE_TIMEOUT_MS,
-            });
+            }));
+            probeJoined = shared.joined;
+            result = await shared.promise;
         }
         finally {
             hostStallMs = sampler.stop();
         }
         const elapsedMs = Date.now() - startedAt;
+        recordAvailabilityProbeOverrun(command, key, elapsedMs, TOOL_PROBE_TIMEOUT_MS, result.failure);
         if (result.status === 0) {
             facts.setSessionFact(key, true);
             // The tool answered: retire the cooldown facts rather than leaving a
@@ -156,6 +166,7 @@ export async function checkToolAvailability(command, facts) {
                 cause: "ok",
                 elapsedMs,
                 latched: true,
+                classifiedBy: probeJoined ? "joined" : "probe",
                 hostStallMs,
                 budgetMs: TOOL_PROBE_TIMEOUT_MS,
             });
@@ -188,7 +199,7 @@ export async function checkToolAvailability(command, facts) {
             hostStallMs,
             ...(retryAfterMs !== undefined && { retryAfterMs }),
             budgetMs: TOOL_PROBE_TIMEOUT_MS,
-            classifiedBy: "probe",
+            classifiedBy: probeJoined ? "joined" : "probe",
             evidence,
         });
         return false;
@@ -419,13 +430,19 @@ function buildCoverageNotice(ctx, runnerLatencies) {
         // The marker describes this exact silent-scanner set. A scanner can
         // recover while another goes dark on the same file, so the set belongs
         // in the session dedupe identity rather than only kind and path.
+        // #2016: these are SCANNER IDS, not filesystem paths. `normalizeMapKey`
+        // would realpath each one; on Windows that fails, falls through to
+        // `resolveNonExisting`, and resolves the id against the CURRENT process
+        // cwd, so the dedupe key differed by platform and by cwd (the #2219
+        // non-path-sentinel class). The cheap syntactic fold is what this
+        // session-scoped dedupe key actually needs.
         const silentScannerSet = [...new Set(unconfirmedServerIds)]
-            .map(normalizeMapKey)
+            .map(normalizeEphemeralMapKey)
             // Code-unit comparator: the sorted set is a dedupe KEY, so ordering
             // must be deterministic across locales — localeCompare is not.
             .sort((a, b) => Number(a > b) - Number(a < b))
             .join(",");
-        const onceKey = `${ctx.kind}:${normalizeMapKey(ctx.filePath)}:${silentScannerSet}`;
+        const onceKey = `${ctx.kind}:${ctx.filePath}:${silentScannerSet}`;
         if (coverageNoticeSeen.has(onceKey))
             return undefined;
         coverageNoticeSeen.add(onceKey);
@@ -467,7 +484,7 @@ function buildCoverageNotice(ctx, runnerLatencies) {
         (r.status === "succeeded" || r.status === "failed"));
     if (anyLinterHasCoverage)
         return undefined;
-    const onceKey = `${ctx.kind}:${normalizeMapKey(ctx.filePath)}`;
+    const onceKey = `${ctx.kind}:${ctx.filePath}`;
     if (coverageNoticeSeen.has(onceKey))
         return undefined;
     coverageNoticeSeen.add(onceKey);
@@ -603,10 +620,123 @@ async function runGroup(ctx, group, registry, onRunnerResult) {
             });
             continue;
         }
+        const projectRoot = ctx.projectRoot ?? ctx.cwd;
+        // Only post-write dispatches participate. Project scans and direct API
+        // callers must retain their existing synchronous semantics.
+        const observedTier = ctx.writeIndex === undefined
+            ? "inline"
+            : classifyObservedRunner(projectRoot, runner.id);
+        if (observedTier === "collect-later") {
+            const markedAtMs = Date.now();
+            const deferred = runRunner(ctx, runner, semantic).then((result) => {
+                const durationMs = Date.now() - markedAtMs;
+                const tier = observeRunnerLatency({
+                    projectRoot,
+                    runnerId: runner.id,
+                    durationMs,
+                    timedOut: result.failureKind === "timeout",
+                });
+                if (tier !== observedTier) {
+                    logLatency({
+                        type: "phase",
+                        filePath: ctx.filePath,
+                        phase: "runner_collect_later_tier_flip",
+                        durationMs: 0,
+                        metadata: {
+                            runnerId: runner.id,
+                            from: observedTier,
+                            to: tier,
+                            projectRoot,
+                        },
+                    });
+                }
+                if (tier === "collect-later") {
+                    incrementDegradationCount({
+                        kind: "runner-collect-later",
+                        subject: `${projectRoot}:${runner.id}`,
+                        reason: `observed ${durationMs}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`,
+                    });
+                }
+                logLatency({
+                    type: "runner",
+                    filePath: ctx.filePath,
+                    runnerId: runner.id,
+                    startedAt: new Date(markedAtMs).toISOString(),
+                    durationMs,
+                    status: result.status,
+                    diagnosticCount: result.diagnostics.length,
+                    semantic: result.semantic ?? semantic,
+                    metadata: { tier: "collect-later", delivered: "turn_end" },
+                });
+                return result;
+            });
+            deferRunnerFindings({
+                filePath: ctx.filePath,
+                cwd: ctx.cwd,
+                projectRoot,
+                runnerId: runner.id,
+                markedAtMs,
+                writeIndex: ctx.writeIndex,
+                promise: deferred,
+            });
+            // A deferred runner is still an observed runner. Keep it visible in
+            // both the edit latency report and the widget until its turn-end result
+            // replaces this pending state (#2122 F1).
+            latencies.push({
+                runnerId: runner.id,
+                startTime: runnerStart,
+                endTime: runnerStart,
+                durationMs: 0,
+                status: "pending",
+                diagnosticCount: 0,
+                semantic: semantic,
+            });
+            recordRunner(ctx.filePath, runner.id, "pending", 0, 0, ctx.writeIndex);
+            logLatency({
+                type: "runner",
+                filePath: ctx.filePath,
+                runnerId: runner.id,
+                durationMs: 0,
+                status: "pending",
+                diagnosticCount: 0,
+                semantic,
+                metadata: { tier: "collect-later", delivered: "turn_end" },
+            });
+            continue;
+        }
         const result = await runRunner(ctx, runner, semantic);
         onRunnerResult?.(runnerId, result);
         const runnerEnd = Date.now();
         const duration = runnerEnd - runnerStart;
+        const tier = ctx.writeIndex === undefined
+            ? "inline"
+            : observeRunnerLatency({
+                projectRoot,
+                runnerId: runner.id,
+                durationMs: duration,
+                timedOut: result.failureKind === "timeout",
+            });
+        if (tier !== observedTier) {
+            logLatency({
+                type: "phase",
+                filePath: ctx.filePath,
+                phase: "runner_collect_later_tier_flip",
+                durationMs: 0,
+                metadata: {
+                    runnerId: runner.id,
+                    from: observedTier,
+                    to: tier,
+                    projectRoot,
+                },
+            });
+        }
+        if (tier === "collect-later") {
+            incrementDegradationCount({
+                kind: "runner-collect-later",
+                subject: `${projectRoot}:${runner.id}`,
+                reason: `observed ${duration}ms, threshold ${COLLECT_LATER_THRESHOLD_MS}ms`,
+            });
+        }
         // Runner definitions are a typed API, but embedders/plugins can still
         // return untyped objects at runtime. Admit only the closed taxonomy and
         // only on actual skips so free text cannot enter durable latency metadata.
@@ -707,8 +837,13 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
     const groupResults = await Promise.all(groups.map((group) => runGroup(ctx, group, registry, onRunnerResult)));
     // Count baseline warnings before filtering (for delta count display)
     const relativeKey = path.relative(ctx.cwd, ctx.filePath).replace(/\\/g, "/");
-    const baselineAbsKey = `session.baseline.${normalizeMapKey(ctx.filePath)}`;
-    const baselineRelKey = `session.baseline.${normalizeMapKey(relativeKey)}`;
+    const baselineAbsKey = `session.baseline.${ctx.filePath}`;
+    // #2016: `relativeKey` is relative to `ctx.cwd`. `normalizeMapKey` resolved
+    // it against the process cwd instead, so on Windows this "relative" key
+    // became an absolute path anchored on the wrong root while POSIX left it
+    // relative. Both the read here and the write below use this const, so the
+    // key stays self-consistent within a session.
+    const baselineRelKey = `session.baseline.${normalizeEphemeralMapKey(relativeKey)}`;
     const previousBaseline = ctx.deltaMode
         ? (ctx.facts.getSessionFact(baselineAbsKey) ??
             ctx.facts.getSessionFact(baselineRelKey))
@@ -819,6 +954,12 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
         output += formatDiagnostics([coverageNotice], "warning", 1);
         warnings.push(coverageNotice);
     }
+    const pendingRunners = runnerLatencies
+        .filter((runner) => runner.status === "pending")
+        .map((runner) => runner.runnerId);
+    if (pendingRunners.length > 0) {
+        output += `\n⏳ Pending runners (reported at turn end): ${pendingRunners.join(", ")}\n`;
+    }
     // Generate and store latency report
     const overallEnd = Date.now();
     const latencyReport = {

package/node_modules/pi-lens/dist/clients/dispatch/fact-store.js

@@ -1,20 +1,73 @@
 import { normalizeMapKey } from "../path-utils.js";
+let capacityEvictionReporter;
+export function setFactStoreEvictionReporter(reporter) {
+    capacityEvictionReporter = reporter;
+}
+export function getFactStoreEvictionReporter() {
+    return capacityEvictionReporter;
+}
+// #2240: the dispatch store is module-scope in integration.ts, so it lives for
+// the whole process, and a review-graph project walk seeds facts for EVERY file
+// it visits. Nothing removed an entry except the next dispatch of that same
+// path, so a several-hundred-file batch retained one entry per distinct path
+// until the heap ran out. Bound the record count the way widget-state.ts bounds
+// its file records.
+const MAX_FILE_FACT_RECORDS = 1024;
+// Keep enough content for 1024 typical source files averaging 64 KiB, while
+// preventing a small number of generated or vendored files from retaining
+// hundreds of MiB for the process lifetime (#2247).
+const MAX_FILE_FACT_CONTENT_BYTES = 64 * 1024 * 1024;
 export class FactStore {
+    subject;
+    // Insertion order is eviction order: the oldest-used record is evicted first.
     fileFacts = new Map();
     sessionFacts = new Map();
+    // Pin refcount per file. A file is exempt from capacity eviction while its
+    // count is > 0. Refcounted, not a Set, so two overlapping dispatches of the
+    // same file both hold the pin until BOTH settle (#2243 item 2).
+    pinnedFiles = new Map();
+    // Running UTF-8 byte total for file.content only. Maintaining it at every
+    // mutation keeps getFileFact/setFileFact O(1) amortized; never scan the map
+    // to decide whether the byte budget is exceeded.
+    retainedContentBytes = 0;
+    // Subset of retainedContentBytes held by currently pinned files (#2247
+    // review F2). Maintained incrementally the same way — a scan over
+    // `pinnedFiles` looks small in isolation, but `evictColdFileFacts` calls it
+    // on EVERY unpinned insert for as long as pinned bytes stay over budget, so
+    // a scan there would re-walk a large pinned file's full string on every
+    // single write admitted during that window. Keeping a running total avoids
+    // reintroducing exactly the scan `retainedContentBytes` exists to avoid.
+    pinnedContentBytesTotal = 0;
+    /**
+     * @param subject Discriminates this store's capacity-eviction telemetry
+     *   from every other production FactStore's (#2243 review round 3, F1).
+     *   Production callers pass a label naming the store (e.g. `"dispatch"`,
+     *   `"runtime-session-call-graph"`); the default is only for call sites
+     *   that never wired a reporter and tests that don't care.
+     */
+    constructor(subject = "session-fact-store") {
+        this.subject = subject;
+    }
     // All file-keyed methods normalize the path internally via normalizeMapKey().
     // Callers always pass raw/resolved paths — normalization is not their concern.
     getFileFact(filePath, factId) {
-        return this.fileFacts.get(normalizeMapKey(filePath))?.get(factId);
+        return this.touchFileFacts(normalizeMapKey(filePath))?.get(factId);
     }
     setFileFact(filePath, factId, value) {
         const key = normalizeMapKey(filePath);
-        let facts = this.fileFacts.get(key);
+        let facts = this.touchFileFacts(key);
         if (!facts) {
             facts = new Map();
             this.fileFacts.set(key, facts);
         }
+        if (factId === "file.content") {
+            const delta = this.contentBytes(value) - this.contentBytes(facts.get(factId));
+            this.retainedContentBytes += delta;
+            if (this.pinnedFiles.has(key))
+                this.pinnedContentBytesTotal += delta;
+        }
         facts.set(factId, value);
+        this.evictColdFileFacts();
     }
     hasFileFact(filePath, factId) {
         return this.fileFacts.get(normalizeMapKey(filePath))?.has(factId) ?? false;
@@ -26,20 +79,186 @@ export class FactStore {
         const facts = this.fileFacts.get(key);
         if (!facts)
             return;
+        if (factId === "file.content") {
+            const dropped = this.contentBytes(facts.get(factId));
+            this.retainedContentBytes -= dropped;
+            if (this.pinnedFiles.has(key))
+                this.pinnedContentBytesTotal -= dropped;
+        }
         facts.delete(factId);
         if (facts.size === 0)
             this.fileFacts.delete(key);
     }
-    /** Clear facts for one specific file only. Use at the start of each per-file dispatch call.
+    /** Clear facts for one specific file only, and mark the file's dispatch as
+     *  begun. Use at the start of each per-file dispatch call.
      *  Preserves facts for other files computed in the same turn.
-     *  Normalizes filePath internally — callers pass raw paths. */
+     *  Normalizes filePath internally — callers pass raw paths.
+     *  Pins the file against capacity eviction until the matching
+     *  {@link endDispatchFor} runs in the dispatch's settle path (#2243 item 2).
+     *  Every `clearFileFactsFor` MUST be paired with an `endDispatchFor`. */
     clearFileFactsFor(filePath) {
-        this.fileFacts.delete(normalizeMapKey(filePath));
+        const key = normalizeMapKey(filePath);
+        this.deleteFileFactsRecord(key);
+        this.pinFile(key);
     }
-    /** Clear all file facts across all paths. Reserve for explicit full resets only —
-     *  do NOT use in the normal per-file dispatch path. */
-    clearFileFacts() {
-        this.fileFacts.clear();
+    /** Pin a file against capacity eviction for the duration of a dispatch,
+     *  WITHOUT clearing its existing facts. Pairs with {@link endDispatchFor}
+     *  exactly like {@link clearFileFactsFor} does.
+     *
+     *  #2243 review round 3 (F5): `clearFileFactsFor`'s clear+re-derive is
+     *  right for a dispatch driven by a fresh edit, but the debounced
+     *  ast-grep warning scan runs ~2s AFTER the inline dispatch for that same
+     *  edit already re-derived every fact for this exact file — a second
+     *  clear there bought nothing but ~51ms of redundant re-parsing across
+     *  all five providers (measured; a warm-cache read is ~1ms). Use this
+     *  where the facts are very likely already fresh: `runProviders` still
+     *  re-derives any fact this file is missing (a genuine miss, e.g. the
+     *  fact was evicted meanwhile), so a read never depends on staleness. */
+    beginDispatchFor(filePath) {
+        this.pinFile(normalizeMapKey(filePath));
+    }
+    /** Release the pin a {@link clearFileFactsFor} or {@link beginDispatchFor}
+     *  took for one file's dispatch. Call once per matching call, from the
+     *  dispatch's finally/settle path, so the pin set tracks dispatches
+     *  actually in flight rather than the last N files touched (#2243 item 2). */
+    endDispatchFor(filePath) {
+        this.unpinFile(normalizeMapKey(filePath));
+        this.evictColdFileFacts();
+    }
+    /** Clear one file's facts WITHOUT pinning. For sequential single-store scans
+     *  (project-diagnostics) that own their store and race no concurrent walk:
+     *  pinning there would exempt every scanned file from the capacity cap and
+     *  defeat it. Normalizes filePath internally. */
+    dropFileFacts(filePath) {
+        this.deleteFileFactsRecord(normalizeMapKey(filePath));
+    }
+    /** LRU touch: re-inserting an existing record moves it to the end of the
+     *  eviction order, so a record still in use is not the next victim. */
+    touchFileFacts(key) {
+        const facts = this.fileFacts.get(key);
+        if (!facts)
+            return undefined;
+        this.fileFacts.delete(key);
+        this.fileFacts.set(key, facts);
+        return facts;
+    }
+    pinFile(key) {
+        const count = this.pinnedFiles.get(key) ?? 0;
+        // Transition from unpinned to pinned: this file's content joins the
+        // pinned subset. A refcount bump past 1 (an already-pinned file, two
+        // overlapping dispatches) does not — it is already counted.
+        if (count === 0) {
+            this.pinnedContentBytesTotal += this.contentBytes(this.fileFacts.get(key)?.get("file.content"));
+        }
+        this.pinnedFiles.set(key, count + 1);
+    }
+    unpinFile(key) {
+        const count = this.pinnedFiles.get(key);
+        if (count === undefined)
+            return;
+        if (count <= 1) {
+            this.pinnedFiles.delete(key);
+            // Transition from pinned to unpinned: this file's content leaves the
+            // pinned subset.
+            this.pinnedContentBytesTotal -= this.contentBytes(this.fileFacts.get(key)?.get("file.content"));
+        }
+        else {
+            this.pinnedFiles.set(key, count - 1);
+        }
+    }
+    /** Drop least-recently-used records past either cap, skipping the files whose
+     *  dispatch pinned them. Pinned content counts toward the byte total, but is
+     *  never evicted before endDispatchFor. Pins survive until clearAll.
+     *
+     *  #2247 review F2: a leaked (or several overlapping) pin(s) can put pinned
+     *  bytes over budget ON THEIR OWN. Evicting every unpinned record can never
+     *  bring the total back under budget in that state — before this guard, the
+     *  loop below evicted each newly inserted unpinned record on the very next
+     *  call (it was always the sole remaining unpinned key), so unpinned writes
+     *  never retained anything: a silent, permanent collapse for the rest of
+     *  the process. Once byte pressure is unpinned-bytes-driven-only, stop
+     *  evicting and admit unpinned inserts as-is — best-effort under pin
+     *  pressure — and record the state distinctly so it is visible instead of
+     *  inferred from "the store stopped retaining anything". */
+    evictColdFileFacts() {
+        if (!this.overCapacity())
+            return;
+        for (const key of this.fileFacts.keys()) {
+            if (this.pinnedFiles.has(key))
+                continue;
+            const axis = this.capacityAxis();
+            if (axis === "bytes" &&
+                this.pinnedContentBytesTotal > MAX_FILE_FACT_CONTENT_BYTES) {
+                this.reportPinnedOverBudget();
+                return;
+            }
+            this.deleteFileFactsRecord(key);
+            this.reportCapacityEviction(key, axis);
+            if (!this.overCapacity())
+                return;
+        }
+    }
+    overCapacity() {
+        return (this.fileFacts.size > MAX_FILE_FACT_RECORDS ||
+            this.retainedContentBytes > MAX_FILE_FACT_CONTENT_BYTES);
+    }
+    capacityAxis() {
+        return this.fileFacts.size > MAX_FILE_FACT_RECORDS ? "count" : "bytes";
+    }
+    contentBytes(value) {
+        return typeof value === "string" ? Buffer.byteLength(value, "utf8") : 0;
+    }
+    deleteFileFactsRecord(key) {
+        const facts = this.fileFacts.get(key);
+        if (!facts)
+            return;
+        const dropped = this.contentBytes(facts.get("file.content"));
+        this.retainedContentBytes -= dropped;
+        if (this.pinnedFiles.has(key))
+            this.pinnedContentBytesTotal -= dropped;
+        this.fileFacts.delete(key);
+    }
+    // #2243 item 4: the cap silently drops a fact a live dispatch may read back
+    // as "" (dispatcher.ts reads `file.content` with `?? ""`). Emit through the
+    // injected reporter so the drop is visible in the ledger instead of being
+    // inferred from a downstream symptom. integration.ts routes this to
+    // `recordDegradationOnce` keyed on THIS store's `subject` (#2243 review
+    // round 3, F1), so the ledger's own per-kind+subject dedupe yields exactly
+    // ONE record per session PER STORE (re-arming at session_start when the
+    // ledger resets) — no latch or generation compare here, so fact-store
+    // keeps no session-scoped state to forget to re-arm.
+    reportCapacityEviction(evictedKey, axis) {
+        capacityEvictionReporter?.(this.subject, axis, axis === "count"
+            ? `file-fact store axis=count exceeded ${MAX_FILE_FACT_RECORDS} records; evicted least-recently-used fact for ${evictedKey}`
+            : `file-fact store axis=bytes exceeded ${MAX_FILE_FACT_CONTENT_BYTES} retained content bytes; evicted least-recently-used fact for ${evictedKey}`);
+    }
+    // #2247 review F2: pinned bytes alone exceeding budget is not an eviction —
+    // nothing is dropped — so it is reported through a distinct axis rather
+    // than reusing `reportCapacityEviction`'s "evicted least-recently-used
+    // fact for X" language, which would misdescribe what happened.
+    reportPinnedOverBudget() {
+        const pinnedBytes = this.pinnedContentBytesTotal;
+        capacityEvictionReporter?.(this.subject, "pinned-over-budget", `file-fact store pinned content bytes (${pinnedBytes}) exceed the ` +
+            `${MAX_FILE_FACT_CONTENT_BYTES}-byte budget; unpinned inserts are ` +
+            `admitted without eviction until a pin releases`);
+    }
+    /** Running UTF-8 byte total for retained `file.content` values. Exposed so
+     *  tests can crosscheck it against a fresh sum over retained records
+     *  (#2247 review F3) — the running total is maintained incrementally on
+     *  every insert/delete path rather than recomputed, so a subtraction
+     *  dropped from one of those paths would otherwise drift silently. */
+    getRetainedContentBytes() {
+        return this.retainedContentBytes;
+    }
+    /** Running UTF-8 byte total for the pinned SUBSET of retained
+     *  `file.content` values. Exposed so tests can crosscheck it against a
+     *  fresh sum over `pinnedFiles ∩ fileFacts` (#2247 review F4) — like
+     *  `retainedContentBytes`, it is maintained incrementally on the pin
+     *  0→1 transition, the unpin 1→0 transition, content overwrite/delete,
+     *  and `clearAll`, so a drop from any one of those paths would
+     *  otherwise drift silently instead of failing loudly. */
+    getPinnedContentBytes() {
+        return this.pinnedContentBytesTotal;
     }
     getSessionFact(factId) {
         return this.sessionFacts.get(factId);
@@ -54,5 +273,8 @@ export class FactStore {
     clearAll() {
         this.fileFacts.clear();
         this.sessionFacts.clear();
+        this.pinnedFiles.clear();
+        this.retainedContentBytes = 0;
+        this.pinnedContentBytesTotal = 0;
     }
 }