@herbertgao/pi-extensions 2026.8.11 → 2026.8.13

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

@@ -5,9 +5,11 @@ import { Worker } from "node:worker_threads";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { writeFileAtomic } from "./atomic-write.js";
 import { getProjectDataDir } from "./file-utils.js";
+import { incrementDegradationCount } from "./degradation-ledger.js";
 import { readJsonCache } from "./json-cache-read.js";
 import { logLatency } from "./latency-logger.js";
 import { normalizeMapKey } from "./path-utils.js";
+import { fingerprintProjectSnapshotJson } from "./project-snapshot-fingerprint.js";
 import { detectProjectConventions, } from "./project-conventions.js";
 import { deserializeWordIndex, serializeWordIndex, } from "./word-index.js";
 // v2: added `wordIndex` (identifier inverted index + BM25, #162). Bumping the
@@ -97,6 +99,15 @@ function parseSnapshotMeta(value) {
         timestamp: typeof meta.timestamp === "string" ? meta.timestamp : "",
         version: meta.version,
         seq: meta.seq,
+        fingerprint: typeof meta.fingerprint === "string" &&
+            /^[a-f0-9]{64}$/.test(meta.fingerprint)
+            ? meta.fingerprint
+            : undefined,
+        gzBytes: typeof meta.gzBytes === "number" &&
+            Number.isInteger(meta.gzBytes) &&
+            meta.gzBytes > 0
+            ? meta.gzBytes
+            : undefined,
         sequenceIndex: parseSequenceIndex(meta.sequenceIndex),
     };
 }
