@oh-my-pi/pi-ai 18.8.4 → 18.8.6

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [18.8.6] - 2026-10-08
+
+### Fixed
+
+- Fixed Google Gemini and Cloud Code Assist (Antigravity) requests failing when tool schemas contain unsupported JSON Schema keywords or fields that allow multiple types.
+- Fixed auth broker account selection and usage-limit enforcement to consistently use the selected account’s quota when multiple accounts are present.
+- Fixed Anthropic-family model streaming so encoded marker tokens are decoded correctly in text, tool-call updates, partial messages, and completed tool calls.
+
+## [18.8.5] - 2026-10-08
+
+### Added
+
+- `oauth.refresh(id, signal, { reason: "auth-recovery" })` forwards provider-401 recovery intent to a delegated (auth broker) refresh, and `AuthStorageOptions.refreshOAuthCredentialMints` marks a `refreshOAuthCredential` hook that exchanges tokens itself so its tokens are reused for auth recovery ([#14752](https://github.com/can1357/oh-my-pi/pull/14752) by [@will-bogusz](https://github.com/will-bogusz))
+- `SessionsApi.inherit` accepts an optional filter, called with each provider and whether the source's affinity is an explicit user pin, to copy only the affinities it accepts ([#14749](https://github.com/can1357/oh-my-pi/pull/14749) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Changed
+
+- `AuthApiKeyOptions.accountIds` also matches the login email, or else the project id, of credentials that carry no account id (see `oauthAccountKey`), so Antigravity requests prefer accounts that serve the requested model ([#14924](https://github.com/can1357/oh-my-pi/issues/14924)).
+
+### Fixed
+
+- Fixed accounts sitting exactly at their `reservePct` (e.g. 70% used with a 30% reserve) still being picked and reported healthy instead of being held in reserve ([#14765](https://github.com/can1357/oh-my-pi/pull/14765) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed `oauth.accessById` with `forceRefresh` returning the stored token unchanged while it was still valid; it now re-mints that one account (through the auth broker when configured) and returns that account's token even if another row is removed meanwhile ([#14752](https://github.com/can1357/oh-my-pi/pull/14752) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed `omp -p` and other short-lived auth-broker clients missing from `omp usage clients`: usage still waiting for the 10-second report batch is now sent to the broker before the process exits ([#14899](https://github.com/can1357/oh-my-pi/pull/14899) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed Cursor web fetches that were cut off by a dropped connection disappearing from resumed and rebuilt sessions; they now show as interrupted ([#14819](https://github.com/can1357/oh-my-pi/pull/14819) by [@jchanghong023](https://github.com/jchanghong023))
+- Anthropic hosted web search can honor custom providers' OAuth-style request shaping and configured headers consistently with conversations ([#14919](https://github.com/can1357/oh-my-pi/pull/14919) by [@farnoy](https://github.com/farnoy))
+
 ## [18.8.4] - 2026-10-08
 
 ### Breaking Changes
@@ -2314,19 +2341,4 @@
 - Fixed OpenAI-compatible Ollama completions that return empty `finish_reason:length` after filling `num_ctx` so they surface an actionable context-window error instead of an empty length stop. ([#2774](https://github.com/can1357/oh-my-pi/issues/2774))
 - Fixed Codex browser login issuing credentials for the `opencode` OAuth originator while OMP requests identify as `pi`, which could make the first authenticated Codex request return 401 ([#2696](https://github.com/can1357/oh-my-pi/issues/2696)).
 
-## [16.0.1] - 2026-06-15
-
-### Added
-
-- Added Umans AI Coding Plan API-key login support and `UMANS_AI_CODING_PLAN_API_KEY` environment fallback ([#2636](https://github.com/can1357/oh-my-pi/pull/2636) by [@oldschoola](https://github.com/oldschoola)).
-
-### Fixed
-
-- Fixed OpenAI Responses, Azure OpenAI Responses, and Codex Responses providers ignoring async `onPayload` replacement bodies. Provider payload hooks can now transform the actual request body sent upstream, matching the Anthropic/Gemini replacement contract.
-- Fixed OpenAI-compatible chat-completions streams that send object-shaped tool arguments in fragments by deep-merging nested objects and task arrays instead of replacing earlier chunks. ([#2617](https://github.com/can1357/oh-my-pi/issues/2617))
-- Fixed OpenAI Responses strict-mode tool schema normalization for nullable enum MCP parameters so enum constraints are distributed to matching `anyOf` branches instead of being copied onto the `null` branch. ([#1835](https://github.com/can1357/oh-my-pi/issues/1835))
-- Fixed Cursor provider formatting tool errors with the same `[Tool Result]` prefix as successful results, causing Composer models to misinterpret error messages (e.g. "Pattern must not be empty") as directives over long conversations. Errors now use a `[Tool Error]` prefix so the model can distinguish failures from successes in the prompt history. ([#1853](https://github.com/can1357/oh-my-pi/pull/1853))
-- Fixed `validateToolArguments` silently accepting JSON-encoded array strings (e.g. `'["a","b"]'`) against `union(string, array<string>)` schemas — providers that double-serialize tool-call arguments (Z.AI / GLM) caused tools like `search` to receive the literal `["a","b"]` as a single path, producing zero matches (single element) or glob parse errors (multi-element). A new pre-validation pass parses JSON-array-shaped strings when the schema explicitly accepts both shapes. ([#1788](https://github.com/can1357/oh-my-pi/issues/1788))
-- Fixed Anthropic thinking summaries that arrive wrapped in literal `<thinking>` tags so advisor/raw transcript dumps do not render nested thinking tags ([#2695](https://github.com/can1357/oh-my-pi/issues/2695)).
-
-Older entries are archived in [packages/ai/CHANGELOG.md@d22e34333695](https://github.com/can1357/oh-my-pi/blob/d22e34333695d3dd9de7741ff45903681dba4606/packages/ai/CHANGELOG.md).
+Older entries are archived in [packages/ai/CHANGELOG.md@0dd6aff5f282](https://github.com/can1357/oh-my-pi/blob/0dd6aff5f2821aec1e5b54c6a458e323667a949b/packages/ai/CHANGELOG.md).

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

@@ -79,14 +79,15 @@ export declare class SessionAffinity implements SessionsApi {
         restoredAtMs?: number;
     }): boolean;
     /**
-     * Copy every stored credential affinity from one live session to another.
+     * Copy stored credential affinities 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.
+     * source session. `include` limits the copy to the providers it accepts,
+     * given whether the source's affinity is an explicit user pin.
      */
-    inherit(sourceSessionId: string, targetSessionId: string): number;
+    inherit(sourceSessionId: string, targetSessionId: string, include?: (provider: string, explicit: boolean) => boolean): number;
     /**
      * Release a session's sticky credential so its next `KeyCascade.get` call
      * re-runs native pool ranking. This never blocks or penalizes the released

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

@@ -67,9 +67,10 @@ export declare class OAuthAccounts implements OAuthApi {
      * Resolve one stored OAuth credential by its durable storage row id.
      *
      * Unlike the normal session resolver, this method never ranks, rotates, or
-     * falls back to sibling credentials. A forced refresh re-mints only the
-     * requested row, preserving exact-account affinity for operations whose
-     * provenance and policy boundary are tied to one workspace.
+     * falls back to sibling credentials. A generic forced refresh re-mints only the
+     * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+     * still-usable recent mint of that row. Either way exact-account affinity holds
+     * for operations whose provenance and policy boundary are tied to one workspace.
      *
      * Returns `undefined` when the row does not exist for `provider` or an
      * explicit runtime/config API-key override suppresses OAuth.

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

@@ -32,6 +32,7 @@ export interface OAuthRefresherDeps {
     pool: CredentialPool;
     policies: AccountPolicies;
     override?: AuthStorageOptions["refreshOAuthCredential"];
+    overrideMints?: AuthStorageOptions["refreshOAuthCredentialMints"];
 }
 /** Single-flighted, lease-guarded OAuth refresh with compare-and-set persistence. */
 export declare class OAuthRefresher {

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

@@ -8,7 +8,7 @@ import { type CredentialPool } from "./pool.js";
 import { type ApiKeySelection, type OAuthSelection } from "./rank.js";
 import { type OAuthRefresher } from "./refresh.js";
 import type { AuthCredentialStore } from "./store.js";
-import type { ApiKeyCredential, AuthApiKeyOptions, AuthCredential, OAuthCredential } from "./types.js";
+import { type ApiKeyCredential, type AuthApiKeyOptions, type AuthCredential, type OAuthCredential } from "./types.js";
 import type { UsageService } from "./usage.js";
 /** Temporary block after a transient OAuth refresh failure. */
 export declare const OAUTH_REFRESH_FAILURE_BACKOFF_MS: number;

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

@@ -316,6 +316,12 @@ export type AuthStorageOptions = {
      * the actual refresh token never leaves the broker.
      */
     refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason) => Promise<OAuthCredentials>;
+    /**
+     * Set when {@link refreshOAuthCredential} exchanges the refresh token with the
+     * provider itself instead of delegating (e.g. to a broker), so its tokens count
+     * as this process's mints for auth-recovery reuse.
+     */
+    refreshOAuthCredentialMints?: boolean;
     /**
      * Human-readable description of the credential store backing this
      * AuthStorage instance. Surfaced through {@link AuthStorage.keys.describe}
@@ -409,7 +415,7 @@ export interface ModelUsageHealthOptions {
 export type AuthApiKeyOptions = {
     baseUrl?: string;
     modelId?: string;
-    /** Provider account ids known to serve `modelId` from multi-account discovery; OAuth selection prefers them and tries other accounts only as a last resort. */
+    /** {@link oauthAccountKey}s of accounts known to serve `modelId` from multi-account discovery; OAuth selection prefers them and tries other accounts only as a last resort. */
     accountIds?: readonly string[];
     /**
      * Caller's cancel signal. Threaded into any broker-bound OAuth refresh so
@@ -429,6 +435,19 @@ export type AuthApiKeyOptions = {
     /** When false, select as `sessionId` would without recording the choice as that session's sticky credential. */
     recordAffinity?: boolean;
 };
+/**
+ * Identity that multi-account discovery records in `Model.accountAccess` and
+ * that {@link AuthApiKeyOptions.accountIds} selection matches: the provider
+ * account id (Codex `chatgpt_account_id`), else the login email for providers
+ * whose credentials carry no account id (Antigravity), else the project id for
+ * a login whose email lookup failed. Same precedence as the credential store's
+ * identity key.
+ */
+export declare function oauthAccountKey(identity: {
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+}): string | undefined;
 /** Non-secret identity bound to the OAuth credential selected for one request attempt. */
 export interface OAuthRequestIdentity {
     orgId?: string;
@@ -917,7 +936,7 @@ export interface KeysApi {
         modelId?: string;
     }): ApiKeyResolver;
 }
-/** Controls whether a row-id refresh may reuse a token minted by this refresher. */
+/** Controls whether a row-id refresh may reuse a recently minted token. */
 export interface OAuthRefreshByIdOptions {
     /**
      * Return the stored credential when it still holds a fresh access token this
@@ -925,6 +944,12 @@ export interface OAuthRefreshByIdOptions {
      * refresh tokens repeatedly when a provider rejects every valid bearer.
      */
     reuseRecentMint?: boolean;
+    /**
+     * Provider-401 recovery intent. Forwarded to a delegated refresh (an auth
+     * broker), which may then return a token it minted in the last five minutes.
+     * Local reuse still requires {@link reuseRecentMint}.
+     */
+    reason?: OAuthRefreshReason;
 }
 /** OAuth login, access, account identity, and refresh operations. */
 export interface OAuthApi {
@@ -966,9 +991,10 @@ export interface OAuthApi {
      * Resolve one stored OAuth credential by its durable storage row id.
      *
      * Unlike the normal session resolver, this method never ranks, rotates, or
-     * falls back to sibling credentials. A forced refresh re-mints only the
-     * requested row, preserving exact-account affinity for operations whose
-     * provenance and policy boundary are tied to one workspace.
+     * falls back to sibling credentials. A generic forced refresh re-mints only the
+     * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+     * still-usable recent mint of that row. Either way exact-account affinity holds
+     * for operations whose provenance and policy boundary are tied to one workspace.
      *
      * Returns `undefined` when the row does not exist for `provider` or an
      * explicit runtime/config API-key override suppresses OAuth.
@@ -1002,8 +1028,9 @@ 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. Mints unconditionally unless
-     * {@link OAuthRefreshByIdOptions.reuseRecentMint} is set.
+     * on every successful refresh. Mints unless {@link OAuthRefreshByIdOptions.reuseRecentMint}
+     * finds a recent local mint, or a delegated refresh given
+     * {@link OAuthRefreshByIdOptions.reason} `"auth-recovery"` returns its recent mint.
      */
     refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
     /**
@@ -1035,14 +1062,15 @@ export interface SessionsApi {
         restoredAtMs?: number;
     }): boolean;
     /**
-     * Copy every stored credential affinity from one live session to another.
+     * Copy stored credential affinities 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.
+     * source session. `include` limits the copy to the providers it accepts,
+     * given whether the source's affinity is an explicit user pin.
      */
-    inherit(sourceSessionId: string, targetSessionId: string): number;
+    inherit(sourceSessionId: string, targetSessionId: string, include?: (provider: string, explicit: boolean) => boolean): number;
     /**
      * Restrict one session's credentials for `provider` to the OAuth accounts
      * whose identity key (`email:<address>|org:<id>` for org-scoped providers;

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

@@ -149,9 +149,10 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     ingestUsageReport(provider: Provider, credential: OAuthCredential, report: UsageReport): boolean;
     /**
      * Fold locally observed request usage into the pending report and schedule
-     * a flush. One `POST /v1/usage/observed` at most per flush interval; on
-     * failure the batch is retained and retried with the next flush. A 404
-     * (pre-endpoint broker) disables reporting for the life of this store.
+     * a flush. One `POST /v1/usage/observed` at most per flush interval, plus a
+     * final one when the process exits; on failure the batch is retained and
+     * retried with the next flush. A 404 (pre-endpoint broker) disables
+     * reporting for the life of this store.
      *
      * `client` overrides the reporting identity — the auth-gateway attributes
      * each request to the originating install/app instead of the gateway host.

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

@@ -169,6 +169,12 @@ export type AnthropicClientOptionsResult = {
  * omitted there.
  */
 export declare function resolveAnthropicCustomHeadersForBaseUrl(baseUrl: string | undefined): Record<string, string> | undefined;
+/**
+ * Merge headers case-insensitively; later sources win and preserve their key casing.
+ * Undefined sources are ignored. Differently cased duplicates are removed so the
+ * Headers constructor cannot join competing values comma-separated on the wire.
+ */
+export declare function mergeHeaders(...headerSources: (Record<string, string> | undefined)[]): Record<string, string>;
 export type AnthropicUsageLike = {
     cache_creation?: {
         ephemeral_5m_input_tokens?: number | null;

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

@@ -169,13 +169,13 @@ export declare function emptyGrepPatternRejection(pattern: string | undefined, g
  * so reparsing unconditionally would erase the arguments of every such block
  * caught open by a truncated stream.
  *
- * Server-owned blocks are also paired here. `connect-scm` and `todo` are
- * stamped {@link kCursorExecResolved} the moment they open, so `agent-loop.ts`
- * synthesizes no placeholder for them and only their `toolCallCompleted` frame
- * pairs a result. A transport that closes before that frame would leave the
- * call unpaired, and `buildSessionContext` strips a dangling call from every
- * rebuilt transcript — the interaction disappears. An interrupted result is
- * emitted instead.
+ * Server-owned blocks are also paired here. `connect-scm`, `todo` and
+ * `web-fetch` are stamped {@link kCursorExecResolved} the moment they open,
+ * so `agent-loop.ts` synthesizes no placeholder for them and only their
+ * `toolCallCompleted` frame pairs a result. A transport that closes before
+ * that frame would leave the call unpaired, and `buildSessionContext` strips
+ * a dangling call from every rebuilt transcript — the interaction disappears.
+ * An interrupted result is emitted instead.
  *
  * MCP blocks are excluded even when resolved: the exec dispatch that marked
  * them owns their result, and `drainInFlightDispatches` awaits it before this

package/dist/types/usage.d.ts

@@ -142,6 +142,8 @@ export interface UsageReport {
  * explicit fraction > used/limit > percent-unit used > inverted remaining.
  */
 export declare function resolveUsedFraction(limit: UsageLimit): number | undefined;
+/** Whether remaining quota is at or below the reserve (both 0..1 fractions). */
+export declare function isWithinUsageReserve(remainingFraction: number, reserveFraction: number): boolean;
 /**
  * One recorded usage-limit snapshot: a single limit window of one account at
  * a point in time. The usage cache itself is latest-snapshot-only; history

package/dist/types/utils/anthropic-auth.d.ts

@@ -9,6 +9,11 @@ export declare function resolveAnthropicBaseUrlFromEnv(): string | undefined;
  * Checks if a token is an OAuth token by looking for sk-ant-oat prefix.
  */
 export declare function isOAuthToken(apiKey: string): boolean;
+/** Optional request-shaping overrides for an already-resolved Anthropic credential. */
+export interface AnthropicAuthOptions {
+    /** Override token detection; false explicitly disables OAuth-style request shaping. */
+    isOAuth?: boolean;
+}
 /**
  * Build an {@link AnthropicAuthConfig} from an already-resolved API key.
  *
@@ -17,18 +22,27 @@ export declare function isOAuthToken(apiKey: string): boolean;
  * env-derived base; pass `undefined` to fall back to FOUNDRY/ANTHROPIC env
  * resolution and finally `DEFAULT_BASE_URL`.
  *
- * `isOAuth` is derived from the token prefix so the helper stays pure: callers
- * never have to thread the OAuth flag through their own resolution logic.
+ * `options.isOAuth` defaults to token detection. Pass the selected model's
+ * `isOAuth` to match the streaming path, which lets the model override the
+ * prefix (custom `anthropic-messages` providers default to OAuth shaping).
  */
-export declare function buildAnthropicAuthConfig(apiKey: string, baseUrl?: string): AnthropicAuthConfig;
+export declare function buildAnthropicAuthConfig(apiKey: string, baseUrl?: string, options?: AnthropicAuthOptions): AnthropicAuthConfig;
+/** Configured headers and fingerprint override policy for Anthropic hosted web search. */
+export interface AnthropicSearchHeaderOptions {
+    /** The selected model's configured headers (`ModelRegistry.resolveModelHeaders`). */
+    modelHeaders?: Record<string, string>;
+    /** The selected model's `compat.allowAnthropicHeaderOverrides`. */
+    allowAnthropicHeaderOverrides?: boolean;
+}
 /**
  * Builds HTTP headers for Anthropic API requests (search variant).
  *
- * Forwards `ANTHROPIC_CUSTOM_HEADERS` when the resolver deems them applicable
- * (Foundry mode, or a non-Anthropic base URL — typically an enterprise
- * gateway), matching the streaming path so web search behaves identically.
+ * Model headers and `ANTHROPIC_CUSTOM_HEADERS` (when the resolver deems them
+ * applicable: Foundry mode, or a non-Anthropic base URL such as an enterprise
+ * gateway) go through the same case-insensitive merge and enforced-header
+ * filtering as the streaming path, so web search behaves identically.
  */
-export declare function buildAnthropicSearchHeaders(auth: AnthropicAuthConfig): Record<string, string>;
+export declare function buildAnthropicSearchHeaders(auth: AnthropicAuthConfig, options?: AnthropicSearchHeaderOptions): Record<string, string>;
 /**
  * Builds the full API URL for Anthropic messages endpoint.
  */

package/dist/types/utils/glyph-codec.d.ts

@@ -4,7 +4,7 @@ import { AssistantMessageEventStream } from "./event-stream.js";
 export interface GlyphCodec {
     /** Context with model-bound glyphs encoded and one conditional convention notice. */
     context: Context;
-    /** Decodes glyph tokens in the stream's terminal assistant message. */
+    /** Decodes glyph tokens live: text and tool-call deltas, partial snapshots, completed tool calls, and the terminal message. */
     wrap(inner: AssistantMessageEventStream): AssistantMessageEventStream;
     /** Decodes Cursor Pi calls and encodes their provider-bound results. */
     wrapCursorExecHandlers(handlers: CursorExecHandlers): CursorExecHandlers;

package/dist/types/utils/schema/normalize.d.ts

@@ -10,7 +10,11 @@ export interface NormalizeSchemaOptions {
     unsupportedFields: (key: string) => boolean;
     normalizeFieldNames: boolean;
     collapseNullFields: boolean;
-    normalizeTypeArrayToNullable: boolean;
+    /**
+     * Target takes a scalar `type` only: `["T", "null"]` becomes `T` (+ `nullable`)
+     * and a multi-type array becomes one `anyOf` branch per type.
+     */
+    scalarizeTypeArrays: boolean;
     stripNullableKeyword: boolean;
     autoPropertyOrdering: boolean;
     ensureObjectProperties: boolean;
@@ -66,8 +70,9 @@ export declare function normalizeSchemaForMCP(value: unknown): unknown;
  *    rejected; collapse to `enum` with an inferred scalar `type`.
  *  - `oneOf` is not an MFJS combinator (only `anyOf` is); residual `oneOf` is
  *    folded into `anyOf`.
- *  - `type` must be a scalar string; `type: [...]` arrays are reduced to a
- *    single scalar (the `null` branch is dropped — `nullable` is unsupported).
+ *  - `type` must be a scalar string; `["T", "null"]` reduces to `T` (the
+ *    `null` member is dropped — `nullable` is unsupported) and a multi-type
+ *    array becomes one typed `anyOf` branch per type.
  *  - Enum-bearing nodes get an inferred `type` (the idiomatic MFJS form; a bare
  *    `enum` is valid too) so `anyOf` branches always carry a `type`.
  *  - Validation/decorative keywords (`minItems`, `maxItems`, `maxLength`,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.8.4",
+	"version": "18.8.6",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.8.4",
-		"@oh-my-pi/pi-catalog": "18.8.4",
-		"@oh-my-pi/pi-natives": "18.8.4",
-		"@oh-my-pi/pi-utils": "18.8.4",
-		"@oh-my-pi/pi-wire": "18.8.4"
+		"@oh-my-pi/omptype": "18.8.6",
+		"@oh-my-pi/pi-catalog": "18.8.6",
+		"@oh-my-pi/pi-natives": "18.8.6",
+		"@oh-my-pi/pi-utils": "18.8.6",
+		"@oh-my-pi/pi-wire": "18.8.6"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth/affinity.ts

@@ -360,19 +360,25 @@ export class SessionAffinity implements SessionsApi {
 	}
 
 	/**
-	 * Copy every stored credential affinity from one live session to another.
+	 * Copy stored credential affinities 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.
+	 * source session. `include` limits the copy to the providers it accepts,
+	 * given whether the source's affinity is an explicit user pin.
 	 */
-	inherit(sourceSessionId: string, targetSessionId: string): number {
+	inherit(
+		sourceSessionId: string,
+		targetSessionId: string,
+		include?: (provider: string, explicit: boolean) => boolean,
+	): number {
 		if (!sourceSessionId || !targetSessionId || sourceSessionId === targetSessionId) return 0;
 		let inherited = 0;
 		for (const provider of this.#pool.providers()) {
 			const credential = this.get(provider, sourceSessionId);
 			if (!credential || !this.#permits(provider, targetSessionId, credential.index)) continue;
+			if (include && !include(provider, credential.explicit === true)) continue;
 			this.record(
 				provider,
 				targetSessionId,

package/src/auth/health.ts

@@ -1,5 +1,5 @@
 import type { Provider } from "../types";
-import { resolveUsedFraction } from "../usage";
+import { isWithinUsageReserve, resolveUsedFraction } from "../usage";
 import type {
 	CredentialRankingContext,
 	UsageCredential,
@@ -224,7 +224,7 @@ export class CredentialHealth implements HealthApi {
 				return {
 					credentialId: entry.id,
 					credentialType,
-					state: remainingFraction <= resolveReserveFraction(entry) ? "reserve" : "healthy",
+					state: isWithinUsageReserve(remainingFraction, resolveReserveFraction(entry)) ? "reserve" : "healthy",
 					remainingFraction,
 				};
 			}),

package/src/auth/oauth.ts

@@ -179,9 +179,20 @@ export class OAuthAccounts implements OAuthApi {
 		options: AuthApiKeyOptions | undefined,
 	): Promise<OAuthAccessResolution> {
 		try {
+			// tryOAuth refreshes only expired tokens; it resyncs this row from the store after a forced re-mint.
+			let index = selection.index;
+			if (options?.forceRefresh) {
+				await this.refresh(selection.credentialId, options.signal, {
+					reuseRecentMint: options.refreshReason === "auth-recovery",
+					reason: options.refreshReason,
+				});
+				// The refresh re-lists rows, so a concurrently removed row can shift this one's position.
+				index = this.#deps.pool.entries(provider).findIndex(entry => entry.id === selection.credentialId);
+				if (index === -1) throw new Error(`OAuth credential ${selection.credentialId} was removed during refresh`);
+			}
 			const resolved = await this.#deps.selector.tryOAuth(
 				provider,
-				{ credential: selection.credential, index: selection.index },
+				{ credential: selection.credential, index },
 				providerKey,
 				undefined,
 				options,
@@ -289,9 +300,10 @@ export class OAuthAccounts implements OAuthApi {
 	 * Resolve one stored OAuth credential by its durable storage row id.
 	 *
 	 * Unlike the normal session resolver, this method never ranks, rotates, or
-	 * falls back to sibling credentials. A forced refresh re-mints only the
-	 * requested row, preserving exact-account affinity for operations whose
-	 * provenance and policy boundary are tied to one workspace.
+	 * falls back to sibling credentials. A generic forced refresh re-mints only the
+	 * requested row; with `refreshReason: "auth-recovery"` it may instead reuse a
+	 * still-usable recent mint of that row. Either way exact-account affinity holds
+	 * for operations whose provenance and policy boundary are tied to one workspace.
 	 *
 	 * Returns `undefined` when the row does not exist for `provider` or an
 	 * explicit runtime/config API-key override suppresses OAuth.

package/src/auth/refresh.ts

@@ -93,6 +93,7 @@ export interface OAuthRefresherDeps {
 	pool: CredentialPool;
 	policies: AccountPolicies;
 	override?: AuthStorageOptions["refreshOAuthCredential"];
+	overrideMints?: AuthStorageOptions["refreshOAuthCredentialMints"];
 }
 
 /** Single-flighted, lease-guarded OAuth refresh with compare-and-set persistence. */
@@ -139,6 +140,13 @@ export class OAuthRefresher {
 		this.#recentMints.set(id, { provider, access: credential.access, at: now });
 	}
 
+	/** Whether refreshes run the provider token exchange in this process rather than delegating it. */
+	#mintsLocally(): boolean {
+		return this.#deps.override
+			? this.#deps.overrideMints === true
+			: this.#deps.store.refreshOAuthCredential === undefined;
+	}
+
 	/**
 	 * Refresh one stored OAuth credential under durable row ownership.
 	 */
@@ -345,7 +353,7 @@ export class OAuthRefresher {
 			} else {
 				this.#deps.store.updateAuthCredential(row.id, merged);
 			}
-			if (this.#deps.override === undefined && this.#deps.store.refreshOAuthCredential === undefined) {
+			if (this.#mintsLocally()) {
 				this.#rememberMint(provider, row.id, merged);
 			}
 			this.#deps.pool.replace(
@@ -462,11 +470,7 @@ export class OAuthRefresher {
 			.then(refreshed => {
 				// A delegated refresh may have returned a broker-cached token rather
 				// than minting one. Only direct local requests can establish mint time.
-				if (
-					!hasRefreshLeases(this.#deps.store) &&
-					this.#deps.override === undefined &&
-					this.#deps.store.refreshOAuthCredential === undefined
-				) {
+				if (!hasRefreshLeases(this.#deps.store) && this.#mintsLocally()) {
 					this.#rememberMint(provider, credentialId, refreshed);
 				}
 				return refreshed;
@@ -613,7 +617,7 @@ export class OAuthRefresher {
 		const promise = (async () => {
 			this.#deps.pool.bump("credential-refresh-start");
 			try {
-				return await this.#forceRefreshCredentialByIdUnshared(id, signal);
+				return await this.#forceRefreshCredentialByIdUnshared(id, signal, options?.reason);
 			} catch (error) {
 				this.#deps.pool.bump("credential-refresh-failure");
 				throw error;
@@ -625,7 +629,11 @@ export class OAuthRefresher {
 		return raceSignal(promise, signal, "credential refresh aborted");
 	}
 
-	async #forceRefreshCredentialByIdUnshared(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry> {
+	async #forceRefreshCredentialByIdUnshared(
+		id: number,
+		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
+	): Promise<AuthCredentialSnapshotEntry> {
 		for (const provider of this.#deps.pool.providers()) {
 			const entries = this.#deps.pool.entries(provider);
 			const index = entries.findIndex(entry => entry.id === id);
@@ -645,7 +653,7 @@ export class OAuthRefresher {
 			const stale: OAuthCredential = { ...attempted, expires: 0 };
 			let refreshed: OAuthCredentials;
 			try {
-				refreshed = await this.#refreshSingleFlight(provider as Provider, stale, id, signal);
+				refreshed = await this.#refreshSingleFlight(provider as Provider, stale, id, signal, reason);
 			} catch (error) {
 				// A definitively-dead grant tears the row down here, where the
 				// attempted credential is known. CAS on the persisted credential so a

package/src/auth/select.ts

@@ -4,6 +4,7 @@ import { getOAuthApiKey, getOAuthProvider } from "../registry/oauth";
 import type { OAuthCredentials, OAuthProvider } from "../registry/oauth/types";
 import type { Provider } from "../types";
 import type { CredentialRankingContext, CredentialRankingStrategy, PlanGate, UsageReport } from "../usage";
+import { isWithinUsageReserve } from "../usage";
 import type { RankingStrategyResolver } from "../usage/registry";
 import type { SessionAffinity } from "./affinity";
 import {
@@ -28,12 +29,13 @@ import {
 } from "./rank";
 import { mergeRefreshedCredential, OAUTH_REFRESH_SKEW_MS, type OAuthRefresher } from "./refresh";
 import type { AuthCredentialStore } from "./store";
-import type {
-	ApiKeyCredential,
-	AuthApiKeyOptions,
-	AuthCredential,
-	OAuthCredential,
-	StoredAuthCredential,
+import {
+	type ApiKeyCredential,
+	type AuthApiKeyOptions,
+	type AuthCredential,
+	type OAuthCredential,
+	oauthAccountKey,
+	type StoredAuthCredential,
 } from "./types";
 import type { UsageService } from "./usage";
 import {
@@ -475,7 +477,9 @@ export class CredentialSelector {
 				blocked,
 				blockedUntil,
 				inReserve:
-					reserveFraction !== undefined && remainingFraction !== undefined && remainingFraction <= reserveFraction,
+					reserveFraction !== undefined &&
+					remainingFraction !== undefined &&
+					isWithinUsageReserve(remainingFraction, reserveFraction),
 				reserveMeasured: reserveFraction !== undefined && remainingFraction !== undefined,
 				accountPriority: policy?.priority === undefined || !Number.isFinite(policy.priority) ? 0 : policy.priority,
 				allowanceSpent: remainingFraction === 0,
@@ -547,9 +551,10 @@ export class CredentialSelector {
 		const accountIds = options?.accountIds?.length ? new Set(options.accountIds) : undefined;
 		const enforceAccounts =
 			accountIds !== undefined &&
-			credentials.some(
-				({ credential }) => credential.accountId !== undefined && accountIds.has(credential.accountId),
-			);
+			credentials.some(({ credential }) => {
+				const accountKey = oauthAccountKey(credential);
+				return accountKey !== undefined && accountIds.has(accountKey);
+			});
 		const hasAccountPolicy = credentials.some(
 			({ credential }) => this.#deps.policies.forCredential(provider, credential) !== undefined,
 		);
@@ -883,8 +888,8 @@ export class CredentialSelector {
 		for (const pass of passes) {
 			for (const candidate of candidates) {
 				if (preflightFailures.has(candidate)) continue;
-				const candidateAccountId = candidate.selection.credential.accountId;
-				if (pass.enforceAccounts && (candidateAccountId === undefined || !accountIds?.has(candidateAccountId)))
+				const candidateAccountKey = oauthAccountKey(candidate.selection.credential);
+				if (pass.enforceAccounts && (candidateAccountKey === undefined || !accountIds?.has(candidateAccountKey)))
 					continue;
 				const resolved = await this.tryOAuth(provider, candidate.selection, providerKey, sessionId, options, {
 					checkUsage,