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

package/src/auth/rotation.ts

@@ -1,3 +1,4 @@
+import { scheduler } from "node:timers/promises";
 import * as AIError from "../error";
 import { isUsageLimitOutcome } from "../error/rate-limit";
 import { extractProviderRetryHint } from "../utils/retry-after";
@@ -5,6 +6,8 @@ import type { CredentialRankingContext, CredentialRankingStrategy } from "../usa
 import type { RankingStrategyResolver } from "../usage/registry";
 import { raceSignal } from "./abort";
 import {
+	ACCOUNT_POLICY_BLOCK_SCOPE,
+	AUTH_BLOCK_SCOPE,
 	DEFAULT_BLOCK_MS,
 	credentialBlockScopesForRequest,
 	modelAccountPolicyBlockScope,
@@ -17,6 +20,7 @@ import type { CredentialPool } from "./pool";
 import type { AuthCredentialStore } from "./store";
 import type {
 	AuthCredential,
+	CredentialRotation,
 	InvalidateCredentialMatchingOptions,
 	LimitsApi,
 	MarkUsageLimitOptions,
@@ -32,6 +36,16 @@ import {
 	windowResetAt,
 } from "./usage-report";
 
+/**
+ * Longest sibling block {@link RateLimits.rotate} sleeps out instead of giving
+ * up. Covers Cloud Code Assist capacity 429s ("Resets in 0s", sub-second
+ * `retryDelay`) that briefly block every healthy account; longer blocks stay
+ * with the caller's own backoff layer.
+ */
+const SIBLING_UNBLOCK_WAIT_MAX_MS = 5_000;
+/** Slack past a sibling's deadline so the post-wait resolve sees the block expired. */
+const SIBLING_UNBLOCK_SLACK_MS = 25;
+
 /** Routing scope and strategy for one failed credential. */
 export type CredentialBlockRouting = {
 	providerKey: string;
@@ -335,6 +349,7 @@ export class RateLimits implements LimitsApi {
 			providerTypeKey(provider, matched.type),
 			matched.index,
 			Date.now() + DEFAULT_BLOCK_MS,
+			AUTH_BLOCK_SCOPE,
 		);
 
 		const markSuspect = this.#deps.store.markCredentialSuspect?.bind(this.#deps.store);
@@ -373,9 +388,16 @@ export class RateLimits implements LimitsApi {
 	 *   reload when no broker hook is wired) and block it, then drop matching
 	 *   sticky state.
 	 *
-	 * Returns whether another usable credential of the same type remains.
+	 * For usage-limit and account-policy failures with no free sibling, sleeps
+	 * until the earliest sibling unblocks when that is at most
+	 * {@link SIBLING_UNBLOCK_WAIT_MAX_MS} away, then reports `afterSiblingWait`.
+	 * Aborting `options.signal` during that wait rejects.
 	 */
-	async rotate(provider: string, sessionId: string | undefined, options?: RotateCredentialOptions): Promise<boolean> {
+	async rotate(
+		provider: string,
+		sessionId: string | undefined,
+		options?: RotateCredentialOptions,
+	): Promise<CredentialRotation> {
 		await this.#deps.pool.adoptExternalChanges();
 		const error = options?.error;
 		const status = AIError.status(error);
@@ -387,16 +409,15 @@ export class RateLimits implements LimitsApi {
 			// will reset in 13 minutes") into the block duration so the credential
 			// is not reselected and hammered while the cap remains active.
 			const retryAfterMs = extractProviderRetryHint(provider, message);
-			return (
-				await this.markReached(provider, sessionId, {
-					retryAfterMs,
-					providerTimed: retryAfterMs !== undefined,
-					modelId: options?.modelId,
-					apiKey: options?.apiKey,
-					credentialId: options?.credentialId,
-					signal: options?.signal,
-				})
-			).switched;
+			const mark = await this.markReached(provider, sessionId, {
+				retryAfterMs,
+				providerTimed: retryAfterMs !== undefined,
+				modelId: options?.modelId,
+				apiKey: options?.apiKey,
+				credentialId: options?.credentialId,
+				signal: options?.signal,
+			});
+			return awaitSiblingUnblock(mark, options?.signal);
 		}
 
 		const deniedModel = AIError.codexChatGPTAccountPolicyModel(error);
@@ -408,16 +429,16 @@ export class RateLimits implements LimitsApi {
 			apiKey: options?.apiKey,
 			allowStaleOAuthBearer: accountPolicy || exactModelPolicy,
 		});
-		if (!sessionCredential) return false;
+		if (!sessionCredential) return { switched: false };
 		// The exact sentence is provider-controlled input. A non-Codex provider,
 		// absent request model, or mismatched model must not turn it into either a
 		// global block or a hard-auth invalidation.
-		if (deniedModel !== undefined && !exactCodexModelPolicy) return false;
+		if (deniedModel !== undefined && !exactCodexModelPolicy) return { switched: false };
 		if (exactModelPolicy || accountPolicy) {
 			const modelPolicyScope = exactModelPolicy
 				? modelAccountPolicyBlockScope(provider, options?.modelId)
 				: undefined;
-			if (exactModelPolicy && modelPolicyScope === undefined) return false;
+			if (exactModelPolicy && modelPolicyScope === undefined) return { switched: false };
 			const routing = this.#credentialBlockRouting(
 				provider,
 				sessionCredential.type,
@@ -425,7 +446,7 @@ export class RateLimits implements LimitsApi {
 				modelPolicyScope,
 			);
 			// Account-wide denials must not inherit a quota scope that healthy usage can heal.
-			routing.blockScope = modelPolicyScope;
+			routing.blockScope = modelPolicyScope ?? ACCOUNT_POLICY_BLOCK_SCOPE;
 			const sticky = this.#deps.affinity.get(provider, sessionId);
 			if (
 				!sessionCredential.explicit ||
@@ -433,14 +454,15 @@ export class RateLimits implements LimitsApi {
 			) {
 				this.#deps.affinity.clear(provider, sessionId);
 			}
-			return this.#blockCredentialForRotation(
+			const mark = this.#blockCredentialForRotation(
 				provider,
 				sessionCredential.type,
 				sessionCredential.index,
 				Date.now() + DEFAULT_BLOCK_MS,
 				routing,
 				false,
-			).switched;
+			);
+			return awaitSiblingUnblock(mark, options?.signal);
 		}
 
 		const providerKey = providerTypeKey(provider, sessionCredential.type);
@@ -462,7 +484,13 @@ export class RateLimits implements LimitsApi {
 		) {
 			this.#deps.affinity.clear(provider, sessionId);
 		}
-		this.#deps.blocks.mark(provider, providerKey, sessionCredential.index, Date.now() + DEFAULT_BLOCK_MS);
+		this.#deps.blocks.mark(
+			provider,
+			providerKey,
+			sessionCredential.index,
+			Date.now() + DEFAULT_BLOCK_MS,
+			AUTH_BLOCK_SCOPE,
+		);
 
 		if (target && AIError.isInvalidatedOAuthTokenError(error)) {
 			const disabledCause = message ?? "upstream reported invalidated OAuth token";
@@ -474,7 +502,7 @@ export class RateLimits implements LimitsApi {
 					latestRows.map(row => ({ id: row.id, credential: row.credential })),
 				);
 			}
-			return deleted && hasSibling;
+			return { switched: deleted && hasSibling };
 		}
 
 		if (target) {
@@ -491,6 +519,19 @@ export class RateLimits implements LimitsApi {
 			);
 		}
 
-		return hasSibling;
+		return { switched: hasSibling };
 	}
 }
