@cortexkit/anthropic-auth-core 1.21.0 → 1.23.0

package/dist/accounts.js

@@ -1,15 +1,31 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { parseRetryAfterHeader, refreshClaudeOAuthToken } from './auth.js';
+import { assertNotCustodyTombstone, CustodyTombstoneRefreshError, custodyTombstoneKey, isCustodyTombstoneValue, } 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 hasNoLocalCredential(account) {
+    return (account.access == null &&
+        (account.refresh == null || account.refresh === ''));
+}
 export function isOAuthAccount(account) {
     return account.type === 'oauth';
 }
@@ -54,7 +70,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;
@@ -110,7 +126,19 @@ function normalizeAccount(value) {
     }
     if (value.type !== 'oauth')
         return null;
-    if (typeof value.refresh !== 'string' || !value.refresh.trim())
+    const refresh = typeof value.refresh === 'string' ? value.refresh : '';
+    const rosterOnly = value.enabled === true &&
+        typeof value.id === 'string' &&
+        Boolean(value.id.trim()) &&
+        typeof value.label === 'string' &&
+        Boolean(value.label.trim()) &&
+        hasNoLocalCredential(value);
+    const scopedRosterOnly = typeof value.claustrumScopedCredentialId === 'string' &&
+        Boolean(value.claustrumScopedCredentialId.trim()) &&
+        typeof value.anthropicAccountUuid === 'string' &&
+        Boolean(value.anthropicAccountUuid.trim()) &&
+        hasNoLocalCredential(value);
+    if (!refresh.trim() && !rosterOnly && !scopedRosterOnly)
         return null;
     return {
         ...normalizeAccountBase(value),
@@ -118,8 +146,23 @@ function normalizeAccount(value) {
         authLineageId: typeof value.authLineageId === 'string' && value.authLineageId.trim()
             ? value.authLineageId
             : undefined,
+        anthropicAccountUuid: typeof value.anthropicAccountUuid === 'string' &&
+            value.anthropicAccountUuid.trim()
+            ? value.anthropicAccountUuid.trim()
+            : undefined,
+        claustrumHandle: typeof value.claustrumHandle === 'string' && value.claustrumHandle.trim()
+            ? value.claustrumHandle.trim()
+            : undefined,
+        claustrumScopedCredentialId: typeof value.claustrumScopedCredentialId === 'string' &&
+            value.claustrumScopedCredentialId.trim()
+            ? value.claustrumScopedCredentialId.trim()
+            : undefined,
+        claustrumScopedState: typeof value.claustrumScopedState === 'string' &&
+            value.claustrumScopedState.trim()
+            ? value.claustrumScopedState.trim()
+            : undefined,
         access: typeof value.access === 'string' ? value.access : undefined,
-        refresh: value.refresh,
+        refresh,
         expires: typeof value.expires === 'number' ? value.expires : undefined,
         lastRefreshedAt: typeof value.lastRefreshedAt === 'number'
             ? value.lastRefreshedAt
@@ -150,6 +193,10 @@ function normalizeOAuthAccountProfile(value) {
             value.accountIdentity.trim() && {
             accountIdentity: value.accountIdentity.trim(),
         }),
+        ...(typeof value.providerAccountUuid === 'string' &&
+            value.providerAccountUuid.trim() && {
+            providerAccountUuid: value.providerAccountUuid.trim(),
+        }),
         ...(typeof value.tokenFingerprint === 'string' &&
             value.tokenFingerprint.trim() && {
             tokenFingerprint: value.tokenFingerprint.trim(),
@@ -176,6 +223,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 +360,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 +427,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 +470,76 @@ function normalizeStorage(value) {
             .filter((account) => account != null),
     };
 }
+function normalizeClaustrumConfig(value) {
+    if (!isRecord(value))
+        return undefined;
+    const mode = value.mode === 'local' || value.mode === 'claustrum'
+        ? value.mode
+        : undefined;
+    const handlesFile = typeof value.handlesFile === 'string' && value.handlesFile.trim()
+        ? value.handlesFile.trim()
+        : undefined;
+    const primary = isRecord(value.primaryAccount)
+        ? value.primaryAccount
+        : undefined;
+    const primaryAccount = primary &&
+        typeof primary.credentialId === 'string' &&
+        primary.credentialId.trim() &&
+        typeof primary.accountId === 'string' &&
+        primary.accountId.trim() &&
+        typeof primary.state === 'string'
+        ? {
+            credentialId: primary.credentialId.trim(),
+            accountId: primary.accountId.trim(),
+            state: primary.state,
+        }
+        : undefined;
+    const scopedRoster = value.scopedRoster === true;
+    const disabledAccountIdentities = Array.isArray(value.disabledAccountIdentities)
+        ? [
+            ...new Set(value.disabledAccountIdentities
+                .filter((id) => typeof id === 'string' && id.trim().length > 0)
+                .map((id) => id.trim())),
+        ]
+        : [];
+    const accounts = isRecord(value.accounts)
+        ? Object.fromEntries(Object.entries(value.accounts).flatMap(([id, entry]) => {
+            if (!isRecord(entry))
+                return [];
+            return [
+                [
+                    id,
+                    {
+                        ...(typeof entry.enabled === 'boolean' && {
+                            enabled: entry.enabled,
+                        }),
+                    },
+                ],
+            ];
+        }))
+        : undefined;
+    if (!mode &&
+        !handlesFile &&
+        !scopedRoster &&
+        disabledAccountIdentities.length === 0 &&
+        (!accounts || Object.keys(accounts).length === 0)) {
+        return undefined;
+    }
+    return {
+        ...(mode && { mode }),
+        ...(scopedRoster && { scopedRoster: true }),
+        ...(primaryAccount && { primaryAccount }),
+        ...(disabledAccountIdentities.length > 0 && { disabledAccountIdentities }),
+        ...(handlesFile && { handlesFile }),
+        ...(accounts && Object.keys(accounts).length > 0 && { accounts }),
+    };
+}
 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 +563,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));
 }
