@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

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

@@ -57,6 +57,8 @@
  * patterns apply to files inside that package, in addition to (and with
  * higher precedence than) the root config's `ignore` patterns.
  */
+import { logExtension } from "./extension-log.js";
+import { notifyUserDegradation } from "./user-notify.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -107,11 +109,17 @@ export function loadPiLensProjectConfig(startDir, preloadedInfo = findPiLensProj
     if (!configInfo)
         return EMPTY_PROJECT_CONFIG;
     const cached = configCache.get(configInfo.path);
-    if (cached && cached.mtimeMs === configInfo.mtimeMs) {
+    if (cached &&
+        cached.mtimeMs === configInfo.mtimeMs &&
+        cached.size === configInfo.size) {
         return cached.config;
     }
     const config = parseConfigFile(configInfo.path);
-    configCache.set(configInfo.path, { mtimeMs: configInfo.mtimeMs, config });
+    configCache.set(configInfo.path, {
+        mtimeMs: configInfo.mtimeMs,
+        size: configInfo.size,
+        config,
+    });
     return config;
 }
 /** For tests + callers that need to force a re-read (e.g. config-watcher hooks). */
@@ -137,7 +145,12 @@ export function findPiLensConfigInDir(dir) {
     const marker = findPiLensConfigMarkerInDir(dir);
     if (!marker)
         return undefined;
-    return { path: marker.path, dir: marker.dir, mtimeMs: marker.mtimeMs };
+    return {
+        path: marker.path,
+        dir: marker.dir,
+        mtimeMs: marker.mtimeMs,
+        size: marker.size,
+    };
 }
 /**
  * Find the closest config, between an edited file and the project root, that
@@ -174,11 +187,11 @@ export function loadPiLensConfigInDir(dir) {
     if (!info)
         return EMPTY_PROJECT_CONFIG;
     const cached = configCache.get(info.path);
-    if (cached && cached.mtimeMs === info.mtimeMs) {
+    if (cached && cached.mtimeMs === info.mtimeMs && cached.size === info.size) {
         return cached.config;
     }
     const config = parseConfigFile(info.path);
-    configCache.set(info.path, { mtimeMs: info.mtimeMs, config });
+    configCache.set(info.path, { mtimeMs: info.mtimeMs, size: info.size, config });
     return config;
 }
 export function findPiLensProjectConfig(startDir) {
@@ -189,7 +202,7 @@ export function findPiLensProjectConfig(startDir) {
             return undefined;
         const stat = safeFileStat(cached.info.path);
         if (stat?.isFile())
-            return { ...cached.info, mtimeMs: stat.mtimeMs };
+            return { ...cached.info, mtimeMs: stat.mtimeMs, size: stat.size };
     }
     const discovered = discoverPiLensProjectConfig(cacheKey);
     discoveryCache.set(cacheKey, discovered);
@@ -223,7 +236,7 @@ function discoverPiLensProjectConfig(startDir) {
             const stat = safeFileStat(candidate);
             if (stat?.isFile()) {
                 return {
-                    info: { path: candidate, dir, mtimeMs: stat.mtimeMs },
+                    info: { path: candidate, dir, mtimeMs: stat.mtimeMs, size: stat.size },
                     dirMtimes,
                 };
             }
@@ -236,7 +249,41 @@ function warnInvalidConfigOnce(configPath, reason) {
     if (warnedInvalidConfigs.has(key))
         return;
     warnedInvalidConfigs.add(key);
-    console.error(`[pi-lens] ignoring invalid project config ${configPath}: ${reason}`);
+    const message = `ignoring invalid project config ${configPath}: ${reason}`;
+    logExtension({
+        subsystem: "project-lens-config",
+        level: "warn",
+        message,
+        metadata: { configPath, reason },
+    });
+    // HUMAN-audience too: the user's own `.pi-lens.json` is being ignored.
+    notifyUserDegradation(`pi-lens: ${message}`);
+}
+function parseRulePolicyList(configPath, ruleId, key, value) {
+    if (!Array.isArray(value)) {
+        warnInvalidConfigOnce(configPath, `rules.${ruleId}.${key} must be an array of strings`);
+        return { list: [], invalid: true };
+    }
+    const list = [];
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            continue;
+        const trimmed = entry.trim();
+        if (trimmed.length > 0)
+            list.push(trimmed);
+    }
+    if (list.length === 0) {
+        // #1087: an explicitly empty array (`"disable": []`) is a well-formed
+        // no-op, not an error — don't warn. Only warn when the array HAD entries
+        // but none were usable strings (all blank / non-string), which is a real
+        // authoring mistake that must not fail silently.
+        if (value.length > 0) {
+            warnInvalidConfigOnce(configPath, `rules.${ruleId}.${key} must contain at least one non-empty string`);
+            return { list: [], invalid: true };
+        }
+        return { list: [], invalid: false };
+    }
+    return { list, invalid: false };
 }
 function parseConfigFile(configPath) {
     let raw;
@@ -264,18 +311,48 @@ function parseConfigFile(configPath) {
     if (obj.rules && typeof obj.rules === "object" && !Array.isArray(obj.rules)) {
         const rawRules = obj.rules;
         for (const [ruleId, ruleCfg] of Object.entries(rawRules)) {
+            // #444's own example writes the lists directly under `rules` (`rules.
+            // disable`), which lands here as an array and would otherwise be
+            // dropped without a word — the one shape a user is most likely to try.
             if (!ruleCfg || typeof ruleCfg !== "object" || Array.isArray(ruleCfg)) {
+                warnInvalidConfigOnce(configPath, `rules.${ruleId} must be an object with threshold, disable, or select; ignored`);
                 continue;
             }
             const r = ruleCfg;
+            const entry = {};
             if (typeof r.threshold === "number" &&
                 Number.isFinite(r.threshold) &&
                 r.threshold > 0) {
-                rules[ruleId] = { threshold: r.threshold };
+                entry.threshold = r.threshold;
             }
             else if ("threshold" in r) {
                 warnInvalidConfigOnce(configPath, `rules.${ruleId}.threshold must be a positive finite number`);
             }
+            if ("disable" in r) {
+                const parsed = parseRulePolicyList(configPath, ruleId, "disable", r.disable);
+                // #1087: an explicitly empty list is valid-but-empty (no warning);
+                // don't store a pointless no-op entry for it.
+                if (!parsed.invalid && parsed.list.length > 0)
+                    entry.disable = parsed.list;
+            }
+            if ("select" in r) {
+                const parsed = parseRulePolicyList(configPath, ruleId, "select", r.select);
+                if (!parsed.invalid && parsed.list.length > 0)
+                    entry.select = parsed.list;
+            }
+            // Honor both threshold-only and policy-only entries; only drop if
+            // the entry had no recognized fields at all (e.g. { unrelated: true }).
+            // A recognized-but-malformed field already warned above, so only warn
+            // here when nothing recognized was spelled at all — #444 proposed
+            // `only` rather than `select`, and that typo must not fail silent.
+            if (entry.threshold !== undefined || entry.disable || entry.select) {
+                rules[ruleId] = entry;
+            }
+            else if (!("threshold" in r) &&
+                !("disable" in r) &&
+                !("select" in r)) {
+                warnInvalidConfigOnce(configPath, `rules.${ruleId} has no recognized setting (threshold, disable, select); ignored`);
+            }
         }
     }
     let maxProjectFiles;

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

@@ -34,8 +34,8 @@
  * into symbol-node metadata so this path can read it for free.
  */
 import * as path from "node:path";