+
+/**
+ * Turn a no-sibling mark into a rotation by sleeping out the soonest sibling
+ * block when it expires within {@link SIBLING_UNBLOCK_WAIT_MAX_MS}.
+ */
+async function awaitSiblingUnblock(mark: UsageLimitMarkResult, signal?: AbortSignal): Promise<CredentialRotation> {
+	if (mark.switched) return { switched: true };
+	if (mark.retryAtMs === undefined) return { switched: false };
+	const waitMs = mark.retryAtMs - Date.now() + SIBLING_UNBLOCK_SLACK_MS;
+	if (waitMs > SIBLING_UNBLOCK_WAIT_MAX_MS) return { switched: false };
+	if (waitMs > 0) await scheduler.wait(waitMs, { signal });
+	return { switched: true, afterSiblingWait: true };
+}

package/src/auth/select.ts

@@ -6,7 +6,13 @@ import type { Provider } from "../types";
 import type { CredentialRankingContext, CredentialRankingStrategy, PlanGate, UsageReport } from "../usage";
 import type { RankingStrategyResolver } from "../usage/registry";
 import type { SessionAffinity } from "./affinity";
-import { credentialBlockScopesForRequest, DEFAULT_BLOCK_MS, providerTypeKey, type CredentialBlocks } from "./blocks";
+import {
+	AUTH_BLOCK_SCOPE,
+	credentialBlockScopesForRequest,
+	DEFAULT_BLOCK_MS,
+	providerTypeKey,
+	type CredentialBlocks,
+} from "./blocks";
 import type { AccountPolicies } from "./policy";
 import { authCredentialEquals, type CredentialPool } from "./pool";
 import {
@@ -749,7 +755,7 @@ export class CredentialSelector {
 								providerKey,
 								latestIndex,
 								Date.now() + OAUTH_REFRESH_FAILURE_BACKOFF_MS,
-								blockScope,
+								AUTH_BLOCK_SCOPE,
 							);
 						}
 					}