@@ -448,6 +591,23 @@ function legacyConfigCredentialsAreNewer(account, stateAccount) {
         accountCredentialTimestamp(stateAccount));
 }
 function mergeConfigAccountAndState(account, stateAccount) {
+    if (typeof account.claustrumScopedCredentialId === 'string' &&
+        typeof account.anthropicAccountUuid === 'string') {
+        const sameBinding = stateAccount.claustrumScopedCredentialId ===
+            account.claustrumScopedCredentialId &&
+            stateAccount.anthropicAccountUuid === account.anthropicAccountUuid;
+        const scoped = {
+            ...(sameBinding ? stateAccount : {}),
+            ...account,
+            refresh: '',
+        };
+        delete scoped.access;
+        delete scoped.expires;
+        delete scoped.lastRefreshedAt;
+        delete scoped.lastRefreshError;
+        delete scoped.claustrumHandle;
+        return scoped;
+    }
     if (legacyConfigCredentialsAreNewer(account, stateAccount)) {
         const merged = { ...stateAccount, ...account };
         const configTimestamp = accountCredentialTimestamp(account);
@@ -461,6 +621,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 +651,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 +664,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 +695,8 @@ function mergeConfigAndState(configValue, stateValue) {
         },
         refresh: objectWithDefinedEntries({
             ...refreshConfig,
-            mainLastRefreshError: mainRefreshSource.lastRefreshError,
+            mainLastRefreshError,
+            mainRefreshErrorClearedAt: mainRefreshSource.refreshErrorClearedAt,
             mainRefreshLeaseId: mainRefreshSource.refreshLeaseId,
             mainRefreshLeaseUntil: mainRefreshSource.refreshLeaseUntil,
             mainRefreshLeaseTokenHash: mainRefreshSource.refreshLeaseTokenHash,
@@ -581,6 +774,12 @@ function accountConfig(account) {
         addedAt: account.addedAt,
         baseURL: account.type === 'api' ? account.baseURL : undefined,
         authHeader: account.type === 'api' ? account.authHeader : undefined,
+        claustrumScopedCredentialId: account.type === 'oauth'
+            ? account.claustrumScopedCredentialId
+            : undefined,
+        anthropicAccountUuid: account.type === 'oauth' && account.claustrumScopedCredentialId
+            ? account.anthropicAccountUuid
+            : undefined,
     });
 }
 function accountRuntimeState(account) {
@@ -592,6 +791,10 @@ function accountRuntimeState(account) {
     }
     return objectWithDefinedEntries({
         authLineageId: account.authLineageId,
+        anthropicAccountUuid: account.anthropicAccountUuid,
+        claustrumHandle: account.claustrumHandle,
+        claustrumScopedCredentialId: account.claustrumScopedCredentialId,
+        claustrumScopedState: account.claustrumScopedState,
         access: account.access,
         refresh: account.refresh,
         expires: account.expires,
@@ -649,17 +852,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,24 +914,58 @@ export function mergeHeaderQuotaForPersistence(existing, incoming) {
             ? 'poll'
             : (incoming.bindingWindowSource ?? existing.bindingWindowSource),
     };
+    const fieldSources = fieldSourcesForMergedQuota(existing, incoming, merged);
+    return {
+        ...merged,
+        ...(fieldSources && { fieldSources }),
+    };
 }
-function mergeAccountRuntimeState(existing, incoming) {
+function mergeAccountRuntimeState(existing, incoming, setClaustrumHandle = false) {
     if (!isRecord(existing))
         return incoming;
+    const incomingForMerge = { ...incoming };
+    if (!setClaustrumHandle)
+        delete incomingForMerge.claustrumHandle;
     const existingEntry = existing;
     const tokenChanged = Boolean((existingEntry.access &&
-        incoming.access &&
-        existingEntry.access !== incoming.access) ||
+        incomingForMerge.access &&
+        existingEntry.access !== incomingForMerge.access) ||
         (existingEntry.refresh &&
-            incoming.refresh &&
-            existingEntry.refresh !== incoming.refresh));
-    const mergesHeaderQuota = Boolean(!tokenChanged && incoming.quota?.source === 'headers');
-    const effectiveIncoming = mergesHeaderQuota && incoming.quota
+            incomingForMerge.refresh &&
+            existingEntry.refresh !== incomingForMerge.refresh));
+    const mergesHeaderQuota = Boolean(!tokenChanged && incomingForMerge.quota?.source === 'headers');
+    const effectiveIncoming = mergesHeaderQuota && incomingForMerge.quota
         ? {
-            ...incoming,
-            quota: mergeHeaderQuotaForPersistence(existingEntry.quota, incoming.quota),
+            ...incomingForMerge,
+            quota: mergeHeaderQuotaForPersistence(existingEntry.quota, incomingForMerge.quota),
         }
-        : incoming;
+        : incomingForMerge;
+    if (existingEntry.refresh === custodyTombstoneKey('anthropic') &&
+        ((typeof effectiveIncoming.access === 'string' &&
+            effectiveIncoming.access.length > 0) ||
+            (typeof effectiveIncoming.refresh === 'string' &&
+                effectiveIncoming.refresh !== custodyTombstoneKey('anthropic'))) &&
+        (!effectiveIncoming.authLineageId ||
+            effectiveIncoming.authLineageId === existingEntry.authLineageId)) {
+        logger.warn('accounts', 'discarded stale credential write over a custody tombstone');
+        const { access: _access, refresh: _refresh, expires: _expires, ...safe } = effectiveIncoming;
+        return mergeAccountRuntimeState(existingEntry, safe, setClaustrumHandle);
+    }
+    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 +1001,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 +1024,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 +1058,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 +1076,93 @@ function configFromStorage(storage) {
         accounts: storage.accounts.map(accountConfig),
     });
 }
+export function getClaustrumMode(storage) {
+    return storage?.claustrum?.mode === 'claustrum' ? 'claustrum' : 'local';
+}
+export function isOAuthAccountVaultOwned(storage, account, binding) {
+    return (getClaustrumMode(storage) === 'claustrum' &&
+        isOAuthAccount(account) &&
+        account.enabled !== false &&
+        // Source is provenance, not authorization; the resolver owns the binding decision.
+        (binding?.status === 'resolved' ||
+            Boolean(storage?.claustrum?.scopedRoster && account.claustrumScopedCredentialId)));
+}
+export async function setClaustrumModePersistent(mode, path = getAccountStoragePath()) {
+    return enqueueSave(async () => {
+        const lock = await acquireAccountConfigWriteLock(path);
+        try {
+            const existing = await loadAccounts(path);
+            const storage = existing ?? createEmptyStorage();
+            if (existing && getClaustrumMode(storage) === mode)
+                return 'unchanged';
+            storage.claustrum = { ...storage.claustrum, mode };
+            await saveAccountsWithConfigLock(storage, path, {
+                [WRITE_CLAUSTRUM_MODE]: true,
+            });
+            return 'changed';
+        }
+        finally {
+            await lock.release();
+        }
+    });
+}
+export async function clearClaustrumHandlePersistent(input) {
+    const path = input.path ?? getAccountStoragePath();
+    return enqueueSave(async () => {
+        const configLock = await acquireAccountConfigWriteLock(path);
+        try {
+            const stateLock = await acquireAccountStateWriteLock(path);
+            try {
+                const storage = await loadAccounts(path);
+                if (!storage)
+                    return 'missing';
+                const statePath = getAccountStatePath(path);
+                const state = (await readJsonIfPresent(statePath)).value;
+                const stateAccounts = isRecord(state) && isRecord(state.accounts)
+                    ? state.accounts
+                    : undefined;
+                const matchingStateKeys = Object.keys(stateAccounts ?? {}).filter((key) => key.trim() === input.id.trim());
+                const account = storage.accounts.find((candidate) => candidate.id === input.id);
+                if (!account) {
+                    if (matchingStateKeys.length === 0)
+                        return 'missing';
+                    for (const key of matchingStateKeys) {
+                        const stateAccount = stateAccounts?.[key];
+                        if (isRecord(stateAccount))
+                            delete stateAccount.claustrumHandle;
+                    }
+                    await writeJsonAtomic(statePath, pruneUndefined(state));
+                    return 'updated';
+                }
+                if (!isOAuthAccount(account))
+                    return 'ineligible';
+                if (!account.claustrumHandle)
+                    return 'updated';
+                delete account.claustrumHandle;
+                const existing = await loadExistingTopLevelFields(path);
+                await writeJsonAtomic(path, {
+                    ...existing,
+                    ...configFromStorage(storage),
+                });
+                if (matchingStateKeys.length > 0) {
+                    for (const key of matchingStateKeys) {
+                        const stateAccount = stateAccounts?.[key];
+                        if (isRecord(stateAccount))
+                            delete stateAccount.claustrumHandle;
+                    }
+                    await writeJsonAtomic(statePath, pruneUndefined(state));
+                }
+                return 'updated';
+            }
+            finally {
+                await stateLock.release();
+            }
+        }
+        finally {
+            await configLock.release();
+        }
+    });
+}
 // ---------------------------------------------------------------------------
 // In-process save mutex — serializes all account-store writes so concurrent
 // read-modify-write callers (background timers that call saveAccountState with
@@ -822,6 +1189,8 @@ async function writeJsonAtomic(path, value) {
         throw error;
     }
 }
