@oh-my-pi/pi-catalog 17.0.4 → 17.0.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [17.0.5] - 2026-07-18
+
+### Added
+
+- Added an Anthropic compatibility flag to allow non-official OAuth endpoints to opt into configured Claude Code fingerprint header overrides.
+
+### Fixed
+
+- Fixed a security issue where sensitive provider-defined request headers (such as API keys or credentials) were serialized in plaintext within the model cache (models.db). The cache now omits these headers, securely invalidates older cached rows, and restores or refetches them dynamically.
+- Fixed OpenAI Codex discovery to respect caller-supplied fetch configurations (such as proxies or custom CAs) and correctly replace stale bundled models with the authenticated account catalog.
+- Fixed stream timeouts and retry loops during long prefills on local loopback or RFC1918 backends (such as litellm proxies fronting local servers) by applying the local stream-timeout floor to these backends.
+- Fixed Kimi K3 models served through generic OpenAI-compatible routes exposing unsupported reasoning efforts instead of the mandatory low/high/max scale.
+
 ## [17.0.4] - 2026-07-18
 
 ### Changed

package/dist/types/discovery/codex.d.ts

@@ -1,4 +1,4 @@
-import type { ModelSpec } from "../types.js";
+import type { FetchImpl, ModelSpec } from "../types.js";
 /**
  * Fetch options for OpenAI Codex model discovery.
  */
@@ -18,7 +18,7 @@ export interface CodexModelDiscoveryOptions {
     /** Abort signal for network request cancellation. */
     signal?: AbortSignal;
     /** Optional fetch implementation override for tests. */
-    fetchFn?: typeof fetch;
+    fetchFn?: FetchImpl;
 }
 /**
  * Normalized Codex discovery response.

package/dist/types/model-cache.d.ts

@@ -4,6 +4,10 @@ interface CacheEntry<TApi extends Api = Api> {
     fresh: boolean;
     authoritative: boolean;
     updatedAt: number;
+    /** Model ids whose live headers were intentionally omitted from disk. */
+    headerOmittedModelIds: readonly string[];
+    /** Header-bearing model ids that cannot be rebuilt from the static source. */
+    unrestorableHeaderModelIds: readonly string[];
     /**
      * Hash of the static catalog slice that was merged into `models` when this
      * row was written. `resolveProviderModels` compares against the current
@@ -13,5 +17,5 @@ interface CacheEntry<TApi extends Api = Api> {
     staticFingerprint: string;
 }
 export declare function readModelCache<TApi extends Api>(providerId: string, ttlMs: number, now: () => number, dbPath?: string): CacheEntry<TApi> | null;
-export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string): void;
+export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string, staticHeaderSources?: readonly Model<TApi>[]): void;
 export {};

package/dist/types/provider-models/special.d.ts

@@ -5,6 +5,7 @@ export interface OpenAICodexModelManagerConfig {
     accessToken?: string;
     accountId?: string;
     clientVersion?: string;
+    fetch?: FetchImpl;
 }
 export declare function openaiCodexModelManagerOptions(config?: OpenAICodexModelManagerConfig): ModelManagerOptions<"openai-codex-responses">;
 export interface CursorModelManagerConfig {

package/dist/types/types.d.ts

@@ -272,16 +272,29 @@ export interface OpenAICompat {
     supportsStrictMode?: boolean;
     /**
      * Tool-schema dialect the endpoint validates `tools.function.parameters`
-     * against. `"moonshot-mfjs"` triggers Moonshot Flavored JSON Schema
-     * normalization (collapse `const`→`enum`, infer `type` on bare enums, strip
-     * unsupported validators/`prefixItems`) because Moonshot/Kimi native hosts
-     * reject standard JSON Schema constructs with HTTP 400. Default:
-     * auto-detected — Moonshot native hosts (api.moonshot.ai / api.kimi.com)
-     * and Kimi-family model ids on any host, since proxies (OpenRouter, custom
-     * gateways) forward schemas to Moonshot verbatim. Set `"none"` to opt a
-     * host out.
+     * against.
+     *
+     * `"moonshot-mfjs"` triggers Moonshot Flavored JSON Schema normalization
+     * (collapse `const`→`enum`, infer `type` on bare enums, strip unsupported
+     * validators/`prefixItems`) because Moonshot/Kimi native hosts reject
+     * standard JSON Schema constructs with HTTP 400.
+     *
+     * `"grammar"` triggers grammar-sampler normalization (widen bare boolean
+     * `true`/`{}` subschemas in genuine subschema slots into a value-accepting
+     * union of primitives) because grammar-constrained backends (llama.cpp, LM
+     * Studio, vLLM) build a GBNF grammar from the JSON Schema and 400 with
+     * `Unrecognized schema: true` on a bare boolean subschema (issue #5914).
+     * Boolean `additionalProperties`/`unevaluatedProperties` are preserved — the
+     * grammar converter reads them as closed/open-object semantics, and
+     * `additionalProperties: false` pins the strict object shape.
+     *
+     * Default: auto-detected — `"moonshot-mfjs"` on Moonshot native hosts
+     * (api.moonshot.ai / api.kimi.com) and Kimi-family model ids on any host,
+     * since proxies (OpenRouter, custom gateways) forward schemas to Moonshot
+     * verbatim; `"grammar"` on local OpenAI-compatible backends. Set `"none"`
+     * to opt a host out.
      */