@@ -1049,6 +1055,7 @@ export class CredentialSelector {
 					providerKey,
 					selection.index,
 					Date.now() + OAUTH_REFRESH_FAILURE_BACKOFF_MS,
+					AUTH_BLOCK_SCOPE,
 				);
 			}
 		}

package/src/auth/types.ts

@@ -632,6 +632,10 @@ export interface ResetCreditRedeemOutcome {
 /** One stored account's live saved-reset status, from {@link AuthStorage.resets.list}. */
 export interface ResetCreditAccountStatus extends UsageResetCredits {
 	provider: string;
+	/** Live quota evidence from this exact account's reset-discovery response. */
+	report?: UsageReport;
+	/** Provider-requested wait before retrying throttled reset discovery (not redemption). */
+	retryAfterMs?: number;
 	credentialId: number;
 	accountId?: string;
 	email?: string;
@@ -701,6 +705,21 @@ export type RotateCredentialOptions = {
 	signal?: AbortSignal;
 };
 
+/**
+ * Outcome of {@link LimitsApi.rotate}.
+ *
+ * `switched` is `true` when a usable same-type sibling credential is available,
+ * so the caller's next resolve hands it out. `afterSiblingWait` is `true` when
+ * no sibling was free at the failure but rotation slept out a sibling's short
+ * block (e.g. a Cloud Code Assist capacity 429 that resets in under a second);
+ * the freed credential may be one the caller already sent in this request, so
+ * attempted-bearer dedupe must let it through once.
+ */
+export interface CredentialRotation {
+	switched: boolean;
+	afterSiblingWait?: boolean;
+}
+
 /** Filter saved reset credits by provider and session. */
 export type ListResetCreditsOptions = {
 	provider?: string;
@@ -1199,9 +1218,15 @@ export interface LimitsApi {
 	 *   reload when no broker hook is wired) and block it, then drop matching
 	 *   sticky state.
 	 *
-	 * Returns whether another usable credential of the same type remains.
+	 * For usage-limit and account-policy failures with no free sibling, waits
+	 * (abortable via `options.signal`) when a sibling's block expires within a
+	 * few seconds, then reports `afterSiblingWait`.
 	 */
-	rotate(provider: string, sessionId: string | undefined, options?: RotateCredentialOptions): Promise<boolean>;
+	rotate(
+		provider: string,
+		sessionId: string | undefined,
+		options?: RotateCredentialOptions,
+	): Promise<CredentialRotation>;
 	/** Invalidate a credential matching an API key after authentication failure. */
 	invalidateMatching(
 		provider: string,
@@ -1232,7 +1257,7 @@ export interface BlocksApi {
 	 */
 	upsert(block: StoredCredentialBlock): void;
 	/**
-	 * Broker-server seam: clear all persisted blocks for one credential and notify snapshot waiters.
+	 * Broker-server seam: clear one exact persisted block and notify snapshot waiters.
 	 */
 	delete(credentialId: number, providerKey: string, blockScope: string): void;
 	/** Delete all persisted blocks for a credential. */

package/src/auth/usage-cache.ts

@@ -12,8 +12,8 @@ const USAGE_LAST_GOOD_RETENTION_MS = 24 * 60 * 60_000;
 /**
  * Per-credential cool-down after a usage fetch fails. While this window is
  * active we serve the last successful value to avoid dropping the credential
- * from the report; without a previous value we just return null and retry
- * on the next poll. Used by UsageService.
+ * from the report; without a previous value we return null until the
+ * cooldown expires. Report invalidation does not bypass this cooldown.
  */
 export const USAGE_FAILURE_BACKOFF_MS = 10_000;
 /**
@@ -118,6 +118,9 @@ export function oauthUsageRequest(
 /** Store-backed usage report cache: keys, epoch, force-refresh markers, invalidation; used by AuthStorage. */
 export class UsageCache {
 	#epoch = 0;
+	#recoveryEpochs: Map<Provider, number> = new Map();
+	#refreshEpochs: Map<Provider, number> = new Map();
+	#allRefreshEpoch = 0;
 	#usageReportCacheKeysByProvider: Map<Provider, Set<string>> = new Map();
 	#store: AuthCredentialStore;
 	#pool: CredentialPool;
@@ -148,6 +151,30 @@ export class UsageCache {
 		this.#epoch += 1;
 	}
 
+	/** Identifies confirmed recoveries that supersede an in-flight failed probe. */
+	recoveryEpoch(provider: Provider): number {
+		return this.#recoveryEpochs.get(provider) ?? 0;
+	}
+
+	/**
+	 * Changes when a user refresh, confirmed reset, or usage-implementation swap
+	 * makes an in-flight probe too old to answer. Block marks do not change it:
+	 * they stop a racing report from being cached, never trigger a re-probe.
+	 */
+	refreshEpoch(provider: Provider): number {
+		return this.#allRefreshEpoch + (this.#refreshEpochs.get(provider) ?? 0);
+	}
+
+	#bumpRefreshEpoch(provider: Provider | undefined): void {
+		if (provider === undefined) this.#allRefreshEpoch += 1;
+		else this.#refreshEpochs.set(provider, (this.#refreshEpochs.get(provider) ?? 0) + 1);
+	}
+
+	/** Failure cooldowns survive report invalidation and process restarts. */
+	failureKey(reportKey: string): string {
+		return `failure:${reportKey}`;
+	}
+
 	get<T>(key: string): UsageCacheEntry<T> | undefined {
 		const raw = this.#store.getCache(`${USAGE_CACHE_PREFIX}${key}`);
 		if (!raw) return undefined;
@@ -275,12 +302,27 @@ export class UsageCache {
 		}
 	}
 
+	/** A confirmed reset permits one fresh probe even during a pre-reset failure cooldown. */
+	invalidateAfterReset(provider: Provider, baseUrl?: string): void {
+		this.#recoveryEpochs.set(provider, this.recoveryEpoch(provider) + 1);
+		this.#bumpRefreshEpoch(provider);
+		if (!this.deletePrefix(`failure:report:${this.#usageCacheProviderKey(provider)}:`)) {
+			const keys = new Set(this.#usageReportCacheKeysByProvider.get(provider));
+			for (const entry of this.#pool.entries(provider)) {
+				keys.add(this.reportKey(usageRequest(provider, buildUsageCredential(entry.credential), baseUrl)));
+			}
+			for (const key of keys) this.set(this.failureKey(key), { value: null, expiresAt: 0 });
+		}
+		this.invalidate(provider, baseUrl);
+	}
+
 	/**
 	 * Expire cached reports for a provider after its runtime usage implementation changes.
 	 * This keeps a newly installed extension provider from serving a built-in snapshot.
 	 */
 	invalidateForProvider(provider: Provider): void {
 		this.#epoch += 1;
+		this.#bumpRefreshEpoch(provider);
 		const expired = Date.now() - 1;
 		const prefix = `report:${this.#usageCacheProviderKey(provider)}:`;
 		if (this.deletePrefix(prefix)) return;
@@ -308,6 +350,7 @@ export class UsageCache {
 		collectRequests: () => Promise<UsageRequestDescriptor[]>,
 	): Promise<void> {
 		this.#epoch += 1;
+		this.#bumpRefreshEpoch(provider);
 		const prefix = provider ? `report:${this.#usageCacheProviderKey(provider)}:` : "report:";
 		if (!this.deletePrefix(prefix)) {
 			// Third-party stores may not support prefix deletion. Clear every active

package/src/auth/usage.ts

@@ -108,7 +108,8 @@ export class UsageService implements UsageApi {
 	#deps: UsageServiceDeps;
 	/** Runtime extension providers take precedence over the configured/default resolver. */
 	#runtimeUsageProviderOverrides: Map<Provider, { provider: UsageProvider; apiKey?: string }> = new Map();
-	#usageRequestInFlight: Map<string, Promise<UsageReport | null>> = new Map();
+	/** One probe per credential report key, tagged with the refresh epoch it can answer. */
+	#usageRequestInFlight: Map<string, { refreshEpoch: number; promise: Promise<UsageReport | null> }> = new Map();
 	#usageHeaderIngestAt: Map<string, number> = new Map();
 	#usageReportsInFlight: Map<string, Promise<UsageReport[] | null>> = new Map();
 	readonly fetch: typeof fetch;
@@ -305,28 +306,46 @@ export class UsageService implements UsageApi {
 	/** Cache a credential report with jitter and failure cooldown. */
 	async #fetchUsageCached(
 		request: UsageRequestDescriptor,
-		options: { timeoutMs?: number; forceRefresh?: boolean } = {},
+		options: { timeoutMs?: number } = {},
 	): Promise<UsageReport | null> {
 		const timeoutMs = options.timeoutMs;
-		const forceRefresh = options.forceRefresh ?? false;
 		const cacheKey = this.#deps.cache.reportKey(request);
-
+		const failureKey = this.#deps.cache.failureKey(cacheKey);
 		const now = Date.now();
-		const cached = forceRefresh ? undefined : this.#deps.cache.get<UsageReport | null>(cacheKey);
+		const cached = this.#deps.cache.get<UsageReport | null>(cacheKey);
 		// Fresh cache hit: return whatever's there (success or null fallback).
 		if (cached && cached.expiresAt > now) {
 			return cached.value;
 		}
 
+		const failure = this.#deps.cache.get<null>(failureKey);
+		if (failure && failure.expiresAt > now) {
+			return this.#deps.cache.getStale<UsageReport | null>(cacheKey)?.value ?? null;
+		}
+
+		// Invalidation must not fork an already-running credential probe. Share it;
+		// only a refresh that postdates its start (user refresh, confirmed reset)
+		// earns one successor probe.
+		const inFlight = this.#usageRequestInFlight.get(cacheKey);
+		if (inFlight) {
+			const report = await inFlight.promise;
+			return inFlight.refreshEpoch === this.#deps.cache.refreshEpoch(request.provider)
+				? report
+				: this.#fetchUsageCached(request, options);
+		}
 		const usageCacheEpoch = this.#deps.cache.epoch;
-		const inFlightKey = `${cacheKey}\0${usageCacheEpoch}`;
-		const inFlight = this.#usageRequestInFlight.get(inFlightKey);
-		if (inFlight) return inFlight;
+		const refreshEpoch = this.#deps.cache.refreshEpoch(request.provider);
+		const recoveryEpoch = this.#deps.cache.recoveryEpoch(request.provider);
 		const promise = (async () => {
 			const report = await this.#fetchUsageUncached(request, timeoutMs);
-			if (usageCacheEpoch !== this.#deps.cache.epoch) return report;
-			const ttlJitter = USAGE_REPORT_TTL_MS * (Math.random() * 0.5 - 0.25);
+			// Block marks bump the generation too: a report racing a fresh 429 may
+			// predate it, so it answers this probe but is neither cached nor used
+			// to heal blocks.
+			const invalidated = usageCacheEpoch !== this.#deps.cache.epoch;
 			if (report !== null) {
+				if (invalidated) return report;
+				this.#deps.blocks.reconcileRequest(request, report);
+				const ttlJitter = USAGE_REPORT_TTL_MS * (Math.random() * 0.5 - 0.25);
 				// Success: stagger per-credential cache expiry so all accounts don't
 				// refresh in the same window — Anthropic / OpenAI rate-limit `/usage`
 				// per source IP regardless of account, and synchronized 5-credential
@@ -337,7 +356,6 @@ export class UsageService implements UsageApi {
 					expiresAt: Date.now() + USAGE_REPORT_TTL_MS + ttlJitter,
 				});
 				this.#recordUsageHistory(request, report);
-				this.#deps.blocks.reconcileRequest(request, report);
 				return report;
 			}
 			// Failure: apply a short jittered cool-down so the credential doesn't
@@ -345,21 +363,31 @@ export class UsageService implements UsageApi {
 			// value through transient failures. Session-cookie providers can opt out
 			// so an expired login does not display stale quota indefinitely.
 			const providerImpl = this.providerFor(request.provider);
-			const retainLastGood = !forceRefresh && providerImpl?.retainLastGoodOnFailure !== false;
+			const retainLastGood = !invalidated && providerImpl?.retainLastGoodOnFailure !== false;
 			const lastGood = retainLastGood
 				? (this.#deps.cache.getStale<UsageReport | null>(cacheKey)?.value ?? null)
 				: null;
 			const failureBackoffMs = providerImpl?.failureBackoffMs ?? USAGE_FAILURE_BACKOFF_MS;
 			const backoffJitter = failureBackoffMs * (Math.random() * 0.5 - 0.25);
 			const coolDown = Date.now() + failureBackoffMs + backoffJitter;
-			this.#deps.cache.set(cacheKey, { value: lastGood, expiresAt: coolDown });
+			// Dropping snapshots is not recovery from a failed endpoint. Persist its
+			// cooldown even if a manual refresh or block update raced this probe.
+			// A confirmed reset is the exception: the old failure cannot suppress
+			// the first post-reset probe.
+			if (recoveryEpoch === this.#deps.cache.recoveryEpoch(request.provider)) {
+				this.#deps.cache.set(failureKey, { value: null, expiresAt: coolDown });
+			}
+			if (!invalidated) this.#deps.cache.set(cacheKey, { value: lastGood, expiresAt: coolDown });
 			return lastGood;
 		})().finally(() => {
-			this.#usageRequestInFlight.delete(inFlightKey);
+			this.#usageRequestInFlight.delete(cacheKey);
 		});
 
-		this.#usageRequestInFlight.set(inFlightKey, promise);
-		return promise;
+		this.#usageRequestInFlight.set(cacheKey, { refreshEpoch, promise });
+		const report = await promise;
+		return refreshEpoch === this.#deps.cache.refreshEpoch(request.provider)
+			? report
+			: this.#fetchUsageCached(request, options);
 	}
 
 	/**
@@ -690,8 +718,7 @@ export class UsageService implements UsageApi {
 		const tails = new Map<Provider, Promise<void>>();
 		return Promise.all(
 			requests.map(request => {
-				const forceRefresh = serializedProviders.has(request.provider);
-				if (!forceRefresh) {
+				if (!serializedProviders.has(request.provider)) {
 					return this.#fetchUsageCached(request, {
 						timeoutMs: this.requestTimeoutMs,
 					});
@@ -700,7 +727,6 @@ export class UsageService implements UsageApi {
 				const current = tail.then(() =>
 					this.#fetchUsageCached(request, {
 						timeoutMs: this.requestTimeoutMs,
-						forceRefresh: true,
 					}),
 				);
 				tails.set(
@@ -757,10 +783,11 @@ export class UsageService implements UsageApi {
 		// accounts can be missing from one fetch and present in the next; the
 		// aggregate cache freezes whichever set landed first).
 		const forcedRefresh = this.#deps.cache.forcedRefresh(requests);
-		const cacheKey = `${this.#deps.cache.reportsKey(requests)}\0${this.#deps.cache.epoch}`;
+		const usageCacheEpoch = this.#deps.cache.epoch;
+		const cacheKey = `${this.#deps.cache.reportsKey(requests)}\0${usageCacheEpoch}`;
 
 		const inFlight = this.#usageReportsInFlight.get(cacheKey);
-		if (inFlight) return inFlight;
+		if (inFlight) return raceSignal(inFlight, options?.signal, "usage fetch aborted");
 
 		const promise = (async () => {
 			for (const request of requests) {
@@ -794,20 +821,20 @@ export class UsageService implements UsageApi {
 					};
 				}),
 			});
-			this.#deps.cache.clearForceRefresh(forcedRefresh);
+			if (usageCacheEpoch === this.#deps.cache.epoch) this.#deps.cache.clearForceRefresh(forcedRefresh);
 			return resolved;
 		})().finally(() => {
 			this.#usageReportsInFlight.delete(cacheKey);
 		});
 
 		this.#usageReportsInFlight.set(cacheKey, promise);
-		return promise;
+		return raceSignal(promise, options?.signal, "usage fetch aborted");
 	}
 
 	/**
 	 * Discard cached usage reports before a user-requested refresh. The next
-	 * read probes upstream serially per provider; a failure reports no fresh
-	 * usage instead of replaying an invalidated last-good snapshot.
+	 * read probes upstream serially per provider unless a failure cooldown is
+	 * active. Failed probes never replay an invalidated last-good snapshot.
 	 */
 	async invalidate(provider?: string, signal?: AbortSignal): Promise<void> {
 		await this.#deps.cache.clearReports(provider, () => this.#collectUsageRequests());

package/src/auth-broker/client.ts

@@ -13,6 +13,7 @@ import type {
 	ClientUsageReportRequest,
 	ClientUsageReportResponse,
 	ClientUsageSummaryResponse,
+	CredentialBlockDeleteRequest,
 	CredentialBlockRequest,
 	CredentialBlockResponse,
 	CredentialBlocksDeleteResponse,
@@ -389,6 +390,18 @@ export class AuthBrokerClient {
 		});
 	}
 
+	async deleteCredentialBlock(
+		id: number,
+		block: CredentialBlockDeleteRequest,
+		signal?: AbortSignal,
+	): Promise<CredentialBlocksDeleteResponse> {
+		return this.#request<CredentialBlocksDeleteResponse>("DELETE", `/v1/credential/${id}/block`, {
+			body: block,
+			schema: "credentialBlocksDeleteResponseSchema",
+			signal,
+		});
+	}
+
 	async deleteCredentialBlocks(id: number, signal?: AbortSignal): Promise<CredentialBlocksDeleteResponse> {
 		return this.#request<CredentialBlocksDeleteResponse>("DELETE", `/v1/credential/${id}/blocks`, {
 			schema: "credentialBlocksDeleteResponseSchema",