-import { normalizeMapKey } from "./path-utils.js";
-import { loadProjectSnapshot } from "./project-snapshot.js";
+import { normalizeMapKey, toProjectRelativePath } from "./path-utils.js";
+import { loadProjectSnapshotWithoutWordIndex } from "./project-snapshot.js";
 const DEFAULT_LIMIT = 10;
 const STALE_THRESHOLD_MS = 15 * 60_000; // 15 minutes
 const LOW_COVERAGE_THRESHOLD = 0.8;
@@ -47,14 +47,19 @@ function clampLimit(limit) {
 }
 // Same display-path convention as module-report.ts's toDisplayPath: cwd-relative
 // + forward-slashed under the project root, else the absolute (slash-normalized)
-// path.
+// path. Delegates to the shape-aware toProjectRelativePath (#1163/#1194) instead
+// of hand-rolling with host-default path.isAbsolute/path.relative, which
+// mis-parses a Windows-shaped path (e.g. a persisted graph symbol-key path) on
+// Linux CI: path.isAbsolute("C:\\repo\\x.ts") is false there, short-circuiting
+// to the raw absolute path instead of relativizing (#1024 divergence class).
 function toDisplayPath(p, projectRoot) {
-    if (!path.isAbsolute(p))
-        return p.replace(/\\/g, "/");
-    const rel = path.relative(projectRoot, p);
-    return rel && !rel.startsWith("..")
-        ? rel.replace(/\\/g, "/")
-        : p.replace(/\\/g, "/");
+    return toProjectRelativePath(p, projectRoot);
+}
+/** Test-only export (refs #1194) so the shape-aware delegation can be verified
+ * directly without standing up a full review graph — mirrors the
+ * `_reset*ForTests` underscore convention used elsewhere in this file. */
+export function _toDisplayPathForTests(p, projectRoot) {
+    return toDisplayPath(p, projectRoot);
 }
 function suggestedNext(displayPath) {
     return { tool: "module_report", path: displayPath };
@@ -110,9 +115,10 @@ function buildFileDegrees(graph) {
 // --- section 1: trust header --------------------------------------------------
 function computeTrust(graph, cwd) {
     const filesCovered = graph.fileNodes.size;
-    const snapshot = loadProjectSnapshot(cwd);
+    const snapshot = loadProjectSnapshotWithoutWordIndex(cwd);
     const snapshotFileCount = snapshot ? Object.keys(snapshot.files).length : 0;
-    const filesTotal = Math.max(filesCovered, snapshotFileCount);
+    const persistedTotal = graph.persistCoverage?.totalFiles ?? 0;
+    const filesTotal = Math.max(filesCovered, snapshotFileCount, persistedTotal);
     const coverage = filesTotal > 0 ? filesCovered / filesTotal : 1;
     let exact = 0;
     let imp = 0;
@@ -142,7 +148,8 @@ function computeTrust(graph, cwd) {
     const frac = (n) => (sampleSize > 0 ? n / sampleSize : 0);
     const ageMs = Date.now() - Date.parse(graph.builtAt);
     const stale = Number.isFinite(ageMs) && ageMs > STALE_THRESHOLD_MS;
-    const lowCoverage = coverage < LOW_COVERAGE_THRESHOLD || graph.persistCoverage?.partial === true;
+    const lowCoverage = coverage < LOW_COVERAGE_THRESHOLD ||
+        graph.persistCoverage?.partial === true;
     const notes = [];
     if (stale) {
         const ageMin = Math.round(ageMs / 60_000);
@@ -151,7 +158,14 @@ function computeTrust(graph, cwd) {
     if (lowCoverage) {
         if (graph.persistCoverage?.partial) {
             const p = graph.persistCoverage;
-            notes.push(`Partial persisted graph: ${p.persistedNodes}/${p.totalNodes} nodes and ${p.persistedEdges}/${p.totalEdges} edges were retained under the ${p.cap}-element cap — whole subsystems may be invisible below.`);
+            const totalFiles = p.totalFiles ?? filesCovered;
+            const persistedFiles = p.persistedFiles ?? filesCovered;
+            if (p.sourceFilesTruncated) {
+                notes.push(`Partial source walk: at least ${totalFiles} source files were represented before the visited-entry budget stopped enumeration; ${persistedFiles} files are in this graph.`);
+            }
+            else {
+                notes.push(`Partial persisted graph: ${p.persistedNodes}/${p.totalNodes} nodes, ${p.persistedEdges}/${p.totalEdges} edges, and ${persistedFiles}/${totalFiles} files were retained under the ${p.cap}-element cap — whole subsystems may be invisible below.`);
+            }
         }
         else {
             notes.push(`Low coverage: only ${filesCovered}/${filesTotal} project files (${Math.round(coverage * 100)}%) are in the graph — whole subsystems may be invisible below.`);

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

@@ -127,6 +127,12 @@ const SNAPSHOT_PARSE_CACHE_MAX = 4;
 // against the UNCOMPRESSED body size, never the (much smaller) gz file size.
 const SNAPSHOT_PARSE_CACHE_MAX_BYTES = 24 * 1024 * 1024;
 const snapshotParseCache = new Map();
+function withoutWordIndex(snapshot) {
+    if (!snapshot?.wordIndex)
+        return snapshot;
+    const { wordIndex: _releasedPostings, ...stripped } = snapshot;
+    return stripped;
+}
 function cacheParsedSnapshot(snapshotPath, entry) {
     // Refresh recency (Map preserves insertion order).
     snapshotParseCache.delete(snapshotPath);
@@ -139,11 +145,64 @@ function cacheParsedSnapshot(snapshotPath, entry) {
     }
 }
 const authoritativeSnapshots = new Map();
+const PROJECT_SNAPSHOT_MAX_WARM_ROOTS = 8;
+const PROJECT_SNAPSHOT_IDLE_EVICT_MS_DEFAULT = 20 * 60_000;
+function projectSnapshotIdleEvictMs() {
+    const value = Number.parseInt(process.env.PI_LENS_PROJECT_SNAPSHOT_IDLE_EVICT_MS ?? "", 10);
+    return Number.isSafeInteger(value) && value > 0 ? value : PROJECT_SNAPSHOT_IDLE_EVICT_MS_DEFAULT;
+}
+function clearAuthoritativeSnapshotTimer(entry) {
+    if (entry.idleTimer)
+        clearTimeout(entry.idleTimer);
+    entry.idleTimer = undefined;
+}
+function deleteAuthoritativeSnapshot(key) {
+    const entry = authoritativeSnapshots.get(key);
+    if (entry)
+        clearAuthoritativeSnapshotTimer(entry);
+    authoritativeSnapshots.delete(key);
+}
+function scheduleAuthoritativeSnapshotEviction(key, entry) {
+    clearAuthoritativeSnapshotTimer(entry);
+    const generation = entry.lastUsedAt;
+    entry.idleTimer = setTimeout(() => {
+        entry.idleTimer = undefined;
+        if (authoritativeSnapshots.get(key) !== entry || entry.lastUsedAt !== generation)
+            return;
+        deleteAuthoritativeSnapshot(key);
+    }, projectSnapshotIdleEvictMs());
+    entry.idleTimer.unref?.();
+}
+function touchAuthoritativeSnapshot(key, entry) {
+    entry.lastUsedAt = Date.now();
+    scheduleAuthoritativeSnapshotEviction(key, entry);
+}
+function enforceAuthoritativeSnapshotCap() {
+    while (authoritativeSnapshots.size > PROJECT_SNAPSHOT_MAX_WARM_ROOTS) {
+        const victim = [...authoritativeSnapshots.entries()].sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)[0];
+        if (!victim)
+            return;
+        clearAuthoritativeSnapshotTimer(victim[1]);
+        deleteAuthoritativeSnapshot(victim[0]);
+    }
+}
+/** Test-only cache keys, in LRU order from oldest to newest. */
+export function _getAuthoritativeSnapshotCacheKeysForTests() {
+    return [...authoritativeSnapshots.entries()]
+        .sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)
+        .map(([key]) => key);
+}
 /** Test hook: drop all cached parses + authoritative writes (per-worker isolation). */
 export function _resetProjectSnapshotParseCacheForTests() {
     snapshotParseCache.clear();
+    for (const entry of authoritativeSnapshots.values())
+        clearAuthoritativeSnapshotTimer(entry);
     authoritativeSnapshots.clear();
 }
+/** Test hook: prove the parse-cache tier never owns serialized postings. */
+export function _projectSnapshotParseCacheRetainsWordIndexForTests() {
+    return [...snapshotParseCache.values()].some((entry) => entry.snapshot?.wordIndex !== undefined);
+}
 /** Resolve which body file is currently on disk: gz canonical, else legacy. */
 function resolveSnapshotBodyPath(cwd) {
     const gzPath = getProjectSnapshotPath(cwd);
@@ -219,7 +278,7 @@ function readSnapshotBody(bodyPath, gz) {
         return { snapshot: null, rawBytes: 0 };
     }
 }
-export function loadProjectSnapshot(cwd) {
+function loadProjectSnapshotInternal(cwd, requireWordIndex) {
     const key = normalizeMapKey(cwd);
     const body = resolveSnapshotBodyPath(cwd);
     // Authoritative in-process write wins while our own (possibly still
@@ -230,11 +289,12 @@ export function loadProjectSnapshot(cwd) {
     if (authoritative) {
         const diskMtime = body ? body.mtimeMs : Number.NEGATIVE_INFINITY;
         if (diskMtime <= authoritative.knownMtime) {
+            touchAuthoritativeSnapshot(key, authoritative);
             return authoritative.snapshot;
         }
         // An external writer moved past our write — honor disk and stop
         // serving the now-stale in-memory object.
-        authoritativeSnapshots.delete(key);
+        deleteAuthoritativeSnapshot(key);
     }
     if (!body) {
         snapshotParseCache.delete(getProjectSnapshotPath(cwd));
@@ -246,14 +306,21 @@ export function loadProjectSnapshot(cwd) {
     // SnapshotParseCacheEntry for why: coarse FAT/exFAT mtime resolution can
     // otherwise alias a just-rewritten file onto a stale cache entry).
     if (cached && cached.mtimeMs === body.mtimeMs && cached.size === body.size) {
-        return cached.snapshot;
+        if (!requireWordIndex || !cached.snapshot || cached.snapshot.wordIndex) {
+            return cached.snapshot;
+        }
     }
     const { snapshot, rawBytes } = readSnapshotBody(body.path, body.gz);
-    if (rawBytes > 0 && rawBytes <= SNAPSHOT_PARSE_CACHE_MAX_BYTES) {
+    // Serialized postings expand into a much larger object graph. Cache only a
+    // shallow postings-stripped body: metadata/report consumers stay warm while
+    // the live warm WordIndex remains the sole retained postings graph (#1370).
+    const cacheSnapshot = withoutWordIndex(snapshot);
+    if (rawBytes > 0 &&
+        (rawBytes <= SNAPSHOT_PARSE_CACHE_MAX_BYTES || snapshot?.wordIndex)) {
         cacheParsedSnapshot(cacheKey, {
             mtimeMs: body.mtimeMs,
             size: body.size,
-            snapshot,
+            snapshot: cacheSnapshot,
         });
     }
     else {
@@ -261,11 +328,24 @@ export function loadProjectSnapshot(cwd) {
     }
     return snapshot;
 }
+/** Load the canonical body, including serialized postings when present. */
+export function loadProjectSnapshot(cwd) {
+    return loadProjectSnapshotInternal(cwd, true);
+}
+/**
+ * Load snapshot metadata without retaining or re-reading serialized postings.
+ * After publication this is served by the postings-stripped parse cache.
+ */
+export function loadProjectSnapshotWithoutWordIndex(cwd) {
+    return loadProjectSnapshotInternal(cwd, false);
+}
 const _snapshotGenerations = new Map();
 const _snapshotWorkerRequests = new Map();
 let _snapshotPersistWorker;
 let _snapshotWorkerRequestId = 0;
 let _snapshotWorkerDisabled = false;
+let _snapshotGenerationGateEnabledForTests = true;
+let _snapshotPromotionSeamForTests;
 let _lastSnapshotPersistErrorForTests;
 function snapshotWorkerEnabled() {
     // The synchronous fallback writer is a legitimate degraded mode (hosts that
@@ -281,7 +361,7 @@ function recordSnapshotPersistFailure(cwd, error) {
     // seq), and dropping the authoritative entry means the next load reflects
     // what is ACTUALLY on disk rather than the object we failed to persist.
     _lastSnapshotPersistErrorForTests = error;
-    authoritativeSnapshots.delete(normalizeMapKey(cwd));
+    deleteAuthoritativeSnapshot(normalizeMapKey(cwd));
     logLatency({
         type: "phase",
         phase: "project_snapshot_persist_failed",
@@ -289,7 +369,8 @@ function recordSnapshotPersistFailure(cwd, error) {
         durationMs: 0,
         metadata: { error },
     });
-    console.error("[project-snapshot] body persist failed:", error);
+    // #1333: the logLatency call above already carries this failure to
+    // latency.log — the console.error was a duplicate RAW write into pi's frame.
 }
 function logSnapshotPersistSuccess(pending, stats) {
     logLatency({
@@ -312,6 +393,33 @@ function reconcileAuthoritativeAfterWrite(pending, rawBytes) {
     // a superseding save already replaced it with a newer object.
     if (!entry || entry.snapshot !== pending.snapshot)
         return;
+    // The worker needs the serialized snapshot until promotion completes, but
+    // retaining it afterward duplicates the mutable warm index's postings. A
+    // shared reference is unsafe: ProjectSnapshot stores serialized arrays while
+    // WordIndex owns mutable Map/PathKeyedMap state. Drop the authoritative copy
+    // after publication; later merge-writers rehydrate the canonical disk body.
+    if (pending.snapshot.wordIndex) {
+        try {
+            const stat = fs.statSync(pending.gzPath);
+            cacheParsedSnapshot(pending.gzPath, {
+                mtimeMs: stat.mtimeMs,
+                size: stat.size,
+                snapshot: withoutWordIndex(pending.snapshot),
+            });
+        }
+        catch {
+            // A cache miss is safe: the first metadata consumer reconstructs it.
+        }
+        deleteAuthoritativeSnapshot(pending.key);
+        logLatency({
+            type: "phase",
+            phase: "project_snapshot_word_index_released",
+            filePath: pending.gzPath,
+            durationMs: 0,
+            metadata: { rawBytes },
+        });
+        return;
+    }
     if (rawBytes > SNAPSHOT_PARSE_CACHE_MAX_BYTES) {
         // Benign but invisible otherwise: the next load will re-parse this body
         // from disk instead of serving the in-process object.
@@ -322,7 +430,7 @@ function reconcileAuthoritativeAfterWrite(pending, rawBytes) {
             durationMs: 0,
             metadata: { rawBytes, maxBytes: SNAPSHOT_PARSE_CACHE_MAX_BYTES },
         });
-        authoritativeSnapshots.delete(pending.key);
+        deleteAuthoritativeSnapshot(pending.key);
         return;
     }
     try {
@@ -378,6 +486,19 @@ function writeSnapshotBodyOnMainThread(pending, reason) {
         recordSnapshotPersistFailure(pending.cwd, err instanceof Error ? err.message : String(err));
     }
 }
+/**
+ * The ForTests promotion seam covers worker-message and every main-thread
+ * fallback promotion. It stays sync and seam-free in production, identical to
+ * calling the writer directly. The process-exit hook is deliberately the sole
+ * direct write because an exit handler cannot await this asynchronous seam.
+ */
+function dispatchMainThreadWriteThroughSeam(pending, reason) {
+    if (_snapshotPromotionSeamForTests) {
+        void _snapshotPromotionSeamForTests().then(() => writeSnapshotBodyOnMainThread(pending, reason));
+        return;
+    }
+    writeSnapshotBodyOnMainThread(pending, reason);
+}
 function handleSnapshotWorkerResult(result) {
     const pending = _snapshotWorkerRequests.get(result.id);
     if (!pending) {
@@ -391,12 +512,15 @@ function handleSnapshotWorkerResult(result) {
         result.serializeMs === undefined ||
         result.writeMs === undefined) {
         fs.rm(result.stagePath, { force: true }, () => { });
-        writeSnapshotBodyOnMainThread(pending, result.error ?? "invalid worker result");
+        dispatchMainThreadWriteThroughSeam(pending, result.error ?? "invalid worker result");
         return;
     }
     // Generation gate: a newer save already superseded this one — discard the
     // stale stage file rather than promote it over the fresher body.
-    if (_snapshotGenerations.get(pending.key) !== result.generation) {
+    if (_snapshotGenerationGateEnabledForTests &&
+        _snapshotGenerations.get(pending.key) !== result.generation) {
+        // The stale stage is part of the promotion transaction: remove it before
+        // returning so a superseded save cannot leave an orphan behind.
         fs.rm(result.stagePath, { force: true }, () => { });
         return;
     }
@@ -414,7 +538,7 @@ function handleSnapshotWorkerResult(result) {
     }
     catch (err) {
         fs.rm(result.stagePath, { force: true }, () => { });
-        writeSnapshotBodyOnMainThread(pending, err instanceof Error ? err.message : String(err));
+        dispatchMainThreadWriteThroughSeam(pending, err instanceof Error ? err.message : String(err));
     }
 }
 function handleSnapshotWorkerDeath(reason) {
@@ -423,7 +547,7 @@ function handleSnapshotWorkerDeath(reason) {
     const requests = [..._snapshotWorkerRequests.values()];
     _snapshotWorkerRequests.clear();
     for (const pending of requests)
-        writeSnapshotBodyOnMainThread(pending, reason);
+        dispatchMainThreadWriteThroughSeam(pending, reason);
 }
 function resolveSnapshotPersistWorkerPath() {
     // esbuild does NOT rewrite new URL(...) asset refs, so from the bundled
@@ -460,8 +584,17 @@ function getSnapshotPersistWorker() {
             return undefined;
         }
         const worker = new Worker(workerPath);
-        worker.unref();
-        worker.on("message", handleSnapshotWorkerResult);
+        // The ForTests promotion seam wraps ONLY when set — the production path
+        // binds the sync handler directly, so scheduling is byte-identical when
+        // no test seam is installed (the async-handler variant of this shifted
+        // promotion timing under full-suite load and flaked the round-trip test).
+        worker.on("message", (result) => {
+            if (_snapshotPromotionSeamForTests) {
+                void _snapshotPromotionSeamForTests().then(() => handleSnapshotWorkerResult(result));
+                return;
+            }
+            handleSnapshotWorkerResult(result);
+        });
         worker.on("error", (err) => handleSnapshotWorkerDeath(err.message));
         worker.on("exit", (code) => {
             if (_snapshotPersistWorker === worker)
@@ -475,7 +608,7 @@ function getSnapshotPersistWorker() {
             if (stranded.length > 0) {
                 _snapshotWorkerRequests.clear();
                 for (const pending of stranded) {
-                    writeSnapshotBodyOnMainThread(pending, `persist worker exited with code ${code}`);
+                    dispatchMainThreadWriteThroughSeam(pending, `persist worker exited with code ${code}`);
                 }
             }
             // Only an ABNORMAL exit disables respawning; a clean idle exit (nothing
@@ -483,6 +616,9 @@ function getSnapshotPersistWorker() {
             if (code !== 0)
                 _snapshotWorkerDisabled = true;
         });
+        // #1148: adding a message listener refs the Worker's public MessagePort.
+        // Unref only after every listener is installed so it stays background-only.
+        worker.unref();
         _snapshotPersistWorker = worker;
         return worker;
     }
@@ -585,7 +721,14 @@ export function saveProjectSnapshot(cwd, snapshot) {
     // legacy body to a merge-consumer, silently dropping this snapshot's fields.
     const priorBody = resolveSnapshotBodyPath(cwd);
     const knownMtime = priorBody ? priorBody.mtimeMs : Number.NEGATIVE_INFINITY;
-    authoritativeSnapshots.set(key, { snapshot, knownMtime });
+    const authoritativeEntry = {
+        snapshot,
+        knownMtime,
+        lastUsedAt: Date.now(),
+    };
+    authoritativeSnapshots.set(key, authoritativeEntry);
+    scheduleAuthoritativeSnapshotEviction(key, authoritativeEntry);
+    enforceAuthoritativeSnapshotCap();
     // A stale disk-parse-cache entry for this path must not out-vote the fresh
     // authoritative write once the latter is dropped (oversized bodies).
     snapshotParseCache.delete(gzPath);
@@ -604,12 +747,12 @@ export function saveProjectSnapshot(cwd, snapshot) {
     sweepStaleSnapshotStageFiles(cacheDir);
     ensureSnapshotPersistExitHook();
     if (!snapshotWorkerEnabled()) {
-        writeSnapshotBodyOnMainThread(pending);
+        dispatchMainThreadWriteThroughSeam(pending, undefined);
         return;
     }
     const worker = getSnapshotPersistWorker();
     if (!worker) {
-        writeSnapshotBodyOnMainThread(pending, "persist worker unavailable");
+        dispatchMainThreadWriteThroughSeam(pending, "persist worker unavailable");
         return;
     }
     const id = ++_snapshotWorkerRequestId;
@@ -640,7 +783,7 @@ export function flushProjectSnapshotPersistsForTests() {
     for (const pending of requests) {
         if (_snapshotGenerations.get(pending.key) !== pending.generation)
             continue;
-        writeSnapshotBodyOnMainThread(pending);
+        dispatchMainThreadWriteThroughSeam(pending, undefined);
     }
 }
 /** Test-only: exercise the degraded worker-death path. */
@@ -652,11 +795,21 @@ export async function terminateProjectSnapshotPersistWorkerForTests() {
 /** Test-only: restore worker creation + clear generation state after a deliberate death. */
 export function resetProjectSnapshotPersistWorkerForTests() {
     _snapshotWorkerDisabled = false;
+    _snapshotGenerationGateEnabledForTests = true;
+    _snapshotPromotionSeamForTests = undefined;
     _snapshotPersistWorker = undefined;
     _snapshotWorkerRequests.clear();
     _snapshotGenerations.clear();
     _lastSnapshotPersistErrorForTests = undefined;
 }
+/** Test-only mutation switch for proving the supersession invariant. */
+export function setProjectSnapshotGenerationGateForTests(enabled) {
+    _snapshotGenerationGateEnabledForTests = enabled;
+}
+/** Test-only seam immediately before generation-gated promotion. */
+export function setProjectSnapshotPromotionSeamForTests(seam) {
+    _snapshotPromotionSeamForTests = seam;
+}
 export function getProjectSnapshotPersistErrorForTests() {
     return _lastSnapshotPersistErrorForTests;
 }
@@ -730,7 +883,9 @@ export function saveRuntimeProjectSnapshot(args) {
             // isProjectSnapshotFresh on load, seq mismatch) would get silently
             // re-stamped with the CURRENT seq by this save, "laundering" a stale
             // index into looking fresh before the word-index task even runs.
-            if (!snapshot.wordIndex && existing.wordIndex && existing.seq === snapshot.seq) {
+            if (!snapshot.wordIndex &&
+                existing.wordIndex &&
+                existing.seq === snapshot.seq) {
                 snapshot.wordIndex = existing.wordIndex;
             }
         }