@gajae-code/ai 0.16.7 → 0.17.1

package/src/auth-storage.ts

@@ -26,12 +26,6 @@ import type {
 	UsageReport,
 } from "./usage";
 
-import {
-	classifyOpenAICodexProEntitlement,
-	formatOpenAICodexChatGPTEntitlementError,
-	requiresOpenAICodexProModel,
-	requiresStrictOpenAICodexProModel,
-} from "./utils/codex-entitlement";
 import { getOAuthApiKey, getOAuthProvider, refreshOAuthToken, resolveOAuthStorageProvider } from "./utils/oauth";
 import { loginDeepInfra } from "./utils/oauth/deepinfra";
 import { loginDeepSeek } from "./utils/oauth/deepseek";
@@ -1146,28 +1140,6 @@ export function readBrokerErrorBody(error: unknown): string | undefined {
 	}
 }
 
-function getUsagePlanType(report: UsageReport | null): string | undefined {
-	const metadata = report?.metadata;
-	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return undefined;
-	const planType = (metadata as { planType?: unknown }).planType;
-	return typeof planType === "string" ? planType.toLowerCase() : undefined;
-}
-
-function getOpenAICodexPlanPriority(report: UsageReport | null): number {
-	const entitlement = classifyOpenAICodexProEntitlement(getUsagePlanType(report));
-	if (entitlement === "entitled") return 0;
-	if (entitlement === "denied") return 2;
-	return 1;
-}
-
-function hasOpenAICodexProPlan(report: UsageReport | null): boolean {
-	return classifyOpenAICodexProEntitlement(getUsagePlanType(report)) === "entitled";
-}
-
-function hasKnownOpenAICodexNonProPlan(report: UsageReport | null): boolean {
-	return classifyOpenAICodexProEntitlement(getUsagePlanType(report)) === "denied";
-}
-
 function resolveDefaultRankingStrategy(provider: Provider): CredentialRankingStrategy | undefined {
 	return DEFAULT_RANKING_STRATEGIES.get(provider);
 }
@@ -1210,6 +1182,28 @@ function raceUsageWithSignal<T>(promise: Promise<T>, signal: AbortSignal | undef
 	});
 }
 
+/**
+ * Distinguish an internal deadline from a caller-owned cancellation.
+ *
+ * `AbortSignal.timeout(...)` (and `AbortSignal.any([...])` when the timeout leg
+ * fires) aborts with a `TimeoutError` reason, whereas a caller's
+ * `AbortController.abort()` surfaces an `AbortError` (or a custom reason). The
+ * probe callers (`#checkCredentialHealth`, `#fetchUsageUncached`) pass a
+ * timeout-derived signal: a refresh cut short by that internal deadline is a
+ * genuine failure — the rotating refresh token may already have been consumed
+ * upstream — and MUST update the replay guard. Only a true caller cancellation
+ * may skip the guard update.
+ */
+function isTimeoutAbort(signal: AbortSignal): boolean {
+	const reason: unknown = signal.reason;
+	return (
+		typeof reason === "object" &&
+		reason !== null &&
+		"name" in reason &&
+		(reason as { name?: unknown }).name === "TimeoutError"
+	);
+}
+
 function raceCredentialRefreshWithSignal<T>(
 	promise: Promise<T>,
 	signal: AbortSignal | undefined,
@@ -1225,6 +1219,17 @@ function raceCredentialRefreshWithSignal<T>(
 	});
 }
 
+function oauthNonTokenFieldsEqual(left: OAuthCredential, right: OAuthCredential): boolean {
+	return (
+		left.accountId === right.accountId &&
+		left.email === right.email &&
+		left.projectId === right.projectId &&
+		left.enterpriseUrl === right.enterpriseUrl &&
+		left.mcpBinding?.resourceOrigin === right.mcpBinding?.resourceOrigin &&
+		left.mcpBinding?.tokenEndpoint === right.mcpBinding?.tokenEndpoint
+	);
+}
+
 function authCredentialEquals(left: AuthCredential, right: AuthCredential): boolean {
 	if (left.type !== right.type) return false;
 	if (left.type === "api_key") {
@@ -1235,15 +1240,60 @@ function authCredentialEquals(left: AuthCredential, right: AuthCredential): bool
 		left.access === right.access &&
 		left.refresh === right.refresh &&
 		left.expires === right.expires &&
-		left.accountId === right.accountId &&
-		left.email === right.email &&
-		left.projectId === right.projectId &&
-		left.enterpriseUrl === right.enterpriseUrl &&
-		left.mcpBinding?.resourceOrigin === right.mcpBinding?.resourceOrigin &&
-		left.mcpBinding?.tokenEndpoint === right.mcpBinding?.tokenEndpoint
+		oauthNonTokenFieldsEqual(left, right)
 	);
 }
 