@@ -149,7 +160,9 @@ 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;
+    return Number.isSafeInteger(value) && value > 0
+        ? value
+        : PROJECT_SNAPSHOT_IDLE_EVICT_MS_DEFAULT;
 }
 function clearAuthoritativeSnapshotTimer(entry) {
     if (entry.idleTimer)
@@ -167,7 +180,8 @@ function scheduleAuthoritativeSnapshotEviction(key, entry) {
     const generation = entry.lastUsedAt;
     entry.idleTimer = setTimeout(() => {
         entry.idleTimer = undefined;
-        if (authoritativeSnapshots.get(key) !== entry || entry.lastUsedAt !== generation)
+        if (authoritativeSnapshots.get(key) !== entry ||
+            entry.lastUsedAt !== generation)
             return;
         deleteAuthoritativeSnapshot(key);
     }, projectSnapshotIdleEvictMs());
@@ -590,7 +604,11 @@ export function loadProjectSnapshot(cwd) {
 export function loadProjectSnapshotWithoutWordIndex(cwd) {
     return loadProjectSnapshotInternal(cwd, false);
 }
-const _snapshotGenerations = new Map();
+const _snapshotGenerationStates = new Map();
+const _successfulSnapshotPersists = new Map();
+const _failedSnapshotPersists = new Map();
+const _activeSnapshotPersists = new Map();
+const _queuedSnapshotPersists = new Map();
 const _snapshotWorkerRequests = new Map();
 let _snapshotPersistWorker;
 let _snapshotWorkerRequestId = 0;
@@ -598,6 +616,8 @@ let _snapshotWorkerDisabled = false;
 let _snapshotGenerationGateEnabledForTests = true;
 let _snapshotPromotionSeamForTests;
 let _lastSnapshotPersistErrorForTests;
+let _snapshotExiting = false;
+let _snapshotWorkerBodyWritesForTests = 0;
 function snapshotWorkerEnabled() {
     // The synchronous fallback writer is a legitimate degraded mode (hosts that
     // can't spawn a worker); tests also force it so a save→load is fully
@@ -605,31 +625,233 @@ function snapshotWorkerEnabled() {
     const raw = process.env.PI_LENS_SNAPSHOT_PERSIST_SYNC;
     return !(raw === "1" || raw === "true");
 }
-function recordSnapshotPersistFailure(cwd, error) {
+function pendingSnapshotIsCurrent(pending) {
+    return (!_snapshotGenerationGateEnabledForTests ||
+        _snapshotGenerationStates.get(pending.key)?.generation ===
+            pending.generation);
+}
+function rememberSuccessfulSnapshotPersist(key, record) {
+    _successfulSnapshotPersists.delete(key);
+    _successfulSnapshotPersists.set(key, record);
+    while (_successfulSnapshotPersists.size > PROJECT_SNAPSHOT_MAX_WARM_ROOTS) {
+        const oldest = _successfulSnapshotPersists.keys().next().value;
+        if (oldest === undefined)
+            break;
+        _successfulSnapshotPersists.delete(oldest);
+    }
+}
+function assessSnapshotBodyIntegrity(meta, body) {
+    if (meta.gzBytes === undefined) {
+        // Legacy meta (pre-#2008): nothing to compare against, so the evidence is
+        // untrusted until the next successful persist populates gzBytes.
+        return { outcome: "legacy-meta", actualBytes: body.size };
+    }
+    if (!body.gz || body.size !== meta.gzBytes) {
+        return {
+            outcome: "size-mismatch",
+            expectedGzBytes: meta.gzBytes,
+            actualBytes: body.size,
+        };
+    }
+    return {
+        outcome: "ok",
+        expectedGzBytes: meta.gzBytes,
+        actualBytes: body.size,
+    };
+}
+/**
+ * Bounded observability for #2008: the degradation ledger keeps one entry per
+ * corrupted subject with the exact detection count for the session; every
+ * detection also emits one `project_snapshot_body_integrity` latency row
+ * naming expected vs actual bytes, so an operator can confirm both the
+ * detection and the forced republish from logs alone.
+ */
+function noteSnapshotBodyIntegrityWithheld(args) {
+    incrementDegradationCount({
+        kind: "snapshot-integrity",
+        subject: args.gzPath,
+        reason: args.verdict,
+    });
+    logLatency({
+        type: "phase",
+        phase: "project_snapshot_body_integrity",
+        filePath: args.gzPath,
+        durationMs: 0,
+        metadata: {
+            outcome: "dedupe_withheld",
+            reason: args.verdict,
+            ...(args.seq !== undefined ? { seq: args.seq } : {}),
+            ...(args.expectedGzBytes === undefined
+                ? {}
+                : { expectedGzBytes: args.expectedGzBytes }),
+            actualBytes: args.actualBytes,
+        },
+    });
+}
+/** Log one row naming a skip that was refused because integrity regressed. */
+function noteSnapshotSkipRefused(args) {
+    logLatency({
+        type: "phase",
+        phase: "project_snapshot_body_integrity",
+        filePath: args.gzPath,
+        durationMs: 0,
+        metadata: {
+            outcome: "skip_refused_rewrite",
+            reason: args.verdict,
+            seq: args.seq,
+        },
+    });
+}
+/**
+ * PURE READ of the durable meta+body evidence for a snapshot key (#2008
+ * refactor): it must never mutate {@link _successfulSnapshotPersists}. This
+ * runs up to three times per persist — admission in saveProjectSnapshot, the
+ * dispatch-time refresh, and the skip-honor re-read — including on results
+ * whose fingerprints are only partially used, so the seeding write lives in
+ * {@link seedSnapshotPersistBaselineFromDurable} and is called only by the
+ * seam that owns the persist lifecycle (dispatchSnapshotPersist).
+ */
+function snapshotPersistBaselinesFor(cwd, key) {
+    const local = _successfulSnapshotPersists.get(key);
+    const meta = readProjectSnapshotMeta(cwd);
+    const body = resolveSnapshotBodyPath(cwd);
+    // No body means no dedupe evidence. This keeps same-seq deletion repair live.
+    if (!meta?.fingerprint || !body) {
+        if (!body)
+            _successfulSnapshotPersists.delete(key);
+        return { fingerprints: [] };
+    }
+    // #2008: a meta whose recorded gz size no longer matches the on-disk body
+    // describes evidence we cannot trust — a truncated/torn gzip under an
+    // intact meta used to win same-fingerprint dedupe forever, keeping the
+    // corrupt body canonical until seq advanced. Withhold the fingerprints so
+    // the pending save republishes (and rewrites) the body.
+    const integrity = assessSnapshotBodyIntegrity(meta, body);
+    if (integrity.outcome !== "ok") {
+        noteSnapshotBodyIntegrityWithheld({
+            gzPath: getProjectSnapshotPath(cwd),
+            verdict: integrity.outcome,
+            seq: meta.seq,
+            expectedGzBytes: integrity.expectedGzBytes,
+            actualBytes: integrity.actualBytes,
+        });
+        return { fingerprints: [] };
+    }
+    const durable = {
+        seq: meta.seq,
+        fingerprint: meta.fingerprint,
+        generatedAt: meta.timestamp,
+        generation: _snapshotGenerationStates.get(key)?.generation ?? 0,
+        gzBytes: meta.gzBytes,
+    };
+    const fingerprints = [durable.fingerprint];
+    // A sibling process may have advanced durable state from local A to B. An
+    // unchanged replay of A is stale work and must not overwrite B. A third
+    // semantic state C matches neither fingerprint and still publishes.
+    if (local && local.fingerprint !== durable.fingerprint) {
+        fingerprints.push(local.fingerprint);
+    }
+    return { durable, fingerprints, integrity: "ok" };
+}
+/**
+ * Seed the in-process baseline for `key` from freshly-read durable state.
+ * Deliberately separate from {@link snapshotPersistBaselinesFor} so the read
+ * stays pure; called only at the dispatch seam where the persist lifecycle
+ * begins.
+ */
+function seedSnapshotPersistBaselineFromDurable(key, durable) {
+    if (!durable || _successfulSnapshotPersists.has(key))
+        return;
+    rememberSuccessfulSnapshotPersist(key, durable);
+}
+function writeProjectSnapshotMeta(metaPath, snapshot, bodyRecord) {
+    writeFileAtomic(metaPath, JSON.stringify({
+        timestamp: bodyRecord?.generatedAt ?? snapshot.generatedAt,
+        version: snapshot.version,
+        seq: snapshot.seq,
+        ...(bodyRecord
+            ? {
+                fingerprint: bodyRecord.fingerprint,
+                ...(bodyRecord.gzBytes === undefined
+                    ? {}
+                    : { gzBytes: bodyRecord.gzBytes }),
+            }
+            : {}),
+        ...(snapshot.sequenceIndex
+            ? { sequenceIndex: snapshot.sequenceIndex }
+            : {}),
+    }), { bestEffort: false });
+}
+function recordSnapshotPersistFailure(pending, error, bodyPersisted = false) {
     // Honesty (#533): a failed async body write must be surfaced, never left to
     // masquerade as a saved snapshot. The meta gate is already self-healing (an
     // old body under a newer-seq meta is rejected on the body's own embedded
     // 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;
-    deleteAuthoritativeSnapshot(normalizeMapKey(cwd));
+    _failedSnapshotPersists.set(pending.key, {
+        seq: pending.snapshot.seq,
+        generation: pending.generation,
+    });
+    while (_failedSnapshotPersists.size > PROJECT_SNAPSHOT_MAX_WARM_ROOTS) {
+        const oldest = _failedSnapshotPersists.keys().next().value;
+        if (oldest === undefined)
+            break;
+        _failedSnapshotPersists.delete(oldest);
+    }
+    deleteAuthoritativeSnapshot(pending.key);
     logLatency({
         type: "phase",
         phase: "project_snapshot_persist_failed",
-        filePath: getProjectSnapshotPath(cwd),
+        filePath: pending.gzPath,
         durationMs: 0,
-        metadata: { error },
+        metadata: {
+            error,
+            seq: pending.snapshot.seq,
+            outcome: bodyPersisted ? "metadata_repair_required" : "failed",
+            ...(bodyPersisted ? { bodyPersisted: true } : {}),
+        },
     });
     // #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) {
+function logSnapshotPersistSuccess(pending, fingerprint, stats) {
+    rememberSuccessfulSnapshotPersist(pending.key, {
+        seq: pending.snapshot.seq,
+        fingerprint,
+        generatedAt: pending.snapshot.generatedAt,
+        generation: pending.generation,
+        rawBytes: stats.rawBytes,
+        gzBytes: stats.gzBytes,
+    });
+    _failedSnapshotPersists.delete(pending.key);
     logLatency({
         type: "phase",
         phase: "project_snapshot_persist",
         filePath: pending.gzPath,
         durationMs: stats.serializeMs + stats.writeMs,
-        metadata: { seq: pending.snapshot.seq, ...stats },
+        metadata: { seq: pending.snapshot.seq, outcome: "executed", ...stats },
+    });
+}
+function logSnapshotPersistDecision(args) {
+    logLatency({
+        type: "phase",
+        phase: "project_snapshot_persist_decision",
+        filePath: getProjectSnapshotPath(args.cwd),
+        durationMs: 0,
+        metadata: {
+            seq: args.seq,
+            decision: args.decision,
+            ...(args.fingerprint
+                ? { fingerprint: args.fingerprint.slice(0, 12) }
+                : {}),
+            ...(args.avoidedRawBytes === undefined
+                ? {}
+                : { avoidedRawBytes: args.avoidedRawBytes }),
+            ...(args.avoidedGzipBytes === undefined
+                ? {}
+                : { avoidedGzipBytes: args.avoidedGzipBytes }),
+        },
     });
 }
 /**
@@ -692,7 +914,33 @@ function reconcileAuthoritativeAfterWrite(pending, rawBytes) {
         // is one extra disk re-parse on the next load.
     }
 }
+function finalizeProjectSnapshotMeta(pending, record) {
+    try {
+        writeProjectSnapshotMeta(getProjectSnapshotMetaPath(pending.cwd), pending.snapshot, record);
+        return true;
+    }
+    catch (err) {
+        recordSnapshotPersistFailure(pending, err instanceof Error ? err.message : String(err), true);
+        return false;
+    }
+}
+function completeSnapshotPersist(pending) {
+    if (_activeSnapshotPersists.get(pending.key) !== pending)
+        return;
+    _activeSnapshotPersists.delete(pending.key);
+    if (_snapshotExiting)
+        return;
+    const queued = _queuedSnapshotPersists.get(pending.key);
+    if (!queued)
+        return;
+    _queuedSnapshotPersists.delete(pending.key);
+    dispatchSnapshotPersist(queued);
+}
 function writeSnapshotBodyOnMainThread(pending, reason) {
+    if (!pendingSnapshotIsCurrent(pending)) {
+        completeSnapshotPersist(pending);
+        return;
+    }
     if (reason) {
         // We took the synchronous main-thread gzip path (the +656MB-risk path,
         // #950) instead of the worker. Surface it rather than burying it in an
@@ -717,13 +965,52 @@ function writeSnapshotBodyOnMainThread(pending, reason) {
         const json = JSON.stringify(pending.snapshot);
         const serializeMs = performance.now() - serializeStarted;
         const rawBytes = Buffer.byteLength(json);
+        const fingerprint = fingerprintProjectSnapshotJson(json, pending.snapshot.generatedAt);
+        if (pending.dedupeFingerprints.includes(fingerprint)) {
+            // Re-read the tiny durable sidecar before honoring a fingerprint
+            // captured at dispatch time (#2008): a body torn between dispatch and
+            // execution must fall through to the full write, not skip.
+            const current = snapshotPersistBaselinesFor(pending.cwd, pending.key);
+            if (current.integrity === "ok") {
+                const prior = current.durable ?? pending.durablePersist;
+                if (authoritativeSnapshots.get(pending.key)?.snapshot === pending.snapshot) {
+                    deleteAuthoritativeSnapshot(pending.key);
+                }
+                logSnapshotPersistDecision({
+                    cwd: pending.cwd,
+                    seq: pending.snapshot.seq,
+                    fingerprint,
+                    decision: "skipped_unchanged",
+                    avoidedRawBytes: rawBytes,
+                    avoidedGzipBytes: prior?.gzBytes,
+                });
+                return;
+            }
+            if (current.integrity !== undefined) {
+                noteSnapshotSkipRefused({
+                    gzPath: pending.gzPath,
+                    verdict: current.integrity,
+                    seq: pending.snapshot.seq,
+                });
+            }
+            // integrity === undefined: the meta/body evidence vanished entirely
+            // since dispatch — falling through to the full write repairs it, the
+            // same contract as deletion-before-dispatch.
+        }
         const writeStarted = performance.now();
         const gzip = gzipSync(json);
         fs.mkdirSync(path.dirname(pending.gzPath), { recursive: true });
         writeFileAtomic(pending.gzPath, gzip, { bestEffort: false });
         fs.rmSync(pending.legacyPath, { force: true });
+        const metadataFinalized = finalizeProjectSnapshotMeta(pending, {
+            fingerprint,
+            generatedAt: pending.snapshot.generatedAt,
+            gzBytes: gzip.byteLength,
+        });
+        if (!metadataFinalized)
+            return;
         reconcileAuthoritativeAfterWrite(pending, rawBytes);
-        logSnapshotPersistSuccess(pending, {
+        logSnapshotPersistSuccess(pending, fingerprint, {
             rawBytes,
             gzBytes: gzip.byteLength,
             serializeMs,
@@ -734,7 +1021,10 @@ function writeSnapshotBodyOnMainThread(pending, reason) {
             _lastSnapshotPersistErrorForTests = reason;
     }
     catch (err) {
-        recordSnapshotPersistFailure(pending.cwd, err instanceof Error ? err.message : String(err));
+        recordSnapshotPersistFailure(pending, err instanceof Error ? err.message : String(err));
+    }
+    finally {
+        completeSnapshotPersist(pending);
     }
 }
 /**
@@ -753,7 +1043,7 @@ function dispatchMainThreadWriteThroughSeam(pending, reason) {
 function handleSnapshotWorkerResult(result) {
     const pending = _snapshotWorkerRequests.get(result.id);
     if (!pending) {
-        fs.rm(result.stagePath, { force: true }, () => { });
+        fs.rmSync(result.stagePath, { force: true });
         return;
     }
     _snapshotWorkerRequests.delete(result.id);
@@ -761,37 +1051,128 @@ function handleSnapshotWorkerResult(result) {
         result.rawBytes === undefined ||
         result.gzBytes === undefined ||
         result.serializeMs === undefined ||
-        result.writeMs === undefined) {
-        fs.rm(result.stagePath, { force: true }, () => { });
+        result.writeMs === undefined ||
+        result.semanticFingerprint === undefined) {
+        fs.rmSync(result.stagePath, { force: true });
         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 (!result.skippedUnchanged)
+        _snapshotWorkerBodyWritesForTests++;
     if (_snapshotGenerationGateEnabledForTests &&
-        _snapshotGenerations.get(pending.key) !== result.generation) {
+        _snapshotGenerationStates.get(pending.key)?.generation !== 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 }, () => { });
+        fs.rmSync(result.stagePath, { force: true });
+        completeSnapshotPersist(pending);
+        return;
+    }
+    if (result.skippedUnchanged) {
+        // Re-read the tiny durable sidecar at the decision seam. A sibling process
+        // may have advanced B after this request captured A. A stale replay of A
+        // must preserve B's body metadata, not restore the captured A sidecar.
+        const baselines = snapshotPersistBaselinesFor(pending.cwd, pending.key);
+        if (baselines.integrity !== "ok") {
+            // The worker skipped WITHOUT staging a body, trusting the durable
+            // fingerprint captured at dispatch. The re-read says that evidence no
+            // longer passes the #2008 integrity gate — refuse the skip and rewrite
+            // synchronously so a torn/missing body cannot outlive this save. The
+            // sync writer recomputes the same baselines, finds them untrusted, and
+            // performs the full gzip+stage+promote (its finally completes this
+            // pending, so do not complete it twice here).
+            if (baselines.integrity !== undefined) {
+                noteSnapshotSkipRefused({
+                    gzPath: pending.gzPath,
+                    verdict: baselines.integrity,
+                    seq: pending.snapshot.seq,
+                });
+            }
+            dispatchMainThreadWriteThroughSeam(pending, "snapshot body integrity regressed");
+            return;
+        }
+        const prior = baselines.durable ?? pending.durablePersist;
+        if (authoritativeSnapshots.get(pending.key)?.snapshot === pending.snapshot) {
+            deleteAuthoritativeSnapshot(pending.key);
+        }
+        logSnapshotPersistDecision({
+            cwd: pending.cwd,
+            seq: pending.snapshot.seq,
+            fingerprint: result.semanticFingerprint,
+            decision: "skipped_unchanged",
+            avoidedRawBytes: result.rawBytes,
+            avoidedGzipBytes: prior?.gzBytes,
+        });
+        completeSnapshotPersist(pending);
         return;
     }
     try {
         fs.renameSync(result.stagePath, pending.gzPath);
         fs.rmSync(pending.legacyPath, { force: true });
+        const metadataFinalized = finalizeProjectSnapshotMeta(pending, {
+            fingerprint: result.semanticFingerprint,
+            generatedAt: pending.snapshot.generatedAt,
+            gzBytes: result.gzBytes,
+        });
+        if (!metadataFinalized) {
+            completeSnapshotPersist(pending);
+            return;
+        }
         reconcileAuthoritativeAfterWrite(pending, result.rawBytes);
-        logSnapshotPersistSuccess(pending, {
+        logSnapshotPersistSuccess(pending, result.semanticFingerprint, {
             rawBytes: result.rawBytes,
             gzBytes: result.gzBytes,
             serializeMs: result.serializeMs,
             writeMs: result.writeMs,
             offloaded: true,
         });
+        completeSnapshotPersist(pending);
     }
     catch (err) {
         fs.rm(result.stagePath, { force: true }, () => { });
         dispatchMainThreadWriteThroughSeam(pending, err instanceof Error ? err.message : String(err));
     }
 }
+function dispatchSnapshotPersist(pending) {
+    // A queued request may have waited behind the publication that created its
+    // best dedupe evidence. Refresh only the tiny sidecar/body stat here; never
+    // retain the stale admission-time baseline through dispatch.
+    const baselines = snapshotPersistBaselinesFor(pending.cwd, pending.key);
+    pending.durablePersist = baselines.durable;
+    pending.dedupeFingerprints = baselines.fingerprints;
+    seedSnapshotPersistBaselineFromDurable(pending.key, baselines.durable);
+    _activeSnapshotPersists.set(pending.key, pending);
+    if (!snapshotWorkerEnabled()) {
+        dispatchMainThreadWriteThroughSeam(pending, undefined);
+        return;
+    }
+    const worker = getSnapshotPersistWorker();
+    if (!worker) {
+        dispatchMainThreadWriteThroughSeam(pending, "persist worker unavailable");
+        return;
+    }
+    const id = ++_snapshotWorkerRequestId;
+    _snapshotWorkerRequests.set(id, pending);
+    const request = {
+        id,
+        generation: pending.generation,
+        stagePath: pending.stagePath,
+        data: pending.snapshot,
+        priorFingerprints: pending.dedupeFingerprints,
+        testDelayMs: process.env.NODE_ENV === "test"
+            ? Number(process.env.PI_LENS_TEST_SNAPSHOT_PERSIST_WORKER_DELAY_MS) ||
+                undefined
+            : undefined,
+    };
+    try {
+        worker.postMessage(request);
+    }
+    catch (err) {
+        _snapshotWorkerRequests.delete(id);
+        dispatchMainThreadWriteThroughSeam(pending, err instanceof Error ? err.message : String(err));
+    }
+}
 function handleSnapshotWorkerDeath(reason) {
     _snapshotPersistWorker = undefined;
     _snapshotWorkerDisabled = true;
@@ -909,12 +1290,27 @@ function ensureSnapshotPersistExitHook() {
         return;
     _snapshotExitHookInstalled = true;
     process.once("exit", () => {
-        const requests = [..._snapshotWorkerRequests.values()];
+        _snapshotExiting = true;
+        const latestByKey = new Map();
+        for (const pending of _snapshotWorkerRequests.values()) {
+            latestByKey.set(pending.key, pending);
+        }
+        for (const pending of _queuedSnapshotPersists.values()) {
+            const prior = latestByKey.get(pending.key);
+            // Queued work is later admission order. Equal-seq requests deliberately
+            // share a gate generation, so a tie must still select the queued payload.
+            if (!prior || prior.generation <= pending.generation) {
+                latestByKey.set(pending.key, pending);
+            }
+        }
         _snapshotWorkerRequests.clear();
-        for (const pending of requests) {
+        _queuedSnapshotPersists.clear();
+        _activeSnapshotPersists.clear();
+        for (const pending of latestByKey.values()) {
             // Only the newest generation per key still matters; older ones are
             // superseded and their stage files are swept on next launch.
-            if (_snapshotGenerations.get(pending.key) !== pending.generation)
+            if (_snapshotGenerationStates.get(pending.key)?.generation !==
+                pending.generation)
                 continue;
             writeSnapshotBodyOnMainThread(pending, "exit_hook");
         }
@@ -928,8 +1324,18 @@ export function saveProjectSnapshot(cwd, snapshot) {
     const cacheDir = path.dirname(gzPath);
     const key = normalizeMapKey(cwd);
     fs.mkdirSync(cacheDir, { recursive: true });
-    // #958: meta is written FIRST, body SECOND — the reverse of the original
-    // order. A crash/failure between the two writes can now only produce
+    const baselines = snapshotPersistBaselinesFor(cwd, key);
+    const priorPersist = baselines.durable;
+    logSnapshotPersistDecision({
+        cwd,
+        seq: snapshot.seq,
+        decision: "requested",
+    });
+    if (_failedSnapshotPersists.delete(key)) {
+        logSnapshotPersistDecision({ cwd, seq: snapshot.seq, decision: "retry" });
+    }
+    // #958: for a new seq, meta is written FIRST and body SECOND. A crash or
+    // failure between the two writes can now only produce
     // "meta already claims the new seq, body hasn't caught up yet" (the meta
     // races ahead). The meta-first gate (isProjectSnapshotMetaStale) reads
     // that as *fresh* and falls through to parsing the body, whose own
@@ -941,24 +1347,14 @@ export function saveProjectSnapshot(cwd, snapshot) {
     // away a genuinely fresh snapshot. That direction is not recoverable
     // until the next save, so it's the one this reorder eliminates.
     //
-    // The meta write is still SYNCHRONOUS (it is tiny) and uses
-    // `bestEffort: false`: if it fails, the body persist below is skipped
-    // entirely — the save is simply lost this round (fail-open, caught by
-    // `saveRuntimeProjectSnapshot`'s own try/catch) rather than leaving a
-    // stale meta in place while the body writer stampedes ahead.
-    writeFileAtomic(metaPath, JSON.stringify({
-        timestamp: snapshot.generatedAt,
-        version: snapshot.version,
-        seq: snapshot.seq,
-        // #1019: mirror the derived sequence index (kept consistent with `seq`
-        // because both are stamped from the same runtime moment) so the
-        // interactive path can hydrate it from the tiny sidecar. Omitted when
-        // absent so a non-runtime side-write (word-index/reverse-deps) that
-        // carried no index doesn't stamp an empty one.
-        ...(snapshot.sequenceIndex
-            ? { sequenceIndex: snapshot.sequenceIndex }
-            : {}),
-    }), { bestEffort: false });
+    // The new-seq meta write stays synchronous and throwing. Same-seq work does
+    // not need to advance the freshness gate, so it leaves the current sidecar
+    // untouched until the worker has a semantic verdict. This prevents a stale
+    // local request from replacing a
+    // newer sibling process's same-seq fingerprint before it can coalesce.
+    if (priorPersist?.seq !== snapshot.seq) {
+        writeProjectSnapshotMeta(metaPath, snapshot);
+    }
     // Record the authoritative in-process write BEFORE handing the body off, so
     // a merge-read between now and the worker's promotion sees our own object
     // (the on-disk body still holds the previous generation until promotion). The
@@ -983,8 +1379,11 @@ export function saveProjectSnapshot(cwd, snapshot) {
     // 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);
-    const generation = (_snapshotGenerations.get(key) ?? 0) + 1;
-    _snapshotGenerations.set(key, generation);
+    const generationState = _snapshotGenerationStates.get(key);
+    const generation = generationState?.seq === snapshot.seq
+        ? generationState.generation
+        : (generationState?.generation ?? 0) + 1;
+    _snapshotGenerationStates.set(key, { generation, seq: snapshot.seq });
     const stagePath = `${gzPath}.stage-${process.pid}-${generation}`;
     const pending = {
         key,
@@ -994,36 +1393,29 @@ export function saveProjectSnapshot(cwd, snapshot) {
         stagePath,
         snapshot,
         generation,
+        durablePersist: priorPersist,
+        dedupeFingerprints: baselines.fingerprints,
     };
     sweepStaleSnapshotStageFiles(cacheDir);
     ensureSnapshotPersistExitHook();
-    if (!snapshotWorkerEnabled()) {
-        dispatchMainThreadWriteThroughSeam(pending, undefined);
-        return;
-    }
-    const worker = getSnapshotPersistWorker();
-    if (!worker) {
-        dispatchMainThreadWriteThroughSeam(pending, "persist worker unavailable");
+    if (_activeSnapshotPersists.has(key)) {
+        _queuedSnapshotPersists.set(key, pending);
+        logSnapshotPersistDecision({
+            cwd,
+            seq: snapshot.seq,
+            decision: "coalesced",
+        });
         return;
     }
-    const id = ++_snapshotWorkerRequestId;
-    _snapshotWorkerRequests.set(id, pending);
-    const request = {
-        id,
-        generation,
-        stagePath,
-        data: snapshot,
-        testDelayMs: process.env.NODE_ENV === "test"
-            ? Number(process.env.PI_LENS_TEST_SNAPSHOT_PERSIST_WORKER_DELAY_MS) ||
-                undefined
-            : undefined,
-    };
-    worker.postMessage(request);
+    dispatchSnapshotPersist(pending);
 }
 // --- Test hooks for the worker persist path ---------------------------------
 /** Test-only: wait until worker requests have either landed or degraded. */
 export async function waitForProjectSnapshotPersistsForTests() {
-    for (let attempts = 0; attempts < 200 && _snapshotWorkerRequests.size > 0; attempts++) {
+    for (let attempts = 0; attempts < 200 &&
+        (_snapshotWorkerRequests.size > 0 ||
+            _activeSnapshotPersists.size > 0 ||
+            _queuedSnapshotPersists.size > 0); attempts++) {
         await new Promise((resolve) => setTimeout(resolve, 10));
     }
 }
@@ -1032,8 +1424,6 @@ export function flushProjectSnapshotPersistsForTests() {
     const requests = [..._snapshotWorkerRequests.values()];
     _snapshotWorkerRequests.clear();
     for (const pending of requests) {
-        if (_snapshotGenerations.get(pending.key) !== pending.generation)
-            continue;
         dispatchMainThreadWriteThroughSeam(pending, undefined);
     }
 }
@@ -1050,9 +1440,25 @@ export function resetProjectSnapshotPersistWorkerForTests() {
     _snapshotPromotionSeamForTests = undefined;
     _snapshotPersistWorker = undefined;
     _snapshotWorkerRequests.clear();
-    _snapshotGenerations.clear();
+    _snapshotGenerationStates.clear();
+    _successfulSnapshotPersists.clear();
+    _failedSnapshotPersists.clear();
+    _activeSnapshotPersists.clear();
+    _queuedSnapshotPersists.clear();
+    _snapshotExiting = false;
+    _snapshotWorkerBodyWritesForTests = 0;
     _lastSnapshotPersistErrorForTests = undefined;
 }
+/** Test-only: expose bounded queue state without retaining snapshot bodies. */
+export function getProjectSnapshotPersistStateForTests(cwd) {
+    const key = normalizeMapKey(cwd);
+    return {
+        active: _activeSnapshotPersists.has(key),
+        queued: _queuedSnapshotPersists.has(key),
+        successfulFingerprint: _successfulSnapshotPersists.get(key)?.fingerprint,
+        workerBodyWrites: _snapshotWorkerBodyWritesForTests,
+    };
+}
 /** Test-only mutation switch for proving the supersession invariant. */
 export function setProjectSnapshotGenerationGateForTests(enabled) {
     _snapshotGenerationGateEnabledForTests = enabled;