@oh-my-pi/pi-ai 18.4.0 → 18.4.2

package/src/auth/refresh.ts

@@ -13,6 +13,8 @@ import {
 	type AuthCredentialSnapshotEntry,
 	type AuthStorageOptions,
 	type OAuthCredential,
+	type OAuthRefreshByIdOptions,
+	type OAuthRefreshReason,
 	type StoredOAuthRefreshOptions,
 	type StoredOAuthRefreshResult,
 } from "./types";
@@ -30,6 +32,12 @@ import {
  * the rotation cadence by <4%.
  */
 export const OAUTH_REFRESH_SKEW_MS = 60_000;
+/**
+ * How long auth recovery may reuse a token this refresher actually minted.
+ * Re-minting a token that a provider rejected moments ago only rotates the
+ * refresh token and churns broker snapshots during provider-wide outages.
+ */
+const OAUTH_REMINT_COOLDOWN_MS = 5 * 60_000;
 const OAUTH_REFRESH_LEASE_TTL_MS = 15_000;
 const OAUTH_REFRESH_LEASE_POLL_MS = 50;
 const OAUTH_REFRESH_LEASE_RENEW_MS = 5_000;
@@ -67,11 +75,45 @@ export class OAuthRefresher {
 	readonly #deps: OAuthRefresherDeps;
 	#oauthRefreshInFlight: Map<number, Promise<AuthCredentialSnapshotEntry>> = new Map();
 	#oauthCredentialRefreshInFlight: Map<number, Promise<OAuthCredentials>> = new Map();
+	/** Access token this process last minted per credential id. */
+	#recentMints = new Map<number, { provider: string; access: string; at: number }>();
 
 	constructor(deps: OAuthRefresherDeps) {
 		this.#deps = deps;
 	}
 
+	/**
+	 * Return the stored row while it still holds a usable token this refresher
+	 * minted within {@link OAUTH_REMINT_COOLDOWN_MS}.
+	 */
+	#recentMint(id: number): { provider: string; credential: OAuthCredential } | undefined {
+		const mint = this.#recentMints.get(id);
+		if (!mint) return undefined;
+		const now = Date.now();
+		if (now - mint.at >= OAUTH_REMINT_COOLDOWN_MS) {
+			this.#recentMints.delete(id);
+			return undefined;
+		}
+		const credential = this.#deps.pool.entries(mint.provider).find(entry => entry.id === id)?.credential;
+		if (
+			credential?.type !== "oauth" ||
+			credential.access !== mint.access ||
+			credential.expires <= now + OAUTH_REFRESH_SKEW_MS
+		) {
+			this.#recentMints.delete(id);
+			return undefined;
+		}
+		return { provider: mint.provider, credential };
+	}
+
+	#rememberMint(provider: string, id: number, credential: OAuthCredentials): void {
+		const now = Date.now();
+		for (const [cachedId, mint] of this.#recentMints) {
+			if (now - mint.at >= OAUTH_REMINT_COOLDOWN_MS) this.#recentMints.delete(cachedId);
+		}
+		this.#recentMints.set(id, { provider, access: credential.access, at: now });
+	}
+
 	/**
 	 * Refresh one stored OAuth credential under durable row ownership.
 	 */
@@ -278,6 +320,9 @@ export class OAuthRefresher {
 			} else {
 				this.#deps.store.updateAuthCredential(row.id, merged);
 			}