+function parseStructuredOAuthKey(apiKey: string): { token: string; projectId?: string } | undefined {
+	if (!apiKey.startsWith("{")) return undefined;
+	try {
+		const parsed = JSON.parse(apiKey) as { token?: unknown; projectId?: unknown };
+		if (typeof parsed.token !== "string") return undefined;
+		return { token: parsed.token, projectId: typeof parsed.projectId === "string" ? parsed.projectId : undefined };
+	} catch {
+		return undefined;
+	}
+}
+
+// Identity keys decode token claims and evidence is computed on hot catalog paths. Key the memo by every
+// field that can feed the identity so an in-place credential mutation can never reuse a stale result.
+const OAUTH_IDENTITY_MEMO_LIMIT = 256;
+const oauthIdentityMemo = new Map<string, string | null>();
+
+function resolveMemoizedOAuthIdentityKey(provider: string, credential: OAuthCredential): string | null {
+	const memoKey = [
+		provider,
+		credential.accountId ?? "",
+		credential.email ?? "",
+		credential.projectId ?? "",
+		credential.enterpriseUrl ?? "",
+		credential.access,
+		credential.refresh,
+	].join("\u0000");
+	const cached = oauthIdentityMemo.get(memoKey);
+	if (cached !== undefined) return cached;
+	const identityKey = resolveCredentialIdentityKey(provider, credential);
+	if (oauthIdentityMemo.size >= OAUTH_IDENTITY_MEMO_LIMIT) oauthIdentityMemo.clear();
+	oauthIdentityMemo.set(memoKey, identityKey);
+	return identityKey;
+}
+
+function isOAuthTokenRotationOnly(provider: string, left: StoredCredential[], right: StoredCredential[]): boolean {
+	if (left.length !== right.length || left.length === 0) return false;
+	for (let index = 0; index < left.length; index += 1) {
+		const leftEntry = left[index];
+		const rightEntry = right[index];
+		if (!leftEntry || !rightEntry || leftEntry.id !== rightEntry.id) return false;
+		if (authCredentialEquals(leftEntry.credential, rightEntry.credential)) continue;
+		const previous = leftEntry.credential;
+		const next = rightEntry.credential;
+		if (previous.type !== "oauth" || next.type !== "oauth" || !oauthNonTokenFieldsEqual(previous, next)) return false;
+		const identityKey = resolveMemoizedOAuthIdentityKey(provider, previous);
+		if (!identityKey || identityKey !== resolveMemoizedOAuthIdentityKey(provider, next)) return false;
+	}
+	return true;
+}
+
 function storedCredentialArraysEqual(left: StoredCredential[], right: StoredCredential[]): boolean {
 	if (left.length !== right.length) return false;
 	for (let index = 0; index < left.length; index += 1) {
@@ -1340,6 +1390,8 @@ export class AuthStorage {
 	#sessionCredentialSelectors: Map<string, Map<string, AuthCredentialSelector>> = new Map();
 	/** Explicit AUTO masks suppress both scoped and process-global selectors for a scope/provider. */
 	#sessionCredentialAutoMasks: Map<string, Set<string>> = new Map();
+	/** Hard-pin failures that must remain unavailable until an explicit user choice. */
+	#sessionCredentialUnavailable: Map<string, Map<string, AuthCredentialSelector>> = new Map();
 	/** Reference counts for sessions sharing one credential scope (top-level + subagents). */
 	#credentialScopeLeases: Map<string, number> = new Map();
 	/** Tracks next credential index per provider:type key for round-robin distribution (non-session use). */
@@ -1381,6 +1433,8 @@ export class AuthStorage {
 	#providerGenerations = new Map<string, number>();
 	#providerConfigurationGenerations = new Map<string, number>();
 	#providerOAuthRefreshGenerations = new Map<string, number>();
+	/** Recent access tokens replaced by same-account rotation, keyed by storage provider and row id. */
+	#rotatedOAuthAccessTokens = new Map<string, string[]>();
 	#generationListeners: Set<(generation: number) => void> = new Set();
 	#oauthRefreshInFlight: Map<number, Promise<AuthCredentialSnapshotEntry>> = new Map();
 	#oauthCredentialRefreshInFlight: Map<number, Promise<RefreshedOAuthCredentials>> = new Map();
@@ -1446,6 +1500,7 @@ export class AuthStorage {
 		this.#credentialScopeLeases.clear();
 		this.#sessionCredentialSelectors.clear();
 		this.#sessionCredentialAutoMasks.clear();
+		this.#sessionCredentialUnavailable.clear();
 		this.#sessionLastCredential.clear();
 		this.#store.close();
 	}
@@ -1520,9 +1575,10 @@ export class AuthStorage {
 				.update(`${this.#getProviderGeneration(storageProvider)}\u0000unavailable-selector`)
 				.digest("hex");
 		}
-		const credentials = selectedCredential
-			? [selectedCredential.credential]
-			: this.#getCredentialsForProvider(provider);
+		const storedEntries: StoredCredential[] = selectedCredential
+			? [selectedCredential]
+			: this.#getStoredCredentials(provider);
+		const credentials = storedEntries.map(entry => entry.credential);
 		const hasApiKey = credentials.some(credential => credential.type === "api_key");
 		const hasUsableOAuth = credentials.some(
 			credential =>
@@ -1545,14 +1601,60 @@ export class AuthStorage {
 				}`;
 			})
 			.join("\u0001");
-		const storedOAuthFingerprint = credentials
-			.filter((credential): credential is Extract<AuthCredential, { type: "oauth" }> => credential.type === "oauth")
-			.map(credential => `${credential.expires}\u0000${credential.expires > Date.now() ? "usable" : "expired"}`)
+		// Account-backed OAuth rows fingerprint by row, identity, request metadata, and usability rather than token
+		// expiry, so a refresh keeps discovery evidence valid. Rows without a resolvable identity keep the expiry
+		// fingerprint.
+		const now = Date.now();
+		const oauthIdentityKeys = storedEntries.map(entry =>
+			entry.credential.type === "oauth" ? resolveMemoizedOAuthIdentityKey(storageProvider, entry.credential) : null,
+		);
+		const storedOAuthFingerprint = storedEntries
+			.map((entry, index) => {
+				const credential = entry.credential;
+				if (credential.type !== "oauth") return undefined;
+				const usability = credential.expires > now ? "usable" : "expired";
+				const identityKey = oauthIdentityKeys[index];
+				if (!identityKey) return `${credential.expires}\u0000${usability}`;
+				return [
+					entry.id,
+					identityKey,
+					usability,
+					credential.projectId ?? "",
+					credential.enterpriseUrl ?? "",
+					credential.mcpBinding?.resourceOrigin ?? "",
+					credential.mcpBinding?.tokenEndpoint ?? "",
+				].join("\u0000");
+			})
+			.filter(fingerprint => fingerprint !== undefined)
 			.join("\u0001");
+		// A key resolved from an account-backed OAuth row is covered by that row's fingerprint. Hashing the raw
+		// token, or a structured key carrying it, would make every refresh look like a different credential.
+		const identityBackedEntries = storedEntries.filter((_, index) => oauthIdentityKeys[index]);
+		let oauthKeyEntry: StoredCredential | undefined;
+		if (evidenceApiKey !== undefined && identityBackedEntries.length > 0) {
+			const structuredKey = parseStructuredOAuthKey(evidenceApiKey);
+			const keyToken = structuredKey ? structuredKey.token : evidenceApiKey;
+			// Callers may still hold the key they resolved before the row rotated, so the row's recently rotated
+			// tokens map to it as well. A structured key for another project stays distinct.
+			const matchesRow = (entry: StoredCredential, tokens: readonly string[] | undefined): boolean => {
+				const credential = entry.credential;
+				if (credential.type !== "oauth" || keyToken.length === 0 || !tokens?.includes(keyToken)) return false;
+				return structuredKey?.projectId === undefined || structuredKey.projectId === credential.projectId;
+			};
+			// Current tokens win over rotated ones so a row's old token can never shadow another row's live token.
+			oauthKeyEntry =
+				identityBackedEntries.find(
+					entry => entry.credential.type === "oauth" && matchesRow(entry, [entry.credential.access]),
+				) ??
+				identityBackedEntries.find(entry =>
+					matchesRow(entry, this.#rotatedOAuthAccessTokens.get(`${storageProvider}\u0000${entry.id}`)),
+				);
+		}
+		const evidenceKeyFingerprint = oauthKeyEntry ? `oauth-row:${oauthKeyEntry.id}` : (evidenceApiKey ?? "");
 		return crypto
 			.createHash("sha256")
 			.update(
-				`${this.#getProviderGeneration(storageProvider)}\u0000${effectiveEnvKey ?? ""}\u0000${storedApiKeyFingerprint}\u0000${storedOAuthFingerprint}\u0000${evidenceApiKey ?? ""}`,
+				`${this.#getProviderGeneration(storageProvider)}\u0000${effectiveEnvKey ?? ""}\u0000${storedApiKeyFingerprint}\u0000${storedOAuthFingerprint}\u0000${evidenceKeyFingerprint}`,
 			)
 			.digest("hex");
 	}
@@ -1672,6 +1774,7 @@ export class AuthStorage {
 		this.#credentialScopeLeases.delete(scope);
 		this.#sessionCredentialSelectors.delete(scope);
 		this.#sessionCredentialAutoMasks.delete(scope);
+		this.#sessionCredentialUnavailable.delete(scope);
 		for (const [provider, sessions] of this.#sessionLastCredential) {
 			if (!sessions.delete(scope)) continue;
 			if (sessions.size === 0) this.#sessionLastCredential.delete(provider);
@@ -1693,6 +1796,7 @@ export class AuthStorage {
 		if (!scope) throw new Error("Credential scope id must not be empty");
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		this.#assertCredentialSelectorUsable(storageProvider, selector, owner);
+		this.#sessionCredentialUnavailable.get(scope)?.delete(storageProvider);
 		const selectors = this.#sessionCredentialSelectors.get(scope) ?? new Map<string, AuthCredentialSelector>();
 		selectors.set(storageProvider, selector);
 		this.#sessionCredentialSelectors.set(scope, selectors);
@@ -1706,6 +1810,7 @@ export class AuthStorage {
 		if (!scope) throw new Error("Credential scope id must not be empty");
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		this.#sessionCredentialSelectors.get(scope)?.delete(storageProvider);
+		this.#sessionCredentialUnavailable.get(scope)?.delete(storageProvider);
 		const masks = this.#sessionCredentialAutoMasks.get(scope) ?? new Set<string>();
 		masks.add(storageProvider);
 		this.#sessionCredentialAutoMasks.set(scope, masks);
@@ -1725,6 +1830,28 @@ export class AuthStorage {
 		if (changed) this.#bumpGeneration("clear-session-credential-selector", storageProvider);
 	}
 
+	/** Preserve a failed hard pin as unavailable instead of allowing AUTO fallback. */
+	markSessionCredentialUnavailable(scopeId: string, provider: string, selector: AuthCredentialSelector): void {
+		const scope = scopeId.trim();
+		if (!scope) throw new Error("Credential scope id must not be empty");
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		const unavailable = this.#sessionCredentialUnavailable.get(scope) ?? new Map<string, AuthCredentialSelector>();
+		unavailable.set(storageProvider, selector);
+		this.#sessionCredentialUnavailable.set(scope, unavailable);
+		this.#sessionCredentialSelectors.get(scope)?.delete(storageProvider);
+		this.#sessionCredentialAutoMasks.get(scope)?.delete(storageProvider);
+		this.#bumpGeneration("mark-session-credential-unavailable", storageProvider);
+	}
+
+	/** Return a failed hard pin retained for this scope, if any. */
+	hasSessionCredentialUnavailable(provider: string, scopeId?: string): boolean {
+		const scope = scopeId?.trim();
+		return (
+			scope !== undefined &&
+			this.#sessionCredentialUnavailable.get(scope)?.has(resolveOAuthStorageProvider(provider)) === true
+		);
+	}
+
 	/** Whether the effective selection for a scope is explicitly pinned (AUTO masks are not pins). */
 	hasSessionCredentialSelector(provider: string, scopeId?: string): boolean {
 		if (!scopeId) return false;
@@ -2277,15 +2404,45 @@ export class AuthStorage {
 				(entry, index) =>
 					entry.id !== credentials[index]?.id || entry.credential.type !== credentials[index]?.credential.type,
 			);
-		this.#resolvedStoredApiKeyValues.delete(provider);
-		this.#storedApiKeyResolutionInFlight.delete(provider);
+		// Refreshing tokens for the same OAuth account is not a configuration change: keep the provider's
+		// evidence and configuration generations so catalogs discovered for that account stay current.
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		const tokenRotationOnly =
+			!identityOrderChanged && isOAuthTokenRotationOnly(storageProvider, current, credentials);
+		if (tokenRotationOnly) {
+			this.#rememberRotatedAccessTokens(storageProvider, current, credentials);
+		} else {
+			this.#forgetRotatedAccessTokens(storageProvider);
+			this.#resolvedStoredApiKeyValues.delete(provider);
+			this.#storedApiKeyResolutionInFlight.delete(provider);
+		}
 		if (credentials.length === 0) {
 			this.#data.delete(provider);
 		} else {
 			this.#data.set(provider, credentials);
 		}
-		if (identityOrderChanged) this.#resetProviderAssignments(resolveOAuthStorageProvider(provider));
-		this.#bumpGeneration("credentials", provider);
+		if (identityOrderChanged) this.#resetProviderAssignments(storageProvider);
+		if (tokenRotationOnly) this.#bumpGeneration("oauth-token-rotation");
+		else this.#bumpGeneration("credentials", provider);
+	}
+
+	#rememberRotatedAccessTokens(storageProvider: string, previous: StoredCredential[], next: StoredCredential[]): void {
+		for (let index = 0; index < previous.length; index += 1) {
+			const before = previous[index];
+			const after = next[index];
+			if (before?.credential.type !== "oauth" || after?.credential.type !== "oauth") continue;
+			if (!before.credential.access || before.credential.access === after.credential.access) continue;
+			const key = `${storageProvider}\u0000${before.id}`;
+			const history = [before.credential.access, ...(this.#rotatedOAuthAccessTokens.get(key) ?? [])].slice(0, 4);
+			this.#rotatedOAuthAccessTokens.set(key, history);
+		}
+	}
+
+	#forgetRotatedAccessTokens(storageProvider: string): void {
+		const prefix = `${storageProvider}\u0000`;
+		for (const key of [...this.#rotatedOAuthAccessTokens.keys()]) {
+			if (key.startsWith(prefix)) this.#rotatedOAuthAccessTokens.delete(key);
+		}
 	}
 
 	#resolveOAuthDedupeIdentityKey(provider: string, credential: OAuthCredential): string | null {
@@ -2692,10 +2849,15 @@ export class AuthStorage {
 		if (persist && !this.#store.refreshSnapshot) this.#store.updateAuthCredential(target.id, credential);
 		const updated = [...entries];
 		updated[index] = { id: target.id, credential };
+		const configurationGeneration = this.#getProviderConfigurationGeneration(provider);
 		this.#setStoredCredentials(provider, updated);
+		// Callers use the refresh generation to discount configuration bumps caused by a refresh, so it only
+		// advances when this refresh bumped configuration; token rotation for a known account does not.
 		if (
+			configurationGeneration !== this.#getProviderConfigurationGeneration(provider) &&
 			credential.type === "oauth" &&
 			target.credential.type === "oauth" &&
+			oauthNonTokenFieldsEqual(credential, target.credential) &&
 			(credential.access !== target.credential.access ||
 				credential.refresh !== target.credential.refresh ||
 				credential.expires !== target.credential.expires)
@@ -2808,7 +2970,9 @@ export class AuthStorage {
 			const selector = selectors.get(storageProvider);
 			if (!selector) continue;
 			const selected = previousEntries.find(entry => this.#credentialMatchesSelector(entry, selector));
-			if (selected && removedIds.has(selected.id)) this.clearSessionCredentialSelector(storageProvider, scopeId);
+			if (selected && removedIds.has(selected.id)) {
+				this.markSessionCredentialUnavailable(scopeId, storageProvider, selector);
+			}
 		}
 		for (const [sessionId, sticky] of this.#sessionLastCredential.get(storageProvider) ?? []) {
 			if (removedIds.has(previousEntries[sticky.index]?.id ?? -1))
@@ -4563,50 +4727,86 @@ export class AuthStorage {
 	}
 
 	/**
-	 * Marks the current session's credential as temporarily blocked due to usage limits.
-	 * Uses usage reports to determine accurate reset time when available.
-	 * Returns true if a credential was blocked, enabling automatic fallback to the next credential.
+	 * Marks the explicit stored row, or the session row captured at entry, as usage-limited.
+	 * Re-finds that same row after the usage lookup; a vanished row marks nothing.
+	 * Returns whether another credential of the same type remains unblocked.
 	 */
 	async markUsageLimitReached(
 		provider: string,
 		sessionId: string | undefined,
-		options?: { retryAfterMs?: number; baseUrl?: string; signal?: AbortSignal; owner?: object },
+		options?: { retryAfterMs?: number; baseUrl?: string; signal?: AbortSignal; owner?: object; rowId?: number },
 	): Promise<boolean> {
 		provider = resolveOAuthStorageProvider(provider);
 		const ownerOverride = this.#configOverrideRegistration(provider, options?.owner);
 		if (ownerOverride && !ownerOverride.envSourced) return false;
+		const entries = this.#getStoredCredentials(provider);
 		const sessionCredential = this.#getSessionCredential(provider, sessionId);
-		if (!sessionCredential) return false;
-
-		const providerKey = this.#getProviderTypeKey(provider, sessionCredential.type);
+		const initial =
+			options?.rowId !== undefined
+				? entries.find(entry => entry.id === options.rowId)
+				: sessionCredential
+					? entries[sessionCredential.index]
+					: undefined;
+		if (!initial) return false;
 		const now = Date.now();
 		let blockedUntil = now + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs);
 
-		if (sessionCredential.type === "oauth" && this.#rankingStrategyResolver?.(provider)) {
-			const credential = this.#getCredentialsForProvider(provider)[sessionCredential.index];
-			if (credential?.type === "oauth") {
-				const report = await this.#getUsageReport(provider, credential, options);
-				if (report && this.#isUsageLimitReached(report)) {
-					const resetAtMs = this.#getUsageResetAtMs(report, Date.now());
-					if (resetAtMs && resetAtMs > blockedUntil) {
-						blockedUntil = resetAtMs;
-					}
-				}
+		if (initial.credential.type === "oauth" && this.#rankingStrategyResolver?.(provider)) {
+			const report = await this.#getUsageReport(provider, initial.credential, options);
+			if (report && this.#isUsageLimitReached(report)) {
+				const resetAtMs = this.#getUsageResetAtMs(report, Date.now());
+				if (resetAtMs && resetAtMs > blockedUntil) blockedUntil = resetAtMs;
 			}
 		}
 
-		this.#markCredentialBlocked(providerKey, sessionCredential.index, blockedUntil);
+		// Never consult the possibly reassigned sticky pointer after the await.
+		const current = this.#getStoredCredentials(provider);
+		const targetIndex = current.findIndex(entry => entry.id === initial.id);
+		const target = current[targetIndex];
+		if (!target) return false;
+		const providerKey = this.#getProviderTypeKey(provider, target.credential.type);
+		this.#markCredentialBlocked(providerKey, targetIndex, blockedUntil);
 
 		const remainingCredentials = this.#getCredentialsForProvider(provider)
 			.map((credential, index) => ({ credential, index }))
 			.filter(
 				(entry): entry is { credential: AuthCredential; index: number } =>
-					entry.credential.type === sessionCredential.type && entry.index !== sessionCredential.index,
+					entry.credential.type === target.credential.type && entry.index !== targetIndex,
 			);
 
 		return remainingCredentials.some(candidate => !this.#isCredentialBlocked(providerKey, candidate.index));
 	}
 
+	/**
+	 * Mark the stored credential whose key matches `apiKey` usage-limited for
+	 * `retryAfterMs` (or the default backoff). Used when the caller knows
+	 * exactly which leased credential failed (e.g. the auth-gateway leases a
+	 * concrete row without a session binding) so bookkeeping cannot land on the
+	 * wrong credential. The credential is never invalidated or marked suspect:
+	 * the block is a bounded backoff only. Returns false when no stored
+	 * credential matches the key.
+	 */
+	async markUsageLimitReachedMatching(
+		provider: string,
+		apiKey: string,
+		options?: { retryAfterMs?: number },
+	): Promise<boolean> {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		const stored = this.#getStoredCredentials(storageProvider);
+		for (let index = 0; index < stored.length; index++) {
+			const entry = stored[index];
+			if (entry && (await this.#credentialMatchesApiKey(storageProvider, entry.credential, apiKey))) {
+				this.#markCredentialBlocked(
+					this.#getProviderTypeKey(storageProvider, entry.credential.type),
+					index,
+					Date.now() + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs),
+				);
+				return true;
+			}
+		}
+		return false;
+	}
+
 	/**
 	 * Earliest instant at which any currently blocked stored credential for this
 	 * provider becomes usable again. Undefined when nothing is blocked.
@@ -4787,11 +4987,6 @@ export class AuthStorage {
 				if (leftBlockedUntil !== rightBlockedUntil) return leftBlockedUntil - rightBlockedUntil;
 				return left.orderPos - right.orderPos;
 			}
-			if (requiresOpenAICodexProModel(args.provider, args.options?.modelId)) {
-				const leftPlanPriority = getOpenAICodexPlanPriority(left.usage);
-				const rightPlanPriority = getOpenAICodexPlanPriority(right.usage);
-				if (leftPlanPriority !== rightPlanPriority) return leftPlanPriority - rightPlanPriority;
-			}
 			if (left.hasPriorityBoost !== right.hasPriorityBoost) return left.hasPriorityBoost ? -1 : 1;
 			if (this.#credentialRankingMode === "earliest-reset" && left.resetAtMs !== right.resetAtMs) {
 				// Earliest-expiry-first: drain the soonest-to-reset account before
@@ -4827,6 +5022,15 @@ export class AuthStorage {
 		options?: AuthApiKeyOptions,
 		reloadsUsed = 0,
 	): Promise<OAuthResolutionResult | undefined> {
+		const unavailableSelector =
+			sessionId && !options?.credentialSelector
+				? this.#sessionCredentialUnavailable.get(sessionId)?.get(resolveOAuthStorageProvider(provider))
+				: undefined;
+		if (unavailableSelector) {
+			throw new Error(
+				`Selected credential for ${provider} (${this.#formatCredentialSelector(unavailableSelector)}) is unavailable`,
+			);
+		}
 		if (reloadsUsed > MAX_OAUTH_RESOLUTION_RELOADS) {
 			logger.warn("OAuth credential resolution exhausted its reload budget", {
 				provider,
@@ -4835,6 +5039,10 @@ export class AuthStorage {
 			return undefined;
 		}
 		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options, sessionId);
+		const sessionSelector =
+			sessionId && !options?.credentialSelector && selectedCredential?.credential.type === "oauth"
+				? { kind: "id" as const, value: String(selectedCredential.id) }
+				: undefined;
 		const selectedOAuthCredential: OAuthCredentialSelection | undefined =
 			selectedCredential?.credential.type === "oauth"
 				? {
@@ -4864,9 +5072,7 @@ export class AuthStorage {
 		const providerKey = this.#getProviderTypeKey(provider, "oauth");
 		const order = selectedCredential ? [0] : this.#getCredentialOrder(providerKey, sessionId, credentials.length);
 		const strategy = this.#rankingStrategyResolver?.(provider);
-		const requiresProModel = requiresOpenAICodexProModel(provider, options?.modelId);
-		const checkUsage =
-			strategy !== undefined && (selectedCredential !== undefined || credentials.length > 1 || requiresProModel);
+		const checkUsage = strategy !== undefined && (selectedCredential !== undefined || credentials.length > 1);
 		const sessionCredential = this.#getSessionCredential(provider, sessionId);
 		const sessionPreferredIndex = sessionCredential?.type === "oauth" ? sessionCredential.index : undefined;
 		// Skip ranking only when the session already has a working preferred credential — re-ranking
@@ -4875,7 +5081,7 @@ export class AuthStorage {
 		// with the most headroom proactively and fall back intelligently when rate-limited.
 		const sessionPreferredIsAvailable =
 			sessionPreferredIndex !== undefined && !this.#isCredentialBlocked(providerKey, sessionPreferredIndex);
-		const shouldRank = !selectedCredential && checkUsage && (!sessionPreferredIsAvailable || requiresProModel);
+		const shouldRank = !selectedCredential && checkUsage && !sessionPreferredIsAvailable;
 		const candidates = shouldRank
 			? await this.#rankOAuthSelections({ providerKey, provider, order, credentials, options, strategy: strategy! })
 			: order
@@ -4913,7 +5119,7 @@ export class AuthStorage {
 			}
 		}
 
-		if (!selectedCredential && sessionPreferredIndex !== undefined && !requiresProModel) {
+		if (!selectedCredential && sessionPreferredIndex !== undefined) {
 			const sessionPreferredCandidate = candidates.findIndex(
 				candidate =>
 					!this.#isCredentialBlocked(providerKey, candidate.selection.index) &&
@@ -4961,24 +5167,6 @@ export class AuthStorage {
 			}),
 		);
 
-		// Skip the Pro-plan filter when no candidate is confirmed Pro, so users with only
-		// non-Pro accounts can still attempt Spark requests (e.g. trial/grandfathered access).
-		const enforceProRequirement =
-			requiresProModel && candidates.some(candidate => hasOpenAICodexProPlan(candidate.usage));
-		// Spark retains its historical Plus fallback for grandfathered accounts.
-		// Sol is different: confirmed Free/Plus plans cannot call it, so reject the
-		// model before returning an OAuth bearer and letting the turn fail remotely.
-		// Unknown plan names still reach the provider because the usage endpoint is
-		// authoritative and future tiers must not be denied by a client-side guess.
-		const strictProRequirement = requiresStrictOpenAICodexProModel(provider, options?.modelId);
-		if (
-			strictProRequirement &&
-			candidates.length > 0 &&
-			candidates.every(candidate => hasKnownOpenAICodexNonProPlan(candidate.usage))
-		) {
-			throw new Error(formatOpenAICodexChatGPTEntitlementError(options?.modelId));
-		}
-
 		const fallback = candidates[0];
 
 		for (const candidate of candidates) {
@@ -4993,9 +5181,9 @@ export class AuthStorage {
 					allowBlocked: false,
 					prefetchedUsage: candidate.usage,
 					usagePrechecked: candidate.usageChecked,
-					enforceProRequirement,
 				},
 				reloadsUsed,
+				sessionSelector,
 			);
 			if (resolved) return resolved;
 		}
@@ -5012,9 +5200,9 @@ export class AuthStorage {
 					allowBlocked: true,
 					prefetchedUsage: fallback.usage,
 					usagePrechecked: fallback.usageChecked,
-					enforceProRequirement,
 				},
 				reloadsUsed,
+				sessionSelector,
 			);
 		}
 
@@ -5229,6 +5417,18 @@ export class AuthStorage {
 			}
 			return authority;
 		} catch (error) {
+			// A genuine caller cancellation (e.g. the agent's ESC) is not a refresh
+			// failure. Rethrow before any failure classification so it never poisons
+			// the replay guard (which would temp-block the credential on the next
+			// request) or otherwise mutate its health state. But an INTERNAL deadline
+			// is a real failure: an `AbortSignal.timeout(...)` from an internal probe
+			// (`#checkCredentialHealth` / `#fetchUsageUncached`) may have cut short a
+			// dial that already consumed the rotating refresh token upstream, so its
+			// failure must still be memoized — otherwise the same (credential, token)
+			// pair is immediately eligible for a second refresh, replaying the token
+			// and tripping provider reuse detection. Skip the guard update only for a
+			// caller-owned abort, never for an internal timeout.
+			if (signal?.aborted && !isTimeoutAbort(signal)) throw error;
 			if (localDial && credentialId !== undefined) {
 				for (const [key, entry] of this.#recentOAuthRefreshFailures) {
 					if (entry.expiresAt <= Date.now()) this.#recentOAuthRefreshFailures.delete(key);
@@ -5298,17 +5498,11 @@ export class AuthStorage {
 			allowBlocked: boolean;
 			prefetchedUsage?: UsageReport | null;
 			usagePrechecked?: boolean;
-			enforceProRequirement?: boolean;
 		},
 		reloadsUsed = 0,
+		sessionSelector?: AuthCredentialSelector,
 	): Promise<OAuthResolutionResult | undefined> {
-		const {
-			checkUsage,
-			allowBlocked,
-			prefetchedUsage = null,
-			usagePrechecked = false,
-			enforceProRequirement,
-		} = usageOptions;
+		const { checkUsage, allowBlocked, prefetchedUsage = null, usagePrechecked = false } = usageOptions;
 		if (!this.#reconcileOAuthCredentialSelection(provider, selection)) return undefined;
 		if (!allowBlocked && this.#isCredentialBlocked(providerKey, selection.index)) {
 			return undefined;
@@ -5318,12 +5512,10 @@ export class AuthStorage {
 			return undefined;
 		}
 
-		const requiresProModel = requiresOpenAICodexProModel(provider, options?.modelId);
-		const applyProFilter = enforceProRequirement ?? requiresProModel;
 		let usage: UsageReport | null = null;
 		let usageChecked = false;
 
-		if ((checkUsage && !allowBlocked) || requiresProModel) {
+		if (checkUsage && !allowBlocked) {
 			if (usagePrechecked) {
 				usage = prefetchedUsage;
 				usageChecked = true;
@@ -5334,9 +5526,6 @@ export class AuthStorage {
 				});
 				usageChecked = true;
 			}
-			if (applyProFilter && !hasOpenAICodexProPlan(usage)) {
-				return undefined;
-			}
 			if (checkUsage && !allowBlocked && usage && this.#isUsageLimitReached(usage)) {
 				const resetAtMs = this.#getUsageResetAtMs(usage, Date.now());
 				this.#markCredentialBlocked(
@@ -5407,7 +5596,7 @@ export class AuthStorage {
 				selectionCredentialId,
 			);
 
-			if ((checkUsage && !allowBlocked) || requiresProModel) {
+			if (checkUsage && !allowBlocked) {
 				const sameAccount = selection.credential.accountId === updated.accountId;
 				if (!usageChecked || !sameAccount) {
 					usage = await this.#getUsageReport(provider, updated, {
@@ -5416,9 +5605,6 @@ export class AuthStorage {
 					});
 					usageChecked = true;
 				}
-				if (applyProFilter && !hasOpenAICodexProPlan(usage)) {
-					return undefined;
-				}
 				if (checkUsage && !allowBlocked && usage && this.#isUsageLimitReached(usage)) {
 					const resetAtMs = this.#getUsageResetAtMs(usage, Date.now());
 					this.#markCredentialBlocked(
@@ -5434,6 +5620,7 @@ export class AuthStorage {
 			this.#recordSessionCredential(provider, sessionId, "oauth", selection.index);
 			return { apiKey: result.apiKey, credential: updated };
 		} catch (error) {
+			if (options?.signal?.aborted) throw error;
 			if (isSqliteError(error)) throw error;
 			// Auth-broker errors retain the sanitized upstream body separately from
 			// their transport message. Include that body for failure classification
@@ -5517,6 +5704,9 @@ export class AuthStorage {
 					`oauth refresh failed: ${errorMsg}`,
 					attemptedCredentialId,
 				);
+				if (sessionSelector && sessionId) {
+					this.markSessionCredentialUnavailable(sessionId, provider, sessionSelector);
+				}
 				if (!disabled) {
 					// The CAS predicate compares the row's serialized `data`, so it also
 					// misses when nothing was rotated: the row may have been replaced by
@@ -5529,7 +5719,12 @@ export class AuthStorage {
 					// peer rotation to clobber — so apply it directly instead of looping.
 					const stillHoldsAttemptedToken =
 						attemptedCredentialId !== undefined &&
-						this.#credentialRowHoldsRefreshToken(provider, attemptedCredentialId, attemptedRefreshToken);
+						(this.#credentialRowHoldsRefreshToken(provider, attemptedCredentialId, attemptedRefreshToken) ||
+							this.#credentialRowHoldsRefreshToken(
+								provider,
+								attemptedCredentialId,
+								selection.credential.refresh,
+							));
 					if (stillHoldsAttemptedToken && attemptedCredentialId !== undefined) {
 						logger.warn("OAuth refresh disable CAS mismatched an unrotated row; disabling by id", {
 							provider,
@@ -5587,6 +5782,9 @@ export class AuthStorage {
 		}
 		if (this.#getCredentialSelector(provider, options, sessionId)) {
 			const selector = this.#getCredentialSelector(provider, options, sessionId);
+			if (selector && sessionId && !options?.credentialSelector) {
+				this.markSessionCredentialUnavailable(sessionId, provider, selector);
+			}
 			throw new Error(
 				`Selected credential for ${provider} (${selector ? this.#formatCredentialSelector(selector) : "unknown"}) is unavailable`,
 			);
@@ -5663,7 +5861,10 @@ 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, options?: Pick<AuthApiKeyOptions, "owner">): Promise<string | undefined> {
+	async peekApiKey(
+		provider: string,
+		options?: Pick<AuthApiKeyOptions, "owner"> & { sessionId?: string },
+	): Promise<string | undefined> {
 		provider = resolveOAuthStorageProvider(provider);
 		const runtimeKey = this.#runtimeOverrides.get(provider);
 		if (runtimeKey) return runtimeKey;
@@ -5671,11 +5872,12 @@ export class AuthStorage {
 		const configOverride = this.#configOverrideRegistration(provider, options?.owner);
 		const configKey = configOverride?.apiKey;
 		if (configKey && !configOverride?.envSourced) return configKey;
+		if (options?.sessionId && this.hasSessionCredentialUnavailable(provider, options.sessionId)) return undefined;
 
 		const selectedCredential = this.#resolveSelectedStoredCredential(
 			provider,
 			options?.owner ? { owner: options.owner } : undefined,
-			undefined,
+			options?.sessionId,
 		);
 		if (configKey) {
 			// Env-sourced (`apiKeyEnv`) override: same precedence as getApiKey —
@@ -5702,6 +5904,10 @@ export class AuthStorage {
 			}
 			return undefined;
 		}
+		// A hard selector is an identity boundary. If its selected row cannot
+		// provide a current token, discovery must not continue into the shared
+		// credential pool and silently query another account's catalog.
+		if (this.#getCredentialSelector(provider, undefined, options?.sessionId)) return undefined;
 
 		const attemptedApiKeyIndices = new Set<number>();
 		for (;;) {
@@ -5770,6 +5976,14 @@ export class AuthStorage {
 			if (storedApiKey) return storedApiKey;
 			return configKey;
 		}
+		if (sessionId && !options?.credentialSelector) {
+			const unavailableSelector = this.#sessionCredentialUnavailable.get(sessionId)?.get(provider);
+			if (unavailableSelector) {
+				throw new Error(
+					`Selected credential for ${provider} (${this.#formatCredentialSelector(unavailableSelector)}) is unavailable`,
+				);
+			}
+		}
 
 		if (selectedCredential?.credential.type === "api_key") {
 			this.#recordSessionCredential(provider, sessionId, "api_key", selectedCredential.index);