@linxiraos/pi-ai 1.1.26 → 1.2.0

package/src/auth/blocks.ts

@@ -64,6 +64,14 @@ export function credentialBlockScopesForRequest(
  */
 type CredentialBackoff = { until: number; timed: boolean; probeAfter: number; persisted?: boolean };
 
+/**
+ * One read of a credential's persisted blocks under a providerKey, keyed by
+ * scope (`""` is unscoped). `undefined`: the store has no bulk read, so use
+ * per-scope point reads. `null`: unreadable (damaged store or failed read), so
+ * it neither contributes deadlines nor retires mirrored in-memory blocks.
+ */
+type PersistedBlockScopes = ReadonlyMap<string, number> | null | undefined;
+
 /** Latch for unrecoverably corrupt persisted block stores, shared with the credential pool. */
 export class BlockStoreHealth {
 	readonly #sourceLabel: string | undefined;
@@ -134,19 +142,37 @@ export class CredentialBlocks implements BlocksApi {
 		}
 	}
 
-	/** Returns in-memory block expiry timestamp for a credential/key pair, cleaning up expired entries. */
-	#getCredentialBlockedUntilForKey(backoffKey: string, credentialId: number, nowMs: number): number | undefined {
+	/**
+	 * Returns in-memory block expiry timestamp for a credential/key pair, cleaning up expired entries.
+	 * `persistedScopes` is a bulk read for the key's providerKey; omitted, the store is point-read.
+	 */
+	#getCredentialBlockedUntilForKey(
+		backoffKey: string,
+		credentialId: number,
+		nowMs: number,
+		persistedScopes: PersistedBlockScopes = undefined,
+	): number | undefined {
 		const block = this.#credentialBackoff.get(backoffKey)?.get(credentialId);
 		if (!block) return undefined;
 		// Once mirrored successfully, the store is authoritative for cross-process
 		// deletion. A reset in a sibling must also retire this process's old map entry.
-		if (block.persisted && !this.#deps.health.damaged && this.#deps.store.getCredentialBlock) {
+		// Upserts are longest-wins, so a persisted row shorter than the deadline this
+		// process mirrored means the row was deleted and replaced: the old deadline
+		// was superseded and must not win the next longest-wins merge.
+		if (
+			block.persisted &&
+			!this.#deps.health.damaged &&
+			persistedScopes !== null &&
+			(persistedScopes !== undefined || this.#deps.store.getCredentialBlock)
+		) {
 			const separator = backoffKey.indexOf("\0");
 			const providerKey = separator < 0 ? backoffKey : backoffKey.slice(0, separator);
 			const scope = separator < 0 ? "" : backoffKey.slice(separator + 1);
 			try {
-				const persisted = this.#deps.store.getCredentialBlock(credentialId, providerKey, scope);
-				if (persisted === undefined) {
+				const persisted = persistedScopes
+					? persistedScopes.get(scope)
+					: this.#deps.store.getCredentialBlock?.(credentialId, providerKey, scope);
+				if (persisted === undefined || persisted < block.until) {
 					this.#deleteCredentialBackoff(backoffKey, credentialId);
 					return undefined;
 				}
@@ -172,7 +198,9 @@ export class CredentialBlocks implements BlocksApi {
 		credentialId: number,
 		providerKey: string,
 		blockScope: string | undefined,
+		persistedScopes: PersistedBlockScopes = undefined,
 	): number | undefined {
+		if (persistedScopes !== undefined) return persistedScopes?.get(blockScope ?? "");
 		if (this.#deps.health.damaged) return undefined;
 		const getCredentialBlock = this.#deps.store.getCredentialBlock?.bind(this.#deps.store);
 		if (!getCredentialBlock) return undefined;
@@ -190,6 +218,20 @@ export class CredentialBlocks implements BlocksApi {
 		}
 	}
 
+	/** Every persisted scope of one credential/providerKey in a single store read, when supported. */
+	#readPersistedCredentialBlockScopes(credentialId: number, providerKey: string): PersistedBlockScopes {
+		const store = this.#deps.store;
+		if (!store.getCredentialBlockScopes) return undefined;
+		if (this.#deps.health.damaged) return null;
+		try {
+			return store.getCredentialBlockScopes(credentialId, providerKey);
+		} catch (err) {
+			if (this.#deps.health.handle(err)) return null;
+			logger.debug("Failed to read credential blocks from persistent store", { err, credentialId, providerKey });
+			return null;
+		}
+	}
+
 	#readPersistedCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number {
 		if (this.#deps.health.damaged) return 0;
 		const getCredentialBlockReconcileAfter = this.#deps.store.getCredentialBlockReconcileAfter?.bind(
@@ -212,13 +254,19 @@ export class CredentialBlocks implements BlocksApi {
 		}
 	}
 
-	#exactBlockedUntil(credentialId: number, providerKey: string, scope: string | undefined): number | undefined {
+	#exactBlockedUntil(
+		credentialId: number,
+		providerKey: string,
+		scope: string | undefined,
+		persistedScopes: PersistedBlockScopes = this.#readPersistedCredentialBlockScopes(credentialId, providerKey),
+	): number | undefined {
 		const memory = this.#getCredentialBlockedUntilForKey(
 			scopedBackoffKey(providerKey, scope),
 			credentialId,
 			Date.now(),
+			persistedScopes,
 		);
-		const persisted = this.#readPersistedCredentialBlock(credentialId, providerKey, scope);
+		const persisted = this.#readPersistedCredentialBlock(credentialId, providerKey, scope, persistedScopes);
 		return memory === undefined ? persisted : persisted === undefined ? memory : Math.max(memory, persisted);
 	}
 
@@ -228,6 +276,22 @@ export class CredentialBlocks implements BlocksApi {
 		providerKey: string,
 		credentialIndex: number,
 		blockScopeOrScopes: string | readonly string[] | undefined = undefined,
+	): number | undefined {
+		const credentialId = this.#deps.pool.entries(provider)[credentialIndex]?.id;
+		if (credentialId === undefined) return undefined;
+		return this.#blockedUntilById(
+			credentialId,
+			providerKey,
+			blockScopeOrScopes,
+			this.#readPersistedCredentialBlockScopes(credentialId, providerKey),
+		);
+	}
+
+	#blockedUntilById(
+		credentialId: number,
+		providerKey: string,
+		blockScopeOrScopes: string | readonly string[] | undefined,
+		persistedScopes: PersistedBlockScopes,
 	): number | undefined {
 		const nowMs = Date.now();
 		// A request honours its own scope plus any legacy catch-all scope, so a
@@ -236,21 +300,25 @@ export class CredentialBlocks implements BlocksApi {
 			...PROTECTED_BLOCK_SCOPES,
 			...(typeof blockScopeOrScopes === "string" ? [blockScopeOrScopes] : (blockScopeOrScopes ?? [])),
 		].filter(scope => scope.length > 0);
-		const credentialId = this.#deps.pool.entries(provider)[credentialIndex]?.id;
-		if (credentialId === undefined) return undefined;
-		let blockedUntil = this.#getCredentialBlockedUntilForKey(providerKey, credentialId, nowMs);
+		let blockedUntil = this.#getCredentialBlockedUntilForKey(providerKey, credentialId, nowMs, persistedScopes);
 		for (const blockScope of scopes) {
 			const scopedBlockedUntil = this.#getCredentialBlockedUntilForKey(
 				scopedBackoffKey(providerKey, blockScope),
 				credentialId,
 				nowMs,
+				persistedScopes,
 			);
 			if (scopedBlockedUntil !== undefined && (blockedUntil === undefined || scopedBlockedUntil > blockedUntil)) {
 				blockedUntil = scopedBlockedUntil;
 			}
 		}
 
-		const persistedGlobalBlockedUntil = this.#readPersistedCredentialBlock(credentialId, providerKey, "");
+		const persistedGlobalBlockedUntil = this.#readPersistedCredentialBlock(
+			credentialId,
+			providerKey,
+			"",
+			persistedScopes,
+		);
 		if (
 			persistedGlobalBlockedUntil !== undefined &&
 			(blockedUntil === undefined || persistedGlobalBlockedUntil > blockedUntil)
@@ -258,7 +326,12 @@ export class CredentialBlocks implements BlocksApi {
 			blockedUntil = persistedGlobalBlockedUntil;
 		}
 		for (const blockScope of scopes) {
-			const persistedScopedBlockedUntil = this.#readPersistedCredentialBlock(credentialId, providerKey, blockScope);
+			const persistedScopedBlockedUntil = this.#readPersistedCredentialBlock(
+				credentialId,
+				providerKey,
+				blockScope,
+				persistedScopes,
+			);
 			if (
 				persistedScopedBlockedUntil !== undefined &&
 				(blockedUntil === undefined || persistedScopedBlockedUntil > blockedUntil)
@@ -437,14 +510,20 @@ export class CredentialBlocks implements BlocksApi {
 		if (!this.supportsHealing(provider)) return false;
 		const credentialId = this.#deps.pool.entries(provider)[credentialIndex]?.id;
 		if (credentialId === undefined) return false;
-		if (PROTECTED_BLOCK_SCOPES.some(scope => this.#exactBlockedUntil(credentialId, providerKey, scope) !== undefined))
+		// One persisted read serves the protected-scope, global, and requested checks.
+		const persistedScopes = this.#readPersistedCredentialBlockScopes(credentialId, providerKey);
+		if (
+			PROTECTED_BLOCK_SCOPES.some(
+				scope => this.#exactBlockedUntil(credentialId, providerKey, scope, persistedScopes) !== undefined,
+			)
+		)
 			return false;
 		if (
 			!this.#deps.strategies(provider)?.healsGlobalBlocks &&
-			this.blockedUntil(provider, providerKey, credentialIndex) !== undefined
+			this.#blockedUntilById(credentialId, providerKey, undefined, persistedScopes) !== undefined
 		)
 			return false;
-		return this.blockedUntil(provider, providerKey, credentialIndex, blockScopeOrScopes) !== undefined;
+		return this.#blockedUntilById(credentialId, providerKey, blockScopeOrScopes, persistedScopes) !== undefined;
 	}
 
 	/**

package/src/auth/cascade.ts

@@ -1,13 +1,13 @@
 import { authPolicyFor } from "@linxiraos/pi-catalog/compat/auth";
-import { $env, $envExact } from "@linxiraos/pi-utils";
+import { $env, $envExact, logger } from "@linxiraos/pi-utils";
 import { type ApiKeyResolver, markAfterSiblingWait, type ResolvedApiKey } from "../auth-retry";
+import { getEnvApiKey, getEnvApiKeyName } from "../env-api-key";
 import * as AIError from "../error";
 import { isUsageLimitOutcome } from "../error/rate-limit";
 import { AUTHENTICATED_SENTINEL } from "../registry/types";
-import { getEnvApiKey, getEnvApiKeyName } from "../stream";
 import type { SessionAffinity } from "./affinity";
 import type { CredentialPool } from "./pool";
-import type { CredentialSelector } from "./select";
+import type { CredentialSelector, OAuthResolutionResult } from "./select";
 import type {
 	AuthApiKeyOptions,
 	AuthCredential,
@@ -32,6 +32,7 @@ export class KeyOverrides {
 	#runtimeOverrides: Map<string, string> = new Map();
 	#configOverrides: Map<string, string> = new Map();
 	#configFallbacks: Map<string, string> = new Map();
+	#mirrorKeys: Map<string, string> = new Map();
 	#configValueResolver: (config: string) => Promise<string | undefined>;
 
 	constructor(resolver?: (config: string) => Promise<string | undefined>) {
@@ -42,6 +43,17 @@ export class KeyOverrides {
 		return this.#runtimeOverrides.has(provider) || this.#configOverrides.has(provider);
 	}
 
+	/**
+	 * Whether an override replaces OAuth for a session. Any override does for an
+	 * unrestricted session. A restricted session skips the runtime key, but a
+	 * config key still blocks OAuth: it marks the provider's endpoint (often a
+	 * proxy) as taking that key, so the session fails closed instead of sending
+	 * a pooled OAuth token there (see `KeyCascade.get`).
+	 */
+	suppressesOAuth(provider: string, restricted: boolean): boolean {
+		return restricted ? this.#configOverrides.has(provider) : this.has(provider);
+	}
+
 	runtimeKey(provider: string): string | undefined {
 		return this.#runtimeOverrides.get(provider);
 	}
@@ -55,6 +67,16 @@ export class KeyOverrides {
 		return this.#configFallbacks.get(provider);
 	}
 
+	/**
+	 * Config value consulted only after every other source, including stored
+	 * api_key credentials — the lowest cascade tier. The OMP compatibility
+	 * overlay uses it so an upstream key is a pure fallback: any credential
+	 * the user later stores locally wins without needing to evict the mirror.
+	 */
+	mirrorKey(provider: string): string | undefined {
+		return this.#mirrorKeys.get(provider);
+	}
+
 	/** Resolve a config value (env var name, "!command", literal) to the secret. */
 	resolve(config: string): Promise<string | undefined> {
 		return this.#configValueResolver(config);
@@ -89,8 +111,19 @@ export class KeyOverrides {
 	 * credentials (at the env-var tier). Providers that own a `/login` flow use
 	 * this so their default key reference (e.g. an unset env-var name, which
 	 * resolves to its literal text) cannot shadow the key the user logged in with.
+	 *
+	 * `mirror: true` ranks the value below everything else, under stored
+	 * api_key credentials — a read-only compatibility mirror (upstream OMP
+	 * agent.db key) that must never shadow a key the user stores locally.
 	 */
-	setConfig(provider: string, apiKeyConfig: string, options?: { fallback?: boolean }): void {
+	setConfig(provider: string, apiKeyConfig: string, options?: { fallback?: boolean; mirror?: boolean }): void {
+		if (options?.mirror) {
+			this.#configOverrides.delete(provider);
+			this.#configFallbacks.delete(provider);
+			this.#mirrorKeys.set(provider, apiKeyConfig);
+			return;
+		}
+		this.#mirrorKeys.delete(provider);
 		if (options?.fallback) {
 			this.#configOverrides.delete(provider);
 			this.#configFallbacks.set(provider, apiKeyConfig);
@@ -101,11 +134,12 @@ export class KeyOverrides {
 	}
 
 	/**
-	 * Remove a single config-sourced API key (override or fallback).
+	 * Remove a single config-sourced API key (override, fallback, or mirror).
 	 */
 	removeConfig(provider: string): void {
 		this.#configOverrides.delete(provider);
 		this.#configFallbacks.delete(provider);
+		this.#mirrorKeys.delete(provider);
 	}
 
 	/**
@@ -115,6 +149,7 @@ export class KeyOverrides {
 	clearConfig(): void {
 		this.#configOverrides.clear();
 		this.#configFallbacks.clear();
+		this.#mirrorKeys.clear();
 	}
 
 	/**
@@ -139,7 +174,7 @@ export interface KeyCascadeDeps {
 	sourceLabel?: string;
 }
 
-/** The provider auth precedence cascade (runtime → config → OAuth → login key → env → stored key). */
+/** The provider auth precedence cascade (runtime → config → OAuth → login key → env → stored key → compat mirror). */
 export class KeyCascade implements KeysApi {
 	#deps: KeyCascadeDeps;
 
@@ -196,8 +231,8 @@ export class KeyCascade implements KeysApi {
 	/**
 	 * Classify where a provider's auth comes from, following the same precedence
 	 * as {@link KeyCascade.get}: runtime override → config override →
-	 * stored OAuth → login-stored api_key → config fallback → env var → stored api_key.
-	 * Returns undefined when no auth is configured.
+	 * stored OAuth → login-stored api_key → config fallback → env var →
+	 * stored api_key → compat mirror. Returns undefined when no auth is configured.
 	 *
 	 * Compact, structured counterpart to {@link KeyCascade.describe}; `env`
 	 * selects dedicated-only, alias-aware, or no environment fallback.
@@ -219,6 +254,7 @@ export class KeyCascade implements KeysApi {
 			return { kind: "env", envVar: getEnvApiKeyName(provider), concrete };
 		}
 		if (bearing.some(credential => credential.type === "api_key")) return { kind: "api_key", concrete: true };
+		if (this.#deps.overrides.mirrorKey(provider) !== undefined) return { kind: "config", concrete: true };
 		return undefined;
 	}
 
@@ -294,10 +330,18 @@ export class KeyCascade implements KeysApi {
 		if (apiKeySelection) {
 			return this.#deps.overrides.resolve(apiKeySelection.credential.key);
 		}
+		const mirrorKey = this.#deps.overrides.mirrorKey(provider);
+		if (mirrorKey !== undefined) return this.#deps.overrides.resolve(mirrorKey);
 		return undefined;
 	}
 
-	/** Resolve a bearer together with the stored row that supplied it. */
+	/**
+	 * Resolve a bearer together with the stored row that supplied it, for a request.
+	 * Same precedence as {@link KeyCascade.get}, but rejects with
+	 * {@link AIError.OAuthRefreshUnavailableError} (transient, retryable) when OAuth
+	 * refresh failed with a retryable error and no other permitted source could serve
+	 * the request, so request paths retry instead of reporting a missing key.
+	 */
 	async getWithCredential(
 		provider: string,
 		sessionId?: string,
@@ -305,7 +349,7 @@ export class KeyCascade implements KeysApi {
 	): Promise<ResolvedApiKey | undefined> {
 		let credentialId: number | undefined;
 		let oauthIdentity: OAuthRequestIdentity | undefined;
-		const apiKey = await this.get(provider, sessionId, options, (id, identity) => {
+		const apiKey = await this.#resolve(provider, sessionId, options, (id, identity) => {
 			credentialId = id;
 			oauthIdentity = identity;
 		});
@@ -315,16 +359,36 @@ export class KeyCascade implements KeysApi {
 	/**
 	 * Get API key for a provider.
 	 * Priority (first match wins): runtime override, config override, OAuth,
+	 * login API key, environment variable, another stored API key, then the
+	 * lowest-tier OMP compat mirror.
 	 * login API key, environment variable, then another stored API key.
+	 * A session restricted by `sessions.restrict` resolves only its allowed
+	 * OAuth accounts and throws {@link AIError.MissingApiKeyError} when none
+	 * can serve or a config key (a models.yml `apiKey`, often for a proxy
+	 * `baseUrl`) owns the provider, rather than using any other credential.
+	 * A transient OAuth refresh failure resolves `undefined`, so availability
+	 * probes move on to their next candidate; request paths use
+	 * {@link KeyCascade.getWithCredential}, which surfaces it.
 	 */
-	async get(
+	async get(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined> {
+		try {
+			return await this.#resolve(provider, sessionId, options);
+		} catch (error) {
+			if (!(error instanceof AIError.OAuthRefreshUnavailableError)) throw error;
+			logger.debug("API key probe skipped transient OAuth refresh failure", { provider, error: error.message });
+			return undefined;
+		}
+	}
+
+	async #resolve(
 		provider: string,
 		sessionId?: string,
 		options?: AuthApiKeyOptions,
 		onCredentialId?: (id: number, identity?: OAuthRequestIdentity) => void,
 	): Promise<string | undefined> {
+		const restricted = this.#deps.affinity.isRestricted(provider, sessionId);
 		// Runtime override takes highest priority
-		const runtimeKey = this.#deps.overrides.runtimeKey(provider);
+		const runtimeKey = restricted ? undefined : this.#deps.overrides.runtimeKey(provider);
 		if (runtimeKey) {
 			return runtimeKey;
 		}
@@ -334,14 +398,29 @@ export class KeyCascade implements KeysApi {
 		// (e.g. an auth-gateway) and supplied the bearer for that endpoint —
 		// honor it instead of forwarding an upstream OAuth token that the proxy
 		// won't accept.
-		const configKey = this.#deps.overrides.configKey(provider);
+		if (restricted && this.#deps.overrides.configKey(provider) !== undefined) {
+			throw new AIError.MissingApiKeyError(
+				provider,
+				`No API key for provider: ${provider} (session ${sessionId} is restricted to its OAuth account pool, but models.yml configures an apiKey for this provider, and pooled OAuth tokens are never sent past it)`,
+			);
+		}
+		const configKey = restricted ? undefined : this.#deps.overrides.configKey(provider);
 		if (configKey !== undefined) {
 			return this.#deps.overrides.resolve(configKey);
 		}
 
 		// Precedence: a deliberate OAuth/login credential wins, then an explicit env var,
 		// then a stored static api_key (which may be a stale broker-migrated copy) as a last resort.
-		const oauthResolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
+		// A transient OAuth refresh failure still lets later sources serve the request; it is
+		// rethrown only when none can, so callers retry instead of reporting a missing key.
+		let oauthResolved: OAuthResolutionResult | undefined;
+		let oauthRefreshFailure: AIError.OAuthRefreshUnavailableError | undefined;
+		try {
+			oauthResolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
+		} catch (error) {
+			if (!(error instanceof AIError.OAuthRefreshUnavailableError)) throw error;
+			oauthRefreshFailure = error;
+		}
 		if (oauthResolved) {
 			if (onCredentialId && oauthResolved.credentialId !== undefined) {
 				const { orgId, region, inferenceRegion } = oauthResolved.credential;
@@ -349,6 +428,13 @@ export class KeyCascade implements KeysApi {
 			}
 			return oauthResolved.apiKey;
 		}
+		if (restricted) {
+			if (oauthRefreshFailure) throw oauthRefreshFailure;
+			throw new AIError.MissingApiKeyError(
+				provider,
+				`No API key for provider: ${provider} (session ${sessionId} is restricted to its OAuth account pool and none of those accounts is available)`,
+			);
+		}
 		const loginApiKeySelection = await this.#deps.selector.selectApiKey(
 			provider,
 			sessionId,
@@ -356,7 +442,9 @@ export class KeyCascade implements KeysApi {
 			credential => credential.source === "login" && !this.isKeylessFallback(provider, credential),
 		);
 		if (loginApiKeySelection) {
-			this.#deps.affinity.record(provider, sessionId, "api_key", loginApiKeySelection.index);
+			if (options?.recordAffinity !== false) {
+				this.#deps.affinity.record(provider, sessionId, "api_key", loginApiKeySelection.index);
+			}
 			const credentialId = onCredentialId
 				? this.#deps.pool.entries(provider)[loginApiKeySelection.index]?.id
 				: undefined;
@@ -382,12 +470,17 @@ export class KeyCascade implements KeysApi {
 			credential => credential.source !== "login",
 		);
 		if (apiKeySelection) {
-			this.#deps.affinity.record(provider, sessionId, "api_key", apiKeySelection.index);
+			if (options?.recordAffinity !== false) {
+				this.#deps.affinity.record(provider, sessionId, "api_key", apiKeySelection.index);
+			}
 			const credentialId = onCredentialId ? this.#deps.pool.entries(provider)[apiKeySelection.index]?.id : undefined;
 			const apiKey = await this.#deps.overrides.resolve(apiKeySelection.credential.key);
 			if (apiKey !== undefined && credentialId !== undefined) onCredentialId?.(credentialId);
 			return apiKey;
 		}
+		const mirrorKey = this.#deps.overrides.mirrorKey(provider);
+		if (mirrorKey !== undefined) return this.#deps.overrides.resolve(mirrorKey);
+		if (oauthRefreshFailure) throw oauthRefreshFailure;
 		return undefined;
 	}
 
@@ -454,6 +547,7 @@ export class KeyCascade implements KeysApi {
 	 *   4. API key persisted by a successful `/login`.
 	 *   5. Env var — overrides a stored static api_key (e.g. a stale broker copy).
 	 *   6. Stored api_key credential.
+	 *   7. OMP compatibility mirror (upstream agent.db fallback key).
 	 *
 	 * The string is purely informational; consumers must not parse it.
 	 */
@@ -504,6 +598,7 @@ export class KeyCascade implements KeysApi {
 			credential => credential.type !== "api_key" || credential.source !== "login",
 		);
 		if (apiKeySource) return apiKeySource;
+		if (this.#deps.overrides.mirrorKey(provider) !== undefined) return "OMP compatibility mirror (upstream agent.db)";
 		return undefined;
 	}
 
@@ -515,7 +610,7 @@ export class KeyCascade implements KeysApi {
 		this.#deps.overrides.removeRuntime(provider);
 	}
 
-	setConfig(provider: string, apiKeyConfig: string, options?: { fallback?: boolean }): void {
+	setConfig(provider: string, apiKeyConfig: string, options?: { fallback?: boolean; mirror?: boolean }): void {
 		this.#deps.overrides.setConfig(provider, apiKeyConfig, options);
 	}
 

package/src/auth/health.ts

@@ -1,5 +1,5 @@
 import type { Provider } from "../types";
-import { resolveUsedFraction } from "../usage";
+import { isWithinUsageReserve, resolveUsedFraction } from "../usage";
 import type {
 	CredentialRankingContext,
 	UsageCredential,
@@ -224,7 +224,7 @@ export class CredentialHealth implements HealthApi {
 				return {
 					credentialId: entry.id,
 					credentialType,
-					state: remainingFraction <= resolveReserveFraction(entry) ? "reserve" : "healthy",
+					state: isWithinUsageReserve(remainingFraction, resolveReserveFraction(entry)) ? "reserve" : "healthy",
 					remainingFraction,
 				};
 			}),
@@ -283,6 +283,7 @@ export class CredentialHealth implements HealthApi {
 		const results: CredentialHealthResult[] = [];
 		for (const row of stored) {
 			options?.signal?.throwIfAborted();
+			if (options?.excludeProviders?.has(row.provider)) continue;
 			const base: CredentialHealthResult = {
 				id: row.id,
 				provider: row.provider,

package/src/auth/oauth.ts

@@ -127,15 +127,18 @@ export class OAuthAccounts implements OAuthApi {
 	 * `enterpriseUrl`). For pure "give me the bytes for `Authorization`"
 	 * scenarios, prefer API-key resolution.
 	 *
-	 * Returns `undefined` when no OAuth credential is available, the
-	 * credential fails to refresh, or runtime/config overrides have replaced
-	 * OAuth with an explicit API key.
+	 * Returns `undefined` when no usable OAuth credential is available
+	 * (none stored, or every one definitively failed to refresh) or
+	 * runtime/config overrides have replaced OAuth with an explicit API key.
+	 * Rejects with {@link AIError.OAuthRefreshUnavailableError} (transient,
+	 * retryable) when a retryable refresh failure left no usable credential.
 	 */
 	async access(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<OAuthAccess | undefined> {
 		// Runtime / config overrides intentionally short-circuit OAuth: when the
 		// user has pinned an API key, they expect the OAuth identity to be
-		// suppressed (same contract as account identity lookup).
-		if (this.#deps.overrides.has(provider)) {
+		// suppressed (same contract as account identity lookup). A session
+		// restricted to an account pool never uses a runtime key.
+		if (this.#deps.overrides.suppressesOAuth(provider, this.#deps.affinity.isRestricted(provider, sessionId))) {
 			return undefined;
 		}
 		const resolved = await this.#deps.selector.resolveOAuth(provider, sessionId, options);
@@ -176,9 +179,20 @@ export class OAuthAccounts implements OAuthApi {
 		options: AuthApiKeyOptions | undefined,
 	): Promise<OAuthAccessResolution> {
 		try {
+			// tryOAuth refreshes only expired tokens; it resyncs this row from the store after a forced re-mint.
+			let index = selection.index;
+			if (options?.forceRefresh) {
+				await this.refresh(selection.credentialId, options.signal, {
+					reuseRecentMint: options.refreshReason === "auth-recovery",
+					reason: options.refreshReason,
+				});
+				// The refresh re-lists rows, so a concurrently removed row can shift this one's position.
+				index = this.#deps.pool.entries(provider).findIndex(entry => entry.id === selection.credentialId);
+				if (index === -1) throw new Error(`OAuth credential ${selection.credentialId} was removed during refresh`);
+			}
 			const resolved = await this.#deps.selector.tryOAuth(
 				provider,
-				{ credential: selection.credential, index: selection.index },
+				{ credential: selection.credential, index },
 				providerKey,
 				undefined,
 				options,
@@ -236,7 +250,7 @@ export class OAuthAccounts implements OAuthApi {
 	 * credential.
 	 */
 	accounts(provider: string, sessionId?: string): OAuthAccountSummary[] {
-		if (this.#deps.overrides.has(provider)) {
+		if (this.#deps.overrides.suppressesOAuth(provider, this.#deps.affinity.isRestricted(provider, sessionId))) {
 			return [];
 		}
 		const sessionCredential = this.#deps.affinity.get(provider, sessionId);
@@ -286,9 +300,10 @@ export class OAuthAccounts implements OAuthApi {
 	 * Resolve one stored OAuth credential by its durable storage row id.
 	 *
 	 * Unlike the normal session resolver, this method never ranks, rotates, or
-	 * falls back to sibling credentials. A forced refresh re-mints only the
-	 * requested row, preserving exact-account affinity for operations whose
-	 * provenance and policy boundary are tied to one workspace.
+	 * falls back to sibling credentials. A generic forced refresh re-mints only the
+	 * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+	 * still-usable recent mint of that row. Either way exact-account affinity holds
+	 * for operations whose provenance and policy boundary are tied to one workspace.
 	 *
 	 * Returns `undefined` when the row does not exist for `provider` or an
 	 * explicit runtime/config API-key override suppresses OAuth.

package/src/auth/policy.ts

@@ -1,3 +1,4 @@
+import { logger } from "@linxiraos/pi-utils";
 import * as AIError from "../error";
 import type {
 	AuthAccountPolicies,
@@ -23,6 +24,8 @@ export function matchesAuthAccountSelector(selector: AuthAccountSelector, identi
 export class AccountPolicies {
 	#accountPolicies: AuthAccountPolicies;
 	#defaultReservePct: number;
+	/** Indexes of policies already warned as unmatched; validation runs on every selection. */
+	#warnedUnmatched = new Set<number>();
 
 	constructor(policies: AuthAccountPolicies, defaultReservePct: number | undefined) {
 		AccountPolicies.#validateAccountPolicyConfiguration(policies);
@@ -52,6 +55,7 @@ export class AccountPolicies {
 		for (const [provider, credentials] of storedCredentials) next.validateFor(provider, credentials);
 		this.#accountPolicies = next.#accountPolicies;
 		this.#defaultReservePct = next.#defaultReservePct;
+		this.#warnedUnmatched = next.#warnedUnmatched;
 	}
 
 	static #validateAccountPolicyConfiguration(accountPolicies: AuthAccountPolicies): void {
@@ -105,6 +109,7 @@ export class AccountPolicies {
 		}
 	}
 
+	/** Throw on ambiguous selectors for `provider`; a selector whose account is absent is inert and warns once. */
 	validateFor(provider: string, credentials: readonly AuthCredential[]): void {
 		const policies = this.#accountPolicies
 			.map((policy, index) => ({ policy, index }))
@@ -125,7 +130,11 @@ export class AccountPolicies {
 			}
 			const path = `auth.accountPolicies[${index}].account`;
 			if (matches.length === 0) {
-				throw new AIError.ConfigurationError(`${path} matches no stored OAuth account for ${provider}`);
+				if (!this.#warnedUnmatched.has(index)) {
+					this.#warnedUnmatched.add(index);
+					logger.warn("Account policy matches no stored OAuth account; ignoring it", { provider, path });
+				}
+				continue;
 			}
 			if (matches.length > 1) {
 				throw new AIError.ConfigurationError(

package/src/auth/pool.ts

@@ -642,11 +642,6 @@ export class CredentialPool implements CredentialsApi {
 		const index = entries.findIndex(entry => entry.id === credentialId);
 		if (index === -1) return false;
 		const remainingEntries = entries.filter((_entry, entryIndex) => entryIndex !== index);
-		this.#options.policies.validateFor(
-			provider,
-			remainingEntries.map(entry => entry.credential),
-		);
-
 		const deleted = await this.#store.deleteAuthCredential(credentialId, "deleted by user");
 		if (!deleted) return false;
 		this.replace(provider, remainingEntries);