+const WRITE_CLAUSTRUM_MODE = Symbol('writeClaustrumMode');
+const MUTATE_ACCOUNT_ROSTER = Symbol('mutateAccountRoster');
 function sameAccountIdentity(left, right) {
     return (left.id === right.id ||
         Boolean(left.label && right.label && left.label === right.label));
@@ -853,6 +1222,21 @@ function mergeAccountsForSave(existing, incoming, options) {
     }
     return merged;
 }
+function preserveScopedAccountsOnSave(current, incoming, options) {
+    const apiRoutes = mergeAccountsForSave(current.filter(isApiKeyAccount), incoming.filter(isApiKeyAccount), options);
+    const byId = new Map(apiRoutes.map((account) => [account.id, account]));
+    const result = current.flatMap((account) => {
+        if (isOAuthAccount(account))
+            return [account];
+        const replacement = byId.get(account.id);
+        if (!replacement)
+            return [];
+        byId.delete(account.id);
+        return [replacement];
+    });
+    result.push(...byId.values());
+    return result;
+}
 const ACCOUNT_CONFIG_LOCK_TTL_MS = 10_000;
 const ACCOUNT_CONFIG_LOCK_WAIT_MS = 12_000;
 const ACCOUNT_STATE_LOCK_TTL_MS = 10_000;
@@ -898,6 +1282,32 @@ export function saveAccounts(storage, path = getAccountStoragePath(), options =
     const resolvedPath = path;
     return enqueueSave(() => saveAccountsLocked(storage, resolvedPath, options));
 }
