@oh-my-pi/pi-ai 17.2.3 → 17.2.5

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [17.2.5] - 2026-08-03
+
+### Changed
+
+- Standardized tool-call examples in `renderToolExamples` and `renderToolInventory` to use Python keyword-argument syntax (`name(key="value")`) across all models, removing the model-specific dialect parameter and the `DialectRenderOptions.example` flag.
+- Updated `renderToolInventory` to render the tool catalog as a unified OpenAI-Harmony-style `## functions` block using TypeScript type declarations and comments, replacing the previous per-tool Markdown sections.
+- Added a `style: "harmony"` option to `jsonSchemaToTypeScript` for generating compact, comma-delimited TypeScript definitions.
+
+### Fixed
+
+- Fixed a session-blocking issue where unescaped Harmony control tokens in replayed assistant responses and tool inputs caused subsequent requests to be rejected with `invalid_prompt` errors.
+- Fixed an issue where Codex Responses dropped native image-generation results from assistant content and replays due to stale `generating` statuses.
+- Fixed Anthropic stream truncation handling where unexpected connection closures were incorrectly treated as clean stops, causing the agent loop to halt silently mid-sentence.
+- Optimized Anthropic prompt caching to prevent unnecessary cache invalidation of the entire system prefix when volatile project footer details (such as current working directory, date, or workspace tree) change.
+
+## [17.2.4] - 2026-08-01
+
+### Fixed
+
+- Fixed Codex WebSocket tool-result turns replaying full history when the preceding tool-call ID required Responses API normalization ([#7279](https://github.com/can1357/oh-my-pi/issues/7279)).
+- Fixed direct Anthropic provider streams ignoring `model.compat.streamIdleTimeoutMs`. Requests dispatched through `streamAnthropic` can now widen the inter-event idle watchdog or set it to `0` to disable that watchdog; caller options and environment overrides retain precedence. Setting the compat value to `0` disables only the inter-event watchdog and leaves the first-event watchdog enabled; wider idle values continue to floor the first-event budget under the existing timeout contract.
+- Fixed OpenRouter DeepSeek models failing structured subagents when the upstream returns an opaque HTTP 400 for a strict yield schema, retrying once without strict tools and remembering the fallback for the provider session ([#7264](https://github.com/can1357/oh-my-pi/issues/7264)).
+- Fixed provider-native Codex compaction streams bypassing WebSocket-first transport selection and SSE transport fallback ([#7198](https://github.com/can1357/oh-my-pi/issues/7198)).
+- Fixed `SqliteAuthCredentialStore.open()` running the `auth_credential_refresh_leases` DDL (`CREATE TABLE`/`CREATE INDEX`) with Bun's default `busy_timeout=0`, before the constructor's `#initializeSchema()` installed the busy handler. Under a concurrent write lock (e.g. WAL recovery on parallel omp startups) the lock-taking DDL failed immediately and, since the error wasn't BUSY-classified, bypassed `open()`'s bounded retry loop. The busy handler is now installed on the connection immediately after it opens, before any lock-taking statement, honoring the issue-#2421 invariant on every entry path. ([#7298](https://github.com/can1357/oh-my-pi/issues/7298))
+- Fixed a corrupt credential store (`agent.db`) silently disabling every persisted rate-limit block. `AuthStorage` caught unrecoverable SQLite errors (`SQLITE_CORRUPT` family / `SQLITE_NOTADB`) from the persisted block read/write paths at `debug` level with no latch, so the broken store was re-queried on every credential evaluation while blocks quietly stopped applying. The first unrecoverable error is now reported once at `error` level with the store location and repair guidance, and every later persisted-block read/write short-circuits for the process lifetime; in-memory backoff still preserves availability ([#7296](https://github.com/can1357/oh-my-pi/issues/7296)).
+
 ## [17.2.3] - 2026-08-01
 
 ### Added

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

@@ -1271,6 +1271,14 @@ export declare class AuthStorage {
  * and `SQLITE_BUSY_TIMEOUT`. All warrant the same backoff-and-retry treatment.
  */
 export declare function isSqliteBusyError(err: unknown): boolean;
+/**
+ * SQLite's unrecoverable-corruption result codes — the `SQLITE_CORRUPT` family
+ * (base plus extended variants like `SQLITE_CORRUPT_VTAB` / `SQLITE_CORRUPT_INDEX`)
+ * and `SQLITE_NOTADB` (the file header is not a database). Unlike
+ * {@link isSqliteBusyError}, these never clear by retrying: the store must be
+ * repaired or replaced, so callers latch and stop touching it.
+ */
+export declare function isSqliteCorruptionError(err: unknown): boolean;
 /**
  * Default SQLite-backed implementation of {@link AuthCredentialStore}.
  *

package/dist/types/dialect/examples.d.ts

@@ -1,2 +1,10 @@
-import type { Dialect, InbandTool } from "./types.js";
-export declare function renderToolExamples(tool: InbandTool, dialect: Dialect, intentField?: string): string;
+import type { InbandTool } from "./types.js";
+/**
+ * Render a tool's examples as an `<examples>` block. Calls render in Python
+ * keyword-argument syntax (`name(key="value", n=1)`) regardless of the model's
+ * tool-call dialect, so example bytes stay identical across models. Multiline
+ * string args render as verbatim `"""…"""` blocks, and a call whose only
+ * argument is a string renders as the bare value — the block already names the
+ * tool, and payload args (commands, code, patches) read best verbatim.
+ */
+export declare function renderToolExamples(tool: InbandTool, intentField?: string): string;

package/dist/types/dialect/inventory.d.ts

@@ -1,12 +1,9 @@
 import type { InbandTool } from "./types.js";
 /**
- * Human-readable per-tool inventory: each tool renders as a `# Tool: <name>`
- * section with its description, a simplified TypeScript-style parameter
- * signature (derived from the wire JSON Schema), and examples in the model's
- * native dialect. Shared by the verbose system-prompt inventory and
- * `/dump` so both render the catalog the same way.
- *
- * `model` is a model id; the native example dialect is resolved from it
- * (`preferredDialect`, which falls back to XML for empty/unknown ids).
+ * Tool catalog in the OpenAI-Harmony `namespace functions { … }` shape: each
+ * tool renders as its full description (and Python-syntax examples) as `//`
+ * comment lines above a flat `type <name> = (_: {…});` declaration. Shared by
+ * the verbose system-prompt inventory and `/dump` so both render the catalog
+ * the same way.
  */
-export declare function renderToolInventory(tools: readonly InbandTool[], model: string): string;
+export declare function renderToolInventory(tools: readonly InbandTool[]): string;

package/dist/types/dialect/rendering.d.ts

@@ -4,6 +4,15 @@ export declare function renderToolResponseResults(results: readonly DialectToolR
 export declare function kimiCallId(name: string, id: string, index: number): string;
 export declare function harmonyRecipient(name: string): string;
 export declare function stringifyJson(value: unknown): string;
+/**
+ * Render `name(key=value, …)` with Python-literal argument values. Top-level
+ * multiline strings render as verbatim `"""…"""` blocks so payload-carrying
+ * args (file content, scripts, patches) keep real newlines instead of `\n`
+ * escape soup; nested values always use escaped single-line literals.
+ */
+export declare function pyCall(name: string, args: Record<string, unknown>): string;
+/** Render a JSON-ish value as a Python literal (`True`/`False`/`None`, escaped strings, lists, dicts). */
+export declare function pyValue(value: unknown): string;
 export declare function escapeXmlAttr(value: string): string;
 export declare function escapeXmlText(value: string): string;
 export type AssistantTranscriptParts = {

package/dist/types/dialect/types.d.ts

@@ -42,7 +42,6 @@ export interface DialectToolResult {
 }
 export interface DialectRenderOptions {
     readonly tools?: readonly InbandTool[];
-    readonly example?: boolean;
 }
 export interface DialectDefinition {
     readonly dialect: CatalogDialect;

package/dist/types/error/flags.d.ts

@@ -40,6 +40,11 @@ export declare function retriable(id: number | undefined, opts?: {
 }): boolean;
 export declare function status(error: unknown): number | undefined;
 export declare function isStreamReadErrorText(text: string): boolean;
+/** Persisted-text form of {@link isStreamEnvelopeError}: recognizes the
+ *  prefix-tagged envelope diagnostic on an aborted turn's `errorMessage` /
+ *  `stopDetails.explanation` so loop-level salvage can classify it after the
+ *  original `Error` instance is gone. */
+export declare function isStreamEnvelopeErrorText(text: string): boolean;
 export declare function classify(error: unknown, api?: Api): number;
 /**
  * Whether an error (or message string) classifies as an account usage/quota

package/dist/types/providers/openai-codex-responses.d.ts

@@ -1,5 +1,5 @@
 import type { CodexCompactionContext, CodexCompactionRequestContext, Context, Model, ProviderSessionState, ServiceTier, StreamFunction, StreamOptions, Tool, ToolChoice } from "../types.js";
-import { type CodexReasoningContext, type RequestBody } from "./openai-codex/request-transformer.js";
+import { type CodexLiteShapedBody, type CodexReasoningContext, type RequestBody } from "./openai-codex/request-transformer.js";
 import type { ResponseInput } from "./openai-responses-wire.js";
 export interface OpenAICodexResponsesOptions extends StreamOptions {
     reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
@@ -43,6 +43,15 @@ export interface OpenAICodexResponsesOptions extends StreamOptions {
      */
     onModerationMetadata?: (metadata: unknown) => void;
 }
+/** Raw V2 compaction body accepted by the Codex transport selector. */
+export interface OpenAICodexCompactionBody extends CodexLiteShapedBody {
+    model: string;
+    [key: string]: unknown;
+}
+/** Transport controls for a provider-native Codex V2 compaction stream. */
+export interface OpenAICodexCompactionStreamOptions extends OpenAICodexResponsesOptions {
+    apiKey: string;
+}
 /** Inputs for synthesizing Codex request identity outside the normal stream path. */
 export interface OpenAICodexCompatibilityMetadataOptions {
     sessionId?: string;
@@ -161,6 +170,11 @@ export declare function resetOpenAICodexHistoryAfterCompaction(options: OpenAICo
 export declare function normalizeCodexToolChoice(choice: ToolChoice | undefined, tools?: Tool[], model?: Model<"openai-codex-responses">): string | Record<string, unknown> | undefined;
 /** @internal Exported for tests. */
 export declare function buildTransformedCodexRequestBody(model: Model<"openai-codex-responses">, context: Context, options: OpenAICodexResponsesOptions | undefined, promptCacheKey?: string | undefined): Promise<RequestBody>;
+/**
+ * Open a provider-native V2 compaction stream through Codex's WebSocket-first
+ * transport, replaying WebSocket transport failures over SSE.
+ */
+export declare function openCodexCompactionEventStream(model: Model<"openai-codex-responses">, body: OpenAICodexCompactionBody, options: OpenAICodexCompactionStreamOptions): Promise<AsyncGenerator<Record<string, unknown>>>;
 export declare const streamOpenAICodexResponses: StreamFunction<"openai-codex-responses">;
 export declare function prewarmOpenAICodexResponses(model: Model<"openai-codex-responses">, options?: Pick<OpenAICodexResponsesOptions, "apiKey" | "headers" | "sessionId" | "signal" | "preferWebsockets" | "providerSessionState" | "responsesLite">): Promise<void>;
 export interface OpenAICodexTransportDetails {

package/dist/types/providers/openai-shared.d.ts

@@ -343,7 +343,13 @@ export declare function resolveOpenAIResponsesOutputClamp(model: Pick<Model, "pr
  */
 export declare function applyChatCompletionsToolStream(params: OpenAICompletionsParams, model: Model<"openai-completions">, compat: ResolvedOpenAICompat): void;
 export declare function isCompiledGrammarTooLargeStrictError(error: unknown, capturedErrorResponse: CapturedHttpErrorResponse | undefined): boolean;
-export declare function shouldRetryWithoutStrictTools(error: unknown, capturedErrorResponse: CapturedHttpErrorResponse | undefined, strictToolsApplied: boolean, tools: Tool[] | undefined): boolean;
+interface StrictToolsRetryContext {
+    model: OpenAIModelIdentity;
+    strictToolsApplied: boolean;
+    tools: Tool[] | undefined;
+}
+/** Decide whether an OpenAI-family request should retry once with non-strict tools. */
+export declare function shouldRetryWithoutStrictTools(error: unknown, capturedErrorResponse: CapturedHttpErrorResponse | undefined, context: StrictToolsRetryContext): boolean;
 export declare const OPENAI_RESPONSES_PROGRESS_EVENT_TYPES: ReadonlySet<string>;
 export declare function isOpenAIResponsesProgressEvent(event: unknown): boolean;
 export declare function encodeTextSignatureV1(id: string, phase?: TextSignatureV1["phase"]): string;
@@ -415,17 +421,27 @@ export interface BuildResponsesInputOptions<TApi extends Api> {
     preserveAssistantMessageIds?: boolean;
 }
 /**
- * Escape reserved Harmony control tokens in the client-boundary text of
- * replayed Responses input items — user/developer/system message text and
- * tool-result output. Model-owned items (assistant output, reasoning, tool-call
- * arguments) carry no client data and are returned untouched.
+ * Escape reserved Harmony control tokens in the free-text fields of replayed
+ * Responses input items: user/developer/system text, tool-result output,
+ * assistant message text, and tool-call payloads.
+ *
+ * Tool-call items are covered deliberately. The original #6913 fix skipped
+ * model-owned items on the theory that they carry no client data — but a model
+ * legitimately writing *about* Harmony samples `<|channel|>` etc. into its own
+ * `function_call.arguments`, and a full-transcript replay (stale or blocked
+ * previous_response_id, provider fallback) feeds those bytes back as input,
+ * which gpt-5.x reject with invalid_prompt / "Request blocked", permanently
+ * poisoning the session. `arguments` is a JSON document, so it uses
+ * {@link escapeHarmonyControlTokensInJson} to stay parseable. Reasoning items
+ * are left untouched: `encrypted_content` is opaque and plaintext summaries
+ * are never rendered back into the prompt.
  *
  * Native history replay pushes stored `providerPayload` items straight onto the
  * wire, bypassing {@link convertResponsesInputContent}; without this a stored
  * `input_text` carrying `<|channel|>analysis` still reaches gpt-5.x raw (#6913).
  * Callers gate on {@link isHarmonyDialectModel}. Items are copied, not mutated.
  */
-export declare function escapeReplayedClientText(items: ResponseInput): ResponseInput;
+export declare function escapeReplayedControlTokens(items: ResponseInput): ResponseInput;
 export declare function buildResponsesInput<TApi extends Api>(options: BuildResponsesInputOptions<TApi>): ResponseInput;
 export declare function convertResponsesAssistantMessage<TApi extends Api>(assistantMsg: AssistantMessage, model: Model<TApi>, msgIndex: number, knownCallIds: Set<string>, includeThinkingSignatures?: boolean, customCallIds?: Set<string>, preserveMessageIds?: boolean, supportsCustomToolCalls?: boolean, customToolWireNameMap?: ReadonlyMap<string, string>, computerCallIds?: Set<string>): ResponseInput;
 /** Appends one tool result while keeping consecutive outputs ahead of its synthetic image messages. */
@@ -510,6 +526,8 @@ export interface ProcessResponsesStreamOptions {
     requestServiceTier?: ServiceTier;
 }
 export declare function computerCallMetadata(item: ResponseComputerToolCall): ComputerToolCallMetadata;
+/** Append a native Responses image result and emit its completion event. */
+export declare function appendResponsesImageResult(output: AssistantMessage, stream: AssistantMessageEventStream, result: string): void;
 export declare function processResponsesStream<TApi extends Api>(openaiStream: AsyncIterable<ResponseStreamEvent>, output: AssistantMessage, stream: AssistantMessageEventStream, model: Model<TApi>, options?: ProcessResponsesStreamOptions): Promise<void>;
 export declare function mapOpenAIResponsesStopReason(status: ResponseStatus | undefined): StopReason;
 export declare function hasExecutableIncompleteResponsesToolCalls(output: AssistantMessage): boolean;

package/dist/types/providers/transform-messages.d.ts

@@ -13,7 +13,7 @@ import type { Api, AssistantMessage, Message, Model } from "../types.js";
  * credential redaction is enabled. Exported so hosts can route the same shapes
  * through reversible obfuscation (keyed placeholders restored before local tool
  * execution) instead of the irreversible `[*_token_redacted]` rewrite below —
- * an irreversible placeholder echoed back in edit-tool `old_text` can never
+ * an irreversible placeholder echoed back in edit-tool `old_string` can never
  * match the real bytes on disk.
  */
 export declare const SENSITIVE_TOKEN_RE: RegExp;

package/dist/types/types.d.ts

@@ -124,10 +124,10 @@ export declare function serviceTierFamily(model: ServiceTierModel): ServiceTierF
 export declare function resolveModelServiceTier(tiers: ServiceTierByFamily | null | undefined, model: Pick<Model, "provider" | "api" | "id">): ServiceTier | undefined;
 /**
  * True when the tier should be sent on the wire as the provider's service-tier
- * request field. OpenAI / OpenAI-Codex accept `flex`/`scale`/`priority`; Google
- * (Gemini API + Vertex) and OpenRouter accept `flex`/`priority`; Fireworks
- * Serverless realizes only its Priority serving path. Anthropic is absent — it
- * realizes `priority` via `speed: "fast"`, not a service-tier field.
+ * request field. OpenAI / OpenAI-Codex accept every {@link ServiceTier};
+ * Google (Gemini API + Vertex) and OpenRouter accept `flex`/`priority`;
+ * Fireworks Serverless realizes only its Priority serving path. Anthropic is
+ * absent because it realizes `priority` via `speed: "fast"`.
  */
 export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, target: Provider | ServiceTierModel | undefined): boolean;
 /**
@@ -660,6 +660,8 @@ export interface AssistantRetryRecovery {
 export interface ContextSnapshot {
     promptTokens: number;
     nonMessageTokens: number;
+    /** Estimated prompt tokens removed by local history rewrites after this provider snapshot was recorded. */
+    historyRewriteTokensRemoved?: number;
     lastMessageTimestamp?: number;
 }
 export interface AssistantMessage {

package/dist/types/utils/harmony-leak.d.ts

@@ -8,6 +8,15 @@ import type { AssistantMessage, Model, ToolCall } from "../types.js";
  * the persisted transcript keeps the byte-for-byte original.
  */
 export declare function escapeHarmonyControlTokens(text: string): string;
+/**
+ * Escape reserved Harmony control tokens inside a JSON document string (e.g.
+ * `function_call.arguments`). Doubles the backslash so the document remains
+ * valid JSON whose *decoded* strings carry the inert `<\|token\|>` spelling.
+ * `<|` cannot occur outside a string literal in valid JSON, so the blanket
+ * replace never corrupts structure; malformed documents are escaped
+ * best-effort.
+ */
+export declare function escapeHarmonyControlTokensInJson(text: string): string;
 /**
  * Whether requests to `model` are served by a Harmony-dialect backend
  * (gpt-5.x / gpt-oss), which rejects reserved control-token spellings appearing

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

@@ -9,10 +9,16 @@
  * literal enums/consts, and descriptions survive.
  */
 export interface JsonSchemaToTsOptions {
-    /** Indentation unit for nested object bodies. Default two spaces. */
+    /** Indentation unit for nested object bodies. Default two spaces (none in `harmony` style). */
     readonly indent?: string;
-    /** Emit `description` keywords as JSDoc comments on object properties. Default true. */
+    /** Emit `description` keywords as comments on object properties. Default true. */
     readonly comments?: boolean;
+    /**
+     * Output flavor. `default` renders JSDoc comments, `;` delimiters, and
+     * indented bodies; `harmony` renders the flat OpenAI-Harmony convention —
+     * `//` line comments, `,` delimiters, no indentation.
+     */
+    readonly style?: "default" | "harmony";
 }
 /** Convert a JSON Schema object into a simplified TypeScript type string. */
 export declare function jsonSchemaToTypeScript(schema: unknown, options?: JsonSchemaToTsOptions): string;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "17.2.3",
+	"version": "17.2.5",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-catalog": "17.2.3",
-		"@oh-my-pi/pi-utils": "17.2.3",
-		"@oh-my-pi/pi-wire": "17.2.3",
+		"@oh-my-pi/pi-catalog": "17.2.5",
+		"@oh-my-pi/pi-utils": "17.2.5",
+		"@oh-my-pi/pi-wire": "17.2.5",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},

package/src/auth-broker/discover.ts

@@ -6,6 +6,7 @@
  */
 import * as path from "node:path";
 import {
+	$envExact,
 	getAgentDbPath,
 	getAgentDir,
 	getAuthBrokerSnapshotCachePath,
@@ -55,7 +56,7 @@ export function getAuthBrokerTokenFilePath(): string {
  */
 async function defaultResolveConfigValue(config: string): Promise<string | undefined> {
 	if (config.startsWith("!")) return undefined;
-	const envValue = process.env[config];
+	const envValue = $envExact(config);
 	return envValue || config;
 }
 

package/src/auth-storage.ts

@@ -12,7 +12,7 @@ import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { parseAlibabaTokenPlanCredential } from "@oh-my-pi/pi-catalog/wire/alibaba-token-plan";
-import { $env, getAgentDbPath, logger } from "@oh-my-pi/pi-utils";
+import { $env, $envExact, getAgentDbPath, getDbBusyTimeoutMs, logger } from "@oh-my-pi/pi-utils";
 import type { ApiKeyResolver } from "./auth-retry";
 import * as AIError from "./error";
 import { isUsageLimitOutcome } from "./error/rate-limit";
@@ -643,7 +643,7 @@ export type AuthStorageOptions = {
  * Does NOT support "!command" syntax (that requires pi-natives).
  */
 async function defaultConfigValueResolver(config: string): Promise<string | undefined> {
-	const envValue = process.env[config];
+	const envValue = $envExact(config);
 	return envValue || config;
 }
 
@@ -1264,6 +1264,15 @@ export class AuthStorage {
 	#credentialBackoff: Map<string, Map<number, number>> = new Map();
 	/** Earliest time a freshly-set in-memory block may be cleared by live usage reconciliation. */
 	#credentialBackoffProbeAfter: Map<string, Map<number, number>> = new Map();
+	/**
+	 * Latched true once the persistent credential-block store reports an
+	 * unrecoverable error (SQLite corruption / not-a-database). While set, every
+	 * persisted-block read and write short-circuits for the life of the process:
+	 * availability is preserved through {@link AuthStorage.#credentialBackoff}, but
+	 * cross-process persistence is abandoned rather than re-querying a broken store
+	 * on every credential evaluation.
+	 */
+	#persistedBlockStoreDamaged = false;
 	#usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
 	#rankingStrategyResolver?: (provider: Provider) => CredentialRankingStrategy | undefined;
 	#usageCache: UsageCache;
@@ -1312,8 +1321,10 @@ export class AuthStorage {
 		}
 		try {
 			this.#store.cleanExpiredCredentialBlocks?.(Date.now());
-		} catch {
-			// Best-effort.
+		} catch (err) {
+			// Best-effort, but init-time corruption must latch the block store
+			// immediately so the first evaluation doesn't re-query a broken DB.
+			this.#handlePersistedBlockStoreError(err);
 		}
 		this.#usageFetch = options.usageFetch ?? fetch;
 		this.#usageRequestTimeoutMs = options.usageRequestTimeoutMs ?? DEFAULT_USAGE_REQUEST_TIMEOUT_MS;
@@ -1483,7 +1494,16 @@ export class AuthStorage {
 	 * Reload credentials from storage.
 	 */
 	async reload(): Promise<void> {
-		const records = this.#store.listAuthCredentials();
+		let records: StoredAuthCredential[];
+		try {
+			records = this.#store.listAuthCredentials();
+		} catch (err) {
+			// Latch + surface repair guidance on corruption, but still fail the
+			// reload: silently continuing with zero credentials would log the
+			// user out of every provider without explanation.
+			this.#handlePersistedBlockStoreError(err);
+			throw err;
+		}
 		const grouped = new Map<string, StoredCredential[]>();
 		for (const record of records) {
 			const list = grouped.get(record.provider) ?? [];
@@ -1701,11 +1721,13 @@ export class AuthStorage {
 		providerKey: string,
 		blockScope: string | undefined,
 	): number | undefined {
+		if (this.#persistedBlockStoreDamaged) return undefined;
 		const getCredentialBlock = this.#store.getCredentialBlock?.bind(this.#store);
 		if (!getCredentialBlock) return undefined;
 		try {
 			return getCredentialBlock(credentialId, providerKey, blockScope ?? "");
 		} catch (err) {
+			if (this.#handlePersistedBlockStoreError(err)) return undefined;
 			logger.debug("Failed to read credential block from persistent store", {
 				err,
 				credentialId,
@@ -1716,6 +1738,26 @@ export class AuthStorage {
 		}
 	}
 
+	#readPersistedCredentialBlockReconcileAfter(credentialId: number, providerKey: string, blockScope: string): number {
+		if (this.#persistedBlockStoreDamaged) return 0;
+		const getCredentialBlockReconcileAfter = this.#store.getCredentialBlockReconcileAfter?.bind(this.#store);
+		if (!getCredentialBlockReconcileAfter) return 0;
+		try {
+			return getCredentialBlockReconcileAfter(credentialId, providerKey, blockScope) ?? 0;
+		} catch (err) {
+			if (this.#handlePersistedBlockStoreError(err)) return 0;
+			// Advisory read: transient failures (e.g. SQLITE_BUSY) fall back to
+			// the in-memory probe window, mirroring #readPersistedCredentialBlock.
+			logger.debug("Failed to read credential block reconcile-after time from persistent store", {
+				err,
+				credentialId,
+				providerKey,
+				blockScope,
+			});
+			return 0;
+		}
+	}
+
 	/** Returns block expiry timestamp for a credential, checking unscoped and scoped blocks. */
 	#getCredentialBlockedUntil(
 		provider: string,
@@ -1792,7 +1834,7 @@ export class AuthStorage {
 		this.#invalidateUsageReportCache(provider);
 
 		const upsertCredentialBlock = this.#store.upsertCredentialBlock?.bind(this.#store);
-		if (!upsertCredentialBlock) return;
+		if (!upsertCredentialBlock || this.#persistedBlockStoreDamaged) return;
 		const credentialId = this.#getStoredCredentials(provider)[credentialIndex]?.id;
 		if (credentialId === undefined) return;
 		try {
@@ -1803,6 +1845,7 @@ export class AuthStorage {
 				blockedUntilMs: nextBlockedUntil,
 			});
 		} catch (err) {
+			if (this.#handlePersistedBlockStoreError(err)) return;
 			logger.debug("Failed to persist credential block", {
 				err,
 				credentialId,
@@ -1814,6 +1857,36 @@ export class AuthStorage {
 		}
 	}
 
+	#handlePersistedBlockStoreError(err: unknown): boolean {
+		if (!isSqliteCorruptionError(err)) return false;
+		this.#reportDamagedBlockStore(err);
+		return true;
+	}
+
+	#assertPersistedBlockStoreWritable(): void {
+		if (!this.#persistedBlockStoreDamaged) return;
+		const store = this.#sourceLabel ?? `local ${getAgentDbPath()}`;
+		throw new Error(`Persistent credential block store ${store} is unavailable after SQLite corruption`);
+	}
+
+	/**
+	 * Latches {@link AuthStorage.#persistedBlockStoreDamaged} on the first
+	 * unrecoverable persisted-block store error and surfaces it once at `error`
+	 * level with the store location, so an operator can repair or replace it.
+	 * Later reads/writes short-circuit silently — the in-memory backoff map keeps
+	 * rate-limit blocks applying for the life of the process; only cross-process
+	 * persistence is lost.
+	 */
+	#reportDamagedBlockStore(err: unknown): void {
+		if (this.#persistedBlockStoreDamaged) return;
+		this.#persistedBlockStoreDamaged = true;
+		const store = this.#sourceLabel ?? `local ${getAgentDbPath()}`;
+		logger.error(
+			"Persistent credential store is corrupt; cross-process rate-limit persistence is disabled for this process. In-memory backoff still applies. Repair the store with `sqlite3 <path> '.recover'` or delete it to recreate on next login.",
+			{ err, store },
+		);
+	}
+
 	/**
 	 * Records which credential was used for a session (for rate-limit switching).
 	 * `lastUsedAtMs` backdates the sticky (session-file pin restores on resume);
@@ -5862,9 +5935,12 @@ export class AuthStorage {
 		const scopedBackoffKey = this.#toScopedBackoffKey(providerKey, blockScope);
 		const globalProbeAfterMs = this.#credentialBackoffProbeAfter.get(providerKey)?.get(credentialIndex) ?? 0;
 		const scopedProbeAfterMs = this.#credentialBackoffProbeAfter.get(scopedBackoffKey)?.get(credentialIndex) ?? 0;
-		const getStoreReconcileAfter = this.#store.getCredentialBlockReconcileAfter?.bind(this.#store);
-		const storeGlobalProbeAfterMs = getStoreReconcileAfter?.(credentialId, providerKey, "") ?? 0;
-		const storeScopedProbeAfterMs = getStoreReconcileAfter?.(credentialId, providerKey, blockScope ?? "") ?? 0;
+		const storeGlobalProbeAfterMs = this.#readPersistedCredentialBlockReconcileAfter(credentialId, providerKey, "");
+		const storeScopedProbeAfterMs = this.#readPersistedCredentialBlockReconcileAfter(
+			credentialId,
+			providerKey,
+			blockScope ?? "",
+		);
 		if (Math.max(globalProbeAfterMs, scopedProbeAfterMs, storeGlobalProbeAfterMs, storeScopedProbeAfterMs) > nowMs) {
 			return;
 		}
@@ -6340,16 +6416,30 @@ export class AuthStorage {
 	 * Broker-server seam: list non-expired persisted blocks for snapshot entries.
 	 */
 	listCredentialBlocks(credentialIds: readonly number[]): StoredCredentialBlock[] {
-		return this.#store.listCredentialBlocks?.(credentialIds) ?? [];
+		if (this.#persistedBlockStoreDamaged) return [];
+		const listCredentialBlocks = this.#store.listCredentialBlocks?.bind(this.#store);
+		if (!listCredentialBlocks) return [];
+		try {
+			return listCredentialBlocks(credentialIds);
+		} catch (err) {
+			if (this.#handlePersistedBlockStoreError(err)) return [];
+			throw err;
+		}
 	}
 
 	/**
 	 * Broker-server seam: persist one credential block and notify snapshot waiters.
 	 */
 	upsertCredentialBlock(block: StoredCredentialBlock): void {
+		this.#assertPersistedBlockStoreWritable();
 		const upsertCredentialBlock = this.#store.upsertCredentialBlock?.bind(this.#store);
 		if (!upsertCredentialBlock) return;
-		upsertCredentialBlock(block);
+		try {
+			upsertCredentialBlock(block);
+		} catch (err) {
+			if (this.#handlePersistedBlockStoreError(err)) this.#assertPersistedBlockStoreWritable();
+			throw err;
+		}
 		this.#invalidateUsageReportCacheForProviderKey(block.providerKey);
 		this.#bumpGeneration("credential-block");
 	}
@@ -6358,17 +6448,29 @@ export class AuthStorage {
 	 * Broker-server seam: clear all persisted blocks for one credential and notify snapshot waiters.
 	 */
 	deleteCredentialBlock(credentialId: number, providerKey: string, blockScope: string): void {
+		this.#assertPersistedBlockStoreWritable();
 		const deleteCredentialBlock = this.#store.deleteCredentialBlock?.bind(this.#store);
 		if (!deleteCredentialBlock) return;
-		deleteCredentialBlock(credentialId, providerKey, blockScope);
+		try {
+			deleteCredentialBlock(credentialId, providerKey, blockScope);
+		} catch (err) {
+			if (this.#handlePersistedBlockStoreError(err)) this.#assertPersistedBlockStoreWritable();
+			throw err;
+		}
 		this.#invalidateUsageReportCacheForProviderKey(providerKey);
 		this.#bumpGeneration("credential-block");
 	}
 
 	deleteCredentialBlocks(credentialId: number): void {
+		this.#assertPersistedBlockStoreWritable();
 		const deleteCredentialBlocks = this.#store.deleteCredentialBlocks?.bind(this.#store);
 		if (!deleteCredentialBlocks) return;
-		deleteCredentialBlocks(credentialId);
+		try {
+			deleteCredentialBlocks(credentialId);
+		} catch (err) {
+			if (this.#handlePersistedBlockStoreError(err)) this.#assertPersistedBlockStoreWritable();
+			throw err;
+		}
 		this.#bumpGeneration("credential-block");
 	}
 
@@ -6482,6 +6584,19 @@ export function isSqliteBusyError(err: unknown): boolean {
 	return typeof code === "string" && code.startsWith("SQLITE_BUSY");
 }
 
+/**
+ * SQLite's unrecoverable-corruption result codes — the `SQLITE_CORRUPT` family
+ * (base plus extended variants like `SQLITE_CORRUPT_VTAB` / `SQLITE_CORRUPT_INDEX`)
+ * and `SQLITE_NOTADB` (the file header is not a database). Unlike
+ * {@link isSqliteBusyError}, these never clear by retrying: the store must be
+ * repaired or replaced, so callers latch and stop touching it.
+ */
+export function isSqliteCorruptionError(err: unknown): boolean {
+	if (err === null || typeof err !== "object" || !("code" in err)) return false;
+	const code = err.code;
+	return typeof code === "string" && (code.startsWith("SQLITE_CORRUPT") || code === "SQLITE_NOTADB");
+}
+
 function normalizeStoredAccountId(accountId: string | null | undefined): string | null {
 	const normalized = accountId?.trim();
 	return normalized && normalized.length > 0 ? normalized : null;
@@ -6914,6 +7029,12 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 			let db: Database | undefined;
 			try {
 				db = new Database(dbPath);
+				// Install the busy handler BEFORE the first lock-taking statement
+				// on this connection. The leases DDL below and the constructor's
+				// schema init both acquire locks during WAL recovery; without a
+				// non-zero `busy_timeout` they fail immediately with SQLITE_BUSY.
+				// See issue #2421.
+				SqliteAuthCredentialStore.#installBusyTimeout(db);
 				try {
 					await fs.chmod(dbPath, 0o600);
 				} catch {
@@ -6950,12 +7071,25 @@ export class SqliteAuthCredentialStore implements AuthCredentialStore {
 		`);
 	}
 
+	/**
+	 * Install the per-connection busy handler so lock-taking statements wait for
+	 * a contended writer instead of failing immediately (Bun defaults
+	 * `busy_timeout` to 0). MUST run before the first lock-taking statement on
+	 * the connection: concurrent omp startups race WAL recovery and the leases
+	 * DDL. Uses the centralized timeout so headless hosts keep their bounded
+	 * busy wait instead of the interactive 5s value. See issues #2421, #7298.
+	 */
+	static #installBusyTimeout(db: Database): void {
+		db.run(`PRAGMA busy_timeout = ${getDbBusyTimeoutMs()}`);
+	}
+
 	#initializeSchema(): void {
 		// Install the busy handler BEFORE any lock-taking statement (incl.
 		// `PRAGMA journal_mode=WAL`, which acquires an exclusive lock during WAL
 		// recovery). Without this, concurrent omp startups can crash here with
-		// `SQLITE_BUSY` / `SQLITE_BUSY_RECOVERY`. See issue #2421.
-		this.#db.run("PRAGMA busy_timeout = 5000");
+		// `SQLITE_BUSY` / `SQLITE_BUSY_RECOVERY`. Re-setting when opened via
+		// `open()` (which already installed it) is idempotent. See issue #2421.
+		SqliteAuthCredentialStore.#installBusyTimeout(this.#db);
 		this.#db.run(`
 			PRAGMA journal_mode=WAL;
 			PRAGMA synchronous=NORMAL;