codex-multi-auth 2.17.0 → 2.17.3

package/dist/lib/storage.js

@@ -1,6 +1,7 @@
 import { existsSync, promises as fs, readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { ACCOUNT_LIMITS } from "./constants.js";
+import { parseIntegerEnv } from "./env-parsing.js";
 import { StorageError } from "./errors.js";
 import { withFileOperationRetry, withRetry } from "./fs-retry.js";
 import { createLogger } from "./logger.js";
@@ -69,6 +70,68 @@ const BACKUP_COPY_MAX_ATTEMPTS = 5;
 const BACKUP_COPY_BASE_DELAY_MS = 10;
 let storageBackupEnabled = true;
 let lastAccountsSaveTimestamp = 0;
+/**
+ * Default minimum age of the newest rotating `.bak` snapshot before a save
+ * pays for another full 3-slot rotation. Rotating backups are crash-recovery
+ * insurance, not a changelog: inside the window the primary-write path skips
+ * ~6 fs ops and ~2x payload bytes of staged copies per save. A credential
+ * change (account count or refresh-token set) still forces a fresh slot — a
+ * backup that predates an in-window rotation can only offer spent tokens — a
+ * missing `.bak` always rotates, and
+ * `CODEX_AUTH_STORAGE_BACKUP_MIN_INTERVAL_MS=0` restores the legacy
+ * rotate-on-every-save behavior.
+ */
+const ACCOUNTS_BACKUP_MIN_INTERVAL_DEFAULT_MS = 30_000;
+function backupRotationMinIntervalMs() {
+    const parsed = parseIntegerEnv(process.env.CODEX_AUTH_STORAGE_BACKUP_MIN_INTERVAL_MS);
+    if (parsed === undefined) {
+        return ACCOUNTS_BACKUP_MIN_INTERVAL_DEFAULT_MS;
+    }
+    return Math.max(0, parsed);
+}
+const lastKnownPrimaryState = new Map();
+const baselinelessSaveWarnedPaths = new Set();
+function notePrimaryState(path, stats, sha256) {
+    if (!stats && sha256 === undefined)
+        return;
+    const fingerprint = { sha256 };
+    if (stats) {
+        if (Number.isFinite(stats.mtimeMs))
+            fingerprint.mtimeMs = stats.mtimeMs;
+        if (Number.isFinite(stats.ctimeMs))
+            fingerprint.ctimeMs = stats.ctimeMs;
+        if (Number.isFinite(stats.size))
+            fingerprint.size = stats.size;
+        // ino can exceed 2^53 on some filesystems; a lossy value would compare
+        // equal for two different files, so only record exact integers.
+        if (Number.isSafeInteger(stats.ino))
+            fingerprint.ino = stats.ino;
+    }
+    if (fingerprint.mtimeMs === undefined &&
+        fingerprint.ctimeMs === undefined &&
+        fingerprint.size === undefined &&
+        fingerprint.ino === undefined &&
+        fingerprint.sha256 === undefined) {
+        return;
+    }
+    lastKnownPrimaryState.set(path, fingerprint);
+}
+/**
+ * Metadata-only identity check, used when no content hash was recorded. A
+ * foreign write bumps ctime on POSIX even when the writer preserves mtime
+ * (utimes), and a rename-replacement changes ino — together they catch the
+ * equal-mtime collisions a mtime-only comparison missed.
+ */
+function primaryFingerprintMatches(last, stats) {
+    return (last.mtimeMs !== undefined &&
+        last.ctimeMs !== undefined &&
+        last.size !== undefined &&
+        last.ino !== undefined &&
+        last.mtimeMs === stats.mtimeMs &&
+        last.ctimeMs === stats.ctimeMs &&
+        last.size === stats.size &&
+        last.ino === stats.ino);
+}
 async function ensureGitignore(storagePath) {
     const state = getStoragePathState();
     if (!state.currentStoragePath)
@@ -201,6 +264,185 @@ async function createRotatingAccountsBackup(path) {
         }
     }
 }
