@gajae-code/ai 0.13.2 → 0.14.0

package/src/auth-storage.ts

@@ -184,6 +184,116 @@ export interface StoredAuthCredential {
 	provider: string;
 	credential: AuthCredential;
 	disabledCause: string | null;
+	/** Monotonic local row revision used by optimistic hard-removal actions. */
+	revision?: number;
+}
+
+/**
+ * Payload-free inventory projection used by account-management and presentation
+ * surfaces. This deliberately has no credential/token fields; `listAuthCredentials`
+ * remains the active full-fidelity selection contract.
+ */
+export interface CredentialInventoryRecord {
+	id: number;
+	provider: string;
+	credentialKind: "oauth" | "api_key";
+	identityLabel: string | null;
+	accountId?: string;
+	email?: string;
+	projectId?: string;
+	disabled: boolean;
+	disabledCause: string | null;
+}
+
+/** Safe usage observation supplied by a remote store's presentation cache. */
+export interface CachedUsagePresentation {
+	credentialId: number;
+	provider: string;
+	inventoryGeneration: number;
+	identityDigest: string;
+	usage: SafeUsageReport;
+	fetchedAt: number;
+	freshUntil: number;
+	retainUntil: number;
+}
+
+/** Opaque local action target for an all-or-nothing OAuth hard removal. */
+export interface CredentialRemovalTarget {
+	id: number;
+	provider: string;
+	expectedRevision: number;
+}
+
+export type AuthCredentialHardRemovalResult =
+	| { kind: "removed"; ids: readonly number[] }
+	| { kind: "conflict"; currentIds: readonly number[] };
+
+/** Usage report projection safe to cross a presentation boundary. */
+export type SafeUsageReport = Omit<UsageReport, "raw">;
+
+export type CachedUsageFreshness = "fresh" | "stale-last-good";
+
+export interface CachedUsageReport {
+	report: SafeUsageReport;
+	fetchedAt: number;
+	freshUntil: number;
+	retainUntil: number;
+	freshness: CachedUsageFreshness;
+}
+
+export type CachedCredentialHealthStatus = "ok" | "failed" | "unverifiable" | "unknown";
+
+export interface CachedCredentialHealth {
+	status: CachedCredentialHealthStatus;
+	reason: string | null;
+	checkedAt?: number;
+	retainUntil?: number;
+}
+
+/** Safe result from an explicit API-key probe whose key bytes are invocation-only. */
+export interface ApiKeyCredentialCheckResult {
+	provider: string;
+	type: "api_key";
+	ok: boolean | null;
+	reason?: string;
+	report?: SafeUsageReport;
+}
+
+/** Typed failure raised when an OAuth-only selector cannot be applied. */
+export type OAuthCredentialSelectorFailureReason =
+	| "api-key-row"
+	| "api-key-provider"
+	| "override-active"
+	| "not-found"
+	| "disabled"
+	| "ambiguous"
+	| "gateway-managed";
+
+export class OAuthCredentialSelectorError extends Error {
+	readonly reason: OAuthCredentialSelectorFailureReason;
+	readonly provider: string;
+	readonly selector: AuthCredentialSelector;
+	readonly candidateIds: readonly number[];
+
+	constructor(
+		reason: OAuthCredentialSelectorFailureReason,
+		provider: string,
+		selector: AuthCredentialSelector,
+		message: string,
+		candidateIds: readonly number[] = [],
+	) {
+		super(message);
+		this.name = "OAuthCredentialSelectorError";
+		this.reason = reason;
+		this.provider = provider;
+		this.selector = selector;
+		this.candidateIds = candidateIds;
+	}
+}
+
+export interface OAuthPinTarget {
+	credentialId: number;
+	canonicalSelector: AuthCredentialSelector;
 }
 
 /**
@@ -215,18 +325,25 @@ export interface CredentialHealthResult {
 	ok: boolean | null;
 	/** Failure / unverifiable reason; absent when `ok === true`. */
 	reason?: string;
-	/** Probe usage report (raw payload stripped) when `ok === true`. */
-	report?: Omit<UsageReport, "raw">;
+	report?: SafeUsageReport;
 }
 
 export interface CheckCredentialsOptions {
 	signal?: AbortSignal;
+	provider?: string;
 	/** Per-credential probe timeout (ms). Defaults to the configured usage request timeout. */
 	timeoutMs?: number;
 	/** Provider → base URL override, same shape as {@link AuthStorage.fetchUsageReports}. */
 	baseUrlResolver?: (provider: Provider) => string | undefined;
 }
 