+			if (this.#deps.override === undefined && this.#deps.store.refreshOAuthCredential === undefined) {
+				this.#rememberMint(provider, row.id, merged);
+			}
 			this.#deps.pool.replace(
 				provider,
 				rows.map(entry => ({
@@ -361,6 +406,23 @@ export class OAuthRefresher {
 		credential: OAuthCredential,
 		credentialId: number | undefined,
 		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
+	): Promise<OAuthCredentials> {
+		const authRecovery = reason === "auth-recovery";
+		if (authRecovery && credentialId !== undefined && !this.#oauthCredentialRefreshInFlight.has(credentialId)) {
+			const recent = this.#recentMint(credentialId);
+			if (recent) return recent.credential;
+		}
+		return this.#refreshSingleFlight(provider, credential, credentialId, signal, reason);
+	}
+
+	/** Refresh without recent-mint reuse; still shares the per-credential in-flight request. */
+	async #refreshSingleFlight(
+		provider: Provider,
+		credential: OAuthCredential,
+		credentialId: number | undefined,
+		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
 	): Promise<OAuthCredentials> {
 		credential = normalizeOAuthCredentialExpiry(provider, credential);
 		if (credentialId !== undefined) {
@@ -369,11 +431,24 @@ export class OAuthRefresher {
 		}
 		if (Date.now() + OAUTH_REFRESH_SKEW_MS < credential.expires) return credential;
 		if (credentialId === undefined) {
-			return this.#refreshOAuthCredentialUnshared(provider, credential, undefined, signal);
+			return this.#refreshOAuthCredentialUnshared(provider, credential, undefined, signal, reason);
 		}
-		const promise = this.#refreshOAuthCredentialUnshared(provider, credential, credentialId).finally(() => {
-			this.#oauthCredentialRefreshInFlight.delete(credentialId);
-		});
+		const promise = this.#refreshOAuthCredentialUnshared(provider, credential, credentialId, signal, reason)
+			.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
+				) {
+					this.#rememberMint(provider, credentialId, refreshed);
+				}
+				return refreshed;
+			})
+			.finally(() => {
+				this.#oauthCredentialRefreshInFlight.delete(credentialId);
+			});
 		this.#oauthCredentialRefreshInFlight.set(credentialId, promise);
 		return raceSignal(promise, signal, "credential refresh aborted");
 	}
@@ -383,6 +458,7 @@ export class OAuthRefresher {
 		credential: OAuthCredential,
 		credentialId: number | undefined,
 		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
 	): Promise<OAuthCredentials> {
 		if (credentialId !== undefined && hasRefreshLeases(this.#deps.store)) {
 			const forceRefresh = credential.expires === 0;
@@ -398,6 +474,7 @@ export class OAuthRefresher {
 						current,
 						credentialId,
 						signal && refreshSignal ? AbortSignal.any([signal, refreshSignal]) : (signal ?? refreshSignal),
+						reason,
 					),
 				isDefinitiveFailure: error => AIError.isDefinitiveOAuthFailure(String(error)),
 				disabledCause: error => `oauth refresh failed: ${String(error)}`,
@@ -429,7 +506,7 @@ export class OAuthRefresher {
 				provider,
 			});
 		}
-		return this.#requestOAuthCredentialRefresh(provider, credential, credentialId, signal);
+		return this.#requestOAuthCredentialRefresh(provider, credential, credentialId, signal, reason);
 	}
 
 	async #requestOAuthCredentialRefresh(