+function credentialSignatureOf(accounts) {
+    const refreshTokens = new Set();
+    for (const account of accounts) {
+        if (isRecord(account) &&
+            typeof account.refreshToken === "string" &&
+            account.refreshToken.length > 0) {
+            refreshTokens.add(account.refreshToken);
+        }
+    }
+    return { count: accounts.length, refreshTokens };
+}
+function sameCredentialSignature(a, b) {
+    if (a.count !== b.count || a.refreshTokens.size !== b.refreshTokens.size) {
+        return false;
+    }
+    for (const token of a.refreshTokens) {
+        if (!b.refreshTokens.has(token))
+            return false;
+    }
+    return true;
+}
+/**
+ * Cheap credential-signature probe for the throttle trigger. Reads and parses
+ * only the top-level `accounts` shape — far cheaper than the staged copies a
+ * rotation costs, and it runs at most once per save inside the throttle
+ * window. Returns null when the signature cannot be determined so the caller
+ * rotates rather than skipping a snapshot it cannot rule out.
+ */
+async function readOnDiskCredentialSignature(path) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path, "utf-8"));
+        if (isRecord(parsed) && Array.isArray(parsed.accounts)) {
+            return credentialSignatureOf(parsed.accounts);
+        }
+    }
+    catch {
+        // Missing or unparsable primary: fall through to the null sentinel.
+    }
+    return null;
+}
+/**
+ * Refresh tokens still present in a recovery source: rotating and discovered
+ * `.bak*` snapshots plus any WAL journal payload. Pending rotated credentials
+ * whose spent token a restore could still resurface must survive pruning, so
+ * recovering a throttle-stale backup self-heals to the newest credential via
+ * `applyPendingAuth` instead of reviving a token that was spent upstream.
+ * Best-effort: unreadable or unparseable sources contribute nothing.
+ */
+async function collectRestorableRefreshTokens(path) {
+    const tokens = [];
+    const collectContent = (raw) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (!isRecord(parsed) || !Array.isArray(parsed.accounts))
+            return;
+        for (const account of parsed.accounts) {
+            if (isRecord(account) &&
+                typeof account.refreshToken === "string" &&
+                account.refreshToken.length > 0) {
+                tokens.push(account.refreshToken);
+            }
+        }
+    };
+    for (const candidate of await getAccountsBackupRecoveryCandidatesWithDiscovery(path)) {
+        try {
+            collectContent(await fs.readFile(candidate, "utf-8"));
+        }
+        catch {
+            // An unreadable candidate contributes nothing.
+        }
+    }
+    try {
+        const walEntry = JSON.parse(await fs.readFile(getAccountsWalPath(path), "utf-8"));
+        if (isRecord(walEntry) && typeof walEntry.content === "string") {
+            collectContent(walEntry.content);
+        }
+    }
+    catch {
+        // No usable WAL payload.
+    }
+    return tokens;
+}
+/**
+ * Gate around `createRotatingAccountsBackup` that throttles rotation churn.
+ * Rotates when the newest `.bak` is missing (always preserve at least one
+ * recovery snapshot), when it is older than `backupRotationMinIntervalMs()`,
+ * or when the incoming write changes the stored credential signature
+ * (account count or refresh-token set) — the case where the pre-write state
+ * is worth a fresh slot even inside the window.
+ * `expectedOnDiskAccounts` lets callers that already read the primary under
+ * the lock (the three-way merge path) skip the signature probe.
+ */
+async function rotateAccountsBackupIfDue(path, nextAccounts, expectedOnDiskAccounts) {
+    const latestBackupPath = getAccountsBackupPath(path);
+    let newestBackupAgeMs = null;
+    try {
+        newestBackupAgeMs = Date.now() - (await fs.stat(latestBackupPath)).mtimeMs;
+    }
+    catch {
+        // Missing or unreadable newest backup: rotate so >=1 snapshot exists.
+        newestBackupAgeMs = null;
+    }
+    const minIntervalMs = backupRotationMinIntervalMs();
+    // Age is clamped at 0: a backup whose mtime lands fractionally ahead of
+    // Date.now() (fs timestamp granularity vs. the clock) is "fresh", and the
+    // clamp also keeps `minIntervalMs = 0` meaning "always rotate".
+    if (newestBackupAgeMs !== null && Math.max(0, newestBackupAgeMs) < minIntervalMs) {
+        const onDiskSignature = expectedOnDiskAccounts !== undefined
+            ? credentialSignatureOf(expectedOnDiskAccounts ?? [])
+            : await readOnDiskCredentialSignature(path);
+        if (onDiskSignature !== null &&
+            sameCredentialSignature(onDiskSignature, credentialSignatureOf(nextAccounts))) {
+            log.debug("Skipping account backup rotation inside throttle window", {
+                path,
+                backupPath: latestBackupPath,
+                newestBackupAgeMs,
+                minIntervalMs,
+            });
+            return;
+        }
+    }
+    await createRotatingAccountsBackup(path);
+}
+/**
+ * Warn (once per storage path per process) when a save without a merge
+ * baseline is about to overwrite a primary this process did not last read or
+ * write — the cheap signature of "concurrent modification, no baseline"
+ * (last-writer-wins). The WeakMap baseline in `saveAccounts` cannot attach to
+ * raw `structuredClone` copies, so this is the residual guard for untracked
+ * objects. First-ever saves (no primary), empty primaries, and files whose
+ * content (or full stat tuple, when no hash was recorded) matches our last
+ * read/write stay quiet; the write is never blocked.
+ */
+async function warnOnBaselinelessSave(path) {
+    if (baselinelessSaveWarnedPaths.has(path))
+        return;
+    // No primary on disk (or an unreadable one): nothing exists to silently
+    // lose, so the first-ever save stays quiet.
+    const stats = await fs.stat(path).catch(() => undefined);
+    if (!stats?.isFile() || stats.size === 0)
+        return;
+    const last = lastKnownPrimaryState.get(path);
+    if (last !== undefined) {
+        if (last.sha256 !== undefined) {
+            // Content-exact check: identical bytes mean nothing was lost to a
+            // foreign write regardless of timestamp granularity or an mtime-
+            // preserving writer, and different bytes mean one landed even when
+            // every stat field coincidentally matches.
+            const currentSha256 = await fs
+                .readFile(path, "utf-8")
+                .then((raw) => computeSha256(raw))
+                .catch(() => undefined);
+            if (currentSha256 !== undefined) {
+                if (currentSha256 === last.sha256)
+                    return;
+            }
+            else if (primaryFingerprintMatches(last, stats)) {
+                // Content unreadable mid-check: fall back to the metadata tuple.
+                return;
+            }
+        }
+        else if (primaryFingerprintMatches(last, stats)) {
+            return;
+        }
+    }
+    baselinelessSaveWarnedPaths.add(path);
+    const message = "Saving account storage without a merge baseline over a primary file this process did not last read or write; a concurrent writer's changes may be overwritten (last-writer-wins). Load via loadAccounts() or clone via cloneTrackedAccountStorage() so the three-way merge can run.";
+    log.warn("Baseline-less account save over externally modified primary", {
+        path,
+    });
+    process.emitWarning(message, {
+        code: "CODEX_MULTI_AUTH_BASELINELESS_SAVE",
+    });
+}
 function isRotatingBackupTempArtifact(storagePath, candidatePath) {
     const backupPrefix = `${storagePath}${ACCOUNTS_BACKUP_SUFFIX}`;
     if (!candidatePath.startsWith(backupPrefix) ||
@@ -467,7 +709,14 @@ export async function restoreAccountsFromBackup(path, options) {
             normalizeAccountStorage,
             isRecord,
         }),
-        saveAccounts,
+        saveAccounts: async (storage) => {
+            // An explicit restore is a deliberate overwrite of the current
+            // primary, like the crash-recovery persists: record the file being
+            // replaced so the baseline-less-save guard neither misreports it as
+            // a foreign write nor spends the once-per-path warning on it.
+            notePrimaryState(getStoragePath(), await fs.stat(getStoragePath()).catch(() => undefined));
+            await saveAccounts(storage);
+        },
     });
 }
 export async function exportNamedBackup(name, options) {
@@ -508,15 +757,31 @@ async function migrateLegacyProjectStorageIfNeeded(options) {
     if (existingCandidatePaths.length === 0) {
         return null;
     }
-    const loadCurrentStorageForMigration = async () => loadNormalizedStorageFromPath(currentStoragePath, "current account storage", {
-        loadAccountsFromPath: (path) => loadAccountsFromPath(path, {
-            normalizeAccountStorage,
-            isRecord,
-        }),
-        logWarn: (message, details) => {
-            log.warn(message, details);
-        },
-    });
+    const loadCurrentStorageForMigration = async () => {
+        // Stat before the read so a migration persist of the merged content
+        // counts as a state this process knows (baseline-less-save guard).
+        // Recorded even when the parse fails: a migration persist that
+        // replaces an unreadable current file is a deliberate overwrite, not
+        // a foreign modification to warn about.
+        let stats;
+        try {
+            stats = await fs.stat(currentStoragePath);
+        }
+        catch {
+            stats = undefined;
+        }
+        const storage = await loadNormalizedStorageFromPath(currentStoragePath, "current account storage", {
+            loadAccountsFromPath: (path) => loadAccountsFromPath(path, {
+                normalizeAccountStorage,
+                isRecord,
+            }),
+            logWarn: (message, details) => {
+                log.warn(message, details);
+            },
+        });
+        notePrimaryState(currentStoragePath, stats);
+        return storage;
+    };
     const readLiveCurrentStorageIfExportMode = async () => {
         if (commit || !existsSync(currentStoragePath)) {
             return { exists: false, storage: null };
@@ -755,17 +1020,289 @@ export function resolveAccountSelectionIndex(accounts, candidate, fallbackIndex
         return matchedIndex;
     return clampIndex(fallbackIndex, accounts.length);
 }
+/**
+ * Total "newest" order over surviving entries, identical to folding
+ * selectNewestAccount left-to-right over the survivor array: higher
+ * `lastUsed` wins, then higher `addedAt`, then — the fold's behavior on a
+ * full tie — the later array position. Reducing the fold to one comparison
+ * over (lastUsed, addedAt, index) is what lets each identity lookup be
+ * answered from an incrementally maintained index instead of a linear scan.
+ */
+function compareDedupIndexEntries(a, b) {
+    if (a.lastUsed !== b.lastUsed)
+        return a.lastUsed - b.lastUsed;
+    if (a.addedAt !== b.addedAt)
+        return a.addedAt - b.addedAt;
+    return a.index - b.index;
+}
+/**
+ * Incremental "newest surviving owner" index for one identity facet value
+ * (a composite accountId+email pair, an email key, or a refresh token).
+ * Survivor slots join when appended, refresh their freshness when a
+ * newest-wins merge replaces the account stored in the slot, and leave when
+ * a replacement drops the facet. A max-heap with lazy deletion answers the
+ * argmax query in amortized O(log n): stale heap entries are popped on
+ * first sight, so every join/update/leave is paid for exactly once.
+ */
+class DedupNewestIndex {
+    liveEntries = new Map();
+    heap = [];
+    get size() {
+        return this.liveEntries.size;
+    }
+    set(index, account) {
+        const entry = {
+            index,
+            lastUsed: account.lastUsed || 0,
+            addedAt: account.addedAt || 0,
+        };
+        this.liveEntries.set(index, entry);
+        const heap = this.heap;
+        let slot = heap.length;
+        heap.push(entry);
+        while (slot > 0) {
+            const parent = (slot - 1) >> 1;
+            const parentEntry = heap[parent];
+            if (parentEntry === undefined ||
+                compareDedupIndexEntries(parentEntry, entry) >= 0) {
+                break;
+            }
+            heap[slot] = parentEntry;
+            slot = parent;
+        }
+        heap[slot] = entry;
+    }
+    delete(index) {
+        this.liveEntries.delete(index);
+    }
+    newestIndex() {
+        const heap = this.heap;
+        while (heap.length > 0) {
+            const top = heap[0];
+            if (top !== undefined && this.liveEntries.get(top.index) === top) {
+                return top.index;
+            }
+            this.dropHeapTop();
+        }
+        return undefined;
+    }
+    dropHeapTop() {
+        const heap = this.heap;
+        const last = heap.pop();
+        if (last === undefined || heap.length === 0)
+            return;
+        heap[0] = last;
+        let slot = 0;
+        for (;;) {
+            const left = slot * 2 + 1;
+            const right = left + 1;
+            let best = slot;
+            let bestEntry = heap[best] ?? last;
+            const leftEntry = left < heap.length ? heap[left] : undefined;
+            if (leftEntry !== undefined &&
+                compareDedupIndexEntries(leftEntry, bestEntry) > 0) {
+                best = left;
+                bestEntry = leftEntry;
+            }
+            const rightEntry = right < heap.length ? heap[right] : undefined;
+            if (rightEntry !== undefined &&
+                compareDedupIndexEntries(rightEntry, bestEntry) > 0) {
+                best = right;
+            }
+            if (best === slot)
+                break;
+            const slotEntry = heap[slot];
+            const bestValue = heap[best];
+            if (bestValue !== undefined)
+                heap[slot] = bestValue;
+            if (slotEntry !== undefined)
+                heap[best] = slotEntry;
+            slot = best;
+        }
+    }
+}
+function bumpIdentityCount(counts, key, delta) {
+    if (!key)
+        return;
+    const next = (counts.get(key) ?? 0) + delta;
+    if (next <= 0) {
+        counts.delete(key);
+    }
+    else {
+        counts.set(key, next);
+    }
+}
+function dedupCompositeKey(ref) {
+    if (!ref.accountId || !ref.emailKey)
+        return undefined;
+    // JSON encoding keeps the pair unambiguous even for adversarial strings.
+    return JSON.stringify([ref.accountId, ref.emailKey]);
+}
+/**
+ * One dedup pass in O(n log n): every candidate is matched against the
+ * surviving array through four incrementally maintained indexes (composite
+ * accountId+email, email, refresh token, accountId) that apply the same
+ * tier precedence and vetoes as the linear findMatchingAccountIndex scans
+ * they replace. A newest-wins replacement re-keys every index the loser
+ * owned, so the indexes always describe the current survivor array.
+ */
 function deduplicateAccountsByIdentityPass(accounts) {
     const deduplicated = [];
+    const refs = [];
+    const compositeIndexes = new Map();
+    const emailIndexes = new Map();
+    const refreshIndexes = new Map();
+    const accountIdOwners = new Map();
+    const addToIndexes = (index, account, ref) => {
+        const compositeKey = dedupCompositeKey(ref);
+        if (compositeKey !== undefined) {
+            let newest = compositeIndexes.get(compositeKey);
+            if (!newest) {
+                newest = new DedupNewestIndex();
+                compositeIndexes.set(compositeKey, newest);
+            }
+            newest.set(index, account);
+        }
+        if (ref.emailKey !== undefined) {
+            let bucket = emailIndexes.get(ref.emailKey);
+            if (!bucket) {
+                bucket = { newest: new DedupNewestIndex(), accountIds: new Map() };
+                emailIndexes.set(ref.emailKey, bucket);
+            }
+            bucket.newest.set(index, account);
+            bumpIdentityCount(bucket.accountIds, ref.accountId, 1);
+        }
+        if (ref.refreshToken !== undefined) {
+            let bucket = refreshIndexes.get(ref.refreshToken);
+            if (!bucket) {
+                bucket = {
+                    newest: new DedupNewestIndex(),
+                    accountIds: new Map(),
+                    emailKeys: new Map(),
+                };
+                refreshIndexes.set(ref.refreshToken, bucket);
+            }
+            bucket.newest.set(index, account);
+            bumpIdentityCount(bucket.accountIds, ref.accountId, 1);
+            bumpIdentityCount(bucket.emailKeys, ref.emailKey, 1);
+        }
+        if (ref.accountId !== undefined) {
+            let owners = accountIdOwners.get(ref.accountId);
+            if (!owners) {
+                owners = new Set();
+                accountIdOwners.set(ref.accountId, owners);
+            }
+            owners.add(index);
+        }
+    };
+    const removeFromIndexes = (index, ref) => {
+        const compositeKey = dedupCompositeKey(ref);
+        if (compositeKey !== undefined) {
+            compositeIndexes.get(compositeKey)?.delete(index);
+        }
+        if (ref.emailKey !== undefined) {
+            const bucket = emailIndexes.get(ref.emailKey);
+            if (bucket) {
+                bucket.newest.delete(index);
+                bumpIdentityCount(bucket.accountIds, ref.accountId, -1);
+            }
+        }
+        if (ref.refreshToken !== undefined) {
+            const bucket = refreshIndexes.get(ref.refreshToken);
+            if (bucket) {
+                bucket.newest.delete(index);
+                bumpIdentityCount(bucket.accountIds, ref.accountId, -1);
+                bumpIdentityCount(bucket.emailKeys, ref.emailKey, -1);
+            }
+        }
+        if (ref.accountId !== undefined) {
+            accountIdOwners.get(ref.accountId)?.delete(index);
+        }
+    };
     for (const account of accounts) {
         if (!account)
             continue;
-        const existingIndex = findMatchingAccountIndex(deduplicated, account);
+        const candidateRef = toAccountIdentityRef(account);
+        let existingIndex;
+        // Tier 1: composite accountId + email match.
+        if (candidateRef.accountId && candidateRef.emailKey) {
+            const compositeKey = dedupCompositeKey(candidateRef);
+            if (compositeKey !== undefined) {
+                existingIndex = compositeIndexes.get(compositeKey)?.newestIndex();
+            }
+        }
+        // Tier 2: safe email match. Refuse when the email's owners plus the
+        // candidate carry more than one distinct accountId.
+        if (existingIndex === undefined && candidateRef.emailKey) {
+            const bucket = emailIndexes.get(candidateRef.emailKey);
+            if (bucket && bucket.newest.size > 0) {
+                const distinctAccountIds = bucket.accountIds.size +
+                    (candidateRef.accountId &&
+                        !bucket.accountIds.has(candidateRef.accountId)
+                        ? 1
+                        : 0);
+                if (distinctAccountIds <= 1) {
+                    existingIndex = bucket.newest.newestIndex();
+                }
+            }
+        }
+        // Tier 3: compatible refresh-token match. Refuse on an owner whose
+        // accountId or emailKey conflicts with the candidate's, and on an
+        // ambiguous refresh-only candidate with more than one owner.
+        if (existingIndex === undefined && candidateRef.refreshToken) {
+            const bucket = refreshIndexes.get(candidateRef.refreshToken);
+            if (bucket && bucket.newest.size > 0) {
+                const accountIdConflict = candidateRef.accountId !== undefined &&
+                    (bucket.accountIds.size > 1 ||
+                        (bucket.accountIds.size === 1 &&
+                            !bucket.accountIds.has(candidateRef.accountId)));
+                const emailKeyConflict = candidateRef.emailKey !== undefined &&
+                    (bucket.emailKeys.size > 1 ||
+                        (bucket.emailKeys.size === 1 &&
+                            !bucket.emailKeys.has(candidateRef.emailKey)));
+                const ambiguous = candidateRef.accountId === undefined &&
+                    candidateRef.emailKey === undefined &&
+                    bucket.newest.size > 1;
+                if (!accountIdConflict && !emailKeyConflict && !ambiguous) {
+                    existingIndex = bucket.newest.newestIndex();
+                }
+            }
+        }
+        // Tier 4: unique-accountId fallback. The dedup pass runs
+        // findMatchingAccountIndex with default options, so the fallback is
+        // only reachable for candidates that also carry an email key; a sole
+        // owner still loses on a conflicting email key.
+        if (existingIndex === undefined &&
+            candidateRef.accountId &&
+            candidateRef.emailKey) {
+            const owners = accountIdOwners.get(candidateRef.accountId);
+            if (owners && owners.size === 1) {
+                const only = owners.values().next();
+                if (!only.done) {
+                    const ownerEmailKey = refs[only.value]?.emailKey;
+                    if (ownerEmailKey === undefined ||
+                        ownerEmailKey === candidateRef.emailKey) {
+                        existingIndex = only.value;
+                    }
+                }
+            }
+        }
         if (existingIndex === undefined) {
+            const index = deduplicated.length;
             deduplicated.push(account);
+            refs.push(candidateRef);
+            addToIndexes(index, account, candidateRef);
             continue;
         }
-        deduplicated[existingIndex] = selectNewestAccount(deduplicated[existingIndex], account);
+        const current = deduplicated[existingIndex];
+        if (selectNewestAccount(current, account) === current)
+            continue;
+        deduplicated[existingIndex] = account;
+        const previousRef = refs[existingIndex];
+        refs[existingIndex] = candidateRef;
+        if (previousRef)
+            removeFromIndexes(existingIndex, previousRef);
+        addToIndexes(existingIndex, account, candidateRef);
     }
     return deduplicated;
 }
@@ -1266,11 +1803,25 @@ async function loadAccountsInternal(persistMigration) {
     const migratedLegacyStorage = persistMigration
         ? await migrateLegacyProjectStorageIfNeeded({ persist: persistMigration })
         : null;
+    // Stat BEFORE the primary read: this fingerprint is the state this process
+    // can claim to know. A writer racing the read makes the record stale, which
+    // is the safe direction for the baseline-less-save guard — never claim
+    // knowledge of content we may not have parsed.
+    let primaryStatsBeforeRead;
+    try {
+        primaryStatsBeforeRead = await fs.stat(path);
+    }
+    catch {
+        primaryStatsBeforeRead = undefined;
+    }
     try {
-        const { normalized, storedVersion, schemaErrors } = await loadAccountsFromPath(path, {
+        const { normalized, storedVersion, schemaErrors, contentSha256 } = await loadAccountsFromPath(path, {
             normalizeAccountStorage,
             isRecord,
         });
+        if (normalized) {
+            notePrimaryState(path, primaryStatsBeforeRead, contentSha256);
+        }
         if (schemaErrors.length > 0) {
             log.warn("Account storage schema validation warnings", {
                 errors: schemaErrors.slice(0, 5),
@@ -1348,6 +1899,12 @@ async function loadAccountsInternal(persistMigration) {
         return normalized;
     }
     catch (error) {
+        // The primary could not be parsed (or read). Whatever file we stat'd is
+        // the state the WAL/backup recovery persists below deliberately replace,
+        // so record it as known — otherwise those intentional recovery saves
+        // would emit the baseline-less-overwrite warning and spend the
+        // once-per-path guard meant for genuine foreign writes.
+        notePrimaryState(path, primaryStatsBeforeRead);
         const code = error.code;
         if (existsSync(resetMarkerPath)) {
             return createEmptyStorageWithMetadata(false, "intentional-reset");
@@ -1467,14 +2024,17 @@ async function loadAccountsForExport() {
         throw error;
     }
 }
-async function saveAccountsUnlocked(storage) {
-    await saveAccountsUnlockedToDisk(storage);
-    // A persisted (or superseded) pending rotated credential is no longer needed.
-    await prunePendingAuth(getStoragePath(), storage).catch((error) => {
+async function saveAccountsUnlocked(storage, options) {
+    await saveAccountsUnlockedToDisk(storage, options);
+    // A persisted (or superseded) pending rotated credential is no longer needed —
+    // unless a restorable backup/WAL snapshot still carries the token it replaces,
+    // in which case the entry stays so a stale-backup recovery self-heals.
+    const path = getStoragePath();
+    await prunePendingAuth(path, storage, () => collectRestorableRefreshTokens(path)).catch((error) => {
         log.warn("Failed to prune pending rotated credentials", { code: typeof error.code === "string" && /^[A-Z_]{1,40}$/.test(error.code ?? "") ? error.code : "INVALID_PENDING_AUTH" });
     });
 }
-async function saveAccountsUnlockedToDisk(storage) {
+async function saveAccountsUnlockedToDisk(storage, options) {
     const path = getStoragePath();
     const resetMarkerPath = getIntentionalResetMarkerPath(path);
     const walPath = getAccountsWalPath(path);
@@ -1513,7 +2073,7 @@ async function saveAccountsUnlockedToDisk(storage) {
             },
         }),
         createSyntheticFixtureError: () => new StorageError("Refusing to overwrite non-synthetic account storage with synthetic fixture payload", "EINVALID", path, "Detected synthetic fixture-like account payload. Use explicit account import/login commands instead."),
-        createRotatingAccountsBackup,
+        createRotatingAccountsBackup: (targetPath) => rotateAccountsBackupIfDue(targetPath, storage.accounts, options?.expectedOnDiskAccounts),
         computeSha256,
         writeJournal: async (content, journalPath) => {
             const journalEntry = {
@@ -1571,8 +2131,9 @@ async function saveAccountsUnlockedToDisk(storage) {
                 // Ignore cleanup failure.
             }
         },
-        onSaved: () => {
+        onSaved: (stats, contentSha256) => {
             lastAccountsSaveTimestamp = Date.now();
+            notePrimaryState(path, stats, contentSha256);
         },
         logWarn: (message, details) => {
             log.warn(message, details);
@@ -1648,14 +2209,18 @@ export async function withAccountAndFlaggedStorageTransaction(handler) {
             const baseline = loadedAccountSnapshots.get(accountStorage);
             const nextAccounts = cloneAccountStorageForPersistence(baseline ? mergeAccountSnapshot(baseline, state.snapshot, accountStorage) : accountStorage);
             const nextFlagged = cloneFlaggedStorageForPersistence(flaggedStorage);
-            await saveAccountsUnlocked(nextAccounts);
+            await saveAccountsUnlocked(nextAccounts, {
+                expectedOnDiskAccounts: state.snapshot?.accounts,
+            });
             try {
                 await saveFlaggedAccountsUnlocked(nextFlagged);
                 state.snapshot = nextAccounts;
             }
             catch (error) {
                 try {
-                    await saveAccountsUnlocked(previousAccounts);
+                    await saveAccountsUnlocked(previousAccounts, {
+                        expectedOnDiskAccounts: state.snapshot?.accounts,
+                    });
                     state.snapshot = previousAccounts;
                 }
                 catch (rollbackError) {
@@ -1709,7 +2274,21 @@ export async function withFlaggedStorageTransaction(handler) {
  * @param storage - Account storage data to save
  * @throws StorageError with platform-aware hints on failure
  */
-/** Clone a loaded working snapshot without losing its optimistic-concurrency baseline. */
+/**
+ * Clone a loaded working snapshot without losing its optimistic-concurrency baseline.
+ *
+ * Baseline contract: `saveAccounts` only runs the three-way merge
+ * (`mergeAccountSnapshot` against a fresh `loadPrimaryAccountsForMerge` read)
+ * when the saved object is registered in `loadedAccountSnapshots` — and that
+ * WeakMap is keyed by OBJECT IDENTITY, so registration does not survive
+ * `structuredClone`, `JSON.parse(JSON.stringify(...))`, spread copies, or
+ * manual reconstruction. A baseline-less save writes the object as-is
+ * (last-writer-wins): concurrent changes are neither merged nor flagged with
+ * ESTALE, and when the primary on disk differs from the state this process
+ * last read or wrote the save additionally emits a one-time baseline-less
+ * overwrite warning. Use this helper — or mutate the loaded object in place —
+ * to keep the merge armed.
+ */
 export function cloneTrackedAccountStorage(storage) {
     const clone = structuredClone(storage);
     const baseline = loadedAccountSnapshots.get(storage);
@@ -1723,8 +2302,16 @@ export async function saveAccounts(storage) {
         withStorageLock,
         saveUnlocked: async (proposed) => {
             const baseline = loadedAccountSnapshots.get(proposed);
-            const snapshot = baseline ? mergeAccountSnapshot(baseline, await loadPrimaryAccountsForMerge(), proposed) : proposed;
-            await saveAccountsUnlocked(snapshot);
+            const current = baseline ? await loadPrimaryAccountsForMerge() : null;
+            if (!baseline) {
+                // Without a baseline the three-way merge cannot run — this write is
+                // last-writer-wins. Warn (once) if the primary changed underneath us.
+                await warnOnBaselinelessSave(getStoragePath());
+            }
+            const snapshot = baseline ? mergeAccountSnapshot(baseline, current, proposed) : proposed;
+            await saveAccountsUnlocked(snapshot, {
+                expectedOnDiskAccounts: current?.accounts,
+            });
             if (baseline) {
                 for (const key of Object.keys(proposed))
                     Reflect.deleteProperty(proposed, key);