@cortexkit/anthropic-auth-core 1.22.0 → 1.23.0

package/dist/accounts.js

@@ -1,9 +1,9 @@
 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 { CustodyTombstoneRefreshError } from './claustrum.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';
@@ -22,6 +22,10 @@ export const QUOTA_FIELD_NAMES = [
     'bindingWindow',
     'fallbackAdvised',
 ];
+export function hasNoLocalCredential(account) {
+    return (account.access == null &&
+        (account.refresh == null || account.refresh === ''));
+}
 export function isOAuthAccount(account) {
     return account.type === 'oauth';
 }
@@ -122,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),
@@ -130,11 +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
@@ -165,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(),
@@ -439,23 +471,68 @@ function normalizeStorage(value) {
     };
 }
 function normalizeClaustrumConfig(value) {
-    if (!isRecord(value) || !isRecord(value.accounts))
+    if (!isRecord(value))
         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;
+    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 {
@@ -514,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);
@@ -680,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) {
@@ -691,7 +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,
@@ -817,23 +920,37 @@ export function mergeHeaderQuotaForPersistence(existing, incoming) {
         ...(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),
-        }
-        : incoming;
+            ...incomingForMerge,
+            quota: mergeHeaderQuotaForPersistence(existingEntry.quota, incomingForMerge.quota),
+        }
+        : 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;
@@ -959,8 +1076,92 @@ function configFromStorage(storage) {
         accounts: storage.accounts.map(accountConfig),
     });
 }
-export function isClaustrumEnabledForAccount(storage, accountId) {
-    return storage.claustrum?.accounts?.[accountId]?.enabled === true;
+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
@@ -988,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));
@@ -1019,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;
@@ -1064,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);
@@ -1088,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;
@@ -1199,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 &&
@@ -1213,9 +1489,8 @@ 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) {
@@ -1304,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);
@@ -1398,7 +1689,6 @@ export function clearClaustrumRefreshErrorPersistent(accountId, handle, path = g
                 if (!storage ||
                     !account ||
                     account.claustrumHandle !== handle ||
-                    !isClaustrumEnabledForAccount(storage, accountId) ||
                     !account.lastRefreshError) {
                     return false;
                 }
@@ -1424,23 +1714,82 @@ export function clearClaustrumRefreshErrorPersistent(accountId, handle, path = g
         }
     });
 }
+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 config = (await readJsonIfPresent(path)).value;
+        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;
@@ -1490,7 +1839,40 @@ async function saveAccountStateUnlocked(storage, path, scope) {
                 (legacyKey ? next.accounts[legacyKey] : undefined);
             for (const key of legacyKeys)
                 delete next.accounts[key];
-            next.accounts[accountId] = mergeAccountRuntimeState(existingAccount, accountRuntimeState(account));
+            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
@@ -1703,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) {
@@ -2176,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,
     };
 }
 /**
@@ -2387,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);
@@ -2624,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',
@@ -2679,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,
@@ -2691,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)
@@ -2760,6 +3249,7 @@ export class FallbackAccountManager {
     fetchImpl;
     configPath;
     refreshPromises = new Map();
+    custodyVerificationAccounts = new Set();
     refreshTimer = null;
     quotaTimer = null;
     quotaManager;
@@ -2847,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)
@@ -2856,19 +3365,21 @@ 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()) &&
-                    (!this.isFallbackAccountVaultEnabled(next.id, storage) ||
-                        next.expires === undefined ||
-                        next.expires <= this.now()) &&
+                    !this.isFallbackAccountVaultEnabled(next.id, storage) &&
                     !this.isFallbackAccountVaultServed(next.id, storage)) {
-                    if (this.isFallbackAccountVaultEnabled(next.id, storage)) {
-                        logger.warn('refresh', 'custody override: local fallback refresh', {
-                            accountId: next.id,
-                            reason: 'vault credential unavailable',
-                        });
-                    }
                     const refreshError = next.lastRefreshError;
                     if (refreshError &&
                         refreshBackoffActive(refreshError, next.id, this.now(), tokenFingerprint(next.refresh))) {
@@ -2956,6 +3467,12 @@ export class FallbackAccountManager {
         for (const account of storage.accounts) {
             if (account.enabled === false || !isOAuthAccount(account))
                 continue;
+            if (this.custodyVerificationAccounts.has(account.id)) {
+                logger.debug('refresh', 'fallback OAuth background skipped vault-service verification', {
+                    accountId: account.id,
+                });
+                continue;
+            }
             if (!tokenNeedsRefresh(account, storage, this.now()) ||
                 this.isFallbackAccountVaultEnabled(account.id, storage) ||
                 this.isFallbackAccountVaultServed(account.id, storage))
@@ -3000,6 +3517,8 @@ 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()) &&
@@ -3089,7 +3608,8 @@ export class FallbackAccountManager {
         return { storage, errors };
     }
     async refreshAccount(account, storage, options = {}) {
-        if (this.isFallbackAccountVaultServed(account.id, storage))
+        if (this.isFallbackAccountVaultServed(account.id, storage) ||
+            this.isFallbackAccountVaultEnabled(account.id, storage))
             return account;
         const existing = this.refreshPromises.get(account.id);
         if (existing) {
@@ -3233,7 +3753,9 @@ export class FallbackAccountManager {
             changed = true;
             access = this.resolveFallbackAccessToken(target, storage);
         }
-        if (!access) {
+        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,
             });
@@ -3243,6 +3765,21 @@ export class FallbackAccountManager {
                 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).
@@ -3256,7 +3793,7 @@ export class FallbackAccountManager {
         const fetchStartedAt = this.now();
         let fetched = false;
         try {
-            const result = await fetchSnapshot(access.token);
+            const result = await fetchSnapshot(access?.token ?? '');
             target.quota = result.quota;
             fetched = result.fetched;
         }
@@ -3264,9 +3801,11 @@ export class FallbackAccountManager {
             const message = error instanceof Error ? error.message : String(error);
             if (!message.includes('Claude quota check failed: 401') ||
                 vaultEnabled ||
-                access.source !== 'sidecar') {
+                access?.source !== 'sidecar') {
                 throw error;
             }
+            await quotaPollLock.release();
+            quotaPollLock = null;
             target = await this.refreshAccount(account, storage, {
                 force: true,
             });
@@ -3282,6 +3821,18 @@ export class FallbackAccountManager {
                     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(access.token);
             target.quota = result.quota;