@cortexkit/anthropic-auth-core 1.21.0 → 1.22.0

package/dist/accounts.js

@@ -3,13 +3,25 @@ import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { parseRetryAfterHeader, refreshClaudeOAuthToken } from './auth.js';
+import { CustodyTombstoneRefreshError } from './claustrum.js';
 import { CACHE_1H_MODES, CLAUDE_CODE_VERSION, DEFAULT_CACHE_1H_MODE, } from './constants.js';
+import { parseJsonRedacted } from './json.js';
 import { log, logger } from './logger.js';
+import { isTransientNetworkError } from './network-errors.js';
+import { tokenFingerprint } from './token-fingerprint.js';
 const setRefreshLockRenewalTimeout = globalThis.setTimeout.bind(globalThis);
 const clearRefreshLockRenewalTimeout = globalThis.clearTimeout.bind(globalThis);
 export const ACCOUNT_FILE_NAME = 'anthropic-auth.json';
 export const ACCOUNT_STATE_FILE_NAME = 'anthropic-auth-state.json';
 export const QUOTA_URL = 'https://api.anthropic.com/api/oauth/usage';
+export const QUOTA_FIELD_NAMES = [
+    'five_hour',
+    'seven_day',
+    'scoped',
+    'extraUsage',
+    'bindingWindow',
+    'fallbackAdvised',
+];
 export function isOAuthAccount(account) {
     return account.type === 'oauth';
 }
@@ -54,7 +66,7 @@ const DEFAULT_MINIMUM_REMAINING = {
     seven_day: 0,
 };
 const DEFAULT_FAIL_CLOSED_ON_UNKNOWN_QUOTA = true;
-const BACKGROUND_TICK_MS = 60_000;
+export const FALLBACK_BACKGROUND_TICK_MS = 60_000;
 const BACKGROUND_TICK_JITTER_MS = 60_000;
 const FALLBACK_REFRESH_LOCK_TTL_MS = 10 * 60_000;
 const FALLBACK_REFRESH_JOIN_WAIT_MS = 10_000;