+/** Options for the explicit, invocation-only API-key probe. */
+export interface ApiKeyCredentialCheckOptions {
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	baseUrl?: string;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Auth Broker Snapshot Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -316,6 +433,15 @@ export type OAuthRefreshLeaseClaim =
 export interface AuthCredentialStore {
 	close(): void;
 	listAuthCredentials(provider?: string): StoredAuthCredential[];
+	/** Payload-free account inventory; active and soft-disabled rows are included. */
+	listCredentialInventory?(provider?: string): CredentialInventoryRecord[];
+	/** Local opaque removal targets; remote stores may omit this capability. */
+	listCredentialRemovalTargets?(provider?: string): CredentialRemovalTarget[];
+	/** Transactional local hard removal; remote stores must reject this capability. */
+	removeAuthCredentialsHard?(
+		provider: string,
+		targets: readonly CredentialRemovalTarget[],
+	): AuthCredentialHardRemovalResult;
 	updateAuthCredential(id: number, credential: AuthCredential): void;
 	deleteAuthCredential(id: number, disabledCause: string): void;
 	tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string): boolean;
@@ -388,6 +514,21 @@ export interface AuthCredentialStore {
 	 * `signal` propagates the agent's cancel down to the broker fetch.
 	 */
 	fetchUsageReports?(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. */
+	recordUsagePresentation?(observation: CachedUsagePresentation): void;
+	/** Read a safe, durable health observation for one credential row. */
+	peekCachedCredentialHealth?(provider: Provider, credentialId: number): CachedCredentialHealth | undefined;
+	/** Persist a safe health observation for one credential row. */
+	recordCredentialHealth?(provider: Provider, credentialId: number, health: CachedCredentialHealth): void;
+	/** Persist a safe usage observation without exposing credential payloads. */
+	recordCredentialUsage?(provider: Provider, credentialId: number, report: SafeUsageReport): void;
+	/**
+	 * Optional readiness hook for stores that must hydrate payload-free metadata
+	 * before one-shot inventory consumers read their first snapshot.
+	 */
+	waitForReady?(): Promise<void>;
 	/**
 	 * Optional store-supplied per-credential usage report lookup. When present,
 	 * `AuthStorage` consults this before its own per-credential upstream fetch
@@ -434,8 +575,8 @@ export interface AuthCredentialStore {
 	replaceAuthCredentialsRemote?(provider: string, credentials: AuthCredential[]): Promise<StoredAuthCredential[]>;
 	/**
 	 * Optional async write hook for clearing every credential for a provider
-	 * (logout). When present, `AuthStorage.remove` routes through this instead
-	 * of the sync `deleteAuthCredentialsForProvider`.
+	 * (logout or a provider-wide invalidation). Remote stores must perform this
+	 * through their authoritative broker rather than mutating the client cache.
 	 */
 	deleteAuthCredentialsRemote?(provider: string, disabledCause: string): Promise<void>;
 }
@@ -728,7 +869,10 @@ const DEFAULT_RANKING_STRATEGIES = new Map<Provider, CredentialRankingStrategy>(
 		"grok-build",
 		{
 			findWindowLimits(report) {
-				return { secondary: report.limits.find(limit => limit.id === "grok-build:7d") };
+				const weekly = report.limits.find(limit => limit.id === "grok-build:weekly");
+				return {
+					secondary: weekly ?? report.limits.find(limit => limit.id === "grok-build:7d"),
+				};
 			},
 			windowDefaults: { primaryMs: 5 * 60 * 60 * 1000, secondaryMs: 30 * 24 * 60 * 60 * 1000 },
 		} satisfies CredentialRankingStrategy,
@@ -862,6 +1006,8 @@ type AuthApiKeyOptions = {
 	signal?: AbortSignal;
 	/** Pin selection to one stored credential instead of using round-robin/ranking. */
 	credentialSelector?: AuthCredentialSelector;
+	/** Prefer one stored OAuth credential while preserving quota-triggered fallback. */
+	preferredCredentialSelector?: AuthCredentialSelector;
 };
 export type AuthCredentialSelectorKind = "id" | "email" | "account" | "project";
 
@@ -898,6 +1044,27 @@ function isAbortSignalOption(
 	return typeof value === "object" && value !== null && "aborted" in value && "addEventListener" in value;
 }
 
+const HEALTH_CACHE_PREFIX = "account_health:v1:local:row:";
+const SOURCE_HEALTH_CACHE_PREFIX = "account_health:v1:source:";
+const PRESENTATION_RETENTION_MS = 24 * 60 * 60_000;
+
+function safeUsageReport(report: UsageReport): SafeUsageReport {
+	const { raw: _raw, ...safe } = report;
+	return safe;
+}
+
+function scrubHealthReason(reason: unknown, secrets: readonly string[] = []): string {
+	let value = reason instanceof Error ? reason.message : String(reason);
+	for (const secret of secrets) {
+		if (secret.length > 0) value = value.split(secret).join("[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();
+	if (value.length > 256) value = `${value.slice(0, 253)}...`;
+	return value || "credential check failed";
+}
+
 function requiresOpenAICodexProModel(provider: string, modelId: string | undefined): boolean {
 	return provider === "openai-codex" && typeof modelId === "string" && modelId.includes("-spark");
 }
@@ -1065,6 +1232,14 @@ export class AuthStorage {
 	#runtimeOverrides: Map<string, string> = new Map();
 	#configOverrides: Map<string, string> = new Map();
 	#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();
+	/** Credential selectors explicitly attached to a credential session scope. */
+	#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();
+	/** 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). */
 	#providerRoundRobinIndex: Map<string, number> = new Map();
 	/** Tracks the last used credential per provider for a session (used for rate-limit switching). */
@@ -1159,6 +1334,10 @@ export class AuthStorage {
 	close(): void {
 		if (this.#closed) return;
 		this.#closed = true;
+		this.#credentialScopeLeases.clear();
+		this.#sessionCredentialSelectors.clear();
+		this.#sessionCredentialAutoMasks.clear();
+		this.#sessionLastCredential.clear();
 		this.#store.close();
 	}
 
@@ -1182,7 +1361,7 @@ export class AuthStorage {
 		const evidenceApiKey = resolvedApiKey;
 		let selectedCredential: ({ index: number } & StoredCredential) | undefined;
 		try {
-			selectedCredential = this.#resolveSelectedStoredCredential(provider);
+			selectedCredential = this.#resolveSelectedStoredCredential(provider, undefined, undefined);
 		} catch {
 			return crypto
 				.createHash("sha256")
@@ -1306,11 +1485,234 @@ export class AuthStorage {
 	 */
 	setRuntimeCredentialSelector(provider: string, selector: AuthCredentialSelector): void {
 		const storageProvider = resolveOAuthStorageProvider(provider);
+		if (this.#runtimePreferredCredentialSelectors.has(storageProvider)) {
+			throw new Error(`Credential selector cannot be combined with a preferred credential selector for ${provider}`);
+		}
 		this.#assertCredentialSelectorUsable(storageProvider, selector);
 		this.#runtimeCredentialSelectors.set(storageProvider, selector);
 		this.#bumpGeneration("set-runtime-credential-selector", provider);
 	}
 
+	/** Acquire a reference-counted credential scope for a session or shared subagent scope. */
+	acquireCredentialScope(scopeId: string): void {
+		const scope = scopeId.trim();
+		if (!scope) throw new Error("Credential scope id must not be empty");
+		this.#credentialScopeLeases.set(scope, (this.#credentialScopeLeases.get(scope) ?? 0) + 1);
+	}
+
+	/** Whether a credential scope already has at least one live owner. */
+	hasCredentialScopeLease(scopeId: string): boolean {
+		const scope = scopeId.trim();
+		return scope.length > 0 && (this.#credentialScopeLeases.get(scope) ?? 0) > 0;
+	}
+
+	/** Release one credential-scope lease; final release clears only that scope's derived state. */
+	releaseCredentialScope(scopeId: string): void {
+		const scope = scopeId.trim();
+		if (!scope) return;
+		const leases = this.#credentialScopeLeases.get(scope);
+		if (leases === undefined) return;
+		if (leases > 1) {
+			this.#credentialScopeLeases.set(scope, leases - 1);
+			return;
+		}
+		this.#credentialScopeLeases.delete(scope);
+		this.#sessionCredentialSelectors.delete(scope);
+		this.#sessionCredentialAutoMasks.delete(scope);
+		for (const [provider, sessions] of this.#sessionLastCredential) {
+			if (!sessions.delete(scope)) continue;
+			if (sessions.size === 0) this.#sessionLastCredential.delete(provider);
+		}
+	}
+
+	/** Set the selector derived from a durable session pin or a session seed. */
+	setSessionCredentialSelector(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);
+		this.#assertCredentialSelectorUsable(storageProvider, selector);
+		const selectors = this.#sessionCredentialSelectors.get(scope) ?? new Map<string, AuthCredentialSelector>();
+		selectors.set(storageProvider, selector);
+		this.#sessionCredentialSelectors.set(scope, selectors);
+		this.#sessionCredentialAutoMasks.get(scope)?.delete(storageProvider);
+		this.#bumpGeneration("set-session-credential-selector", storageProvider);
+	}
+
+	/** Explicitly mask persistent/process-global selection and return the provider to AUTO for one scope. */
+	setSessionCredentialAuto(provider: string, scopeId: string): void {
+		const scope = scopeId.trim();
+		if (!scope) throw new Error("Credential scope id must not be empty");
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		this.#sessionCredentialSelectors.get(scope)?.delete(storageProvider);
+		const masks = this.#sessionCredentialAutoMasks.get(scope) ?? new Set<string>();
+		masks.add(storageProvider);
+		this.#sessionCredentialAutoMasks.set(scope, masks);
+		this.#bumpGeneration("set-session-credential-auto", storageProvider);
+	}
+
+	/** Clear a scope's explicit selector and AUTO mask, restoring normal precedence. */
+	clearSessionCredentialSelector(provider: string, scopeId: string): void {
+		const scope = scopeId.trim();
+		if (!scope) return;
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		const selectors = this.#sessionCredentialSelectors.get(scope);
+		const masks = this.#sessionCredentialAutoMasks.get(scope);
+		const changed = Boolean(selectors?.delete(storageProvider) || masks?.delete(storageProvider));
+		if (selectors?.size === 0) this.#sessionCredentialSelectors.delete(scope);
+		if (masks?.size === 0) this.#sessionCredentialAutoMasks.delete(scope);
+		if (changed) this.#bumpGeneration("clear-session-credential-selector", storageProvider);
+	}
+
+	/** 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;
+		return this.#getCredentialSelector(provider, undefined, scopeId) !== undefined;
+	}
+
+	/** Whether this scope explicitly masks provider pins and uses AUTO ranking. */
+	hasSessionCredentialAuto(provider: string, scopeId?: string): boolean {
+		if (!scopeId) return false;
+		return this.#sessionCredentialAutoMasks.get(scopeId)?.has(resolveOAuthStorageProvider(provider)) === true;
+	}
+
+	/** Resolve the effective selector precedence for a provider/scope. */
+	resolveEffectiveCredentialSelector(
+		provider: string,
+		scopeId?: string,
+		explicitSelector?: AuthCredentialSelector,
+	): AuthCredentialSelector | undefined {
+		return this.#getCredentialSelector(
+			provider,
+			explicitSelector ? { credentialSelector: explicitSelector } : undefined,
+			scopeId,
+		);
+	}
+
+	/** Validate and canonicalize an OAuth-only selector for account pinning. */
+	resolveOAuthPinTarget(provider: string, selector: AuthCredentialSelector): OAuthPinTarget {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		if (
+			this.#runtimeOverrides.has(storageProvider) ||
+			this.#configOverrides.has(storageProvider) ||
+			getEnvApiKey(storageProvider)
+		) {
+			throw new OAuthCredentialSelectorError(
+				"override-active",
+				storageProvider,
+				selector,
+				`Credential selector ${this.#formatCredentialSelector(selector)} cannot be used for ${storageProvider} while an API-key override is active; remove the override or choose AUTO`,
+			);
+		}
+		const allRows = this.#store.listCredentialInventory?.(storageProvider) ?? [];
+		const matchingCredentials = this.#getStoredCredentials(storageProvider).filter(entry =>
+			this.#credentialMatchesSelector(entry, selector),
+		);
+		const matchingIds = new Set(matchingCredentials.map(entry => entry.id));
+		const matchingRows = allRows.filter(
+			row => matchingIds.has(row.id) && !row.disabled && row.credentialKind === "oauth",
+		);
+		if (matchingRows.length === 0) {
+			const providerRows = allRows.filter(row => row.provider === storageProvider);
+			if (
+				selector.kind === "id" &&
+				providerRows.some(row => String(row.id) === selector.value && row.credentialKind === "api_key")
+			) {
+				throw new OAuthCredentialSelectorError(
+					"api-key-row",
+					storageProvider,
+					selector,
+					`Credential ${selector.value} is an API-key row and cannot be pinned; choose an OAuth account`,
+				);
+			}
+			if (providerRows.length > 0 && providerRows.every(row => row.credentialKind === "api_key")) {
+				throw new OAuthCredentialSelectorError(
+					"api-key-provider",
+					storageProvider,
+					selector,
+					`Provider ${storageProvider} has no OAuth credentials to pin`,
+				);
+			}
+			const disabled = providerRows.find(
+				row => row.disabled && this.#credentialMatchesInventorySelector(row, selector),
+			);
+			if (disabled) {
+				throw new OAuthCredentialSelectorError(
+					"disabled",
+					storageProvider,
+					selector,
+					`Credential ${this.#formatCredentialSelector(selector)} is disabled${disabled.disabledCause ? `: ${disabled.disabledCause}` : ""}; run /login ${storageProvider} or choose an active account`,
+				);
+			}
+			throw new OAuthCredentialSelectorError(
+				"not-found",
+				storageProvider,
+				selector,
+				`No active OAuth credential found for ${storageProvider} matching ${this.#formatCredentialSelector(selector)}; run /login ${storageProvider} or choose AUTO`,
+			);
+		}
+		if (matchingRows.length > 1) {
+			throw new OAuthCredentialSelectorError(
+				"ambiguous",
+				storageProvider,
+				selector,
+				`Selector ${this.#formatCredentialSelector(selector)} matches multiple OAuth credentials; choose id:<row-id>`,
+				matchingRows.map(row => row.id),
+			);
+		}
+		const target = matchingRows[0];
+		if (!target || target.disabled || target.credentialKind !== "oauth") {
+			throw new OAuthCredentialSelectorError(
+				"disabled",
+				storageProvider,
+				selector,
+				`Credential ${this.#formatCredentialSelector(selector)} is not an active OAuth credential; choose an active account`,
+			);
+		}
+		return { credentialId: target.id, canonicalSelector: { kind: "id", value: String(target.id) } };
+	}
+
+	/** Return all local inventory rows, including soft-disabled metadata, without payloads. */
+	listCredentialInventory(provider?: string): CredentialInventoryRecord[] {
+		return this.#store.listCredentialInventory?.(provider) ?? [];
+	}
+
+	/** Return local OAuth hard-removal action targets, including disabled rows. */
+	listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[] {
+		return this.#store.listCredentialRemovalTargets?.(provider) ?? [];
+	}
+
+	/** Remove selected local OAuth rows atomically; conflict leaves all rows intact. */
+	removeAuthCredentialsHard(
+		provider: string,
+		targets: readonly CredentialRemovalTarget[],
+	): AuthCredentialHardRemovalResult {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		const result = this.#store.removeAuthCredentialsHard?.(storageProvider, targets) ?? {
+			kind: "conflict",
+			currentIds: [],
+		};
+		if (result.kind !== "removed") return result;
+		const removed = new Set(result.ids);
+		const previousEntries = this.#getStoredCredentials(storageProvider);
+		const entries = previousEntries.filter(entry => !removed.has(entry.id));
+		this.#setStoredCredentials(storageProvider, entries);
+		this.#usageRequestInFlight.clear();
+		this.#usageReportsInFlight.clear();
+		this.#usageCache.deletePrefix?.(`report:${storageProvider}:`);
+		for (const [scopeId, selectors] of this.#sessionCredentialSelectors) {
+			const selector = selectors.get(storageProvider);
+			const selected = selector
+				? previousEntries.find(entry => this.#credentialMatchesSelector(entry, selector))
+				: undefined;
+			if (selected && removed.has(selected.id)) this.clearSessionCredentialSelector(storageProvider, scopeId);
+		}
+		for (const [sessionId, sticky] of this.#sessionLastCredential.get(storageProvider) ?? []) {
+			if (removed.has(previousEntries[sticky.index]?.id ?? -1))
+				this.#clearSessionCredential(storageProvider, sessionId);
+		}
+		this.#resetProviderAssignments(storageProvider);
+		return result;
+	}
 	/**
 	 * Remove a runtime credential selector.
 	 */
@@ -1321,6 +1723,58 @@ export class AuthStorage {
 		}
 	}
 
+	/** Whether a provider currently has a soft runtime credential preference. */
+	hasRuntimePreferredCredentialSelector(provider: string): boolean {
+		return this.#runtimePreferredCredentialSelectors.has(resolveOAuthStorageProvider(provider));
+	}
+
+	/** Resolve an unqualified preferred selector to the single active OAuth provider it matches. */
+	resolveRuntimePreferredCredentialSelectorProvider(selector: AuthCredentialSelector): string {
+		const providers = [...this.#data.entries()]
+			.filter(([, entries]) =>
+				entries.some(
+					entry => entry.credential.type === "oauth" && this.#credentialMatchesSelector(entry, selector),
+				),
+			)
+			.map(([provider]) => provider);
+		if (providers.length === 0) {
+			throw new Error(`No active credential found matching ${this.#formatCredentialSelector(selector)}`);
+		}
+		if (providers.length > 1) {
+			throw new Error(
+				`Preferred credential selector ${this.#formatCredentialSelector(selector)} matches multiple providers; use provider/${this.#formatCredentialSelector(selector)}`,
+			);
+		}
+		return providers[0]!;
+	}
+
+	/**
+	 * Prefer one stored OAuth credential for a provider while retaining quota
+	 * fallback to the rest of the pool (not persisted to disk). Used for CLI
+	 * `--prefer-credential`. Unlike {@link setRuntimeCredentialSelector}, a
+	 * quota/rate-limit failure on the preferred row still rotates to another
+	 * active credential instead of failing the session.
+	 */
+	setRuntimePreferredCredentialSelector(provider: string, selector: AuthCredentialSelector): void {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		if (this.#runtimeCredentialSelectors.has(storageProvider)) {
+			throw new Error(`Preferred credential selector cannot be combined with a credential selector for ${provider}`);
+		}
+		this.#assertPreferredCredentialSelectorUsable(storageProvider, selector);
+		this.#runtimePreferredCredentialSelectors.set(storageProvider, selector);
+		this.#bumpGeneration("set-runtime-preferred-credential-selector", provider);
+	}
+
+	/**
+	 * Remove a runtime preferred credential selector.
+	 */
+	removeRuntimePreferredCredentialSelector(provider: string): void {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		if (this.#runtimePreferredCredentialSelectors.delete(storageProvider)) {
+			this.#bumpGeneration("remove-runtime-preferred-credential-selector", provider);
+		}
+	}
+
 	/**
 	 * Remove a runtime API key override.
 	 */
@@ -1353,6 +1807,11 @@ export class AuthStorage {
 		return this.#runtimeCredentialSelectors.has(resolveOAuthStorageProvider(provider));
 	}
 
+	/** Whether the effective selector for a session scope is pinned. */
+	hasEffectiveCredentialSelector(provider: string, sessionId?: string): boolean {
+		return this.#getCredentialSelector(provider, undefined, sessionId) !== undefined;
+	}
+
 	/**
 	 * Opaque stored row id of the credential this session is currently using.
 	 *
@@ -1372,6 +1831,62 @@ export class AuthStorage {
 		return this.#getStoredCredentials(storageProvider)[session.index]?.id;
 	}
 
+	/**
+	 * Force a running session's OAuth credential for a provider to a specific
+	 * stored row, independent of quota/rate-limit state. Used for a mid-session
+	 * `/credential <selector>` switch that has nothing to do with exhaustion —
+	 * the user just wants a different account for the rest of the session.
+	 *
+	 * This mutates ONLY the session-scoped sticky pointer
+	 * ({@link AuthStorage.#recordSessionCredential}), never a provider-wide
+	 * runtime override, so it cannot bleed into other sessions in the same
+	 * process whose credential identity differs. The sticky pointer is keyed by
+	 * `sessionId`, and subagents/team workers inherit their parent's
+	 * `credentialSessionId` by design so they keep using the same account as
+	 * the parent — a switch therefore applies to the whole session family
+	 * sharing that identity, not to unrelated sessions.
+	 *
+	 * Fails closed rather than silently no-op when a stronger override already
+	 * decides this provider's credential every call: a hard pin
+	 * ({@link AuthStorage.setRuntimeCredentialSelector}, `--credential`), a
+	 * 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.
+	 *
+	 * Deliberately does not touch credential-blocked state: if the target row
+	 * is still backoff-blocked from a prior quota failure, the existing
+	 * `#resolveOAuthSelection` ranking safely ignores this sticky pointer and
+	 * 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 {
+		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)) {
+			throw new Error(
+				`Cannot switch credential for ${provider}: a config API key override (models.yml) is active and always wins`,
+			);
+		}
+		if (this.#runtimeCredentialSelectors.has(storageProvider)) {
+			throw new Error(
+				`Cannot switch credential for ${provider}: --credential already pins this session to one stored row`,
+			);
+		}
+		const matched = this.#findCredentialBySelector(storageProvider, selector);
+		if (matched?.credential.type !== "oauth") {
+			throw new Error(
+				`No active OAuth credential found for ${provider} matching ${this.#formatCredentialSelector(selector)}`,
+			);
+		}
+		this.#recordSessionCredential(storageProvider, sessionId, "oauth", matched.index);
+		this.#bumpGeneration("switch-session-credential");
+	}
+
 	/**
 	 * Register a per-provider API key sourced from user configuration
 	 * (e.g. `models.yml` `providers.<name>.apiKey`). Higher priority than
@@ -1419,6 +1934,7 @@ export class AuthStorage {
 	 * Reload credentials from storage.
 	 */
 	async reload(): Promise<void> {
+		await this.#store.waitForReady?.();
 		const records = this.#store.listAuthCredentials();
 		const grouped = new Map<string, StoredCredential[]>();
 		for (const record of records) {
@@ -1528,6 +2044,7 @@ export class AuthStorage {
 			for (const entry of removed) {
 				this.#store.deleteAuthCredential(entry.id, "deduplicated duplicate credential");
 			}
+			this.#clearSelectorsForRemovedCredential(provider, new Set(removed.map(entry => entry.id)), entries);
 			this.#resetProviderAssignments(provider);
 		}
 		return kept.reverse();
@@ -1682,8 +2199,38 @@ export class AuthStorage {
 		return undefined;
 	}
 
-	#getCredentialSelector(provider: string, options?: AuthApiKeyOptions): AuthCredentialSelector | undefined {
-		return options?.credentialSelector ?? this.#runtimeCredentialSelectors.get(resolveOAuthStorageProvider(provider));
+	#credentialMatchesInventorySelector(row: CredentialInventoryRecord, selector: AuthCredentialSelector): boolean {
+		if (row.disabled || row.credentialKind !== "oauth") return false;
+		switch (selector.kind) {
+			case "id":
+				return String(row.id) === selector.value;
+			case "email":
+				return row.identityLabel?.toLowerCase() === selector.value.toLowerCase();
+			case "account":
+			case "project":
+				return row.identityLabel === selector.value;
+		}
+	}
+	#getCredentialSelector(
+		provider: string,
+		options?: AuthApiKeyOptions,
+		sessionId?: string,
+	): AuthCredentialSelector | undefined {
+		if (options?.credentialSelector) return options.credentialSelector;
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		if (sessionId) {
+			if (this.#sessionCredentialAutoMasks.get(sessionId)?.has(storageProvider)) return undefined;
+			const scoped = this.#sessionCredentialSelectors.get(sessionId)?.get(storageProvider);
+			if (scoped) return scoped;
+		}
+		return this.#runtimeCredentialSelectors.get(storageProvider);
+	}
+
+	#getPreferredCredentialSelector(provider: string, options?: AuthApiKeyOptions): AuthCredentialSelector | undefined {
+		return (
+			options?.preferredCredentialSelector ??
+			this.#runtimePreferredCredentialSelectors.get(resolveOAuthStorageProvider(provider))
+		);
 	}
 
 	#assertCredentialSelectorUsable(provider: string, selector: AuthCredentialSelector): void {
@@ -1702,11 +2249,32 @@ export class AuthStorage {
 		}
 	}
 
+	/**
+	 * Validates a preferred-credential selector (`--prefer-credential`). Unlike
+	 * {@link AuthStorage.#assertCredentialSelectorUsable}, the match must resolve
+	 * 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)) {
+			throw new Error(
+				`Preferred credential selector ${this.#formatCredentialSelector(selector)} cannot be used for ${provider} while an API key override is active`,
+			);
+		}
+		const selected = this.#findCredentialBySelector(provider, selector);
+		if (selected?.credential.type !== "oauth") {
+			throw new Error(
+				`No active credential found for ${provider} matching ${this.#formatCredentialSelector(selector)}`,
+			);
+		}
+	}
+
 	#resolveSelectedStoredCredential(
 		provider: string,
 		options?: AuthApiKeyOptions,
+		sessionId?: string,
 	): ({ index: number } & StoredCredential) | undefined {
-		const selector = this.#getCredentialSelector(provider, options);
+		const selector = this.#getCredentialSelector(provider, options, sessionId);
 		if (!selector) return undefined;
 		this.#assertCredentialSelectorUsable(resolveOAuthStorageProvider(provider), selector);
 		const selected = this.#findCredentialBySelector(provider, selector);
@@ -1846,6 +2414,7 @@ export class AuthStorage {
 		if (!disabled) return false;
 		const updated = entries.filter((_value, idx) => idx !== index);
 		this.#setStoredCredentials(provider, updated);
+		this.#clearSelectorsForRemovedCredential(provider, new Set([target.id]), entries);
 		this.#resetProviderAssignments(provider);
 		this.#emitCredentialDisabled({ provider, disabledCause });
 		return true;
@@ -1875,10 +2444,30 @@ export class AuthStorage {
 			provider,
 			entries.filter(entry => entry.id !== credentialId),
 		);
+		this.#clearSelectorsForRemovedCredential(provider, new Set([credentialId]), entries);
 		this.#resetProviderAssignments(provider);
 		this.#emitCredentialDisabled({ provider, disabledCause });
 	}
 
+	/** Clear every selector whose durable/in-memory target was just removed. */
+	#clearSelectorsForRemovedCredential(
+		provider: string,
+		removedIds: ReadonlySet<number>,
+		previousEntries: readonly StoredCredential[] = this.#getStoredCredentials(provider),
+	): void {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		for (const [scopeId, selectors] of this.#sessionCredentialSelectors) {
+			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);
+		}
+		for (const [sessionId, sticky] of this.#sessionLastCredential.get(storageProvider) ?? []) {
+			if (removedIds.has(previousEntries[sticky.index]?.id ?? -1))
+				this.#clearSessionCredential(storageProvider, sessionId);
+		}
+	}
+
 	#emitCredentialDisabled(event: CredentialDisabledEvent): void {
 		if (this.#credentialDisabledListeners.size === 0) {
 			// No subscribers — buffer for later replay. Cap the backlog so a process that runs
@@ -2020,7 +2609,13 @@ export class AuthStorage {
 		} else {
 			this.#store.deleteAuthCredentialsForProvider(storageProvider, "deleted by user");
 		}
+		const previousEntries = this.#getStoredCredentials(storageProvider);
 		this.#setStoredCredentials(storageProvider, []);
+		this.#clearSelectorsForRemovedCredential(
+			storageProvider,
+			new Set(previousEntries.map(entry => entry.id)),
+			previousEntries,
+		);
 		this.#resetProviderAssignments(storageProvider);
 	}
 
@@ -2051,10 +2646,10 @@ export class AuthStorage {
 		return false;
 	}
 
-	hasAuth(provider: string): boolean {
+	hasAuth(provider: string, sessionId?: string): boolean {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		try {
-			this.#resolveSelectedStoredCredential(storageProvider);
+			this.#resolveSelectedStoredCredential(storageProvider, undefined, sessionId);
 		} catch {
 			return false;
 		}
@@ -2070,7 +2665,7 @@ export class AuthStorage {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		let selected: ({ index: number } & StoredCredential) | undefined;
 		try {
-			selected = this.#resolveSelectedStoredCredential(storageProvider);
+			selected = this.#resolveSelectedStoredCredential(storageProvider, undefined, sessionId);
 		} catch {
 			return undefined;
 		}
@@ -2097,7 +2692,7 @@ export class AuthStorage {
 	hasUsableAuth(provider: string): boolean {
 		const storageProvider = resolveOAuthStorageProvider(provider);
 		try {
-			const selectedCredential = this.#resolveSelectedStoredCredential(storageProvider);
+			const selectedCredential = this.#resolveSelectedStoredCredential(storageProvider, undefined, undefined);
 			if (this.hasRuntimeApiKey(storageProvider)) return true;
 			if (this.#configOverrides.has(storageProvider)) return true;
 			if (selectedCredential) {
@@ -2153,7 +2748,14 @@ export class AuthStorage {
 	/**
 	 * Get OAuth credentials for a provider.
 	 */
-	getOAuthCredential(provider: string): OAuthCredential | undefined {
+	getOAuthCredential(provider: string, sessionId?: string): OAuthCredential | undefined {
+		const selected = this.#resolveSelectedStoredCredential(
+			resolveOAuthStorageProvider(provider),
+			undefined,
+			sessionId,
+		);
+		if (selected?.credential.type === "oauth") return selected.credential;
+		if (selected) return undefined;
 		return this.#getCredentialsForProvider(provider).find(
 			(credential): credential is OAuthCredential => credential.type === "oauth",
 		);
@@ -2177,6 +2779,13 @@ export class AuthStorage {
 		if (this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider)) return undefined;
 
 		// Prefer the session-sticky credential when available.
+
+		const scopedSelection = this.#resolveSelectedStoredCredential(provider, undefined, sessionId);
+		if (scopedSelection?.credential.type === "api_key") return undefined;
+		if (scopedSelection?.credential.type === "oauth") {
+			const accountId = scopedSelection.credential.accountId;
+			return typeof accountId === "string" && accountId.length > 0 ? accountId : undefined;
+		}
 		const sessionPref = this.#getSessionCredential(provider, sessionId);
 		// If the session has been routed to a stored API key, do not inject OAuth account_uuid.
 		if (sessionPref !== undefined && sessionPref.type !== "oauth") return undefined;
@@ -2623,6 +3232,7 @@ export class AuthStorage {
 			projectId: credential.projectId,
 			email: credential.email,
 			enterpriseUrl: credential.enterpriseUrl,
+			mcpBinding: credential.mcpBinding,
 		};
 	}
 
@@ -2697,6 +3307,7 @@ export class AuthStorage {
 			projectId: credential.projectId,
 			email: credential.email,
 			enterpriseUrl: credential.enterpriseUrl,
+			mcpBinding: credential.mcpBinding,
 		};
 	}
 
@@ -2710,6 +3321,7 @@ export class AuthStorage {
 			projectId: refreshed.projectId ?? credential.projectId,
 			email: refreshed.email ?? credential.email,
 			enterpriseUrl: refreshed.enterpriseUrl ?? credential.enterpriseUrl,
+			mcpBinding: credential.mcpBinding,
 		};
 	}
 
@@ -2757,6 +3369,7 @@ export class AuthStorage {
 			projectId: next.projectId,
 			email: next.email,
 			enterpriseUrl: next.enterpriseUrl,
+			mcpBinding: next.mcpBinding ?? existing.mcpBinding,
 		});
 	}
 
@@ -3208,9 +3821,172 @@ export class AuthStorage {
 	 * Environment-variable API keys are not enumerated — the caller's intent
 	 * here is "which of my stored credentials is broken".
 	 */
+	/** Return a safe cache-only usage observation. */
+	getCachedUsageReport(provider: Provider, credentialId: number, baseUrl?: string): CachedUsageReport | undefined {
+		const storageProvider = resolveOAuthStorageProvider(provider);
+		const presentation = this.#store.peekCachedUsagePresentation?.(storageProvider, credentialId);
+		if (presentation) {
+			const now = Date.now();
+			if (presentation.retainUntil > now) {
+				return {
+					report: presentation.usage,
+					fetchedAt: presentation.fetchedAt,
+					freshUntil: presentation.freshUntil,
+					retainUntil: presentation.retainUntil,
+					freshness: presentation.freshUntil > now ? "fresh" : "stale-last-good",
+				};
+			}
+		}
+		const entry = this.#getStoredCredentials(storageProvider).find(candidate => candidate.id === credentialId);
+		if (entry?.credential.type !== "oauth") return undefined;
+		const request = this.#buildUsageRequestForOauth(storageProvider, entry.credential, baseUrl);
+		const cached = this.#usageCache.getStale<UsageReport | null>(this.#buildUsageReportCacheKey(request));
+		if (!cached || cached.value === null || cached.expiresAt + PRESENTATION_RETENTION_MS < Date.now())
+			return undefined;
+		return {
+			report: safeUsageReport(cached.value),
+			fetchedAt: cached.value.fetchedAt,
+			freshUntil: cached.expiresAt,
+			retainUntil: cached.expiresAt + PRESENTATION_RETENTION_MS,
+			freshness: cached.expiresAt > Date.now() ? "fresh" : "stale-last-good",
+		};
+	}
+
+	/** Cache-only health observation; unknown means no retained explicit check. */
+	getCachedCredentialHealth(credentialId: number): CachedCredentialHealth {
+		const inventory = this.#store.listCredentialInventory?.() ?? [];
+		const row = inventory.find(candidate => candidate.id === credentialId);
+		if (row?.disabled) return { status: "failed", reason: scrubHealthReason(row.disabledCause ?? "disabled") };
+		const remote = row ? this.#store.peekCachedCredentialHealth?.(row.provider as Provider, credentialId) : undefined;
+		if (remote) return remote;
+		const raw = this.#store.getCache(`${HEALTH_CACHE_PREFIX}${credentialId}`);
+		if (!raw) return { status: "unknown", reason: null };
+		try {
+			const value = JSON.parse(raw) as {
+				status?: unknown;
+				reason?: unknown;
+				checkedAt?: unknown;
+				retainUntil?: unknown;
+			};
+			if (typeof value.retainUntil !== "number" || value.retainUntil <= Date.now())
+				return { status: "unknown", reason: null };
+			const status =
+				value.status === "ok" || value.status === "failed" || value.status === "unverifiable"
+					? value.status
+					: "unknown";
+			return {
+				status,
+				reason: typeof value.reason === "string" ? value.reason : null,
+				checkedAt: typeof value.checkedAt === "number" ? value.checkedAt : undefined,
+				retainUntil: value.retainUntil,
+			};
+		} catch {
+			return { status: "unknown", reason: null };
+		}
+	}
+
+	peekCachedCredentialHealthForSource(provider: string, source: "env" | "config" | "runtime"): CachedCredentialHealth {
+		const raw = this.#store.getCache(`${SOURCE_HEALTH_CACHE_PREFIX}${provider}:${source}`);
+		if (!raw) return { status: "unknown", reason: null };
+		try {
+			const value = JSON.parse(raw) as CachedCredentialHealth;
+			if (!value.retainUntil || value.retainUntil <= Date.now()) return { status: "unknown", reason: null };
+			return {
+				status:
+					value.status === "ok" || value.status === "failed" || value.status === "unverifiable"
+						? value.status
+						: "unknown",
+				reason: value.reason ? scrubHealthReason(value.reason) : null,
+				checkedAt: value.checkedAt,
+				retainUntil: value.retainUntil,
+			};
+		} catch {
+			return { status: "unknown", reason: null };
+		}
+	}
+
+	recordCredentialHealthForSource(
+		provider: string,
+		source: "env" | "config" | "runtime",
+		health: CachedCredentialHealth,
+	): void {
+		if (health.status === "unknown" || !health.retainUntil) return;
+		const retainUntil = health.retainUntil;
+		const payload: CachedCredentialHealth = {
+			status: health.status,
+			reason: health.reason ? scrubHealthReason(health.reason) : null,
+			checkedAt: health.checkedAt ?? Date.now(),
+			retainUntil,
+		};
+		this.#store.setCache(
+			`${SOURCE_HEALTH_CACHE_PREFIX}${resolveOAuthStorageProvider(provider)}:${source}`,
+			JSON.stringify(payload),
+			Math.floor(retainUntil / 1000),
+		);
+	}
+
+	#recordCredentialHealth(provider: Provider, credentialId: number, health: CachedCredentialHealth): void {
+		if (health.status !== "unknown") this.#store.recordCredentialHealth?.(provider, credentialId, health);
+		if (health.status === "unknown" || !health.retainUntil) return;
+		const healthPayload = {
+			v: 1,
+			status: health.status,
+			reason: health.reason ? scrubHealthReason(health.reason) : null,
+			checkedAt: health.checkedAt ?? Date.now(),
+			retainUntil: health.retainUntil,
+		};
+		this.#store.setCache(
+			`${HEALTH_CACHE_PREFIX}${credentialId}`,
+			JSON.stringify(healthPayload),
+			Math.floor(healthPayload.retainUntil / 1000),
+		);
+	}
+	/** Explicit API-key probe; key bytes are not retained in the returned result. */
+	async checkApiKeyCredential(
+		provider: Provider,
+		apiKey: string,
+		options: ApiKeyCredentialCheckOptions = {},
+	): Promise<ApiKeyCredentialCheckResult> {
+		const providerImpl = this.#usageProviderResolver?.(provider);
+		const base: ApiKeyCredentialCheckResult = { provider, type: "api_key", ok: null };
+		if (!providerImpl) {
+			base.reason = `unsupported API-key probe for ${provider}`;
+			return base;
+		}
+		const request = this.#buildUsageRequest(provider, { type: "api_key", apiKey }, options.baseUrl);
+		if (providerImpl.supports && !providerImpl.supports(request)) {
+			base.reason = `unsupported API-key probe for ${provider}`;
+			return base;
+		}
+		options.signal?.throwIfAborted();
+		const timeoutMs = options.timeoutMs ?? this.#usageRequestTimeoutMs;
+		const timeoutSignal = AbortSignal.timeout(timeoutMs);
+		const signal = options.signal ? AbortSignal.any([options.signal, timeoutSignal]) : timeoutSignal;
+		try {
+			const report = await providerImpl.fetchUsage(
+				{ ...request, signal },
+				{
+					fetch: this.#usageFetch,
+					logger: this.#usageLogger,
+				},
+			);
+			if (!report) {
+				base.reason = "API-key probe returned no verifiable data";
+				return base;
+			}
+			base.ok = true;
+			base.report = safeUsageReport(report);
+			return base;
+		} catch (error) {
+			base.ok = false;
+			base.reason = scrubHealthReason(error, [apiKey]);
+			return base;
+		}
+	}
+
 	async checkCredentials(options?: CheckCredentialsOptions): Promise<CredentialHealthResult[]> {
 		options?.signal?.throwIfAborted();
-		const stored = this.#store.listAuthCredentials();
+		const stored = this.#store.listAuthCredentials(options?.provider);
 		const resolver = this.#usageProviderResolver;
 		const timeoutMs = options?.timeoutMs ?? this.#usageRequestTimeoutMs;
 		const ctx: UsageFetchContext = { fetch: this.#usageFetch, logger: this.#usageLogger };
@@ -3281,12 +4057,21 @@ export class AuthStorage {
 						params = { ...params, credential: refreshedCredential };
 					} catch (error) {
 						base.ok = false;
-						base.reason = `oauth refresh failed: ${error instanceof Error ? error.message : String(error)}`;
-						results.push(base);
-						continue;
+						base.reason = `oauth refresh failed: ${scrubHealthReason(error)}`;
 					}
 				}
 			}
+			if (base.ok === false && base.reason?.startsWith("oauth refresh failed:")) {
+				results.push(base);
+				const healthPayload: CachedCredentialHealth = {
+					status: "failed",
+					reason: scrubHealthReason(base.reason),
+					checkedAt: Date.now(),
+					retainUntil: Date.now() + PRESENTATION_RETENTION_MS,
+				};
+				this.#recordCredentialHealth(row.provider as Provider, row.id, healthPayload);
+				continue;
+			}
 
 			try {
 				const report = await providerImpl.fetchUsage(params, ctx);
@@ -3300,13 +4085,27 @@ export class AuthStorage {
 					if (email) base.email = email;
 					const { raw: _raw, ...trimmed } = report;
 					base.report = trimmed;
+					this.#usageCache.set(this.#buildUsageReportCacheKey(params), {
+						value: report,
+						expiresAt: Date.now() + USAGE_REPORT_TTL_MS,
+					});
+					this.#store.recordCredentialUsage?.(row.provider as Provider, row.id, trimmed);
 				}
 			} catch (error) {
 				base.ok = false;
-				base.reason = error instanceof Error ? error.message : String(error);
+				base.reason = scrubHealthReason(error, cred.type === "api_key" ? [cred.key] : []);
 			}
 
 			results.push(base);
+			const healthPayload: CachedCredentialHealth = {
+				status: base.ok === true ? "ok" : base.ok === false ? "failed" : "unverifiable",
+				reason: base.reason
+					? scrubHealthReason(base.reason, row.credential.type === "api_key" ? [row.credential.key] : [])
+					: null,
+				checkedAt: Date.now(),
+				retainUntil: Date.now() + PRESENTATION_RETENTION_MS,
+			};
+			this.#recordCredentialHealth(row.provider as Provider, row.id, healthPayload);
 		}
 
 		return results;
@@ -3559,7 +4358,7 @@ export class AuthStorage {
 			});
 			return undefined;
 		}
-		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options);
+		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options, sessionId);
 		const selectedOAuthCredential =
 			selectedCredential?.credential.type === "oauth"
 				? { credential: selectedCredential.credential, index: selectedCredential.index }
