@oh-my-pi/pi-ai 18.2.0 → 18.2.2

package/src/auth-gateway/session-state.ts

@@ -0,0 +1,312 @@
+/**
+ * Server-owned provider session state for the auth-gateway.
+ *
+ * `SimpleStreamOptions.providerSessionState` is how a provider keeps what it
+ * learned about an endpoint across turns of one conversation: Anthropic's
+ * sticky `strictToolsDisabled` / `fastModeDisabled` /
+ * `replayUnsignedThinkingDisabled` flags and dropped-thinking-prefix set,
+ * OpenAI's strict-tools and reasoning-effort fallbacks, Codex's WebSocket and
+ * turn-state sessions. An in-process omp session owns that `Map` for its whole
+ * lifetime, so a grammar-too-large 400 or a fast-mode rejection costs one
+ * wasted round-trip per session rather than one per turn.
+ *
+ * The map is deliberately non-serializable — `Set`/`Map` fields, live sockets,
+ * a `close()` method — so `pi-native-client` strips it from the wire and
+ * `pi-native-server` never accepts it. Gateway clients therefore cannot bring
+ * their own, and without a server-side owner every containerized / robomp turn
+ * re-learns every lesson from a fresh upstream rejection.
+ *
+ * A plain `Map<sessionId, …>` in a long-lived server process is a leak: nothing
+ * ever reclaims an entry, and the entries own timers and sockets. This store is
+ * an LRU with a hard entry ceiling that calls `close()` on everything it drops
+ * and on everything it still holds at shutdown — but it only ever drops an
+ * entry no request is holding, because `close()` on a live entry tears down
+ * state an in-flight stream is still streaming through.
+ */
+
+import { logger } from "@oh-my-pi/pi-utils";
+import { resetAccountScopedProviderSessionState } from "../provider-session-state";
+import type { Api, Context, Model, ProviderSessionState } from "../types";
+
+/**
+ * Retained logical sessions. Each entry is a handful of small provider records
+ * plus, for Codex, a WebSocket session — cheap to keep, but not free, so the
+ * ceiling is what turns "one entry per session id forever" into a bounded cost.
+ * Eviction is least-recently-used, so the ceiling only ever drops sessions that
+ * have been quiet longer than the 256 most recent ones.
+ */
+export const AUTH_GATEWAY_MAX_SESSION_STATES = 256;
+
+/** Why an entry's provider records were closed. Logged on teardown failure. */
+type SessionDisposeReason = "evict" | "shutdown";
+
+/**
+ * One request's claim on a retained session.
+ *
+ * `release()` is what makes the entry evictable again, so it MUST run for every
+ * outcome of the request — a `finally` at the call site for the synchronous
+ * paths, stream completion for the streaming ones. It is idempotent, so the
+ * two can overlap.
+ */
+export interface AuthGatewaySessionStateLease {
+	/** The map to hand to `streamSimple` as `providerSessionState`. */
+	readonly states: Map<string, ProviderSessionState>;
+	/** Reset account-scoped records if an in-request auth retry switches accounts. */
+	updateAccount(account: string): void;
+	/** Give up this request's claim. Idempotent. */
+	release(): void;
+}
+
+/** Everything the store needs to place one request on a retained session. */
+export interface AuthGatewaySessionStateRequest {
+	/**
+	 * The client's own session key (`prompt_cache_key` / `sessionId`), or
+	 * `undefined` when it sent none — blank counts as none. A supplied key is
+	 * authoritative: the client is telling us which conversation this is.
+	 */
+	clientKey: string | undefined;
+	model: Model<Api>;
+	/**
+	 * System prompt, tools and message history of this request. Used only when
+	 * `clientKey` is absent, to place the request on the conversation it
+	 * continues.
+	 */
+	context: Context;
+	/**
+	 * Stable identity of the account this request's credential resolved to.
+	 * A change means the gateway switched the session to a sibling credential,
+	 * so the account-dependent lessons in the retained map are re-probed. The
+	 * comparison happens on acquire and whenever an in-request auth retry
+	 * resolves a sibling credential.
+	 */
+	account: string;
+}
+
+interface RetainedSession {
+	/** Current index key. Advances as a keyless conversation grows. */
+	key: string;
+	states: Map<string, ProviderSessionState>;
+	/** Account identity of the most recent request placed on this entry. */
+	account: string;
+	/** Requests currently holding this entry. Eviction never takes one of these. */
+	leases: number;
+}
+
+/**
+ * Close every provider record an evicted (or drained) session held.
+ *
+ * Anthropic's `close()` resets its sticky flags, Codex's tears down WebSockets
+ * and GitLab Duo's stops the server-side workflow — so dropping an entry
+ * without closing it leaks exactly the resources the bound exists to cap.
+ */
+function closeSessionState(
+	states: Map<string, ProviderSessionState>,
+	sessionKey: string,
+	reason: SessionDisposeReason,
+): void {
+	for (const [providerKey, state] of states) {
+		try {
+			state.close();
+		} catch (error) {
+			// One provider's teardown must not abort the rest: a throw here
+			// propagates out of the eviction into whichever request happened to
+			// trigger it, or abandons the remainder of the shutdown drain.
+			logger.warn("auth-gateway provider session state close failed", {
+				sessionKey,
+				providerKey,
+				reason,
+				error: String(error),
+			});
+		}
+	}
+	states.clear();
+}
+
+/**
+ * Index keys this request may be placed on, most specific first.
+ *
+ * With a client key there is exactly one: the client named its conversation, so
+ * provider + model + that key is the identity.
+ *
+ * Without one the gateway has to infer the conversation, and the request's
+ * message history is the only thing that can distinguish two of them. The
+ * derived `sessionId` used for prefix caching and credential stickiness hashes
+ * the model, system prompt, tools and *first* message, which is deliberately
+ * prefix-shaped — two chats that open the same way share a cache bucket, which
+ * is a cache hit rather than a leak, and share a sticky account, which is a
+ * load-balancing hint. Retained provider state is neither: sharing it means one
+ * chat's rejection silences another chat's request, and one chat's Codex
+ * transport session answers another chat's turn. So provider state gets its own
+ * key, and only provider state: `deriveSessionId` keeps its two other jobs.
+ *
+ * The key is therefore a running hash over (provider, model, system, tools) and
+ * then every message, one key per message — the last of which identifies the
+ * exact history this request presented. Turn N+1 of a conversation extends turn
+ * N's history, so turn N's key is one of the earlier entries in turn N+1's
+ * chain: the store finds the nearest ancestor and moves that entry forward onto
+ * the new key. Two conversations that share an opening therefore share an entry
+ * only until they diverge; after that the first branch to arrive keeps the
+ * ancestor and the other starts clean. That is the most a stateless wire can
+ * tell us — before divergence the two requests are byte-identical.
+ *
+ * System prompt and tools sit in the root rather than per-message because they
+ * are not history: a client that re-stamps its system prompt every turn (a
+ * date, a cwd) starts a new lineage, exactly as it already starts a new derived
+ * `sessionId` today.
+ */
+function sessionKeys(request: AuthGatewaySessionStateRequest): string[] {
+	const { model } = request;
+	const scope = `${model.provider}\u0000${model.id}`;
+	if (request.clientKey !== undefined) return [`c\u0000${scope}\u0000${request.clientKey}`];
+	const { context } = request;
+	// NUL separates the components so none of them can forge the boundary.
+	let hash = Bun.hash(
+		`${scope}\u0000${context.systemPrompt?.join("\n\n") ?? ""}\u0000${context.tools ? JSON.stringify(context.tools) : ""}`,
+	);
+	const keys: string[] = [];
+	for (const message of context.messages) {
+		// Role + content only: omp re-stamps `timestamp` and provider metadata on
+		// every parsed message, so hashing those would break the chain on turn
+		// two of every conversation.
+		hash = Bun.hash(JSON.stringify({ role: message.role, content: message.content }), hash);
+		keys.push(`h\u0000${scope}\u0000${hash.toString(36)}`);
+	}
+	// A request with no messages has no history to place; its root is the key.
+	if (keys.length === 0) return [`h\u0000${scope}\u0000${hash.toString(36)}`];
+	keys.reverse();
+	return keys;
+}
+
+/**
+ * Bounded per-session provider state, owned by one gateway server instance.
+ *
+ * Two gateways in the same process get separate stores, so neither can hand a
+ * request another gateway's learned state or close it out from under one.
+ *
+ * The recency order is this class's own (a `Map` iterates in insertion order,
+ * and every acquire re-inserts) rather than `LRUCache`'s, because the policy
+ * needs two things a general cache cannot express: an entry that a request is
+ * still holding must be skipped when picking a victim, and an entry must be
+ * able to change key — `LRUCache` disposes on every removal, which is precisely
+ * the `close()` we must not run here.
+ */
+export class AuthGatewaySessionStateStore {
+	/** Least recently acquired first — insertion order is the LRU order. */
+	readonly #sessions = new Map<string, RetainedSession>();
+	readonly #max: number;
+
+	constructor(max: number = AUTH_GATEWAY_MAX_SESSION_STATES) {
+		if (!Number.isInteger(max) || max < 1) throw new TypeError("max must be a positive integer");
+		this.#max = max;
+	}
+
+	/** Retained logical sessions. */
+	get size(): number {
+		return this.#sessions.size;
+	}
+
+	/**
+	 * Claim the provider-session map for one request, created on first use and
+	 * returned by reference so provider mutations persist into the next request.
+	 *
+	 * Keyed by provider + model + conversation (see {@link sessionKeys}). A
+	 * client is free to reuse one session id across models, and the coarsest
+	 * provider entries do not separate models themselves (`openai-responses`
+	 * keys its strict-tools / history-replay record by provider alone,
+	 * Antigravity by a single constant), so the model belongs in the key here.
+	 * Endpoint is deliberately absent: every provider whose learning is
+	 * endpoint-specific already sub-keys it internally
+	 * (`anthropic-messages:${baseUrl}\0${modelId}`,
+	 * `openai-completions:${provider}:${baseUrl}:${modelId}`), and repeating it
+	 * would only fragment the map. The credential is absent for the same reason
+	 * — most of what is retained is true of the endpoint whoever calls it, and
+	 * Codex already sub-keys its transport by account and bearer — so a
+	 * credential switch resets the account-dependent subset instead of
+	 * splitting the entry (see `resetAccountScopedProviderSessionState`).
+	 *
+	 * The returned lease MUST be released; until then the entry cannot be
+	 * evicted.
+	 */
+	acquire(request: AuthGatewaySessionStateRequest): AuthGatewaySessionStateLease {
+		const session = this.#claim(sessionKeys(request), request.account);
+		let released = false;
+		return {
+			states: session.states,
+			updateAccount: (account: string): void => {
+				if (session.account === account) return;
+				resetAccountScopedProviderSessionState(session.states);
+				session.account = account;
+			},
+			release: (): void => {
+				if (released) return;
+				released = true;
+				session.leases--;
+				// This entry may be the victim the bound has been waiting for.
+				if (session.leases === 0) this.#evict();
+			},
+		};
+	}
+
+	/** Close and drop every retained state. Called when the gateway shuts down. */
+	close(): void {
+		// The only place a leased entry is torn down: the listener is already
+		// down, every in-flight stream is being cancelled with it, and the
+		// process cannot settle while a Codex WebSocket or Duo workflow is open.
+		for (const session of this.#sessions.values()) closeSessionState(session.states, session.key, "shutdown");
+		this.#sessions.clear();
+	}
+
+	/**
+	 * Resolve `keys` to an entry — reusing the nearest ancestor when a keyless
+	 * conversation has grown — mark it most recently used, and hand the caller
+	 * the claim. The claim is taken before the ceiling is enforced: a brand-new
+	 * entry belongs to the request that just created it, and is not a candidate
+	 * for making room for itself.
+	 */
+	#claim(keys: readonly string[], account: string): RetainedSession {
+		const key = keys[0] ?? "";
+		for (const candidate of keys) {
+			const session = this.#sessions.get(candidate);
+			if (session === undefined) continue;
+			// Re-insert at the tail for recency, under this request's own key so
+			// the next turn of this conversation finds it as its ancestor. A
+			// sibling branch of the same ancestor no longer matches, which is the
+			// point: it gets an entry of its own.
+			this.#sessions.delete(candidate);
+			session.key = key;
+			this.#sessions.set(key, session);
+			session.leases++;
+			if (session.account !== account) {
+				resetAccountScopedProviderSessionState(session.states);
+				session.account = account;
+			}
+			return session;
+		}
+		const created: RetainedSession = { key, states: new Map(), account, leases: 1 };
+		this.#sessions.set(key, created);
+		this.#evict();
+		return created;
+	}
+
+	/**
+	 * Enforce the ceiling against entries no request is holding.
+	 *
+	 * A long-running stream is exactly the entry LRU order would pick — it was
+	 * acquired when the stream opened and not touched since — so blind eviction
+	 * would `close()` the sockets and flags that stream is still using. Live
+	 * entries are skipped instead, and the store sits above its bound until
+	 * their requests release; the excess is therefore capped by the number of
+	 * concurrent requests, each of which holds a client connection.
+	 */
+	#evict(): void {
+		if (this.#sessions.size <= this.#max) return;
+		// Deleting during Map iteration is well-defined: the current and later
+		// keys stay consistent, so this walks least-recently-acquired first.
+		for (const session of this.#sessions.values()) {
+			if (this.#sessions.size <= this.#max) return;
+			if (session.leases > 0) continue;
+			this.#sessions.delete(session.key);
+			closeSessionState(session.states, session.key, "evict");
+		}
+	}
+}

package/src/auth-storage.ts

@@ -9,7 +9,7 @@
  */
 import { createHash } from "node:crypto";
 import { planRequirementFor } from "@oh-my-pi/pi-catalog/compat/behavior";
-import { $env, $envExact, extractRetryHint, getAgentDbPath, logger, untilAborted } from "@oh-my-pi/pi-utils";
+import { $env, $envExact, getAgentDbPath, logger, untilAborted } from "@oh-my-pi/pi-utils";
 import {
 	isSqliteCorruptionError,
 	resolveCredentialIdentityKey,
@@ -31,6 +31,7 @@ import type {
 } from "./registry/oauth/types";
 import { AUTHENTICATED_SENTINEL } from "./registry/types";
 import { getEnvApiKey, getEnvApiKeyName } from "./stream";
+import { extractProviderRetryHint } from "./utils/retry-after";
 import type { Provider } from "./types";
 import type {
 	ClientUsageIdentity,
@@ -765,6 +766,11 @@ export { isDefinitiveOAuthFailure } from "./error/auth-classify";
  * the usage report reveals. Callers that wait the account out (instead of
  * rotating) must sleep until this, not the error-text hint alone.
  *
+ * `requestedBlockedUntilMs` (epoch ms) is this mark call's initial deadline,
+ * before usage-report correction and longest-wins merging. Callers use it to
+ * distinguish the call's replaceable heuristic from a longer merged block
+ * that credential selection will continue enforcing.
+ *
  * `priorBlockedUntilMs` (epoch ms) is the live block deadline the map already
  * stored for this credential before this call. The merged `blockedUntilMs`
  * masks a pre-existing block shorter than this call's own heuristic
@@ -790,6 +796,8 @@ export interface UsageLimitMarkResult {
 	switched: boolean;
 	retryAtMs?: number;
 	blockedUntilMs?: number;
+	/** This mark call's initial deadline, before report correction and merging. */
+	requestedBlockedUntilMs?: number;
 	priorBlockedUntilMs?: number;
 	priorBlockedUntilTimed?: boolean;
 	reportResetAtMs?: number;
@@ -1353,7 +1361,7 @@ export class AuthStorage {
 	/** Tracks the last used credential per provider for a session (used for rate-limit switching). */
 	#sessionLastCredential: Map<
 		string,
-		Map<string, { type: AuthCredential["type"]; index: number; lastUsedAtMs?: number }>
+		Map<string, { type: AuthCredential["type"]; index: number; credentialId?: number; lastUsedAtMs?: number }>
 	> = new Map();
 	/** Recent bearer fingerprints resolved for each durable OAuth row; used only for delayed usage-limit attribution. */
 	#oauthBearerFingerprints: Map<string, Map<number, string[]>> = new Map();
@@ -1490,6 +1498,36 @@ export class AuthStorage {
 		return true;
 	}
 
+	/**
+	 * Adopt credentials another process committed before selecting or rotating.
+	 *
+	 * The store is shared across every omp process, but the pool is an
+	 * in-process cache refreshed only by this process's own writes. Without
+	 * this a long-running session ranks a stale pool for its whole lifetime:
+	 * `omp auth` in another terminal is invisible, rotation reports no usable
+	 * sibling while a freshly added account sits unblocked in SQLite, and the
+	 * turn degrades to the fallback chain. The auth-broker path already polls;
+	 * direct-store sessions had no equivalent.
+	 *
+	 * A poll is two cheap reads (`PRAGMA data_version` plus the auth revision)
+	 * and re-lists credentials only when another connection committed, so it
+	 * runs on every resolution rather than on a timer that would make recovery
+	 * depend on wall-clock spacing. It sits on the paths that read the pool —
+	 * OAuth selection, and the two public usage-limit entry points — and is
+	 * idempotent, so a rotation reached through `markUsageLimitReached` costs
+	 * one extra `data_version` read and no second reload.
+	 */
+	async #adoptExternalCredentialChanges(): Promise<void> {
+		if (this.#closed || this.#store.pollExternalChanges === undefined) return;
+		try {
+			await this.pollExternalChanges();
+		} catch (error) {
+			// A failed poll must not fail credential resolution: the in-memory
+			// pool is still serviceable, just possibly stale.
+			logger.debug("External credential poll failed", { error: String(error) });
+		}
+	}
+
 	onGenerationChanged(listener: (generation: number) => void): () => void {
 		this.#generationListeners.add(listener);
 		return () => {
@@ -2084,12 +2122,12 @@ export class AuthStorage {
 	): void {
 		if (!sessionId) return;
 		const nowMs = lastUsedAtMs ?? Date.now();
+		const credentialId = this.#getStoredCredentials(provider)[index]?.id;
 		const sessionMap = this.#sessionLastCredential.get(provider) ?? new Map();
-		sessionMap.set(sessionId, { type, index, lastUsedAtMs: nowMs });
+		sessionMap.set(sessionId, { type, index, credentialId, lastUsedAtMs: nowMs });
 		this.#sessionLastCredential.set(provider, sessionMap);
 
 		try {
-			const credentialId = this.#getStoredCredentials(provider)[index]?.id;
 			if (credentialId !== undefined) {
 				const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
 				const cacheValue = JSON.stringify({
@@ -2111,11 +2149,24 @@ export class AuthStorage {
 	#getSessionCredential(
 		provider: string,
 		sessionId: string | undefined,
-	): { type: AuthCredential["type"]; index: number; lastUsedAtMs?: number } | undefined {
+	): { type: AuthCredential["type"]; index: number; credentialId?: number; lastUsedAtMs?: number } | undefined {
 		if (!sessionId) return undefined;
 		let sessionMap = this.#sessionLastCredential.get(provider);
-		if (sessionMap?.has(sessionId)) {
-			return sessionMap.get(sessionId);
+		const live = sessionMap?.get(sessionId);
+		if (live) {
+			// Another process can add or drop rows mid-session and the pool is an
+			// index-ordered snapshot, so re-resolve the pin through its durable row
+			// id: a compacted array must not point the session at a different
+			// account, and a deleted account must not hand its slot to a sibling.
+			if (live.credentialId === undefined) return live;
+			const stored = this.#getStoredCredentials(provider);
+			const actualIndex = stored.findIndex(entry => entry.id === live.credentialId);
+			if (actualIndex === -1 || stored[actualIndex]?.credential.type !== live.type) {
+				sessionMap?.delete(sessionId);
+				return undefined;
+			}
+			live.index = actualIndex;
+			return live;
 		}
 		try {
 			const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
@@ -2149,6 +2200,7 @@ export class AuthStorage {
 				const sessionVal = {
 					type: val.type,
 					index: val.index,
+					credentialId: val.credentialId,
 					lastUsedAtMs: val.lastUsedAtMs,
 				};
 				sessionMap.set(sessionId, sessionVal);
@@ -3145,6 +3197,7 @@ export class AuthStorage {
 			onProgress: ctrl.onProgress,
 			onPrompt: ctrl.onPrompt,
 			onManualCodeInput: ctrl.onManualCodeInput ?? manualCodeInput,
+			onBrowserSession: ctrl.onBrowserSession,
 			signal: ctrl.signal,
 			fetch: ctrl.fetch,
 		});
@@ -3730,7 +3783,7 @@ export class AuthStorage {
 	ingestUsageHeaders(
 		provider: Provider,
 		headers: Record<string, string>,
-		options?: { sessionId?: string; baseUrl?: string },
+		options?: { sessionId?: string; baseUrl?: string; responseStatus?: number },
 	): boolean {
 		if (this.#fetchUsageReportsOverride) return false;
 		const parseHeaders = this.#resolveUsageProvider(provider)?.parseRateLimitHeaders;
@@ -3743,7 +3796,7 @@ export class AuthStorage {
 			this.#buildUsageRequestForOauth(provider, credential, options?.baseUrl),
 		);
 		const now = Date.now();
-		const parsedReport = parseHeaders(headers, now);
+		const parsedReport = parseHeaders(headers, now, { responseStatus: options?.responseStatus });
 		if (!parsedReport) return false;
 		// Throttled to one ingest per interval — except when a window reads
 		// exhausted: persist that snapshot immediately. A full-backed cache can
@@ -4204,7 +4257,14 @@ export class AuthStorage {
 				const credentialType = entry.credential.type;
 				const providerKey = this.#getProviderTypeKey(provider, credentialType);
 				let blockedUntil = this.#getCredentialBlockedUntil(provider, providerKey, index, blockScopes);
-				if (blockedUntil !== undefined && provider !== "openai-codex") {
+				// A block under a scope the strategy can vouch for must still fetch
+				// a probe report, or it outlives the recovery that report would
+				// prove: no report means no reconciliation, so the credential idles
+				// until the clock runs out even after quota is restored.
+				if (
+					blockedUntil !== undefined &&
+					!this.#blockedCredentialCanHeal(provider, providerKey, index, blockScopes)
+				) {
 					return {
 						credentialId: entry.id,
 						credentialType,
@@ -4231,7 +4291,7 @@ export class AuthStorage {
 					planEligibilityByCredential.set(entry.id, getOpenAICodexPlanEligibility(report, planRequirement));
 				}
 
-				if (provider === "openai-codex") {
+				if (this.#supportsUsageBlockHealing(provider)) {
 					blockedUntil = this.#getCredentialBlockedUntil(provider, providerKey, index, blockScopes);
 				}
 				if (blockedUntil !== undefined) {
@@ -4795,6 +4855,7 @@ export class AuthStorage {
 			signal?: AbortSignal;
 		},
 	): Promise<UsageLimitMarkResult> {
+		await this.#adoptExternalCredentialChanges();
 		let sessionCredential = await this.#resolveCredentialTarget(provider, sessionId, {
 			credentialId: options?.credentialId,
 			apiKey: options?.apiKey,
@@ -4820,7 +4881,8 @@ export class AuthStorage {
 
 		const routing = this.#credentialBlockRouting(provider, credentialType, options?.modelId);
 		const now = Date.now();
-		let blockedUntil = now + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs);
+		const requestedBlockedUntilMs = now + (options?.retryAfterMs ?? AuthStorage.#defaultBackoffMs);
+		let blockedUntil = requestedBlockedUntilMs;
 		// Heuristic/default fallbacks are guesses; provider-stated hints and
 		// report-derived extensions are timed.
 		let providerTimed = options?.providerTimed === true;
@@ -4871,7 +4933,11 @@ export class AuthStorage {
 			routing,
 			providerTimed,
 		);
-		return reportResetAtMs === undefined ? rotation : { ...rotation, reportResetAtMs };
+		return {
+			...rotation,
+			requestedBlockedUntilMs,
+			...(reportResetAtMs === undefined ? {} : { reportResetAtMs }),
+		};
 	}
 
 	#resolveWindowResetAt(window: UsageLimit["window"]): number | undefined {
@@ -5011,7 +5077,15 @@ export class AuthStorage {
 				);
 				let usage: UsageReport | null = null;
 				let usageChecked = false;
-				if (blockedUntil !== undefined && args.provider === "openai-codex") {
+				if (
+					blockedUntil !== undefined &&
+					this.#blockedCredentialCanHeal(
+						args.provider,
+						args.providerKey,
+						selection.index,
+						args.blockScopes ?? args.blockScope,
+					)
+				) {
 					usage = await this.#getUsageReport(args.provider, selection.credential, {
 						...args.options,
 						timeoutMs: this.#usageRequestTimeoutMs,
@@ -5136,6 +5210,7 @@ export class AuthStorage {
 		sessionId?: string,
 		options?: AuthApiKeyOptions,
 	): Promise<OAuthResolutionResult | undefined> {
+		await this.#adoptExternalCredentialChanges();
 		const credentials = this.#getCredentialsForProvider(provider)
 			.map((credential, index) => ({ credential, index }))
 			.filter((entry): entry is { credential: OAuthCredential; index: number } => entry.credential.type === "oauth");
@@ -5889,6 +5964,8 @@ export class AuthStorage {
 			return configKey;
 		}
 
+		await this.#adoptExternalCredentialChanges();
+
 		// 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 oauthSelection = this.#selectCredentialByType(provider, "oauth");
@@ -6164,6 +6241,32 @@ export class AuthStorage {
 		return true;
 	}
 
+	/**
+	 * Copy every stored credential affinity from one live session to another.
+	 *
+	 * The target receives its own sticky entries, so request resolution, usage
+	 * blocking, credential rotation, metadata, and persisted pins all continue
+	 * through the target session id without retaining a live dependency on the
+	 * source session.
+	 */
+	inheritSessionCredentials(sourceSessionId: string, targetSessionId: string): number {
+		if (!sourceSessionId || !targetSessionId || sourceSessionId === targetSessionId) return 0;
+		let inherited = 0;
+		for (const provider of this.#data.keys()) {
+			const credential = this.#getSessionCredential(provider, sourceSessionId);
+			if (!credential) continue;
+			this.#recordSessionCredential(
+				provider,
+				targetSessionId,
+				credential.type,
+				credential.index,
+				credential.lastUsedAtMs,
+			);
+			inherited += 1;
+		}
+		return inherited;
+	}
+
 	/**
 	 * Resolve every stored OAuth credential for `provider` independently.
 	 *
@@ -6612,6 +6715,29 @@ export class AuthStorage {
 		);
 	}
 
+	/**
+	 * Whether a fresh report could lift what currently blocks this credential.
+	 *
+	 * A strategy that names healable scopes can only vouch for those scopes, so
+	 * a live unscoped block — an Opus/Sonnet usage limit, a refresh failure —
+	 * keeps the credential unusable whatever the report says about a tier. A
+	 * probe then cannot change the outcome and must not be spent; the tier scope
+	 * heals on a later pass, once the block that actually holds the credential
+	 * has lifted. Codex heals through its meter metadata rather than named
+	 * scopes, so its blocks always qualify.
+	 */
+	#blockedCredentialCanHeal(
+		provider: Provider,
+		providerKey: string,
+		credentialIndex: number,
+		blockScopeOrScopes: string | readonly string[] | undefined,
+	): boolean {
+		if (!this.#supportsUsageBlockHealing(provider)) return false;
+		if (this.#rankingStrategyResolver?.(provider)?.healableBlockScopes === undefined) return true;
+		if (this.#getCredentialBlockedUntil(provider, providerKey, credentialIndex) !== undefined) return false;
+		return this.#getCredentialBlockedUntil(provider, providerKey, credentialIndex, blockScopeOrScopes) !== undefined;
+	}
+
 	/**
 	 * Self-heal stale usage-limit blocks: when a fresh live usage report says a
 	 * scope is below every limit gating it, drop its persisted and in-memory
@@ -6626,6 +6752,10 @@ export class AuthStorage {
 		if (credentialIndex < 0) return;
 		const strategy = this.#rankingStrategyResolver?.(provider);
 		if (provider !== "openai-codex") {
+			// Only a live report proves recovery. A broker can serve its retained
+			// last-good report for hours after `/usage` starts failing, and those
+			// healthy limits describe the account before the 429 that blocked it.
+			if (!Number.isFinite(report.fetchedAt) || Date.now() - report.fetchedAt > USAGE_REPORT_TTL_MS) return;
 			for (const { blockScope, limits } of strategy?.healableBlockScopes?.(report) ?? []) {
 				if (limits.length === 0 || this.#isUsageLimitReached(limits)) continue;
 				this.#clearHealedBlockScope(provider, providerKey, credentialId, credentialIndex, blockScope);
@@ -6861,6 +6991,7 @@ export class AuthStorage {
 			signal?: AbortSignal;
 		},
 	): Promise<boolean> {
+		await this.#adoptExternalCredentialChanges();
 		const error = options?.error;
 		const status = AIError.status(error);
 		const message = error instanceof Error ? error.message : typeof error === "string" ? error : undefined;
@@ -6870,7 +7001,7 @@ export class AuthStorage {
 			// Thread the provider-specified reset window (e.g. Devin "Your limit
 			// will reset in 13 minutes") into the block duration so the credential
 			// is not reselected and hammered while the cap remains active.
-			const retryAfterMs = extractRetryHint(undefined, message);
+			const retryAfterMs = extractProviderRetryHint(provider, message);
 			return (
 				await this.markUsageLimitReached(provider, sessionId, {
 					retryAfterMs,