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

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [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

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.8.4",
+	"version": "18.8.5",
 	"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.5",
+		"@oh-my-pi/pi-catalog": "18.8.5",
+		"@oh-my-pi/pi-natives": "18.8.5",
+		"@oh-my-pi/pi-utils": "18.8.5",
+		"@oh-my-pi/pi-wire": "18.8.5"
 	},
 	"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,

package/src/auth/types.ts

@@ -373,6 +373,12 @@ export type AuthStorageOptions = {
 		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}
@@ -472,7 +478,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
@@ -493,6 +499,22 @@ export type AuthApiKeyOptions = {
 	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 function oauthAccountKey(identity: {
+	accountId?: string;
+	email?: string;
+	projectId?: string;
+}): string | undefined {
+	return identity.accountId ?? identity.email ?? identity.projectId;
+}
+
 /** Non-secret identity bound to the OAuth credential selected for one request attempt. */
 export interface OAuthRequestIdentity {
 	orgId?: string;
@@ -998,7 +1020,7 @@ export interface KeysApi {
 	resolver(provider: string, options?: { sessionId?: string; baseUrl?: string; 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
@@ -1006,6 +1028,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. */
@@ -1048,9 +1076,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.
@@ -1088,8 +1117,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>;
 	/**
@@ -1124,14 +1154,19 @@ export interface SessionsApi {
 	 */
 	pin(provider: string, sessionId: string, credentialId: number, options?: { 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.
-	 */
-	inherit(sourceSessionId: string, targetSessionId: string): number;
+	 * 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,
+		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/src/auth-broker/remote-store.ts

@@ -8,7 +8,7 @@
  * runs isn't required.
  */
 import * as os from "node:os";
-import { getAppName, getInstallId, logger } from "@oh-my-pi/pi-utils";
+import { getAppName, getInstallId, logger, postmortem } from "@oh-my-pi/pi-utils";
 import type { AuthCredentialStore } from "../auth/store";
 import {
 	type AuthCredential,
@@ -69,6 +69,8 @@ const BACKGROUND_BACKOFF_INITIAL_MS = 500;
 const BACKGROUND_BACKOFF_MAX_MS = 30_000;
 /** Idle window after the last foreground store use before background sync parks. */
 const BACKGROUND_IDLE_MS = 20_000;
+/** Longest a process exit waits for the final observed-usage report to reach the broker. */
+const OBSERVED_USAGE_EXIT_FLUSH_MS = 2_000;
 
 function toCredentialBlockSnapshot(block: StoredCredentialBlock): CredentialBlockSnapshot {
 	return {
@@ -318,6 +320,10 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 	readonly #observedUsageFlushMs: number;
 	/** Latched once the broker answered 404 — old broker, never report again. */
 	#observedUsageUnsupported = false;
+	/** Tail of the serialized observed-usage sends; each flush waits for the one before it. */
+	#observedUsageFlush: Promise<void> = Promise.resolve();
+	/** Cancels the exit flush registered with the first buffered usage. */
+	#cancelObservedUsageExitFlush: (() => void) | undefined;
 
 	constructor(opts: RemoteAuthCredentialStoreOptions) {
 		this.#client = opts.client;
@@ -1456,9 +1462,10 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	/**
 	 * 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.
@@ -1488,9 +1495,31 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 			}, this.#observedUsageFlushMs);
 			this.#observedUsageTimer.unref?.();
 		}
+		// The timer never holds the process open, so a process that exits first (a
+		// one-shot run, a signal) sends what is still buffered on the way out. The
+		// wait is bounded: an unreachable broker must not stall the exit.
+		this.#cancelObservedUsageExitFlush ??= postmortem.register("auth-broker-observed-usage", () =>
+			raceSignal(
+				this.#flushObservedUsage(),
+				AbortSignal.timeout(OBSERVED_USAGE_EXIT_FLUSH_MS),
+				"observed usage exit flush timed out",
+			).catch(error => {
+				logger.debug("auth-broker observed usage dropped at exit", { error: String(error) });
+			}),
+		);
+	}
+
+	#flushObservedUsage(): Promise<void> {
+		// The tail never rejects, so one failed send cannot stall every later flush.
+		this.#observedUsageFlush = this.#observedUsageFlush
+			.then(() => this.#sendObservedUsage())
+			.catch(error => {
+				logger.debug("auth-broker observed usage flush failed", { error: String(error) });
+			});
+		return this.#observedUsageFlush;
 	}
 
-	async #flushObservedUsage(): Promise<void> {
+	async #sendObservedUsage(): Promise<void> {
 		if (this.#observedUsage.size === 0 || this.#observedUsageUnsupported) return;
 		const batch = [...this.#observedUsage.values()];
 		this.#observedUsage.clear();
@@ -1539,8 +1568,9 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 			clearTimeout(this.#observedUsageTimer);
 			this.#observedUsageTimer = undefined;
 		}
-		// Best-effort final flush; failures are dropped (the process is exiting).
-		if (this.#observedUsage.size > 0) void this.#flushObservedUsage();
+		// Final flush. The exit registration outlives close() until it settles, so a
+		// process exiting right after close() still sends it; failures are dropped.
+		void this.#flushObservedUsage().finally(() => this.#cancelObservedUsageExitFlush?.());
 		this.#cache.clear();
 		this.#usageOverlays.clear();
 	}

package/src/auth-storage.ts

@@ -185,7 +185,13 @@ export class AuthStorage {
 				affinity.clearProvider(provider);
 			},
 		});
-		const refresher = new OAuthRefresher({ store, pool, policies, override: options.refreshOAuthCredential });
+		const refresher = new OAuthRefresher({
+			store,
+			pool,
+			policies,
+			override: options.refreshOAuthCredential,
+			overrideMints: options.refreshOAuthCredentialMints,
+		});
 		const usageProviders = options.usageProviderResolver ?? defaultUsageProvider;
 		// Key reports by the effective provider (runtime extension override first), so an
 		// override's `cacheVersion` separates its rows from other processes sharing the store.

package/src/providers/anthropic.ts

@@ -1307,10 +1307,12 @@ function buildClaudeCodeTlsFetchOptions(
 		},
 	};
 }
-function mergeHeaders(...headerSources: (Record<string, string> | undefined)[]): Record<string, string> {
-	// Case-insensitive merge: later sources win and keep their casing. A plain
-	// Object.assign would let `authorization` and `Authorization` coexist, and
-	// the Headers constructor then joins both values comma-separated on the wire.
+/**
+ * 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 function mergeHeaders(...headerSources: (Record<string, string> | undefined)[]): Record<string, string> {
 	const merged: Record<string, string> = {};
 	const keyByLower = new Map<string, string>();
 	for (const headers of headerSources) {

package/src/providers/cursor.ts

@@ -4496,13 +4496,13 @@ function isExecOwnedToolCall(toolCall: { tool?: { case?: string } } | undefined)
  * 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
@@ -4523,7 +4523,7 @@ export function flushOpenToolCalls(
 			clearStreamingPartialJson(block);
 		}
 		const kind = block[kStreamingBlockKind];
-		if (kind === "connect-scm" || kind === "todo" || kind === "cursor-edit") {
+		if (kind === "connect-scm" || kind === "todo" || kind === "cursor-edit" || kind === "web-fetch") {
 			if (!(kind === "cursor-edit" && state.pairedEditToolCallIds?.has(block.id))) {
 				state.onToolResult?.({
 					role: "toolResult",

package/src/usage.ts

@@ -169,6 +169,14 @@ export function resolveUsedFraction(limit: UsageLimit): number | undefined {
 	return undefined;
 }
 
+/** Float slack so a remaining fraction derived as `1 - used` still matches a reserve it sits exactly on. */
+const RESERVE_BOUNDARY_EPSILON = 1e-9;
+
+/** Whether remaining quota is at or below the reserve (both 0..1 fractions). */
+export function isWithinUsageReserve(remainingFraction: number, reserveFraction: number): boolean {
+	return remainingFraction <= reserveFraction + RESERVE_BOUNDARY_EPSILON;
+}
+
 /**
  * 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/src/utils/anthropic-auth.ts

@@ -9,7 +9,7 @@
  * through {@link buildAnthropicAuthConfig} for header/URL shaping.
  */
 import { $env } from "@oh-my-pi/pi-utils";
-import { buildAnthropicHeaders, resolveAnthropicCustomHeadersForBaseUrl } from "../providers/anthropic";
+import { buildAnthropicHeaders, mergeHeaders, resolveAnthropicCustomHeadersForBaseUrl } from "../providers/anthropic";
 import { normalizeAnthropicBaseUrl } from "../providers/anthropic-state";
 import { isFoundryEnabled } from "./foundry";
 
@@ -43,6 +43,12 @@ export function isOAuthToken(apiKey: string): boolean {
 	return apiKey.includes("sk-ant-oat");
 }
 
+/** 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.
  *
@@ -51,32 +57,50 @@ export 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 function buildAnthropicAuthConfig(apiKey: string, baseUrl?: string): AnthropicAuthConfig {
+export function buildAnthropicAuthConfig(
+	apiKey: string,
+	baseUrl?: string,
+	options: AnthropicAuthOptions = {},
+): AnthropicAuthConfig {
 	return {
 		apiKey,
 		baseUrl: normalizeBaseUrl(baseUrl) ?? resolveAnthropicBaseUrlFromEnv() ?? DEFAULT_BASE_URL,
-		isOAuth: isOAuthToken(apiKey),
+		isOAuth: options.isOAuth ?? isOAuthToken(apiKey),
 	};
 }
 
+/** 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 function buildAnthropicSearchHeaders(auth: AnthropicAuthConfig): Record<string, string> {
+export function buildAnthropicSearchHeaders(
+	auth: AnthropicAuthConfig,
+	options: AnthropicSearchHeaderOptions = {},
+): Record<string, string> {
 	return buildAnthropicHeaders({
 		apiKey: auth.apiKey,
 		baseUrl: auth.baseUrl,
 		isOAuth: auth.isOAuth,
 		extraBetas: ["web-search-2025-03-05"],
 		stream: false,
-		modelHeaders: resolveAnthropicCustomHeadersForBaseUrl(auth.baseUrl),
+		modelHeaders: mergeHeaders(options.modelHeaders, resolveAnthropicCustomHeadersForBaseUrl(auth.baseUrl)),
+		allowAnthropicHeaderOverrides: options.allowAnthropicHeaderOverrides,
 	});
 }