-    toolSchemaFlavor?: "moonshot-mfjs" | "none";
+    toolSchemaFlavor?: "moonshot-mfjs" | "grammar" | "none";
     /**
      * Stream-watchdog idle-timeout floor in ms for slow reasoning hosts.
      * Default: auto-detected (GLM coding-plan hosts, direct DeepSeek reasoning).
@@ -379,6 +392,11 @@ export interface AnthropicCompat {
      * auto-detected (Z.AI hosts).
      */
     requiresToolResultId?: boolean;
+    /**
+     * Allow configured Claude Code fingerprint headers to replace generated
+     * OAuth defaults on non-official Anthropic endpoints.
+     */
+    allowAnthropicHeaderOverrides?: boolean;
     /**
      * Replay unsigned `thinking` blocks from prior assistant turns as native
      * thinking instead of demoting them to text. Official Anthropic enforces

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-catalog",
-	"version": "17.0.4",
+	"version": "17.0.5",
 	"description": "Model catalog for omp: bundled model database, provider discovery descriptors, model identity, classification, and equivalence",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -34,12 +34,12 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.1",
-		"@oh-my-pi/pi-utils": "17.0.4",
+		"@oh-my-pi/pi-utils": "17.0.5",
 		"arktype": "2.2.3",
 		"zod": "^4"
 	},
 	"devDependencies": {
-		"@oh-my-pi/pi-ai": "17.0.4",
+		"@oh-my-pi/pi-ai": "17.0.5",
 		"@types/bun": "^1.3.14"
 	},
 	"engines": {

package/src/compat/anthropic.ts

@@ -109,6 +109,7 @@ export function buildAnthropicCompat(spec: ModelSpec<"anthropic-messages">): Res
 		signingEndpoint,
 		disableStrictTools: isAzure,
 		disableAdaptiveThinking: false,
+		allowAnthropicHeaderOverrides: false,
 		supportsEagerToolInputStreaming: official,
 		// Long cache retention is only sent to the official API by default;
 		// proxies opt in explicitly via `compat.supportsLongCacheRetention: true`.

package/src/compat/openai.ts

@@ -154,14 +154,32 @@ const OPENCODE_WHEN_THINKING: NonNullable<OpenAICompat["whenThinking"]> = {
 	reasoningContentField: "reasoning_content",
 };
 
+const KIMI_K3_REASONING_EFFORT_MAP: NonNullable<OpenAICompat["reasoningEffortMap"]> = {
+	minimal: "low",
+	medium: "high",
+	xhigh: "max",
+	max: "max",
+};
+
 const MIMO_REASONING_EFFORT_MAP: NonNullable<OpenAICompat["reasoningEffortMap"]> = {
 	minimal: "low",
 	xhigh: "high",
 };
 
-function mergeMimoReasoningEffortMap(compat: ResolvedOpenAISharedCompat, enabled: boolean): void {
-	if (!enabled) return;
-	compat.reasoningEffortMap = { ...MIMO_REASONING_EFFORT_MAP, ...compat.reasoningEffortMap };
+function mergeModelReasoningEffortMap(
+	compat: ResolvedOpenAISharedCompat,
+	modelId: string,
+	isMimoReasoningEffortModel: boolean,
+): void {
+	let detected: NonNullable<OpenAICompat["reasoningEffortMap"]>;
+	if (isKimiK3ModelId(modelId)) {
+		detected = KIMI_K3_REASONING_EFFORT_MAP;
+	} else if (isMimoReasoningEffortModel) {
+		detected = MIMO_REASONING_EFFORT_MAP;
+	} else {
+		return;
+	}
+	compat.reasoningEffortMap = { ...detected, ...compat.reasoningEffortMap };
 }
 
 function detectStrictModeSupport(provider: string, baseUrl: string): boolean {
@@ -249,11 +267,10 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 	const isKimiModel = isKimiModelId(spec.id);
 	const isMoonshotNative = modelMatchesHost(hostModel, "moonshotNative");
 	const isMoonshotKimi = isKimiModel && isMoonshotNative;
-	// Kimi K3 (native) always reasons via OpenAI-style `reasoning_effort: "max"`
-	// and does NOT accept the K2.x binary `thinking: { type }` block, so it must
-	// stay on the "openai" thinking dialect even though it is a Moonshot-native
-	// Kimi model (#5756).
-	const isMoonshotKimiK3 = isMoonshotKimi && isKimiK3ModelId(spec.id);
+	// Native Kimi K3 uses OpenAI-style `reasoning_effort` with mandatory
+	// low/high/max thinking, not the K2.x binary `thinking: { type }` block.
+	const isKimiK3 = isKimiK3ModelId(spec.id);
+	const isMoonshotKimiK3 = isMoonshotKimi && isKimiK3;
 	const requiresEnabledThinking = isMoonshotKimi && matchesKimiK27CodeFamily(spec);
 	const usesMoonshotKimiPreservedThinking = isMoonshotKimi && isKimiK26ModelId(spec.id);
 	const isAnthropicModel =
@@ -306,6 +323,14 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 	const isLocalOpenAICompatBackend =
 		!PROXY_OPENAI_COMPAT_PROVIDERS.has(provider) &&
 		(LOCAL_OPENAI_COMPAT_PROVIDERS.has(provider) || hasLocalLoopbackBaseUrl(baseUrl));
+	// Stream-timeout floor applies to ANY loopback/RFC1918 backend, INCLUDING
+	// local proxies (litellm) excluded from `isLocalOpenAICompatBackend` above:
+	// widening the first-event/idle abort ceiling only helps a slow local
+	// upstream and never pushes an extra wire field, so the proxy carve-out (a
+	// `replayReasoningContent` safety measure) must not also strip the timeout
+	// floor. Without this, a loopback litellm fronting a cold/reprocessing
+	// llama-server aborts prefill at the 100s default and retry-loops (#4786).
+	const isLocalServingBackend = isLocalOpenAICompatBackend || hasLocalLoopbackBaseUrl(baseUrl);
 
 	const useMaxTokens =
 		isMistral ||
@@ -378,7 +403,7 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 						? KIMI_REASONING_STREAM_IDLE_TIMEOUT_MS
 						: spec.reasoning && isDirectDeepseekApi
 							? DEEPSEEK_REASONING_STREAM_IDLE_TIMEOUT_MS
-							: isLocalOpenAICompatBackend
+							: isLocalServingBackend
 								? LOCAL_OPENAI_COMPAT_STREAM_IDLE_TIMEOUT_MS
 								: undefined;
 
@@ -423,7 +448,7 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 		// OpenAI proprietary reasoning models (o-series, gpt-5+) reject explicit
 		// temperature/top_p/… with a 400 on every serving host (#5606).
 		supportsSamplingParams: !isOpenAISamplingRestrictedModelId(spec.id),
-		reasoningEffortMap: isMimoReasoningEffortModel ? MIMO_REASONING_EFFORT_MAP : {},
+		reasoningEffortMap: {},
 		supportsUsageInStreaming: !isCerebras,
 		// pi-ai's thinking-loop guard is gemini-only; default the flag from the
 		// family classifier so OpenAI-compat proxies serving Gemini are covered.
@@ -436,11 +461,9 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 		// every call since the family can otherwise emit very long reasoning traces
 		// before the final answer.
 		alwaysSendMaxTokens: isKimiModel,
-		// Native Kimi K3 always reasons via `reasoning_effort: "max"` (never the
+		// Native Kimi K3 always reasons through `reasoning_effort` (never the
 		// K2.x binary `thinking` block that #827's forced-tool-choice conflict is
-		// about), so suppressing its effort would strip the mandatory `max` from
-		// normal forced-tool turns (e.g. plan-mode `toolChoice: "required"`) and
-		// leave K3 in an unsupported mode (#5758 review).
+		// about), so suppressing its effort would leave K3 in an unsupported mode.
 		disableReasoningOnForcedToolChoice: (isKimiModel && !isMoonshotKimiK3) || isAnthropicModel,
 		disableReasoningOnToolChoice: isDeepseekFamily && Boolean(spec.reasoning) && !isOpenRouter,
 		supportsToolChoice: !isDirectDeepseekReasoning,
@@ -451,11 +474,10 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 		requiresAssistantAfterToolResult: isMistral,
 		requiresThinkingAsText: isMistral,
 		requiresMistralToolIds: isMistral,
-		// Only Kimi's native hosts (Moonshot / Kimi-code, matched by `isMoonshotKimi`)
-		// speak the z.ai binary `thinking: { type }` field. Kimi reached through
-		// OpenAI-compatible proxies — Fireworks' Fire Pass router, OpenCode's gateway,
-		// etc. — drives reasoning via OpenAI-style `reasoning_effort`
-		// (low|medium|high|xhigh|max|none), so those stay on the "openai" path.
+		// Only Kimi's native K2.x hosts (Moonshot / Kimi-code, matched by
+		// `isMoonshotKimi`) speak the z.ai binary `thinking: { type }` field.
+		// K3 and Kimi reached through OpenAI-compatible proxies drive reasoning
+		// via OpenAI-style `reasoning_effort`.
 		// NVIDIA NIM hosts Qwen with the vLLM convention
 		// (`chat_template_kwargs.enable_thinking`); top-level `enable_thinking`
 		// is rejected by NIM's `additionalProperties: false` request schema
@@ -535,7 +557,8 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 		// Kimi-family ids trigger MFJS on any host, not just native base URLs:
 		// proxies (OpenRouter, custom gateways) forward `tools.function.parameters`
 		// to Moonshot verbatim, which 400s on non-MFJS constructs.
-		toolSchemaFlavor: isMoonshotNative || isKimiModel ? "moonshot-mfjs" : undefined,
+		toolSchemaFlavor:
+			isMoonshotNative || isKimiModel ? "moonshot-mfjs" : isLocalOpenAICompatBackend ? "grammar" : undefined,
 		streamIdleTimeoutMs,
 		stripDeepseekSpecialTokens:
 			isDeepseekModelIdOrName(spec.id) && (provider === "nvidia" || provider === "deepseek"),
@@ -557,7 +580,7 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 	if (spec.compat?.omitReasoningEffort === undefined && !compat.supportsReasoningEffort) {
 		compat.omitReasoningEffort = true;
 	}
-	mergeMimoReasoningEffortMap(compat, isMimoReasoningEffortModel);
+	mergeModelReasoningEffortMap(compat, spec.id, isMimoReasoningEffortModel);
 
 	const whenThinkingPolicy =
 		spec.compat?.whenThinking ?? (isOpenCodeProvider && spec.reasoning ? OPENCODE_WHEN_THINKING : undefined);
@@ -570,7 +593,7 @@ export function buildOpenAICompat(spec: ModelSpec<"openai-completions">): Resolv
 		if (whenThinkingPolicy.omitReasoningEffort === undefined && !variant.supportsReasoningEffort) {
 			variant.omitReasoningEffort = true;
 		}
-		mergeMimoReasoningEffortMap(variant, isMimoReasoningEffortModel);
+		mergeModelReasoningEffortMap(variant, spec.id, isMimoReasoningEffortModel);
 		compat.whenThinking = variant;
 	}
 
@@ -606,9 +629,13 @@ export function buildOpenAIResponsesCompat(spec: OpenAIResponsesSpecLike): Resol
 	const isAnthropicModel = id ? isClaudeModelId(id) || isAnthropicNamespacedModelId(id) : false;
 	const isDeepseekFamily = id ? isDeepseekModelIdOrName(id) || isDeepseekModelIdOrName(spec.name) : false;
 	const reasoningCapable = Boolean(spec.reasoning);
-	const isLocalOpenAICompatBackend =
-		!PROXY_OPENAI_COMPAT_PROVIDERS.has(spec.provider) &&
-		(LOCAL_OPENAI_COMPAT_PROVIDERS.has(spec.provider) || hasLocalLoopbackBaseUrl(baseUrl));
+	// `replayReasoningContent` is Responses-only-false, so the proxy carve-out is
+	// irrelevant here; the stream-timeout floor still applies to ANY loopback /
+	// RFC1918 backend, including local proxies (litellm), so a slow local
+	// upstream is not aborted at the 100s default and retry-looped (#4786).
+	const isLocalServingBackend =
+		(!PROXY_OPENAI_COMPAT_PROVIDERS.has(spec.provider) && LOCAL_OPENAI_COMPAT_PROVIDERS.has(spec.provider)) ||
+		hasLocalLoopbackBaseUrl(baseUrl);
 
 	const compat: ResolvedOpenAIResponsesCompat = {
 		supportsDeveloperRole: isAzure || isOpenAIUrl || hostMatchesUrl(baseUrl, "githubCopilot"),
@@ -675,7 +702,7 @@ export function buildOpenAIResponsesCompat(spec: OpenAIResponsesSpecLike): Resol
 		emptyLengthFinishIsContextError: spec.provider === "ollama",
 		usesOpenAIToolCallIdLimit: spec.provider === "openai",
 		promptCacheSessionHeader: spec.provider === "xai-oauth" ? "x-grok-conv-id" : undefined,
-		streamIdleTimeoutMs: isLocalOpenAICompatBackend
+		streamIdleTimeoutMs: isLocalServingBackend
 			? LOCAL_OPENAI_COMPAT_STREAM_IDLE_TIMEOUT_MS
 			: spec.compat?.streamIdleTimeoutMs,
 	};

package/src/discovery/codex.ts

@@ -1,6 +1,6 @@
 import { type } from "arktype";
 import { parseKnownModel, semverEqual } from "../identity/classify";
-import type { ModelSpec } from "../types";
+import type { FetchImpl, ModelSpec } from "../types";
 import { discoveryFetch } from "../utils";
 import { CODEX_BASE_URL, CODEX_CLIENT_VERSION, OPENAI_HEADER_VALUES, OPENAI_HEADERS } from "../wire/codex";
 
@@ -69,7 +69,7 @@ export interface CodexModelDiscoveryOptions {
 	/** Abort signal for network request cancellation. */
 	signal?: AbortSignal;
 	/** Optional fetch implementation override for tests. */
