codex-multi-auth 2.17.0 → 2.17.3

package/dist/lib/storage/gitignore.d.ts

@@ -4,4 +4,3 @@ export declare function ensureCodexGitignoreEntry(params: {
     logDebug: (message: string, details: Record<string, unknown>) => void;
     logWarn: (message: string, details: Record<string, unknown>) => void;
 }): Promise<void>;
-//# sourceMappingURL=gitignore.d.ts.map

package/dist/lib/storage/hash.d.ts

@@ -1,2 +1 @@
 export declare function computeSha256(value: string): string;
-//# sourceMappingURL=hash.d.ts.map

package/dist/lib/storage/health.d.ts

@@ -19,4 +19,3 @@ export declare function createStorageHealthSummary(params: {
     schemaErrors?: string[];
     recoverySource?: "wal";
 }): StorageHealthSummary;
-//# sourceMappingURL=health.d.ts.map

package/dist/lib/storage/identity.d.ts

@@ -18,4 +18,3 @@ export declare function toAccountIdentityRef(account: Pick<AccountLike, "account
 export declare function getAccountIdentityKey(account: Pick<AccountLike, "accountId" | "email" | "refreshToken">): string | undefined;
 export declare function getRuntimeAccountIdentityKey(account: Pick<RuntimeAccountLike, "accountId" | "email" | "index">): string | number | undefined;
 export {};
-//# sourceMappingURL=identity.d.ts.map

package/dist/lib/storage/import-export.d.ts

@@ -22,4 +22,3 @@ export declare function mergeImportedAccounts(params: {
     total: number;
     skipped: number;
 };
-//# sourceMappingURL=import-export.d.ts.map

package/dist/lib/storage/json-store-lock.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Stamp `updatedAt` for a per-key governance entry with a hybrid logical
+ * floor: when the wall clock regressed below the timestamp the entry being
+ * overwritten already carries, stamp `prior + 1` instead of `now`. Every
+ * upsert-only store merges with `updatedAt >=`, so a backward clock jump
+ * would otherwise stamp a semantically-newer write below its own
+ * predecessor and the merge would silently drop it. Equal or forward wall
+ * times pass through unchanged — ties already resolve to the caller's
+ * write under `>=`.
+ *
+ * `prior` is the entry the writer saw, which can trail the freshest on-disk
+ * entry when a concurrent writer lands between the caller's load and its
+ * save; baseline-aware save merges re-apply this same floor against the
+ * on-disk entry at merge time so the edit still cannot be lost.
+ */
+export declare function stampUpdatedAt(now: number, prior: number | undefined): number;
+/**
+ * Serialize `task` behind the previous write queued for `path`, so same-file
+ * writers inside this process run one at a time in submission order. A failed
+ * predecessor never blocks or fails successors. Re-entrant for the same path
+ * within one async context.
+ *
+ * This is the per-path generalization of the module-local `writeQueue`
+ * variables the governance stores used to keep by hand.
+ */
+export declare function withJsonStoreWriteQueue<T>(path: string, task: () => Promise<T>): Promise<T>;
+/** Test helper: drop queued-write bookkeeping (all paths, or one when given). */
+export declare function resetJsonStoreWriteQueuesForTests(path?: string): void;
+/**
+ * Stat `filePath` for its mtime with bounded transient-FS retry (the save
+ * path is Windows-sensitive: a single transient EBUSY/EPERM/EAGAIN from an
+ * AV/indexer lock must not abort the whole save). ENOENT returns `null`
+ * immediately; on exhaustion the last failure surfaces so the caller treats
+ * it as a real save error rather than a phantom missing file.
+ */
+export declare function getJsonStoreFileMtimeMs(filePath: string): Promise<number | null>;
+/**
+ * The `ESTALE` signal used by the CAS retry loop: the file's mtime moved
+ * between the caller's stat and its write, so the attempt must re-read and
+ * re-merge against the latest on-disk state instead of clobbering it.
+ */
+export declare function createJsonStoreStaleError(filePath: string): NodeJS.ErrnoException;
+/**
+ * Throw `ESTALE` when `filePath`'s current mtime differs from
+ * `expectedMtimeMs` (`null` means "file must still be absent"). Writers that
+ * keep their own temp+rename flow call this just before the rename, matching
+ * {@link writeJsonStoreFileAtomicWithRetry}'s inline check.
+ */
+export declare function assertJsonStoreFileMtimeUnchanged(filePath: string, expectedMtimeMs: number | null): Promise<void>;
+export interface JsonStoreAtomicWriteOptions {
+    /**
+     * When present (including explicit `null` = "expect the file to be
+     * absent"), compare-and-swap guard: abort with `ESTALE` if the target's
+     * mtime moved since the caller read it, so the caller can re-read and
+     * merge instead of clobbering a concurrent write. Omit the key entirely
+     * to skip the check.
+     */
+    expectedMtimeMs?: number | null;
+    /** Temp file mode (and therefore the final file's mode when created). */
+    mode?: number;
+    /** fsync the temp file before rename so a crash/power-loss cannot leave a truncated store. */
+    fsync?: boolean;
+    /** Rename retry codes; defaults to EBUSY/EPERM. */
+    retryableCodes?: ReadonlySet<string>;
+}
+/**
+ * Atomic JSON write: serialize `payload` pretty-printed with a trailing
+ * newline to a crypto-random sibling temp file, then rename it over
+ * `filePath` with bounded transient-FS retry. Optionally CAS-checks the
+ * target mtime first and fsyncs the temp file; on failure the temp is
+ * removed best-effort.
+ */
+export declare function writeJsonStoreFileAtomicWithRetry(filePath: string, payload: unknown, options?: JsonStoreAtomicWriteOptions): Promise<void>;
+/**
+ * Run `task`, retrying `ESTALE` CAS aborts so each attempt can re-read and
+ * re-merge against the latest on-disk state (matches the config save loop:
+ * 3 attempts, immediate retry, ESTALE-only).
+ */
+export declare function withJsonStoreCasRetry<T>(task: () => Promise<T>): Promise<T>;
+export interface JsonStoreFileLockOptions {
+    /**
+     * How long to wait for a lock held by a LIVE foreign process before
+     * failing with `ELOCKTIMEOUT` (default 10s). A crashed holder's lock is
+     * reclaimed as soon as its dead PID is observed; a live holder is never
+     * evicted — including a reused PID, which fails closed here rather than
+     * risking two writers in the critical section.
+     */
+    waitTimeoutMs?: number;
+}
+/**
+ * Cross-process mutex for a JSON store file, delegated to the proven
+ * candidate-directory transaction lock in lib/storage/file-lock.ts: each
+ * acquirer stages `<path>.write-lock.candidate-*` containing its unique
+ * `<host>.<pid>.<uuid>` owner file, then publishes it with a single atomic
+ * `rename` (which only succeeds while the lock directory is absent or empty,
+ * so there is no ownerless acquisition window). A crashed holder's lock is
+ * recovered by unlinking exactly that dead owner's unique filename and
+ * removing the directory only while it is still empty — an `rmdir` can never
+ * erase a lock that was republished in the meantime, so takeover can never
+ * delete another owner's live lock. Waiters on a live holder retry inside
+ * `waitTimeoutMs` (default 10s), then this wrapper surfaces the exhaustion
+ * as `ELOCKTIMEOUT`. Re-entrant for the same resolved path within one async
+ * context.
+ */
+export declare function withJsonStoreFileLock<T>(targetPath: string, task: () => Promise<T>, options?: JsonStoreFileLockOptions): Promise<T>;

package/dist/lib/storage/json-store-lock.js

@@ -0,0 +1,259 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { promises as fs } from "node:fs";
+import { dirname } from "node:path";
+import { withRetry } from "../fs-retry.js";
+import { tempPathFor } from "../temp-path.js";
+import { withFileTransactionLock } from "./file-lock.js";
+/**
+ * Shared concurrency machinery for the file-backed governance JSON stores
+ * (config, unified settings, budget guards, routing profiles, account
+ * policies, local client tokens, quota cache).
+ *
+ * Three cooperating guards, extracted from lib/config.ts's save path so every
+ * store gets the same semantics instead of each re-deriving a subset:
+ *
+ * 1. {@link withJsonStoreWriteQueue} — a per-path in-process promise queue
+ *    that serializes writers inside this process (replaces each store's
+ *    hand-rolled `writeQueue` module variable).
+ * 2. {@link withJsonStoreFileLock} — a cross-process lock directory
+ *    (`<path>.write-lock`) delegated to {@link withFileTransactionLock}: a
+ *    pre-populated candidate directory is published by atomic rename, and a
+ *    crashed holder's lock is recovered only when its owner PID is dead —
+ *    live holders are NEVER evicted, so a takeover can never unlink a newly
+ *    acquired lock (the stale-check→unlink TOCTOU that a single lockfile
+ *    cannot close: POSIX has no delete-if-unchanged primitive, and renaming
+ *    the file aside leaves an empty path another `wx` create can claim).
+ *    The promise queue only serializes THIS process; the lock directory
+ *    closes the read→check→merge→rename TOCTOU window against OTHER
+ *    processes. Re-entrant within one async context so a nested write on the
+ *    same path cannot deadlock itself.
+ * 3. mtime compare-and-swap — {@link getJsonStoreFileMtimeMs} /
+ *    {@link assertJsonStoreFileMtimeUnchanged} /
+ *    {@link writeJsonStoreFileAtomicWithRetry} plus
+ *    {@link withJsonStoreCasRetry}: each attempt re-stats, re-reads, and
+ *    re-merges against the latest on-disk state before writing, aborting with
+ *    `ESTALE` when another writer moved the file under us. This stays on as a
+ *    second-line guard for writers that do not take the lockfile.
+ *
+ * Storage layer: this module sits below the governance stores (which live in
+ * lib/ root) and below lib/config.ts; it must only depend on leaf utilities.
+ */
+const JSON_STORE_WRITE_RETRY_CODES = new Set(["EBUSY", "EPERM"]);
+const JSON_STORE_READ_RETRY_CODES = new Set(["EBUSY", "EPERM", "EAGAIN"]);
+const JSON_STORE_CAS_MAX_ATTEMPTS = 3;
+/**
+ * Stamp `updatedAt` for a per-key governance entry with a hybrid logical
+ * floor: when the wall clock regressed below the timestamp the entry being
+ * overwritten already carries, stamp `prior + 1` instead of `now`. Every
+ * upsert-only store merges with `updatedAt >=`, so a backward clock jump
+ * would otherwise stamp a semantically-newer write below its own
+ * predecessor and the merge would silently drop it. Equal or forward wall
+ * times pass through unchanged — ties already resolve to the caller's
+ * write under `>=`.
+ *
+ * `prior` is the entry the writer saw, which can trail the freshest on-disk
+ * entry when a concurrent writer lands between the caller's load and its
+ * save; baseline-aware save merges re-apply this same floor against the
+ * on-disk entry at merge time so the edit still cannot be lost.
+ */
+export function stampUpdatedAt(now, prior) {
+    return typeof prior === "number" && Number.isFinite(prior) && now < prior
+        ? prior + 1
+        : now;
+}
+// ---------------------------------------------------------------------------
+// 1. Per-path in-process write queue
+// ---------------------------------------------------------------------------
+const jsonStoreWriteQueues = new Map();
+// Async-local re-entrancy map for the write queue (keyed by the raw path
+// string, matching the queue key): a nested withJsonStoreWriteQueue on the
+// same path inside one async context runs inside the outer critical section
+// instead of deadlocking on its own queue slot — e.g. config.ts wraps
+// saveUnifiedPluginConfig (which queues on settings.json) in an outer queue
+// for the same path.
+const jsonStoreQueueLeases = new AsyncLocalStorage();
+/**
+ * Serialize `task` behind the previous write queued for `path`, so same-file
+ * writers inside this process run one at a time in submission order. A failed
+ * predecessor never blocks or fails successors. Re-entrant for the same path
+ * within one async context.
+ *
+ * This is the per-path generalization of the module-local `writeQueue`
+ * variables the governance stores used to keep by hand.
+ */
+export async function withJsonStoreWriteQueue(path, task) {
+    const held = jsonStoreQueueLeases.getStore();
+    if (held?.get(path)?.active) {
+        return task();
+    }
+    const previous = jsonStoreWriteQueues.get(path) ?? Promise.resolve();
+    const lease = { active: true };
+    const context = new Map(held);
+    context.set(path, lease);
+    const queued = previous.catch(() => { }).then(async () => {
+        try {
+            return await jsonStoreQueueLeases.run(context, task);
+        }
+        finally {
+            lease.active = false;
+        }
+    });
+    // Store the settled (never-rejecting) wrapper so successors chain cleanly;
+    // keep the reference for the same-object check below.
+    const stored = queued.then(() => undefined, () => undefined);
+    jsonStoreWriteQueues.set(path, stored);
+    try {
+        return await queued;
+    }
+    finally {
+        if (jsonStoreWriteQueues.get(path) === stored) {
+            jsonStoreWriteQueues.delete(path);
+        }
+    }
+}
+/** Test helper: drop queued-write bookkeeping (all paths, or one when given). */
+export function resetJsonStoreWriteQueuesForTests(path) {
+    if (path !== undefined) {
+        jsonStoreWriteQueues.delete(path);
+        return;
+    }
+    jsonStoreWriteQueues.clear();
+}
+// ---------------------------------------------------------------------------
+// 2. mtime compare-and-swap + atomic JSON write
+// ---------------------------------------------------------------------------
+/**
+ * Stat `filePath` for its mtime with bounded transient-FS retry (the save
+ * path is Windows-sensitive: a single transient EBUSY/EPERM/EAGAIN from an
+ * AV/indexer lock must not abort the whole save). ENOENT returns `null`
+ * immediately; on exhaustion the last failure surfaces so the caller treats
+ * it as a real save error rather than a phantom missing file.
+ */
+export async function getJsonStoreFileMtimeMs(filePath) {
+    return withRetry(async () => {
+        try {
+            return (await fs.stat(filePath)).mtimeMs;
+        }
+        catch (error) {
+            if (error?.code === "ENOENT") {
+                return null;
+            }
+            throw error;
+        }
+    }, {
+        maxAttempts: 5,
+        backoffMs: (attempt) => 10 * 2 ** (attempt - 1),
+        retryableCodes: JSON_STORE_READ_RETRY_CODES,
+    });
+}
+/**
+ * The `ESTALE` signal used by the CAS retry loop: the file's mtime moved
+ * between the caller's stat and its write, so the attempt must re-read and
+ * re-merge against the latest on-disk state instead of clobbering it.
+ */
+export function createJsonStoreStaleError(filePath) {
+    const staleError = new Error(`JSON store at ${filePath} changed on disk during save; retrying with latest state.`);
+    staleError.code = "ESTALE";
+    return staleError;
+}
+/**
+ * Throw `ESTALE` when `filePath`'s current mtime differs from
+ * `expectedMtimeMs` (`null` means "file must still be absent"). Writers that
+ * keep their own temp+rename flow call this just before the rename, matching
+ * {@link writeJsonStoreFileAtomicWithRetry}'s inline check.
+ */
+export async function assertJsonStoreFileMtimeUnchanged(filePath, expectedMtimeMs) {
+    const currentMtimeMs = await getJsonStoreFileMtimeMs(filePath);
+    if (currentMtimeMs !== expectedMtimeMs) {
+        throw createJsonStoreStaleError(filePath);
+    }
+}
+/**
+ * Atomic JSON write: serialize `payload` pretty-printed with a trailing
+ * newline to a crypto-random sibling temp file, then rename it over
+ * `filePath` with bounded transient-FS retry. Optionally CAS-checks the
+ * target mtime first and fsyncs the temp file; on failure the temp is
+ * removed best-effort.
+ */
+export async function writeJsonStoreFileAtomicWithRetry(filePath, payload, options) {
+    const tempPath = tempPathFor(filePath);
+    await fs.mkdir(dirname(filePath), { recursive: true });
+    const handle = await fs.open(tempPath, "w", options?.mode);
+    try {
+        await handle.writeFile(`${JSON.stringify(payload, null, 2)}\n`, "utf8");
+        if (options?.fsync) {
+            await handle.sync();
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    let renamed = false;
+    try {
+        if (options && "expectedMtimeMs" in options) {
+            await assertJsonStoreFileMtimeUnchanged(filePath, options.expectedMtimeMs ?? null);
+        }
+        await withRetry(() => fs.rename(tempPath, filePath), {
+            maxAttempts: 5,
+            backoffMs: (attempt) => 10 * 2 ** (attempt - 1),
+            retryableCodes: options?.retryableCodes ?? JSON_STORE_WRITE_RETRY_CODES,
+        });
+        renamed = true;
+    }
+    finally {
+        if (!renamed) {
+            try {
+                await fs.unlink(tempPath);
+            }
+            catch {
+                // Best-effort temp cleanup.
+            }
+        }
+    }
+}
+/**
+ * Run `task`, retrying `ESTALE` CAS aborts so each attempt can re-read and
+ * re-merge against the latest on-disk state (matches the config save loop:
+ * 3 attempts, immediate retry, ESTALE-only).
+ */
+export async function withJsonStoreCasRetry(task) {
+    return withRetry(task, {
+        maxAttempts: JSON_STORE_CAS_MAX_ATTEMPTS,
+        backoffMs: 0,
+        retryableCodes: ["ESTALE"],
+    });
+}
+// ---------------------------------------------------------------------------
+// 3. Cross-process lockfile
+// ---------------------------------------------------------------------------
+const JSON_STORE_LOCK_WAIT_TIMEOUT_MS = 10_000;
+/**
+ * Cross-process mutex for a JSON store file, delegated to the proven
+ * candidate-directory transaction lock in lib/storage/file-lock.ts: each
+ * acquirer stages `<path>.write-lock.candidate-*` containing its unique
+ * `<host>.<pid>.<uuid>` owner file, then publishes it with a single atomic
+ * `rename` (which only succeeds while the lock directory is absent or empty,
+ * so there is no ownerless acquisition window). A crashed holder's lock is
+ * recovered by unlinking exactly that dead owner's unique filename and
+ * removing the directory only while it is still empty — an `rmdir` can never
+ * erase a lock that was republished in the meantime, so takeover can never
+ * delete another owner's live lock. Waiters on a live holder retry inside
+ * `waitTimeoutMs` (default 10s), then this wrapper surfaces the exhaustion
+ * as `ELOCKTIMEOUT`. Re-entrant for the same resolved path within one async
+ * context.
+ */
+export async function withJsonStoreFileLock(targetPath, task, options) {
+    try {
+        return await withFileTransactionLock(targetPath, task, {
+            waitMs: options?.waitTimeoutMs ?? JSON_STORE_LOCK_WAIT_TIMEOUT_MS,
+        });
+    }
+    catch (error) {
+        if (error?.code === "ELOCKED") {
+            const timeoutError = new Error(`Timed out acquiring JSON store lock at ${targetPath}.`);
+            timeoutError.code = "ELOCKTIMEOUT";
+            throw timeoutError;
+        }
+        throw error;
+    }
+}

package/dist/lib/storage/metadata-section.d.ts

@@ -13,4 +13,3 @@ export declare function buildMetadataSection<TSnapshot extends {
     validSnapshotCount: number;
     snapshots: TSnapshot[];
 };
-//# sourceMappingURL=metadata-section.d.ts.map

package/dist/lib/storage/migrations.d.ts

@@ -33,4 +33,3 @@ export interface AccountStorageV1 {
 }
 export declare function migrateV1ToV3(v1: AccountStorageV1): AccountStorageV3;
 export {};
-//# sourceMappingURL=migrations.d.ts.map

package/dist/lib/storage/migrations.js

@@ -7,38 +7,51 @@
  * ./public-types.ts.
  */
 import { MODEL_FAMILIES } from "../request/helpers/model-map.js";
+import { isRecord } from "./record-utils.js";
 function nowMs() {
     return Date.now();
 }
 export function migrateV1ToV3(v1) {
     const now = nowMs();
+    const rawActiveIndexByFamily = isRecord(v1.activeIndexByFamily)
+        ? v1
+            .activeIndexByFamily
+        : {};
     return {
         version: 3,
-        accounts: v1.accounts.map((account) => {
+        accounts: v1.accounts
+            .filter((account) => account !== null && typeof account === "object")
+            .map((account) => {
+            const { rateLimitResetTime, rateLimitResetTimes: existingResets, ...passthrough } = account;
+            // A pre-existing V3 map wins per key; the legacy scalar only fills
+            // families the map does not already cover.
             const rateLimitResetTimes = {};
-            if (typeof account.rateLimitResetTime === "number" && account.rateLimitResetTime > now) {
+            if (isRecord(existingResets)) {
+                for (const [family, value] of Object.entries(existingResets)) {
+                    if (typeof value === "number") {
+                        rateLimitResetTimes[family] = value;
+                    }
+                }
+            }
+            if (typeof rateLimitResetTime === "number" && rateLimitResetTime > now) {
                 for (const family of MODEL_FAMILIES) {
-                    rateLimitResetTimes[family] = account.rateLimitResetTime;
+                    rateLimitResetTimes[family] ??= rateLimitResetTime;
                 }
             }
             return {
-                accountId: account.accountId,
-                accountIdSource: account.accountIdSource,
-                accountLabel: account.accountLabel,
-                email: account.email,
-                refreshToken: account.refreshToken,
-                accessToken: account.accessToken,
-                expiresAt: account.expiresAt,
-                enabled: account.enabled,
-                addedAt: account.addedAt,
-                lastUsed: account.lastUsed,
-                lastSwitchReason: account.lastSwitchReason,
-                rateLimitResetTimes: Object.keys(rateLimitResetTimes).length > 0 ? rateLimitResetTimes : undefined,
-                coolingDownUntil: account.coolingDownUntil,
-                cooldownReason: account.cooldownReason,
+                ...passthrough,
+                rateLimitResetTimes: Object.keys(rateLimitResetTimes).length > 0
+                    ? rateLimitResetTimes
+                    : undefined,
             };
         }),
         activeIndex: v1.activeIndex,
-        activeIndexByFamily: Object.fromEntries(MODEL_FAMILIES.map((family) => [family, v1.activeIndex])),
+        activeIndexByFamily: Object.fromEntries(MODEL_FAMILIES.map((family) => {
+            const perFamily = rawActiveIndexByFamily[family];
+            return [
+                family,
+                typeof perFamily === "number" ? perFamily : v1.activeIndex,
+            ];
+        })),
     };
 }

package/dist/lib/storage/named-backup-entry.d.ts

@@ -12,4 +12,3 @@ export declare function exportNamedBackupEntry(params: {
     getStoragePath: () => string;
     exportAccounts: (filePath: string, force?: boolean, beforeCommit?: (resolvedPath: string) => Promise<void> | void) => Promise<void>;
 }): Promise<string>;
-//# sourceMappingURL=named-backup-entry.d.ts.map

package/dist/lib/storage/named-backups-entry.d.ts

@@ -16,4 +16,3 @@ export declare function getNamedBackupsEntry(params: {
     }>;
     logDebug: (message: string, details: Record<string, unknown>) => void;
 }): Promise<NamedBackupSummary[]>;
-//# sourceMappingURL=named-backups-entry.d.ts.map

package/dist/lib/storage/named-backups.d.ts

@@ -12,4 +12,3 @@ export declare function collectNamedBackups(storagePath: string, deps: {
     }>;
     logDebug: (message: string, details: Record<string, unknown>) => void;
 }): Promise<NamedBackupSummary[]>;
-//# sourceMappingURL=named-backups.d.ts.map

package/dist/lib/storage/path-state.d.ts

@@ -10,4 +10,3 @@ export declare function setStoragePathDirectState(state: StoragePathState): void
 export declare function runWithStoragePathState<T>(state: StoragePathState, fn: () => T | Promise<T>): Promise<T>;
 /** Temporarily use the shared pool without mutating the caller or sibling async scopes. */
 export declare function runWithGlobalStoragePath<T>(fn: () => T | Promise<T>): Promise<T>;
-//# sourceMappingURL=path-state.d.ts.map

package/dist/lib/storage/paths.d.ts

@@ -59,4 +59,3 @@ export declare function resolveProjectStorageIdentityRoot(projectRoot: string):
 export declare function isProjectDirectory(dir: string): boolean;
 export declare function findProjectRoot(startDir: string): string | null;
 export declare function resolvePath(filePath: string): string;
-//# sourceMappingURL=paths.d.ts.map

package/dist/lib/storage/pending-auth.d.ts

@@ -3,6 +3,7 @@ export declare function getPendingAuthPath(storagePath: string): string;
 /** Record a rotated credential beside the account pool. */
 export declare function recordPendingAuth(storagePath: string, auth: {
     priorRefreshToken: string;
+    recordId?: string;
     refreshToken: string;
     accessToken: string;
     expiresAt: number;
@@ -10,8 +11,14 @@ export declare function recordPendingAuth(storagePath: string, auth: {
 }): Promise<void>;
 /** Overlay pending rotated credentials on rows that still hold the spent token. */
 export declare function applyPendingAuth(storagePath: string, storage: AccountStorageV3 | null): Promise<AccountStorageV3 | null>;
-/** After a save, drop entries whose spent token is no longer on disk (persisted or superseded). */
-export declare function prunePendingAuth(storagePath: string, saved: AccountStorageV3): Promise<void>;
+/**
+ * After a save, drop entries whose spent token is no longer in any restorable
+ * state. `saved` is the primary content just persisted; callers may also
+ * supply `restorableRefreshTokens` — refresh tokens still present in recovery
+ * sources (rotating/discovered backups, a WAL payload) — since a restore can
+ * resurface a spent token, its entry must survive until no source holds it.
+ * A scan failure keeps every entry: retention is the safe direction.
+ */
+export declare function prunePendingAuth(storagePath: string, saved: AccountStorageV3, restorableRefreshTokens?: () => Promise<Iterable<string>>): Promise<void>;
 /** Coordinate resets with pending credential writers, including Windows rename locks. */
 export declare function clearPendingAuth(storagePath: string): Promise<void>;
-//# sourceMappingURL=pending-auth.d.ts.map

package/dist/lib/storage/pending-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pending-auth.d.ts","sourceRoot":"","sources":["../../../lib/storage/pending-auth.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAyB1D,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAmCD,2DAA2D;AAC3D,wBAAsB,iBAAiB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3G,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED,mFAAmF;AACnF,wBAAsB,gBAAgB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAC9B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA4BlC;AAED,mGAAmG;AACnG,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlG;AAED,yFAAyF;AACzF,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzE"}
+{"version":3,"file":"pending-auth.d.ts","sourceRoot":"","sources":["../../../lib/storage/pending-auth.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AA0B1D,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAmCD,2DAA2D;AAC3D,wBAAsB,iBAAiB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9H,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED,mFAAmF;AACnF,wBAAsB,gBAAgB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAC9B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA6BlC;AAED,mGAAmG;AACnG,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUlG;AAED,yFAAyF;AACzF,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGzE"}

package/dist/lib/storage/pending-auth.js

@@ -17,6 +17,7 @@ import { getIntentionalResetMarkerPath } from "./backup-paths.js";
 const entrySchema = z.object({
     /** sha256 of the spent refresh token: identifies the row without storing it. */
     prior: z.string().regex(/^[0-9a-f]{64}$/),
+    recordId: z.string().trim().min(1).optional(),
     refreshToken: z.string().min(1),
     accessToken: z.string().min(1),
     expiresAt: z.number(),
@@ -78,15 +79,17 @@ export async function recordPendingAuth(storagePath, auth) {
         }
         const prior = hash(auth.priorRefreshToken);
         const entries = (await read(path)).filter((entry) => entry.prior !== prior && entry.prior !== hash(auth.refreshToken));
-        // Rotating a token that is itself only journaled: the row on disk still holds
-        // the original spent token, so extend that entry rather than add one that
-        // no disk row can match.
+        // Rotating a token that is itself only journaled: extend that entry to the
+        // newest credential, but ALSO keep an entry keyed by the token this
+        // rotation just spent. A backup slot or WAL can still hold that
+        // intermediate token, and pruning now keeps entries whose spent token any
+        // recovery source can surface — a stale-snapshot restore then self-heals
+        // straight to the newest credential instead of reviving a spent token.
         const chained = entries.find((entry) => entry.refreshToken === auth.priorRefreshToken);
-        const current = chained ?? { prior, refreshToken: auth.refreshToken, accessToken: auth.accessToken, expiresAt: auth.expiresAt, at: auth.at };
         if (chained)
-            Object.assign(chained, { refreshToken: auth.refreshToken, accessToken: auth.accessToken, expiresAt: auth.expiresAt, at: auth.at });
-        else
-            entries.push(current);
+            Object.assign(chained, { recordId: chained.recordId ?? auth.recordId, refreshToken: auth.refreshToken, accessToken: auth.accessToken, expiresAt: auth.expiresAt, at: auth.at });
+        const current = { prior, recordId: auth.recordId, refreshToken: auth.refreshToken, accessToken: auth.accessToken, expiresAt: auth.expiresAt, at: auth.at };
+        entries.push(current);
         const excess = entries.length - MAX_ENTRIES;
         if (excess > 0) {
             // Drop the oldest other entries, never the credential being recorded now.
@@ -120,6 +123,7 @@ export async function applyPendingAuth(storagePath, storage) {
         const entry = account.refreshToken ? entries.find((item) => item.prior === hash(account.refreshToken)) : undefined;
         if (!entry)
             continue;
+        account.recordId ??= entry.recordId;
         account.refreshToken = entry.refreshToken;
         account.accessToken = entry.accessToken;
         account.expiresAt = entry.expiresAt;
@@ -132,14 +136,34 @@ export async function applyPendingAuth(storagePath, storage) {
     }
     return storage;
 }
-/** After a save, drop entries whose spent token is no longer on disk (persisted or superseded). */
-export async function prunePendingAuth(storagePath, saved) {
+/**
+ * After a save, drop entries whose spent token is no longer in any restorable
+ * state. `saved` is the primary content just persisted; callers may also
+ * supply `restorableRefreshTokens` — refresh tokens still present in recovery
+ * sources (rotating/discovered backups, a WAL payload) — since a restore can
+ * resurface a spent token, its entry must survive until no source holds it.
+ * A scan failure keeps every entry: retention is the safe direction.
+ */
+export async function prunePendingAuth(storagePath, saved, restorableRefreshTokens) {
     const path = getPendingAuthPath(storagePath);
     const current = await read(path);
     if (!current.length)
         return;
     await withFileTransactionLock(path, async () => {
         const spent = new Set(saved.accounts.map((account) => hash(account.refreshToken)));
+        if (restorableRefreshTokens) {
+            try {
+                for (const token of await restorableRefreshTokens()) {
+                    spent.add(hash(token));
+                }
+            }
+            catch (error) {
+                log.warn("Recovery-source scan failed; keeping all pending rotated credentials", {
+                    code: typeof error.code === "string" && /^[A-Z_]{1,40}$/.test(error.code ?? "") ? error.code : "UNKNOWN",
+                });
+                return;
+            }
+        }
         const entries = await read(path);
         const remaining = entries.filter((entry) => spent.has(entry.prior));
         if (remaining.length !== entries.length)

package/dist/lib/storage/project-migration.d.ts

@@ -7,4 +7,3 @@ export declare function loadNormalizedStorageFromPath(path: string, label: strin
     logWarn: (message: string, details: Record<string, unknown>) => void;
 }): Promise<AccountStorageV3 | null>;
 export declare function mergeStorageForMigration(current: AccountStorageV3 | null, incoming: AccountStorageV3, normalizeAccountStorage: (value: unknown) => AccountStorageV3 | null, findMatchingAccountIndex: (accounts: AccountStorageV3["accounts"], candidate: AccountStorageV3["accounts"][number]) => number | undefined): AccountStorageV3;
-//# sourceMappingURL=project-migration.d.ts.map

package/dist/lib/storage/public-types.d.ts

@@ -86,4 +86,3 @@ export interface FlaggedAccountStorageV1 {
     version: 1;
     accounts: FlaggedAccountMetadataV1[];
 }
-//# sourceMappingURL=public-types.d.ts.map

package/dist/lib/storage/record-identity.d.ts

@@ -0,0 +1,15 @@
+/** Derive a legacy record identity before its first persisted token rotation. */
+export declare function deriveAccountRecordId(account: {
+    accountId?: string;
+    email?: string;
+    refreshToken: string;
+    addedAt: number;
+}): string;
+/** Resolve the persisted identity, or derive it for a legacy row. */
+export declare function resolveAccountRecordId(account: {
+    recordId?: string;
+    accountId?: string;
+    email?: string;
+    refreshToken: string;
+    addedAt: number;
+}): string;

package/dist/lib/storage/record-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-identity.d.ts","sourceRoot":"","sources":["../../../lib/storage/record-identity.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,wBAAgB,qBAAqB,CACpC,OAAO,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CAChB,GACC,MAAM,CAQR;AAED,qEAAqE;AACrE,wBAAgB,sBAAsB,CACrC,OAAO,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CAChB,GACC,MAAM,CAGR"}