@@ -3597,6 +4396,32 @@ export class AuthStorage {
 					.filter((selection): selection is { credential: OAuthCredential; index: number } => Boolean(selection))
 					.map(selection => ({ selection, usage: null, usageChecked: false }));
 
+		// Soft `--prefer-credential` preference: reorder the preferred row to the
+		// front when it is usable, ahead of the session-stickiness reorder below so
+		// a blocked preferred row falls through to whatever the session already
+		// stuck to (its own quota-triggered fallback) instead of overriding it.
+		if (!selectedCredential) {
+			const preferredSelector = this.#getPreferredCredentialSelector(provider, options);
+			if (preferredSelector) {
+				this.#assertPreferredCredentialSelectorUsable(resolveOAuthStorageProvider(provider), preferredSelector);
+			}
+			const preferredSelection = preferredSelector
+				? this.#findCredentialBySelector(provider, preferredSelector)
+				: undefined;
+			if (
+				preferredSelection?.credential.type === "oauth" &&
+				!this.#isCredentialBlocked(providerKey, preferredSelection.index)
+			) {
+				const preferredCandidate = candidates.findIndex(
+					candidate => candidate.selection.index === preferredSelection.index,
+				);
+				if (preferredCandidate > 0) {
+					const [preferred] = candidates.splice(preferredCandidate, 1);
+					candidates.unshift(preferred);
+				}
+			}
+		}
+
 		if (!selectedCredential && sessionPreferredIndex !== undefined && !requiresProModel) {
 			const sessionPreferredCandidate = candidates.findIndex(
 				candidate =>
@@ -4089,6 +4914,23 @@ export class AuthStorage {
 			if (attemptedCredentialId !== undefined) {
 				const latestRow = this.#store.listAuthCredentials(provider).find(row => row.id === attemptedCredentialId);
 				const latestCredential = latestRow?.credential;
+				if (!latestRow) {
+					// The row we just tried is no longer active: a peer disabled it after a
+					// definitive refresh failure, the user removed it, or a re-login replaced
+					// it with a new row. Our in-memory snapshot is stale, and the refresh
+					// helper can only answer "credential disappeared" for it — an error that
+					// classifies as transient and would temp-block a row that will never come
+					// back. Long-lived processes (resumed sessions) would then keep replaying
+					// the vanished credential until restart while a valid re-login row sits
+					// unused in the store. Reload and re-resolve against the persisted truth.
+					logger.debug("OAuth credential vanished from the store; reloading snapshot", {
+						provider,
+						index: selection.index,
+						credentialId: attemptedCredentialId,
+					});
+					await this.reload();
+					return this.#resolveOAuthSelection(provider, sessionId, options, reloadsUsed + 1);
+				}
 				if (latestCredential?.type === "oauth" && latestCredential.refresh !== attemptedRefreshToken) {
 					logger.debug("OAuth refresh race detected; another process rotated token first", {
 						provider,
@@ -4110,7 +4952,7 @@ export class AuthStorage {
 			logger.warn("OAuth token refresh failed", {
 				provider,
 				index: selection.index,
-				error: errorMsg,
+				error: scrubHealthReason(error, [selection.credential.access, selection.credential.refresh]),
 				isDefinitiveFailure,
 			});
 
@@ -4155,7 +4997,7 @@ export class AuthStorage {
 					}
 				}
 				if (
-					!this.#getCredentialSelector(provider, options) &&
+					!this.#getCredentialSelector(provider, options, sessionId) &&
 					this.#getCredentialsForProvider(provider).some(credential => credential.type === "oauth")
 				) {
 					return this.#resolveOAuthSelection(provider, sessionId, options, reloadsUsed);
@@ -4165,8 +5007,8 @@ export class AuthStorage {
 				this.#markCredentialBlocked(providerKey, selection.index, Date.now() + 5 * 60 * 1000);
 			}
 		}
-		if (this.#getCredentialSelector(provider, options)) {
-			const selector = this.#getCredentialSelector(provider, options);
+		if (this.#getCredentialSelector(provider, options, sessionId)) {
+			const selector = this.#getCredentialSelector(provider, options, sessionId);
 			throw new Error(
 				`Selected credential for ${provider} (${selector ? this.#formatCredentialSelector(selector) : "unknown"}) is unavailable`,
 			);
@@ -4251,7 +5093,7 @@ export class AuthStorage {
 		const configKey = this.#configOverrides.get(provider);
 		if (configKey) return configKey;
 
-		const selectedCredential = this.#resolveSelectedStoredCredential(provider);
+		const selectedCredential = this.#resolveSelectedStoredCredential(provider, undefined, undefined);
 		if (selectedCredential?.credential.type === "api_key") {
 			return this.#resolveStoredApiKey(provider, selectedCredential.credential.key);
 		}
@@ -4311,7 +5153,7 @@ export class AuthStorage {
 	 */
 	async getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined> {
 		provider = resolveOAuthStorageProvider(provider);
-		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options);
+		const selectedCredential = this.#resolveSelectedStoredCredential(provider, options, sessionId);
 
 		// Runtime override takes highest priority after selector validation.
 		const runtimeKey = this.#runtimeOverrides.get(provider);
@@ -4666,14 +5508,16 @@ export class AuthStorage {
 	 * `POST /v1/credential/:id/disable`. Returns `false` when no such row exists.
 	 */
 	disableCredentialById(id: number, disabledCause: string): boolean {
+		const cause = normalizeDisabledCause(disabledCause);
 		for (const [provider, entries] of this.#data) {
 			const index = entries.findIndex(entry => entry.id === id);
 			if (index === -1) continue;
-			this.#store.deleteAuthCredential(id, disabledCause);
+			this.#store.deleteAuthCredential(id, cause);
 			const next = entries.filter((_value, idx) => idx !== index);
 			this.#setStoredCredentials(provider, next);
+			this.#clearSelectorsForRemovedCredential(provider, new Set([id]), entries);
 			this.#resetProviderAssignments(provider);
-			this.#emitCredentialDisabled({ provider, disabledCause });
+			this.#emitCredentialDisabled({ provider, disabledCause: cause });
 			return true;
 		}
 		return false;
@@ -4759,6 +5603,7 @@ type AuthRow = {
 	data: string;
 	disabled_cause: string | null;
 	identity_key: string | null;
+	revision: number;
 };
 
 type SerializedCredentialRecord = {
@@ -4767,7 +5612,7 @@ type SerializedCredentialRecord = {
 	identityKey: string | null;
 };
 
-const AUTH_SCHEMA_VERSION = 4;
+const AUTH_SCHEMA_VERSION = 5;
 const SQLITE_NOW_EPOCH = "CAST(strftime('%s','now') AS INTEGER)";
 
 function normalizeStoredAccountId(accountId: string | null | undefined): string | null {
@@ -4827,12 +5672,19 @@ function deserializeCredential(row: AuthRow): AuthCredential | null {
 }
 
 function normalizeDisabledCause(disabledCause: string): string {
-	const normalized = disabledCause.trim();
+	const normalized = disabledCause
+		.replace(/bearer\s+[^\s,;]+/gi, "Bearer [redacted]")
+		.replace(/(api[_-]?key|token|secret|authorization)[=:]\s*[^\s,;]+/gi, "$1=[redacted]")
+		.replace(/https?:\/\/[^\s?#]+\?[^\s]+/gi, value => value.split("?")[0] ?? "[redacted URL]")
+		.replace(/[\u0000-\u001f\u007f]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim()
+		.slice(0, 240);
 	return normalized.length > 0 ? normalized : "disabled";
 }
 
 function toStoredAuthCredential(row: AuthRow, credential: AuthCredential): StoredAuthCredential {
-	return { id: row.id, provider: row.provider, credential, disabledCause: row.disabled_cause };
+	return { id: row.id, provider: row.provider, credential, disabledCause: row.disabled_cause, revision: row.revision };
 }
 
 function resolveProviderCredentialIdentityKey(provider: string, identifiers: string[]): string | null {
@@ -4941,6 +5793,8 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 	#db: Database;
 	#listActiveStmt: Statement;
 	#listActiveByProviderStmt: Statement;
+	#listAllStmt: Statement;
+	#listAllByProviderStmt: Statement;
 	#listDisabledByProviderStmt: Statement;
 	#insertStmt: Statement;
 	#updateStmt: Statement;
@@ -4960,28 +5814,34 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		this.#initializeSchema();
 
 		this.#listActiveStmt = this.#db.prepare(
-			"SELECT id, provider, credential_type, data, disabled_cause, identity_key FROM auth_credentials WHERE disabled_cause IS NULL ORDER BY id ASC",
+			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE disabled_cause IS NULL ORDER BY id ASC",
 		);
 		this.#listActiveByProviderStmt = this.#db.prepare(
-			"SELECT id, provider, credential_type, data, disabled_cause, identity_key FROM auth_credentials WHERE provider = ? AND disabled_cause IS NULL ORDER BY id ASC",
+			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ? AND disabled_cause IS NULL ORDER BY id ASC",
+		);
+		this.#listAllStmt = this.#db.prepare(
+			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials ORDER BY id ASC",
+		);
+		this.#listAllByProviderStmt = this.#db.prepare(
+			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ? ORDER BY id ASC",
 		);
 		this.#listDisabledByProviderStmt = this.#db.prepare(
-			"SELECT id, provider, credential_type, data, disabled_cause, identity_key FROM auth_credentials WHERE provider = ? AND disabled_cause IS NOT NULL ORDER BY id ASC",
+			"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE provider = ? AND disabled_cause IS NOT NULL ORDER BY id ASC",
 		);
 		this.#insertStmt = this.#db.prepare(
-			`INSERT INTO auth_credentials (provider, credential_type, data, identity_key, created_at, updated_at) VALUES (?, ?, ?, ?, ${SQLITE_NOW_EPOCH}, ${SQLITE_NOW_EPOCH}) RETURNING id`,
+			`INSERT INTO auth_credentials (provider, credential_type, data, identity_key, revision, created_at, updated_at) VALUES (?, ?, ?, ?, 1, ${SQLITE_NOW_EPOCH}, ${SQLITE_NOW_EPOCH}) RETURNING id`,
 		);
 		this.#updateStmt = this.#db.prepare(
-			`UPDATE auth_credentials SET credential_type = ?, data = ?, identity_key = ?, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ?`,
+			`UPDATE auth_credentials SET credential_type = ?, data = ?, identity_key = ?, revision = revision + 1, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ?`,
 		);
 		this.#deleteStmt = this.#db.prepare(
-			`UPDATE auth_credentials SET disabled_cause = ?, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ?`,
+			`UPDATE auth_credentials SET disabled_cause = ?, revision = revision + 1, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ?`,
 		);
 		this.#deleteIfMatchesStmt = this.#db.prepare(
-			`UPDATE auth_credentials SET disabled_cause = ?, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ? AND data = ? AND disabled_cause IS NULL`,
+			`UPDATE auth_credentials SET disabled_cause = ?, revision = revision + 1, updated_at = ${SQLITE_NOW_EPOCH} WHERE id = ? AND data = ? AND disabled_cause IS NULL`,
 		);
 		this.#deleteByProviderStmt = this.#db.prepare(
-			`UPDATE auth_credentials SET disabled_cause = ?, updated_at = ${SQLITE_NOW_EPOCH} WHERE provider = ? AND disabled_cause IS NULL`,
+			`UPDATE auth_credentials SET disabled_cause = ?, revision = revision + 1, updated_at = ${SQLITE_NOW_EPOCH} WHERE provider = ? AND disabled_cause IS NULL`,
 		);
 		this.#hardDeleteStmt = this.#db.prepare("DELETE FROM auth_credentials WHERE id = ?");
 		this.#getCacheStmt = this.#db.prepare(
@@ -5106,6 +5966,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 				data TEXT NOT NULL,
 				disabled_cause TEXT DEFAULT NULL,
 				identity_key TEXT DEFAULT NULL,
+				revision INTEGER NOT NULL DEFAULT 1,
 				created_at INTEGER NOT NULL DEFAULT (${SQLITE_NOW_EPOCH}),
 				updated_at INTEGER NOT NULL DEFAULT (${SQLITE_NOW_EPOCH})
 			);
@@ -5130,6 +5991,9 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		if (fromVersion < 4) {
 			this.#migrateAuthSchemaV3ToV4();
 		}
+		if (fromVersion < 5) {
+			this.#migrateAuthSchemaV4ToV5();
+		}
 	}
 
 	#migrateAuthSchemaV0ToV1(): void {
@@ -5209,11 +6073,16 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		});
 		migrate();
 	}
+	#migrateAuthSchemaV4ToV5(): void {
+		const columns = this.#db.prepare("PRAGMA table_info(auth_credentials)").all() as Array<{ name?: string }>;
+		if (columns.some(column => column.name === "revision")) return;
+		this.#db.run("ALTER TABLE auth_credentials ADD COLUMN revision INTEGER NOT NULL DEFAULT 1");
+	}
 
 	#backfillCredentialIdentityKeys(): void {
 		const rows = this.#db
 			.prepare(
-				"SELECT id, provider, credential_type, data, disabled_cause, identity_key FROM auth_credentials WHERE identity_key IS NULL ORDER BY id ASC",
+				"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE identity_key IS NULL ORDER BY id ASC",
 			)
 			.all() as AuthRow[];
 		if (rows.length === 0) return;
@@ -5241,6 +6110,79 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		}
 		return results;
 	}
+
+	listCredentialInventory(provider?: string): CredentialInventoryRecord[] {
+		const rows =
+			provider === undefined
+				? (this.#listAllStmt.all() as AuthRow[])
+				: (this.#listAllByProviderStmt.all(provider) as AuthRow[]);
+		const results: CredentialInventoryRecord[] = [];
+		for (const row of rows) {
+			const credential = deserializeCredential(row);
+			if (!credential) continue;
+			const identityLabel =
+				credential.type === "oauth"
+					? (credential.email ?? credential.accountId ?? credential.projectId ?? null)
+					: null;
+			results.push({
+				id: row.id,
+				provider: row.provider,
+				credentialKind: credential.type,
+				identityLabel,
+				...(credential.type === "oauth" && credential.accountId ? { accountId: credential.accountId } : {}),
+				...(credential.type === "oauth" && credential.email ? { email: credential.email } : {}),
+				...(credential.type === "oauth" && credential.projectId ? { projectId: credential.projectId } : {}),
+				disabled: row.disabled_cause !== null,
+				disabledCause: row.disabled_cause,
+			});
+		}
+		return results;
+	}
+
+	listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[] {
+		const rows =
+			provider === undefined
+				? (this.#listAllStmt.all() as AuthRow[])
+				: (this.#listAllByProviderStmt.all(provider) as AuthRow[]);
+		return rows
+			.filter(row => row.credential_type === "oauth")
+			.map(row => ({ id: row.id, provider: row.provider, expectedRevision: row.revision }));
+	}
+	removeAuthCredentialsHard(
+		provider: string,
+		targets: readonly CredentialRemovalTarget[],
+	): AuthCredentialHardRemovalResult {
+		const unique = [...new Map(targets.map(target => [target.id, target])).values()];
+		const remove = this.#db.transaction((): AuthCredentialHardRemovalResult => {
+			const currentIds: number[] = [];
+			for (const target of unique) {
+				const row = this.#db
+					.prepare("SELECT id, provider, credential_type, revision FROM auth_credentials WHERE id = ?")
+					.get(target.id) as
+					| { id?: number; provider?: string; credential_type?: string; revision?: number }
+					| undefined;
+				if (
+					!row ||
+					row.provider !== provider ||
+					row.credential_type !== "oauth" ||
+					row.revision !== target.expectedRevision
+				) {
+					currentIds.push(row?.id ?? target.id);
+				}
+			}
+			if (currentIds.length > 0) return { kind: "conflict", currentIds };
+			for (const target of unique) {
+				this.#hardDeleteStmt.run(target.id);
+				this.#db.prepare("DELETE FROM oauth_refresh_leases WHERE credential_id = ?").run(target.id);
+				this.#db.prepare("DELETE FROM cache WHERE key = ?").run(`${HEALTH_CACHE_PREFIX}${target.id}`);
+			}
+			this.#db
+				.prepare("DELETE FROM cache WHERE substr(key, 1, ?) = ?")
+				.run(`usage_cache:report:${provider}:`.length, `usage_cache:report:${provider}:`);
+			return { kind: "removed", ids: unique.map(target => target.id) };
+		});
+		return remove();
+	}
 	claimOAuthRefreshLease(
 		credentialId: number,
 		expectedRefresh: string,
@@ -5252,7 +6194,7 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		const claim = this.#db.transaction((): OAuthRefreshLeaseClaim => {
 			const row = this.#db
 				.prepare(
-					"SELECT id, provider, credential_type, data, disabled_cause, identity_key FROM auth_credentials WHERE id = ? AND disabled_cause IS NULL",
+					"SELECT id, provider, credential_type, data, disabled_cause, identity_key, revision FROM auth_credentials WHERE id = ? AND disabled_cause IS NULL",
 				)
 				.get(credentialId) as AuthRow | undefined;
 			const credential = row ? deserializeCredential(row) : null;
@@ -5699,6 +6641,8 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		this.#closed = true;
 		this.#listActiveStmt.finalize();
 		this.#listActiveByProviderStmt.finalize();
+		this.#listAllStmt.finalize();
+		this.#listAllByProviderStmt.finalize();
 		this.#listDisabledByProviderStmt.finalize();
 		this.#insertStmt.finalize();
 		this.#updateStmt.finalize();