@oh-my-pi/pi-ai 18.7.0 → 18.8.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [18.8.0] - 2026-10-07
+
+### Breaking Changes
+
+- The environment API-key helpers (`getEnvApiKey`, `getEnvApiKeyName`, and `listProvidersWithEnvKey`) are no longer exported from `@oh-my-pi/pi-ai/stream`; import them from `@oh-my-pi/pi-ai` or `@oh-my-pi/pi-ai/env-api-key` instead.
+- `TranscriptionRequest.audio` now accepts `Uint8Array | Blob`. Consumers must handle `Blob` values when reading transcription requests.
+
+### Changed
+
+- Improved CPU and memory efficiency across streamed model responses, including Cursor, Devin, Codex, OpenAI Responses, and GitLab Duo Workflow.
+- Improved request and authentication performance, including account ranking, OAuth preflight, credential rate-limit checks, credential synchronization, and auth gateway requests.
+- Improved tool-call parsing performance for long calls and Apple Foundation Models requests.
+- Improved Cloudflare AI Gateway request performance and AWS credential-source detection.
+- Reduced memory usage when handling generated images and usage reports.
+
+### Fixed
+
+- Fixed false thinking-loop detections for Gemini, DeepSeek, and Grok when responses contain repetitive code or markup such as VRML, SVG, or JSON; valid output is no longer discarded and retried.
+- Fixed the Cursor provider retaining request resources after requests completed.
+- Fixed session-affinity pins growing without bound in long-lived gateways; pins are now capped at 256 sessions per provider.
+- Fixed Anthropic sessions failing every request with HTTP 400 ("role 'system' must precede an 'assistant' message") after a tool change coincided with compaction or an interrupted or failed reply; sessions already stuck this way recover on the next message ([#14746](https://github.com/can1357/oh-my-pi/issues/14746)).
+
 ## [18.7.0] - 2026-10-06
 
 ### Added

package/dist/types/auth/sqlite-credential-store.d.ts

@@ -60,6 +60,7 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     deleteCachePrefix(prefix: string): void;
     cleanExpiredCache(): void;
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    getCredentialBlockScopes(credentialId: number, providerKey: string): Map<string, number>;
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     upsertCredentialBlock(block: StoredCredentialBlock): void;
     deleteCredentialBlock(credentialId: number, providerKey: string, blockScope: string): void;

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

@@ -71,6 +71,12 @@ export interface CredentialCacheStore {
 export interface CredentialBlockStore {
     /** Non-expired block for one (credential, providerKey, scope) key, or undefined. */
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    /**
+     * Non-expired blocks for one credential and providerKey, keyed by block
+     * scope (`""` is unscoped), in one read. Optional: selectors fall back to
+     * {@link CredentialBlockStore.getCredentialBlock} per scope when absent.
+     */
+    getCredentialBlockScopes?(credentialId: number, providerKey: string): ReadonlyMap<string, number>;
     /** Earliest time a shared-store block should be eligible for live-usage reconciliation. */
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     /** Upsert with MAX semantics: keep the later blockedUntilMs on conflict. */

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

@@ -73,6 +73,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     /** Broker-backed disabled tombstones; empty against brokers predating the endpoint. */
     listDisabledCredentials(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]>;
     getCredentialBlock(credentialId: number, providerKey: string, blockScope: string): number | undefined;
+    getCredentialBlockScopes(credentialId: number, providerKey: string): Map<string, number>;
     getCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number | undefined;
     listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[];
     upsertCredentialBlock(block: StoredCredentialBlock): void;

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

@@ -15,3 +15,15 @@ export interface WriteAuthBrokerSnapshotCacheOptions {
 }
 export declare function readAuthBrokerSnapshotCache(opts: ReadAuthBrokerSnapshotCacheOptions): Promise<SnapshotResponse | null>;
 export declare function writeAuthBrokerSnapshotCache(opts: WriteAuthBrokerSnapshotCacheOptions): Promise<void>;
+/**
+ * Fire-and-forget cache write for snapshot callbacks. The first snapshot after
+ * a quiet period is written immediately; later ones within
+ * {@link WRITE_COALESCE_MS} collapse into a single trailing write of the
+ * newest. A snapshot whose generation and credential content match the last
+ * write is skipped (see {@link UNCHANGED_REWRITE_MS}). Pending writes are
+ * flushed on process shutdown and by {@link flushAuthBrokerSnapshotCacheWrites};
+ * failures are logged, never thrown.
+ */
+export declare function scheduleAuthBrokerSnapshotCacheWrite(opts: WriteAuthBrokerSnapshotCacheOptions): void;
+/** Write every pending scheduled snapshot now and wait for in-flight writes to settle. */
+export declare function flushAuthBrokerSnapshotCacheWrites(): Promise<void>;

package/dist/types/auth-gateway/session-state.d.ts

@@ -63,6 +63,12 @@ export interface AuthGatewaySessionStateRequest {
      * continues.
      */
     context: Context;
+    /**
+     * `JSON.stringify(context.tools)` when the caller already serialized it
+     * (the gateway derives its `sessionId` from the same string). Recomputed
+     * from `context` when absent.
+     */
+    toolsJson?: string;
     /**
      * Stable identity of the account this request's credential resolved to.
      * A change means the gateway switched the session to a sibling credential,

package/dist/types/dialect/terminator-wait.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Fast path for in-band scanners that sit inside a body waiting for one fixed
+ * terminator (a tool-call close tag) and emit nothing until it arrives.
+ *
+ * Appending each delta to the scanner's string buffer and calling `indexOf` on
+ * it flattens the growing rope on every delta, so a long in-band tool call cost
+ * O(n²) copying and scanning. While armed, deltas are set aside and only the new
+ * text plus the terminator-length overlap with what came before is searched;
+ * the buffer is rebuilt once, when the terminator shows up or the stream ends.
+ */
+export declare class TerminatorWait {
+    #private;
+    /** Start deferring; `buffered` is the scanner's pending body, known not to contain `terminator`. */
+    arm(terminator: string, buffered: string): void;
+    /** Take `text` while the terminator is still absent; false means the caller must {@link release} and scan. */
+    absorb(text: string): boolean;
+    /** Stop deferring and return `buffered` with every absorbed delta appended. */
+    release(buffered: string): string;
+}

package/dist/types/env-api-key.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
+ *
+ * Will not return API keys for providers that require OAuth tokens.
+ * Checks Bun.env, then cwd/.env, then ~/.env.
+ */
+export declare function getEnvApiKey(provider: string): string | undefined;
+/**
+ * Name of the environment variable that backs `getEnvApiKey` for a provider,
+ * when that provider maps to a single named variable (e.g. `github-copilot` →
+ * `COPILOT_GITHUB_TOKEN`). Returns undefined for providers whose env fallback
+ * is computed (multi-var pickers, Vertex ADC / Bedrock probes, …) since no
+ * single variable name describes the source.
+ */
+export declare function getEnvApiKeyName(provider: string): string | undefined;
+/**
+ * Enumerate every provider that has an env-var fallback for `getEnvApiKey`.
+ * Used by `omp auth-broker migrate --include-env` to discover env-sourced keys
+ * that should be uploaded to the broker.
+ */
+export declare function listProvidersWithEnvKey(): string[];

package/dist/types/images/shared.d.ts

@@ -32,6 +32,12 @@ export declare function decodeImageResponse(value: unknown, fetch: FetchImpl, si
     images: GeneratedImage[];
     usage: Usage;
 }>;
+/**
+ * Mime type of a base64 image, read from its header only. 64 base64 chars
+ * decode to 48 bytes, past every magic number `parseImageMetadata` checks, so
+ * multi-MB payloads are never fully decoded just to be labelled.
+ */
+export declare function sniffBase64ImageMimeType(base64: string): string | undefined;
 export declare function toDataUrl(image: GeneratedImage): string;
 export declare function resolveOpenAIImageSize(aspectRatio?: string, imageSize?: string): string | undefined;
 export {};

package/dist/types/index.d.ts

@@ -39,6 +39,7 @@ export type * from "./providers/openai-responses.js";
 export type * from "./providers/synthetic.js";
 export * from "./registry/index.js";
 export { resolveCacheRetention } from "./utils.js";
+export * from "./env-api-key.js";
 export * from "./stream.js";
 export * from "./types.js";
 export * from "./usage.js";

package/dist/types/providers/connect-frame.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Connect-protocol streaming envelope shared by the Cursor and Devin
+ * transports: 1 flag byte + 4-byte big-endian payload length + payload.
+ */
+/** Flag bit: payload is compressed with the negotiated encoding (gzip). */
+export declare const CONNECT_COMPRESSED_FLAG = 1;
+/** Flag bit: payload is the end-of-stream JSON trailer. */
+export declare const CONNECT_END_STREAM_FLAG = 2;
+/** Wrap one Connect-protocol message: 1 flag byte + 4-byte big-endian length + payload. */
+export declare function frameConnectMessage(data: Uint8Array, flags?: number): Buffer;
+/** One decoded Connect envelope. */
+export interface ConnectFrame {
+    flags: number;
+    payload: Buffer;
+}
+/** Options for {@link ConnectFrameDecoder}. */
+export interface ConnectFrameDecoderOptions {
+    /**
+     * Payload cap: a length prefix above `maxPayloadBytes` throws `error(length)`
+     * before any of that payload is buffered. Uncapped when omitted.
+     */
+    limit?: {
+        maxPayloadBytes: number;
+        error: (length: number) => Error;
+    };
+}
+/**
+ * Incremental Connect frame decoder. Incoming chunks are kept as-is and a frame
+ * spanning several chunks is joined once, when the length the header announced
+ * has fully arrived — re-concatenating the pending bytes on every chunk made a
+ * multi-MB frame cost O(size × chunks).
+ *
+ * Payloads alias the chunk they came from whenever a frame fits in one chunk,
+ * so callers must not reuse chunk buffers they hand in.
+ */
+export declare class ConnectFrameDecoder {
+    #private;
+    constructor(options?: ConnectFrameDecoderOptions);
+    /**
+     * Buffer `chunk` (if any) and yield every frame now complete, in wire order.
+     * An oversize length prefix throws after the frames that precede it.
+     */
+    decode(chunk?: Uint8Array): Generator<ConnectFrame, void, undefined>;
+}

package/dist/types/providers/cursor/interaction-query.d.ts

@@ -7,8 +7,6 @@ type ProtoUnknownField = {
 interface CursorInteractionWriter {
     write(frame: Uint8Array): void;
 }
-/** Wrap one Connect-protocol message: 1 flag byte + 4-byte big-endian length + payload. */
-export declare function frameConnectMessage(data: Uint8Array, flags?: number): Buffer;
 /** Well-formed protobuf-es `$unknown` entries on `message`; anything else on the bag is ignored. */
 export declare function protoUnknownFields(message: object): ProtoUnknownField[];
 /**

package/dist/types/stream.d.ts

@@ -31,27 +31,6 @@ export declare const __providerInFlightForTesting: {
     captureStaleLockRelease(provider: string): Promise<(() => Promise<void>) | null>;
     captureLockDirRelease(provider: string): Promise<(() => Promise<void>) | null>;
 };
-/**
- * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
- *
- * Will not return API keys for providers that require OAuth tokens.
- * Checks Bun.env, then cwd/.env, then ~/.env.
- */
-export declare function getEnvApiKey(provider: string): string | undefined;
-/**
- * Name of the environment variable that backs `getEnvApiKey` for a provider,
- * when that provider maps to a single named variable (e.g. `github-copilot` →
- * `COPILOT_GITHUB_TOKEN`). Returns undefined for providers whose env fallback
- * is computed (multi-var pickers, Vertex ADC / Bedrock probes, …) since no
- * single variable name describes the source.
- */
-export declare function getEnvApiKeyName(provider: string): string | undefined;
-/**
- * Enumerate every provider that has an env-var fallback for `getEnvApiKey`.
- * Used by `omp auth-broker migrate --include-env` to discover env-sourced keys
- * that should be uploaded to the broker.
- */
-export declare function listProvidersWithEnvKey(): string[];
 export declare function stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>): AssistantMessageEventStream;
 export declare function complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>): Promise<AssistantMessage>;
 export declare function streamSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;

package/dist/types/transcription/types.d.ts

@@ -2,7 +2,8 @@ import type { Usage } from "@oh-my-pi/pi-catalog/types";
 export type TranscriptionResponseFormat = "json" | "verbose_json";
 export type TranscriptionTimestampGranularity = "word" | "segment";
 export interface TranscriptionRequest {
-    audio: Uint8Array;
+    /** Audio bytes. A `Blob`/`File` (e.g. a parsed multipart upload) is sent without copying. */
+    audio: Uint8Array | Blob;
     mimeType: string;
     fileName?: string;
     language?: string;

package/dist/types/utils/aws-profile.d.ts

@@ -9,6 +9,11 @@ export declare function resolveAwsProfile(profile?: string): string;
  * the AWS SDK's `AWS_SDK_LOAD_CONFIG` opt-in.
  */
 export declare function shouldLoadAwsSharedConfig(profile?: string): boolean;
+/** Shared credentials and config file locations, honoring their env overrides. */
+export declare function awsSharedFilePaths(): {
+    credentialsPath: string;
+    configPath: string;
+};
 export declare function resolveAwsProfileRegion(profile?: string): string | undefined;
 /** Region selected by the environment or active shared-config profile. */
 export declare function resolveAwsAmbientRegion(profile?: string): string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.7.0",
+	"version": "18.8.0",
 	"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.7.0",
-		"@oh-my-pi/pi-catalog": "18.7.0",
-		"@oh-my-pi/pi-natives": "18.7.0",
-		"@oh-my-pi/pi-utils": "18.7.0",
-		"@oh-my-pi/pi-wire": "18.7.0"
+		"@oh-my-pi/omptype": "18.8.0",
+		"@oh-my-pi/pi-catalog": "18.8.0",
+		"@oh-my-pi/pi-natives": "18.8.0",
+		"@oh-my-pi/pi-utils": "18.8.0",
+		"@oh-my-pi/pi-wire": "18.8.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth/affinity.ts

@@ -1,5 +1,6 @@
 import { logger } from "@oh-my-pi/pi-utils";
-import { getEnvApiKey } from "../stream";
+import { LRUCache } from "@oh-my-pi/pi-utils/lru";
+import { getEnvApiKey } from "../env-api-key";
 import type { AuthCredential, OAuthCredential, SessionsApi } from "./types";
 import type { AuthCredentialStore } from "./store";
 import type { CredentialPool } from "./pool";
@@ -14,6 +15,11 @@ const SESSION_STICKY_TTL_SEC = 30 * 24 * 60 * 60;
  * in-memory sticky stays exact; only the copy other processes resume from lags.
  */
 const SESSION_STICKY_PERSIST_INTERVAL_MS = 60_000;
+/**
+ * In-memory pins kept per provider. Long-lived gateways mint a session id per
+ * conversation; evicted sessions resume from their persisted sticky row.
+ */
+const SESSION_AFFINITY_MAX_SESSIONS_PER_PROVIDER = 256;
 
 /** What this process last wrote (or read) for one persisted sticky row. */
 type PersistedSticky = {
@@ -36,9 +42,9 @@ export type SessionCredential = {
 /** Session → credential affinity (pins), persisted in the store cache. */
 export class SessionAffinity implements SessionsApi {
 	/** Tracks the last used credential per provider for a session (used for rate-limit switching). */
-	#sessionLastCredential: Map<string, Map<string, SessionCredential>> = new Map();
-	/** Persisted sticky rows keyed by cache key, so unchanged re-records skip the write. */
-	#persistedSticky: Map<string, PersistedSticky> = new Map();
+	#sessionLastCredential: Map<string, LRUCache<string, SessionCredential>> = new Map();
+	/** Persisted sticky rows per provider, keyed by session id, so unchanged re-records skip the write. */
+	#persistedSticky: Map<string, LRUCache<string, PersistedSticky>> = new Map();
 	#store: AuthCredentialStore;
 	#pool: CredentialPool;
 	#overrides: KeyOverrides;
@@ -49,13 +55,21 @@ export class SessionAffinity implements SessionsApi {
 		this.#overrides = overrides;
 	}
 
+	/** Bounded per-provider session map, created on first use. */
+	static #sessionsFor<V>(maps: Map<string, LRUCache<string, V>>, provider: string): LRUCache<string, V> {
+		let sessions = maps.get(provider);
+		if (!sessions) {
+			sessions = new LRUCache<string, V>({ max: SESSION_AFFINITY_MAX_SESSIONS_PER_PROVIDER });
+			maps.set(provider, sessions);
+		}
+		return sessions;
+	}
+
 	/** Drop every pin for a provider, both in memory and in the persisted cache. */
 	clearProvider(provider: string): void {
 		this.#sessionLastCredential.delete(provider);
+		this.#persistedSticky.delete(provider);
 		const prefix = `${SESSION_STICKY_CACHE_PREFIX}${provider}:`;
-		for (const cacheKey of this.#persistedSticky.keys()) {
-			if (cacheKey.startsWith(prefix)) this.#persistedSticky.delete(cacheKey);
-		}
 		try {
 			this.#store.deleteCachePrefix?.(prefix);
 		} catch (err) {
@@ -90,7 +104,7 @@ export class SessionAffinity implements SessionsApi {
 		if (!sessionId) return;
 		const nowMs = lastUsedAtMs ?? Date.now();
 		const credentialId = this.#pool.entries(provider)[index]?.id;
-		const sessionMap = this.#sessionLastCredential.get(provider) ?? new Map();
+		const sessionMap = SessionAffinity.#sessionsFor(this.#sessionLastCredential, provider);
 		const previous = sessionMap.get(sessionId);
 		const sameCredential =
 			previous?.type === type &&
@@ -104,12 +118,12 @@ export class SessionAffinity implements SessionsApi {
 			...(isExplicit ? { explicit: true as const } : {}),
 		};
 		sessionMap.set(sessionId, sessionCredential);
-		this.#sessionLastCredential.set(provider, sessionMap);
 
 		if (credentialId === undefined) return;
 		const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
 		const expiresAtSec = Math.floor(nowMs / 1000) + SESSION_STICKY_TTL_SEC;
-		const persisted = this.#persistedSticky.get(cacheKey);
+		const persistedSessions = SessionAffinity.#sessionsFor(this.#persistedSticky, provider);
+		const persisted = persistedSessions.get(sessionId);
 		if (
 			persisted &&
 			persisted.type === type &&
@@ -121,14 +135,14 @@ export class SessionAffinity implements SessionsApi {
 		}
 		try {
 			this.#store.setCache(cacheKey, JSON.stringify(sessionCredential), expiresAtSec);
-			this.#persistedSticky.set(cacheKey, {
+			persistedSessions.set(sessionId, {
 				type,
 				credentialId,
 				explicit: isExplicit,
 				lastUsedAtMs: nowMs,
 			});
 		} catch (err) {
-			this.#persistedSticky.delete(cacheKey);
+			persistedSessions.delete(sessionId);
 			logger.debug("Failed to write session sticky credential to persistent store cache", { err });
 		}
 	}
@@ -136,8 +150,7 @@ export class SessionAffinity implements SessionsApi {
 	/** Retrieves the last credential used by a session. */
 	get(provider: string, sessionId: string | undefined): SessionCredential | undefined {
 		if (!sessionId) return undefined;
-		let sessionMap = this.#sessionLastCredential.get(provider);
-		const live = sessionMap?.get(sessionId);
+		const live = this.#sessionLastCredential.get(provider)?.get(sessionId);
 		if (live) {
 			// Another process can add or drop rows mid-session and the pool is an
 			// index-ordered snapshot, so re-resolve the pin through its durable row
@@ -147,7 +160,7 @@ export class SessionAffinity implements SessionsApi {
 			const stored = this.#pool.entries(provider);
 			const actualIndex = stored.findIndex(entry => entry.id === live.credentialId);
 			if (actualIndex === -1 || stored[actualIndex]?.credential.type !== live.type) {
-				sessionMap?.delete(sessionId);
+				this.#sessionLastCredential.get(provider)?.delete(sessionId);
 				return undefined;
 			}
 			live.index = actualIndex;
@@ -163,22 +176,18 @@ export class SessionAffinity implements SessionsApi {
 					const stored = this.#pool.entries(provider);
 					const actualIndex = stored.findIndex(entry => entry.id === val.credentialId);
 					if (actualIndex === -1 || stored[actualIndex]?.credential.type !== val.type) {
-						this.#persistedSticky.delete(cacheKey);
+						this.#persistedSticky.get(provider)?.delete(sessionId);
 						this.#store.setCache(cacheKey, "", 0);
 						return undefined;
 					}
 					val.index = actualIndex;
 				} else {
 					// Fallback: drop unsafe index-only cache rows to prevent wrong-account routing
-					this.#persistedSticky.delete(cacheKey);
+					this.#persistedSticky.get(provider)?.delete(sessionId);
 					this.#store.setCache(cacheKey, "", 0);
 					return undefined;
 				}
 
-				if (!sessionMap) {
-					sessionMap = new Map();
-					this.#sessionLastCredential.set(provider, sessionMap);
-				}
 				const sessionVal: SessionCredential = {
 					type: val.type,
 					index: val.index,
@@ -187,14 +196,14 @@ export class SessionAffinity implements SessionsApi {
 					...(val.explicit === true ? { explicit: true } : {}),
 				};
 				if (typeof val.lastUsedAtMs === "number") {
-					this.#persistedSticky.set(cacheKey, {
+					SessionAffinity.#sessionsFor(this.#persistedSticky, provider).set(sessionId, {
 						type: val.type,
 						credentialId: val.credentialId,
 						explicit: val.explicit === true,
 						lastUsedAtMs: val.lastUsedAtMs,
 					});
 				}
-				sessionMap.set(sessionId, sessionVal);
+				SessionAffinity.#sessionsFor(this.#sessionLastCredential, provider).set(sessionId, sessionVal);
 				return sessionVal;
 			}
 		} catch (err) {
@@ -214,7 +223,7 @@ export class SessionAffinity implements SessionsApi {
 			}
 		}
 		const cacheKey = `${SESSION_STICKY_CACHE_PREFIX}${provider}:${sessionId}`;
-		this.#persistedSticky.delete(cacheKey);
+		this.#persistedSticky.get(provider)?.delete(sessionId);
 		try {
 			this.#store.setCache(cacheKey, "", 0);
 		} catch (err) {

package/src/auth/blocks.ts

@@ -64,6 +64,14 @@ export function credentialBlockScopesForRequest(
  */
 type CredentialBackoff = { until: number; timed: boolean; probeAfter: number; persisted?: boolean };
 
+/**
+ * One read of a credential's persisted blocks under a providerKey, keyed by
+ * scope (`""` is unscoped). `undefined`: the store has no bulk read, so use
+ * per-scope point reads. `null`: unreadable (damaged store or failed read), so
+ * it neither contributes deadlines nor retires mirrored in-memory blocks.
+ */
+type PersistedBlockScopes = ReadonlyMap<string, number> | null | undefined;
+
 /** Latch for unrecoverably corrupt persisted block stores, shared with the credential pool. */
 export class BlockStoreHealth {
 	readonly #sourceLabel: string | undefined;
@@ -134,8 +142,16 @@ export class CredentialBlocks implements BlocksApi {
 		}
 	}
 
-	/** Returns in-memory block expiry timestamp for a credential/key pair, cleaning up expired entries. */
-	#getCredentialBlockedUntilForKey(backoffKey: string, credentialId: number, nowMs: number): number | undefined {
+	/**
+	 * Returns in-memory block expiry timestamp for a credential/key pair, cleaning up expired entries.
+	 * `persistedScopes` is a bulk read for the key's providerKey; omitted, the store is point-read.
+	 */
+	#getCredentialBlockedUntilForKey(
+		backoffKey: string,
+		credentialId: number,
+		nowMs: number,
+		persistedScopes: PersistedBlockScopes = undefined,
+	): number | undefined {
 		const block = this.#credentialBackoff.get(backoffKey)?.get(credentialId);
 		if (!block) return undefined;
 		// Once mirrored successfully, the store is authoritative for cross-process
@@ -143,12 +159,19 @@ export class CredentialBlocks implements BlocksApi {
 		// Upserts are longest-wins, so a persisted row shorter than the deadline this
 		// process mirrored means the row was deleted and replaced: the old deadline
 		// was superseded and must not win the next longest-wins merge.
-		if (block.persisted && !this.#deps.health.damaged && this.#deps.store.getCredentialBlock) {
+		if (
+			block.persisted &&
+			!this.#deps.health.damaged &&
+			persistedScopes !== null &&
+			(persistedScopes !== undefined || this.#deps.store.getCredentialBlock)
+		) {
 			const separator = backoffKey.indexOf("\0");
 			const providerKey = separator < 0 ? backoffKey : backoffKey.slice(0, separator);
 			const scope = separator < 0 ? "" : backoffKey.slice(separator + 1);
 			try {
-				const persisted = this.#deps.store.getCredentialBlock(credentialId, providerKey, scope);
+				const persisted = persistedScopes
+					? persistedScopes.get(scope)
+					: this.#deps.store.getCredentialBlock?.(credentialId, providerKey, scope);
 				if (persisted === undefined || persisted < block.until) {
 					this.#deleteCredentialBackoff(backoffKey, credentialId);
 					return undefined;
@@ -175,7 +198,9 @@ export class CredentialBlocks implements BlocksApi {
 		credentialId: number,
 		providerKey: string,
 		blockScope: string | undefined,
+		persistedScopes: PersistedBlockScopes = undefined,
 	): number | undefined {
+		if (persistedScopes !== undefined) return persistedScopes?.get(blockScope ?? "");
 		if (this.#deps.health.damaged) return undefined;
 		const getCredentialBlock = this.#deps.store.getCredentialBlock?.bind(this.#deps.store);
 		if (!getCredentialBlock) return undefined;
@@ -193,6 +218,20 @@ export class CredentialBlocks implements BlocksApi {
 		}
 	}
 
+	/** Every persisted scope of one credential/providerKey in a single store read, when supported. */
+	#readPersistedCredentialBlockScopes(credentialId: number, providerKey: string): PersistedBlockScopes {
+		const store = this.#deps.store;
+		if (!store.getCredentialBlockScopes) return undefined;
+		if (this.#deps.health.damaged) return null;
+		try {
+			return store.getCredentialBlockScopes(credentialId, providerKey);
+		} catch (err) {
+			if (this.#deps.health.handle(err)) return null;
+			logger.debug("Failed to read credential blocks from persistent store", { err, credentialId, providerKey });
+			return null;
+		}
+	}
+
 	#readPersistedCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number {
 		if (this.#deps.health.damaged) return 0;
 		const getCredentialBlockReconcileAfter = this.#deps.store.getCredentialBlockReconcileAfter?.bind(
@@ -215,13 +254,19 @@ export class CredentialBlocks implements BlocksApi {
 		}
 	}
 
-	#exactBlockedUntil(credentialId: number, providerKey: string, scope: string | undefined): number | undefined {
+	#exactBlockedUntil(
+		credentialId: number,
+		providerKey: string,
+		scope: string | undefined,
+		persistedScopes: PersistedBlockScopes = this.#readPersistedCredentialBlockScopes(credentialId, providerKey),
+	): number | undefined {
 		const memory = this.#getCredentialBlockedUntilForKey(
 			scopedBackoffKey(providerKey, scope),
 			credentialId,
 			Date.now(),
+			persistedScopes,
 		);
-		const persisted = this.#readPersistedCredentialBlock(credentialId, providerKey, scope);
+		const persisted = this.#readPersistedCredentialBlock(credentialId, providerKey, scope, persistedScopes);
 		return memory === undefined ? persisted : persisted === undefined ? memory : Math.max(memory, persisted);
 	}
 
@@ -231,6 +276,22 @@ export class CredentialBlocks implements BlocksApi {
 		providerKey: string,
 		credentialIndex: number,
 		blockScopeOrScopes: string | readonly string[] | undefined = undefined,
+	): number | undefined {
+		const credentialId = this.#deps.pool.entries(provider)[credentialIndex]?.id;
+		if (credentialId === undefined) return undefined;
+		return this.#blockedUntilById(
+			credentialId,
+			providerKey,
+			blockScopeOrScopes,
+			this.#readPersistedCredentialBlockScopes(credentialId, providerKey),
+		);
+	}
+
+	#blockedUntilById(
+		credentialId: number,
+		providerKey: string,
+		blockScopeOrScopes: string | readonly string[] | undefined,
+		persistedScopes: PersistedBlockScopes,
 	): number | undefined {
 		const nowMs = Date.now();
 		// A request honours its own scope plus any legacy catch-all scope, so a
@@ -239,21 +300,25 @@ export class CredentialBlocks implements BlocksApi {
 			...PROTECTED_BLOCK_SCOPES,
 			...(typeof blockScopeOrScopes === "string" ? [blockScopeOrScopes] : (blockScopeOrScopes ?? [])),
 		].filter(scope => scope.length > 0);
-		const credentialId = this.#deps.pool.entries(provider)[credentialIndex]?.id;
-		if (credentialId === undefined) return undefined;
-		let blockedUntil = this.#getCredentialBlockedUntilForKey(providerKey, credentialId, nowMs);
+		let blockedUntil = this.#getCredentialBlockedUntilForKey(providerKey, credentialId, nowMs, persistedScopes);
 		for (const blockScope of scopes) {
 			const scopedBlockedUntil = this.#getCredentialBlockedUntilForKey(
 				scopedBackoffKey(providerKey, blockScope),
 				credentialId,
 				nowMs,
+				persistedScopes,
 			);
 			if (scopedBlockedUntil !== undefined && (blockedUntil === undefined || scopedBlockedUntil > blockedUntil)) {
 				blockedUntil = scopedBlockedUntil;
 			}
 		}
 
-		const persistedGlobalBlockedUntil = this.#readPersistedCredentialBlock(credentialId, providerKey, "");
+		const persistedGlobalBlockedUntil = this.#readPersistedCredentialBlock(
+			credentialId,
+			providerKey,
+			"",
+			persistedScopes,
+		);
 		if (
 			persistedGlobalBlockedUntil !== undefined &&
 			(blockedUntil === undefined || persistedGlobalBlockedUntil > blockedUntil)
@@ -261,7 +326,12 @@ export class CredentialBlocks implements BlocksApi {
 			blockedUntil = persistedGlobalBlockedUntil;
 		}
 		for (const blockScope of scopes) {
-			const persistedScopedBlockedUntil = this.#readPersistedCredentialBlock(credentialId, providerKey, blockScope);
+			const persistedScopedBlockedUntil = this.#readPersistedCredentialBlock(
+				credentialId,
+				providerKey,
+				blockScope,
+				persistedScopes,
+			);
 			if (
 				persistedScopedBlockedUntil !== undefined &&
 				(blockedUntil === undefined || persistedScopedBlockedUntil > blockedUntil)
@@ -440,14 +510,20 @@ export class CredentialBlocks implements BlocksApi {
 		if (!this.supportsHealing(provider)) return false;
 		const credentialId = this.#deps.pool.entries(provider)[credentialIndex]?.id;
 		if (credentialId === undefined) return false;
-		if (PROTECTED_BLOCK_SCOPES.some(scope => this.#exactBlockedUntil(credentialId, providerKey, scope) !== undefined))
+		// One persisted read serves the protected-scope, global, and requested checks.
+		const persistedScopes = this.#readPersistedCredentialBlockScopes(credentialId, providerKey);
+		if (
+			PROTECTED_BLOCK_SCOPES.some(
+				scope => this.#exactBlockedUntil(credentialId, providerKey, scope, persistedScopes) !== undefined,
+			)
+		)
 			return false;
 		if (
 			!this.#deps.strategies(provider)?.healsGlobalBlocks &&
-			this.blockedUntil(provider, providerKey, credentialIndex) !== undefined
+			this.#blockedUntilById(credentialId, providerKey, undefined, persistedScopes) !== undefined
 		)
 			return false;
-		return this.blockedUntil(provider, providerKey, credentialIndex, blockScopeOrScopes) !== undefined;
+		return this.#blockedUntilById(credentialId, providerKey, blockScopeOrScopes, persistedScopes) !== undefined;
 	}
 
 	/**