@@ -437,6 +514,7 @@ export class OAuthRefresher {
 		credential: OAuthCredential,
 		credentialId: number | undefined,
 		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
 	): Promise<OAuthCredentials> {
 		let refreshPromise: Promise<OAuthCredentials>;
 		// Caller override > store-level hook > local per-provider refresh.
@@ -445,7 +523,7 @@ export class OAuthRefresher {
 		const storeRefresh = this.#deps.store.refreshOAuthCredential?.bind(this.#deps.store);
 		const overrideRefresh = this.#deps.override ?? storeRefresh;
 		if (overrideRefresh && credentialId !== undefined) {
-			refreshPromise = overrideRefresh(provider, credentialId, credential, signal);
+			refreshPromise = overrideRefresh(provider, credentialId, credential, signal, reason);
 		} else {
 			const customProvider = getOAuthProvider(provider);
 			if (customProvider) {
@@ -497,9 +575,15 @@ export class OAuthRefresher {
 	 * refresh attempt, which is required for providers that rotate refresh tokens
 	 * on every successful refresh.
 	 */
-	async refreshById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry> {
+	async refreshById(
+		id: number,
+		signal?: AbortSignal,
+		options?: OAuthRefreshByIdOptions,
+	): Promise<AuthCredentialSnapshotEntry> {
 		const existing = this.#oauthRefreshInFlight.get(id);
 		if (existing) return raceSignal(existing, signal, "credential refresh aborted");
+		const recent = options?.reuseRecentMint ? this.#recentMint(id) : undefined;
+		if (recent) return snapshotEntry(id, recent.provider, recent.credential);
 
 		const promise = (async () => {
 			this.#deps.pool.bump("credential-refresh-start");
@@ -531,12 +615,12 @@ export class OAuthRefresher {
 			// await so a definitive failure can CAS-disable the row against the
 			// value we actually attempted (NOT the expires:0 clone below).
 			const attempted = target.credential;
-			// Pass a clone with expires=0 so the cached not-yet-expired short-circuit
-			// in refresh doesn't suppress the requested refresh.
+			// Pass a clone with expires=0 and bypass recent-mint reuse so scheduled
+			// refreshes and direct force-refresh callers always mint.
 			const stale: OAuthCredential = { ...attempted, expires: 0 };
 			let refreshed: OAuthCredentials;
 			try {
-				refreshed = await this.refresh(provider as Provider, stale, id, signal);
+				refreshed = await this.#refreshSingleFlight(provider as Provider, stale, id, signal);
 			} catch (error) {
 				// A definitively-dead grant tears the row down here, where the
 				// attempted credential is known. CAS on the persisted credential so a
@@ -563,13 +647,18 @@ export class OAuthRefresher {
 			if (this.#deps.pool.replaceById(provider, id, updated) === -1) {
 				throw new AIError.ValidationError(`No credential with id=${id}`);
 			}
-			return {
-				id,
-				provider,
-				credential: { ...updated, refresh: REMOTE_REFRESH_SENTINEL },
-				identityKey: resolveCredentialIdentityKey(provider, updated),
-			};
+			return snapshotEntry(id, provider, updated);
 		}
 		throw new AIError.ValidationError(`No credential with id=${id}`);
 	}
 }
+
+/** Broker-facing snapshot entry for a refreshed row; the real refresh token never leaves the store. */
+function snapshotEntry(id: number, provider: string, credential: OAuthCredential): AuthCredentialSnapshotEntry {
+	return {
+		id,
+		provider,
+		credential: { ...credential, refresh: REMOTE_REFRESH_SENTINEL },
+		identityKey: resolveCredentialIdentityKey(provider, credential),
+	};
+}

package/src/auth/resets.ts

@@ -200,7 +200,9 @@ export class ResetCredits implements ResetsApi {
 					selected.remainingCount < pending.remainingCount
 				) {
 					this.#pendingClaudeResets.delete(accountKey);
-					this.#deps.usageCache.invalidateAfterReset(provider, options.baseUrl);
+					this.#deps.usageCache.invalidateAfterReset(provider, options.baseUrl, {
+						resetSpentCredentialId: access.credentialId,
+					});
 					return { ...identity, ok: false, code: "already_redeemed", creditId };
 				}
 				if (pending.program === "juniper_tide") {
@@ -256,7 +258,9 @@ export class ResetCredits implements ResetsApi {
 			result = { ...identity, ok: consumed.ok, code: consumed.code, creditId };
 		}
 		if (result.ok) {
-			this.#deps.usageCache.invalidateAfterReset(provider, options.baseUrl);
+			this.#deps.usageCache.invalidateAfterReset(provider, options.baseUrl, {
+				resetSpentCredentialId: access.credentialId,
+			});
 			if (this.#deps.store.invalidateUsageCache) {
 				await this.#deps.store.invalidateUsageCache(options.signal).catch(err => {
 					logger.debug("Failed to notify store of stale usage", { err });

package/src/auth/select.ts

@@ -697,8 +697,18 @@ export class CredentialSelector {
 						refreshTarget,
 						credentialId,
 						options?.signal,
+						force ? options?.refreshReason : undefined,
 					);
-					const updated = mergeRefreshedCredential(candidate.selection.credential, refreshedCredentials);
+					const beforeRefresh = candidate.selection.credential;
+					const updated = mergeRefreshedCredential(beforeRefresh, refreshedCredentials);
+					if (credentialId !== undefined && authCredentialEquals(beforeRefresh, updated)) {
+						// The await may have allowed a peer to replace/remove this row or
+						// compact its index. Rebind by id without writing the cached result.
+						if (!this.#syncOAuthSelectionFromStore(provider, candidate.selection, credentialId)) {
+							preflightFailures.add(candidate);
+						}
+						return;
+					}
 					candidate.selection.credential = updated;
 					if (credentialId !== undefined) {
 						const idx = this.#deps.pool.replaceById(provider, credentialId, updated);

package/src/auth/store.ts

@@ -13,6 +13,7 @@ import type {
 	AuthCredential,
 	DisabledCredentialSummary,
 	OAuthCredential,
+	OAuthRefreshReason,
 	StoredAuthCredential,
 	StoredCredentialBlock,
 } from "./types";
@@ -157,12 +158,15 @@ 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,
+		reason?: OAuthRefreshReason,
 	): Promise<OAuthCredentials>;
 	/**
 	 * Optional async pre-read hook invoked after AuthStorage selects a stored

package/src/auth/types.ts

@@ -322,6 +322,9 @@ export interface CredentialDisabledEvent {
 	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;
@@ -351,6 +354,9 @@ 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.
@@ -360,6 +366,7 @@ export type AuthStorageOptions = {
 		credentialId: number,
 		credential: OAuthCredential,
 		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
 	) => Promise<OAuthCredentials>;
 	/**
 	 * Human-readable description of the credential store backing this
@@ -475,6 +482,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;
 };
 
 /**
@@ -956,6 +965,16 @@ 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. */
+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 {
 	/**
@@ -1034,9 +1053,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.
 	 */

package/src/auth/usage-cache.ts

@@ -287,23 +287,27 @@ export 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 {
 		this.#epoch += 1;
 		const expired = Date.now() - 1;
 		for (const entry of this.#pool.entries(provider)) {
 			if (entry.credential.type !== "oauth") continue;
 			const cacheKey = this.reportKey(oauthUsageRequest(provider, entry.credential, baseUrl));
-			const existing = this.getStale<UsageReport | null>(cacheKey);
-			this.set(cacheKey, {
-				value: existing?.value ?? null,
-				expiresAt: expired,
-			});
+			let value = this.getStale<UsageReport | null>(cacheKey)?.value ?? null;
+			if (value?.resetCredits && entry.id === options?.resetSpentCredentialId) {
+				const { resetCredits: _spent, ...rest } = value;
+				value = rest;
+			}
+			this.set(cacheKey, { value, expiresAt: expired });
 		}
 	}
 
 	/** A confirmed reset permits one fresh probe even during a pre-reset failure cooldown. */
-	invalidateAfterReset(provider: Provider, baseUrl?: string): void {
+	invalidateAfterReset(provider: Provider, baseUrl?: string, options?: { resetSpentCredentialId?: number }): void {
 		this.#recoveryEpochs.set(provider, this.recoveryEpoch(provider) + 1);
 		this.#bumpRefreshEpoch(provider);
 		if (!this.deletePrefix(`failure:report:${this.#usageCacheProviderKey(provider)}:`)) {
@@ -313,7 +317,7 @@ export class UsageCache {
 			}
 			for (const key of keys) this.set(this.failureKey(key), { value: null, expiresAt: 0 });
 		}
-		this.invalidate(provider, baseUrl);
+		this.invalidate(provider, baseUrl, options);
 	}
 
 	/**

package/src/auth/usage.ts

@@ -103,6 +103,11 @@ export interface UsageServiceDeps {
 	logger: UsageLogger;
 }
 
+type UsageReportsOptions = {
+	baseUrlResolver?: (provider: Provider) => string | undefined;
+	signal?: AbortSignal;
+};
+
 /** Usage reports: per-credential cached fetches, aggregate reports, header ingestion, history. */
 export class UsageService implements UsageApi {
 	#deps: UsageServiceDeps;
@@ -261,9 +266,13 @@ export class UsageService implements UsageApi {
 		if (providerImpl.supports && !providerImpl.supports(params)) return null;
 
 		try {
+			const previousReport = this.#deps.cache.getStale<UsageReport | null>(
+				this.#deps.cache.reportKey(request),
+			)?.value;
 			const report = await providerImpl.fetchUsage(params, {
 				fetch: this.fetch,
 				logger: this.logger,
+				...(previousReport ? { previousReport } : {}),
 			});
 			// Attribute the report to the credential's organization. The orgId and
 			// orgName fallbacks apply independently: Claude's usage endpoint stamps
@@ -563,16 +572,19 @@ export class UsageService implements UsageApi {
 		return true;
 	}
 
-	/** Collect resolved account requests for all configured usage providers. */
-	async #collectUsageRequests(options?: {
-		baseUrlResolver?: (provider: Provider) => string | undefined;
-	}): Promise<UsageRequestDescriptor[]> {
+	/** Collect resolved account requests, restricted to runtime providers when the store owns aggregate reports. */
+	async #collectUsageRequests(
+		options?: UsageReportsOptions,
+		providerFilter?: ReadonlySet<Provider>,
+	): Promise<UsageRequestDescriptor[]> {
 		const requests: UsageRequestDescriptor[] = [];
-		const providers = new Set<string>([
-			...this.#deps.pool.providers(),
-			...this.#runtimeUsageProviderOverrides.keys(),
-			...DEFAULT_USAGE_PROVIDERS.map(provider => provider.id),
-		]);
+		const providers =
+			providerFilter ??
+			new Set<string>([
+				...this.#deps.pool.providers(),
+				...this.#runtimeUsageProviderOverrides.keys(),
+				...DEFAULT_USAGE_PROVIDERS.map(provider => provider.id),
+			]);
 
 		for (const providerId of providers) {
 			const provider = providerId as Provider;
@@ -742,14 +754,9 @@ export class UsageService implements UsageApi {
 	}
 
 	/** Fetch all providers’ current usage reports, sharing concurrent polls. */
-	async 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> {
-		// Store-level hook > local per-credential fan-out. `RemoteAuthCredentialStore`
-		// implements the hook so a gateway backed by a broker routes usage to the
-		// broker without the caller wiring it explicitly.
+	async reports(options?: UsageReportsOptions): Promise<UsageReport[] | null> {
+		// The broker owns its providers' reports; runtime providers registered
+		// only in this process still need local per-credential probes.
 		const storeOverride = this.#deps.store.fetchUsageReports?.bind(this.#deps.store);
 		if (storeOverride) {
 			// Reuse the in-flight map so concurrent callers (widget poll + format
@@ -768,9 +775,28 @@ export class UsageService implements UsageApi {
 			}
 			const reports = await raceSignal(shared, options?.signal, "usage fetch aborted");
 			if (reports) this.#deps.blocks.reconcileReports(reports);
-			return reports;
+			if (!reports || this.#runtimeUsageProviderOverrides.size === 0) return reports;
+
+			// The broker owns its reported providers; only extension providers
+			// absent from its response need local credentials and a local probe.
+			const brokerProviders = new Set(reports.map(report => report.provider));
+			const localProviders = new Set<Provider>();
+			for (const provider of this.#runtimeUsageProviderOverrides.keys()) {
+				if (!brokerProviders.has(provider)) localProviders.add(provider);
+			}
+			if (localProviders.size === 0) return reports;
+			const localReports = await this.#fetchLocalReports(options, localProviders);
+			return localReports?.length ? [...reports, ...localReports] : reports;
 		}
-		const requests = await this.#collectUsageRequests(options);
+		return this.#fetchLocalReports(options);
+	}
+
+	/** Probe only the selected providers locally, preserving per-credential caching and cooldowns. */
+	async #fetchLocalReports(
+		options?: UsageReportsOptions,
+		providerFilter?: ReadonlySet<Provider>,
+	): Promise<UsageReport[] | null> {
+		const requests = await this.#collectUsageRequests(options, providerFilter);
 		if (requests.length === 0) return [];
 
 		this.logger?.debug("Usage fetch requested", {

package/src/auth-broker/client.ts

@@ -8,7 +8,7 @@
 
 import { type } from "@oh-my-pi/omptype";
 import { readSseEvents } from "@oh-my-pi/pi-utils";
-import type { AuthCredential, DisabledCredentialSummary } from "../auth-storage";
+import type { AuthCredential, DisabledCredentialSummary, OAuthRefreshReason } from "../auth-storage";
 import type {
 	ClientUsageReportRequest,
 	ClientUsageReportResponse,
@@ -327,8 +327,13 @@ export class AuthBrokerClient {
 		});
 	}
 
-	async refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse> {
-		return this.#request<CredentialRefreshResponse>("POST", `/v1/credential/${id}/refresh`, {
+	async refreshCredential(
+		id: number,
+		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
+	): Promise<CredentialRefreshResponse> {
+		const suffix = reason === "auth-recovery" ? "?reason=auth-recovery" : "";
+		return this.#request<CredentialRefreshResponse>("POST", `/v1/credential/${id}/refresh${suffix}`, {
 			schema: "credentialRefreshResponseSchema",
 			signal,
 		});

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

@@ -15,6 +15,7 @@ import {
 	type AuthCredentialSnapshotEntry,
 	type DisabledCredentialSummary,
 	type OAuthCredential,
+	type OAuthRefreshReason,
 	REMOTE_REFRESH_SENTINEL,
 	type StoredAuthCredential,
 	type StoredCredentialBlock,
@@ -856,7 +857,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	async markCredentialSuspect(credentialId: number, opts: { signal?: AbortSignal } = {}): Promise<void> {
 		this.#noteActivity();
-		const { entry } = await this.#client.refreshCredential(credentialId, opts.signal);
+		const { entry } = await this.#client.refreshCredential(credentialId, opts.signal, "auth-recovery");
 		if (entry.credential.type !== "oauth") {
 			throw new AIError.AuthBrokerError(`Broker returned non-OAuth credential for id=${credentialId}`);
 		}
@@ -1172,9 +1173,10 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 		credentialId: number,
 		_credential: OAuthCredential,
 		signal?: AbortSignal,
+		reason?: OAuthRefreshReason,
 	): Promise<OAuthCredentials> {
 		this.#noteActivity();
-		const { entry } = await this.#client.refreshCredential(credentialId, signal);
+		const { entry } = await this.#client.refreshCredential(credentialId, signal, reason);
 		if (entry.credential.type !== "oauth") {
 			throw new AIError.AuthBrokerError(`Broker returned non-OAuth credential for id=${credentialId}`);
 		}

package/src/auth-broker/server.ts

@@ -50,6 +50,7 @@ import {
 } from "./wire-schemas";
 
 const DEFAULT_EXTERNAL_CHANGE_POLL_MS = 250;
+const AUTH_RECOVERY_REFRESH_OPTIONS = { reuseRecentMint: true } as const;
 
 export interface AuthBrokerServerOptions {
 	/** Underlying credential storage (wraps the local SQLite store on the broker). */
@@ -765,8 +766,13 @@ export function startAuthBroker(opts: AuthBrokerServerOptions): AuthBrokerServer
 				const refreshMatch = req.method === "POST" ? pathname.match(REFRESH_ROUTE) : null;
 				if (refreshMatch) {
 					const id = Number.parseInt(refreshMatch[1], 10);
+					const authRecovery = url.searchParams.get("reason") === "auth-recovery";
 					try {
-						const entry = await opts.storage.oauth.refresh(id, req.signal);
+						const entry = await opts.storage.oauth.refresh(
+							id,
+							req.signal,
+							authRecovery ? AUTH_RECOVERY_REFRESH_OPTIONS : undefined,
+						);
 						const body: CredentialRefreshResponse = { entry };
 						logger.info("auth-broker credential refreshed", {
 							id,

package/src/auth-gateway/dispatch.ts

@@ -214,6 +214,7 @@ export function buildGatewayApiKeyResolver(
 			const refreshed = await storage.keys.get(model.provider, sessionId, {
 				...modelKeyOptions(model, sig),
 				forceRefresh: true,
+				refreshReason: AIError.status(error) === 401 ? "auth-recovery" : undefined,
 			});
 			lastKey = refreshed ?? lastKey;
 			if (refreshed) onResolvedKey?.(refreshed);

package/src/auth-retry.ts

@@ -423,7 +423,11 @@ export async function withOAuthAccess<T>(
 			if (!refreshedCurrent) {
 				refreshedCurrent = true;
 				try {
-					next = await storage.oauth.access(provider, sessionId, { forceRefresh: true, signal });
+					next = await storage.oauth.access(provider, sessionId, {
+						forceRefresh: true,
+						refreshReason: AIError.status(lastError) === 401 ? "auth-recovery" : undefined,
+						signal,
+					});
 				} catch {
 					next = undefined;
 				}

package/src/error/flags.ts

@@ -875,14 +875,21 @@ export function attach<E extends object>(error: E, id: number): E {
 
 /** Overflow-classification evidence, including errors received before token usage is available. */
 export interface ContextOverflowMessage extends Pick<AssistantMessage, "errorId" | "stopReason" | "errorMessage"> {
-	readonly usage?: Pick<Usage, "input" | "cacheRead" | "cacheWrite">;
+	readonly usage?: Pick<Usage, "input" | "cacheRead" | "cacheWrite" | "contextTokens">;
 }
 
-/** Provider-reported usage proves context-window excess — authoritative, compaction-owned (#9235). */
+/**
+ * Provider-reported usage proves context-window excess — authoritative, compaction-owned (#9235).
+ *
+ * Prefers `contextTokens` when the provider reports it: providers that run
+ * several model calls per turn (Cursor's server-side tool loop) report
+ * `input`/`cacheRead` summed across those calls, which can exceed the window
+ * many times over while the conversation itself stays small.
+ */
 export function isUsageBackedContextOverflow(message: ContextOverflowMessage, contextWindow?: number): boolean {
 	const usage = message.usage;
 	if (!contextWindow || !usage) return false;
-	const inputTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+	const inputTokens = usage.contextTokens ?? usage.input + usage.cacheRead + usage.cacheWrite;
 	return inputTokens > contextWindow;
 }