@oh-my-pi/pi-ai 18.3.5 → 18.4.1

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## [Unreleased]
 
+## [18.4.1] - 2026-09-28
+
+### Fixed
+
+- Fixed extension-provided usage reports missing from broker-connected clients when the broker does not have that provider ([#13579](https://github.com/can1357/oh-my-pi/issues/13579)).
+- Fixed signed LiteLLM `thinking_blocks` being dropped on openai-completions tool-call turns ([#13407](https://github.com/can1357/oh-my-pi/issues/13407)).
+- Fixed Anthropic turns ending on a bare `aborted` error with no retry when the connection dropped mid-response (typically during long thinking). The first-party Anthropic transport runs on `node:https`, whose Bun shim reports a response cut off mid-body as `Error("aborted")` (ECONNRESET) — indistinguishable from a cancellation, so it classified as unknown. It now surfaces as "The socket connection was closed unexpectedly…", the same wording native `fetch` uses, so the drop classifies as transient and the turn is retried; caller aborts keep their original error ([#13384](https://github.com/can1357/oh-my-pi/pull/13384) by [@jerryfane](https://github.com/jerryfane))
+- Fixed a stale Z.AI quota block pinning sessions to a fallback model after live usage recovered ([#13343](https://github.com/can1357/oh-my-pi/issues/13343)).
+- Fixed OAuth credentials being re-minted on every provider 401 during an outage; recently minted tokens are reused for auth recovery ([#13350](https://github.com/can1357/oh-my-pi/issues/13350)) ([#13485](https://github.com/can1357/oh-my-pi/pull/13485) by [@ShivamB25](https://github.com/ShivamB25)).
+- Fixed Claude usage reports intermittently dropping an account's saved resets when the separate reset probe was rate-limited or timed out; the last known saved resets now stay visible until the probe answers again ([#13474](https://github.com/can1357/oh-my-pi/pull/13474) by [@schickling-assistant](https://github.com/schickling-assistant))
+- Fixed transient Windows `EPERM` when creating the provider in-flight lock failing the request instead of retrying ([#13334](https://github.com/can1357/oh-my-pi/pull/13334) by [@1Morganmore](https://github.com/1Morganmore)).
+- Fixed rolling per-minute TPM/RPM 429s worded as quota errors being treated as exhausted quota and ending the turn ([#13253](https://github.com/can1357/oh-my-pi/issues/13253)).
+- Fixed keyless Anthropic-compatible endpoints receiving `Authorization: Bearer N/A` and `X-Api-Key: N/A` headers ([#13043](https://github.com/can1357/oh-my-pi/pull/13043) by [@jchanghong023](https://github.com/jchanghong023)).
+- Fixed legacy Windsurf Enterprise API keys being rejected because they were always sent with the Devin session-token prefix ([#12960](https://github.com/can1357/oh-my-pi/pull/12960)).
+- Fixed an exhausted Cursor "Other Models" pool blocking Grok and Composer, which Cursor bills to its own pool ([#13198](https://github.com/can1357/oh-my-pi/issues/13198)).
+- Fixed Anthropic OAuth requests leaving the agent system prompt without its own cache breakpoint: the breakpoint on the short Claude Code identity block now moves to the last system block, so a request whose messages miss the cache (such as the first after a compaction) reads the cached system prompt instead of writing it again ([#13104](https://github.com/can1357/oh-my-pi/issues/13104), [#13556](https://github.com/can1357/oh-my-pi/pull/13556) by [@aktanazat](https://github.com/aktanazat)).
+- Fixed the Anthropic system cache breakpoint covering working-directory-specific system text: it now sits before the first `<project-context>` or `<memories>` block, and on OAuth it replaces the identity-block breakpoint instead of taking a message breakpoint ([#13104](https://github.com/can1357/oh-my-pi/issues/13104)).
+
+## [18.4.0] - 2026-09-28
+
+### Breaking Changes
+
+- Changed `LimitsApi.rotate()` to return a `CredentialRotation` object (`{ switched, afterSiblingWait? }`) instead of a boolean. Check `.switched` explicitly, since the returned object is always truthy.
+
+### Added
+
+- Added image metadata to hosted OpenAI image-generation results, including the model used and each generated image’s dimensions and quality.
+
+### Changed
+
+- Redesigned the browser page displayed during OAuth login.
+
+### Fixed
+
+- Fixed Anthropic accounts remaining blocked after quota resets, including for broker-connected clients, while preserving independent authentication and model-limit restrictions.
+- Fixed concurrent usage refreshes repeatedly probing providers after failures, reducing unnecessary usage-endpoint requests.
+- Fixed Gemini and Antigravity usage and cost reporting when upstream responses omit prompt-token counts or report more cached tokens than prompt tokens.
+- Fixed credential failover after authentication errors so stored credentials rotate through every distinct sibling instead of stopping after one attempt; rotation can also wait briefly for a temporarily blocked healthy sibling to become available.
+- Fixed native judge responses without token counts producing invalid usage and cost values.
+- Fixed Cursor usage, cost, and context accounting to include final input, cache, reasoning, and output metrics, improving compaction and handoff sizing.
+- Fixed Cursor MCP tool calls routed through external executors being returned as text instead of tool calls.
+- Fixed Cursor shell-tool timeouts being displayed in milliseconds rather than seconds.
+- Fixed fetch requests over Unix sockets when `PI_PROXY` is configured.
+- Fixed Ollama chat turns being recorded with zero cost; usage is now priced using the model’s cost information.
+- Fixed Anthropic requests failing after native compaction when per-message effort settings were present; effort controls are now handled correctly with compaction.
+
 ## [18.3.5] - 2026-09-27
 
 ### Breaking Changes
@@ -2276,51 +2322,4 @@
 - Fixed explicit request-debug mode to overwrite existing `.res.log` files for the requested path instead of failing when they already exist
 - Fixed OpenAI Responses `previous_response_id` chaining on Zero Data Retention orgs: the in-provider retry classifier missed the ZDR-specific 400 ("Previous response cannot be used for this organization due to Zero Data Retention"), so chained turns kept failing every other request after a brief recovery — the chain was reset but not disabled, so the next successful full-replay turn re-armed it. The ZDR phrasing is now classified categorically: one strike disables chaining for the session (skipping the three-strike circuit breaker) and the in-call retry drops `store: true`/`previous_response_id` and replays the full transcript instead ([#2341](https://github.com/can1357/oh-my-pi/issues/2341)).
 
-## [15.11.4] - 2026-06-12
-
-### Added
-
-- Codex/Responses providers now map `end_turn: false` on the terminal stream event (Codex backend signal for "response ended, turn didn't" — commentary-only progress updates) to `stopDetails: { type: "pause_turn" }` with stopReason `"stop"`, so the agent loop can re-sample instead of ending the turn. Wired in `openai-codex-responses` and `processResponsesStream` (`openai-responses`/`azure-openai-responses`); inert for backends that never send the field.
-- Added Codex upstream protocol features to `openai-codex-responses` (tracking codex-rs as of June 2026): `onModerationMetadata` callback surfacing `response.metadata` → `openai_chatgpt_moderation_metadata` on both transports; `reasoningContext` option emitting `reasoning.context` (`auto`/`current_turn`/`all_turns`); `clientMetadata` option emitting `client_metadata` in the request body (canonical `x-codex-turn-metadata` envelope) without breaking the websocket append fast-path; and an opt-in `responsesLite` mode mirroring codex-rs — lite header on HTTP requests and the websocket upgrade, `ws_request_header_*` marker in `response.create` client metadata, lite-keyed socket pooling, image-detail stripping, forced serial tool calls, and `reasoning.context: all_turns` default. Dormant until OpenAI flips `use_responses_lite` in the model catalog.
-- Added `withOAuthAccess` — the `withAuth` counterpart for OAuth-access consumers: runs an operation through the central a/b/c auth-retry policy (resolve → force-refresh same account → rotate to a sibling) while handing the attempt the full `OAuthAccess` (bearer plus `accountId`/`projectId`/`enterpriseUrl` identity metadata). Use it instead of hand-rolled `getOAuthAccess` + fetch flows so 401s and usage-limits rotate credentials instead of failing the call.
-- Added `ProviderHttpError` — a typed HTTP error carrying `status`, `headers`, and `code` — replacing the ad-hoc `as Error & { status?... }` / `Object.assign` hacks at provider throw sites, with per-provider subclasses `CodexApiError`, `AuthGatewayError`, `GoogleApiError`, `GeminiCliApiError`, `OllamaApiError`, and `BedrockApiError`; `AnthropicApiError` now extends it. Google, Gemini CLI, Ollama, and Bedrock HTTP errors now also carry response headers, so server-suggested `retry-after` delays are visible to retry classification on those paths. The internal `withHttpStatus` helper was removed.
-- Added stateful SSE turn chaining for OpenAI Codex (on by default; disable with `PI_CODEX_STATEFUL=0` or `statefulResponses: false`): SSE requests now reuse `previous_response_id` with delta-only input instead of replaying the full transcript, mirroring the websocket fast-path via a shared transport-aware builder. Any history mutation or option change falls back to a full replay; a server-side `previous_response_not_found` (HTTP or in-stream) resets the chain and retries the turn with full context, and three consecutive stale failures disable chaining for the session.
-- Added stateful `previous_response_id` chaining to the platform OpenAI Responses provider (`openai-responses`): on by default against the official api.openai.com endpoint (forces `store: true`, which chaining requires), off for other Responses endpoints; override with `statefulResponses` or `PI_OPENAI_STATEFUL`. Chain detection compares the wire form of the conversation arguments alone — per-turn trailing scaffolding such as the GPT-5 "Juice: 0" developer item is excluded from the append-baseline prefix check and re-appended to the delta — and a rejected/stale previous response falls back to a one-shot full replay with the same circuit breaker.
-- Added `AuthStorage.getOAuthAccountIdentity()` and the `OAuthAccountIdentity` type — a read-only lookup returning the `accountId`/`email`/`projectId` of the OAuth credential a session is currently routed to, for display and metadata paths.
-
-### Changed
-
-- The GPT-5 "Juice: 0" no-reasoning developer item in `applyResponsesReasoningParams` is now gated on the resolved `compat.requiresJuiceZeroHack` flag (auto-detected from GPT-5-family model names by `@oh-my-pi/pi-catalog`, overridable per model) instead of an inline model-name check.
-
-### Fixed
-
-- Fixed websocket append fast-path to remain usable when only `client_metadata` changes between turns
-- Fixed `onModerationMetadata` handling so exceptions thrown by callback observers no longer terminate the response stream
-- Fixed local SQLite OAuth credential caches returning a stale Anthropic access token after another `omp` process refreshed and persisted the same row. `AuthStorage` now syncs the selected row from storage before returning or force-refreshing OAuth credentials, so concurrent sessions pick up peer-rotated tokens instead of surfacing a one-turn `401 Invalid authentication credentials`.
-- Fixed forced OAuth preflight refresh failures being swallowed silently in credential selection; they now emit a debug log (`OAuth preflight refresh failed`) so stale-refresh-token replays from concurrent sessions are diagnosable.
-
-## [15.11.3] - 2026-06-11
-
-### Fixed
-
-- Fixed GitHub Copilot long-context model requests to use the upstream `requestModelId` when calling Anthropic, OpenAI Responses, and OpenAI Completions APIs
-- Fixed GitHub Copilot model enablement to deduplicate catalog variants by upstream model ID when enabling all models
-
-## [15.11.2] - 2026-06-11
-
-### Fixed
-
-- Fixed Anthropic encoding of error tool results with whitespace-only content so requests no longer 400 with `tool_result: content cannot be empty if is_error is true`
-
-## [15.11.1] - 2026-06-11
-
-### Changed
-
-- Exported `resolveAnthropicMetadataUserId` so non-streaming Anthropic Messages consumers (e.g. the coding-agent web search provider) can produce the same Claude-Code-shaped `metadata.user_id` as the main streaming path.
-
-### Fixed
-
-- Preserved Anthropic `stop_details` on assistant messages so refusal and sensitive classifier stops remain structurally visible to callers. ([#2290](https://github.com/can1357/oh-my-pi/issues/2290))
-- Fixed OpenAI Responses, Azure OpenAI Responses, and OpenAI Completions streams hanging until the 120s idle watchdog errored the turn when a provider delivers the terminal frame but never sends `[DONE]` nor closes the connection. `processResponsesStream` now breaks out of the event loop on `response.completed`/`response.incomplete` (mirroring the Codex websocket/SSE terminal break), and the completions consumer breaks once `finish_reason` plus a usage payload arrived — or, for hosts that never send usage, ends the stream cleanly via a short post-finish grace window (`iterateWithTerminalGrace`) that aborts the transport to release the socket.
-
-Older entries are archived in [packages/ai/CHANGELOG.md@d58593a30902](https://github.com/can1357/oh-my-pi/blob/d58593a3090258473304608d68ffd1f620e6b695/packages/ai/CHANGELOG.md).
+Older entries are archived in [packages/ai/CHANGELOG.md@dfbf3cc34eeb](https://github.com/can1357/oh-my-pi/blob/dfbf3cc34eeb5653580f51bfbcae558a9840f697/packages/ai/CHANGELOG.md).

package/README.md

@@ -1161,6 +1161,18 @@ const response = await complete(
 );
 ```
 
+When an auth-broker client requests recovery after a provider rejects an OAuth
+bearer, the broker may reuse a still-fresh token that it minted in the previous
+five minutes instead of rotating the refresh token again. The process-local
+cache is bound to the credential ID and access token. Scheduled expiry refreshes,
+direct forced refreshes such as MCP recovery, ordinary hard-auth blocks, and
+sibling rotation keep their existing behavior. Cached refresh responses rebind
+by durable credential ID so concurrent row removal cannot switch a pinned
+session to another account.
+Generic `forceRefresh: true` requests do not opt into reuse. Provider-401 retry
+paths pass `refreshReason: "auth-recovery"` explicitly; expiry sentinels and
+usage polling do not imply that reason.
+
 ### Provider Notes
 
 **OpenAI Codex**: Requires a ChatGPT Plus or Pro subscription. Provides access to GPT-5.x Codex models with extended context windows and reasoning capabilities. The library automatically handles session-based prompt caching when `sessionId` is provided in stream options.

package/dist/types/auth/blocks.d.ts

@@ -11,6 +11,10 @@ export declare const DEFAULT_BLOCK_MS = 60000;
 export declare function providerTypeKey(provider: string, type: AuthCredential["type"]): string;
 /** Scoped backoff map key used by the credential block store. */
 export declare function scopedBackoffKey(providerKey: string, blockScope: string | undefined): string;
+/** Authentication backoffs apply to every model and cannot be healed by quota evidence. */
+export declare const AUTH_BLOCK_SCOPE = "auth";
+/** Account-policy backoffs apply to every model and survive quota resets. */
+export declare const ACCOUNT_POLICY_BLOCK_SCOPE = "account-policy";
 /** Scope key for one model-specific account-policy block, shared by selectors and rate limits. */
 export declare function modelAccountPolicyBlockScope(provider: string, modelId: string | undefined): string | undefined;
 /** Scope keys that a request must check, including model-policy constraints. */
@@ -67,26 +71,15 @@ export declare class CredentialBlocks implements BlocksApi {
      * that `markUsageLimitReached` set for the now-obsolete reset time.
      */
     clearAll(provider: string, credentialId: number): void;
-    /**
-     * Clear one backoff scope. The in-memory backoff is per scope so it is
-     * dropped directly; the persisted store deletes a credential's blocks as a
-     * unit, so it is only purged once no other scope still holds a live block.
-     * Leaving a persisted row behind is safe: the scope it belongs to is
-     * unblocked in memory, and the row heals on the pass where its own meter
-     * recovers.
-     */
-    clearScope(provider: string, credentialId: number, providerKey: string, blockScope: string | undefined): void;
+    /** Clear exactly one quota scope, preserving unrelated account and model blocks. */
+    clearScope(provider: string, credentialId: number, providerKey: string, blockScope: string | undefined): boolean;
     /** Providers whose stale usage-limit blocks a healthy live report may clear. */
     supportsHealing(provider: Provider): boolean;
     /**
      * 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.
+     * Claude reports can heal legacy account-wide quota blocks too. Explicit
+     * auth/account-policy blocks never justify a usage probe.
      */
     canHeal(provider: Provider, providerKey: string, credentialIndex: number, blockScopeOrScopes: string | readonly string[] | undefined): boolean;
     /**
@@ -107,9 +100,7 @@ export declare class CredentialBlocks implements BlocksApi {
      * Broker-server seam: persist one credential block and notify snapshot waiters.
      */
     upsert(block: StoredCredentialBlock): void;
-    /**
-     * Broker-server seam: clear all persisted blocks for one credential and notify snapshot waiters.
-     */
-    delete(credentialId: number, providerKey: string, blockScope: string): void;
+    /** Broker-server seam: clear exactly one persisted and local block and notify snapshot waiters. */
+    delete(credentialId: number, providerKey: string, blockScope: string, invalidateUsage?: boolean): void;
     deleteAll(credentialId: number): void;
 }

package/dist/types/auth/cascade.d.ts

@@ -1,4 +1,4 @@
-import type { ApiKeyResolver, ResolvedApiKey } from "../auth-retry.js";
+import { type ApiKeyResolver, type ResolvedApiKey } from "../auth-retry.js";
 import type { SessionAffinity } from "./affinity.js";
 import type { CredentialPool } from "./pool.js";
 import type { CredentialSelector } from "./select.js";

package/dist/types/auth/oauth.d.ts

@@ -5,7 +5,7 @@ import type { AccountPolicies } from "./policy.js";
 import type { CredentialPool } from "./pool.js";
 import type { OAuthRefresher } from "./refresh.js";
 import type { CredentialSelector } from "./select.js";
-import type { AuthAccountPolicy, AuthApiKeyOptions, OAuthAccess, OAuthAccessResolution, OAuthAccountIdentity, OAuthAccountSummary, OAuthApi, OAuthCredential, OAuthLoginController, OAuthLoginIdentity, StoredOAuthRefreshOptions, StoredOAuthRefreshResult, AuthCredentialSnapshotEntry } from "./types.js";
+import type { AuthAccountPolicy, AuthApiKeyOptions, AuthCredentialSnapshotEntry, OAuthAccess, OAuthAccessResolution, OAuthAccountIdentity, OAuthAccountSummary, OAuthApi, OAuthCredential, OAuthLoginController, OAuthLoginIdentity, OAuthRefreshByIdOptions, StoredOAuthRefreshOptions, StoredOAuthRefreshResult } from "./types.js";
 /** Dependencies used by the OAuth account operations. */
 export interface OAuthAccountsDeps {
     pool: CredentialPool;
@@ -87,7 +87,7 @@ export declare class OAuthAccounts implements OAuthApi {
      */
     policy(provider: string, identity: OAuthAccountIdentity): AuthAccountPolicy | undefined;
     /** Force-refresh one stored credential by its durable row id. */
-    refresh(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
     /** Refresh one stored OAuth credential through the durable ownership path. */
     refreshStored<T extends OAuthCredential = OAuthCredential>(provider: string, options: StoredOAuthRefreshOptions<T>): Promise<StoredOAuthRefreshResult<T>>;
 }

package/dist/types/auth/refresh.d.ts

@@ -3,7 +3,7 @@ import type { Provider } from "../types.js";
 import { type CredentialPool } from "./pool.js";
 import type { AccountPolicies } from "./policy.js";
 import { type AuthCredentialStore } from "./store.js";
-import { type AuthCredentialSnapshotEntry, type AuthStorageOptions, type OAuthCredential, type StoredOAuthRefreshOptions, type StoredOAuthRefreshResult } from "./types.js";
+import { type AuthCredentialSnapshotEntry, type AuthStorageOptions, type OAuthCredential, type OAuthRefreshByIdOptions, type OAuthRefreshReason, type StoredOAuthRefreshOptions, type StoredOAuthRefreshResult } from "./types.js";
 /**
  * Refresh OAuth access tokens this many ms before their stated expiry. The
  * skew exists so callers downstream of {@link OAuthRefresher} (stream providers,
@@ -48,12 +48,12 @@ export declare class OAuthRefresher {
      * continuing.
      */
     disableDefinitiveFailure(provider: string, credentialId: number | undefined, attemptedCredential: OAuthCredential, index: number, errorMsg: string): Promise<"disabled" | "peer-rotated" | "cas-lost">;
-    refresh(provider: Provider, credential: OAuthCredential, credentialId: number | undefined, signal?: AbortSignal): Promise<OAuthCredentials>;
+    refresh(provider: Provider, credential: OAuthCredential, credentialId: number | undefined, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<OAuthCredentials>;
     /**
      * Refresh the OAuth credential with the given id through a per-credential
      * single-flight. Concurrent callers for the same row await the same upstream
      * refresh attempt, which is required for providers that rotate refresh tokens
      * on every successful refresh.
      */
-    refreshById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    refreshById(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
 }

package/dist/types/auth/rotation.d.ts

@@ -5,7 +5,7 @@ import type { KeyOverrides } from "./cascade.js";
 import type { SessionAffinity } from "./affinity.js";
 import type { CredentialPool } from "./pool.js";
 import type { AuthCredentialStore } from "./store.js";
-import type { InvalidateCredentialMatchingOptions, LimitsApi, MarkUsageLimitOptions, RotateCredentialOptions, UsageLimitMarkResult } from "./types.js";
+import type { CredentialRotation, InvalidateCredentialMatchingOptions, LimitsApi, MarkUsageLimitOptions, RotateCredentialOptions, UsageLimitMarkResult } from "./types.js";
 import type { UsageService } from "./usage.js";
 /** Routing scope and strategy for one failed credential. */
 export type CredentialBlockRouting = {
@@ -60,7 +60,10 @@ export declare class RateLimits implements LimitsApi {
      *   reload when no broker hook is wired) and block it, then drop matching
      *   sticky state.
      *
-     * Returns whether another usable credential of the same type remains.
+     * For usage-limit and account-policy failures with no free sibling, sleeps
+     * until the earliest sibling unblocks when that is at most
+     * {@link SIBLING_UNBLOCK_WAIT_MAX_MS} away, then reports `afterSiblingWait`.
+     * Aborting `options.signal` during that wait rejects.
      */
-    rotate(provider: string, sessionId: string | undefined, options?: RotateCredentialOptions): Promise<boolean>;
+    rotate(provider: string, sessionId: string | undefined, options?: RotateCredentialOptions): Promise<CredentialRotation>;
 }

package/dist/types/auth/store.d.ts

@@ -1,7 +1,7 @@
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { Provider } from "../types.js";
 import type { ClientUsageIdentity, ClientUsageReport, ClientUsageSummary, ObservedUsageEntry, UsageHistoryEntry, UsageHistoryQuery, UsageReport } from "../usage.js";
-import type { AuthCredential, DisabledCredentialSummary, OAuthCredential, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
+import type { AuthCredential, DisabledCredentialSummary, OAuthCredential, OAuthRefreshReason, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
 /** Owner and timestamp that fence a durable credential refresh lease. */
 export interface CredentialRefreshLeaseFence {
     owner: string;
@@ -128,8 +128,10 @@ export interface CredentialUpstream {
      * `signal` propagates the agent's cancel (ESC, request abort, …) all the
      * way to the broker fetch so a hung connection can't strand the caller
      * for `timeoutMs * (maxRetries + 1)`.
+     * `reason` distinguishes provider-auth recovery from generic/MCP refreshes
+     * that must always mint a new access token.
      */
-    refreshOAuthCredential(provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    refreshOAuthCredential(provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<OAuthCredentials>;
     /**
      * Optional async pre-read hook invoked after AuthStorage selects a stored
      * credential but before it returns that credential for an outbound request.

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

@@ -272,6 +272,8 @@ export interface CredentialDisabledEvent {
     orgId?: string;
     orgName?: string;
 }
+/** Why a delegated OAuth refresh was requested. */
+export type OAuthRefreshReason = "auth-recovery";
 /** Configuration supplied when constructing credential storage. */
 export type AuthStorageOptions = {
     usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
@@ -301,11 +303,14 @@ export type AuthStorageOptions = {
      * per-provider local refresh function. Receives the credential id so the
      * implementation can address remote credentials.
      *
+     * `reason` is `"auth-recovery"` only for a provider-auth retry; generic and
+     * managed MCP force-refresh calls leave it unset.
+     *
      * Must return updated {@link OAuthCredentials} with at least `access` and
      * `expires`. `refresh` may be an opaque sentinel (e.g. `"__remote__"`) when
      * the actual refresh token never leaves the broker.
      */
-    refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal) => Promise<OAuthCredentials>;
+    refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason) => Promise<OAuthCredentials>;
     /**
      * Human-readable description of the credential store backing this
      * AuthStorage instance. Surfaced through {@link AuthStorage.keys.describe}
@@ -414,6 +419,8 @@ export type AuthApiKeyOptions = {
      * that a peer/broker rotated out from under us is replaced before retrying.
      */
     forceRefresh?: boolean;
+    /** Explicit provider-401 recovery; generic force refreshes leave this unset. */
+    refreshReason?: OAuthRefreshReason;
 };
 /**
  * Refreshed OAuth access plus identity metadata returned by
@@ -564,6 +571,10 @@ export interface ResetCreditRedeemOutcome {
 /** One stored account's live saved-reset status, from {@link AuthStorage.resets.list}. */
 export interface ResetCreditAccountStatus extends UsageResetCredits {
     provider: string;
+    /** Live quota evidence from this exact account's reset-discovery response. */
+    report?: UsageReport;
+    /** Provider-requested wait before retrying throttled reset discovery (not redemption). */
+    retryAfterMs?: number;
     credentialId: number;
     accountId?: string;
     email?: string;
@@ -627,6 +638,20 @@ export type RotateCredentialOptions = {
     credentialId?: number;
     signal?: AbortSignal;
 };
+/**
+ * Outcome of {@link LimitsApi.rotate}.
+ *
+ * `switched` is `true` when a usable same-type sibling credential is available,
+ * so the caller's next resolve hands it out. `afterSiblingWait` is `true` when
+ * no sibling was free at the failure but rotation slept out a sibling's short
+ * block (e.g. a Cloud Code Assist capacity 429 that resets in under a second);
+ * the freed credential may be one the caller already sent in this request, so
+ * attempted-bearer dedupe must let it through once.
+ */
+export interface CredentialRotation {
+    switched: boolean;
+    afterSiblingWait?: boolean;
+}
 /** Filter saved reset credits by provider and session. */
 export type ListResetCreditsOptions = {
     provider?: string;
@@ -858,6 +883,15 @@ export interface KeysApi {
         modelId?: string;
     }): ApiKeyResolver;
 }
+/** Controls whether a row-id refresh may reuse a token minted by this refresher. */
+export interface OAuthRefreshByIdOptions {
+    /**
+     * Return the stored credential when it still holds a fresh access token this
+     * refresher minted recently. Auth-recovery callers use this to avoid rotating
+     * refresh tokens repeatedly when a provider rejects every valid bearer.
+     */
+    reuseRecentMint?: boolean;
+}
 /** OAuth login, access, account identity, and refresh operations. */
 export interface OAuthApi {
     /**
@@ -932,9 +966,10 @@ export interface OAuthApi {
      * Refresh the OAuth credential with the given id through a per-credential
      * single-flight. Concurrent callers for the same row await the same upstream
      * refresh attempt, which is required for providers that rotate refresh tokens
-     * on every successful refresh.
+     * on every successful refresh. Mints unconditionally unless
+     * {@link OAuthRefreshByIdOptions.reuseRecentMint} is set.
      */
-    refresh(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
     /**
      * Refresh one stored OAuth credential under durable row ownership.
      */
@@ -1107,9 +1142,11 @@ export interface LimitsApi {
      *   reload when no broker hook is wired) and block it, then drop matching
      *   sticky state.
      *
-     * Returns whether another usable credential of the same type remains.
+     * For usage-limit and account-policy failures with no free sibling, waits
+     * (abortable via `options.signal`) when a sibling's block expires within a
+     * few seconds, then reports `afterSiblingWait`.
      */
-    rotate(provider: string, sessionId: string | undefined, options?: RotateCredentialOptions): Promise<boolean>;
+    rotate(provider: string, sessionId: string | undefined, options?: RotateCredentialOptions): Promise<CredentialRotation>;
     /** Invalidate a credential matching an API key after authentication failure. */
     invalidateMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
 }
@@ -1134,7 +1171,7 @@ export interface BlocksApi {
      */
     upsert(block: StoredCredentialBlock): void;
     /**
-     * Broker-server seam: clear all persisted blocks for one credential and notify snapshot waiters.
+     * Broker-server seam: clear one exact persisted block and notify snapshot waiters.
      */
     delete(credentialId: number, providerKey: string, blockScope: string): void;
     /** Delete all persisted blocks for a credential. */

package/dist/types/auth/usage-cache.d.ts

@@ -8,8 +8,8 @@ export declare const USAGE_HEADER_INGEST_INTERVAL_MS = 60000;
 /**
  * Per-credential cool-down after a usage fetch fails. While this window is
  * active we serve the last successful value to avoid dropping the credential
- * from the report; without a previous value we just return null and retry
- * on the next poll. Used by UsageService.
+ * from the report; without a previous value we return null until the
+ * cooldown expires. Report invalidation does not bypass this cooldown.
  */
 export declare const USAGE_FAILURE_BACKOFF_MS = 10000;
 /** Default usage fetch timeout; used by the AuthStorage facade. */
@@ -44,6 +44,16 @@ export declare class UsageCache {
     constructor(store: AuthCredentialStore, pool: CredentialPool, usageProviders: (provider: Provider) => UsageProvider | undefined);
     get epoch(): number;
     bumpEpoch(): void;
+    /** Identifies confirmed recoveries that supersede an in-flight failed probe. */
+    recoveryEpoch(provider: Provider): number;
+    /**
+     * Changes when a user refresh, confirmed reset, or usage-implementation swap
+     * makes an in-flight probe too old to answer. Block marks do not change it:
+     * they stop a racing report from being cached, never trigger a re-probe.
+     */
+    refreshEpoch(provider: Provider): number;
+    /** Failure cooldowns survive report invalidation and process restarts. */
+    failureKey(reportKey: string): string;
     get<T>(key: string): UsageCacheEntry<T> | undefined;
     getStale<T>(key: string): UsageCacheEntry<T> | undefined;
     set<T>(key: string, entry: UsageCacheEntry<T>): void;
@@ -56,8 +66,17 @@ export declare class UsageCache {
     /**
      * Force the next usage fetch for `provider` to bypass the 5-min cache, so
      * `/usage` reflects a freshly-redeemed reset instead of stale numbers.
+     * `resetSpentCredentialId` also forgets that credential's cached saved-reset
+     * block, so a failed follow-up reset probe cannot carry the pre-spend
+     * inventory forward.
      */
-    invalidate(provider: string, baseUrl?: string): void;
+    invalidate(provider: string, baseUrl?: string, options?: {
+        resetSpentCredentialId?: number;
+    }): void;
+    /** A confirmed reset permits one fresh probe even during a pre-reset failure cooldown. */
+    invalidateAfterReset(provider: Provider, baseUrl?: string, options?: {
+        resetSpentCredentialId?: number;
+    }): void;
     /**
      * Expire cached reports for a provider after its runtime usage implementation changes.
      * This keeps a newly installed extension provider from serving a built-in snapshot.

package/dist/types/auth/usage.d.ts

@@ -29,6 +29,10 @@ export interface UsageServiceDeps {
     requestTimeoutMs: number;
     logger: UsageLogger;
 }
+type UsageReportsOptions = {
+    baseUrlResolver?: (provider: Provider) => string | undefined;
+    signal?: AbortSignal;
+};
 /** Usage reports: per-credential cached fetches, aggregate reports, header ingestion, history. */
 export declare class UsageService implements UsageApi {
     #private;
@@ -95,15 +99,12 @@ export declare class UsageService implements UsageApi {
      */
     reportingModelIds(provider: Provider, modelIds: readonly string[], reports: readonly UsageReport[]): string[];
     /** Fetch all providers’ current usage reports, sharing concurrent polls. */
-    reports(options?: {
-        baseUrlResolver?: (provider: Provider) => string | undefined;
-        /** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
-        signal?: AbortSignal;
-    }): Promise<UsageReport[] | null>;
+    reports(options?: UsageReportsOptions): Promise<UsageReport[] | null>;
     /**
      * Discard cached usage reports before a user-requested refresh. The next
-     * read probes upstream serially per provider; a failure reports no fresh
-     * usage instead of replaying an invalidated last-good snapshot.
+     * read probes upstream serially per provider unless a failure cooldown is
+     * active. Failed probes never replay an invalidated last-good snapshot.
      */
     invalidate(provider?: string, signal?: AbortSignal): Promise<void>;
 }
+export {};

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

@@ -5,8 +5,8 @@
  * `omp auth-broker status` (liveness checks). All endpoints except
  * `/v1/healthz` require a bearer token.
  */
-import type { AuthCredential, DisabledCredentialSummary } from "../auth-storage.js";
-import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
+import type { AuthCredential, DisabledCredentialSummary, OAuthRefreshReason } from "../auth-storage.js";
+import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockDeleteRequest, CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
 export interface AuthBrokerClientOptions {
     /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
     url: string;
@@ -86,7 +86,7 @@ export declare class AuthBrokerClient {
         sinceMs?: number;
     }, signal?: AbortSignal): Promise<ClientUsageSummaryResponse>;
     notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse>;
-    refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
+    refreshCredential(id: number, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
     /**
      * Disabled-credential tombstones (identity + cause, no token material).
@@ -96,5 +96,6 @@ export declare class AuthBrokerClient {
     listDisabledCredentials(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]>;
     uploadCredential(provider: string, credential: AuthCredential, signal?: AbortSignal): Promise<CredentialUploadResponse>;
     upsertCredentialBlock(id: number, block: CredentialBlockRequest, signal?: AbortSignal): Promise<CredentialBlockResponse>;
+    deleteCredentialBlock(id: number, block: CredentialBlockDeleteRequest, signal?: AbortSignal): Promise<CredentialBlocksDeleteResponse>;
     deleteCredentialBlocks(id: number, signal?: AbortSignal): Promise<CredentialBlocksDeleteResponse>;
 }

package/dist/types/auth-broker/remote-store.d.ts

@@ -1,5 +1,5 @@
 import type { AuthCredentialStore } from "../auth/store.js";
-import { type AuthCredential, type DisabledCredentialSummary, type OAuthCredential, type StoredAuthCredential, type StoredCredentialBlock } from "../auth/types.js";
+import { type AuthCredential, type DisabledCredentialSummary, type OAuthCredential, type OAuthRefreshReason, type StoredAuthCredential, type StoredCredentialBlock } from "../auth/types.js";
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { Provider } from "../types.js";
 import type { ClientUsageIdentity, ObservedUsageEntry, UsageReport } from "../usage.js";
@@ -76,7 +76,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[];
     upsertCredentialBlock(block: StoredCredentialBlock): void;
-    deleteCredentialBlock(_credentialId: number, _providerKey: string, _blockScope: string): void;
+    deleteCredentialBlock(credentialId: number, providerKey: string, blockScope: string): void;
     deleteCredentialBlocks(credentialId: number): void;
     cleanExpiredCredentialBlocks(nowMs: number): void;
     /**
@@ -128,12 +128,11 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * the broker-redacted credential with {@link REMOTE_REFRESH_SENTINEL} in
      * the `refresh` slot.
      */
-    refreshOAuthCredential(_provider: Provider, credentialId: number, _credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    refreshOAuthCredential(_provider: Provider, credentialId: number, _credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<OAuthCredentials>;
     /**
      * Store-level hook consumed by `AuthStorage.usage.reports()` — proxies
-     * to the broker's `/v1/usage` endpoint. The broker's egress IP isn't
-     * rate-limited by Anthropic's per-IP `/usage` cap the way a heavy
-     * residential laptop is, so all credentials surface every cycle.
+     * to the broker's `/v1/usage` endpoint. Shared per-credential caches and
+     * cooldowns keep separate clients from multiplying provider probes.
      */
     fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
     /**
@@ -142,8 +141,8 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * same response (coalesced + cached), then overlays any client-observed
      * header hints for the matching credential.
      *
-     * The broker already aggregates with its own 30s TTL on the server side; our
-     * 15s client TTL is below that so we usually re-use the broker's cache too.
+     * The broker caches each credential independently; the short client TTL
+     * also folds sequential consumers into one broker round-trip.
      */
     getUsageReport(provider: Provider, credential: OAuthCredential, signal?: AbortSignal): Promise<UsageReport | null>;
     ingestUsageReport(provider: Provider, credential: OAuthCredential, report: UsageReport): boolean;

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

@@ -73,11 +73,13 @@ export interface DisabledCredentialsResponse {
 }
 /** POST /v1/credential/:id/block request body. */
 export type CredentialBlockRequest = CredentialBlockSnapshot;
+/** DELETE /v1/credential/:id/block request body; empty scope targets only the global row. */
+export type CredentialBlockDeleteRequest = Pick<CredentialBlockSnapshot, "providerKey" | "blockScope">;
 /** POST /v1/credential/:id/block response body. */
 export interface CredentialBlockResponse {
     ok: boolean;
 }
-/** DELETE /v1/credential/:id/blocks response body. */
+/** DELETE /v1/credential/:id/block or /blocks response body. */
 export interface CredentialBlocksDeleteResponse {
     ok: boolean;
 }

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -14,7 +14,7 @@
  */
 import { type FluentType } from "@oh-my-pi/omptype";
 import { type ApiKeyCredential, type AuthCredential, type AuthCredentialSnapshotEntry, type DisabledCredentialSummary, type OAuthCredential, type RemoteOAuthCredential, type SnapshotCredential } from "../auth-storage.js";
-import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockRequest, CredentialBlockResponse, CredentialBlockSnapshot, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadRequest, CredentialUploadResponse, DisabledCredentialsResponse, HealthzResponse, RefresherSchedule, SnapshotEntry, SnapshotResponse, SnapshotStreamEntryEvent, SnapshotStreamEvent, SnapshotStreamRemovedEvent, SnapshotStreamSnapshotEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
+import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockDeleteRequest, CredentialBlockRequest, CredentialBlockResponse, CredentialBlockSnapshot, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadRequest, CredentialUploadResponse, DisabledCredentialsResponse, HealthzResponse, RefresherSchedule, SnapshotEntry, SnapshotResponse, SnapshotStreamEntryEvent, SnapshotStreamEvent, SnapshotStreamRemovedEvent, SnapshotStreamSnapshotEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
 /** Real OAuth credential (broker-side) — refresh token is the actual upstream value. */
 export declare const oauthCredentialSchema: FluentType<OAuthCredential>;
 /** OAuth credential as it appears in broker snapshots — refresh replaced with sentinel. */
@@ -62,6 +62,7 @@ export declare const disabledCredentialSummarySchema: FluentType<DisabledCredent
 /** Broker `GET /v1/credentials/disabled` response. */
 export declare const disabledCredentialsResponseSchema: FluentType<DisabledCredentialsResponse>;
 export declare const credentialBlockRequestSchema: FluentType<CredentialBlockRequest>;
+export declare const credentialBlockDeleteRequestSchema: FluentType<CredentialBlockDeleteRequest>;
 export declare const credentialBlockResponseSchema: FluentType<CredentialBlockResponse>;
 export declare const credentialBlocksDeleteResponseSchema: FluentType<CredentialBlocksDeleteResponse>;
 export declare const usageStaleResponseSchema: FluentType<UsageStaleResponse>;