+/** Read-modify-write account configuration under the existing config/state lock order.
+ * The callback is synchronous: network discovery must happen under its own outer
+ * lease, never while holding the config lock. Do not call another persistence API
+ * from the callback.
+ */
+export function mutateAccountsPersistent(path, mutate, options = {}) {
+    const resolvedPath = resolve(path);
+    return enqueueSave(async () => {
+        const lock = await acquireAccountConfigWriteLock(resolvedPath);
+        try {
+            const current = (await loadAccounts(resolvedPath)) ?? createEmptyStorage();
+            const mutation = mutate(current);
+            if (mutation.save !== false) {
+                await options.assertAuthority?.();
+                await saveAccountsWithConfigLock(mutation.storage, resolvedPath, {
+                    ...mutation.options,
+                    [MUTATE_ACCOUNT_ROSTER]: true,
+                });
+            }
+            return mutation.result;
+        }
+        finally {
+            await lock.release();
+        }
+    });
+}
 export async function getOrCreateMainAccountId(path = getAccountStoragePath(), createId = randomUUID) {
     return enqueueSave(async () => {
         const lock = await acquireAccountConfigWriteLock(path);
@@ -922,32 +1332,65 @@ export async function getOrCreateMainAccountId(path = getAccountStoragePath(), c
 async function saveAccountsLocked(storage, path, options) {
     const lock = await acquireAccountConfigWriteLock(path);
     try {
-        const current = await loadAccounts(path);
-        const nextStorage = {
-            ...storage,
-            accounts: mergeAccountsForSave(current?.accounts ?? [], storage.accounts, options),
-        };
-        const existing = await loadExistingTopLevelFields(path);
-        const nextConfig = { ...existing, ...configFromStorage(nextStorage) };
-        await writeJsonAtomic(path, nextConfig);
-        // Config precedes state everywhere both locks are needed; reversing this
-        // order can deadlock profile mutations against full account saves.
-        const stateLock = await acquireAccountStateWriteLock(path);
-        try {
-            await saveAccountStateUnlocked(nextStorage, path, {
-                mainQuota: true,
-                mainRefresh: true,
-                accounts: true,
-            });
-        }
-        finally {
-            await stateLock.release();
-        }
+        await saveAccountsWithConfigLock(storage, path, options);
     }
     finally {
         await lock.release();
     }
 }
+async function saveAccountsWithConfigLock(storage, path, options) {
+    const current = await loadAccounts(path);
+    // A config-only writer may hold a pre-discovery snapshot. It must not
+    // resurrect departed OAuth members or overwrite scoped exclusions.
+    const preserveScopedRoster = current?.claustrum?.scopedRoster === true && !options[MUTATE_ACCOUNT_ROSTER];
+    const mergeOptions = preserveScopedRoster
+        ? {
+            ...options,
+            removedAccountIds: options.removedAccountIds?.filter((id) => current?.accounts.some((account) => account.id === id && isApiKeyAccount(account))),
+        }
+        : options;
+    const nextStorage = {
+        ...storage,
+        ...(storage.claustrum && {
+            claustrum: {
+                ...current?.claustrum,
+                ...storage.claustrum,
+                ...(preserveScopedRoster && current?.claustrum),
+                ...(options[WRITE_CLAUSTRUM_MODE]
+                    ? { mode: storage.claustrum.mode }
+                    : current?.claustrum?.mode
+                        ? { mode: current.claustrum.mode }
+                        : {}),
+            },
+        }),
+        ...(!storage.claustrum &&
+            current?.claustrum && {
+            claustrum: current.claustrum,
+        }),
+        accounts: preserveScopedRoster
+            ? preserveScopedAccountsOnSave(current?.accounts ?? [], storage.accounts, mergeOptions)
+            : mergeAccountsForSave(current?.accounts ?? [], storage.accounts, mergeOptions),
+    };
+    const existing = await loadExistingTopLevelFields(path);
+    const nextConfig = { ...existing, ...configFromStorage(nextStorage) };
+    if (!nextStorage.claustrum)
+        delete nextConfig.claustrum;
+    await writeJsonAtomic(path, nextConfig);
+    // Config precedes state everywhere both locks are needed; reversing this
+    // order can deadlock profile mutations against full account saves.
+    const stateLock = await acquireAccountStateWriteLock(path);
+    try {
+        await saveAccountStateUnlocked(nextStorage, path, {
+            mainQuota: true,
+            mainRefresh: true,
+            accounts: true,
+            setClaustrumHandleAccountIds: options.setClaustrumHandleAccountIds,
+        });
+    }
+    finally {
+        await stateLock.release();
+    }
+}
 function applyMainProfileStatePatch(state, storage) {
     state.main = state.main ?? {};
     state.main.profile = storage.main?.profile;
@@ -999,7 +1442,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 &&
@@ -1030,12 +1476,11 @@ function applyMainQuotaStatePatch(state, storage) {
         ? mergeHeaderQuotaForPersistence(state.main.quota, incomingQuota)
         : incomingQuota;
     const mergesHeaderQuota = Boolean(sameToken && incomingQuota?.source === 'headers');
-    const existingCheckedAt = typeof state.main.quotaCheckedAt === 'number'
-        ? state.main.quotaCheckedAt
-        : quotaSnapshotCheckedAt(state.main.quota);
-    const incomingCheckedAt = typeof storage.quota?.mainQuotaCheckedAt === 'number'
-        ? storage.quota.mainQuotaCheckedAt
-        : quotaSnapshotCheckedAt(effectiveIncomingQuota);
+    // Ordering authority must travel inside the account-bound snapshot. The
+    // legacy top-level quotaCheckedAt/mainQuotaCheckedAt fields carry no account
+    // identity and can form a mixed pair under concurrent cross-account writes.
+    const existingCheckedAt = quotaSnapshotCheckedAt(state.main.quota);
+    const incomingCheckedAt = quotaSnapshotCheckedAt(effectiveIncomingQuota);
     if (!mergesHeaderQuota &&
         (existingCheckedAt > incomingCheckedAt ||
             (existingCheckedAt === incomingCheckedAt &&
@@ -1044,14 +1489,29 @@ function applyMainQuotaStatePatch(state, storage) {
         return;
     }
     state.main.quota = effectiveIncomingQuota;
-    state.main.quotaCheckedAt = mergesHeaderQuota
-        ? Math.max(existingCheckedAt, incomingCheckedAt)
-        : storage.quota?.mainQuotaCheckedAt;
+    const boundCheckedAt = quotaSnapshotCheckedAt(effectiveIncomingQuota);
+    state.main.quotaCheckedAt = boundCheckedAt > 0 ? boundCheckedAt : undefined;
     state.main.quotaToken = storage.quota?.mainQuotaToken;
 }
 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;
@@ -1119,6 +1579,22 @@ export function saveOAuthProfileState(input, path = getAccountStoragePath()) {
                     ? { ...existing, version: 1 }
                     : { version: 1 };
                 const { accountId, accountIdentity, profile } = input;
+                if (current?.claustrum?.scopedRoster &&
+                    getClaustrumMode(current) === 'claustrum') {
+                    const account = current.accounts.find((entry) => entry.id === accountId);
+                    const expected = accountId === 'main'
+                        ? current.claustrum.primaryAccount?.accountId
+                        : account && isOAuthAccount(account)
+                            ? account.anthropicAccountUuid
+                            : undefined;
+                    if (!expected ||
+                        accountIdentity !== expected ||
+                        (profile?.accountIdentity !== undefined &&
+                            profile.accountIdentity !== expected) ||
+                        (profile?.providerAccountUuid !== undefined &&
+                            profile.providerAccountUuid !== expected))
+                        return false;
+                }
                 if (accountId === 'main') {
                     next.main = { ...(next.main ?? {}) };
                     const existingProfile = normalizeOAuthAccountProfile(next.main.profile);
@@ -1201,27 +1677,210 @@ 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 ||
+                    !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();
+        }
+    });
+}
+function fenceScopedPrimaryState(state, primaryId) {
+    if (!isRecord(state.main))
+        state.main = {};
+    const main = state.main;
+    if (!primaryId || main.scopedAccountIdentity !== primaryId) {
+        delete main.prime;
+        delete main.primeAuthLineageId;
+        delete main.primeAuthLineageRefreshTokenFingerprint;
+        delete main.quotaErrorGeneration;
+        delete main.quotaErrorClearedAt;
+    }
+    main.scopedAccountIdentity = primaryId;
+    if (!primaryId || main.quota?.accountIdentity !== primaryId) {
+        delete main.quota;
+        delete main.quotaCheckedAt;
+        delete main.quotaToken;
+    }
+    if (!primaryId || main.lastQuotaApiError?.accountIdentity !== primaryId)
+        delete main.lastQuotaApiError;
+    if (!primaryId ||
+        (main.profile?.providerAccountUuid ?? main.profile?.accountIdentity) !==
+            primaryId) {
+        delete main.profile;
+        delete main.profileToken;
+    }
+    delete main.lastRefreshError;
+    delete main.refreshErrorClearedAt;
+    delete main.refreshLeaseId;
+    delete main.refreshLeaseUntil;
+    delete main.refreshLeaseTokenHash;
+}
 async function saveAccountStateUnlocked(storage, path, scope) {
     const statePath = getAccountStatePath(path);
     const existing = (await readJsonIfPresent(statePath)).value;
     const next = isRecord(existing)
         ? { ...existing, version: 1 }
         : { version: 1 };
-    if (scope.mainProfile)
+    const persistedConfig = (await readJsonIfPresent(path)).value;
+    const authority = isRecord(persistedConfig)
+        ? normalizeClaustrumConfig(persistedConfig.claustrum)
+        : undefined;
+    const scoped = authority?.mode === 'claustrum' && authority.scopedRoster === true;
+    const primaryId = authority?.primaryAccount?.accountId;
+    const samePrimary = Boolean(primaryId && storage.claustrum?.primaryAccount?.accountId === primaryId);
+    if (scoped)
+        fenceScopedPrimaryState(next, primaryId);
+    const incomingProfileId = storage.main?.profile?.providerAccountUuid ??
+        storage.main?.profile?.accountIdentity;
+    if (scope.mainProfile &&
+        (!scoped ||
+            (samePrimary &&
+                (!storage.main?.profile || incomingProfileId === primaryId))))
         applyMainProfileStatePatch(next, storage);
-    if (scope.mainQuota)
-        applyMainQuotaStatePatch(next, storage);
-    if (scope.mainRefresh)
+    const quotaMatches = samePrimary &&
+        (!storage.quota?.mainQuota ||
+            storage.quota.mainQuota.accountIdentity === primaryId) &&
+        (!storage.quota?.mainLastQuotaApiError ||
+            storage.quota.mainLastQuotaApiError.accountIdentity === primaryId);
+    if (scope.mainQuota && (!scoped || quotaMatches)) {
+        applyMainQuotaStatePatch(next, scoped
+            ? { ...storage, quota: { ...storage.quota, mainQuotaToken: primaryId } }
+            : storage);
+    }
+    if (scope.mainRefresh && !scoped)
         applyMainRefreshStatePatch(next, storage);
-    if (scope.mainPrime)
+    if (scope.mainPrime && (!scoped || samePrimary))
         applyMainPrimeStatePatch(next, storage);
     if (scope.accounts) {
         const ids = scope.accounts === true ? null : new Set(scope.accounts);
+        const setClaustrumHandleAccountIds = new Set(scope.setClaustrumHandleAccountIds ?? []);
+        const config = persistedConfig;
+        const configAccounts = isRecord(config) && Array.isArray(config.accounts)
+            ? new Map(config.accounts
+                .filter(isRecord)
+                .map((entry) => [String(entry.id ?? '').trim(), entry]))
+            : new Map();
+        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];
+            const configured = configAccounts.get(accountId);
+            if (configured &&
+                typeof configured.claustrumScopedCredentialId === 'string' &&
+                typeof configured.anthropicAccountUuid === 'string') {
+                const matches = (value) => isRecord(value) &&
+                    value.claustrumScopedCredentialId ===
+                        configured.claustrumScopedCredentialId &&
+                    value.anthropicAccountUuid === configured.anthropicAccountUuid;
+                const incoming = accountRuntimeState(account);
+                const merged = mergeAccountRuntimeState(matches(existingAccount) ? existingAccount : undefined, matches(incoming) ? incoming : {});
+                // The current config owns identity. Older local writers cannot restore
+                // credentials, handles or another account's observations after cutover.
+                next.accounts[accountId] = {
+                    ...merged,
+                    claustrumScopedCredentialId: configured.claustrumScopedCredentialId,
+                    anthropicAccountUuid: configured.anthropicAccountUuid,
+                    refresh: '',
+                };
+                const scoped = next.accounts[accountId];
+                delete scoped.access;
+                delete scoped.expires;
+                delete scoped.lastRefreshedAt;
+                delete scoped.lastRefreshError;
+                delete scoped.claustrumHandle;
+            }
+            else {
+                const merged = mergeAccountRuntimeState(existingAccount, accountRuntimeState(account), setClaustrumHandleAccountIds.has(account.id) ||
+                    setClaustrumHandleAccountIds.has(accountId));
+                if (configured) {
+                    delete merged.claustrumScopedCredentialId;
+                    delete merged.claustrumScopedState;
+                }
+                next.accounts[accountId] = merged;
+            }
+        }
+        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 +1889,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));
 }
@@ -1439,6 +2085,12 @@ export async function acquireRefreshFileLock(options) {
         return null;
     scheduleRenewal();
     return {
+        assertOwned: async () => {
+            const owner = await readOwner().catch(() => undefined);
+            if (released || owner?.ownerId !== ownerId) {
+                throw new Error('Account file lock ownership was lost');
+            }
+        },
         release: async () => {
             released = true;
             if (renewTimer) {
@@ -1717,6 +2369,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 +2384,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 +2398,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 +2414,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 +2429,7 @@ export function buildRefreshOperationError(input) {
         nextRetryAt: input.now + delay,
         retryCount,
         accountIdentity: input.accountIdentity,
+        refreshTokenFingerprint: input.refreshTokenFingerprint,
         status,
         permanent: status === 400 && isInvalidGrant,
     };
@@ -1802,15 +2456,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 +2489,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) {
@@ -1893,13 +2564,14 @@ export async function setLogLevelPersistent(level, path = getAccountStoragePath(
     setLogLevel(level);
 }
 export function getPersistedMainQuota(storage) {
-    if (!storage?.quota?.mainQuota || !storage.quota.mainQuotaCheckedAt)
+    const quota = storage?.quota?.mainQuota;
+    if (!quota)
         return null;
     return {
-        quota: storage.quota.mainQuota,
-        checkedAt: storage.quota.mainQuotaCheckedAt,
-        tokenFingerprint: storage.quota.mainQuotaToken,
-        accountIdentity: storage.quota.mainQuota.accountIdentity,
+        quota,
+        checkedAt: quotaSnapshotCheckedAt(quota),
+        tokenFingerprint: storage.quota?.mainQuotaToken,
+        accountIdentity: quota.accountIdentity,
     };
 }
 /**
@@ -2104,35 +2776,84 @@ export async function setKillswitchPersistent(config, path = getAccountStoragePa
     return storage;
 }
 export async function removeAccountPersistent(id, path = getAccountStoragePath()) {
-    const storage = await loadAccounts(path);
-    if (!storage)
-        return false;
-    const existed = removeAccount(storage, id);
-    if (existed) {
-        await saveAccounts(storage, path, { removedAccountIds: [id] });
-    }
-    return existed;
+    return mutateAccountsPersistent(path, (storage) => {
+        const account = storage.accounts.find((entry) => entry.id === id);
+        if (account &&
+            isOAuthAccount(account) &&
+            account.claustrumScopedCredentialId &&
+            getClaustrumMode(storage) === 'claustrum') {
+            throw new Error('Disable this account or remove it from Claustrum; scoped membership is managed by the vault');
+        }
+        const existed = removeAccount(storage, id);
+        return {
+            storage,
+            result: existed,
+            save: existed,
+            options: { removedAccountIds: [id] },
+        };
+    });
 }
 export async function reorderAccountsPersistent(orderedIds, path = getAccountStoragePath()) {
-    const storage = await loadAccounts(path);
-    if (!storage)
-        return;
-    reorderAccounts(storage, orderedIds);
-    await saveAccounts(storage, path, { preserveExistingAccountOrder: false });
+    await mutateAccountsPersistent(path, (storage) => {
+        reorderAccounts(storage, orderedIds);
+        return {
+            storage,
+            result: undefined,
+            options: { preserveExistingAccountOrder: false },
+        };
+    });
 }
 export async function setAccountEnabledPersistent(id, enabled, path = getAccountStoragePath()) {
-    const storage = await loadAccounts(path);
-    if (!storage)
-        return false;
-    const found = setAccountEnabled(storage, id, enabled);
-    if (found)
-        await saveAccounts(storage, path);
-    return found;
+    return mutateAccountsPersistent(path, (storage) => {
+        const found = setAccountEnabled(storage, id, enabled);
+        const account = storage.accounts.find((candidate) => candidate.id === id);
+        if (account &&
+            isOAuthAccount(account) &&
+            (account.claustrumScopedCredentialId ||
+                storage.claustrum?.scopedRoster) &&
+            account.anthropicAccountUuid) {
+            const disabled = new Set(storage.claustrum?.disabledAccountIdentities ?? []);
+            if (enabled)
+                disabled.delete(account.anthropicAccountUuid);
+            else
+                disabled.add(account.anthropicAccountUuid);
+            storage.claustrum = {
+                ...storage.claustrum,
+                disabledAccountIdentities: [...disabled],
+            };
+        }
+        return { storage, result: found, save: found };
+    });
 }
 export async function addAccountPersistent(account, path = getAccountStoragePath()) {
-    const storage = (await loadAccounts(path)) ?? createEmptyStorage();
-    upsertAccount(storage, account);
-    await saveAccounts(storage, path);
+    await mutateAccountsPersistent(path, (storage) => {
+        if (storage.claustrum?.scopedRoster &&
+            getClaustrumMode(storage) === 'claustrum' &&
+            isOAuthAccount(account)) {
+            throw new Error('Claustrum account membership is managed by the vault; add accounts with ck auth login');
+        }
+        upsertAccount(storage, account);
+        if (isOAuthAccount(account) &&
+            getClaustrumMode(storage) === 'local' &&
+            account.refresh &&
+            !isCustodyTombstoneValue(account.refresh)) {
+            const updated = storage.accounts.find((entry) => entry.id === account.id ||
+                (account.label && entry.label === account.label));
+            if (updated && isOAuthAccount(updated)) {
+                delete updated.claustrumScopedCredentialId;
+                delete updated.claustrumScopedState;
+            }
+        }
+        return {
+            storage,
+            result: undefined,
+            options: {
+                setClaustrumHandleAccountIds: account.type === 'oauth' && account.claustrumHandle
+                    ? [account.id]
+                    : undefined,
+            },
+        };
+    });
 }
 export function getQuotaNextRefreshAt(quota, storage, now) {
     const intervalMs = getQuotaCheckIntervalMs(storage);
@@ -2209,18 +2930,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));
 }
@@ -2348,6 +3062,7 @@ function mapUsageWindow(window, checkedAt) {
     };
 }
 export async function fetchOAuthQuotaSnapshot(input) {
+    assertNotCustodyTombstone(input.accessToken, 'anthropic');
     const fetchImpl = input.fetchImpl ?? fetch;
     const response = await fetchImpl(QUOTA_URL, {
         method: 'GET',
@@ -2370,7 +3085,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 +3097,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);
@@ -2392,10 +3118,16 @@ export function upsertAccount(storage, account) {
     const index = storage.accounts.findIndex((candidate) => candidate.id === account.id ||
         (account.label && candidate.label === account.label));
     if (index >= 0) {
-        storage.accounts[index] = {
-            ...storage.accounts[index],
+        const existing = storage.accounts[index];
+        if (!existing)
+            return;
+        const lineageChanged = existing.type === 'oauth' &&
+            account.type === 'oauth' &&
+            existing.authLineageId !== account.authLineageId;
+        const updated = {
+            ...existing,
             ...account,
-            addedAt: storage.accounts[index]?.addedAt ?? account.addedAt,
+            addedAt: existing.addedAt ?? account.addedAt,
             ...(account.type === 'oauth' && {
                 quota: account.quota,
                 profile: account.profile,
@@ -2404,10 +3136,54 @@ export function upsertAccount(storage, account) {
                 lastQuotaRefreshError: account.lastQuotaRefreshError,
             }),
         };
+        if (lineageChanged && updated.type === 'oauth') {
+            logger.debug('accounts', 'cleared provider UUID after auth lineage change');
+            delete updated.anthropicAccountUuid;
+        }
+        storage.accounts[index] = updated;
         return;
     }
     storage.accounts.push(account);
 }
+export function persistFallbackQuotaHeaderPersistent(input, path = getAccountStoragePath()) {
+    return enqueueSave(async () => {
+        const configLock = await acquireAccountConfigWriteLock(path);
+        try {
+            const stateLock = await acquireAccountStateWriteLock(path);
+            try {
+                const storage = await loadAccounts(path);
+                const account = storage?.accounts.find((candidate) => candidate.id === input.accountId && isOAuthAccount(candidate));
+                if (!storage ||
+                    !account ||
+                    account.authLineageId !== input.authLineageId) {
+                    return false;
+                }
+                account.quota = {
+                    ...input.quota,
+                    accountIdentity: account.id,
+                };
+                if (input.anthropicAccountUuid !== undefined) {
+                    account.anthropicAccountUuid = input.anthropicAccountUuid;
+                }
+                await saveAccountStateUnlocked(storage, path, {
+                    accounts: [input.accountId],
+                });
+                return true;
+            }
+            finally {
+                await stateLock.release();
+            }
+        }
+        finally {
+            await configLock.release();
+        }
+    });
+}
+export function fallbackAccountUuidForLineage(account, authLineageId) {
+    if (!account || account.authLineageId !== authLineageId)
+        return null;
+    return account.anthropicAccountUuid ?? null;
+}
 export function removeAccount(storage, id) {
     const index = storage.accounts.findIndex((c) => c.id === id);
     if (index < 0)
@@ -2433,6 +3209,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 +3220,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({
@@ -2468,9 +3249,14 @@ export class FallbackAccountManager {
     fetchImpl;
     configPath;
     refreshPromises = new Map();
+    custodyVerificationAccounts = new Set();
     refreshTimer = null;
     quotaTimer = null;
     quotaManager;
+    isFallbackAccountVaultServed;
+    isFallbackAccountVaultEnabled;
+    resolveFallbackAccessToken;
+    onBackgroundRefresh;
     onFallbackStorageChanged;
     setIntervalImpl;
     clearIntervalImpl;
@@ -2479,6 +3265,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 +3316,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)
@@ -2536,6 +3337,25 @@ export class FallbackAccountManager {
         this.refreshTimer = null;
         this.quotaTimer = null;
     }
+    async withAccountRefreshLock(accountId, fn) {
+        const lock = await acquireRefreshFileLock({
+            name: fallbackRefreshLockName(accountId),
+            ttlMs: FALLBACK_REFRESH_LOCK_TTL_MS,
+            path: this.configPath,
+            now: this.now,
+            renew: true,
+        });
+        if (!lock)
+            throw new Error('Fallback OAuth refresh is already in progress');
+        this.custodyVerificationAccounts.add(accountId);
+        try {
+            return await fn();
+        }
+        finally {
+            this.custodyVerificationAccounts.delete(accountId);
+            await lock.release();
+        }
+    }
     async getUsableFallbackAccounts(existingStorage, options = {}) {
         const storage = existingStorage !== undefined ? existingStorage : await this.load();
         if (!storage)
@@ -2545,12 +3365,24 @@ export class FallbackAccountManager {
         for (const account of storage.accounts) {
             if (account.enabled === false || !isOAuthAccount(account))
                 continue;
+            if (this.isFallbackAccountVaultEnabled(account.id, storage)) {
+                if (!this.isFallbackAccountVaultServed(account.id, storage))
+                    continue;
+                if (hasNoLocalCredential(account) &&
+                    !storage.quota?.minimumRemaining &&
+                    !isKillswitchEnabled(storage)) {
+                    usable.push(account);
+                    continue;
+                }
+            }
             let next = account;
             try {
-                if (tokenNeedsRefresh(next, storage, this.now())) {
+                if (tokenNeedsRefresh(next, storage, this.now()) &&
+                    !this.isFallbackAccountVaultEnabled(next.id, storage) &&
+                    !this.isFallbackAccountVaultServed(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);
@@ -2566,8 +3398,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 +3423,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 +3467,17 @@ export class FallbackAccountManager {
         for (const account of storage.accounts) {
             if (account.enabled === false || !isOAuthAccount(account))
                 continue;
-            if (!tokenNeedsRefresh(account, storage, this.now()))
+            if (this.custodyVerificationAccounts.has(account.id)) {
+                logger.debug('refresh', 'fallback OAuth background skipped vault-service verification', {
+                    accountId: account.id,
+                });
                 continue;
-            if (refreshBackoffActive(account.lastRefreshError, account.id, 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(), 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
@@ -2676,10 +3517,14 @@ export class FallbackAccountManager {
         for (const account of storage.accounts) {
             if (account.enabled === false || !isOAuthAccount(account))
                 continue;
+            if (this.custodyVerificationAccounts.has(account.id))
+                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 +3541,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 +3568,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 +3590,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 +3608,9 @@ export class FallbackAccountManager {
         return { storage, errors };
     }
     async refreshAccount(account, storage, options = {}) {
+        if (this.isFallbackAccountVaultServed(account.id, storage) ||
+            this.isFallbackAccountVaultEnabled(account.id, storage))
+            return account;
         const existing = this.refreshPromises.get(account.id);
         if (existing) {
             const refreshed = await existing;
@@ -2771,9 +3621,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 +3660,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,10 +3740,46 @@ 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);
+        }
+        const delegatedQuotaAuthorization = storage?.claustrum?.scopedRoster === true &&
+            this.quotaManager?.canFetchWithoutAccessToken() === true;
+        if (!access && !delegatedQuotaAuthorization) {
+            log('[quota] fallback quota poll skipped: no usable credential', {
+                accountId: target.id,
+            });
+            return {
+                account: target,
+                fetched: false,
+                changed,
+            };
+        }
+        let quotaPollLock = await acquireRefreshFileLock({
+            name: fallbackRefreshLockName(target.id),
+            ttlMs: FALLBACK_REFRESH_LOCK_TTL_MS,
+            path: this.configPath,
+            now: this.now,
+        });
+        if (!quotaPollLock) {
+            log('[quota] fallback quota poll skipped refresh lock', {
+                accountId: target.id,
+            });
+            return { account: target, fetched: false, changed };
         }
+        await using _quotaPollLock = {
+            [Symbol.asyncDispose]: async () => quotaPollLock?.release(),
+        };
         // 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).
@@ -2897,21 +3793,48 @@ 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;
+            }
+            await quotaPollLock.release();
+            quotaPollLock = null;
             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,
+                };
+            }
+            quotaPollLock = await acquireRefreshFileLock({
+                name: fallbackRefreshLockName(target.id),
+                ttlMs: FALLBACK_REFRESH_LOCK_TTL_MS,
+                path: this.configPath,
+                now: this.now,
+            });
+            if (!quotaPollLock) {
+                log('[quota] fallback quota poll skipped refresh lock', {
+                    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 +3845,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 +3870,12 @@ export class FallbackAccountManager {
                 checkedAt: now,
             }, target);
         }
-        return { account: target, fetched };
+        return {
+            account: target,
+            fetched,
+            changed: changed ||
+                JSON.stringify([target.quota, target.lastQuotaRefreshError]) !==
+                    initialQuotaState,
+        };
     }
 }