-	fetchFn?: typeof fetch;
+	fetchFn?: FetchImpl;
 }
 
 /**

package/src/model-cache.ts

@@ -7,16 +7,20 @@ import { getModelDbPath } from "@oh-my-pi/pi-utils";
 import type { Api, Model, ModelSpec } from "./types";
 
 // Rows persist ModelSpec JSON (sparse `compat`, never the resolved record);
-// the model manager rebuilds via `buildModel` on load. v9 invalidates Kimi
-// Code rows predating live effort and protocol metadata; v8 invalidated Codex
-// discovery rows predating provider-native V2 compaction metadata; v7
-// invalidated rows predating the Antigravity Gemini budget-mode migration
-// (cached specs still carrying `thinking.mode: "google-level"` and the old
-// 3.5-flash effort routing); v6 invalidated rows that may contain the retired
-// unknown-limit sentinels (222222/8888); v5 invalidated rows predating
+// the model manager rebuilds via `buildModel` on load. Request headers are
+// intentionally omitted: arbitrary provider-defined header names can carry
+// credentials. v10 deletes rows that may contain persisted headers and records
+// which model ids lost headers and which cannot be rebuilt from static inputs,
+// so the manager can restore the safe subset or refetch dynamic-only headers;
+// v9 invalidated Kimi Code rows predating live effort and protocol metadata;
+// v8 invalidated Codex discovery rows predating provider-native V2 compaction
+// metadata; v7 invalidated rows predating the Antigravity Gemini budget-mode
+// migration (cached specs still carrying `thinking.mode: "google-level"` and
+// the old 3.5-flash effort routing); v6 invalidated rows that may contain the
+// retired unknown-limit sentinels (222222/8888); v5 invalidated rows predating
 // effort-tier variant collapsing (raw `-low`/`-high`/`-thinking` member ids);
 // v4 dropped the pre-efforts ThinkingConfig shape.
-const CACHE_SCHEMA_VERSION = 9;
+const CACHE_SCHEMA_VERSION = 10;
 
 interface CacheRow {
 	provider_id: string;
@@ -25,6 +29,8 @@ interface CacheRow {
 	authoritative: number;
 	static_fingerprint: string;
 	models: string;
+	header_omitted_model_ids: string;
+	unrestorable_header_model_ids: string;
 }
 
 interface TableInfoRow {
@@ -36,6 +42,10 @@ interface CacheEntry<TApi extends Api = Api> {
 	fresh: boolean;
 	authoritative: boolean;
 	updatedAt: number;
+	/** Model ids whose live headers were intentionally omitted from disk. */
+	headerOmittedModelIds: readonly string[];
+	/** Header-bearing model ids that cannot be rebuilt from the static source. */
+	unrestorableHeaderModelIds: readonly string[];
 	/**
 	 * Hash of the static catalog slice that was merged into `models` when this
 	 * row was written. `resolveProviderModels` compares against the current
@@ -53,6 +63,10 @@ function openDb(resolvedPath: string): Database {
 	// Install the busy handler BEFORE any lock-taking statement. See
 	// https://github.com/can1357/oh-my-pi/issues/2421.
 	db.run("PRAGMA busy_timeout = 3000");
+	// Schema invalidation can delete rows containing credentials written by old
+	// versions. Overwrite deleted SQLite cells instead of leaving their bytes in
+	// free pages where a raw scan of models.db can still recover them (#5780).
+	db.run("PRAGMA secure_delete = ON");
 	db.run("PRAGMA journal_mode = WAL");
 	db.run(`
 		CREATE TABLE IF NOT EXISTS model_cache (
@@ -61,6 +75,8 @@ function openDb(resolvedPath: string): Database {
 			updated_at INTEGER NOT NULL,
 			authoritative INTEGER NOT NULL DEFAULT 0,
 			static_fingerprint TEXT NOT NULL DEFAULT '',
+			header_omitted_model_ids TEXT NOT NULL DEFAULT '[]',
+			unrestorable_header_model_ids TEXT NOT NULL DEFAULT '[]',
 			models TEXT NOT NULL
 		)
 	`);
@@ -99,6 +115,12 @@ function migrateCacheSchema(db: Database): void {
 		if (!columns.some(column => column.name === "static_fingerprint")) {
 			db.run("ALTER TABLE model_cache ADD COLUMN static_fingerprint TEXT NOT NULL DEFAULT ''");
 		}
+		if (!columns.some(column => column.name === "header_omitted_model_ids")) {
+			db.run("ALTER TABLE model_cache ADD COLUMN header_omitted_model_ids TEXT NOT NULL DEFAULT '[]'");
+		}
+		if (!columns.some(column => column.name === "unrestorable_header_model_ids")) {
+			db.run("ALTER TABLE model_cache ADD COLUMN unrestorable_header_model_ids TEXT NOT NULL DEFAULT '[]'");
+		}
 	} finally {
 		stmt.finalize();
 	}
@@ -125,6 +147,14 @@ export function readModelCache<TApi extends Api>(
 					return null;
 				}
 				const models = JSON.parse(row.models) as ModelSpec<TApi>[];
+				const parsedHeaderModelIds: unknown = JSON.parse(row.header_omitted_model_ids);
+				const headerOmittedModelIds = Array.isArray(parsedHeaderModelIds)
+					? parsedHeaderModelIds.filter((id): id is string => typeof id === "string")
+					: [];
+				const parsedUnrestorableModelIds: unknown = JSON.parse(row.unrestorable_header_model_ids);
+				const unrestorableHeaderModelIds = Array.isArray(parsedUnrestorableModelIds)
+					? parsedUnrestorableModelIds.filter((id): id is string => typeof id === "string")
+					: [];
 				const ageMs = now() - row.updated_at;
 				const fresh = Number.isFinite(ageMs) && ageMs >= 0 && ageMs <= ttlMs;
 				return {
@@ -132,6 +162,8 @@ export function readModelCache<TApi extends Api>(
 					fresh,
 					authoritative: row.authoritative === 1,
 					updatedAt: row.updated_at,
+					headerOmittedModelIds,
+					unrestorableHeaderModelIds,
 					staticFingerprint: row.static_fingerprint ?? "",
 				};
 			} finally {
@@ -143,6 +175,39 @@ export function readModelCache<TApi extends Api>(
 	}
 }
 
+/** Whether a live model carries at least one request header. */
+function hasModelHeaders(model: Model<Api>): boolean {
+	const headers = model.headers;
+	if (!headers) return false;
+	for (const _key in headers) return true;
+	return false;
+}
+
+/**
+ * Project a live model to cache-safe metadata.
+ *
+ * Headers are never persisted: custom/runtime providers may use arbitrary
+ * credential header names, so no name-based filter can be complete. The
+ * separately persisted model-id list lets the manager restore matching static
+ * headers and reject/refetch dynamic-only cached models that need live headers.
+ */
+function toCachedModelSpec<TApi extends Api>(model: Model<TApi>): ModelSpec<TApi> {
+	const { headers: _headers, compatConfig, ...rest } = model;
+	return { ...rest, compat: compatConfig };
+}
+
+/** Whether two in-memory header records are byte-for-byte equivalent. */
+function headersEqual(left: Record<string, string> | undefined, right: Record<string, string> | undefined): boolean {
+	if (!left || !right) return left === right;
+	for (const key in left) {
+		if (right[key] !== left[key]) return false;
+	}
+	for (const key in right) {
+		if (!(key in left)) return false;
+	}
+	return true;
+}
+
 export function writeModelCache<TApi extends Api>(
 	providerId: string,
 	updatedAt: number,
@@ -150,19 +215,37 @@ export function writeModelCache<TApi extends Api>(
 	authoritative: boolean,
 	staticFingerprint: string,
 	dbPath?: string,
+	staticHeaderSources: readonly Model<TApi>[] = [],
 ): void {
 	try {
 		withModelCacheDb(dbPath, db => {
+			const headerOmittedModelIds: string[] = [];
+			const unrestorableHeaderModelIds: string[] = [];
+			const cachedModels: ModelSpec<TApi>[] = [];
+			const staticById = new Map(staticHeaderSources.map(model => [model.id, model]));
+			for (const model of models) {
+				if (hasModelHeaders(model)) {
+					headerOmittedModelIds.push(model.id);
+					if (!headersEqual(model.headers, staticById.get(model.id)?.headers)) {
+						unrestorableHeaderModelIds.push(model.id);
+					}
+				}
+				cachedModels.push(toCachedModelSpec(model));
+			}
 			db.run(
-				`INSERT OR REPLACE INTO model_cache (provider_id, version, updated_at, authoritative, static_fingerprint, models)
-				 VALUES (?, ?, ?, ?, ?, ?)`,
+				`INSERT OR REPLACE INTO model_cache (
+					provider_id, version, updated_at, authoritative, static_fingerprint,
+					header_omitted_model_ids, unrestorable_header_model_ids, models
+				) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
 				[
 					providerId,
 					CACHE_SCHEMA_VERSION,
 					updatedAt,
 					authoritative ? 1 : 0,
 					staticFingerprint,
-					JSON.stringify(models.map(model => ({ ...model, compat: model.compatConfig, compatConfig: undefined }))),
+					JSON.stringify(headerOmittedModelIds),
+					JSON.stringify(unrestorableHeaderModelIds),
+					JSON.stringify(cachedModels),
 				],
 			);
 		});

package/src/model-manager.ts

@@ -100,6 +100,47 @@ function passModelList<TApi extends Api>(value: unknown): Model<TApi>[] {
 	}
 	return out;
 }
+interface CachedHeaderRestoreResult<TApi extends Api> {
+	models: Model<TApi>[];
+	unresolvedModelIds: ReadonlySet<string>;
+}
+
+/**
+ * Restore cache-omitted headers from the current static source.
+ *
+ * Dynamic-only header-bearing models cannot be reconstructed safely without
+ * persisting arbitrary credential values; callers must refetch them online or
+ * omit them from an offline result rather than return a broken model.
+ */
+function restoreCachedModelHeaders<TApi extends Api>(
+	cachedModels: readonly ModelSpec<TApi>[],
+	staticModels: readonly Model<TApi>[],
+	headerOmittedModelIds: readonly string[],
+	unrestorableHeaderModelIds: readonly string[],
+): CachedHeaderRestoreResult<TApi> {
+	const models = passModelList<TApi>(cachedModels);
+	if (headerOmittedModelIds.length === 0) {
+		return { models, unresolvedModelIds: new Set() };
+	}
+	const omittedIds = new Set(headerOmittedModelIds);
+	const unrestorableIds = new Set(unrestorableHeaderModelIds);
+	const staticById = new Map(staticModels.map(model => [model.id, model]));
+	const unresolvedModelIds = new Set<string>();
+	const restored = models.map(model => {
+		if (!omittedIds.has(model.id)) return model;
+		if (unrestorableIds.has(model.id)) {
+			unresolvedModelIds.add(model.id);
+			return model;
+		}
+		const staticModel = staticById.get(model.id);
+		if (!staticModel?.headers) {
+			unresolvedModelIds.add(model.id);
+			return model;
+		}
+		return { ...model, headers: staticModel.headers };
+	});
+	return { models: restored, unresolvedModelIds };
+}
 
 /**
  * Resolves provider models with source precedence:
@@ -119,10 +160,19 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 		? passModelList<TApi>(options.staticModels)
 		: (getBundledModels(options.providerId as GeneratedProvider) as Model<TApi>[]);
 	const cache = readModelCache<TApi>(cacheProviderId, ttlMs, now, dbPath);
+	const restoredCache = restoreCachedModelHeaders(
+		cache?.models ?? [],
+		staticModels,
+		cache?.headerOmittedModelIds ?? [],
+		cache?.unrestorableHeaderModelIds ?? [],
+	);
+	const usableCachedModels = restoredCache.models.filter(model => !restoredCache.unresolvedModelIds.has(model.id));
+	const cacheHasUnresolvedHeaders = restoredCache.unresolvedModelIds.size > 0;
 	const dynamicModelsAuthoritative = options.dynamicModelsAuthoritative ?? false;
 	const staticFingerprint = fingerprintStatic(staticModels, dynamicModelsAuthoritative);
 	const cacheFingerprintMatches = cache?.staticFingerprint === staticFingerprint && staticFingerprint.length > 0;
-	const hasUsableFreshCache = (cache?.fresh ?? false) && (!dynamicModelsAuthoritative || cacheFingerprintMatches);
+	const hasUsableFreshCache =
+		(cache?.fresh ?? false) && !cacheHasUnresolvedHeaders && (!dynamicModelsAuthoritative || cacheFingerprintMatches);
 	const dynamicFetcher = options.fetchDynamicModels;
 	const hasDynamicFetcher = typeof dynamicFetcher === "function";
 	const hasAuthoritativeCache = ((cache?.authoritative ?? false) && hasUsableFreshCache) || !hasDynamicFetcher;
@@ -139,8 +189,14 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 	// was merged in last time, the cache row IS the authoritative merge result.
 	// Re-running `mergeDynamicModels(static, cache)` would just rebuild the same
 	// objects (~800ms in the steady-state cold-start profile for `omp -p hi`).
-	if (!shouldFetchFromNetwork && cache?.fresh && hasAuthoritativeCache && cacheFingerprintMatches) {
-		return { models: collapseBuiltModelVariants(passModelList<TApi>(cache.models)), stale: false };
+	if (
+		!shouldFetchFromNetwork &&
+		cache?.fresh &&
+		hasAuthoritativeCache &&
+		cacheFingerprintMatches &&
+		!cacheHasUnresolvedHeaders
+	) {
+		return { models: collapseBuiltModelVariants(restoredCache.models), stale: false };
 	}
 
 	const [fetchedModelsDevModels, fetchedDynamicModels] = shouldFetchFromNetwork
@@ -153,7 +209,7 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 	const cacheModels = dynamicFetchSucceeded
 		? []
 		: prepareCacheModelsForStaticMismatch(
-				normalizeModelList<TApi>(cache?.models ?? []),
+				usableCachedModels,
 				staticModels,
 				cacheFingerprintMatches,
 				options.dropCachedModelIdsOnStaticMismatch,
@@ -178,11 +234,21 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 				true,
 				staticFingerprint,
 				dbPath,
+				staticModels,
 			);
 		} else {
 			// Dynamic fetch failed — update cache with a non-authoritative snapshot so
 			// stale state remains visible while retry backoff still applies.
 			const latestCache = readModelCache<TApi>(cacheProviderId, ttlMs, now, dbPath);
+			const latestRestoredCache = restoreCachedModelHeaders(
+				latestCache?.models ?? cache?.models ?? [],
+				staticModels,
+				latestCache?.headerOmittedModelIds ?? cache?.headerOmittedModelIds ?? [],
+				latestCache?.unrestorableHeaderModelIds ?? cache?.unrestorableHeaderModelIds ?? [],
+			);
+			const latestUsableCacheModels = latestRestoredCache.models.filter(
+				model => !latestRestoredCache.unresolvedModelIds.has(model.id),
+			);
 			writeModelCache(
 				cacheProviderId,
 				now(),
@@ -190,7 +256,7 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 					mergeDynamicModels(
 						mergeModelSources(staticModels, modelsDevModels),
 						prepareCacheModelsForStaticMismatch(
-							normalizeModelList<TApi>(latestCache?.models ?? cache?.models ?? []),
+							latestUsableCacheModels,
 							staticModels,
 							cacheFingerprintMatches,
 							options.dropCachedModelIdsOnStaticMismatch,
@@ -200,6 +266,7 @@ export async function resolveProviderModels<TApi extends Api = Api, TModelsDevPa
 				false,
 				staticFingerprint,
 				dbPath,
+				staticModels,
 			);
 		}
 	}