@oh-my-pi/pi-ai 16.3.11 → 16.3.13

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## [Unreleased]
 
+## [16.3.13] - 2026-07-09
+
+### Changed
+
+- Changed the xAI Grok OAuth (`xai-oauth`) provider to use manual code-paste login by default. `/login` now accepts a pasted authorization code or full `http://127.0.0.1:56121/callback?code=...` redirect URL without starting a local callback listener ([#3277](https://github.com/can1357/oh-my-pi/pull/3277) by [@Jaaneek](https://github.com/Jaaneek)).
+- Renamed the xAI Grok OAuth provider in login and credential prompts to "xAI Grok OAuth (SuperGrok or X Premium+)" ([#3277](https://github.com/can1357/oh-my-pi/pull/3277) by [@Jaaneek](https://github.com/Jaaneek)).
+
+### Fixed
+
+- Fixed the generic lazy-stream idle watchdog aborting healthy `cursor-agent` streams with "Provider stream stalled while waiting for the next event" while a Cursor exec-channel local tool (shell/read/grep/write/MCP/…) legitimately ran longer than the idle budget. Provider streams now advertise consumer-side local work in flight and the watchdog slides its deadline instead of aborting; genuinely silent streams still time out. ([#4593](https://github.com/can1357/oh-my-pi/issues/4593))
+- Fixed OpenAI Codex/Responses reasoning streams so streamed thinking content is preserved when the final `output_item.done` reconstructs to an empty summary ([#4918](https://github.com/can1357/oh-my-pi/issues/4918)).
+- Fixed Anthropic streams hanging forever when generation wedges mid-stream (notably long `write` tool calls on Opus 4.8 high/xhigh) while the server keeps sending `ping` keepalives: pings now extend the idle watchdog only within a bounded window (3x the idle timeout) since the last real stream event, so a stalled tool-call stream times out and recovers instead of hanging with no retry path ([#4900](https://github.com/can1357/oh-my-pi/issues/4900)).
+
+## [16.3.12] - 2026-07-08
+
+### Added
+
+- Added `AssistantMessage.toolCallAbortMessages` for per-tool placeholder labels on aborted assistant turns ([#2783](https://github.com/can1357/oh-my-pi/issues/2783)).
+
+### Fixed
+
+- Fixed Anthropic replay 400s (`tool_use ids were found without tool_result blocks immediately after`) when a persisted assistant turn carries content after a completed tool call — such as a mid-turn `server-side-fallback` handoff (fallback block plus continued text/tool calls after the primary model's `tool_use`) or trailing text from cross-provider replays — by stable-partitioning assistant content so all `tool_use` blocks trail the non-`tool_use` chain. ([#4781](https://github.com/can1357/oh-my-pi/issues/4781), [#544](https://github.com/can1357/oh-my-pi/issues/544))
+- Fixed access-token-only OAuth credentials attempting token refresh with an empty refresh token after expiry.
+- Fixed gateway usage-limit retries falling through to cross-provider model fallback before trying a sibling credential from the same provider.
+- Fixed Codex usage-limit rotation treating Plus and K-12 accounts as separate quota groups for shared 5-hour/7-day windows.
+- Fixed OpenAI Responses streams that end with `response.done` being misclassified as premature stream closures.
+- Fixed OpenCode Go `/login` credentials being shadowed by an existing `OPENCODE_API_KEY` env fallback after switching accounts. ([#4688](https://github.com/can1357/oh-my-pi/issues/4688))
+- Fixed OpenAI Codex WebSocket continuations to treat proxy stale-anchor codes such as `codex_previous_response_stale` as an expired `previous_response_id` chain — same recovery class as the OpenAI-standard `previous_response_not_found` — so the turn is retried with full context instead of surfacing the error to the user ([#4624](https://github.com/can1357/oh-my-pi/issues/4624)).
+- Fixed Azure Foundry Anthropic utility requests to omit the structured-output beta whenever strict tools are disabled, preventing `structured_outputs not supported in your workspace` failures for Sonnet 5 compaction ([#4679](https://github.com/can1357/oh-my-pi/issues/4679)).
+- Fixed OAuth `launchUrl` advertisement for flows whose redirect never returns to the local callback server: custom-scheme redirects (e.g. GitLab Duo's `vscode://` URI, which `new URL` parses without complaint) and fixed non-loopback hosts no longer receive a `http://localhost:<port>/launch` copy target that misrepresents the callback endpoint and resolves nowhere for remote users.
+- Codex load balancing: clear stale persisted and in-memory usage-limit blocks for an `openai-codex` account when a fresh live usage report shows it is allowed and below all limits, including broker-backed gateway snapshots, so traffic returns to recovered accounts instead of funneling to one sibling.
+
 ## [16.3.11] - 2026-07-06
 
 ### Fixed

package/dist/types/auth-broker/discover.d.ts

@@ -19,7 +19,7 @@ export declare function getAuthBrokerTokenFilePath(): string;
  * Resolve broker connection configuration using the same precedence as the TUI:
  *
  * 1. `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN` env vars.
- * 2. `auth.broker.url` / `auth.broker.token` in `<agentDir>/config.yml`.
+ * 2. `auth.broker.url` / `auth.broker.token` in `<agentDir>/config.yml` or `<agentDir>/config.yaml`.
  * 3. `<config-root>/auth-broker.token` file (paired with a URL from env/config).
  *
  * Returns `null` when no broker URL is configured — callers should fall back to

package/dist/types/auth-retry.d.ts

@@ -21,6 +21,8 @@ export interface ApiKeyResolveContext {
     lastChance: boolean;
     /** The auth error that triggered this re-resolution, or `undefined` on the initial resolve. */
     error: unknown;
+    /** Bearer used by the failed attempt, when the caller can expose it. */
+    previousKey?: string;
     /** Caller cancel signal, threaded into any credential refresh / rotation work. */
     signal?: AbortSignal;
 }
@@ -56,7 +58,7 @@ export { isAuthRetryableError };
  */
 export declare const AUTH_RETRY_STEPS: readonly boolean[];
 /** Resolve a single retry step, swallowing resolver failures into `undefined`. */
-export declare function resolveRetryKey(resolver: ApiKeyResolver, lastChance: boolean, error: unknown, signal?: AbortSignal): Promise<string | undefined>;
+export declare function resolveRetryKey(resolver: ApiKeyResolver, lastChance: boolean, error: unknown, signal?: AbortSignal, previousKey?: string): Promise<string | undefined>;
 /**
  * Runs an auth-protected operation through the central a/b/c retry policy.
  *

package/dist/types/auth-storage.d.ts

@@ -16,6 +16,7 @@ import { type CodexResetConsumeCode, type CodexResetCredit } from "./usage/opena
 export type ApiKeyCredential = {
     type: "api_key";
     key: string;
+    source?: "login";
 };
 export type OAuthCredential = {
     type: "oauth";
@@ -678,8 +679,8 @@ export declare class AuthStorage {
     /**
      * Classify where a provider's auth comes from, following the same precedence
      * as {@link AuthStorage.getApiKey}: runtime override → config override →
-     * stored OAuth → env var → stored api_key → fallback resolver. Returns
-     * undefined when no auth is configured.
+     * stored OAuth → login-stored api_key → env var → stored api_key →
+     * fallback resolver. Returns undefined when no auth is configured.
      *
      * Compact, structured counterpart to {@link describeCredentialSource}.
      */
@@ -792,6 +793,7 @@ export declare class AuthStorage {
         retryAfterMs?: number;
         baseUrl?: string;
         modelId?: string;
+        apiKey?: string;
         signal?: AbortSignal;
     }): Promise<UsageLimitMarkResult>;
     /**
@@ -807,9 +809,10 @@ export declare class AuthStorage {
      * 1. Runtime override (CLI --api-key)
      * 2. Config override (models.yml `providers.<name>.apiKey`)
      * 3. OAuth token from storage (auto-refreshed)
-     * 4. Environment variable
-     * 5. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
-     * 6. Fallback resolver (models.yml custom providers, last-resort)
+     * 4. API key persisted by a successful `/login`
+     * 5. Environment variable
+     * 6. Stored API key (e.g. a broker-migrated copy) — last resort, so an explicit env var wins
+     * 7. Fallback resolver (models.yml custom providers, last-resort)
      */
     getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
     /**
@@ -908,6 +911,7 @@ export declare class AuthStorage {
     rotateSessionCredential(provider: string, sessionId: string | undefined, options?: {
         error?: unknown;
         modelId?: string;
+        apiKey?: string;
         signal?: AbortSignal;
     }): Promise<boolean>;
     /**
@@ -986,9 +990,10 @@ export declare class AuthStorage {
      *   1. Runtime override (`--api-key`).
      *   2. Config override (`models.yml` `providers.<name>.apiKey`).
      *   3. Stored OAuth credential.
-     *   4. Env var — overrides a stored static api_key (e.g. a stale broker copy).
-     *   5. Stored api_key credential.
-     *   6. Fallback resolver.
+     *   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. Fallback resolver.
      *
      * The string is purely informational; consumers must not parse it.
      */

package/dist/types/providers/anthropic.d.ts

@@ -157,6 +157,7 @@ export type AnthropicClientOptionsArgs = {
     hasTools?: boolean;
     thinkingEnabled?: boolean;
     thinkingDisplay?: AnthropicThinkingDisplay;
+    disableStrictTools?: boolean;
     fetch?: FetchImpl;
     claudeCodeSessionId?: string;
 };

package/dist/types/providers/cursor.d.ts

@@ -1,4 +1,7 @@
+import http2 from "node:http2";
 import { type JsonValue } from "@bufbuild/protobuf";
+import type { McpToolDefinition } from "@oh-my-pi/pi-catalog/discovery/cursor-gen/agent_pb";
+import { type AgentServerMessage, type ConversationStateStructure } from "@oh-my-pi/pi-catalog/discovery/cursor-gen/agent_pb";
 import type { AssistantMessage, CursorExecHandlerResult, CursorExecHandlers, CursorToolResultHandler, Message, StreamFunction, StreamOptions, TextContent, ThinkingContent, ToolCall, ToolResultMessage } from "../types.js";
 import { kCursorExecResolved, kStreamingBlockIndex, kStreamingBlockKind, kStreamingLastParseLen, kStreamingPartialJson } from "../utils/block-symbols.js";
 import { AssistantMessageEventStream } from "../utils/event-stream.js";
@@ -39,6 +42,8 @@ export interface BlockState {
 export interface UsageState {
     sawTokenDelta: boolean;
 }
+/** Exported for tests: drives one Cursor server message through the stream (exec waits mark the stream busy). */
+export declare function handleServerMessage(msg: AgentServerMessage, output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, blobStore: Map<string, Uint8Array>, h2Request: http2.ClientHttp2Stream, execHandlers: CursorExecHandlers | undefined, onToolResult: CursorToolResultHandler | undefined, usageState: UsageState, requestContextTools: McpToolDefinition[], onConversationCheckpoint?: (checkpoint: ConversationStateStructure) => void): Promise<void>;
 /** Exported for tests: verifies handler is invoked with correct `this` when passed as bound. */
 export declare function resolveExecHandler<TArgs, TResult>(args: TArgs, handler: ((args: TArgs) => Promise<CursorExecHandlerResult<TResult>>) | undefined, onToolResult: CursorToolResultHandler | undefined, buildFromToolResult: (toolResult: ToolResultMessage) => TResult, buildRejected: (reason: string) => TResult, buildError: (error: string) => TResult): Promise<{
     execResult: TResult;

package/dist/types/providers/openai-shared.d.ts

@@ -382,6 +382,8 @@ type ResponsesToolCallBlock = ToolCall & {
     [kStreamingLastParseLen]?: number;
 };
 export declare function appendReasoningSummaryPart(item: ResponseReasoningItem, part: ResponseReasoningItem["summary"][number]): void;
+/** Chooses the final reasoning text without discarding content already streamed into the block. */
+export declare function finalizeReasoningThinking(item: ResponseReasoningItem, streamedThinking: string): string;
 export declare function appendReasoningSummaryTextDelta(item: ResponseReasoningItem, block: ThinkingContent, delta: string, stream: AssistantMessageEventStream, output: AssistantMessage, contentIndex: number): void;
 export declare function appendReasoningSummaryPartDone(item: ResponseReasoningItem, block: ThinkingContent, stream: AssistantMessageEventStream, output: AssistantMessage, contentIndex: number): void;
 export declare function appendMessageContentPart(item: ResponseOutputMessage, part: ResponseContentPartAddedEvent["part"] | undefined): void;
@@ -400,9 +402,10 @@ export interface ProcessResponsesStreamOptions {
     onFirstToken?: () => void;
     onOutputItemDone?: (item: ResponseOutputItem) => void;
     /**
-     * Called when a terminal `response.completed` or `response.incomplete` event
-     * is successfully processed. Only invoked on the successful-completion path;
-     * thrown failure (`response.failed`) and cancellation paths never call this.
+     * Called when a terminal `response.completed`, `response.incomplete`, or
+     * `response.done` event is successfully processed. Only invoked on the
+     * successful-completion path; thrown failure (`response.failed`) and
+     * cancellation paths never call this.
      * Used by callers to detect premature stream closure (i.e. the stream ended
      * without a recognized terminal event).
      */

package/dist/types/providers/register-builtins.d.ts

@@ -13,10 +13,15 @@
 import type { AssistantMessageEventStream, Context, Model, OptionsForApi } from "../types.js";
 import { AssistantMessageEventStream as EventStreamImpl } from "../utils/event-stream.js";
 import type { BedrockOptions } from "./amazon-bedrock.js";
+import type { CursorOptions } from "./cursor.js";
+interface CursorProviderModule {
+    streamCursor: (model: Model<"cursor-agent">, context: Context, options: CursorOptions) => AssistantMessageEventStream;
+}
 interface BedrockProviderModule {
     streamBedrock: (model: Model<"bedrock-converse-stream">, context: Context, options: BedrockOptions) => AssistantMessageEventStream;
 }
 export declare function setBedrockProviderModule(module: BedrockProviderModule): void;
+export declare function setCursorProviderModule(module: CursorProviderModule): void;
 export declare const streamAnthropic: (model: Model<"anthropic-messages">, context: Context, options: OptionsForApi<"anthropic-messages">) => EventStreamImpl;
 export declare const streamAzureOpenAIResponses: (model: Model<"azure-openai-responses">, context: Context, options: OptionsForApi<"azure-openai-responses">) => EventStreamImpl;
 export declare const streamGoogle: (model: Model<"google-generative-ai">, context: Context, options: OptionsForApi<"google-generative-ai">) => EventStreamImpl;

package/dist/types/registry/oauth/callback-server.d.ts

@@ -23,6 +23,8 @@ export interface OAuthCallbackFlowOptions {
      * an actionable message before opening the browser.
      */
     allowPortFallback?: boolean;
+    /** Skip the local callback server entirely; the user pastes the code or redirect URL back. */
+    manualInputOnly?: boolean;
 }
 /**
  * Abstract base class for OAuth flows with local callback servers.

package/dist/types/registry/oauth/xai-oauth.d.ts

@@ -24,10 +24,7 @@ export declare function validateXAIEndpoint(url: string, field: string): string;
  */
 export declare function isXAIAccessTokenExpiring(jwt: string, skewSeconds?: number): boolean;
 /**
- * xAI Grok OAuth loopback flow (Hermes `_xai_oauth_loopback_login` L5315-5469).
- *
- * Uses a fixed redirect URI so the callback server fails fast instead of
- * falling back to a random port that xAI's redirect_uri allowlist rejects.
+ * xAI Grok OAuth code flow (Hermes `_xai_oauth_loopback_login` L5315-5469).
  */
 export declare class XAIOAuthFlow extends OAuthCallbackFlow {
     #private;
@@ -38,9 +35,6 @@ export declare class XAIOAuthFlow extends OAuthCallbackFlow {
     }>;
     exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials>;
 }
-/**
- * Login with xAI Grok OAuth (SuperGrok Subscription).
- */
 export declare function loginXAIOAuth(ctrl: OAuthController): Promise<OAuthCredentials>;
 /**
  * Refresh an xAI OAuth access token using a stored refresh_token.

package/dist/types/registry/registry.d.ts

@@ -265,9 +265,10 @@ declare const ALL: ({
     readonly name: "xAI";
 } | {
     readonly id: "xai-oauth";
-    readonly name: "xAI Grok OAuth (SuperGrok Subscription)";
+    readonly name: "xAI Grok OAuth (SuperGrok or X Premium+)";
     readonly login: (cb: import("./oauth/index.js").OAuthLoginCallbacks) => Promise<import("./oauth/index.js").OAuthCredentials>;
     readonly refreshToken: (credentials: import("./oauth/index.js").OAuthCredentials) => Promise<import("./oauth/index.js").OAuthCredentials>;
+    readonly pasteCodeFlow: true;
 } | {
     readonly id: "xiaomi";
     readonly name: "Xiaomi MiMo";

package/dist/types/registry/xai-oauth.d.ts

@@ -1,7 +1,8 @@
 import type { OAuthCredentials, OAuthLoginCallbacks } from "./oauth/types.js";
 export declare const xaiOauthProvider: {
     readonly id: "xai-oauth";
-    readonly name: "xAI Grok OAuth (SuperGrok Subscription)";
+    readonly name: "xAI Grok OAuth (SuperGrok or X Premium+)";
     readonly login: (cb: OAuthLoginCallbacks) => Promise<OAuthCredentials>;
     readonly refreshToken: (credentials: OAuthCredentials) => Promise<OAuthCredentials>;
+    readonly pasteCodeFlow: true;
 };

package/dist/types/types.d.ts

@@ -537,6 +537,8 @@ export interface AssistantMessage {
     stopReason: StopReason;
     stopDetails?: StopDetails | null;
     errorMessage?: string;
+    /** Per-tool abort messages used when an aborted assistant turn needs different placeholder results per tool call. */
+    toolCallAbortMessages?: Record<string, string>;
     /** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
     errorStatus?: number;
     /** Structured machine-readable error classifier; see `utils/error-id.ts` for bit layout and helpers. */

package/dist/types/utils/event-stream.d.ts

@@ -22,6 +22,13 @@ export declare class EventStream<T, R = T> implements AsyncIterable<T> {
     fail(err: unknown): void;
     [Symbol.asyncIterator](): AsyncIterator<T>;
     result(): Promise<R>;
+    /** True while local work tracked via {@link trackLocalWork} is pending. */
+    get hasPendingLocalWork(): boolean;
+    /**
+     * Track a local-work promise so idle watchdogs on this stream do not treat
+     * the event silence while it is pending as a provider stall.
+     */
+    trackLocalWork<TWork>(work: Promise<TWork>): Promise<TWork>;
 }
 export declare class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
     constructor();

package/dist/types/utils/idle-iterator.d.ts

@@ -83,6 +83,16 @@ export interface IdleTimeoutIteratorOptions {
      * keepalive/no-op events from keeping a stalled tool call alive forever.
      */
     isProgressItem?: (item: unknown) => boolean;
+    /**
+     * Reports consumer-side local work in flight for the stream: the provider
+     * transport is waiting on a server-requested local tool bridge (e.g. the
+     * Cursor exec channel) before anything can flow upstream again. While it
+     * returns true, an expired idle / first-item deadline slides forward
+     * instead of aborting — the silence is ours, not a provider stall. The
+     * watchdog re-arms with a full budget once the local work completes, so a
+     * provider that stalls afterwards is still caught.
+     */
+    hasPendingLocalWork?: () => boolean;
     /**
      * Cancel iteration as soon as this signal aborts. Required for caller-driven
      * cancellation (ESC) when the underlying transport does not surface signal

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.3.11",
+	"version": "16.3.13",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "16.3.11",
-		"@oh-my-pi/pi-utils": "16.3.11",
-		"@oh-my-pi/pi-wire": "16.3.11",
+		"@oh-my-pi/pi-catalog": "16.3.13",
+		"@oh-my-pi/pi-utils": "16.3.13",
+		"@oh-my-pi/pi-wire": "16.3.13",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/auth-broker/discover.ts

@@ -1,6 +1,6 @@
 /**
  * Broker-aware auth-storage discovery used by both the coding-agent runtime and
- * the catalog model generator. Keeps the precedence logic (env → config.yml →
+ * the catalog model generator. Keeps the precedence logic (env → config.yml/config.yaml →
  * token file → local SQLite) in one place so build-time tooling sees the same
  * credentials as the TUI.
  */
@@ -12,6 +12,7 @@ import {
 	getConfigRootDir,
 	isEnoent,
 	logger,
+	MAIN_CONFIG_FILENAMES,
 } from "@oh-my-pi/pi-utils";
 import { YAML } from "bun";
 import { AuthStorage } from "../auth-storage";
@@ -72,21 +73,24 @@ interface ConfigSnapshot {
 }
 
 async function readConfigYaml(agentDir: string): Promise<ConfigSnapshot> {
-	const configPath = path.join(agentDir, "config.yml");
-	try {
-		const raw = await Bun.file(configPath).text();
-		const parsed = YAML.parse(raw);
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
-		const record = parsed as Record<string, unknown>;
-		const url = typeof record["auth.broker.url"] === "string" ? (record["auth.broker.url"] as string) : undefined;
-		const token =
-			typeof record["auth.broker.token"] === "string" ? (record["auth.broker.token"] as string) : undefined;
-		return { url, token };
-	} catch (err) {
-		if (isEnoent(err)) return {};
-		logger.warn("auth-broker config.yml unreadable", { error: String(err) });
-		return {};
+	for (const filename of MAIN_CONFIG_FILENAMES) {
+		const configPath = path.join(agentDir, filename);
+		try {
+			const raw = await Bun.file(configPath).text();
+			const parsed = YAML.parse(raw);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+			const record = parsed as Record<string, unknown>;
+			const url = typeof record["auth.broker.url"] === "string" ? (record["auth.broker.url"] as string) : undefined;
+			const token =
+				typeof record["auth.broker.token"] === "string" ? (record["auth.broker.token"] as string) : undefined;
+			return { url, token };
+		} catch (err) {
+			if (isEnoent(err)) continue;
+			logger.warn("auth-broker config unreadable", { path: configPath, error: String(err) });
+			return {};
+		}
 	}
+	return {};
 }
 
 function resolveSnapshotTtlMs(): number {
@@ -104,7 +108,7 @@ function resolveSnapshotTtlMs(): number {
  * Resolve broker connection configuration using the same precedence as the TUI:
  *
  * 1. `OMP_AUTH_BROKER_URL` / `OMP_AUTH_BROKER_TOKEN` env vars.
- * 2. `auth.broker.url` / `auth.broker.token` in `<agentDir>/config.yml`.
+ * 2. `auth.broker.url` / `auth.broker.token` in `<agentDir>/config.yml` or `<agentDir>/config.yaml`.
  * 3. `<config-root>/auth-broker.token` file (paired with a URL from env/config).
  *
  * Returns `null` when no broker URL is configured — callers should fall back to

package/src/auth-broker/remote-store.ts

@@ -61,6 +61,41 @@ function toCredentialBlockSnapshot(block: StoredCredentialBlock): CredentialBloc
 	};
 }
 
+function credentialBlockSnapshotsEqual(
+	left: readonly CredentialBlockSnapshot[] | undefined,
+	right: readonly CredentialBlockSnapshot[] | undefined,
+): boolean {
+	const leftBlocks = left ?? [];
+	const rightBlocks = right ?? [];
+	if (leftBlocks.length !== rightBlocks.length) return false;
+	for (let index = 0; index < leftBlocks.length; index += 1) {
+		const leftBlock = leftBlocks[index]!;
+		const rightBlock = rightBlocks[index]!;
+		if (
+			leftBlock.providerKey !== rightBlock.providerKey ||
+			leftBlock.blockScope !== rightBlock.blockScope ||
+			leftBlock.blockedUntilMs !== rightBlock.blockedUntilMs
+		) {
+			return false;
+		}
+	}
+	return true;
+}
+
+function snapshotBlocksChanged(previous: readonly SnapshotEntry[], next: readonly SnapshotEntry[]): boolean {
+	const previousBlocksById = new Map<number, readonly CredentialBlockSnapshot[] | undefined>();
+	for (const entry of previous) previousBlocksById.set(entry.id, entry.blocks);
+	for (const entry of next) {
+		const previousBlocks = previousBlocksById.get(entry.id);
+		if (!credentialBlockSnapshotsEqual(previousBlocks, entry.blocks)) return true;
+		previousBlocksById.delete(entry.id);
+	}
+	for (const previousBlocks of previousBlocksById.values()) {
+		if (previousBlocks && previousBlocks.length > 0) return true;
+	}
+	return false;
+}
+
 function credentialEntryWithBlocks(
 	entry: AuthCredentialSnapshotEntry,
 	blocks: readonly CredentialBlockSnapshot[] | undefined,
@@ -173,6 +208,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	#cache: Map<string, CacheEntry> = new Map();
 	#usageCache?: UsageCacheEntry;
 	#usageInflight?: Promise<UsageReport[] | null>;
+	#usageCacheEpoch = 0;
 	#closed = false;
 	/**
 	 * `true` once the SSE consumer received its first frame and hasn't dropped
@@ -202,10 +238,9 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	#applySnapshot(snapshot: SnapshotResponse, generation: number): void {
 		const nowMs = Date.now();
-		this.#snapshot = {
-			...snapshot,
-			credentials: snapshot.credentials.map(entry => this.#normalizeSnapshotEntryBlocks(entry, nowMs)),
-		};
+		const credentials = snapshot.credentials.map(entry => this.#normalizeSnapshotEntryBlocks(entry, nowMs));
+		if (snapshotBlocksChanged(this.#snapshot.credentials, credentials)) this.#invalidateUsageCache();
+		this.#snapshot = { ...snapshot, credentials };
 		this.#generation = generation;
 		this.#snapshotReceivedAt = nowMs;
 		const onSnapshot = this.#onSnapshot;
@@ -304,6 +339,8 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	): void {
 		const incoming = this.#normalizeSnapshotEntryBlocks(entry, Date.now());
 		const index = this.#snapshot.credentials.findIndex(candidate => candidate.id === incoming.id);
+		const previousBlocks = index === -1 ? undefined : this.#snapshot.credentials[index]?.blocks;
+		if (!credentialBlockSnapshotsEqual(previousBlocks, incoming.blocks)) this.#invalidateUsageCache();
 		const credentials =
 			index === -1
 				? [...this.#snapshot.credentials, incoming]
@@ -314,6 +351,8 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	}
 
 	#removeStreamCredential(id: number, refresher: RefresherSchedule, generation: number, serverNowMs: number): void {
+		const removed = this.#snapshot.credentials.find(entry => entry.id === id);
+		if (removed?.blocks && removed.blocks.length > 0) this.#invalidateUsageCache();
 		const credentials = this.#snapshot.credentials.filter(entry => entry.id !== id);
 		this.#snapshot = { ...this.#snapshot, generation, serverNowMs, refresher, credentials };
 		this.#generation = generation;
@@ -376,6 +415,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	upsertCredentialBlock(block: StoredCredentialBlock): void {
 		this.#upsertSnapshotBlock(block);
+		this.#invalidateUsageCache();
 		const body = toCredentialBlockSnapshot(block);
 		void this.#client
 			.upsertCredentialBlock(block.credentialId, body)
@@ -394,6 +434,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	deleteCredentialBlocks(credentialId: number): void {
 		this.#deleteSnapshotBlocks(credentialId);
+		this.#invalidateUsageCache();
 		void this.#client
 			.deleteCredentialBlocks(credentialId)
 			.then(() => {
@@ -698,6 +739,12 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		}
 	}
 
+	#invalidateUsageCache(): void {
+		this.#usageCache = undefined;
+		this.#usageInflight = undefined;
+		this.#usageCacheEpoch += 1;
+	}
+
 	/**
 	 * Store-level hook consumed by `AuthStorage` — routes refresh through the
 	 * broker so the actual refresh token never leaves the broker host. Returns
@@ -834,9 +881,11 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 			return Promise.resolve(cached.reports);
 		}
 		if (this.#usageInflight) return this.#usageInflight;
+		const epoch = this.#usageCacheEpoch;
 		const inflight = this.#client
 			.fetchUsage()
 			.then(body => {
+				if (epoch !== this.#usageCacheEpoch) return this.#loadUsageReports();
 				this.#usageCache = { reports: body.reports, fetchedAt: Date.now() };
 				return body.reports;
 			})
@@ -845,11 +894,12 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 				// Documented 15s TTL fallback: cache the null so sequential callers
 				// don't re-hit the broker while it's still down. See
 				// docs/auth-broker-gateway.md § "Client-side single-flight".
+				if (epoch !== this.#usageCacheEpoch) return this.#loadUsageReports();
 				this.#usageCache = { reports: null, fetchedAt: Date.now() };
 				return null;
 			})
 			.finally(() => {
-				this.#usageInflight = undefined;
+				if (this.#usageInflight === inflight) this.#usageInflight = undefined;
 			});
 		this.#usageInflight = inflight;
 		return inflight;

package/src/auth-gateway/server.ts

@@ -233,6 +233,7 @@ async function refreshGatewayApiKeyAfterAuthError(
 			retryAfterMs,
 			baseUrl: model.baseUrl,
 			modelId: model.id,
+			apiKey: oldKey,
 			signal,
 		});
 		logger.debug("auth-gateway retrying provider request after usage-limit block", {

package/src/auth-retry.ts

@@ -1,6 +1,7 @@
 import type { OAuthAccess } from "./auth-storage";
 import * as AIError from "./error";
 import { isAuthRetryableError } from "./error/auth-classify";
+import { isUsageLimit } from "./error/flags";
 
 /**
  * Context passed to an {@link ApiKeyResolver} on each resolution attempt.
@@ -23,6 +24,8 @@ export interface ApiKeyResolveContext {
 	lastChance: boolean;
 	/** The auth error that triggered this re-resolution, or `undefined` on the initial resolve. */
 	error: unknown;
+	/** Bearer used by the failed attempt, when the caller can expose it. */
+	previousKey?: string;
 	/** Caller cancel signal, threaded into any credential refresh / rotation work. */
 	signal?: AbortSignal;
 }
@@ -87,9 +90,11 @@ export async function resolveRetryKey(
 	lastChance: boolean,
 	error: unknown,
 	signal?: AbortSignal,
+	previousKey?: string,
 ): Promise<string | undefined> {
 	try {
-		return (await resolver({ lastChance, error, signal })) || undefined;
+		const rotateSibling = lastChance || (!lastChance && isUsageLimit(error));
+		return (await resolver({ lastChance: rotateSibling, error, signal, previousKey })) || undefined;
 	} catch {
 		return undefined;
 	}
@@ -136,7 +141,7 @@ export async function withAuth<T>(
 	}
 
 	for (let i = 0; i < AUTH_RETRY_STEPS.length; i++) {
-		const nextKey = await resolveRetryKey(resolver, AUTH_RETRY_STEPS[i]!, lastError, signal);
+		const nextKey = await resolveRetryKey(resolver, AUTH_RETRY_STEPS[i]!, lastError, signal, lastKey);
 		if (nextKey === undefined || nextKey === lastKey) continue;
 		lastKey = nextKey;
 		try {