@gajae-code/ai 0.15.4 → 0.15.6

package/src/auth-storage.ts

@@ -47,6 +47,20 @@ export type ApiKeyCredential = {
 	key: string;
 };
 
+/**
+ * Extracts the bearer token from the structured API-key form used by OAuth
+ * providers that need to carry token metadata alongside the access token.
+ */
+export function extractStructuredApiKeyToken(apiKey: string): string | undefined {
+	if (!apiKey.startsWith("{")) return undefined;
+	try {
+		const parsed = JSON.parse(apiKey) as { token?: unknown };
+		return typeof parsed.token === "string" ? parsed.token : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 export interface MCPOAuthBinding {
 	/** Exact HTTP(S) origin of the MCP resource endpoint. */
 	resourceOrigin: string;
@@ -369,6 +383,7 @@ export interface AuthCredentialSnapshotEntry {
 	provider: string;
 	credential: SnapshotCredential;
 	identityKey: string | null;
+	revision?: number;
 }
 
 export type AuthCredentialIfAbsentReason =
@@ -430,8 +445,21 @@ export type OAuthRefreshLeaseClaim =
 	| { kind: "busy"; expiresAt: number }
 	| { kind: "missing" };
 
+/**
+ * Store-owned ticket that orders a provider admission against remote
+ * credential snapshot application. The ticket is intentionally released at
+ * provider admission, not response completion.
+ */
+export interface CredentialDispatchTicket {
+	release(): void;
+}
+
 export interface AuthCredentialStore {
 	close(): void;
+	refreshSnapshot?(signal?: AbortSignal): Promise<unknown>;
+	onSnapshotChanged?(listener: () => void): () => void;
+	/** Order provider admission with remote snapshot authority application. */
+	acquireCredentialDispatchTicket?(provider: Provider, signal?: AbortSignal): Promise<CredentialDispatchTicket>;
 	listAuthCredentials(provider?: string): StoredAuthCredential[];
 	/** Payload-free account inventory; active and soft-disabled rows are included. */
 	listCredentialInventory?(provider?: string): CredentialInventoryRecord[];
@@ -445,12 +473,15 @@ export interface AuthCredentialStore {
 	updateAuthCredential(id: number, credential: AuthCredential): void;
 	deleteAuthCredential(id: number, disabledCause: string): void;
 	tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string): boolean;
+	tryDisableAuthCredentialIfRevision?(id: number, expectedRevision: number, disabledCause: string): boolean;
 	replaceAuthCredentialsForProvider(provider: string, credentials: AuthCredential[]): StoredAuthCredential[];
 	upsertAuthCredentialForProvider(provider: string, credential: AuthCredential): StoredAuthCredential[];
 	upsertAuthCredentialForProviderIfAbsent(provider: string, credential: AuthCredential): AuthCredentialIfAbsentResult;
 	deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void;
 	getCache(key: string, options?: { includeExpired?: boolean }): string | null;
 	setCache(key: string, value: string, expiresAtSec: number): void;
+	/** Atomically allocate a durable sequence for broker restart epochs. */
+	allocateMonotonicSequence(key: string, expiresAtSec: number): number;
 	deleteCachePrefix?(prefix: string): void;
 	cleanExpiredCache(): void;
 	/**
@@ -514,6 +545,7 @@ export interface AuthCredentialStore {
 	 * `signal` propagates the agent's cancel down to the broker fetch.
 	 */
 	fetchUsageReports?(signal?: AbortSignal): Promise<UsageReport[] | null>;
+	fetchUsageReportsForProvider?(provider: Provider, signal?: AbortSignal): Promise<UsageReport[] | null>;
 	/** Synchronous, zero-network usage presentation peek. */
 	peekCachedUsagePresentation?(provider: Provider, credentialId: number): CachedUsagePresentation | undefined;
 	/** Record a safe usage observation after an explicit fetch/check. */
@@ -552,6 +584,21 @@ export interface AuthCredentialStore {
 	 * {@link AuthStorage.invalidateCredentialMatching} fall back to `reload()`.
 	 */
 	markCredentialSuspect?(credentialId: number, opts?: { signal?: AbortSignal }): Promise<void>;
+	/**
+	 * Optional async write hook to disable one credential through an authoritative
+	 * remote store. Remote clients MUST use this hook instead of the synchronous
+	 * local delete methods when an OAuth refresh fails definitively.
+	 *
+	 * Returns `false` when the row is already absent (for example, a peer
+	 * disabled it first). Implementations MUST NOT treat a failed remote write as
+	 * a successful local deletion.
+	 */
+	disableAuthCredentialRemote?(
+		credentialId: number,
+		disabledCause: string,
+		signal?: AbortSignal,
+		expectedRevision?: number,
+	): Promise<boolean>;
 	/**
 	 * Optional async write hook for upserting a single credential. When present,
 	 * `AuthStorage.#upsertOAuthCredential` routes through this instead of the
@@ -675,6 +722,7 @@ export type AuthStorageOptions = {
 	 * AuthStorage caller surfaces that to its own consumer unchanged.
 	 */
 	fetchUsageReports?: (signal?: AbortSignal) => Promise<UsageReport[] | null>;
+	fetchUsageReportsForProvider?: (provider: Provider, signal?: AbortSignal) => Promise<UsageReport[] | null>;
 };
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -995,9 +1043,11 @@ type UsageRequestDescriptor = {
 	baseUrl?: string;
 };
 
-type AuthApiKeyOptions = {
+export type AuthApiKeyOptions = {
 	baseUrl?: string;
 	modelId?: string;
+	/** Select config registrations owned by one caller (for example a ModelRegistry). */
+	owner?: object;
 	/**
 	 * Caller's cancel signal. Threaded into any broker-bound OAuth refresh so
 	 * `ESC` / request abort actually kills a hung broker fetch instead of
@@ -1036,6 +1086,7 @@ export interface OAuthAccess {
 export interface InvalidateCredentialMatchingOptions {
 	signal?: AbortSignal;
 	sessionId?: string;
+	owner?: object;
 }
 
 function isAbortSignalOption(
@@ -1054,17 +1105,40 @@ function safeUsageReport(report: UsageReport): SafeUsageReport {
 }
 
 function scrubHealthReason(reason: unknown, secrets: readonly string[] = []): string {
-	let value = reason instanceof Error ? reason.message : String(reason);
+	let value = (reason instanceof Error ? reason.message : String(reason)).replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "");
 	for (const secret of secrets) {
-		if (secret.length > 0) value = value.split(secret).join("[redacted]");
+		if (secret.length > 0) {
+			value = value.split(secret).join("[redacted]");
+			const escaped = [...secret].map(char => char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&"));
+			value = value.replace(new RegExp(escaped.join("\\s*"), "gu"), "[redacted]");
+		}
 	}
 	value = value.replace(/bearer\s+[^\s,;]+/gi, "Bearer [redacted]");
 	value = value.replace(/(api[_-]?key|token|secret|authorization)[=:]\s*[^\s,;]+/gi, "$1=[redacted]");
-	value = value.replace(/[\r\n\t ]+/g, " ").trim();
+	value = value
+		.replace(/[\x00-\x1f\x7f-\x9f]+/gu, " ")
+		.replace(/[\r\n\t ]+/g, " ")
+		.trim();
 	if (value.length > 256) value = `${value.slice(0, 253)}...`;
 	return value || "credential check failed";
 }
 
+/** Read optional broker error detail without allowing hostile objects to escape classification. */
+/** @internal Tested directly because hostile accessors must preserve the original error identity. */
+export function readBrokerErrorBody(error: unknown): string | undefined {
+	if (error === null || (typeof error !== "object" && typeof error !== "function")) return undefined;
+	try {
+		if (!("body" in error)) return undefined;
+		const body = (error as { body?: unknown }).body;
+		return typeof body === "string" ? body : undefined;
+	} catch {
+		// Preserve the original provider error and its terminal behavior. A proxy or
+		// throwing accessor is untrusted provider data, not a reason to replace the
+		// refresh failure with an inspection error.
+		throw error;
+	}
+}
+
 function requiresOpenAICodexProModel(provider: string, modelId: string | undefined): boolean {
 	return provider === "openai-codex" && typeof modelId === "string" && modelId.includes("-spark");
 }
@@ -1213,7 +1287,15 @@ class AuthStorageUsageCache implements UsageCache {
 // In-memory representation
 // ─────────────────────────────────────────────────────────────────────────────
 
-type StoredCredential = { id: number; credential: AuthCredential };
+type StoredCredential = { id: number; credential: AuthCredential; revision?: number };
+type IndexedStoredCredential<T extends AuthCredential = AuthCredential> = {
+	id: number;
+	credential: T;
+	index: number;
+	revision?: number;
+};
+type OAuthCredentialSelection = IndexedStoredCredential<OAuthCredential>;
+type ConfigApiKeyRegistration = { apiKey: string; envSourced: boolean; order: number };
 
 // ─────────────────────────────────────────────────────────────────────────────
 // AuthStorage Class
@@ -1231,6 +1313,18 @@ export class AuthStorage {
 	#data: Map<string, StoredCredential[]> = new Map();
 	#runtimeOverrides: Map<string, string> = new Map();
 	#configOverrides: Map<string, string> = new Map();
+	/** Effective config override registrations, including owner-scoped model registries. */
+	#configOverrideRegistrations: Map<string, Map<object, ConfigApiKeyRegistration>> = new Map();
+	#unownedConfigOverrides: Map<string, ConfigApiKeyRegistration> = new Map();
+	#configOverrideOrder = 0;
+	/**
+	 * Providers whose config override was resolved from a models.yml `apiKeyEnv`
+	 * indirection rather than a literal `apiKey` pin. An env pointer is not a
+	 * pinned secret: the pointed-to value (shell env, trusted env files) can go
+	 * stale silently, and the 401 rotation machinery cannot repair it. A stored
+	 * api_key credential from `auth login` therefore outranks it.
+	 */
+	#configOverrideEnvSourced: Set<string> = new Set();
 	#runtimeCredentialSelectors: Map<string, AuthCredentialSelector> = new Map();
 	/** Soft runtime credential preference per provider; quota failures may rotate away from it. */
 	#runtimePreferredCredentialSelectors: Map<string, AuthCredentialSelector> = new Map();
@@ -1256,12 +1350,14 @@ export class AuthStorage {
 	#credentialRankingMode: CredentialRankingMode = "balanced";
 	#usageLogger?: UsageLogger;
 	#fallbackResolver?: (provider: string) => string | undefined;
+	#ownedFallbackResolvers: Map<object, (provider: string) => string | undefined> = new Map();
 	#store: AuthCredentialStore;
 	#configValueResolver: (config: string, cacheScope?: string) => Promise<string | undefined>;
 	#resolvedStoredApiKeyValues: Map<string, Map<string, { fingerprint: string; usable: boolean }>> = new Map();
 	#storedApiKeyResolutionInFlight: Map<string, Map<string, Promise<string | undefined>>> = new Map();
 	#refreshOAuthCredentialOverride?: AuthStorageOptions["refreshOAuthCredential"];
 	#fetchUsageReportsOverride?: AuthStorageOptions["fetchUsageReports"];
+	#fetchUsageReportsForProviderOverride?: AuthStorageOptions["fetchUsageReportsForProvider"];
 	#sourceLabel?: string;
 	#credentialDisabledListeners: Set<(event: CredentialDisabledEvent) => void | Promise<void>> = new Set();
 	/**
@@ -1291,6 +1387,10 @@ export class AuthStorage {
 
 	constructor(store: AuthCredentialStore, options: AuthStorageOptions = {}) {
 		this.#store = store;
+		store.onSnapshotChanged?.(() => {
+			this.#reloadCredentialRowsFromStore();
+			void this.reload();
+		});
 		this.#configValueResolver = options.configValueResolver ?? defaultConfigValueResolver;
 		this.#usageProviderResolver = options.usageProviderResolver ?? resolveDefaultUsageProvider;
 		this.#rankingStrategyResolver = options.rankingStrategyResolver ?? resolveDefaultRankingStrategy;
@@ -1300,6 +1400,7 @@ export class AuthStorage {
 		this.#credentialRankingMode = options.credentialRankingMode ?? "balanced";
 		this.#refreshOAuthCredentialOverride = options.refreshOAuthCredential;
 		this.#fetchUsageReportsOverride = options.fetchUsageReports;
+		this.#fetchUsageReportsForProviderOverride = options.fetchUsageReportsForProvider;
 		this.#sourceLabel = options.sourceLabel;
 		if (options.onCredentialDisabled) {
 			// Constructor-registered subscribers are permanent for this AuthStorage's lifetime;
@@ -1344,6 +1445,15 @@ export class AuthStorage {
 	getGeneration(): number {
 		return this.#generation;
 	}
+	getCache(key: string, options?: { includeExpired?: boolean }): string | null {
+		return this.#store.getCache(key, options);
+	}
+	setCache(key: string, value: string, expiresAtSec: number): void {
+		this.#store.setCache(key, value, expiresAtSec);
+	}
+	allocateMonotonicSequence(key: string, expiresAtSec: number): number {
+		return this.#store.allocateMonotonicSequence(key, expiresAtSec);
+	}
 	getProviderConfigurationGeneration(provider: string): number {
 		return this.#getProviderConfigurationGeneration(provider);
 	}
@@ -1356,13 +1466,29 @@ export class AuthStorage {
 	#getProviderConfigurationGeneration(provider: string): number {
 		return this.#providerConfigurationGenerations.get(resolveOAuthStorageProvider(provider)) ?? 1;
 	}
-	getProviderEvidenceGeneration(provider: string, resolvedApiKey?: string): string {
+	#configOverrideRegistration(provider: string, owner?: object): ConfigApiKeyRegistration | undefined {
 		const storageProvider = resolveOAuthStorageProvider(provider);
+		if (owner) {
+			return (
+				this.#configOverrideRegistrations.get(storageProvider)?.get(owner) ??
+				this.#unownedConfigOverrides.get(storageProvider)
+			);
+		}
+		const apiKey = this.#configOverrides.get(storageProvider);
+		return apiKey === undefined
+			? undefined
+			: { apiKey, envSourced: this.#configOverrideEnvSourced.has(storageProvider), order: 0 };
+	}
+	#hasConfigOverride(provider: string, owner?: object): boolean {
+		return this.#configOverrideRegistration(provider, owner) !== undefined;
+	}
+	getProviderEvidenceGeneration(provider: string, resolvedApiKey?: string, owner?: object): string {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		provider = storageProvider;
 		const evidenceApiKey = resolvedApiKey;
+		const configOverride = this.#configOverrideRegistration(storageProvider, owner);
 		const storedLiteral =
-			evidenceApiKey === undefined ||
-			this.#runtimeOverrides.has(storageProvider) ||
-			this.#configOverrides.has(storageProvider)
+			evidenceApiKey === undefined || this.#runtimeOverrides.has(storageProvider) || configOverride !== undefined
 				? undefined
 				: this.#getCredentialsForProvider(storageProvider).find(
 						(credential): credential is Extract<AuthCredential, { type: "api_key" }> =>
@@ -1379,7 +1505,7 @@ export class AuthStorage {
 		}
 		let selectedCredential: ({ index: number } & StoredCredential) | undefined;
 		try {
-			selectedCredential = this.#resolveSelectedStoredCredential(provider, undefined, undefined);
+			selectedCredential = this.#resolveSelectedStoredCredential(provider, owner ? { owner } : undefined, undefined);
 		} catch {
 			return crypto
 				.createHash("sha256")
@@ -1395,7 +1521,7 @@ export class AuthStorage {
 				credential.type === "oauth" && Number.isFinite(credential.expires) && credential.expires > Date.now(),
 		);
 		const effectiveEnvKey =
-			this.#runtimeOverrides.get(provider) || this.#configOverrides.get(provider) || hasApiKey || hasUsableOAuth
+			this.#runtimeOverrides.get(provider) || configOverride?.apiKey || hasApiKey || hasUsableOAuth
 				? undefined
 				: getEnvApiKey(provider);
 		const storedApiKeyFingerprint = credentials
@@ -1543,12 +1669,21 @@ export class AuthStorage {
 		}
 	}
 
-	/** Set the selector derived from a durable session pin or a session seed. */
-	setSessionCredentialSelector(scopeId: string, provider: string, selector: AuthCredentialSelector): void {
+	/**
+	 * Set the selector derived from a durable session pin or a session seed.
+	 * `owner` scopes config-override validation to one ModelRegistry; omitted
+	 * owners retain process-wide caller semantics.
+	 */
+	setSessionCredentialSelector(
+		scopeId: string,
+		provider: string,
+		selector: AuthCredentialSelector,
+		owner?: object,
+	): void {
 		const scope = scopeId.trim();
 		if (!scope) throw new Error("Credential scope id must not be empty");
 		const storageProvider = resolveOAuthStorageProvider(provider);
-		this.#assertCredentialSelectorUsable(storageProvider, selector);
+		this.#assertCredentialSelectorUsable(storageProvider, selector, owner);
 		const selectors = this.#sessionCredentialSelectors.get(scope) ?? new Map<string, AuthCredentialSelector>();
 		selectors.set(storageProvider, selector);
 		this.#sessionCredentialSelectors.set(scope, selectors);
@@ -1607,23 +1742,32 @@ export class AuthStorage {
 	}
 
 	/** @internal Return cache provenance for an exact stored literal API-key row without resolving its value. */
-	getStoredLiteralApiKeyEvidenceGeneration(provider: string, selector: AuthCredentialSelector): string | undefined {
+	getStoredLiteralApiKeyEvidenceGeneration(
+		provider: string,
+		selector: AuthCredentialSelector,
+		owner?: object,
+	): string | undefined {
 		if (selector.kind !== "id") return undefined;
 		const storageProvider = resolveOAuthStorageProvider(provider);
-		if (this.#runtimeOverrides.has(storageProvider) || this.#configOverrides.has(storageProvider)) return undefined;
+		if (this.#runtimeOverrides.has(storageProvider) || this.#hasConfigOverride(storageProvider, owner))
+			return undefined;
 		const selected = this.#findCredentialBySelector(storageProvider, selector);
 		if (selected?.credential.type !== "api_key") return undefined;
 		const key = selected.credential.key;
 		if (!key || key.startsWith("!") || process.env[key] !== undefined) return undefined;
-		return this.getProviderEvidenceGeneration(storageProvider, key);
+		return this.getProviderEvidenceGeneration(storageProvider, key, owner);
 	}
 
-	/** Validate and canonicalize an OAuth-only selector for account pinning. */
-	resolveOAuthPinTarget(provider: string, selector: AuthCredentialSelector): OAuthPinTarget {
+	/**
+	 * Validate and canonicalize an OAuth-only selector for account pinning.
+	 * `owner` scopes config-override checks to one ModelRegistry; omitted owners
+	 * retain process-wide caller semantics.
+	 */
+	resolveOAuthPinTarget(provider: string, selector: AuthCredentialSelector, owner?: object): OAuthPinTarget {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		if (
 			this.#runtimeOverrides.has(storageProvider) ||
-			this.#configOverrides.has(storageProvider) ||
+			this.#hasConfigOverride(storageProvider, owner) ||
 			getEnvApiKey(storageProvider)
 		) {
 			throw new OAuthCredentialSelectorError(
@@ -1820,8 +1964,8 @@ export class AuthStorage {
 	}
 
 	/** Whether a provider is currently authenticated by a config API-key override. */
-	hasConfigApiKey(provider: string): boolean {
-		return Boolean(this.#configOverrides.get(resolveOAuthStorageProvider(provider)));
+	hasConfigApiKey(provider: string, owner?: object): boolean {
+		return Boolean(this.#configOverrideRegistration(provider, owner)?.apiKey);
 	}
 
 	/**
@@ -1882,7 +2026,8 @@ export class AuthStorage {
 	 * runtime API-key override (`--api-key`), or a config-sourced API key
 	 * (`models.yml` `apiKey`) would each re-decide the credential on the very
 	 * next {@link AuthStorage.getApiKey} call and make this switch appear to
-	 * silently do nothing.
+	 * silently do nothing. `owner` scopes the config-override check to one
+	 * ModelRegistry; omitted owners retain process-wide caller semantics.
 	 *
 	 * Deliberately does not touch credential-blocked state: if the target row
 	 * is still backoff-blocked from a prior quota failure, the existing
@@ -1890,14 +2035,19 @@ export class AuthStorage {
 	 * falls back to a usable account instead of re-issuing a request that would
 	 * just draw another 429/quota error.
 	 */
-	switchSessionCredential(provider: string, sessionId: string, selector: AuthCredentialSelector): void {
+	switchSessionCredential(
+		provider: string,
+		sessionId: string,
+		selector: AuthCredentialSelector,
+		owner?: object,
+	): void {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		if (this.#runtimeOverrides.has(storageProvider)) {
 			throw new Error(
 				`Cannot switch credential for ${provider}: a runtime API key override (--api-key) is active and always wins`,
 			);
 		}
-		if (this.#configOverrides.has(storageProvider)) {
+		if (this.#hasConfigOverride(storageProvider, owner)) {
 			throw new Error(
 				`Cannot switch credential for ${provider}: a config API key override (models.yml) is active and always wins`,
 			);
@@ -1926,38 +2076,122 @@ export class AuthStorage {
 	 *
 	 * Lower priority than {@link setRuntimeApiKey} so a CLI `--api-key`
 	 * still wins for the duration of a single invocation.
+	 *
+	 * `options.owner` scopes the override to one registry or other caller. The
+	 * unscoped form is process-wide and is retained for standalone callers.
+	 *
+	 * `options.envSourced` marks the value as resolved from a models.yml
+	 * `apiKeyEnv` indirection. Unlike a literal pin, an env pointer only says
+	 * where to look for a key; when the user has since run `auth login`, the
+	 * stored api_key credential is the fresher, actively-managed secret and
+	 * wins over the indirection (stored OAuth credentials still yield, so a
+	 * custom-endpoint bearer is never replaced by an upstream OAuth token).
 	 */
-	setConfigApiKey(provider: string, apiKey: string): void {
+	setConfigApiKey(provider: string, apiKey: string, options: { envSourced?: boolean; owner?: object } = {}): void {
 		const storageProvider = resolveOAuthStorageProvider(provider);
-		this.#configOverrides.set(storageProvider, apiKey);
-		this.#bumpGeneration("set-config-api-key", storageProvider);
+		const registration = {
+			apiKey,
+			envSourced: options.envSourced === true,
+			order: ++this.#configOverrideOrder,
+		};
+		if (options.owner) {
+			const registrations = this.#configOverrideRegistrations.get(storageProvider) ?? new Map();
+			registrations.set(options.owner, registration);
+			this.#configOverrideRegistrations.set(storageProvider, registrations);
+		} else {
+			this.#unownedConfigOverrides.set(storageProvider, registration);
+		}
+		this.#reconcileConfigApiKey(storageProvider, "set-config-api-key", true);
 	}
 
 	/**
 	 * Remove a single config-sourced API key override.
 	 */
-	removeConfigApiKey(provider: string): void {
+	removeConfigApiKey(provider: string, owner?: object): void {
 		const storageProvider = resolveOAuthStorageProvider(provider);
-		if (this.#configOverrides.delete(storageProvider)) this.#bumpGeneration("remove-config-api-key", storageProvider);
+		if (owner) {
+			const registrations = this.#configOverrideRegistrations.get(storageProvider);
+			if (!registrations?.delete(owner)) return;
+			if (registrations.size === 0) this.#configOverrideRegistrations.delete(storageProvider);
+		} else {
+			if (!this.#unownedConfigOverrides.delete(storageProvider)) return;
+		}
+		this.#reconcileConfigApiKey(storageProvider, "remove-config-api-key", true);
 	}
 
 	/**
-	 * Drop every config-sourced API key. Called by `ModelRegistry` before
-	 * re-parsing `models.yml` so removed entries actually disappear.
+	 * Drop config-sourced API keys. An owner removes only its own registrations;
+	 * the unscoped form remains an explicit global reset for callers that own the
+	 * entire AuthStorage instance.
 	 */
-	clearConfigApiKeys(): void {
-		const providers = [...this.#configOverrides.keys()];
-		if (providers.length === 0) return;
-		this.#configOverrides.clear();
-		for (const provider of providers) this.#bumpGeneration("clear-config-api-keys", provider);
+	clearConfigApiKeys(owner?: object): void {
+		if (owner) {
+			const providers = [...this.#configOverrideRegistrations.entries()]
+				.filter(([, registrations]) => registrations.has(owner))
+				.map(([provider]) => provider);
+			for (const provider of providers) this.removeConfigApiKey(provider, owner);
+			return;
+		}
+		const providers = new Set([
+			...this.#configOverrides.keys(),
+			...this.#unownedConfigOverrides.keys(),
+			...this.#configOverrideRegistrations.keys(),
+		]);
+		this.#unownedConfigOverrides.clear();
+		this.#configOverrideRegistrations.clear();
+		for (const provider of providers) this.#reconcileConfigApiKey(provider, "clear-config-api-keys", true);
+	}
+
+	#reconcileConfigApiKey(provider: string, reason: string, forceGeneration = false): void {
+		const previous = this.#configOverrides.get(provider);
+		const previousEnvSourced = this.#configOverrideEnvSourced.has(provider);
+		let winner: { apiKey: string; envSourced: boolean; order: number } | undefined =
+			this.#unownedConfigOverrides.get(provider);
+		for (const registration of this.#configOverrideRegistrations.get(provider)?.values() ?? []) {
+			if (!winner || registration.order > winner.order) winner = registration;
+		}
+		if (!winner) {
+			this.#configOverrides.delete(provider);
+			this.#configOverrideEnvSourced.delete(provider);
+		} else {
+			this.#configOverrides.set(provider, winner.apiKey);
+			if (winner.envSourced) this.#configOverrideEnvSourced.add(provider);
+			else this.#configOverrideEnvSourced.delete(provider);
+		}
+		const current = this.#configOverrides.get(provider);
+		const currentEnvSourced = this.#configOverrideEnvSourced.has(provider);
+		if (forceGeneration || previous !== current || previousEnvSourced !== currentEnvSourced) {
+			this.#bumpGeneration(reason, provider);
+		}
 	}
 
 	/**
 	 * Set a fallback resolver for API keys not found in storage or env vars.
 	 * Used for custom provider keys from models.json.
 	 */
-	setFallbackResolver(resolver: (provider: string) => string | undefined): void {
+	setFallbackResolver(resolver: (provider: string) => string | undefined, owner?: object): () => void {
+		if (owner) {
+			this.#ownedFallbackResolvers.set(owner, resolver);
+			return () => {
+				if (this.#ownedFallbackResolvers.get(owner) !== resolver) return;
+				this.#ownedFallbackResolvers.delete(owner);
+			};
+		}
 		this.#fallbackResolver = resolver;
+		return () => {
+			if (this.#fallbackResolver === resolver) this.#fallbackResolver = undefined;
+		};
+	}
+
+	#resolveFallback(provider: string, owner?: object): string | undefined {
+		if (owner) {
+			return this.#ownedFallbackResolvers.get(owner)?.(provider) ?? this.#fallbackResolver?.(provider);
+		}
+		for (const resolver of [...this.#ownedFallbackResolvers.values()].reverse()) {
+			const value = resolver(provider);
+			if (value !== undefined) return value;
+		}
+		return this.#fallbackResolver?.(provider);
 	}
 
 	/**
@@ -1965,11 +2199,27 @@ export class AuthStorage {
 	 */
 	async reload(): Promise<void> {
 		await this.#store.waitForReady?.();
+		this.#reloadCredentialRowsFromStore();
+	}
+
+	/**
+	 * Acquire a store-owned provider-admission ticket when the backing store
+	 * provides one (for example, a remote broker snapshot store). Local stores
+	 * need no additional ordering and return `undefined`.
+	 */
+	async acquireCredentialDispatchTicket(
+		provider: Provider,
+		signal?: AbortSignal,
+	): Promise<CredentialDispatchTicket | undefined> {
+		return this.#store.acquireCredentialDispatchTicket?.(resolveOAuthStorageProvider(provider), signal);
+	}
+
+	#reloadCredentialRowsFromStore(): void {
 		const records = this.#store.listAuthCredentials();
 		const grouped = new Map<string, StoredCredential[]>();
 		for (const record of records) {
 			const list = grouped.get(record.provider) ?? [];
-			list.push({ id: record.id, credential: record.credential });
+			list.push({ id: record.id, credential: record.credential, revision: record.revision });
 			grouped.set(record.provider, list);
 		}
 
@@ -2010,6 +2260,12 @@ export class AuthStorage {
 	#setStoredCredentials(provider: string, credentials: StoredCredential[]): void {
 		const current = this.#data.get(provider) ?? [];
 		if (storedCredentialArraysEqual(current, credentials)) return;
+		const identityOrderChanged =
+			current.length !== credentials.length ||
+			current.some(
+				(entry, index) =>
+					entry.id !== credentials[index]?.id || entry.credential.type !== credentials[index]?.credential.type,
+			);
 		this.#resolvedStoredApiKeyValues.delete(provider);
 		this.#storedApiKeyResolutionInFlight.delete(provider);
 		if (credentials.length === 0) {
@@ -2017,6 +2273,7 @@ export class AuthStorage {
 		} else {
 			this.#data.set(provider, credentials);
 		}
+		if (identityOrderChanged) this.#resetProviderAssignments(resolveOAuthStorageProvider(provider));
 		this.#bumpGeneration("credentials", provider);
 	}
 
@@ -2217,10 +2474,7 @@ export class AuthStorage {
 		}
 	}
 
-	#findCredentialBySelector(
-		provider: string,
-		selector: AuthCredentialSelector,
-	): ({ index: number } & StoredCredential) | undefined {
+	#findCredentialBySelector(provider: string, selector: AuthCredentialSelector): IndexedStoredCredential | undefined {
 		const stored = this.#getStoredCredentials(provider);
 		for (let index = 0; index < stored.length; index++) {
 			const entry = stored[index];
@@ -2263,13 +2517,13 @@ export class AuthStorage {
 		);
 	}
 
-	#assertCredentialSelectorUsable(provider: string, selector: AuthCredentialSelector): void {
+	#assertCredentialSelectorUsable(provider: string, selector: AuthCredentialSelector, owner?: object): void {
 		if (this.#runtimeOverrides.has(provider)) {
 			throw new Error(
 				`Credential selector ${this.#formatCredentialSelector(selector)} cannot be used for ${provider} while a runtime API key override is active`,
 			);
 		}
-		if (this.#configOverrides.has(provider)) {
+		if (this.#hasConfigOverride(provider, owner)) {
 			throw new Error(
 				`Credential selector ${this.#formatCredentialSelector(selector)} cannot be used for ${provider} while a config API key override is active`,
 			);
@@ -2285,8 +2539,8 @@ export class AuthStorage {
 	 * to an OAuth row specifically — the soft-preference/quota-fallback path is
 	 * meaningless for a single static API key.
 	 */
-	#assertPreferredCredentialSelectorUsable(provider: string, selector: AuthCredentialSelector): void {
-		if (this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider)) {
+	#assertPreferredCredentialSelectorUsable(provider: string, selector: AuthCredentialSelector, owner?: object): void {
+		if (this.#runtimeOverrides.has(provider) || this.#hasConfigOverride(provider, owner)) {
 			throw new Error(
 				`Preferred credential selector ${this.#formatCredentialSelector(selector)} cannot be used for ${provider} while an API key override is active`,
 			);
@@ -2303,10 +2557,10 @@ export class AuthStorage {
 		provider: string,
 		options?: AuthApiKeyOptions,
 		sessionId?: string,
-	): ({ index: number } & StoredCredential) | undefined {
+	): IndexedStoredCredential | undefined {
 		const selector = this.#getCredentialSelector(provider, options, sessionId);
 		if (!selector) return undefined;
-		this.#assertCredentialSelectorUsable(resolveOAuthStorageProvider(provider), selector);
+		this.#assertCredentialSelectorUsable(resolveOAuthStorageProvider(provider), selector, options?.owner);
 		const selected = this.#findCredentialBySelector(provider, selector);
 		if (!selected) {
 			throw new Error(`No credential found for ${provider} matching ${this.#formatCredentialSelector(selector)}`);
@@ -2323,13 +2577,23 @@ export class AuthStorage {
 		type: T,
 		sessionId?: string,
 		isUsable?: (credential: Extract<AuthCredential, { type: T }>, index: number) => boolean | undefined,
-	): { credential: Extract<AuthCredential, { type: T }>; index: number } | undefined {
-		const credentials = this.#getCredentialsForProvider(provider)
-			.map((credential, index) => ({ credential, index }))
+	): IndexedStoredCredential<Extract<AuthCredential, { type: T }>> | undefined {
+		const credentials = this.#getStoredCredentials(provider)
+			.map((entry, index) => ({ entry, index }))
 			.filter(
-				(entry): entry is { credential: Extract<AuthCredential, { type: T }>; index: number } =>
-					entry.credential.type === type,
-			);
+				(
+					item,
+				): item is {
+					entry: StoredCredential & { credential: Extract<AuthCredential, { type: T }> };
+					index: number;
+				} => item.entry.credential.type === type,
+			)
+			.map(({ entry, index }) => ({
+				id: entry.id,
+				credential: entry.credential,
+				index,
+				revision: entry.revision,
+			}));
 
 		if (credentials.length === 0) return undefined;
 
@@ -2355,12 +2619,14 @@ export class AuthStorage {
 		sessionId?: string,
 		excludedIndices: ReadonlySet<number> = new Set(),
 		includeKnownUnusable = false,
-	): { credential: ApiKeyCredential; index: number } | undefined {
-		const credentials = this.#getCredentialsForProvider(provider)
-			.map((credential, index) => ({ credential, index }))
+	): IndexedStoredCredential<ApiKeyCredential> | undefined {
+		const credentials = this.#getStoredCredentials(provider)
+			.map((entry, index) => ({ entry, index }))
 			.filter(
-				(entry): entry is { credential: ApiKeyCredential; index: number } => entry.credential.type === "api_key",
-			);
+				(item): item is { entry: StoredCredential & { credential: ApiKeyCredential }; index: number } =>
+					item.entry.credential.type === "api_key",
+			)
+			.map(({ entry, index }) => ({ id: entry.id, credential: entry.credential, index, revision: entry.revision }));
 		if (credentials.length === 0) return undefined;
 
 		const providerKey = this.#getProviderTypeKey(provider, "api_key");
@@ -2399,11 +2665,20 @@ export class AuthStorage {
 	}
 
 	/** Updates a credential at index after OAuth token refresh. */
-	#replaceCredentialAt(provider: string, index: number, credential: AuthCredential, persist = true): void {
+	#replaceCredentialAt(
+		provider: string,
+		index: number,
+		credential: AuthCredential,
+		persist = true,
+		expectedId?: number,
+	): void {
 		const entries = this.#getStoredCredentials(provider);
 		if (index < 0 || index >= entries.length) return;
 		const target = entries[index];
-		if (persist) this.#store.updateAuthCredential(target.id, credential);
+		if (expectedId !== undefined && target.id !== expectedId) {
+			throw new Error("Credential authority changed during refresh");
+		}
+		if (persist && !this.#store.refreshSnapshot) this.#store.updateAuthCredential(target.id, credential);
 		const updated = [...entries];
 		updated[index] = { id: target.id, credential };
 		this.#setStoredCredentials(provider, updated);
@@ -2434,15 +2709,18 @@ export class AuthStorage {
 		index: number,
 		expectedCredential: AuthCredential,
 		disabledCause: string,
+		expectedId?: number,
 	): boolean {
 		const entries = this.#getStoredCredentials(provider);
-		if (index < 0 || index >= entries.length) return false;
-		const target = entries[index];
+		const targetIndex = expectedId === undefined ? index : entries.findIndex(entry => entry.id === expectedId);
+		if (targetIndex < 0 || targetIndex >= entries.length) return false;
+		const target = entries[targetIndex];
+		if (expectedId !== undefined && target.id !== expectedId) return false;
 		const serialized = serializeCredential(provider, expectedCredential);
 		if (!serialized) return false;
 		const disabled = this.#store.tryDisableAuthCredentialIfMatches(target.id, serialized.data, disabledCause);
 		if (!disabled) return false;
-		const updated = entries.filter((_value, idx) => idx !== index);
+		const updated = entries.filter((_value, idx) => idx !== targetIndex);
 		this.#setStoredCredentials(provider, updated);
 		this.#clearSelectorsForRemovedCredential(provider, new Set([target.id]), entries);
 		this.#resetProviderAssignments(provider);
@@ -2479,6 +2757,35 @@ export class AuthStorage {
 		this.#emitCredentialDisabled({ provider, disabledCause });
 	}
 
+	/**
+	 * Disable one credential through an authoritative remote store and reconcile
+	 * this AuthStorage instance only after that write succeeds. Remote stores
+	 * must never be mutated through the synchronous local delete path because
+	 * their snapshots do not own persistence authority.
+	 */
+	async #disableCredentialRemotely(
+		provider: string,
+		credentialId: number,
+		disabledCause: string,
+		signal?: AbortSignal,
+		expectedRevision?: number,
+	): Promise<boolean> {
+		const disable = this.#store.disableAuthCredentialRemote?.bind(this.#store);
+		if (!disable) return false;
+		const disabled = await disable(credentialId, disabledCause, signal, expectedRevision);
+		if (!disabled) return false;
+		const entries = this.#getStoredCredentials(provider);
+		if (!entries.some(entry => entry.id === credentialId)) return true;
+		this.#setStoredCredentials(
+			provider,
+			entries.filter(entry => entry.id !== credentialId),
+		);
+		this.#clearSelectorsForRemovedCredential(provider, new Set([credentialId]), entries);
+		this.#resetProviderAssignments(provider);
+		this.#emitCredentialDisabled({ provider, disabledCause });
+		return true;
+	}
+
 	/** Clear every selector whose durable/in-memory target was just removed. */
 	#clearSelectorsForRemovedCredential(
 		provider: string,
@@ -2553,7 +2860,7 @@ export class AuthStorage {
 			: this.#store.replaceAuthCredentialsForProvider(storageProvider, deduped);
 		this.#setStoredCredentials(
 			storageProvider,
-			stored.map(record => ({ id: record.id, credential: record.credential })),
+			stored.map(record => ({ id: record.id, credential: record.credential, revision: record.revision })),
 		);
 		this.#resetProviderAssignments(storageProvider);
 	}
@@ -2568,6 +2875,7 @@ export class AuthStorage {
 				provider: entry.provider,
 				credential: redacted,
 				identityKey: resolveCredentialIdentityKey(provider, persisted),
+				...(entry.revision === undefined ? {} : { revision: entry.revision }),
 			};
 		});
 	}
@@ -2584,14 +2892,15 @@ export class AuthStorage {
 	async importCredentialIfAbsent(
 		provider: string,
 		credential: AuthCredential,
+		owner?: object,
 	): Promise<AuthCredentialIfAbsentSnapshotResult> {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		if (this.#runtimeOverrides.has(storageProvider))
 			return this.#snapshotSkipResult(storageProvider, "skipped-existing-runtime");
-		if (this.#configOverrides.has(storageProvider))
+		if (this.#hasConfigOverride(storageProvider, owner))
 			return this.#snapshotSkipResult(storageProvider, "skipped-existing-config");
 		if (getEnvApiKey(storageProvider)) return this.#snapshotSkipResult(storageProvider, "skipped-existing-env");
-		if (this.#fallbackResolver?.(storageProvider))
+		if (this.#resolveFallback(storageProvider, owner))
 			return this.#snapshotSkipResult(storageProvider, "skipped-existing-fallback");
 
 		const result = this.#store.upsertAuthCredentialRemoteIfAbsent
@@ -2599,7 +2908,7 @@ export class AuthStorage {
 			: this.#store.upsertAuthCredentialForProviderIfAbsent(storageProvider, credential);
 		this.#setStoredCredentials(
 			storageProvider,
-			result.entries.map(entry => ({ id: entry.id, credential: entry.credential })),
+			result.entries.map(entry => ({ id: entry.id, credential: entry.credential, revision: entry.revision })),
 		);
 		this.#resetProviderAssignments(storageProvider);
 		if (result.inserted) this.#invalidateUsageCacheForProvider(storageProvider);
@@ -2617,7 +2926,7 @@ export class AuthStorage {
 			: this.#store.upsertAuthCredentialForProvider(provider, credential);
 		this.#setStoredCredentials(
 			provider,
-			stored.map(record => ({ id: record.id, credential: record.credential })),
+			stored.map(record => ({ id: record.id, credential: record.credential, revision: record.revision })),
 		);
 		this.#resetProviderAssignments(provider);
 		this.#invalidateUsageCacheForProvider(provider);
@@ -2667,23 +2976,44 @@ export class AuthStorage {
 	 * Check if any form of auth is configured for a provider.
 	 * Unlike getApiKey(), this doesn't refresh OAuth tokens.
 	 */
-	#hasConfiguredAuth(storageProvider: string): boolean {
+	#hasConfiguredAuth(storageProvider: string, owner?: object): boolean {
 		if (this.hasRuntimeApiKey(storageProvider)) return true;
-		if (this.#configOverrides.has(storageProvider)) return true;
+		if (this.#hasConfigOverride(storageProvider, owner)) return true;
 		if (this.#getCredentialsForProvider(storageProvider).length > 0) return true;
 		if (getEnvApiKey(storageProvider)) return true;
-		if (this.#fallbackResolver?.(storageProvider)) return true;
+		if (this.#resolveFallback(storageProvider, owner)) return true;
 		return false;
 	}
 
-	hasAuth(provider: string, sessionId?: string): boolean {
+	disableCredentialByIdIfRevision(id: number, expectedRevision: number, disabledCause: string): boolean {
+		const cause = normalizeDisabledCause(disabledCause);
+		if (this.#store.tryDisableAuthCredentialIfRevision?.(id, expectedRevision, cause) !== true) return false;
+		for (const [provider, entries] of this.#data) {
+			if (!entries.some(entry => entry.id === id)) continue;
+			this.#setStoredCredentials(
+				provider,
+				entries.filter(entry => entry.id !== id),
+			);
+			this.#clearSelectorsForRemovedCredential(provider, new Set([id]), entries);
+			this.#resetProviderAssignments(provider);
+			this.#emitCredentialDisabled({ provider, disabledCause: cause });
+			return true;
+		}
+		return false;
+	}
+
+	hasAuth(provider: string, sessionId?: string, options?: Pick<AuthApiKeyOptions, "owner">): boolean {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		try {
-			this.#resolveSelectedStoredCredential(storageProvider, undefined, sessionId);
+			this.#resolveSelectedStoredCredential(
+				storageProvider,
+				options?.owner ? { owner: options.owner } : undefined,
+				sessionId,
+			);
 		} catch {
 			return false;
 		}
-		return this.#hasConfiguredAuth(storageProvider);
+		return this.#hasConfiguredAuth(storageProvider, options?.owner);
 	}
 
 	/**
@@ -2691,15 +3021,24 @@ export class AuthStorage {
 	 * Mirrors getApiKey selector validation, overrides, session OAuth stickiness,
 	 * cached command-key usability, OAuth retry, and environment fallback order.
 	 */
-	getEffectiveCredentialType(provider: string, sessionId?: string): AuthCredential["type"] | undefined {
+	getEffectiveCredentialType(
+		provider: string,
+		sessionId?: string,
+		options?: Pick<AuthApiKeyOptions, "owner">,
+	): AuthCredential["type"] | undefined {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		let selected: ({ index: number } & StoredCredential) | undefined;
 		try {
-			selected = this.#resolveSelectedStoredCredential(storageProvider, undefined, sessionId);
+			selected = this.#resolveSelectedStoredCredential(
+				storageProvider,
+				options?.owner ? { owner: options.owner } : undefined,
+				sessionId,
+			);
 		} catch {
 			return undefined;
 		}
-		if (this.hasRuntimeApiKey(storageProvider) || this.#configOverrides.has(storageProvider)) return "api_key";
+		if (this.hasRuntimeApiKey(storageProvider) || this.#hasConfigOverride(storageProvider, options?.owner))
+			return "api_key";
 		if (selected) return selected.credential.type;
 
 		const credentials = this.#getCredentialsForProvider(storageProvider);
@@ -2712,19 +3051,23 @@ export class AuthStorage {
 		}
 		if (credentials.some(credential => credential.type === "oauth")) return "oauth";
 		if (apiKeys.length > 0) return "api_key";
-		if (getEnvApiKey(storageProvider) || this.#fallbackResolver?.(storageProvider)) return "api_key";
+		if (getEnvApiKey(storageProvider) || this.#resolveFallback(storageProvider, options?.owner)) return "api_key";
 		return undefined;
 	}
 
 	/**
 	 * Check whether configured auth is currently usable without resolving credentials.
 	 */
-	hasUsableAuth(provider: string): boolean {
+	hasUsableAuth(provider: string, options?: Pick<AuthApiKeyOptions, "owner">): boolean {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		try {
-			const selectedCredential = this.#resolveSelectedStoredCredential(storageProvider, undefined, undefined);
+			const selectedCredential = this.#resolveSelectedStoredCredential(
+				storageProvider,
+				options?.owner ? { owner: options.owner } : undefined,
+				undefined,
+			);
 			if (this.hasRuntimeApiKey(storageProvider)) return true;
-			if (this.#configOverrides.has(storageProvider)) return true;
+			if (this.#hasConfigOverride(storageProvider, options?.owner)) return true;
 			if (selectedCredential) {
 				if (selectedCredential.credential.type === "api_key") {
 					return (
@@ -2765,7 +3108,7 @@ export class AuthStorage {
 		} catch {
 			return false;
 		}
-		return Boolean(getEnvApiKey(storageProvider) || this.#fallbackResolver?.(storageProvider));
+		return Boolean(getEnvApiKey(storageProvider) || this.#resolveFallback(storageProvider, options?.owner));
 	}
 
 	/**
@@ -2778,10 +3121,14 @@ export class AuthStorage {
 	/**
 	 * Get OAuth credentials for a provider.
 	 */
-	getOAuthCredential(provider: string, sessionId?: string): OAuthCredential | undefined {
+	getOAuthCredential(
+		provider: string,
+		sessionId?: string,
+		options?: Pick<AuthApiKeyOptions, "owner">,
+	): OAuthCredential | undefined {
 		const selected = this.#resolveSelectedStoredCredential(
 			resolveOAuthStorageProvider(provider),
-			undefined,
+			options?.owner ? { owner: options.owner } : undefined,
 			sessionId,
 		);
 		if (selected?.credential.type === "oauth") return selected.credential;
@@ -2798,7 +3145,11 @@ export class AuthStorage {
 	 * first call before any `getApiKey` has been issued, or single-credential setups).
 	 * Returns `undefined` when no OAuth credential carries an `accountId`.
 	 */
-	getOAuthAccountId(provider: string, sessionId?: string): string | undefined {
+	getOAuthAccountId(
+		provider: string,
+		sessionId?: string,
+		options?: Pick<AuthApiKeyOptions, "owner">,
+	): string | undefined {
 		provider = resolveOAuthStorageProvider(provider);
 		const allCredentials = this.#getCredentialsForProvider(provider);
 		const oauthCredentials = allCredentials.filter((c): c is OAuthCredential => c.type === "oauth");
@@ -2806,11 +3157,15 @@ export class AuthStorage {
 
 		// Runtime / config overrides bypass OAuth account_uuid attribution — the
 		// caller is authenticating with an explicit key, not the broker's OAuth.
-		if (this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider)) return undefined;
+		if (this.#runtimeOverrides.has(provider) || this.#hasConfigOverride(provider, options?.owner)) return undefined;
 
 		// Prefer the session-sticky credential when available.
 
-		const scopedSelection = this.#resolveSelectedStoredCredential(provider, undefined, sessionId);
+		const scopedSelection = this.#resolveSelectedStoredCredential(
+			provider,
+			options?.owner ? { owner: options.owner } : undefined,
+			sessionId,
+		);
 		if (scopedSelection?.credential.type === "api_key") return undefined;
 		if (scopedSelection?.credential.type === "oauth") {
 			const accountId = scopedSelection.credential.accountId;
@@ -2826,7 +3181,7 @@ export class AuthStorage {
 		// account_uuid injection would misattribute traffic. Only apply this guard when
 		// sessionPref is absent; a recorded OAuth sticky (sessionPref.type === "oauth") must
 		// NOT be blocked even if an env key also happens to exist.
-		if (!sessionPref && (getEnvApiKey(provider) || this.#fallbackResolver?.(provider))) return undefined;
+		if (!sessionPref && (getEnvApiKey(provider) || this.#resolveFallback(provider, options?.owner))) return undefined;
 		// Resolve the sticky index against the full credential list — the index is
 		// recorded against the unfiltered provider array (by #recordSessionCredential /
 		// #tryOAuthCredential), not the OAuth-only subset, so dereferencing it into the
@@ -2951,6 +3306,16 @@ export class AuthStorage {
 				credentials = await loginKimi(ctrl);
 				break;
 			}
+			case "kiro": {
+				const { loginKiro } = await import("./utils/oauth/kiro");
+				credentials = await loginKiro({
+					onAuth: (url, instructions) => ctrl.onAuth({ url, instructions }),
+					onPrompt: ctrl.onPrompt,
+					onProgress: ctrl.onProgress,
+					signal: ctrl.signal,
+				});
+				break;
+			}
 			case "kilo": {
 				const { loginKilo } = await import("./utils/oauth/kilo");
 				credentials = await loginKilo(ctrl);
@@ -2982,6 +3347,12 @@ export class AuthStorage {
 				await saveApiKeyCredential(apiKey);
 				return;
 			}
+			case "commandcode-goat": {
+				const { loginCommandCode } = await import("./utils/oauth/commandcode");
+				const apiKey = await loginCommandCode(ctrl);
+				await saveApiKeyCredential(apiKey);
+				return;
+			}
 			case "lm-studio": {
 				const { loginLmStudio } = await import("./utils/oauth/lm-studio");
 				const apiKey = await loginLmStudio(ctrl);
@@ -3525,7 +3896,9 @@ export class AuthStorage {
 			}
 			return lastGood;
 		})().finally(() => {
-			this.#usageRequestInFlight.delete(cacheKey);
+			if (this.#usageRequestInFlight.get(cacheKey) === promise) {
+				this.#usageRequestInFlight.delete(cacheKey);
+			}
 		});
 
 		this.#usageRequestInFlight.set(cacheKey, promise);
@@ -3533,6 +3906,7 @@ export class AuthStorage {
 	}
 
 	#collectUsageRequests(options?: {
+		provider?: Provider;
 		baseUrlResolver?: (provider: Provider) => string | undefined;
 	}): UsageRequestDescriptor[] {
 		const resolver = this.#usageProviderResolver;
@@ -3546,6 +3920,7 @@ export class AuthStorage {
 
 		for (const providerId of providers) {
 			const provider = providerId as Provider;
+			if (options?.provider && options.provider !== provider) continue;
 			const providerImpl = resolver(provider);
 			if (!providerImpl) continue;
 			const baseUrl = options?.baseUrlResolver?.(provider);
@@ -3745,6 +4120,7 @@ export class AuthStorage {
 	}
 
 	async fetchUsageReports(options?: {
+		provider?: Provider;
 		baseUrlResolver?: (provider: Provider) => string | undefined;
 		/** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
 		signal?: AbortSignal;
@@ -3755,6 +4131,15 @@ export class AuthStorage {
 		// `RemoteAuthCredentialStore` implements the store hook so a gateway
 		// backed by a broker automatically routes usage to the broker without
 		// needing the caller to wire it explicitly.
+		const scopedStoreFetch = options?.provider
+			? (this.#fetchUsageReportsForProviderOverride ?? this.#store.fetchUsageReportsForProvider?.bind(this.#store))
+			: undefined;
+		if (scopedStoreFetch && options?.provider) {
+			return raceUsageWithSignal(scopedStoreFetch(options.provider), options.signal);
+		}
+		if (options?.provider && (this.#fetchUsageReportsOverride || this.#store.fetchUsageReports)) {
+			throw new Error("Provider-scoped usage fetch is unavailable");
+		}
 		const override = this.#fetchUsageReportsOverride ?? this.#store.fetchUsageReports?.bind(this.#store);
 		if (override) {
 			// Reuse the in-flight map so concurrent callers (widget poll + format
@@ -3767,7 +4152,9 @@ export class AuthStorage {
 				// Don't forward the caller signal into the shared fetch — first caller's
 				// abort would otherwise cancel the upstream for every peer.
 				shared = override().finally(() => {
-					this.#usageReportsInFlight.delete(OVERRIDE_KEY);
+					if (this.#usageReportsInFlight.get(OVERRIDE_KEY) === shared) {
+						this.#usageReportsInFlight.delete(OVERRIDE_KEY);
+					}
 				});
 				this.#usageReportsInFlight.set(OVERRIDE_KEY, shared);
 			}
@@ -3836,7 +4223,9 @@ export class AuthStorage {
 			}
 			return resolved;
 		})().finally(() => {
-			this.#usageReportsInFlight.delete(cacheKey);
+			if (this.#usageReportsInFlight.get(cacheKey) === promise) {
+				this.#usageReportsInFlight.delete(cacheKey);
+			}
 		});
 
 		this.#usageReportsInFlight.set(cacheKey, promise);
@@ -4170,9 +4559,11 @@ export class AuthStorage {
 	async markUsageLimitReached(
 		provider: string,
 		sessionId: string | undefined,
-		options?: { retryAfterMs?: number; baseUrl?: string; signal?: AbortSignal },
+		options?: { retryAfterMs?: number; baseUrl?: string; signal?: AbortSignal; owner?: object },
 	): Promise<boolean> {
 		provider = resolveOAuthStorageProvider(provider);
+		const ownerOverride = this.#configOverrideRegistration(provider, options?.owner);
+		if (ownerOverride && !ownerOverride.envSourced) return false;
 		const sessionCredential = this.#getSessionCredential(provider, sessionId);
 		if (!sessionCredential) return false;
 
@@ -4272,12 +4663,12 @@ export class AuthStorage {
 		providerKey: string;
 		provider: string;
 		order: number[];
-		credentials: Array<{ credential: OAuthCredential; index: number }>;
+		credentials: OAuthCredentialSelection[];
 		options?: AuthApiKeyOptions;
 		strategy: CredentialRankingStrategy;
 	}): Promise<
 		Array<{
-			selection: { credential: OAuthCredential; index: number };
+			selection: OAuthCredentialSelection;
 			usage: UsageReport | null;
 			usageChecked: boolean;
 		}>
@@ -4285,7 +4676,7 @@ export class AuthStorage {
 		const nowMs = Date.now();
 		const { strategy } = args;
 		const ranked: Array<{
-			selection: { credential: OAuthCredential; index: number };
+			selection: OAuthCredentialSelection;
 			usage: UsageReport | null;
 			usageChecked: boolean;
 			blocked: boolean;
@@ -4433,18 +4824,29 @@ export class AuthStorage {
 			return undefined;
 		}
 		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options, sessionId);
-		const selectedOAuthCredential =
+		const selectedOAuthCredential: OAuthCredentialSelection | undefined =
 			selectedCredential?.credential.type === "oauth"
-				? { credential: selectedCredential.credential, index: selectedCredential.index }
+				? {
+						id: selectedCredential.id,
+						credential: selectedCredential.credential,
+						index: selectedCredential.index,
+						revision: selectedCredential.revision,
+					}
 				: undefined;
 		if (selectedCredential && !selectedOAuthCredential) return undefined;
 		const credentials = selectedOAuthCredential
 			? [selectedOAuthCredential]
-			: this.#getCredentialsForProvider(provider)
-					.map((credential, index) => ({ credential, index }))
+			: this.#getStoredCredentials(provider)
 					.filter(
-						(entry): entry is { credential: OAuthCredential; index: number } => entry.credential.type === "oauth",
-					);
+						(entry): entry is StoredCredential & { credential: OAuthCredential } =>
+							entry.credential.type === "oauth",
+					)
+					.map((entry, index) => ({
+						id: entry.id,
+						credential: entry.credential,
+						index,
+						revision: entry.revision,
+					}));
 
 		if (credentials.length === 0) return undefined;
 
@@ -4467,7 +4869,7 @@ export class AuthStorage {
 			? await this.#rankOAuthSelections({ providerKey, provider, order, credentials, options, strategy: strategy! })
 			: order
 					.map(idx => credentials[idx])
-					.filter((selection): selection is { credential: OAuthCredential; index: number } => Boolean(selection))
+					.filter((selection): selection is OAuthCredentialSelection => Boolean(selection))
 					.map(selection => ({ selection, usage: null, usageChecked: false }));
 
 		// Soft `--prefer-credential` preference: reorder the preferred row to the
@@ -4477,7 +4879,11 @@ export class AuthStorage {
 		if (!selectedCredential) {
 			const preferredSelector = this.#getPreferredCredentialSelector(provider, options);
 			if (preferredSelector) {
-				this.#assertPreferredCredentialSelectorUsable(resolveOAuthStorageProvider(provider), preferredSelector);
+				this.#assertPreferredCredentialSelectorUsable(
+					resolveOAuthStorageProvider(provider),
+					preferredSelector,
+					options?.owner,
+				);
 			}
 			const preferredSelection = preferredSelector
 				? this.#findCredentialBySelector(provider, preferredSelector)
@@ -4509,14 +4915,15 @@ export class AuthStorage {
 		}
 		await Promise.all(
 			candidates.map(async candidate => {
+				if (!this.#reconcileOAuthCredentialSelection(provider, candidate.selection)) return;
 				if (Date.now() + OAUTH_REFRESH_SKEW_MS < candidate.selection.credential.expires) return;
-				const latestCredential = this.#getCredentialsForProvider(provider)[candidate.selection.index];
+				const latestCredential = candidate.selection.credential;
 				if (latestCredential?.type === "oauth" && Date.now() + OAUTH_REFRESH_SKEW_MS < latestCredential.expires) {
 					candidate.selection.credential = latestCredential;
 					return;
 				}
 				try {
-					const credentialId = this.#getStoredCredentials(provider)[candidate.selection.index]?.id;
+					const credentialId = candidate.selection.id;
 					const refreshedCredentials = await this.#refreshOAuthCredential(
 						provider,
 						candidate.selection.credential,
@@ -4528,12 +4935,14 @@ export class AuthStorage {
 						...refreshedCredentials,
 						type: "oauth",
 					};
+					if (!this.#reconcileOAuthCredentialSelection(provider, candidate.selection)) return;
 					candidate.selection.credential = updated;
 					this.#replaceCredentialAt(
 						provider,
 						candidate.selection.index,
 						updated,
 						!refreshedCredentials.persistedByLease,
+						credentialId,
 					);
 				} catch {}
 			}),
@@ -4759,6 +5168,15 @@ export class AuthStorage {
 		}
 		try {
 			const refreshed = await Promise.race([refreshPromise, cancellation.promise]);
+			let effectiveRefreshed = refreshed;
+			if (this.#refreshOAuthCredentialOverride && this.#store.refreshSnapshot) {
+				await this.#store.refreshSnapshot();
+				const accepted = this.#store.listAuthCredentials(provider).find(row => row.id === credentialId)?.credential;
+				if (accepted?.type !== "oauth") {
+					throw new Error("Credential authority changed during refresh");
+				}
+				effectiveRefreshed = accepted;
+			}
 			// Return the FULL authority of the effective credential: rotated
 			// tokens from upstream plus the identity metadata and MCP binding of
 			// the (possibly guard-adopted) credential that was actually
@@ -4767,12 +5185,12 @@ export class AuthStorage {
 			// next refresh token to the wrong endpoint — or relabel rotated
 			// tokens with stale identity.
 			const authority: RefreshedOAuthCredentials = {
-				...refreshed,
-				accountId: refreshed.accountId ?? credential.accountId,
-				email: refreshed.email ?? credential.email,
-				projectId: refreshed.projectId ?? credential.projectId,
-				enterpriseUrl: refreshed.enterpriseUrl ?? credential.enterpriseUrl,
-				mcpBinding: (refreshed as RefreshedOAuthCredentials).mcpBinding ?? credential.mcpBinding,
+				...effectiveRefreshed,
+				accountId: effectiveRefreshed.accountId ?? credential.accountId,
+				email: effectiveRefreshed.email ?? credential.email,
+				projectId: effectiveRefreshed.projectId ?? credential.projectId,
+				enterpriseUrl: effectiveRefreshed.enterpriseUrl ?? credential.enterpriseUrl,
+				mcpBinding: (effectiveRefreshed as RefreshedOAuthCredentials).mcpBinding ?? credential.mcpBinding,
 			};
 			if (refreshLease) {
 				const completeLease = this.#store.completeOAuthRefreshLease?.bind(this.#store);
@@ -4801,15 +5219,28 @@ export class AuthStorage {
 		}
 	}
 
+	#reconcileOAuthCredentialSelection(provider: string, selection: OAuthCredentialSelection): boolean {
+		const entries = this.#getStoredCredentials(provider);
+		const index = entries.findIndex(entry => entry.id === selection.id);
+		if (index === -1) return false;
+		const current = entries[index];
+		if (current?.credential.type !== "oauth") return false;
+		selection.index = index;
+		selection.credential = current.credential;
+		selection.revision = current.revision;
+		return true;
+	}
+
 	async #prepareOAuthCredentialForRequest(
 		provider: string,
-		selection: { credential: OAuthCredential; index: number },
+		selection: OAuthCredentialSelection,
 		options: AuthApiKeyOptions | undefined,
 	): Promise<boolean> {
+		if (!this.#reconcileOAuthCredentialSelection(provider, selection)) return false;
 		const prepare = this.#store.prepareForRequest?.bind(this.#store);
 		if (!prepare) return true;
 		const stored = this.#getStoredCredentials(provider);
-		const selected = stored[selection.index];
+		const selected = stored.find(entry => entry.id === selection.id);
 		if (selected?.credential.type !== "oauth") return false;
 
 		const prepared = await prepare(selected.id, { signal: options?.signal });
@@ -4817,21 +5248,22 @@ export class AuthStorage {
 		const latestRows = this.#store.listAuthCredentials(provider);
 		this.#setStoredCredentials(
 			provider,
-			latestRows.map(row => ({ id: row.id, credential: row.credential })),
+			latestRows.map(row => ({ id: row.id, credential: row.credential, revision: row.revision })),
 		);
-		const latestIndex = latestRows.findIndex(row => row.id === selected.id);
+		const latestIndex = latestRows.findIndex(row => row.id === selection.id);
 		if (latestIndex === -1) return false;
 		const latest = latestRows[latestIndex];
 		if (latest?.credential.type !== "oauth") return false;
 		selection.index = latestIndex;
 		selection.credential = latest.credential;
+		selection.revision = latest.revision;
 		return true;
 	}
 
 	/** Attempts to use a single OAuth credential, checking usage and refreshing token. */
 	async #tryOAuthCredential(
 		provider: Provider,
-		selection: { credential: OAuthCredential; index: number },
+		selection: OAuthCredentialSelection,
 		providerKey: string,
 		sessionId: string | undefined,
 		options: AuthApiKeyOptions | undefined,
@@ -4851,6 +5283,7 @@ export class AuthStorage {
 			usagePrechecked = false,
 			enforceProRequirement,
 		} = usageOptions;
+		if (!this.#reconcileOAuthCredentialSelection(provider, selection)) return undefined;
 		if (!allowBlocked && this.#isCredentialBlocked(providerKey, selection.index)) {
 			return undefined;
 		}
@@ -4890,6 +5323,8 @@ export class AuthStorage {
 		}
 
 		try {
+			if (!this.#reconcileOAuthCredentialSelection(provider, selection)) return undefined;
+			const selectionCredentialId = selection.id;
 			let result: { newCredentials: OAuthCredentials; apiKey: string } | null;
 			// The refresh result carries the effective (possibly guard-adopted)
 			// credential's binding; `updated` must persist it or the next refresh
@@ -4900,7 +5335,7 @@ export class AuthStorage {
 				const refreshedCredentials = await this.#refreshOAuthCredential(
 					provider,
 					selection.credential,
-					this.#getStoredCredentials(provider)[selection.index]?.id,
+					selectionCredentialId,
 					options?.signal,
 				);
 				refreshedAuthority = refreshedCredentials;
@@ -4917,7 +5352,7 @@ export class AuthStorage {
 				const refreshedCredentials = await this.#refreshOAuthCredential(
 					provider,
 					selection.credential,
-					this.#getStoredCredentials(provider)[selection.index]?.id,
+					selectionCredentialId,
 					options?.signal,
 				);
 				refreshedAuthority = refreshedCredentials;
@@ -4938,7 +5373,13 @@ export class AuthStorage {
 				enterpriseUrl: result.newCredentials.enterpriseUrl ?? selection.credential.enterpriseUrl,
 				mcpBinding: refreshedAuthority.mcpBinding,
 			};
-			this.#replaceCredentialAt(provider, selection.index, updated, !refreshedAuthority.persistedByLease);
+			this.#replaceCredentialAt(
+				provider,
+				selection.index,
+				updated,
+				!refreshedAuthority.persistedByLease,
+				selectionCredentialId,
+			);
 
 			if ((checkUsage && !allowBlocked) || requiresProModel) {
 				const sameAccount = selection.credential.accountId === updated.accountId;
@@ -4962,10 +5403,17 @@ export class AuthStorage {
 					return undefined;
 				}
 			}
+			if (!this.#reconcileOAuthCredentialSelection(provider, selection)) return undefined;
+			if (!authCredentialEquals(selection.credential, updated)) return undefined;
 			this.#recordSessionCredential(provider, sessionId, "oauth", selection.index);
 			return { apiKey: result.apiKey, credential: updated };
 		} catch (error) {
-			const errorMsg = String(error);
+			// Auth-broker errors retain the sanitized upstream body separately from
+			// their transport message. Include that body for failure classification
+			// (the broker's 500 envelope otherwise hides `invalid_grant`) while
+			// preserving the original error object for callers and diagnostics.
+			const brokerBody = readBrokerErrorBody(error);
+			const errorMsg = [String(error), brokerBody].filter((part): part is string => Boolean(part)).join(" ");
 			// Peer-rotation recovery runs before ANY failure classification: a
 			// concurrent process may have rotated the refresh token, which
 			// invalidates the snapshot token we just attempted. Re-read the row —
@@ -4984,7 +5432,7 @@ export class AuthStorage {
 			// selection snapshot would misread that adoption as a fresh peer
 			// rotation and loop reload-retry instead of classifying the failure.
 			const attemptedRefreshToken = getAttemptedRefreshToken(error) ?? selection.credential.refresh;
-			const attemptedCredentialId = this.#getStoredCredentials(provider)[selection.index]?.id;
+			const attemptedCredentialId = selection.id;
 			if (attemptedCredentialId !== undefined) {
 				const latestRow = this.#store.listAuthCredentials(provider).find(row => row.id === attemptedCredentialId);
 				const latestCredential = latestRow?.credential;
@@ -5040,6 +5488,7 @@ export class AuthStorage {
 					selection.index,
 					selection.credential,
 					`oauth refresh failed: ${errorMsg}`,
+					attemptedCredentialId,
 				);
 				if (!disabled) {
 					// The CAS predicate compares the row's serialized `data`, so it also
@@ -5060,7 +5509,35 @@ export class AuthStorage {
 							index: selection.index,
 							credentialId: attemptedCredentialId,
 						});
-						this.#disableCredentialById(provider, attemptedCredentialId, `oauth refresh failed: ${errorMsg}`);
+						const disabledCause = `oauth refresh failed: ${errorMsg}`;
+						if (this.#store.disableAuthCredentialRemote) {
+							try {
+								const disabled = await this.#disableCredentialRemotely(
+									provider,
+									attemptedCredentialId,
+									disabledCause,
+									options?.signal,
+									selection.revision,
+								);
+								if (!disabled) {
+									await this.reload();
+									return this.#resolveOAuthSelection(provider, sessionId, options, reloadsUsed + 1);
+								}
+							} catch (disableError) {
+								// A failed broker mutation must not replace the provider's
+								// original authentication failure. We also deliberately do
+								// not remove the row locally: remote authority may still be
+								// active and can only be changed by its broker.
+								logger.warn("OAuth refresh remote disable failed", {
+									provider,
+									credentialId: attemptedCredentialId,
+									error: String(disableError),
+								});
+								throw error;
+							}
+						} else {
+							this.#disableCredentialById(provider, attemptedCredentialId, disabledCause);
+						}
 					} else {
 						logger.debug("OAuth refresh disable lost CAS; reloading after peer rotation", {
 							provider,
@@ -5159,15 +5636,27 @@ export class AuthStorage {
 	 * and get a best-effort token. For GitHub Copilot we preserve enterprise
 	 * routing metadata so discovery can hit the correct host.
 	 */
-	async peekApiKey(provider: string): Promise<string | undefined> {
+	async peekApiKey(provider: string, options?: Pick<AuthApiKeyOptions, "owner">): Promise<string | undefined> {
 		provider = resolveOAuthStorageProvider(provider);
 		const runtimeKey = this.#runtimeOverrides.get(provider);
 		if (runtimeKey) return runtimeKey;
 
-		const configKey = this.#configOverrides.get(provider);
-		if (configKey) return configKey;
+		const configOverride = this.#configOverrideRegistration(provider, options?.owner);
+		const configKey = configOverride?.apiKey;
+		if (configKey && !configOverride?.envSourced) return configKey;
 
-		const selectedCredential = this.#resolveSelectedStoredCredential(provider, undefined, undefined);
+		const selectedCredential = this.#resolveSelectedStoredCredential(
+			provider,
+			options?.owner ? { owner: options.owner } : undefined,
+			undefined,
+		);
+		if (configKey) {
+			// Env-sourced (`apiKeyEnv`) override: same precedence as getApiKey —
+			// a stored api_key credential from `auth login` wins, stored OAuth
+			// still yields to the indirection.
+			const storedApiKey = await this.#resolveStoredApiKeyOverEnvConfig(provider, selectedCredential, undefined);
+			return storedApiKey ?? configKey;
+		}
 		if (selectedCredential?.credential.type === "api_key") {
 			return this.#resolveStoredApiKey(provider, selectedCredential.credential.key);
 		}
@@ -5210,20 +5699,23 @@ export class AuthStorage {
 			}
 		}
 
-		return getEnvApiKey(provider) || this.#fallbackResolver?.(provider);
+		return getEnvApiKey(provider) || this.#resolveFallback(provider, options?.owner);
 	}
 
 	/**
 	 * Get API key for a provider.
 	 * Priority:
 	 * 1. Runtime override (CLI --api-key)
-	 * 2. Config override (models.yml `providers.<name>.apiKey`)
-	 * 3. Session-selected OAuth credential, when present
-	 * 4. Usable or unresolved API key from storage
-	 * 5. OAuth token from storage (auto-refreshed)
-	 * 6. Previously unusable command-backed API key retry
-	 * 7. Environment variable
-	 * 8. Fallback resolver (models.yml custom providers, last-resort)
+	 * 2. Config override (models.yml `providers.<name>.apiKey` literal pin)
+	 * 3. Stored api_key credential from `auth login`, when the config override
+	 *    is only an `apiKeyEnv` indirection
+	 * 4. Config override sourced from models.yml `providers.<name>.apiKeyEnv`
+	 * 5. Session-selected OAuth credential, when present
+	 * 6. Usable or unresolved API key from storage
+	 * 7. OAuth token from storage (auto-refreshed)
+	 * 8. Previously unusable command-backed API key retry
+	 * 9. Environment variable
+	 * 10. Fallback resolver (models.yml custom providers, last-resort)
 	 */
 	async getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined> {
 		provider = resolveOAuthStorageProvider(provider);
@@ -5238,8 +5730,19 @@ export class AuthStorage {
 		// (e.g. an auth-gateway) and supplied the bearer for that endpoint —
 		// honor it instead of forwarding an upstream OAuth token that the proxy
 		// won't accept.
-		const configKey = this.#configOverrides.get(provider);
-		if (configKey) return configKey;
+		const configOverride = this.#configOverrideRegistration(provider, options?.owner);
+		const configKey = configOverride?.apiKey;
+		if (configKey) {
+			if (!configOverride?.envSourced) return configKey;
+			// The override is an `apiKeyEnv` indirection, not a pinned value. A
+			// stored api_key credential from `auth login` is actively managed
+			// (validated at login, rotated on 401), while the pointed-to env
+			// value can go stale with no recovery path — prefer the stored
+			// credential. Stored OAuth credentials still yield to the override.
+			const storedApiKey = await this.#resolveStoredApiKeyOverEnvConfig(provider, selectedCredential, sessionId);
+			if (storedApiKey) return storedApiKey;
+			return configKey;
+		}
 
 		if (selectedCredential?.credential.type === "api_key") {
 			this.#recordSessionCredential(provider, sessionId, "api_key", selectedCredential.index);
@@ -5292,7 +5795,39 @@ export class AuthStorage {
 		if (sessionId) this.#sessionLastCredential.get(provider)?.delete(sessionId);
 		const envKey = getEnvApiKey(provider);
 		if (envKey) return envKey;
-		return this.#fallbackResolver?.(provider) ?? undefined;
+		return this.#resolveFallback(provider, options?.owner) ?? undefined;
+	}
+
+	/**
+	 * Resolve a stored api_key credential that outranks an env-sourced config
+	 * override (`apiKeyEnv`). Mirrors the api_key branches of {@link getApiKey}:
+	 * the selector-pinned credential first, then the round-robin/session pool.
+	 * Returns undefined when no stored api_key credential resolves, leaving the
+	 * env-sourced override in effect.
+	 */
+	async #resolveStoredApiKeyOverEnvConfig(
+		provider: string,
+		selectedCredential: ({ index: number } & StoredCredential) | undefined,
+		sessionId?: string,
+	): Promise<string | undefined> {
+		if (selectedCredential?.credential.type === "api_key") {
+			const resolved = await this.#resolveStoredApiKey(provider, selectedCredential.credential.key);
+			if (resolved) {
+				this.#recordSessionCredential(provider, sessionId, "api_key", selectedCredential.index);
+				return resolved;
+			}
+		}
+		const attemptedApiKeyIndices = new Set<number>();
+		for (;;) {
+			const apiKeySelection = this.#selectApiKeyCredential(provider, sessionId, attemptedApiKeyIndices);
+			if (!apiKeySelection) return undefined;
+			attemptedApiKeyIndices.add(apiKeySelection.index);
+			const resolved = await this.#resolveStoredApiKey(provider, apiKeySelection.credential.key);
+			if (resolved) {
+				this.#recordSessionCredential(provider, sessionId, "api_key", apiKeySelection.index);
+				return resolved;
+			}
+		}
 	}
 
 	/**
@@ -5319,7 +5854,7 @@ export class AuthStorage {
 		// Runtime / config overrides intentionally short-circuit OAuth: when the
 		// user has pinned an API key, they expect the OAuth identity to be
 		// suppressed (same contract as `getOAuthAccountId`).
-		if (this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider)) {
+		if (this.#runtimeOverrides.has(provider) || this.#hasConfigOverride(provider, options?.owner)) {
 			return undefined;
 		}
 		const resolved = await this.#resolveOAuthSelection(provider, sessionId, options);
@@ -5335,13 +5870,7 @@ export class AuthStorage {
 	}
 
 	#extractStructuredApiKeyToken(apiKey: string): string | undefined {
-		if (!apiKey.startsWith("{")) return undefined;
-		try {
-			const parsed = JSON.parse(apiKey) as { token?: unknown };
-			return typeof parsed.token === "string" ? parsed.token : undefined;
-		} catch {
-			return undefined;
-		}
+		return extractStructuredApiKeyToken(apiKey);
 	}
 
 	async #credentialMatchesApiKey(provider: string, credential: AuthCredential, apiKey: string): Promise<boolean> {
@@ -5371,6 +5900,9 @@ export class AuthStorage {
 		const signal = isAbortSignalOption(optionsOrSignal) ? optionsOrSignal : optionsOrSignal?.signal;
 		const sessionId = isAbortSignalOption(optionsOrSignal) ? undefined : optionsOrSignal?.sessionId;
 		const storageProvider = resolveOAuthStorageProvider(provider);
+		const owner = isAbortSignalOption(optionsOrSignal) ? undefined : optionsOrSignal?.owner;
+		const ownerOverride = this.#configOverrideRegistration(storageProvider, owner);
+		if (ownerOverride && !ownerOverride.envSourced && ownerOverride.apiKey === apiKey) return false;
 		const stored = this.#getStoredCredentials(storageProvider);
 		let matched: { id: number; type: AuthCredential["type"]; index: number } | undefined;
 		for (let index = 0; index < stored.length; index++) {
@@ -5403,7 +5935,7 @@ export class AuthStorage {
 		const latestRows = this.#store.listAuthCredentials(storageProvider);
 		this.#setStoredCredentials(
 			storageProvider,
-			latestRows.map(row => ({ id: row.id, credential: row.credential })),
+			latestRows.map(row => ({ id: row.id, credential: row.credential, revision: row.revision })),
 		);
 		return true;
 	}
@@ -5430,6 +5962,7 @@ export class AuthStorage {
 					provider,
 					credential: redacted,
 					identityKey: resolveCredentialIdentityKey(provider, credential),
+					...(entry.revision === undefined ? {} : { revision: entry.revision }),
 				});
 			}
 		}
@@ -5565,12 +6098,14 @@ export class AuthStorage {
 				enterpriseUrl: refreshed.enterpriseUrl ?? target.credential.enterpriseUrl,
 				mcpBinding: refreshed.mcpBinding,
 			};
-			this.#replaceCredentialAt(provider, index, updated, !refreshed.persistedByLease);
+			this.#replaceCredentialAt(provider, index, updated, !refreshed.persistedByLease, id);
+			const persisted = this.#store.listAuthCredentials(provider).find(entry => entry.id === id);
 			return {
 				id,
 				provider,
 				credential: { ...updated, refresh: REMOTE_REFRESH_SENTINEL },
 				identityKey: resolveCredentialIdentityKey(provider, updated),
+				...(persisted?.revision === undefined ? {} : { revision: persisted.revision }),
 			};
 		}
 		throw new Error(`No credential with id=${id}`);
@@ -5610,7 +6145,7 @@ export class AuthStorage {
 		const stored = this.#store.upsertAuthCredentialForProvider(provider, credential);
 		this.#setStoredCredentials(
 			provider,
-			stored.map(entry => ({ id: entry.id, credential: entry.credential })),
+			stored.map(entry => ({ id: entry.id, credential: entry.credential, revision: entry.revision })),
 		);
 		this.#resetProviderAssignments(provider);
 		return this.#toSnapshotEntries(provider, stored);
@@ -5621,26 +6156,39 @@ export class AuthStorage {
 	 *
 	 * Surfaces four layers, highest precedence first:
 	 *   1. Runtime override (`--api-key`).
-	 *   2. Config override (`models.yml` `providers.<name>.apiKey`).
+	 *   2. Config override (`models.yml` `providers.<name>.apiKey` literal pin,
+	 *      or an `apiKeyEnv` indirection when no stored api_key credential
+	 *      outranks it).
 	 *   3. Stored credential (the one this session is currently sticky to, or the
 	 *      one round-robin would pick next when no session id is supplied).
 	 *   4. Env var / fallback resolver — when no stored credential exists.
 	 *
 	 * The string is purely informational; consumers must not parse it.
 	 */
-	describeCredentialSource(provider: string, sessionId?: string): string | undefined {
+	describeCredentialSource(
+		provider: string,
+		sessionId?: string,
+		options?: Pick<AuthApiKeyOptions, "owner">,
+	): string | undefined {
+		provider = resolveOAuthStorageProvider(provider);
 		if (this.#runtimeOverrides.has(provider)) {
 			return "runtime override (--api-key)";
 		}
-		if (this.#configOverrides.has(provider)) {
-			return "config override (models.yml)";
+		const configOverride = this.#configOverrideRegistration(provider, options?.owner);
+		if (configOverride) {
+			// An `apiKeyEnv` indirection loses to a stored api_key credential
+			// (see getApiKey); describe the credential that actually wins.
+			const shadowed = this.#getStoredCredentials(provider).some(entry => entry.credential.type === "api_key");
+			if (!configOverride.envSourced || !shadowed) {
+				return "config override (models.yml)";
+			}
 		}
 
 		const baseLabel = this.#sourceLabel ?? "local store";
 		const stored = this.#getStoredCredentials(provider);
 		if (stored.length === 0) {
 			if (getEnvApiKey(provider)) return `env ${baseLabel ? `(fallback over ${baseLabel})` : ""}`.trim();
-			if (this.#fallbackResolver?.(provider) !== undefined) return `fallback resolver`;
+			if (this.#resolveFallback(provider, options?.owner) !== undefined) return `fallback resolver`;
 			return undefined;
 		}
 
@@ -5874,6 +6422,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 	#updateStmt: Statement;
 	#deleteStmt: Statement;
 	#deleteIfMatchesStmt: Statement;
+	#deleteIfRevisionStmt: Statement;
 	#deleteByProviderStmt: Statement;
 	#hardDeleteStmt: Statement;
 	#getCacheStmt: Statement;
@@ -5914,6 +6463,9 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		this.#deleteIfMatchesStmt = this.#db.prepare(
 			`UPDATE auth_credentials SET disabled_cause = ?, revision = revision + 1, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ? AND data = ? AND disabled_cause IS NULL`,
 		);
+		this.#deleteIfRevisionStmt = this.#db.prepare(
+			`UPDATE auth_credentials SET disabled_cause = ?, revision = revision + 1, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ? AND revision = ? AND disabled_cause IS NULL`,
+		);
 		this.#deleteByProviderStmt = this.#db.prepare(
 			`UPDATE auth_credentials SET disabled_cause = ?, revision = revision + 1, updated_at = ${SQLITE_NOW_EPOCH} WHERE provider = ? AND disabled_cause IS NULL`,
 		);
@@ -6350,6 +6902,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 				id: row.id,
 				credential: deserializeCredential(row),
 				identityKey: resolveRowCredentialIdentityKey(providerName, row),
+				revision: row.revision,
 			}));
 
 			const result: StoredAuthCredential[] = [];
@@ -6366,7 +6919,13 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 				if (match) {
 					matchedExistingIds.add(match.id);
 					this.#updateStmt.run(serialized.credentialType, serialized.data, serialized.identityKey, match.id);
-					result.push({ id: match.id, provider: providerName, credential, disabledCause: null });
+					result.push({
+						id: match.id,
+						provider: providerName,
+						credential,
+						disabledCause: null,
+						revision: match.revision + 1,
+					});
 				} else {
 					const row = this.#insertStmt.get(
 						providerName,
@@ -6375,7 +6934,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 						serialized.identityKey,
 					) as { id?: number } | undefined;
 					if (row?.id) {
-						result.push({ id: row.id, provider: providerName, credential, disabledCause: null });
+						result.push({ id: row.id, provider: providerName, credential, disabledCause: null, revision: 1 });
 					}
 				}
 			}
@@ -6468,6 +7027,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 					id: number;
 					credential: AuthCredential;
 					identityKey: string | null;
+					revision: number;
 				}> = [];
 				for (const row of existingRows) {
 					const activeCredential = deserializeCredential(row);
@@ -6476,6 +7036,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 						id: row.id,
 						credential: activeCredential,
 						identityKey: resolveRowCredentialIdentityKey(providerName, row),
+						revision: row.revision,
 					});
 				}
 				if (existing.length > 0) {
@@ -6508,6 +7069,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 							provider: providerName,
 							credential: row.credential,
 							disabledCause: null,
+							revision: row.revision,
 						})),
 					};
 				}
@@ -6595,6 +7157,17 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		}
 	}
 
+	tryDisableAuthCredentialIfRevision(id: number, expectedRevision: number, disabledCause: string): boolean {
+		try {
+			const result = this.#deleteIfRevisionStmt.run(normalizeDisabledCause(disabledCause), id, expectedRevision) as {
+				changes: number;
+			};
+			return result.changes === 1;
+		} catch {
+			return false;
+		}
+	}
+
 	deleteAuthCredentialsForProvider(provider: string, disabledCause: string): void {
 		try {
 			this.#deleteByProviderStmt.run(normalizeDisabledCause(disabledCause), provider);
@@ -6621,6 +7194,17 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		}
 	}
 
+	allocateMonotonicSequence(key: string, expiresAtSec: number): number {
+		const allocate = this.#db.transaction(() => {
+			const row = this.#getCacheIncludingExpiredStmt.get(key) as { value?: string } | undefined;
+			const current = Number(row?.value);
+			const next = Number.isSafeInteger(current) && current >= 0 ? current + 1 : 1;
+			this.#upsertCacheStmt.run(key, String(next), expiresAtSec);
+			return next;
+		});
+		return allocate();
+	}
+
 	deleteCachePrefix(prefix: string): void {
 		if (prefix.length === 0) return;
 		try {
@@ -6715,6 +7299,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		this.#updateStmt.finalize();
 		this.#deleteStmt.finalize();
 		this.#deleteIfMatchesStmt.finalize();
+		this.#deleteIfRevisionStmt.finalize();
 		this.#deleteByProviderStmt.finalize();
 		this.#hardDeleteStmt.finalize();
 		this.#getCacheStmt.finalize();