@cortexkit/anthropic-auth-core 1.20.0 → 1.22.0

package/dist/accounts.js

@@ -3,14 +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';
 }
@@ -55,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;
@@ -119,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,
@@ -147,6 +161,10 @@ function normalizeOAuthAccountProfile(value) {
         tier: value.tier.trim(),
         orgType: value.orgType.trim(),
         checkedAt: value.checkedAt,
+        ...(typeof value.accountIdentity === 'string' &&
+            value.accountIdentity.trim() && {
+            accountIdentity: value.accountIdentity.trim(),
+        }),
         ...(typeof value.tokenFingerprint === 'string' &&
             value.tokenFingerprint.trim() && {
             tokenFingerprint: value.tokenFingerprint.trim(),
@@ -169,7 +187,14 @@ function normalizeOperationError(value) {
         checkedAt,
         nextRetryAt: Number.isFinite(nextRetryAt) ? nextRetryAt : undefined,
         retryCount: Number.isFinite(retryCount) ? retryCount : undefined,
+        accountIdentity: typeof value.accountIdentity === 'string' && value.accountIdentity.trim()
+            ? 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
@@ -234,6 +259,10 @@ function normalizeQuota(value) {
     if (typeof value.checkedAt === 'number' && Number.isFinite(value.checkedAt)) {
         quota.checkedAt = value.checkedAt;
     }
+    if (typeof value.accountIdentity === 'string' &&
+        value.accountIdentity.trim()) {
+        quota.accountIdentity = value.accountIdentity.trim();
+    }
     if (Array.isArray(value.scoped)) {
         const scoped = value.scoped
             .map((entry) => {
@@ -299,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) {
@@ -332,6 +375,9 @@ function normalizeStorage(value) {
         return null;
     return {
         version: 1,
+        mainAccountId: typeof value.mainAccountId === 'string' && value.mainAccountId.trim()
+            ? value.mainAccountId.trim()
+            : undefined,
         main: {
             type: 'opencode',
             provider: 'anthropic',
@@ -343,12 +389,19 @@ function normalizeStorage(value) {
             : undefined,
         refresh: isRecord(value.refresh) ? value.refresh : undefined,
         quota: isRecord(value.quota) ? value.quota : undefined,
+        quotaHeaderFeed: isRecord(value.quotaHeaderFeed)
+            ? value.quotaHeaderFeed
+            : undefined,
         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: (() => {
@@ -385,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') {
@@ -403,6 +478,21 @@ function objectWithDefinedEntries(value) {
 function numericField(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
+// A clear is a monotonic tombstone; older or absent writes must not reopen backoff.
+export function mergeMainQuotaErrorClearedAt(existing, incoming) {
+    if (incoming === undefined || !Number.isFinite(incoming))
+        return existing;
+    if (existing === undefined || !Number.isFinite(existing))
+        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));
 }
@@ -437,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;
@@ -447,12 +552,42 @@ function mergeConfigAndState(configValue, stateValue) {
     const refreshConfig = isRecord(configValue.refresh) ? configValue.refresh : {};
     const mainQuotaSource = mainState ?? quotaConfig;
     const mainRefreshSource = mainState ?? refreshConfig;
+    const mainQuotaErrorClearedAt = typeof mainState?.quotaErrorClearedAt === 'number' &&
+        Number.isFinite(mainState.quotaErrorClearedAt) &&
+        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 &&
+            isRecord(configQuotaError) &&
+            typeof configQuotaError.checkedAt === 'number' &&
+            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);
         })
@@ -466,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,
@@ -476,7 +612,9 @@ function mergeConfigAndState(configValue, stateValue) {
             mainQuota: mainQuotaSource.quota,
             mainQuotaCheckedAt: mainQuotaSource.quotaCheckedAt,
             mainQuotaToken: mainQuotaSource.quotaToken,
-            mainLastQuotaApiError: mainQuotaSource.lastQuotaApiError,
+            mainLastQuotaApiError,
+            mainQuotaErrorGeneration: mainQuotaSource.quotaErrorGeneration,
+            mainQuotaErrorClearedAt: mainQuotaSource.quotaErrorClearedAt,
         }),
         // Carry the main-side prime counters from the state file back into the
         // merged storage so a subsequent read sees the cumulative counters. The
@@ -553,6 +691,7 @@ function accountRuntimeState(account) {
     }
     return objectWithDefinedEntries({
         authLineageId: account.authLineageId,
+        claustrumHandle: account.claustrumHandle,
         access: account.access,
         refresh: account.refresh,
         expires: account.expires,
@@ -610,17 +749,61 @@ function mergeHeaderOwnedWindow(existingSnapshot, incomingSnapshot, key) {
         ? existing
         : incoming;
 }
-function mergeHeaderQuotaForPersistence(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),
@@ -628,6 +811,11 @@ 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))
@@ -646,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 &&
@@ -681,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 = {
@@ -705,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) {
@@ -730,18 +930,22 @@ function configFromStorage(storage) {
         : undefined;
     return omitUndefinedTopLevel({
         version: 1,
+        mainAccountId: storage.mainAccountId,
         main: { type: 'opencode', provider: 'anthropic' },
         routing: storage.routing,
         fallbackOn: storage.fallbackOn,
         refresh,
         quota,
+        quotaHeaderFeed: storage.quotaHeaderFeed,
         claudeCache: storage.claudeCache,
         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
@@ -755,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
@@ -857,6 +1064,27 @@ export function saveAccounts(storage, path = getAccountStoragePath(), options =
     const resolvedPath = path;
     return enqueueSave(() => saveAccountsLocked(storage, resolvedPath, options));
 }
+export async function getOrCreateMainAccountId(path = getAccountStoragePath(), createId = randomUUID) {
+    return enqueueSave(async () => {
+        const lock = await acquireAccountConfigWriteLock(path);
+        try {
+            const storage = (await loadAccounts(path)) ?? createEmptyStorage();
+            if (storage.mainAccountId)
+                return storage.mainAccountId;
+            const mainAccountId = createId();
+            const nextStorage = { ...storage, mainAccountId };
+            const existing = await loadExistingTopLevelFields(path);
+            await writeJsonAtomic(path, {
+                ...existing,
+                ...configFromStorage(nextStorage),
+            });
+            return mainAccountId;
+        }
+        finally {
+            await lock.release();
+        }
+    });
+}
 async function saveAccountsLocked(storage, path, options) {
     const lock = await acquireAccountConfigWriteLock(path);
     try {
@@ -892,6 +1120,77 @@ function applyMainProfileStatePatch(state, storage) {
 }
 function applyMainQuotaStatePatch(state, storage) {
     state.main = state.main ?? {};
+    const incomingError = storage.quota?.mainLastQuotaApiError;
+    const incomingGeneration = typeof storage.quota?.mainQuotaErrorGeneration === 'number' &&
+        Number.isSafeInteger(storage.quota.mainQuotaErrorGeneration) &&
+        storage.quota.mainQuotaErrorGeneration >= 0
+        ? storage.quota.mainQuotaErrorGeneration
+        : undefined;
+    const incomingClearedAt = typeof storage.quota?.mainQuotaErrorClearedAt === 'number' &&
+        Number.isFinite(storage.quota.mainQuotaErrorClearedAt) &&
+        storage.quota.mainQuotaErrorClearedAt >= 0
+        ? storage.quota.mainQuotaErrorClearedAt
+        : undefined;
+    const existingGeneration = typeof state.main.quotaErrorGeneration === 'number' &&
+        Number.isSafeInteger(state.main.quotaErrorGeneration) &&
+        state.main.quotaErrorGeneration >= 0
+        ? state.main.quotaErrorGeneration
+        : 0;
+    const existingErrorObservedAt = typeof state.main.lastQuotaApiError?.checkedAt === 'number' &&
+        Number.isFinite(state.main.lastQuotaApiError.checkedAt) &&
+        state.main.lastQuotaApiError.checkedAt >= 0
+        ? state.main.lastQuotaApiError.checkedAt
+        : undefined;
+    const existingClearedAt = typeof state.main.quotaErrorClearedAt === 'number' &&
+        Number.isFinite(state.main.quotaErrorClearedAt) &&
+        state.main.quotaErrorClearedAt >= 0
+        ? state.main.quotaErrorClearedAt
+        : undefined;
+    const existingObservedAt = Math.max(existingErrorObservedAt ?? 0, existingClearedAt ?? 0);
+    const incomingErrorObservedAt = typeof incomingError?.checkedAt === 'number' &&
+        Number.isFinite(incomingError.checkedAt) &&
+        incomingError.checkedAt >= 0
+        ? incomingError.checkedAt
+        : undefined;
+    // Error transitions are ordered by observation time, not write order. All
+    // instances share one host clock, so an error observed before a clear cannot
+    // resurrect that clear even when both processes allocated the same generation.
+    if (incomingError === undefined &&
+        incomingClearedAt !== undefined &&
+        incomingClearedAt >= existingObservedAt) {
+        state.main.lastQuotaApiError = undefined;
+        state.main.quotaErrorClearedAt = mergeMainQuotaErrorClearedAt(existingClearedAt, incomingClearedAt);
+        if (incomingGeneration !== undefined &&
+            incomingGeneration >= existingGeneration) {
+            state.main.quotaErrorGeneration = incomingGeneration;
+        }
+    }
+    else if (incomingError &&
+        typeof incomingError.checkedAt === 'number' &&
+        Number.isFinite(incomingError.checkedAt) &&
+        incomingError.checkedAt > existingObservedAt) {
+        const acceptsByObservation = incomingErrorObservedAt !== undefined &&
+            incomingErrorObservedAt > existingObservedAt;
+        const acceptsEqualObservation = incomingErrorObservedAt !== undefined &&
+            incomingErrorObservedAt === existingObservedAt &&
+            existingErrorObservedAt !== undefined &&
+            existingClearedAt === undefined &&
+            incomingGeneration !== undefined &&
+            incomingGeneration >= existingGeneration;
+        const acceptsLegacyGeneration = incomingErrorObservedAt === undefined &&
+            incomingClearedAt === undefined &&
+            incomingGeneration !== undefined &&
+            incomingGeneration >= existingGeneration &&
+            existingClearedAt === undefined;
+        if (acceptsByObservation ||
+            acceptsEqualObservation ||
+            acceptsLegacyGeneration) {
+            state.main.lastQuotaApiError = incomingError;
+            if (incomingGeneration !== undefined) {
+                state.main.quotaErrorGeneration = Math.max(existingGeneration, incomingGeneration);
+            }
+        }
+    }
     const incomingQuota = storage.quota?.mainQuota;
     const sameToken = Boolean(state.main.quotaToken &&
         storage.quota?.mainQuotaToken &&
@@ -918,11 +1217,26 @@ function applyMainQuotaStatePatch(state, storage) {
         ? Math.max(existingCheckedAt, incomingCheckedAt)
         : storage.quota?.mainQuotaCheckedAt;
     state.main.quotaToken = storage.quota?.mainQuotaToken;
-    state.main.lastQuotaApiError = storage.quota?.mainLastQuotaApiError;
 }
 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;
@@ -989,38 +1303,41 @@ export function saveOAuthProfileState(input, path = getAccountStoragePath()) {
                 const next = isRecord(existing)
                     ? { ...existing, version: 1 }
                     : { version: 1 };
-                const { accountId, expectedTokenFingerprint, profile } = input;
-                if (profile?.tokenFingerprint &&
-                    profile.tokenFingerprint !== expectedTokenFingerprint) {
-                    return false;
-                }
+                const { accountId, accountIdentity, profile } = input;
                 if (accountId === 'main') {
                     next.main = { ...(next.main ?? {}) };
                     const existingProfile = normalizeOAuthAccountProfile(next.main.profile);
-                    const persistedToken = next.main.profileToken ?? existingProfile?.tokenFingerprint;
-                    if (!profile &&
-                        existingProfile &&
-                        persistedToken === expectedTokenFingerprint) {
-                        return false;
-                    }
-                    if (profile) {
-                        if (persistedToken && persistedToken !== expectedTokenFingerprint) {
-                            return false;
-                        }
+                    if (!profile) {
                         if (existingProfile &&
-                            existingProfile.checkedAt > profile.checkedAt) {
+                            (accountIdentity === undefined ||
+                                existingProfile.accountIdentity === undefined ||
+                                existingProfile.accountIdentity === accountIdentity)) {
                             return false;
                         }
+                        next.main.profile = undefined;
+                        return await writeJsonAtomic(statePath, pruneUndefined(next)).then(() => true);
                     }
-                    next.main.profile = profile;
-                    next.main.profileToken = expectedTokenFingerprint;
+                    if (profile.accountIdentity !== undefined &&
+                        profile.accountIdentity !== accountIdentity) {
+                        return false;
+                    }
+                    const persistedProfile = accountIdentity === undefined ||
+                        profile.accountIdentity === accountIdentity
+                        ? profile
+                        : { ...profile, accountIdentity };
+                    if (existingProfile &&
+                        (accountIdentity === undefined ||
+                            existingProfile.accountIdentity === undefined ||
+                            existingProfile.accountIdentity === accountIdentity) &&
+                        existingProfile.checkedAt > persistedProfile.checkedAt) {
+                        return false;
+                    }
+                    next.main.profile = persistedProfile;
                 }
                 else {
                     const account = current?.accounts.find((candidate) => candidate.id === accountId && isOAuthAccount(candidate));
-                    if (!account?.access ||
-                        tokenFingerprint(account.access) !== expectedTokenFingerprint) {
+                    if (!account)
                         return false;
-                    }
                     next.accounts = {
                         ...(isRecord(next.accounts) ? next.accounts : {}),
                     };
@@ -1028,16 +1345,33 @@ export function saveOAuthProfileState(input, path = getAccountStoragePath()) {
                         ? { ...next.accounts[accountId] }
                         : {};
                     const existingProfile = normalizeOAuthAccountProfile(existingEntry.profile);
-                    if (!profile &&
-                        existingProfile?.tokenFingerprint === expectedTokenFingerprint) {
-                        return false;
+                    if (!profile) {
+                        if (existingProfile &&
+                            (accountIdentity === undefined ||
+                                existingProfile.accountIdentity === undefined ||
+                                existingProfile.accountIdentity === accountIdentity)) {
+                            return false;
+                        }
+                        existingEntry.profile = undefined;
                     }
-                    if (profile &&
-                        existingProfile &&
-                        existingProfile.checkedAt > profile.checkedAt) {
-                        return false;
+                    else {
+                        if (profile.accountIdentity !== undefined &&
+                            profile.accountIdentity !== accountIdentity) {
+                            return false;
+                        }
+                        const persistedProfile = accountIdentity === undefined ||
+                            profile.accountIdentity === accountIdentity
+                            ? profile
+                            : { ...profile, accountIdentity };
+                        if (existingProfile &&
+                            (accountIdentity === undefined ||
+                                existingProfile.accountIdentity === undefined ||
+                                existingProfile.accountIdentity === accountIdentity) &&
+                            existingProfile.checkedAt > persistedProfile.checkedAt) {
+                            return false;
+                        }
+                        existingEntry.profile = persistedProfile;
                     }
-                    existingEntry.profile = profile;
                     next.accounts[accountId] = existingEntry;
                 }
                 await writeJsonAtomic(statePath, pruneUndefined(next));
@@ -1052,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;
@@ -1068,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;
-            next.accounts[account.id] = mergeAccountRuntimeState(next.accounts[account.id], accountRuntimeState(account));
+            if (configuredIds &&
+                !configuredIds.has(account.id) &&
+                !configuredIds.has(accountId))
+                continue;
+            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) {
@@ -1081,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));
 }
@@ -1421,12 +1834,8 @@ export async function setPrimePersistentEnabled(enabled, path = getAccountStorag
     await saveAccounts(storage, path);
     return storage;
 }
-/**
- * Return the stable prime marker identity for an OAuth account, seeding it in
- * runtime state when older storage has no lineage yet. Main lookups return
- * undefined when the live refresh token is unavailable and no lineage exists.
- */
-export async function getOrCreatePrimeAuthLineageId(accountId, path = getAccountStoragePath(), mainRefreshToken) {
+/** Return the stable prime marker identity for an OAuth account. */
+export async function getOrCreatePrimeAuthLineageId(accountId, path = getAccountStoragePath()) {
     return enqueueSave(async () => {
         const configLock = await acquireAccountConfigWriteLock(path);
         try {
@@ -1435,52 +1844,23 @@ export async function getOrCreatePrimeAuthLineageId(accountId, path = getAccount
                 const storage = (await loadAccounts(path)) ?? createEmptyStorage();
                 if (accountId === 'main') {
                     const existing = storage.prime?.mainAuthLineageId;
-                    const observedFingerprint = mainRefreshToken
-                        ? tokenFingerprint(mainRefreshToken)
-                        : undefined;
-                    const boundFingerprint = storage.prime?.mainAuthLineageRefreshTokenFingerprint;
-                    if (existing) {
-                        if (!observedFingerprint ||
-                            boundFingerprint === observedFingerprint)
-                            return existing;
-                        if (boundFingerprint &&
-                            storage.refresh?.mainRefreshLeaseUntil &&
-                            storage.refresh.mainRefreshLeaseUntil > Date.now()) {
-                            // The owner binds before publishing its rotated credential. An
-                            // active lease makes either side of that handoff ambiguous, so
-                            // suppress this tick instead of classifying it as a re-login.
-                            return existing;
-                        }
-                        if (!boundFingerprint) {
-                            // Legacy lineages predate refresh-token binding. The first
-                            // observation attaches the credential without changing markers.
-                            storage.prime = {
-                                ...(storage.prime ?? {}),
-                                mainAuthLineageRefreshTokenFingerprint: observedFingerprint,
-                            };
-                            await saveAccountStateUnlocked(storage, path, {
-                                mainPrime: true,
-                            });
-                            return existing;
-                        }
+                    if (existing)
+                        return existing;
+                    const mainAccountId = storage.mainAccountId ?? randomUUID();
+                    if (!storage.mainAccountId) {
+                        const existingConfig = await loadExistingTopLevelFields(path);
+                        await writeJsonAtomic(path, {
+                            ...existingConfig,
+                            ...configFromStorage({ ...storage, mainAccountId }),
+                        });
+                        storage.mainAccountId = mainAccountId;
                     }
-                    // Without the live host credential there is no safe way to bind a
-                    // new identity. Skip this tick rather than creating an unbound
-                    // namespace that could churn or suppress another account.
-                    if (!observedFingerprint)
-                        return undefined;
-                    // A bound mismatch that did not pass through the owned refresh path
-                    // is a host credential replacement and needs a fresh marker identity.
-                    const authLineageId = randomUUID();
                     storage.prime = {
                         ...(storage.prime ?? {}),
-                        mainAuthLineageId: authLineageId,
-                        ...(observedFingerprint && {
-                            mainAuthLineageRefreshTokenFingerprint: observedFingerprint,
-                        }),
+                        mainAuthLineageId: mainAccountId,
                     };
                     await saveAccountStateUnlocked(storage, path, { mainPrime: true });
-                    return authLineageId;
+                    return mainAccountId;
                 }
                 const account = storage.accounts.find((candidate) => candidate.id === accountId && isOAuthAccount(candidate));
                 if (!account) {
@@ -1507,42 +1887,6 @@ export async function getOrCreatePrimeAuthLineageId(accountId, path = getAccount
         }
     });
 }
-/** Advance a main lineage across a refresh performed by this plugin. */
-export async function continueMainPrimeAuthLineageAfterRefresh(input, path = getAccountStoragePath()) {
-    return enqueueSave(async () => {
-        const configLock = await acquireAccountConfigWriteLock(path);
-        try {
-            const stateLock = await acquireAccountStateWriteLock(path);
-            try {
-                const storage = (await loadAccounts(path)) ?? createEmptyStorage();
-                const authLineageId = storage.prime?.mainAuthLineageId;
-                if (!authLineageId)
-                    return;
-                const previousFingerprint = tokenFingerprint(input.previousRefreshToken);
-                const currentFingerprint = tokenFingerprint(input.currentRefreshToken);
-                const boundFingerprint = storage.prime?.mainAuthLineageRefreshTokenFingerprint;
-                if (boundFingerprint &&
-                    boundFingerprint !== previousFingerprint &&
-                    boundFingerprint !== currentFingerprint) {
-                    // Another process observed a host replacement after this refresh
-                    // started; the stale rotation must not rebind that newer lineage.
-                    return;
-                }
-                storage.prime = {
-                    ...(storage.prime ?? {}),
-                    mainAuthLineageRefreshTokenFingerprint: currentFingerprint,
-                };
-                await saveAccountStateUnlocked(storage, path, { mainPrime: true });
-            }
-            finally {
-                await stateLock.release();
-            }
-        }
-        finally {
-            await configLock.release();
-        }
-    });
-}
 /**
  * Atomically increment an account's cumulative prime counters and persist via
  * the scoped runtime-state path. The `main` account lives at state.main.prime;
@@ -1637,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;
@@ -1649,19 +1996,12 @@ 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 tokenHash = hashRefreshToken(input.refreshToken);
-    const previousRetryCount = input.previous?.tokenHash === tokenHash
-        ? (input.previous.retryCount ?? 0)
+    const previousRetryCount = input.previous?.accountIdentity === input.accountIdentity &&
+        input.previous?.refreshTokenFingerprint === input.refreshTokenFingerprint
+        ? (input.previous?.retryCount ?? 0)
         : 0;
     const retryCount = previousRetryCount + 1;
     const retryAfterFromError = input.error
@@ -1670,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));
     }
@@ -1683,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
@@ -1696,7 +2040,8 @@ export function buildRefreshOperationError(input) {
         checkedAt: input.now,
         nextRetryAt: input.now + delay,
         retryCount,
-        tokenHash,
+        accountIdentity: input.accountIdentity,
+        refreshTokenFingerprint: input.refreshTokenFingerprint,
         status,
         permanent: status === 400 && isInvalidGrant,
     };
@@ -1723,21 +2068,40 @@ 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, refreshToken, 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;
-    if (!refreshToken)
+    const retryAt = effectiveRefreshRetryAt(error);
+    if (!retryAt || retryAt <= now)
+        return false;
+    if (error.refreshTokenFingerprint &&
+        currentRefreshTokenFingerprint &&
+        error.refreshTokenFingerprint !== currentRefreshTokenFingerprint) {
+        return false;
+    }
+    if (!error.accountIdentity)
         return true;
-    return error.tokenHash === hashRefreshToken(refreshToken);
+    if (!accountIdentity)
+        return true;
+    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) {
@@ -1768,7 +2132,9 @@ export function isQuotaPolicyAuthError(error) {
     return /Claude quota check failed: 403\b/.test(formatErrorMessage(error));
 }
 export function buildQuotaOperationError(input) {
-    const previousRetryCount = input.previous?.retryCount ?? 0;
+    const previousRetryCount = input.previous?.accountIdentity === input.accountIdentity
+        ? (input.previous?.retryCount ?? 0)
+        : 0;
     const retryCount = previousRetryCount + 1;
     const delay = isTransientQuotaError(input.error)
         ? Math.min(MAX_QUOTA_RETRY_DELAY_MS, MIN_QUOTA_RETRY_DELAY_MS * 2 ** Math.min(retryCount - 1, 6))
@@ -1778,6 +2144,9 @@ export function buildQuotaOperationError(input) {
         checkedAt: input.now,
         nextRetryAt: input.now + delay,
         retryCount,
+        ...(input.accountIdentity !== undefined && {
+            accountIdentity: input.accountIdentity,
+        }),
     };
 }
 export function quotaBackoffActive(error, now) {
@@ -1813,6 +2182,7 @@ export function getPersistedMainQuota(storage) {
         quota: storage.quota.mainQuota,
         checkedAt: storage.quota.mainQuotaCheckedAt,
         tokenFingerprint: storage.quota.mainQuotaToken,
+        accountIdentity: storage.quota.mainQuota.accountIdentity,
     };
 }
 /**
@@ -1879,6 +2249,9 @@ export function quotaSnapshotPassesPolicy(quota, storage) {
     }
     return true;
 }
+export function quotaSnapshotHasStandardWindows(quota) {
+    return Boolean(quota?.five_hour && quota.seven_day);
+}
 // ---------------------------------------------------------------------------
 // Killswitch — hard-block requests when remaining quota drops below per-account
 // thresholds, even if the API would still accept them.
@@ -2119,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));
 }
@@ -2280,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),
@@ -2292,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);
@@ -2343,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;
@@ -2351,11 +2730,14 @@ function recordRefreshError(account, error, now) {
     account.lastRefreshError = buildRefreshOperationError({
         error,
         now,
-        refreshToken: account.refresh,
+        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({
@@ -2381,6 +2763,10 @@ export class FallbackAccountManager {
     refreshTimer = null;
     quotaTimer = null;
     quotaManager;
+    isFallbackAccountVaultServed;
+    isFallbackAccountVaultEnabled;
+    resolveFallbackAccessToken;
+    onBackgroundRefresh;
     onFallbackStorageChanged;
     setIntervalImpl;
     clearIntervalImpl;
@@ -2389,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 =
@@ -2406,7 +2807,7 @@ export class FallbackAccountManager {
         const checkedAt = quotaSnapshotCheckedAt(account.quota);
         if (checkedAt <= 0)
             return;
-        const existing = this.quotaManager.getFallback(account.id, account.access);
+        const existing = this.quotaManager.getFallback(account.id, account);
         if (existing && existing.checkedAt >= checkedAt)
             return;
         const checkInterval = getQuotaCheckIntervalMs(storage);
@@ -2414,7 +2815,7 @@ export class FallbackAccountManager {
             quota: account.quota,
             refreshAfter: checkedAt + checkInterval,
             checkedAt,
-        }, account.access);
+        }, account);
     }
     async load() {
         return loadAccounts(this.configPath);
@@ -2425,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)
@@ -2455,12 +2856,22 @@ export class FallbackAccountManager {
         for (const account of storage.accounts) {
             if (account.enabled === false || !isOAuthAccount(account))
                 continue;
+            let next = account;
             try {
-                let next = account;
-                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.refresh, this.now())) {
+                        refreshBackoffActive(refreshError, next.id, this.now(), tokenFingerprint(next.refresh))) {
                         throw createRefreshBackoffActiveError(refreshError, this.now());
                     }
                     next = await this.refreshAccount(next, storage);
@@ -2468,7 +2879,7 @@ export class FallbackAccountManager {
                 }
                 this.seedFallbackQuota(next, storage);
                 const stale = this.quotaManager
-                    ? this.quotaManager.isFallbackStale(next.id, next.access, options.modelId)
+                    ? this.quotaManager.isFallbackStale(next.id, next.access, options.modelId, next)
                     : quotaIsStale(next, storage, this.now(), options.modelId);
                 // Skip the request-time refresh when this account's quota API is
                 // backed off (recent 429/5xx). Hitting it again would extend the
@@ -2476,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
@@ -2488,20 +2900,21 @@ export class FallbackAccountManager {
                     usable.push(next);
             }
             catch (error) {
-                if (canUseCachedQuotaAfterRefreshError(account, storage, error, this.now())) {
+                if (canUseCachedQuotaAfterRefreshError(next, storage, error, this.now())) {
                     log('[refresh] fallback quota using cached quota after refresh error', {
-                        accountId: account.id,
+                        accountId: next.id,
                         error: formatErrorMessage(error),
                     });
-                    if (this.accountPassesQuotaPolicy(this.quotaPolicyAccount(account), storage, {
+                    if (this.accountPassesQuotaPolicy(this.quotaPolicyAccount(next), storage, {
                         modelId: options.modelId,
                     })) {
-                        usable.push(account);
+                        usable.push(next);
                     }
                 }
                 else if (!failClosedOnUnknownQuota(storage) &&
-                    quotaSnapshotPassesModelScope(account.quota, options.modelId)) {
-                    usable.push(account);
+                    !refreshBackoffActive(next.lastRefreshError, next.id, this.now(), tokenFingerprint(next.refresh)) &&
+                    quotaSnapshotPassesModelScope(next.quota, options.modelId)) {
+                    usable.push(next);
                 }
             }
         }
@@ -2532,7 +2945,7 @@ export class FallbackAccountManager {
     quotaPolicyAccount(account) {
         if (!this.quotaManager)
             return account;
-        const cached = this.quotaManager.getFallback(account.id, account.access)?.quota;
+        const cached = this.quotaManager.getFallback(account.id, account)?.quota;
         return cached ? { ...account, quota: cached } : account;
     }
     async refreshDueAccounts() {
@@ -2543,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.refresh, 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
@@ -2587,8 +3002,10 @@ export class FallbackAccountManager {
                 continue;
             let next = account;
             try {
-                if (tokenNeedsRefresh(next, storage, this.now())) {
-                    if (refreshBackoffActive(next.lastRefreshError, next.refresh, 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);
@@ -2605,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());
@@ -2632,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.refresh, this.now())) {
+                        refreshBackoffActive(refreshError, next.id, this.now(), tokenFingerprint(next.refresh))) {
                         throw createRefreshBackoffActiveError(refreshError, this.now());
                     }
                     next = await this.refreshAccount(next, storage);
@@ -2652,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());
@@ -2670,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;
@@ -2680,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;
@@ -2709,7 +3140,7 @@ export class FallbackAccountManager {
             }
             const refreshError = latestAccount.lastRefreshError;
             if (refreshError &&
-                refreshBackoffActive(refreshError, latestAccount.refresh, this.now())) {
+                refreshBackoffActive(refreshError, latestAccount.id, this.now(), tokenFingerprint(latestAccount.refresh))) {
                 updateStoredAccount(storage, latestAccount);
                 throw createRefreshBackoffActiveError(refreshError, this.now());
             }
@@ -2789,15 +3220,34 @@ 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
         // to a direct fetch only when no QuotaManager is wired (e.g. in isolation).
         const fetchSnapshot = (accessToken) => this.quotaManager
-            ? this.quotaManager.refreshFallbackWithMetadata(target.id, accessToken)
+            ? this.quotaManager.refreshFallbackWithMetadata(target.id, accessToken, target)
             : fetchOAuthQuotaSnapshot({
                 accessToken,
                 fetchImpl: this.fetchImpl,
@@ -2806,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;
         }
@@ -2831,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);
@@ -2853,8 +3317,14 @@ export class FallbackAccountManager {
                 quota: target.quota,
                 refreshAfter: now + getQuotaCheckIntervalMs(storage),
                 checkedAt: now,
-            }, target.access);
+            }, target);
         }
-        return { account: target, fetched };
+        return {
+            account: target,
+            fetched,
+            changed: changed ||
+                JSON.stringify([target.quota, target.lastQuotaRefreshError]) !==
+                    initialQuotaState,
+        };
     }
 }