@@ -118,6 +130,9 @@ function normalizeAccount(value) {
         authLineageId: typeof value.authLineageId === 'string' && value.authLineageId.trim()
             ? value.authLineageId
             : undefined,
+        claustrumHandle: typeof value.claustrumHandle === 'string' && value.claustrumHandle.trim()
+            ? value.claustrumHandle.trim()
+            : undefined,
         access: typeof value.access === 'string' ? value.access : undefined,
         refresh: value.refresh,
         expires: typeof value.expires === 'number' ? value.expires : undefined,
@@ -176,6 +191,10 @@ function normalizeOperationError(value) {
             ? value.accountIdentity.trim()
             : undefined,
         tokenHash: typeof value.tokenHash === 'string' ? value.tokenHash : undefined,
+        refreshTokenFingerprint: typeof value.refreshTokenFingerprint === 'string' &&
+            value.refreshTokenFingerprint.trim()
+            ? value.refreshTokenFingerprint.trim()
+            : undefined,
         // Preserve the dead-token discriminators across save/load. Without these,
         // a retry-exhausted transient (permanent=false, 24h backoff) would lose its
         // flag on reload and the 24h-delay heuristic would wrongly re-classify it
@@ -309,6 +328,20 @@ function normalizeQuota(value) {
     if (value.source === 'poll' || value.source === 'headers') {
         quota.source = value.source;
     }
+    if (isRecord(value.fieldSources)) {
+        const fieldSources = {};
+        for (const field of QUOTA_FIELD_NAMES) {
+            if (quota[field] === undefined)
+                continue;
+            const source = value.fieldSources[field];
+            if (source === 'poll' || source === 'headers') {
+                fieldSources[field] = source;
+            }
+        }
+        if (Object.keys(fieldSources).length > 0) {
+            quota.fieldSources = fieldSources;
+        }
+    }
     return Object.keys(quota).length ? quota : undefined;
 }
 function normalizeQuotaMoney(value) {
@@ -362,9 +395,13 @@ function normalizeStorage(value) {
         claudeCache: isRecord(value.claudeCache) ? value.claudeCache : undefined,
         dump: isRecord(value.dump) ? value.dump : undefined,
         claudeFast: isRecord(value.claudeFast) ? value.claudeFast : undefined,
+        thinkingBinding: isRecord(value.thinkingBinding)
+            ? value.thinkingBinding
+            : undefined,
         costZeroing: isRecord(value.costZeroing) ? value.costZeroing : undefined,
         cacheKeep: isRecord(value.cacheKeep) ? value.cacheKeep : undefined,
         relay: isRecord(value.relay) ? value.relay : undefined,
+        claustrum: normalizeClaustrumConfig(value.claustrum),
         logging: isRecord(value.logging) ? value.logging : undefined,
         killswitch: isRecord(value.killswitch) ? value.killswitch : undefined,
         prime: (() => {
@@ -401,9 +438,31 @@ function normalizeStorage(value) {
             .filter((account) => account != null),
     };
 }
+function normalizeClaustrumConfig(value) {
+    if (!isRecord(value) || !isRecord(value.accounts))
+        return undefined;
+    const accounts = Object.fromEntries(Object.entries(value.accounts).flatMap(([id, entry]) => {
+        if (!isRecord(entry))
+            return [];
+        return [
+            [
+                id,
+                {
+                    ...(typeof entry.enabled === 'boolean' && {
+                        enabled: entry.enabled,
+                    }),
+                },
+            ],
+        ];
+    }));
+    return Object.keys(accounts).length > 0 ? { accounts } : undefined;
+}
 async function readJsonIfPresent(path) {
     try {
-        return { exists: true, value: JSON.parse(await readFile(path, 'utf8')) };
+        return {
+            exists: true,
+            value: parseJsonRedacted(await readFile(path, 'utf8')),
+        };
     }
     catch (error) {
         if (error.code === 'ENOENT') {
@@ -427,6 +486,13 @@ export function mergeMainQuotaErrorClearedAt(existing, incoming) {
         return incoming;
     return Math.max(existing, incoming);
 }
+export function mergeMainRefreshErrorClearedAt(existing, incoming) {
+    if (incoming === undefined || !Number.isFinite(incoming))
+        return existing;
+    if (existing === undefined || !Number.isFinite(existing))
+        return incoming;
+    return Math.max(existing, incoming);
+}
 function accountCredentialTimestamp(value) {
     return Math.max(numericField(value.lastRefreshedAt), numericField(value.lastUsed), numericField(value.addedAt));
 }
@@ -461,6 +527,21 @@ function mergeConfigAccountAndState(account, stateAccount) {
     }
     return { ...account, ...stateAccount };
 }
+function configAccountHasInvalidShape(account) {
+    if (account.type !== 'api' && account.type !== 'oauth')
+        return true;
+    if (account.type === 'api' &&
+        'baseURL' in account &&
+        (typeof account.baseURL !== 'string' || !isValidApiBaseURL(account.baseURL))) {
+        return true;
+    }
+    if (account.type === 'oauth' &&
+        'refresh' in account &&
+        (typeof account.refresh !== 'string' || !account.refresh.trim())) {
+        return true;
+    }
+    return false;
+}
 function mergeConfigAndState(configValue, stateValue) {
     if (!isRecord(configValue))
         return configValue;
@@ -476,6 +557,11 @@ function mergeConfigAndState(configValue, stateValue) {
         mainState.quotaErrorClearedAt >= 0
         ? mainState.quotaErrorClearedAt
         : undefined;
+    const mainRefreshErrorClearedAt = typeof mainState?.refreshErrorClearedAt === 'number' &&
+        Number.isFinite(mainState.refreshErrorClearedAt) &&
+        mainState.refreshErrorClearedAt >= 0
+        ? mainState.refreshErrorClearedAt
+        : undefined;
     const configQuotaError = quotaConfig.mainLastQuotaApiError;
     const mainLastQuotaApiError = mainState?.lastQuotaApiError ??
         (mainQuotaErrorClearedAt !== undefined &&
@@ -484,12 +570,24 @@ function mergeConfigAndState(configValue, stateValue) {
             configQuotaError.checkedAt <= mainQuotaErrorClearedAt
             ? undefined
             : configQuotaError);
+    const configRefreshError = refreshConfig.mainLastRefreshError;
+    const mainLastRefreshError = mainState?.lastRefreshError ??
+        (mainRefreshErrorClearedAt !== undefined &&
+            isRecord(configRefreshError) &&
+            typeof configRefreshError.checkedAt === 'number' &&
+            configRefreshError.checkedAt <= mainRefreshErrorClearedAt
+            ? undefined
+            : configRefreshError);
     const accounts = Array.isArray(configValue.accounts)
         ? configValue.accounts.map((account) => {
             if (!isRecord(account))
                 return account;
-            const stateAccount = typeof account.id === 'string' && isRecord(stateAccounts[account.id])
-                ? stateAccounts[account.id]
+            const rawId = typeof account.id === 'string' ? account.id : undefined;
+            const stateValue = rawId
+                ? (stateAccounts[rawId] ?? stateAccounts[rawId.trim()])
+                : undefined;
+            const stateAccount = isRecord(stateValue)
+                ? stateValue
                 : {};
             return mergeConfigAccountAndState(account, stateAccount);
         })
@@ -503,7 +601,8 @@ function mergeConfigAndState(configValue, stateValue) {
         },
         refresh: objectWithDefinedEntries({
             ...refreshConfig,
-            mainLastRefreshError: mainRefreshSource.lastRefreshError,
+            mainLastRefreshError,
+            mainRefreshErrorClearedAt: mainRefreshSource.refreshErrorClearedAt,
             mainRefreshLeaseId: mainRefreshSource.refreshLeaseId,
             mainRefreshLeaseUntil: mainRefreshSource.refreshLeaseUntil,
             mainRefreshLeaseTokenHash: mainRefreshSource.refreshLeaseTokenHash,
@@ -592,6 +691,7 @@ function accountRuntimeState(account) {
     }
     return objectWithDefinedEntries({
         authLineageId: account.authLineageId,
+        claustrumHandle: account.claustrumHandle,
         access: account.access,
         refresh: account.refresh,
         expires: account.expires,
@@ -649,17 +749,61 @@ function mergeHeaderOwnedWindow(existingSnapshot, incomingSnapshot, key) {
         ? existing
         : incoming;
 }
+export function quotaFieldSource(snapshot, field) {
+    if (!snapshot || snapshot[field] === undefined)
+        return undefined;
+    return (snapshot.fieldSources?.[field] ??
+        (snapshot.source === 'poll' || snapshot.source === 'headers'
+            ? snapshot.source
+            : undefined));
+}
+function fieldSourcesForMergedQuota(existing, incoming, merged) {
+    const fieldSources = {};
+    for (const field of QUOTA_FIELD_NAMES) {
+        if (merged[field] === undefined)
+            continue;
+        if (field === 'scoped' || field === 'extraUsage') {
+            fieldSources[field] = 'poll';
+            continue;
+        }
+        if (field === 'bindingWindow' &&
+            existing.bindingWindowSource === 'poll' &&
+            existing.bindingWindow === merged.bindingWindow) {
+            fieldSources[field] = 'poll';
+            continue;
+        }
+        if (field === 'fallbackAdvised' &&
+            incoming.fieldSources?.fallbackAdvised === undefined) {
+            const source = quotaFieldSource(existing, field);
+            if (source)
+                fieldSources[field] = source;
+            continue;
+        }
+        const source = incoming[field] === merged[field]
+            ? quotaFieldSource(incoming, field)
+            : existing[field] === merged[field]
+                ? quotaFieldSource(existing, field)
+                : (quotaFieldSource(existing, field) ??
+                    quotaFieldSource(incoming, field));
+        if (source)
+            fieldSources[field] = source;
+    }
+    return Object.keys(fieldSources).length > 0 ? fieldSources : undefined;
+}
 export function mergeHeaderQuotaForPersistence(existing, incoming) {
     if (!existing || incoming.source !== 'headers')
         return incoming;
     const preservePollBinding = existing.bindingWindowSource === 'poll';
-    return {
+    const merged = {
         ...existing,
         ...incoming,
         five_hour: mergeHeaderOwnedWindow(existing, incoming, 'five_hour'),
         seven_day: mergeHeaderOwnedWindow(existing, incoming, 'seven_day'),
         scoped: mergeHeaderScopedQuota(existing, incoming),
         extraUsage: existing.extraUsage ?? incoming.extraUsage,
+        fallbackAdvised: incoming.fieldSources?.fallbackAdvised !== undefined
+            ? incoming.fallbackAdvised
+            : (existing.fallbackAdvised ?? incoming.fallbackAdvised),
         bindingWindow: preservePollBinding
             ? existing.bindingWindow
             : (incoming.bindingWindow ?? existing.bindingWindow),
@@ -667,6 +811,11 @@ export function mergeHeaderQuotaForPersistence(existing, incoming) {
             ? 'poll'
             : (incoming.bindingWindowSource ?? existing.bindingWindowSource),
     };
+    const fieldSources = fieldSourcesForMergedQuota(existing, incoming, merged);
+    return {
+        ...merged,
+        ...(fieldSources && { fieldSources }),
+    };
 }
 function mergeAccountRuntimeState(existing, incoming) {
     if (!isRecord(existing))
@@ -685,6 +834,21 @@ function mergeAccountRuntimeState(existing, incoming) {
             quota: mergeHeaderQuotaForPersistence(existingEntry.quota, incoming.quota),
         }
         : incoming;
+    const preferredRefreshError = (() => {
+        const existingError = existingEntry.lastRefreshError;
+        const incomingError = effectiveIncoming.lastRefreshError;
+        if (!existingError)
+            return incomingError;
+        if (incomingError) {
+            return incomingError.checkedAt >= existingError.checkedAt
+                ? incomingError
+                : existingError;
+        }
+        return (effectiveIncoming.lastRefreshedAt ?? 0) >
+            (existingEntry.lastRefreshedAt ?? 0)
+            ? undefined
+            : existingError;
+    })();
     const existingQuotaCheckedAt = quotaSnapshotCheckedAt(existingEntry.quota);
     const incomingQuotaCheckedAt = quotaSnapshotCheckedAt(effectiveIncoming.quota);
     const existingQuotaWinsEqualTimestamp = Boolean(existingQuotaCheckedAt === incomingQuotaCheckedAt &&
@@ -720,15 +884,14 @@ function mergeAccountRuntimeState(existing, incoming) {
             if (!('lastQuotaRefreshError' in effectiveIncoming)) {
                 delete merged.lastQuotaRefreshError;
             }
-            if (!('lastRefreshError' in effectiveIncoming)) {
-                delete merged.lastRefreshError;
-            }
+            merged.lastRefreshError = preferredRefreshError;
             return merged;
         }
         return {
             ...merged,
             quota: existingEntry.quota,
             lastQuotaRefreshError: existingEntry.lastQuotaRefreshError,
+            lastRefreshError: preferredRefreshError,
         };
     }
     const merged = {
@@ -744,9 +907,7 @@ function mergeAccountRuntimeState(existing, incoming) {
     if (!('lastQuotaRefreshError' in effectiveIncoming)) {
         delete merged.lastQuotaRefreshError;
     }
-    if (!('lastRefreshError' in effectiveIncoming)) {
-        delete merged.lastRefreshError;
-    }
+    merged.lastRefreshError = preferredRefreshError;
     return merged;
 }
 function configFromStorage(storage) {
@@ -780,9 +941,11 @@ function configFromStorage(storage) {
         dump: storage.dump,
         logging: storage.logging,
         claudeFast: storage.claudeFast,
+        thinkingBinding: storage.thinkingBinding,
         costZeroing: storage.costZeroing,
         cacheKeep: storage.cacheKeep,
         relay: storage.relay,
+        claustrum: storage.claustrum,
         killswitch: storage.killswitch,
         prime: (() => {
             // Config side carries ONLY the `enabled` flag — runtime counters and
@@ -796,6 +959,9 @@ function configFromStorage(storage) {
         accounts: storage.accounts.map(accountConfig),
     });
 }
+export function isClaustrumEnabledForAccount(storage, accountId) {
+    return storage.claustrum?.accounts?.[accountId]?.enabled === true;
+}
 // ---------------------------------------------------------------------------
 // In-process save mutex — serializes all account-store writes so concurrent
 // read-modify-write callers (background timers that call saveAccountState with
@@ -999,7 +1165,10 @@ function applyMainQuotaStatePatch(state, storage) {
             state.main.quotaErrorGeneration = incomingGeneration;
         }
     }
-    else if (incomingError) {
+    else if (incomingError &&
+        typeof incomingError.checkedAt === 'number' &&
+        Number.isFinite(incomingError.checkedAt) &&
+        incomingError.checkedAt > existingObservedAt) {
         const acceptsByObservation = incomingErrorObservedAt !== undefined &&
             incomingErrorObservedAt > existingObservedAt;
         const acceptsEqualObservation = incomingErrorObservedAt !== undefined &&
@@ -1051,7 +1220,23 @@ function applyMainQuotaStatePatch(state, storage) {
 }
 function applyMainRefreshStatePatch(state, storage) {
     state.main = state.main ?? {};
-    state.main.lastRefreshError = storage.refresh?.mainLastRefreshError;
+    const incomingError = storage.refresh?.mainLastRefreshError;
+    const incomingClearedAt = storage.refresh?.mainRefreshErrorClearedAt;
+    const existingErrorObservedAt = state.main.lastRefreshError?.checkedAt;
+    const existingClearedAt = state.main.refreshErrorClearedAt;
+    const existingObservedAt = Math.max(existingErrorObservedAt ?? 0, existingClearedAt ?? 0);
+    if (incomingError === undefined &&
+        incomingClearedAt !== undefined &&
+        incomingClearedAt >= existingObservedAt) {
+        state.main.lastRefreshError = undefined;
+        state.main.refreshErrorClearedAt = mergeMainRefreshErrorClearedAt(existingClearedAt, incomingClearedAt);
+    }
+    else if (incomingError &&
+        typeof incomingError.checkedAt === 'number' &&
+        Number.isFinite(incomingError.checkedAt) &&
+        incomingError.checkedAt > existingObservedAt) {
+        state.main.lastRefreshError = incomingError;
+    }
     state.main.refreshLeaseId = storage.refresh?.mainRefreshLeaseId;
     state.main.refreshLeaseUntil = storage.refresh?.mainRefreshLeaseUntil;
     state.main.refreshLeaseTokenHash = storage.refresh?.mainRefreshLeaseTokenHash;
@@ -1201,6 +1386,44 @@ export function saveOAuthProfileState(input, path = getAccountStoragePath()) {
         }
     });
 }
+export function clearClaustrumRefreshErrorPersistent(accountId, handle, path = getAccountStoragePath()) {
+    return enqueueSave(async () => {
+        const configLock = await acquireAccountConfigWriteLock(path);
+        try {
+            const stateLock = await acquireAccountStateWriteLock(path);
+            try {
+                // Re-read under both locks so this field-scoped clear cannot write a stale credential or config snapshot.
+                const storage = await loadAccounts(path);
+                const account = storage?.accounts.find((candidate) => candidate.id === accountId && isOAuthAccount(candidate));
+                if (!storage ||
+                    !account ||
+                    account.claustrumHandle !== handle ||
+                    !isClaustrumEnabledForAccount(storage, accountId) ||
+                    !account.lastRefreshError) {
+                    return false;
+                }
+                account.lastRefreshError = undefined;
+                await saveAccountStateUnlocked(storage, path, { accounts: [accountId] });
+                const statePath = getAccountStatePath(path);
+                const state = (await readJsonIfPresent(statePath)).value;
+                if (isRecord(state) && isRecord(state.accounts)) {
+                    const entry = state.accounts[accountId];
+                    if (isRecord(entry)) {
+                        delete entry.lastRefreshError;
+                        await writeJsonAtomic(statePath, pruneUndefined(state));
+                    }
+                }
+                return true;
+            }
+            finally {
+                await stateLock.release();
+            }
+        }
+        finally {
+            await configLock.release();
+        }
+    });
+}
 async function saveAccountStateUnlocked(storage, path, scope) {
     const statePath = getAccountStatePath(path);
     const existing = (await readJsonIfPresent(statePath)).value;
@@ -1217,11 +1440,65 @@ async function saveAccountStateUnlocked(storage, path, scope) {
         applyMainPrimeStatePatch(next, storage);
     if (scope.accounts) {
         const ids = scope.accounts === true ? null : new Set(scope.accounts);
+        const config = (await readJsonIfPresent(path)).value;
+        const configuredIds = (() => {
+            if (!isRecord(config) || !Array.isArray(config.accounts))
+                return null;
+            if (config.accounts.length === 0)
+                return new Set();
+            const stateAccounts = isRecord(next.accounts) ? next.accounts : {};
+            const incomingAccounts = Object.fromEntries(storage.accounts.map((account) => [
+                account.id.trim(),
+                accountRuntimeState(account),
+            ]));
+            // Keep both forms because legacy state may still use either key while
+            // scoped saves must preserve entries not superseded by an incoming account.
+            const memberships = config.accounts.map((account) => {
+                if (!isRecord(account) || typeof account.id !== 'string')
+                    return null;
+                const id = account.id.trim();
+                if (!id)
+                    return null;
+                if (configAccountHasInvalidShape(account))
+                    return null;
+                const stateValue = stateAccounts[account.id] ?? stateAccounts[id];
+                const stateAccount = isRecord(stateValue)
+                    ? stateValue
+                    : {};
+                const incomingAccount = incomingAccounts[id];
+                return normalizeAccount(mergeConfigAccountAndState(account, incomingAccount ?? stateAccount))
+                    ? [account.id, id]
+                    : null;
+            });
+            // A populated config with any unparseable entry cannot establish safe membership.
+            return memberships.every((membership) => membership !== null)
+                ? new Set(memberships.flatMap((membership) => membership ?? []))
+                : null;
+        })();
         next.accounts = { ...(isRecord(next.accounts) ? next.accounts : {}) };
         for (const account of storage.accounts) {
-            if (ids && !ids.has(account.id))
+            const accountId = account.id.trim();
+            if (ids && !ids.has(account.id) && !ids.has(accountId))
+                continue;
+            if (configuredIds &&
+                !configuredIds.has(account.id) &&
+                !configuredIds.has(accountId))
                 continue;
-            next.accounts[account.id] = mergeAccountRuntimeState(next.accounts[account.id], accountRuntimeState(account));
+            const legacyKeys = Object.keys(next.accounts).filter((key) => key !== accountId && key.trim() === accountId);
+            const legacyKey = legacyKeys[0];
+            const existingAccount = next.accounts[accountId] ??
+                (legacyKey ? next.accounts[legacyKey] : undefined);
+            for (const key of legacyKeys)
+                delete next.accounts[key];
+            next.accounts[accountId] = mergeAccountRuntimeState(existingAccount, accountRuntimeState(account));
+        }
+        if (configuredIds) {
+            // Config membership is authoritative for scoped writes too; otherwise a
+            // stale writer can preserve state for an account removed out of band.
+            for (const id of Object.keys(next.accounts)) {
+                if (!configuredIds.has(id))
+                    delete next.accounts[id];
+            }
         }
         if (ids) {
             for (const id of ids) {
@@ -1230,19 +1507,6 @@ async function saveAccountStateUnlocked(storage, path, scope) {
                 }
             }
         }
-        else {
-            // Full save: drop any per-account state whose id is no longer present in
-            // storage.accounts. The scoped path above only prunes ids it was asked to
-            // save; on a removal the storage is saved with scope.accounts === true
-            // (ids === null), so without this branch the removed account's runtime
-            // state (quota/lastRefreshError/access/refresh/expires) would be orphaned
-            // in the state file and later merged onto a re-added same-id account.
-            const present = new Set(storage.accounts.map((account) => account.id));
-            for (const id of Object.keys(next.accounts)) {
-                if (!present.has(id))
-                    delete next.accounts[id];
-            }
-        }
     }
     await writeJsonAtomic(statePath, pruneUndefined(next));
 }
@@ -1717,6 +1981,9 @@ function refreshBeforeExpiryMs(storage) {
         DEFAULT_REFRESH_BEFORE_EXPIRY_MINUTES;
     return Math.max(MIN_REFRESH_BEFORE_EXPIRY_MINUTES, minutes) * 60_000;
 }
+export function getRefreshBeforeExpiryMs(storage) {
+    return refreshBeforeExpiryMs(storage);
+}
 export function getRefreshIntervalMs(storage) {
     const minutes = storage?.refresh?.intervalMinutes ?? DEFAULT_REFRESH_INTERVAL_MINUTES;
     return Math.max(1, minutes) * 60_000;
@@ -1729,17 +1996,11 @@ function isTransientRefreshError(error) {
     if (typeof status === 'number' && Number.isFinite(status)) {
         return status === 429 || status >= 500;
     }
-    if (!(error instanceof Error))
-        return false;
-    return (error.message.includes('fetch failed') ||
-        ('code' in error &&
-            (error.code === 'ECONNRESET' ||
-                error.code === 'ECONNREFUSED' ||
-                error.code === 'ETIMEDOUT' ||
-                error.code === 'UND_ERR_CONNECT_TIMEOUT')));
+    return isTransientNetworkError(error);
 }
 export function buildRefreshOperationError(input) {
-    const previousRetryCount = input.previous?.accountIdentity === input.accountIdentity
+    const previousRetryCount = input.previous?.accountIdentity === input.accountIdentity &&
+        input.previous?.refreshTokenFingerprint === input.refreshTokenFingerprint
         ? (input.previous?.retryCount ?? 0)
         : 0;
     const retryCount = previousRetryCount + 1;
@@ -1749,6 +2010,9 @@ export function buildRefreshOperationError(input) {
     if (typeof retryAfterFromError === 'number' && retryAfterFromError > 0) {
         delay = retryAfterFromError * 1000;
     }
+    else if (isTransientNetworkError(input.error)) {
+        delay = MIN_REFRESH_RETRY_DELAY_MS;
+    }
     else if (isTransientRefreshError(input.error)) {
         delay = Math.min(MAX_REFRESH_RETRY_DELAY_MS, MIN_REFRESH_RETRY_DELAY_MS * 2 ** Math.min(retryCount - 1, 6));
     }
@@ -1762,9 +2026,10 @@ export function buildRefreshOperationError(input) {
     const message = formatErrorMessage(input.error);
     // A token is permanently dead ONLY on 400 invalid_grant. The OAuth spec allows
     // other 400s (invalid_client / invalid_request / unsupported_grant_type) that
-    // re-login does NOT fix — those, like a retry-exhausted / network / 429 / 5xx
-    // error, get a long backoff but must stay permanent=false so they are not
-    // falsely flagged "needs re-login". ClaudeOAuthRefreshError carries the raw
+    // re-login does NOT fix — those must stay permanent=false so they are not
+    // falsely flagged "needs re-login". Network failures use a fixed five-minute
+    // retry interval so connectivity recovery cannot inherit an hour-long backoff.
+    // ClaudeOAuthRefreshError carries the raw
     // OAuth body, and its message embeds it (`...: 400 — <body>`), so check both.
     const body = typeof input.error.body === 'string'
         ? input.error.body
@@ -1776,6 +2041,7 @@ export function buildRefreshOperationError(input) {
         nextRetryAt: input.now + delay,
         retryCount,
         accountIdentity: input.accountIdentity,
+        refreshTokenFingerprint: input.refreshTokenFingerprint,
         status,
         permanent: status === 400 && isInvalidGrant,
     };
@@ -1802,15 +2068,32 @@ export function isPermanentRefreshError(error) {
         return error.permanent;
     if (typeof error.status === 'number')
         return error.status === 400;
+    if (isTransientNetworkError(error))
+        return false;
     if (typeof error.nextRetryAt === 'number') {
         return (error.nextRetryAt - error.checkedAt >=
             NON_TRANSIENT_REFRESH_RETRY_DELAY_MS);
     }
     return false;
 }
-export function refreshBackoffActive(error, accountIdentity, now) {
-    if (!error?.nextRetryAt || error.nextRetryAt <= now)
+function effectiveRefreshRetryAt(error) {
+    const persistedRetryAt = error.nextRetryAt;
+    if (!persistedRetryAt || !isTransientNetworkError(error)) {
+        return persistedRetryAt;
+    }
+    return Math.min(persistedRetryAt, error.checkedAt + MIN_REFRESH_RETRY_DELAY_MS);
+}
+export function refreshBackoffActive(error, accountIdentity, now, currentRefreshTokenFingerprint) {
+    if (!error)
+        return false;
+    const retryAt = effectiveRefreshRetryAt(error);
+    if (!retryAt || retryAt <= now)
         return false;
+    if (error.refreshTokenFingerprint &&
+        currentRefreshTokenFingerprint &&
+        error.refreshTokenFingerprint !== currentRefreshTokenFingerprint) {
+        return false;
+    }
     if (!error.accountIdentity)
         return true;
     if (!accountIdentity)
@@ -1818,7 +2101,7 @@ export function refreshBackoffActive(error, accountIdentity, now) {
     return error.accountIdentity === accountIdentity;
 }
 export function formatRefreshBackoffMessage(error, now) {
-    const seconds = Math.max(1, Math.ceil(((error.nextRetryAt ?? now) - now) / 1000));
+    const seconds = Math.max(1, Math.ceil(((effectiveRefreshRetryAt(error) ?? now) - now) / 1000));
     return `Claude OAuth refresh is backed off for ${seconds}s after: ${error.message}`;
 }
 function createRefreshBackoffActiveError(error, now) {
@@ -2209,18 +2492,11 @@ function isTransientQuotaError(error) {
     if (formattedMessage.includes('Quota refresh is already in progress')) {
         return true;
     }
-    if (!(error instanceof Error))
-        return false;
-    const message = error.message;
-    const code = error.code;
-    return (message.includes('fetch failed') ||
-        code === 'ECONNRESET' ||
-        code === 'ECONNREFUSED' ||
-        code === 'ETIMEDOUT' ||
-        code === 'UND_ERR_CONNECT_TIMEOUT');
+    return isTransientNetworkError(error);
 }
 function canUseCachedQuotaAfterRefreshError(account, storage, error, now) {
-    return (isTransientQuotaError(error) &&
+    return (Boolean(account.access && account.expires && account.expires > now) &&
+        isTransientQuotaError(error) &&
         quotaSnapshotPassesPolicy(account.quota, storage) &&
         cachedQuotaSnapshotStillRelevant(account.quota, now));
 }
@@ -2370,7 +2646,7 @@ export async function fetchOAuthQuotaSnapshot(input) {
     const checkedAt = input.now?.() ?? Date.now();
     const usage = (await response.json());
     const bindingWindow = mapBindingWindow(usage.limits);
-    return {
+    const snapshot = {
         five_hour: mapUsageWindow(usage.five_hour, checkedAt),
         seven_day: mapUsageWindow(usage.seven_day, checkedAt),
         scoped: mapScopedWeeklyLimits(usage.limits, checkedAt),
@@ -2382,6 +2658,17 @@ export async function fetchOAuthQuotaSnapshot(input) {
         source: 'poll',
         checkedAt,
     };
+    const fieldSources = {
+        ...(snapshot.five_hour && { five_hour: 'poll' }),
+        ...(snapshot.seven_day && { seven_day: 'poll' }),
+        ...(snapshot.scoped && { scoped: 'poll' }),
+        ...(snapshot.extraUsage && { extraUsage: 'poll' }),
+        ...(snapshot.bindingWindow && { bindingWindow: 'poll' }),
+    };
+    return {
+        ...snapshot,
+        ...(Object.keys(fieldSources).length > 0 && { fieldSources }),
+    };
 }
 function updateStoredAccount(storage, account) {
     const index = storage.accounts.findIndex((candidate) => candidate.id === account.id);
@@ -2433,6 +2720,8 @@ function formatErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function recordRefreshError(account, error, now) {
+    if (error instanceof CustodyTombstoneRefreshError)
+        return;
     const existing = existingRefreshBackoffError(error);
     if (existing) {
         account.lastRefreshError = existing;
@@ -2442,10 +2731,13 @@ function recordRefreshError(account, error, now) {
         error,
         now,
         accountIdentity: account.id,
+        refreshTokenFingerprint: tokenFingerprint(account.refresh),
         previous: account.lastRefreshError,
     });
 }
 function recordQuotaRefreshError(account, error, now) {
+    if (error instanceof CustodyTombstoneRefreshError)
+        return;
     if (isQuotaPolicyAuthError(error) || existingRefreshBackoffError(error))
         return;
     account.lastQuotaRefreshError = buildQuotaOperationError({
@@ -2471,6 +2763,10 @@ export class FallbackAccountManager {
     refreshTimer = null;
     quotaTimer = null;
     quotaManager;
+    isFallbackAccountVaultServed;
+    isFallbackAccountVaultEnabled;
+    resolveFallbackAccessToken;
+    onBackgroundRefresh;
     onFallbackStorageChanged;
     setIntervalImpl;
     clearIntervalImpl;
@@ -2479,6 +2775,21 @@ export class FallbackAccountManager {
         this.fetchImpl = options.fetchImpl ?? fetch;
         this.configPath = options.configPath ?? getAccountStoragePath();
         this.quotaManager = options.quotaManager ?? null;
+        this.isFallbackAccountVaultServed =
+            options.isFallbackAccountVaultServed ?? (() => false);
+        this.isFallbackAccountVaultEnabled =
+            options.isFallbackAccountVaultEnabled ?? (() => false);
+        this.resolveFallbackAccessToken =
+            options.resolveFallbackAccessToken ??
+                ((account) => {
+                    if (!account.access ||
+                        account.expires === undefined ||
+                        account.expires <= this.now()) {
+                        return undefined;
+                    }
+                    return { token: account.access, source: 'sidecar' };
+                });
+        this.onBackgroundRefresh = options.onBackgroundRefresh;
         this.onFallbackStorageChanged = options.onFallbackStorageChanged;
         this.setIntervalImpl = options.setIntervalImpl ?? globalThis.setInterval;
         this.clearIntervalImpl =
@@ -2515,18 +2826,18 @@ export class FallbackAccountManager {
         });
     }
     startBackgroundRefresh() {
-        const run = async () => {
+        const run = async (initial = false) => {
+            await this.onBackgroundRefresh?.(initial);
             await this.refreshDueAccounts();
             await this.refreshQuotaForDueAccounts();
         };
-        void run().catch(() => { });
+        const initialRun = run(true).catch(() => { });
         if (!this.refreshTimer) {
-            this.refreshTimer = this.setIntervalImpl(() => {
-                void run().catch(() => { });
-            }, BACKGROUND_TICK_MS + jitterMs(BACKGROUND_TICK_JITTER_MS));
+            this.refreshTimer = this.setIntervalImpl(() => run().catch(() => { }), FALLBACK_BACKGROUND_TICK_MS + jitterMs(BACKGROUND_TICK_JITTER_MS));
             if ('unref' in this.refreshTimer)
                 this.refreshTimer.unref();
         }
+        return initialRun;
     }
     stopBackgroundRefresh() {
         if (this.refreshTimer)
@@ -2547,10 +2858,20 @@ export class FallbackAccountManager {
                 continue;
             let next = account;
             try {
-                if (tokenNeedsRefresh(next, storage, this.now())) {
+                if (tokenNeedsRefresh(next, storage, this.now()) &&
+                    (!this.isFallbackAccountVaultEnabled(next.id, storage) ||
+                        next.expires === undefined ||
+                        next.expires <= this.now()) &&
+                    !this.isFallbackAccountVaultServed(next.id, storage)) {
+                    if (this.isFallbackAccountVaultEnabled(next.id, storage)) {
+                        logger.warn('refresh', 'custody override: local fallback refresh', {
+                            accountId: next.id,
+                            reason: 'vault credential unavailable',
+                        });
+                    }
                     const refreshError = next.lastRefreshError;
                     if (refreshError &&
-                        refreshBackoffActive(refreshError, next.id, this.now())) {
+                        refreshBackoffActive(refreshError, next.id, this.now(), tokenFingerprint(next.refresh))) {
                         throw createRefreshBackoffActiveError(refreshError, this.now());
                     }
                     next = await this.refreshAccount(next, storage);
@@ -2566,8 +2887,9 @@ export class FallbackAccountManager {
                 // the background refreshQuotaForDueAccounts() guard.
                 if (stale &&
                     !quotaBackoffActive(next.lastQuotaRefreshError, this.now())) {
-                    next = (await this.refreshAccountQuota(next, storage)).account;
-                    changed = true;
+                    const result = await this.refreshAccountQuota(next, storage);
+                    next = result.account;
+                    changed ||= result.changed;
                 }
                 // Single source of truth: evaluate quota policy from the unified
                 // QuotaManager cache (the same source as the staleness check above) so
@@ -2590,7 +2912,7 @@ export class FallbackAccountManager {
                     }
                 }
                 else if (!failClosedOnUnknownQuota(storage) &&
-                    !refreshBackoffActive(next.lastRefreshError, next.id, this.now()) &&
+                    !refreshBackoffActive(next.lastRefreshError, next.id, this.now(), tokenFingerprint(next.refresh)) &&
                     quotaSnapshotPassesModelScope(next.quota, options.modelId)) {
                     usable.push(next);
                 }
@@ -2634,9 +2956,11 @@ export class FallbackAccountManager {
         for (const account of storage.accounts) {
             if (account.enabled === false || !isOAuthAccount(account))
                 continue;
-            if (!tokenNeedsRefresh(account, storage, this.now()))
+            if (!tokenNeedsRefresh(account, storage, this.now()) ||
+                this.isFallbackAccountVaultEnabled(account.id, storage) ||
+                this.isFallbackAccountVaultServed(account.id, storage))
                 continue;
-            if (refreshBackoffActive(account.lastRefreshError, account.id, this.now())) {
+            if (refreshBackoffActive(account.lastRefreshError, account.id, this.now(), tokenFingerprint(account.refresh))) {
                 // Backoff skips are steady-state while a fallback account is waiting for
                 // its next retry. Logging every background tick from every OpenCode
                 // process creates noise without adding new diagnostic signal; the
@@ -2678,8 +3002,10 @@ export class FallbackAccountManager {
                 continue;
             let next = account;
             try {
-                if (tokenNeedsRefresh(next, storage, this.now())) {
-                    if (refreshBackoffActive(next.lastRefreshError, next.id, this.now())) {
+                if (tokenNeedsRefresh(next, storage, this.now()) &&
+                    !this.isFallbackAccountVaultEnabled(next.id, storage) &&
+                    !this.isFallbackAccountVaultServed(next.id, storage)) {
+                    if (refreshBackoffActive(next.lastRefreshError, next.id, this.now(), tokenFingerprint(next.refresh))) {
                         continue;
                     }
                     next = await this.refreshAccount(next, storage);
@@ -2696,8 +3022,8 @@ export class FallbackAccountManager {
                     : quotaIsStale(next, storage, this.now());
                 if (!stale)
                     continue;
-                await this.refreshAccountQuota(next, storage);
-                changed = true;
+                const result = await this.refreshAccountQuota(next, storage);
+                changed ||= result.changed;
             }
             catch (error) {
                 recordQuotaRefreshError(account, error, this.now());
@@ -2723,10 +3049,12 @@ export class FallbackAccountManager {
                 continue;
             let next = account;
             try {
-                if (tokenNeedsRefresh(next, storage, this.now())) {
+                if (tokenNeedsRefresh(next, storage, this.now()) &&
+                    !this.isFallbackAccountVaultServed(next.id, storage) &&
+                    !this.isFallbackAccountVaultEnabled(next.id, storage)) {
                     const refreshError = next.lastRefreshError;
                     if (refreshError &&
-                        refreshBackoffActive(refreshError, next.id, this.now())) {
+                        refreshBackoffActive(refreshError, next.id, this.now(), tokenFingerprint(next.refresh))) {
                         throw createRefreshBackoffActiveError(refreshError, this.now());
                     }
                     next = await this.refreshAccount(next, storage);
@@ -2743,8 +3071,8 @@ export class FallbackAccountManager {
                     }
                     continue;
                 }
-                await this.refreshAccountQuota(next, storage);
-                changed = true;
+                const result = await this.refreshAccountQuota(next, storage);
+                changed ||= result.changed;
             }
             catch (error) {
                 recordQuotaRefreshError(account, error, this.now());
@@ -2761,6 +3089,8 @@ export class FallbackAccountManager {
         return { storage, errors };
     }
     async refreshAccount(account, storage, options = {}) {
+        if (this.isFallbackAccountVaultServed(account.id, storage))
+            return account;
         const existing = this.refreshPromises.get(account.id);
         if (existing) {
             const refreshed = await existing;
@@ -2771,9 +3101,19 @@ export class FallbackAccountManager {
             this.refreshPromises.delete(account.id);
         });
         this.refreshPromises.set(account.id, promise);
-        const refreshed = await promise;
-        updateStoredAccount(storage, refreshed);
-        return refreshed;
+        try {
+            const refreshed = await promise;
+            updateStoredAccount(storage, refreshed);
+            return refreshed;
+        }
+        catch (error) {
+            if (options.persistError) {
+                recordRefreshError(account, error, this.now());
+                updateStoredAccount(storage, account);
+                await this.save(storage);
+            }
+            throw error;
+        }
     }
     async waitForConcurrentFallbackRefresh(account, storage, previous, options) {
         const deadline = Date.now() + FALLBACK_REFRESH_JOIN_WAIT_MS;
@@ -2800,7 +3140,7 @@ export class FallbackAccountManager {
             }
             const refreshError = latestAccount.lastRefreshError;
             if (refreshError &&
-                refreshBackoffActive(refreshError, latestAccount.id, this.now())) {
+                refreshBackoffActive(refreshError, latestAccount.id, this.now(), tokenFingerprint(latestAccount.refresh))) {
                 updateStoredAccount(storage, latestAccount);
                 throw createRefreshBackoffActiveError(refreshError, this.now());
             }
@@ -2880,9 +3220,28 @@ export class FallbackAccountManager {
         }
     }
     async refreshAccountQuota(account, storage) {
+        const initialQuotaState = JSON.stringify([
+            account.quota,
+            account.lastQuotaRefreshError,
+        ]);
+        let changed = false;
         let target = account;
-        if (!target.access) {
-            throw new Error(`Fallback account ${account.id} has no access token`);
+        const vaultEnabled = this.isFallbackAccountVaultEnabled(target.id, storage);
+        let access = this.resolveFallbackAccessToken(target, storage);
+        if (!access && !vaultEnabled) {
+            target = await this.refreshAccount(account, storage, { force: true });
+            changed = true;
+            access = this.resolveFallbackAccessToken(target, storage);
+        }
+        if (!access) {
+            log('[quota] fallback quota poll skipped: no usable credential', {
+                accountId: target.id,
+            });
+            return {
+                account: target,
+                fetched: false,
+                changed,
+            };
         }
         // Unify on the shared QuotaManager when present: it adds inflight
         // deduplication and 429 backoff gating around the same quota API. Fall back
@@ -2897,21 +3256,34 @@ export class FallbackAccountManager {
         const fetchStartedAt = this.now();
         let fetched = false;
         try {
-            const result = await fetchSnapshot(target.access);
+            const result = await fetchSnapshot(access.token);
             target.quota = result.quota;
             fetched = result.fetched;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            if (!message.includes('Claude quota check failed: 401'))
+            if (!message.includes('Claude quota check failed: 401') ||
+                vaultEnabled ||
+                access.source !== 'sidecar') {
                 throw error;
+            }
             target = await this.refreshAccount(account, storage, {
                 force: true,
             });
-            if (!target.access)
-                throw error;
+            changed = true;
+            access = this.resolveFallbackAccessToken(target, storage);
+            if (!access) {
+                log('[quota] fallback quota poll skipped after refresh: no usable credential', {
+                    accountId: target.id,
+                });
+                return {
+                    account: target,
+                    fetched: false,
+                    changed,
+                };
+            }
             // 401 does not arm QuotaManager backoff, so this retry proceeds.
-            const result = await fetchSnapshot(target.access);
+            const result = await fetchSnapshot(access.token);
             target.quota = result.quota;
             fetched = result.fetched;
         }
@@ -2922,16 +3294,17 @@ export class FallbackAccountManager {
             latestAccount.access !== target.access) {
             this.seedFallbackQuota(latestAccount, latestStorage);
             updateStoredAccount(storage, latestAccount);
-            return { account: latestAccount, fetched: false };
+            return { account: latestAccount, fetched: false, changed: false };
         }
         if (latestStorage &&
-            latestAccount?.access === target.access &&
+            latestAccount &&
+            latestAccount.access === target.access &&
             latestAccount.quota &&
             quotaSnapshotCheckedAt(latestAccount.quota) >= fetchStartedAt &&
             quotaSnapshotIsFresh(latestAccount.quota, latestStorage, this.now())) {
             this.seedFallbackQuota(latestAccount, latestStorage);
             updateStoredAccount(storage, latestAccount);
-            return { account: latestAccount, fetched };
+            return { account: latestAccount, fetched, changed: false };
         }
         target.lastQuotaRefreshError = undefined;
         updateStoredAccount(storage, target);
@@ -2946,6 +3319,12 @@ export class FallbackAccountManager {
                 checkedAt: now,
             }, target);
         }
-        return { account: target, fetched };
+        return {
+            account: target,
+            fetched,
+            changed: changed ||
+                JSON.stringify([target.quota, target.lastQuotaRefreshError]) !==
+                    initialQuotaState,
+        };
     }
 }