pi-cache-optimizer 2.8.6 → 2.8.8

package/index.ts

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { chmod, copyFile, lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { constants as fsConstants, readFileSync, statSync, watch } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import {
   getAgentDir,
   type BuildSystemPromptOptions,
@@ -80,6 +80,8 @@ const STARTUP_CACHE_RETENTION_ENV = getOrCaptureCacheRetentionBaseline();
  * 2. Sets PI_CACHE_RETENTION=long at extension load time.
  * 3. Warns once for provider/model cache compat gaps where the signal is conservative.
  * 4. Shows lightweight persisted provider-specific cache stats in Pi's footer.
+ * 5. Offers disabled-by-default deterministic built-in tool ordering when
+ *    explicitly opted in.
  *
  * Provider prompt/KV caches are provider-side and best-effort. This extension improves
  * the odds of cache hits; it cannot guarantee hits, especially through proxies.
@@ -112,6 +114,13 @@ const SHARD_GLOBAL_EPOCH_PATH = join(SHARD_EPOCH_DIR, "global.json");
 const SHARD_CLEANUP_LOCK_PATH = join(SHARD_MAINTENANCE_DIR, "cleanup.lock");
 const SHARD_CLEANUP_MARKER_PATH = join(SHARD_MAINTENANCE_DIR, "last-cleanup");
 const CONFIG_FILE_PATH = join(STATE_DIR, "pi-cache-optimizer-config.json");
+const CONFIG_RECEIPT_FILE_NAME = "pi-cache-optimizer-config-receipt.json";
+const CONFIG_RECEIPT_PATH = join(STATE_DIR, CONFIG_RECEIPT_FILE_NAME);
+const FIX_RECEIPT_FILE_NAME = "pi-cache-optimizer-fix-receipt.json";
+const FIX_RECEIPT_PATH = join(STATE_DIR, FIX_RECEIPT_FILE_NAME);
+const MODELS_TRANSACTION_LOCK_PATH = join(STATE_DIR, "pi-cache-optimizer-models-transaction.lock");
+const MODELS_TRANSACTION_LOCK_STALE_MS = 60_000;
+const MODELS_TRANSACTION_LOCK_WAIT_MS = 5_000;
 const SHARD_RETENTION_MS = 48 * 60 * 60 * 1000;
 const SHARD_TEMP_RETENTION_MS = 24 * 60 * 60 * 1000;
 const SHARD_CLEANUP_INTERVAL_MS = 6 * 60 * 60 * 1000;
@@ -122,17 +131,84 @@ const NO_OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY";
 const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
 const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
 const NO_PROMPT_REWRITE_ENV = "PI_CACHE_OPTIMIZER_NO_PROMPT_REWRITE";
+const TOOL_ORDER_ENV = "PI_CACHE_OPTIMIZER_TOOL_ORDER";
 const FOOTER_MODE_ENV = "PI_CACHE_OPTIMIZER_FOOTER_MODE";
 type FooterStatsMode = "session" | "total" | "process";
+type FixReceiptPlacement = "provider" | "model" | "modelOverride";
+type ReceiptScalar = string | number | boolean | null;
+type ReceiptScalarState =
+  | { present: false }
+  | { present: true; value: ReceiptScalar };
+type FixReceiptCompatChange = {
+  before: ReceiptScalarState;
+  after: ReceiptScalarState;
+};
+type ModelsJsonFixReceiptV1 = {
+  version: 1;
+  kind: "pi-cache-optimizer-fix-receipt";
+  transactionId: string;
+  provider: string;
+  modelId: string;
+  placement: FixReceiptPlacement;
+  targetExistedBefore: boolean;
+  changedKeys: Record<string, FixReceiptCompatChange>;
+  beforeHash: string;
+  afterHash: string;
+  backupFile: string;
+  createdAt: number;
+  appliedAt: number;
+  status?: "rolled_back";
+  rolledBackAt?: number;
+};
+
+// Receipts are trusted input to a later rollback command, so their key set is
+// deliberately narrower than the full models.json compat vocabulary. This
+// prevents a corrupted or hand-edited receipt from turning rollback into a
+// way to rewrite credentials, headers, routing, or arbitrary provider fields.
+const RECEIPT_COMPAT_KEYS = new Set([
+  "sendSessionAffinityHeaders",
+  "supportsLongCacheRetention",
+  "requiresReasoningContentOnAssistantMessages",
+  "forceAdaptiveThinking",
+  "allowEmptySignature",
+  "thinkingFormat",
+  "supportsReasoningEffort",
+]);
 type FooterStatsModeSource = "config" | "env" | "default";
 type PersistedCacheOptimizerConfigV1 = {
   version: 1;
   footerMode?: FooterStatsMode;
 };
+type PersistedCacheOptimizerConfigV2 = {
+  version: 2;
+  footerMode?: FooterStatsMode;
+  promptCacheKey?: {
+    omit?: string[];
+  };
+};
+type PersistedCacheOptimizerConfig = PersistedCacheOptimizerConfigV1 | PersistedCacheOptimizerConfigV2;
+type PromptCacheKeyConfigReceipt = {
+  version: 2;
+  kind: "pi-cache-optimizer-config-receipt";
+  transactionId: string;
+  provider: string;
+  modelId: string;
+  beforeHash: string;
+  afterHash: string;
+  backupFile: string;
+  targetExistedBefore: boolean;
+  targetHadModelKey: boolean;
+  addedModelKey: string;
+  createdAt: number;
+  appliedAt: number;
+  status?: "rolled_back";
+  rolledBackAt?: number;
+};
 const PI_ROUTING_REGISTRY_SYMBOL = Symbol.for("pi.routing.registry.v1");
 const PI_CACHE_HINTS_SYMBOL = Symbol.for("pi.cache.hints.v1");
 const PI_CACHE_HINTS_OWNER_SYMBOL = Symbol.for("pi.cache.optimizer.hints-owner.v1");
 const ANTHROPIC_TTL_FALLBACK_SYMBOL = Symbol.for("pi.cache.optimizer.anthropic-ttl-fallback.v1");
+const REASONING_PROTOCOL_FALLBACK_SYMBOL = Symbol.for("pi.cache.optimizer.reasoning-protocol-fallback.v1");
 
 type AnthropicTtlFallbackStateV1 = {
   version: 1;
@@ -140,6 +216,31 @@ type AnthropicTtlFallbackStateV1 = {
   warnedModelKeys: Set<string>;
 };
 
+type ReasoningProtocolFallbackStateV1 = {
+  version: 1;
+  modelKeys: Set<string>;
+  warnedModelKeys: Set<string>;
+};
+
+function getReasoningProtocolFallbackState(): ReasoningProtocolFallbackStateV1 {
+  const globals = globalThis as Record<symbol, unknown>;
+  const existing = globals[REASONING_PROTOCOL_FALLBACK_SYMBOL] as Partial<ReasoningProtocolFallbackStateV1> | undefined;
+  if (
+    existing?.version === 1 &&
+    existing.modelKeys instanceof Set &&
+    existing.warnedModelKeys instanceof Set
+  ) {
+    return existing as ReasoningProtocolFallbackStateV1;
+  }
+  const state: ReasoningProtocolFallbackStateV1 = {
+    version: 1,
+    modelKeys: new Set<string>(),
+    warnedModelKeys: new Set<string>(),
+  };
+  globals[REASONING_PROTOCOL_FALLBACK_SYMBOL] = state;
+  return state;
+}
+
 function getAnthropicTtlFallbackState(): AnthropicTtlFallbackStateV1 {
   const globals = globalThis as Record<symbol, unknown>;
   const existing = globals[ANTHROPIC_TTL_FALLBACK_SYMBOL] as Partial<AnthropicTtlFallbackStateV1> | undefined;
@@ -391,6 +492,15 @@ type OptimizedSystemPrompt = {
   changed: boolean;
 };
 
+type ToolOrderApi =
+  | "openai-completions"
+  | "openai-responses"
+  | "anthropic-messages"
+  | "google-generative-ai"
+  | "google-vertex"
+  | "bedrock-converse-stream";
+
+
 /**
  * Per-request sample stored for trend analysis and usage-field-missing detection.
  * Contains only numeric counters and booleans — never message content, prompts,
@@ -481,6 +591,205 @@ function isStableContextFilePath(filePath: string): boolean {
   );
 }
 
+function isKnownToolOrderApi(api: unknown): api is ToolOrderApi {
+  return api === "openai-completions" || api === "openai-responses" ||
+    api === "anthropic-messages" || api === "google-generative-ai" ||
+    api === "google-vertex" || api === "bedrock-converse-stream";
+}
+
+function isToolOrderingEligibleModel(model: PiModel | undefined): boolean {
+  // Responses/Codex prompt bypasses remain untouched. The pure helper still
+  // supports the verified Responses shape for fixture use, but the request
+  // hook must preserve Pi's server-managed/safety-sensitive bypass.
+  return !!model && isKnownToolOrderApi(model.api) && !isResponsesPromptRewriteBypassApi(model.api);
+}
+
+function getToolNameForPayload(tool: unknown): string | undefined {
+  const record = asRecord(tool);
+  if (!record) return undefined;
+  if (isNonEmptyString(record.name)) return record.name;
+  const fn = asRecord(record.function);
+  if (isNonEmptyString(fn?.name)) return fn.name;
+  const custom = asRecord(record.custom);
+  if (isNonEmptyString(custom?.name)) return custom.name;
+  const spec = asRecord(record.toolSpec);
+  if (isNonEmptyString(spec?.name)) return spec.name;
+  return undefined;
+}
+
+function compareToolOrderEntries(
+  left: { name: string; index: number },
+  right: { name: string; index: number },
+): number {
+  // Do not use localeCompare here: its result can vary with the host locale.
+  // Exact UTF-16 code-unit ordering plus the original index is reproducible.
+  return left.name < right.name ? -1 : left.name > right.name ? 1 : left.index - right.index;
+}
+
+function isJsonObject(value: unknown): value is UnknownRecord {
+  return asRecord(value) !== undefined;
+}
+
+function isVerifiedToolForApi(tool: unknown, api: ToolOrderApi): tool is UnknownRecord {
+  const record = asRecord(tool);
+  if (!record) return false;
+
+  if (api === "openai-completions") {
+    if (record.type === "function") {
+      const fn = asRecord(record.function);
+      return isNonEmptyString(fn?.name) && isJsonObject(fn.parameters);
+    }
+    if (record.type === "custom") {
+      const custom = asRecord(record.custom);
+      return isNonEmptyString(custom?.name) && isJsonObject(custom.format);
+    }
+    return false;
+  }
+
+  if (api === "openai-responses") {
+    if (record.type === "function") {
+      return isNonEmptyString(record.name) && isJsonObject(record.parameters);
+    }
+    if (record.type === "custom") {
+      return isNonEmptyString(record.name) && isJsonObject(record.format);
+    }
+    return false;
+  }
+
+  if (api === "anthropic-messages") {
+    return isNonEmptyString(record.name) && isJsonObject(record.input_schema);
+  }
+
+  if (api === "google-generative-ai" || api === "google-vertex") {
+    return isNonEmptyString(record.name) &&
+      (isJsonObject(record.parametersJsonSchema) || isJsonObject(record.parameters));
+  }
+
+  const spec = asRecord(record.toolSpec);
+  const inputSchema = asRecord(spec?.inputSchema);
+  return isNonEmptyString(spec?.name) && isJsonObject(inputSchema?.json);
+}
+
+type ToolArrayInspection = {
+  sortedIndices: number[];
+  changed: boolean;
+};
+
+function hasTopLevelCacheControl(tools: unknown): boolean {
+  return Array.isArray(tools) && tools.some((tool) => {
+    const record = asRecord(tool);
+    return !!record && Object.prototype.hasOwnProperty.call(record, "cache_control");
+  });
+}
+
+function inspectToolArray(tools: unknown, api: ToolOrderApi): ToolArrayInspection | undefined {
+  if (!Array.isArray(tools)) return undefined;
+  // Native Anthropic and OpenAI-compatible transports can attach a cache
+  // breakpoint to a specific tool (normally the final one). Never move it,
+  // regardless of API id. Anthropic defer_loading also encodes immediate vs
+  // deferred tool groups in array order, so mixed/grouped payloads are no-ops.
+  if (hasTopLevelCacheControl(tools)) return undefined;
+  if (api === "anthropic-messages" && tools.some((tool) => {
+    const record = asRecord(tool);
+    return !!record && Object.prototype.hasOwnProperty.call(record, "defer_loading");
+  })) return undefined;
+  const entries = tools.map((tool, index) => {
+    if (!isVerifiedToolForApi(tool, api)) return undefined;
+    return { name: getToolNameForPayload(tool) ?? "", index };
+  });
+  if (entries.some((entry) => entry === undefined)) return undefined;
+
+  const verified = entries as Array<{ name: string; index: number }>;
+  const sorted = [...verified].sort(compareToolOrderEntries);
+  return {
+    sortedIndices: sorted.map((entry) => entry.index),
+    changed: sorted.some((entry, index) => entry.index !== index),
+  };
+}
+
+type ToolArrayPath = {
+  kind: "root" | "bedrock" | "google";
+  groupIndex?: number;
+  sortedIndices: number[];
+};
+
+/**
+ * Pure deterministic tool-order normalizer for the exact payload shapes
+ * emitted by Pi's built-in transports. It returns the original object for a
+ * no-op/unsupported/malformed payload and shallow-clones only the verified
+ * path to a tool array when sorting is needed. Tool objects and unrelated
+ * request fields (including SDK objects and AbortSignal) retain their identity.
+ */
+function normalizeToolsInPayload(
+  payload: unknown,
+  api: unknown,
+): { payload: unknown; changed: boolean } {
+  if (!isKnownToolOrderApi(api)) return { payload, changed: false };
+  const root = asRecord(payload);
+  if (!root) return { payload, changed: false };
+
+  if (api === "google-generative-ai" || api === "google-vertex") {
+    const config = asRecord(root.config);
+    const groups = config?.tools;
+    if (!Array.isArray(groups) || groups.length === 0) return { payload, changed: false };
+
+    const paths: ToolArrayPath[] = [];
+    for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+      const group = asRecord(groups[groupIndex]);
+      if (!group || !Array.isArray(group.functionDeclarations)) return { payload, changed: false };
+      const inspected = inspectToolArray(group.functionDeclarations, api);
+      if (!inspected) return { payload, changed: false };
+      if (inspected.changed) paths.push({ kind: "google", groupIndex, sortedIndices: inspected.sortedIndices });
+    }
+    if (paths.length === 0) return { payload, changed: false };
+
+    const sortedGroups = [...groups];
+    for (const path of paths) {
+      const groupIndex = path.groupIndex!;
+      const group = asRecord(groups[groupIndex])!;
+      const tools = group.functionDeclarations as unknown[];
+      sortedGroups[groupIndex] = {
+        ...group,
+        functionDeclarations: path.sortedIndices.map((index) => tools[index]),
+      };
+    }
+    return {
+      payload: { ...root, config: { ...config, tools: sortedGroups } },
+      changed: true,
+    };
+  }
+
+  if (api === "bedrock-converse-stream") {
+    const toolConfig = asRecord(root.toolConfig);
+    const tools = toolConfig?.tools;
+    const inspected = inspectToolArray(tools, api);
+    if (!inspected || !inspected.changed || !Array.isArray(tools)) return { payload, changed: false };
+    return {
+      payload: {
+        ...root,
+        toolConfig: {
+          ...toolConfig,
+          tools: inspected.sortedIndices.map((index) => tools[index]),
+        },
+      },
+      changed: true,
+    };
+  }
+
+  const tools = root.tools;
+  const inspected = inspectToolArray(tools, api);
+  if (!inspected || !inspected.changed || !Array.isArray(tools)) return { payload, changed: false };
+  return {
+    payload: { ...root, tools: inspected.sortedIndices.map((index) => tools[index]) },
+    changed: true,
+  };
+}
+
+/** Public test-facing alias: a pure payload transformation. */
+function sortToolsInPayload(payload: unknown, api: unknown): unknown {
+  return normalizeToolsInPayload(payload, api).payload;
+}
+
 function formatSkillsForPrompt(skills: NonNullable<BuildSystemPromptOptions["skills"]>): string {
   const visibleSkills = skills.filter((skill) => !skill.disableModelInvocation);
   if (visibleSkills.length === 0) return "";
@@ -1039,15 +1348,21 @@ function routeSnapshotToPiModel(snapshot: PiRouteSnapshot, fallback?: PiModel):
 }
 
 function findModelInRegistry(registry: ModelRegistryLike | undefined, provider: string, id: string): PiModel | undefined {
-  const found = registry?.find?.(provider, id);
-  if (found) return found;
+  try {
+    const found = registry?.find?.(provider, id);
+    if (found) return found;
 
-  const available = registry?.getAvailable?.() ?? [];
-  const availableMatch = available.find((candidate) => candidate.provider === provider && candidate.id === id);
-  if (availableMatch) return availableMatch;
+    const available = registry?.getAvailable?.() ?? [];
+    const availableMatch = available.find((candidate) => candidate.provider === provider && candidate.id === id);
+    if (availableMatch) return availableMatch;
 
-  const all = registry?.getAll?.() ?? [];
-  return all.find((candidate) => candidate.provider === provider && candidate.id === id);
+    const all = registry?.getAll?.() ?? [];
+    return all.find((candidate) => candidate.provider === provider && candidate.id === id);
+  } catch {
+    // Registry extensions are optional input; a malformed/throwing registry
+    // must not turn a provider error hook into a Pi session failure.
+    return undefined;
+  }
 }
 
 function isRoutedFallbackModel(model: PiModel | undefined): boolean {
@@ -1549,6 +1864,10 @@ function isEnabledEnv(value: string | undefined): boolean {
   return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
 }
 
+function isToolOrderEnabled(env: MutableEnv = process.env): boolean {
+  return runtimeOptimizerEnabled && isEnabledEnv(env[TOOL_ORDER_ENV]);
+}
+
 function parseFooterStatsMode(value: unknown): FooterStatsMode | undefined {
   if (typeof value !== "string") return undefined;
   const normalized = value.trim().toLowerCase();
@@ -1570,10 +1889,12 @@ const CACHE_OPTIMIZER_COMMANDS = [
   "compat",
   "reset",
   "fix",
+  "rollback",
 ] as const;
 const CACHE_OPTIMIZER_CONFIG_ARGUMENTS = ["footer-mode"] as const;
 const CACHE_OPTIMIZER_FOOTER_MODES = ["total", "session", "process"] as const;
 const CACHE_OPTIMIZER_STATS_ARGUMENTS = ["all", "contributors"] as const;
+const CACHE_OPTIMIZER_FIX_ARGUMENTS = ["prompt-cache-key"] as const;
 
 function filterCommandCompletionItems(
   values: readonly string[],
@@ -1624,6 +1945,12 @@ function getCacheOptimizerArgumentCompletions(argumentPrefix: string): CommandCo
       : null;
   }
 
+  if (parts[0].toLowerCase() === "fix") {
+    return parts.length === 2
+      ? filterCommandCompletionItems(CACHE_OPTIMIZER_FIX_ARGUMENTS, parts[1], "fix")
+      : null;
+  }
+
   if (parts[0].toLowerCase() !== "config") return null;
 
   if (parts.length === 2) {
@@ -1641,36 +1968,368 @@ function getCacheOptimizerArgumentCompletions(argumentPrefix: string): CommandCo
   return null;
 }
 
-function parsePersistedCacheOptimizerConfig(value: unknown): PersistedCacheOptimizerConfigV1 | undefined {
+function parsePersistedCacheOptimizerConfig(value: unknown): PersistedCacheOptimizerConfig | undefined {
   const record = asRecord(value);
-  if (!record || record.version !== 1) return undefined;
+  if (!record || (record.version !== 1 && record.version !== 2)) return undefined;
+  const allowedTopLevel = new Set(record.version === 1 ? ["version", "footerMode"] : ["version", "footerMode", "promptCacheKey"]);
+  if (Object.keys(record).some((key) => !allowedTopLevel.has(key))) return undefined;
   const footerMode = parseFooterStatsMode(record.footerMode);
   if (record.footerMode !== undefined && !footerMode) return undefined;
-  return { version: 1, ...(footerMode ? { footerMode } : {}) };
+  if (record.version === 1) return { version: 1, ...(footerMode ? { footerMode } : {}) };
+
+  const rawPromptCacheKey = record.promptCacheKey;
+  if (rawPromptCacheKey !== undefined && !asRecord(rawPromptCacheKey)) return undefined;
+  const promptCacheKey = asRecord(rawPromptCacheKey);
+  if (promptCacheKey && Object.keys(promptCacheKey).some((key) => key !== "omit")) return undefined;
+  const omit = promptCacheKey?.omit;
+  if (omit !== undefined && (!Array.isArray(omit) || omit.some((value): value is string => !isNonEmptyString(value)))) return undefined;
+  const stringOmit = omit as string[] | undefined;
+  const uniqueOmit = stringOmit ? [...new Set(stringOmit.map((value) => value.trim()))].sort() : undefined;
+  return {
+    version: 2,
+    ...(footerMode ? { footerMode } : {}),
+    ...(uniqueOmit && uniqueOmit.length > 0 ? { promptCacheKey: { omit: uniqueOmit } } : {}),
+  };
+}
+
+function normalizePersistedCacheOptimizerConfig(value: PersistedCacheOptimizerConfig | undefined): PersistedCacheOptimizerConfigV2 {
+  if (!value) return { version: 2 };
+  return value.version === 2
+    ? value
+    : { version: 2, ...(value.footerMode ? { footerMode: value.footerMode } : {}) };
+}
+
+function readPersistedCacheOptimizerConfig(configPath: string = CONFIG_FILE_PATH): PersistedCacheOptimizerConfigV2 {
+  try {
+    return normalizePersistedCacheOptimizerConfig(parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8"))));
+  } catch (error) {
+    if (getErrorCode(error) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to read optimizer config; using defaults`, error);
+    return { version: 2 };
+  }
 }
 
 function readPersistedFooterMode(configPath: string = CONFIG_FILE_PATH): FooterStatsMode | undefined {
+  return readPersistedCacheOptimizerConfig(configPath).footerMode;
+}
+
+async function writePersistedCacheOptimizerConfigUnlocked(
+  config: PersistedCacheOptimizerConfigV2,
+  configPath: string,
+): Promise<void> {
+  await mkdir(dirname(configPath), { recursive: true });
+  const payloadText = JSON.stringify(normalizePersistedCacheOptimizerConfig(config), null, 2) + "\n";
+  let targetInfo: Awaited<ReturnType<typeof lstat>> | undefined;
+  let targetMode = 0o600;
+  let targetHash: string | undefined;
   try {
-    const parsed = parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8")));
-    if (!parsed) throw new Error("invalid footer config schema");
-    return parsed.footerMode;
+    targetInfo = await lstat(configPath);
+    if (targetInfo.isSymbolicLink() || !targetInfo.isFile()) throw new Error("optimizer config is not a regular file; no changes were made");
+    const targetText = await readFile(configPath, "utf8");
+    targetMode = targetInfo.mode & 0o7777;
+    targetHash = hashText(targetText);
   } catch (error) {
-    if (getErrorCode(error) !== "ENOENT") {
-      console.warn(`${LOG_PREFIX}: failed to read footer config; using environment/default mode`, error);
+    if (getErrorCode(error) !== "ENOENT") throw error;
+  }
+  if (targetInfo) {
+    await atomicReplaceTextFilePreservingMode(configPath, payloadText, targetMode, "config", {
+      identity: targetInfo,
+      hash: targetHash,
+      mode: targetMode,
+    });
+    return;
+  }
+
+  const tempPath = uniqueTempPath(configPath, "config");
+  try {
+    await writeFile(tempPath, payloadText, { encoding: "utf8", mode: targetMode, flag: "wx" });
+    await chmod(tempPath, targetMode);
+    try {
+      await lstat(configPath);
+      throw new Error("optimizer config appeared during write; no changes were made");
+    } catch (error) {
+      if (getErrorCode(error) !== "ENOENT") throw error;
     }
-    return undefined;
+    await rename(tempPath, configPath);
+  } catch (error) {
+    await unlink(tempPath).catch((cleanupError) => { if (getErrorCode(cleanupError) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove temporary config`, cleanupError); });
+    throw error;
+  }
+}
+
+async function writePersistedCacheOptimizerConfig(
+  config: PersistedCacheOptimizerConfigV2,
+  configPath: string = CONFIG_FILE_PATH,
+): Promise<void> {
+  await withModelsJsonTransactionLock(() => writePersistedCacheOptimizerConfigUnlocked(config, configPath));
+}
+
+async function writePersistedFooterModeUnlocked(
+  mode: FooterStatsMode,
+  configPath: string,
+): Promise<void> {
+  let version: 1 | 2 = 1;
+  let raw: PersistedCacheOptimizerConfig | undefined;
+  let targetExists = false;
+  try {
+    raw = parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8")));
+    targetExists = true;
+    if (!raw) throw new Error("invalid footer config schema");
+    version = raw.version === 2 ? 2 : 1;
+  } catch (error) {
+    if (getErrorCode(error) !== "ENOENT") throw new Error("invalid footer config schema");
+  }
+  const current = normalizePersistedCacheOptimizerConfig(raw);
+  if (version === 1 && !current.promptCacheKey) {
+    await mkdir(dirname(configPath), { recursive: true });
+    const targetInfo = targetExists ? await lstat(configPath) : undefined;
+    if (targetInfo && (targetInfo.isSymbolicLink() || !targetInfo.isFile())) throw new Error("optimizer config is not a regular file; no changes were made");
+    const targetText = targetInfo ? await readFile(configPath, "utf8") : undefined;
+    const targetMode = targetInfo ? targetInfo.mode & 0o7777 : 0o600;
+    const tempPath = uniqueTempPath(configPath, "config-footer");
+    try {
+      await writeFile(tempPath, JSON.stringify({ version: 1, footerMode: mode }, null, 2) + "\n", { encoding: "utf8", mode: targetMode, flag: "wx" });
+      await chmod(tempPath, targetMode);
+      if (targetInfo && targetText !== undefined) {
+        await validateAtomicTarget(configPath, { identity: targetInfo, hash: hashText(targetText), mode: targetMode });
+      } else {
+        try {
+          await lstat(configPath);
+          throw new Error("optimizer config appeared during footer write; no changes were made");
+        } catch (error) {
+          if (getErrorCode(error) !== "ENOENT") throw error;
+        }
+      }
+      await rename(tempPath, configPath);
+    } catch (error) {
+      await unlink(tempPath).catch(() => {});
+      throw error;
+    }
+    return;
   }
+  await writePersistedCacheOptimizerConfigUnlocked({ ...current, version: 2, footerMode: mode }, configPath);
 }
 
 async function writePersistedFooterMode(
   mode: FooterStatsMode,
   configPath: string = CONFIG_FILE_PATH,
 ): Promise<void> {
+  await withModelsJsonTransactionLock(() => writePersistedFooterModeUnlocked(mode, configPath));
+}
+
+function configReceiptBackupPath(receipt: PromptCacheKeyConfigReceipt, receiptPath: string = CONFIG_RECEIPT_PATH): string {
+  return join(dirname(receiptPath), receipt.backupFile);
+}
+
+function parsePromptCacheKeyConfigReceipt(value: unknown): PromptCacheKeyConfigReceipt | undefined {
+  const record = asRecord(value);
+  if (!record || (record.version !== 1 && record.version !== 2) || record.kind !== "pi-cache-optimizer-config-receipt") return undefined;
+  const allowed = new Set(record.version === 1
+    ? ["version", "kind", "transactionId", "provider", "modelId", "beforeHash", "afterHash", "backupFile", "targetExistedBefore", "createdAt", "appliedAt", "status", "rolledBackAt"]
+    : ["version", "kind", "transactionId", "provider", "modelId", "beforeHash", "afterHash", "backupFile", "targetExistedBefore", "targetHadModelKey", "addedModelKey", "createdAt", "appliedAt", "status", "rolledBackAt"]);
+  if (Object.keys(record).some((key) => !allowed.has(key))) return undefined;
+  if (![record.transactionId, record.provider, record.modelId].every(isSafeReceiptText)) return undefined;
+  if (!isSha256(record.beforeHash) || !isSha256(record.afterHash) || record.beforeHash === record.afterHash) return undefined;
+  if (!isSafeReceiptText(record.backupFile) || basename(record.backupFile) !== record.backupFile || !record.backupFile.startsWith("pi-cache-optimizer-config.backup-")) return undefined;
+  if (typeof record.targetExistedBefore !== "boolean" || !isReceiptTimestamp(record.createdAt) || !isReceiptTimestamp(record.appliedAt)) return undefined;
+  const addedModelKey = `${record.provider}/${record.modelId}`;
+  const targetHadModelKey = record.version === 1 ? false : record.targetHadModelKey;
+  if (typeof targetHadModelKey !== "boolean") return undefined;
+  if (record.version === 2 && (!isSafeReceiptText(record.addedModelKey) || record.addedModelKey !== addedModelKey)) return undefined;
+  if (record.status !== undefined && record.status !== "rolled_back") return undefined;
+  if (record.status === "rolled_back" && (!isReceiptTimestamp(record.rolledBackAt) || record.rolledBackAt < record.appliedAt)) return undefined;
+  if (record.status === undefined && record.rolledBackAt !== undefined) return undefined;
+  return {
+    version: 2,
+    kind: "pi-cache-optimizer-config-receipt",
+    transactionId: String(record.transactionId),
+    provider: String(record.provider),
+    modelId: String(record.modelId),
+    beforeHash: String(record.beforeHash).toLowerCase(),
+    afterHash: String(record.afterHash).toLowerCase(),
+    backupFile: String(record.backupFile),
+    targetExistedBefore: record.targetExistedBefore,
+    targetHadModelKey,
+    addedModelKey,
+    createdAt: Number(record.createdAt),
+    appliedAt: Number(record.appliedAt),
+    ...(record.status === "rolled_back" ? { status: "rolled_back", rolledBackAt: Number(record.rolledBackAt) } : {}),
+  };
+}
+
+function isActionablePromptCacheKeyConfigReceipt(receipt: PromptCacheKeyConfigReceipt | undefined): receipt is PromptCacheKeyConfigReceipt {
+  return receipt !== undefined && receipt.status === undefined;
+}
+
+async function readPromptCacheKeyConfigReceipt(receiptPath: string = CONFIG_RECEIPT_PATH): Promise<PromptCacheKeyConfigReceipt | undefined> {
+  try {
+    const info = await lstat(receiptPath);
+    if (info.isSymbolicLink() || !info.isFile()) return undefined;
+    const receipt = parsePromptCacheKeyConfigReceipt(JSON.parse(await readFile(receiptPath, "utf8")));
+    return receipt;
+  } catch {
+    return undefined;
+  }
+}
+
+async function writePromptCacheKeyConfigReceipt(receipt: PromptCacheKeyConfigReceipt, receiptPath: string = CONFIG_RECEIPT_PATH): Promise<void> {
+  if (!parsePromptCacheKeyConfigReceipt(receipt)) throw new Error("invalid prompt cache key config receipt");
+  await mkdir(dirname(receiptPath), { recursive: true });
+  const tempPath = uniqueTempPath(receiptPath, "config-receipt");
+  try {
+    await writeFile(tempPath, JSON.stringify(receipt, null, 2) + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await chmod(tempPath, 0o600);
+    await rename(tempPath, receiptPath);
+  } catch (error) {
+    await unlink(tempPath).catch((cleanupError) => { if (getErrorCode(cleanupError) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove temporary config receipt`, cleanupError); });
+    throw error;
+  }
+}
+
+async function applyPromptCacheKeyConfigFixUnderLock(
+  model: PiModel,
+  configPath: string = CONFIG_FILE_PATH,
+  receiptPath: string = CONFIG_RECEIPT_PATH,
+): Promise<{ receipt: PromptCacheKeyConfigReceipt; backupPath: string }> {
   await mkdir(dirname(configPath), { recursive: true });
-  const payload: PersistedCacheOptimizerConfigV1 = { version: 1, footerMode: mode };
-  const tempPath = `${configPath}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile(tempPath, JSON.stringify(payload, null, 2) + "\n", "utf8");
-  await rename(tempPath, configPath);
+  let originalText = "";
+  let targetExistedBefore = false;
+  let mode = 0o600;
+  try {
+    const info = await lstat(configPath);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error("optimizer config is not a regular file; no changes were made");
+    originalText = await readFile(configPath, "utf8");
+    targetExistedBefore = true;
+    mode = info.mode & 0o7777;
+  } catch (error) {
+    if (getErrorCode(error) !== "ENOENT") throw error;
+  }
+  const parsedCurrent = targetExistedBefore ? parsePersistedCacheOptimizerConfig(JSON.parse(originalText)) : undefined;
+  if (targetExistedBefore && !parsedCurrent) throw new Error("optimizer config is invalid; no changes were made");
+  const current = normalizePersistedCacheOptimizerConfig(parsedCurrent);
+  const key = modelKey(model);
+  const existingOmit = current.promptCacheKey?.omit ?? [];
+  const targetHadModelKey = existingOmit.includes(key);
+  const omit = [...new Set([...existingOmit, key])].sort();
+  const next: PersistedCacheOptimizerConfigV2 = { ...current, version: 2, promptCacheKey: { omit } };
+  const modifiedText = JSON.stringify(next, null, 2) + "\n";
+  const beforeHash = hashText(originalText);
+  const afterHash = hashText(modifiedText);
+  const originalInfo = targetExistedBefore ? await lstat(configPath) : undefined;
+  const backupFile = `pi-cache-optimizer-config.backup-${backupTimestamp()}`;
+  const backupPath = join(dirname(configPath), backupFile);
+  if (targetExistedBefore) {
+    await copyFile(configPath, backupPath, fsConstants.COPYFILE_EXCL);
+    await chmod(backupPath, mode);
+  }
+  const tempPath = uniqueTempPath(configPath, "config-fix");
+  let committedInfo: Awaited<ReturnType<typeof lstat>> | undefined;
+  try {
+    await writeFile(tempPath, modifiedText, { encoding: "utf8", mode, flag: "wx" });
+    await chmod(tempPath, mode);
+    if (originalInfo) {
+      await validateAtomicTarget(configPath, { identity: originalInfo, hash: beforeHash, mode });
+    } else {
+      try {
+        await lstat(configPath);
+        throw new Error("optimizer config appeared during the fix; no changes were made");
+      } catch (error) {
+        if (getErrorCode(error) !== "ENOENT") throw error;
+      }
+    }
+    await rename(tempPath, configPath);
+    committedInfo = await lstat(configPath);
+    const receipt: PromptCacheKeyConfigReceipt = {
+      version: 2,
+      kind: "pi-cache-optimizer-config-receipt",
+      transactionId: randomUUID(),
+      provider: model.provider,
+      modelId: model.id,
+      beforeHash,
+      afterHash,
+      backupFile,
+      targetExistedBefore,
+      targetHadModelKey,
+      addedModelKey: key,
+      createdAt: Date.now(),
+      appliedAt: Date.now(),
+    };
+    await writePromptCacheKeyConfigReceipt(receipt, receiptPath);
+    return { receipt, backupPath };
+  } catch (error) {
+    await unlink(tempPath).catch(() => {});
+    if (targetExistedBefore && committedInfo) {
+      await atomicRestoreFileFromBackup(backupPath, configPath, mode, { identity: committedInfo, hash: afterHash, mode }).catch(() => {});
+    } else if (!targetExistedBefore && committedInfo) {
+      await validateAtomicTarget(configPath, { identity: committedInfo, hash: afterHash, mode }).then(() => unlink(configPath)).catch(() => {});
+    }
+    throw error;
+  }
+}
+
+async function applyPromptCacheKeyConfigFix(
+  model: PiModel,
+  configPath: string = CONFIG_FILE_PATH,
+  receiptPath: string = CONFIG_RECEIPT_PATH,
+): Promise<{ receipt: PromptCacheKeyConfigReceipt; backupPath: string }> {
+  return withModelsJsonTransactionLock(() => applyPromptCacheKeyConfigFixUnderLock(model, configPath, receiptPath));
+}
+
+async function rollbackPromptCacheKeyConfigUnderLock(
+  receipt: PromptCacheKeyConfigReceipt,
+  configPath: string = CONFIG_FILE_PATH,
+  receiptPath: string = CONFIG_RECEIPT_PATH,
+): Promise<void> {
+  const currentInfo = await lstat(configPath);
+  if (currentInfo.isSymbolicLink() || !currentInfo.isFile()) throw new Error("optimizer config is not a regular file; refusing to overwrite user changes");
+  const currentText = await readFile(configPath, "utf8");
+  if (hashText(currentText) !== receipt.afterHash) throw new Error("optimizer config changed after the fix; refusing to overwrite user changes");
+  const current = parsePersistedCacheOptimizerConfig(JSON.parse(currentText));
+  if (!current) throw new Error("optimizer config is invalid; refusing to overwrite user changes");
+  const key = `${receipt.provider}/${receipt.modelId}`;
+  if (receipt.addedModelKey !== key) throw new Error("prompt-cache-key receipt identity does not match; refusing to change user config");
+  if (receipt.targetHadModelKey) throw new Error("prompt-cache-key was already configured before this fix; refusing to remove user configuration");
+  const omit = current.version === 2 ? current.promptCacheKey?.omit ?? [] : [];
+  if (!omit.includes(receipt.addedModelKey)) throw new Error("prompt-cache-key opt-out is no longer present; refusing to change user config");
+  const backupPath = configReceiptBackupPath(receipt, receiptPath);
+  if (receipt.targetExistedBefore) {
+    const backupInfo = await lstat(backupPath);
+    if (backupInfo.isSymbolicLink() || !backupInfo.isFile()) throw new Error("config backup is not a regular file");
+    const backupText = await readFile(backupPath, "utf8");
+    if (hashText(backupText) !== receipt.beforeHash) throw new Error("config backup hash does not match the fix receipt");
+    await atomicRestoreFileFromBackup(
+      backupPath,
+      configPath,
+      backupInfo.mode & 0o7777,
+      { backupHash: receipt.beforeHash, identity: currentInfo, hash: hashText(currentText), mode: currentInfo.mode & 0o7777 },
+    );
+  } else {
+    if (current.footerMode || omit.length > 1) {
+      const restored: PersistedCacheOptimizerConfigV2 = {
+        version: 2,
+        ...(current.footerMode ? { footerMode: current.footerMode } : {}),
+        ...(omit.length > 1 ? { promptCacheKey: { omit: omit.filter((item) => item !== receipt.addedModelKey) } } : {}),
+      };
+      await atomicReplaceTextFilePreservingMode(
+        configPath,
+        JSON.stringify(restored, null, 2) + "\n",
+        currentInfo.mode & 0o7777,
+        "config-rollback",
+        { identity: currentInfo, hash: hashText(currentText), mode: currentInfo.mode & 0o7777 },
+      );
+    } else {
+      await validateAtomicTarget(configPath, { identity: currentInfo, hash: hashText(currentText), mode: currentInfo.mode & 0o7777 });
+      await unlink(configPath);
+    }
+  }
+  await writePromptCacheKeyConfigReceipt({ ...receipt, status: "rolled_back", rolledBackAt: Date.now() }, receiptPath);
+}
+
+async function rollbackPromptCacheKeyConfig(
+  receipt: PromptCacheKeyConfigReceipt,
+  configPath: string = CONFIG_FILE_PATH,
+  receiptPath: string = CONFIG_RECEIPT_PATH,
+): Promise<void> {
+  return withModelsJsonTransactionLock(() => rollbackPromptCacheKeyConfigUnderLock(receipt, configPath, receiptPath));
 }
 
 function resolveFooterStatsMode(
@@ -1689,7 +2348,8 @@ function footerStatsMode(
   return resolveFooterStatsMode(configuredMode, env).mode;
 }
 
-let persistedFooterStatsMode = readPersistedFooterMode();
+let persistedCacheOptimizerConfig = readPersistedCacheOptimizerConfig();
+let persistedFooterStatsMode = persistedCacheOptimizerConfig.footerMode;
 
 function isDisabledEnv(value: string | undefined): boolean {
   if (!value) return false;
@@ -1722,6 +2382,7 @@ function getOptimizerRuntimeModeLines(): string[] {
   const lines: string[] = [];
   lines.push(`Runtime state: ${state}`);
   lines.push(`• Prompt rewrite: ${runtimeOptimizerEnabled && !isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV]) ? "on" : "off"}`);
+  lines.push(`• Deterministic tool ordering: ${isToolOrderEnabled() ? "on (verified built-in payloads, opt-in)" : "off"}`);
   lines.push(`• OpenAI prompt_cache_key fallback: ${shouldInjectOpenAIPromptCacheKey() ? "on" : "off"}`);
   lines.push(`• Footer cache stats: on${runtimeOptimizerEnabled ? "" : " (comparison mode)"}`);
   lines.push(`• Compat warnings: ${runtimeOptimizerEnabled ? "on" : "off"}`);
@@ -1810,6 +2471,25 @@ function shouldInjectOpenAIPromptCacheKeyForModel(model: PiModel | undefined): b
   return isOpenAICompatibleApi(model?.api);
 }
 
+function isPromptCacheKeyOmittedForModel(model: PiModel | undefined, config: PersistedCacheOptimizerConfigV2 = persistedCacheOptimizerConfig): boolean {
+  if (!model || !isOpenAICompatibleApi(model.api)) return false;
+  return config.promptCacheKey?.omit?.includes(modelKey(model)) === true;
+}
+
+function setPersistedCacheOptimizerConfig(config: PersistedCacheOptimizerConfigV2): void {
+  persistedCacheOptimizerConfig = normalizePersistedCacheOptimizerConfig(config);
+  persistedFooterStatsMode = persistedCacheOptimizerConfig.footerMode;
+}
+
+function omitOpenAIPromptCacheKeys(payload: unknown): unknown | undefined {
+  const record = asRecord(payload);
+  if (!record || (!Object.prototype.hasOwnProperty.call(record, "prompt_cache_key") && !Object.prototype.hasOwnProperty.call(record, "promptCacheKey"))) return undefined;
+  const copy = { ...record };
+  delete copy.prompt_cache_key;
+  delete copy.promptCacheKey;
+  return copy;
+}
+
 function collectAnthropicCacheControlsInWireOrder(payload: unknown): UnknownRecord[] {
   const record = asRecord(payload);
   if (!record) return [];
@@ -2558,6 +3238,76 @@ function modelFromAssistantMessage(message: unknown, fallback: PiModel | undefin
   } as PiModel;
 }
 
+const REQUEST_SNAPSHOT_COMPAT_KEYS: Array<keyof CacheCompat> = [
+  "supportsStore",
+  "supportsDeveloperRole",
+  "supportsReasoningEffort",
+  "supportsUsageInStreaming",
+  "supportsStrictMode",
+  "maxTokensField",
+  "sendSessionAffinityHeaders",
+  "sessionAffinityFormat",
+  "supportsLongCacheRetention",
+  "thinkingFormat",
+  "requiresReasoningContentOnAssistantMessages",
+  "cacheControlFormat",
+  "forceAdaptiveThinking",
+  "allowEmptySignature",
+];
+
+function snapshotCompatForDiagnostics(model: PiModel): CacheCompat {
+  const source = getCompat(model);
+  const snapshot: CacheCompat = {};
+  const mutableSnapshot = snapshot as Record<string, unknown>;
+  for (const key of REQUEST_SNAPSHOT_COMPAT_KEYS) {
+    const value = source[key];
+    if (value !== undefined) mutableSnapshot[key] = value;
+  }
+  return snapshot;
+}
+
+function snapshotBaseUrlForDiagnostics(value: unknown): string {
+  if (!isNonEmptyString(value)) return "";
+  try {
+    const url = new URL(value);
+    // Request correlation only needs endpoint identity. Strip userinfo and
+    // query/fragment material so a provider URL cannot carry credentials into
+    // the process-local snapshot.
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+  } catch {
+    // Invalid endpoint strings are not useful for applicability checks. Keep
+    // only a conservative path-free origin-like prefix without userinfo.
+    return value.replace(new RegExp("//[^/?#\\s@]+@"), "//").split(/[?#]/, 1)[0];
+  }
+}
+
+function snapshotProviderRequestModel(model: PiModel | undefined): PiModel | undefined {
+  if (!model) return undefined;
+
+  // The provider response hooks do not receive the model that initiated the
+  // request (Pi's runner only forwards status/headers). Keep a process-local,
+  // credential-blind metadata snapshot so a model switch or route change
+  // between request and response cannot retarget a protocol observation. Do
+  // not retain the caller's complete model object or any request data.
+  return {
+    provider: model.provider,
+    id: model.id,
+    name: model.name,
+    api: model.api,
+    baseUrl: snapshotBaseUrlForDiagnostics(model.baseUrl),
+    compat: snapshotCompatForDiagnostics(model),
+    reasoning: model.reasoning ?? false,
+    input: model.input ?? ["text"],
+    cost: model.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: model.contextWindow ?? 0,
+    maxTokens: model.maxTokens ?? 0,
+  } as PiModel;
+}
+
 function keyForModelExt(model: { provider: string; id: string }): string {
   return `${model.provider}/${model.id}`;
 }
@@ -2923,18 +3673,306 @@ function hasPromptCacheRetentionUnsupportedErrorMessage(message: unknown): boole
     hasPromptCacheRetentionUnsupportedText(record.errorMessage);
 }
 
-type CompatAdvicePlacement = {
-  providerLabel?: string;
-  modelId?: string;
-};
+function hasPromptCacheKeyUnsupportedText(value: unknown): boolean {
+  const normalized = lower(value).replace(/["'`]/g, "").replace(/[_-]+/g, "_").replace(/\s+/g, " ").trim();
+  const key = "(?:prompt ?cache ?key|prompt_cache_key)";
+  if (!new RegExp(key).test(normalized)) return false;
 
-function buildProviderCompatOverride(providerLabel: string, compat: Record<string, unknown>): Record<string, unknown> {
-  return {
-    providers: {
-      [providerLabel]: {
-        compat,
-      },
-    },
+  // Only classify a field-level capability rejection. Value validation,
+  // conditional restrictions, and generic invalid-parameter messages are not
+  // proof that the endpoint lacks support for the field.
+  return [
+    new RegExp(`unsupported (?:parameter|field|input|argument)[: ]+.*${key}`),
+    new RegExp(`unknown (?:parameter|field|input|argument)[: ]+.*${key}`),
+    new RegExp(`unrecognized (?:parameter|field|input|argument)[: ]+.*${key}`),
+    new RegExp(`(?:parameter|field|input|argument)[: ]+${key} (?:is )?(?:unsupported|unknown|unrecognized|not supported|not allowed|not permitted)`),
+    new RegExp(`${key} (?:is )?(?:unsupported|unknown|unrecognized|not supported|not allowed|not permitted)`),
+    new RegExp(`extra inputs?(?: are)? (?:not permitted|not allowed)[: ]+.*${key}`),
+    new RegExp(`(?:not supported|not permitted|not allowed)[: ]+.*${key}`),
+  ].some((pattern) => pattern.test(normalized));
+}
+
+function hasPromptCacheKeyUnsupportedSignal(headers: Record<string, string> | undefined): boolean {
+  if (!headers) return false;
+  return Object.entries(headers).some(([key, value]) => hasPromptCacheKeyUnsupportedText(`${key}: ${value}`));
+}
+
+function hasPromptCacheKeyUnsupportedErrorMessage(message: unknown): boolean {
+  const record = getAssistantRecord(message);
+  return record?.stopReason === "error" &&
+    getOptionalAssistantHttpStatus(record) === 400 &&
+    hasPromptCacheKeyUnsupportedText(record.errorMessage);
+}
+
+function isPromptCacheKeyUnsupportedApplicable(model: PiModel): boolean {
+  return isOpenAICompatibleApi(model.api);
+}
+
+function hasReasoningProtocolRejectionText(value: unknown): boolean {
+  const normalized = lower(value).replace(/\s+/g, " ").trim();
+  if (!normalized) return false;
+
+  // Match only a rejection that is attached to the `thinking` parameter. Do
+  // not merely look for both parameter names: `reasoning_effort is not
+  // supported; use thinking` is the opposite direction and must not activate
+  // this fallback.
+  const thinkingParameterRejectionPatterns = [
+    /(?:^|[^a-z0-9_])["'`]?thinking["'`]?(?:\s+(?:parameter|field|argument))?\s*(?:is\s+)?(?:not supported|unsupported|unknown|unrecognized|not allowed|not permitted|rejected|invalid|not valid|not accepted|disallowed|not a valid(?:\s+(?:parameter|field|argument))?)(?![a-z0-9_])/,
+    /(?:^|[^a-z0-9_])(?:unsupported|unknown|unrecognized|invalid|disallowed|rejected|not\s+(?:a\s+)?valid|not\s+accepted|not\s+allowed|not\s+permitted)(?:[_ ](?:parameter|field|argument))?\s*[:=]?\s*["'`]?thinking["'`]?(?![a-z0-9_])/,
+    /(?:^|[^a-z0-9_])(?:extra\s+inputs?|additional\s+(?:inputs?|parameters?))\s+(?:are\s+)?(?:not permitted|not allowed|unsupported)\s*[:=]?\s*["'`]?thinking["'`]?(?![a-z0-9_])/,
+  ];
+  let rejectionEnd = -1;
+  for (const pattern of thinkingParameterRejectionPatterns) {
+    const match = pattern.exec(normalized);
+    if (match && match.index + match[0].length > rejectionEnd) {
+      rejectionEnd = match.index + match[0].length;
+    }
+  }
+  if (rejectionEnd < 0) return false;
+
+  // The provider must direct the caller to reasoning_effort after the
+  // rejection. Limiting this to the short suffix after the matched rejection
+  // keeps generic documentation or an unrelated earlier sentence from being
+  // treated as runtime protocol evidence.
+  const recommendation = normalized.slice(rejectionEnd, rejectionEnd + 260);
+  if (!/\breasoning[_\.]effort\b/.test(recommendation)) return false;
+
+  const recommendationClauses = recommendation.split(/[.;!?\n]/);
+  return recommendationClauses.some((clause) => {
+    if (!/\breasoning[_\.]effort\b/.test(clause)) return false;
+    // A target mentioned inside a negated/disabled clause is not positive
+    // protocol guidance, even if words such as `must` or `supported` occur.
+    if (
+      /\b(?:do\s+not|don't|never|avoid)\s+(?:use|set|send|pass|provide)?\s*["'`]?reasoning[_\.]effort\b/.test(clause) ||
+      /\breasoning[_\.]effort\b[^.;]{0,80}\b(?:must|should|may|do)\s+(?:not|never)\b/.test(clause) ||
+      /\breasoning[_\.]effort\b[^.;]{0,80}\b(?:unsupported|disabled|unavailable|not\s+(?:supported|accepted|allowed|available|enabled|required|recommended|expected))\b/.test(clause)
+    ) return false;
+
+    return [
+      /(?:use|try|set|send|pass|provide)\s+(?:the\s+)?(?:top[- ]level\s+)?["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
+      /(?:reasoning[_\.]effort)\b[^.;]{0,120}(?:instead|required|must\s+be|should\s+be|is\s+(?:supported|accepted|preferred|recommended|expected))\b/,
+      /(?:parameter|field|option)\s+(?:is|should be)\s+["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
+      /instead[^.;]{0,120}(?:use|try|set|send|pass|provide)\s+(?:the\s+)?["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
+      /(?:replace|change|switch)\s+(?:the\s+)?["'`]?thinking["'`]?\s+(?:with|to)\s+["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
+    ].some((pattern) => pattern.test(clause));
+  });
+}
+
+function hasReasoningProtocolRejectionSignal(headers: Record<string, string> | undefined): boolean {
+  if (!headers) return false;
+  // Each response header is one diagnostic unit. Joining all values can pair a
+  // rejection from one header with unrelated documentation in another.
+  return Object.entries(headers).some(([key, headerValue]) =>
+    hasReasoningProtocolRejectionText(`${key}: ${headerValue}`)
+  );
+}
+
+function getOptionalAssistantHttpStatus(record: UnknownRecord): number | undefined {
+  const readStatus = (value: unknown): number | undefined => {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599) return value;
+    if (typeof value === "string" && /^\d{3}$/.test(value.trim())) {
+      const parsed = Number(value.trim());
+      return parsed >= 100 && parsed <= 599 ? parsed : undefined;
+    }
+    return undefined;
+  };
+
+  for (const key of ["status", "statusCode", "httpStatus", "httpStatusCode"]) {
+    const status = readStatus(record[key]);
+    if (status !== undefined) return status;
+  }
+
+  // Foreign/provider adapters sometimes put the HTTP status under a
+  // diagnostic `details`, `error`, or `cause` object rather than exposing it
+  // on the finalized assistant message itself. Traverse only these known
+  // diagnostic wrappers, with a small depth bound; never inspect arbitrary
+  // payload/message fields for a number that happens to look like a status.
+  const scanDiagnosticStatus = (value: unknown, depth: number): number | undefined => {
+    if (depth > 2) return undefined;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const status = scanDiagnosticStatus(item, depth + 1);
+        if (status !== undefined) return status;
+      }
+      return undefined;
+    }
+    const source = asRecord(value);
+    if (!source) return undefined;
+    for (const key of ["status", "statusCode", "httpStatus", "httpStatusCode", "code"]) {
+      const status = readStatus(source[key]);
+      if (status !== undefined) return status;
+    }
+    for (const key of ["details", "error", "cause", "diagnostics"]) {
+      const status = scanDiagnosticStatus(source[key], depth + 1);
+      if (status !== undefined) return status;
+    }
+    return undefined;
+  };
+  for (const key of ["diagnostics", "diagnostic", "details", "error", "cause"]) {
+    const status = scanDiagnosticStatus(record[key], 0);
+    if (status !== undefined) return status;
+  }
+
+  // Pi's built-in OpenAI-compatible adapters normally prefix a provider error
+  // body with the HTTP status (for example `400: {...}` or
+  // `OpenAI API error (400): ...`). Only parse status-shaped prefixes; never
+  // search arbitrary body text where a model id or payload number could be
+  // mistaken for a response status.
+  if (typeof record.errorMessage === "string") {
+    const errorText = record.errorMessage;
+    const matches = [
+      /^\s*([1-5]\d{2})\b/,
+      /^\s*(?:http(?:\s+status)?|status(?:\s+code)?)\s*[:(]?\s*([1-5]\d{2})\b/i,
+      /^\s*[^():\n]{1,100}\(\s*([1-5]\d{2})\b/,
+      /^\s*(?:error|api\s+error|provider\s+error|request\s+failed|http\s+error)\s*[:(]\s*([1-5]\d{2})\b/i,
+    ];
+    for (const pattern of matches) {
+      const match = pattern.exec(errorText);
+      if (match) return Number(match[1]);
+    }
+  }
+  return undefined;
+}
+
+function hasReasoningProtocolRejectionErrorMessage(message: unknown): boolean {
+  const record = getAssistantRecord(message);
+  if (!record || record.stopReason !== "error") return false;
+  // Finalized assistant messages do not expose a separate status field in the
+  // normal Pi path, so recover it only from structured diagnostics or the
+  // adapter's status-shaped error prefix. A text-only 400-looking parameter
+  // message is not enough evidence for a protocol repair.
+  return getOptionalAssistantHttpStatus(record) === 400 &&
+    hasReasoningProtocolRejectionText(record.errorMessage);
+}
+
+function isReasoningProtocolRejectionSignalApplicable(model: PiModel | undefined): boolean {
+  // A provider error can teach us which protocol it expects, so this gate is
+  // intentionally broader than the explicit DeepSeek-format diagnostic gate.
+  // The model family identifies the affected cache/compat bucket; the error
+  // text, not the model name, supplies the wire-protocol evidence.
+  return !!model && isOpenAICompatibleProxyApi(model.api) && isDeepSeekLikeModel(model);
+}
+
+function isReasoningProtocolRejectionForModel(message: unknown, model: PiModel | undefined): boolean {
+  if (!model || !isReasoningProtocolRejectionSignalApplicable(model)) return false;
+  if (!hasReasoningProtocolRejectionErrorMessage(message)) return false;
+  const record = getAssistantRecord(message);
+  if (!record) return false;
+  const messageProvider = firstNonEmptyString(record.provider);
+  const messageModel = firstNonEmptyString(record.responseModel, record.model);
+  // An explicit identity in the finalized assistant error is authoritative.
+  // Do not broaden a model-scoped observation to another DeepSeek-named model.
+  return (!messageProvider || messageProvider === model.provider) &&
+    (!messageModel || messageModel === model.id);
+}
+
+async function notifyReasoningProtocolObservation(
+  model: PiModel,
+  ctx: Pick<ExtensionContext, "ui">,
+  rejectedModelKeys: Set<string>,
+  warnedModelKeys: Set<string>,
+): Promise<void> {
+  const key = modelKey(model);
+  rejectedModelKeys.add(key);
+  if (warnedModelKeys.has(key)) return;
+  warnedModelKeys.add(key);
+
+  const receipt = await readModelsJsonFixReceipt();
+  const matchingReceipt = isActionableModelsJsonFixReceipt(receipt) &&
+    receipt.provider === model.provider &&
+    receipt.modelId === model.id;
+  const recovery = matchingReceipt
+    ? "A matching confirmed fix receipt exists; run /cache-optimizer rollback to undo it safely."
+    : "Run /cache-optimizer fix to review a model-scoped repair.";
+  ctx.ui.notify(
+    `⚠️ ${LOG_PREFIX}: ${key} rejected the configured reasoning format. ${recovery} ` +
+    "No configuration was changed automatically.",
+    "warning",
+  );
+}
+
+function fixSuggestionIdentity(model: PiModel): { providerLabel: string; modelId: string } {
+  const key = modelKey(model);
+  const slashIdx = key.indexOf("/");
+  return {
+    providerLabel: slashIdx > 0 ? key.slice(0, slashIdx) : key,
+    modelId: model.id,
+  };
+}
+
+function mergeFixSuggestions(...suggestions: Array<FixSuggestion | undefined>): FixSuggestion | undefined {
+  const present = suggestions.filter((suggestion): suggestion is FixSuggestion => suggestion !== undefined);
+  if (present.length === 0) return undefined;
+  const first = present[0];
+  return {
+    providerLabel: first.providerLabel,
+    modelId: first.modelId,
+    compatKeys: Object.assign({}, ...present.map((suggestion) => suggestion.compatKeys)),
+    forceModelLevel: present.some((suggestion) => suggestion.forceModelLevel === true),
+  };
+}
+
+function buildReasoningProtocolFixSuggestion(
+  model: PiModel,
+  protocolRejectionObserved = false,
+): FixSuggestion | undefined {
+  if (!protocolRejectionObserved) return undefined;
+  if (!isDeepSeekLikeModel(model) || !isOpenAICompatibleProxyApi(model.api)) return undefined;
+
+  const compat = getCompat(model);
+  // Explicit provider-specific formats are user/provider evidence in their own
+  // right. Do not replace qwen/openrouter/together/etc. merely because a
+  // generic error happened to mention both reasoning parameter names. The
+  // evidence-driven repair is limited to the old DeepSeek `thinking` format,
+  // an explicit standard OpenAI format, or an absent format that needs to be
+  // made unambiguous after the provider's rejection.
+  if (
+    compat.thinkingFormat !== undefined &&
+    compat.thinkingFormat !== "deepseek" &&
+    compat.thinkingFormat !== "openai"
+  ) {
+    return undefined;
+  }
+
+  const identity = fixSuggestionIdentity(model);
+  const compatKeys: Record<string, unknown> = {};
+  if (compat.thinkingFormat !== "openai") {
+    compatKeys.thinkingFormat = "openai";
+  }
+  if (compat.supportsReasoningEffort !== true) {
+    compatKeys.supportsReasoningEffort = true;
+  }
+
+  // Replay behavior is changed only when the current effective configuration
+  // actually enabled it. Never invent a false value merely because the model
+  // family is named DeepSeek or because a provider supports reasoning effort.
+  if (compat.requiresReasoningContentOnAssistantMessages === true) {
+    compatKeys.requiresReasoningContentOnAssistantMessages = false;
+  }
+  if (Object.keys(compatKeys).length === 0) return undefined;
+
+  return {
+    ...identity,
+    // Protocol observations are always model-scoped. A provider may expose
+    // DeepSeek-named models with different wire formats, so sibling models
+    // must never inherit this evidence-driven change.
+    compatKeys,
+    forceModelLevel: true,
+  };
+}
+
+type CompatAdvicePlacement = {
+  providerLabel?: string;
+  modelId?: string;
+};
+
+function buildProviderCompatOverride(providerLabel: string, compat: Record<string, unknown>): Record<string, unknown> {
+  return {
+    providers: {
+      [providerLabel]: {
+        compat,
+      },
+    },
   };
 }
 
@@ -3021,7 +4059,7 @@ function buildOpenAIProxyCompatWarningText(key: string, missing: string[]): stri
 
   const modelsJsonPath = getModelsJsonDisplayPath();
   const lines: string[] = [
-    `💡 pi-cache-optimizer: ${key} is a third-party GPT/OpenAI-compatible proxy but merged compat lacks ${missing.join(" and ")}.`,
+    `💡 pi-cache-optimizer: ${key} is a third-party OpenAI-compatible proxy but merged compat lacks ${missing.join(" and ")}.`,
     `Edit ${modelsJsonPath} -> providers["${providerLabel}"] -> compat (at the same level as baseUrl/api/apiKey/models).`,
     ``,
   ];
@@ -3031,80 +4069,82 @@ function buildOpenAIProxyCompatWarningText(key: string, missing: string[]): stri
   return lines.join("\n");
 }
 
+/**
+ * DeepSeek's model family and its reasoning wire protocol are separate facts.
+ * The family name selects the cache adapter, but only an explicit effective
+ * `thinkingFormat: "deepseek"` opts a third-party OpenAI Completions model into
+ * the reasoning/replay compat checks below. Model names, provider ids, URLs,
+ * and supportsReasoningEffort are not protocol evidence.
+ */
+function isDeepSeekWireCompatApplicable(model: PiModel): boolean {
+  // `thinkingFormat` is the only wire-protocol signal. The model family is
+  // still name/id based for adapter selection, while provider, URL, and
+  // supportsReasoningEffort remain deliberately irrelevant here.
+  return isDeepSeekLikeModel(model)
+    && isOpenAICompatibleProxyApi(model.api)
+    && getCompat(model).thinkingFormat === "deepseek";
+}
+
 function describeMissingDeepSeekCompat(model: PiModel): string[] {
+  if (!isDeepSeekWireCompatApplicable(model)) return [];
+
   const compat = getCompat(model);
   const missing: string[] = [];
-
-  if (compat.supportsLongCacheRetention !== true) {
-    missing.push("supportsLongCacheRetention");
-  }
-  if (model.api !== "openai-responses" && compat.sendSessionAffinityHeaders !== true) {
-    missing.push("sendSessionAffinityHeaders");
-  }
   if (compat.requiresReasoningContentOnAssistantMessages !== true) {
     missing.push("requiresReasoningContentOnAssistantMessages");
   }
-  if (compat.thinkingFormat !== "deepseek") {
-    missing.push("thinkingFormat");
-  }
-
   return missing;
 }
 
+/**
+ * Compatibility diagnostics for a DeepSeek-like model are generic unless the
+ * user has explicitly selected Pi's DeepSeek reasoning wire format. In
+ * particular, never manufacture `thinkingFormat: "deepseek"`: doing so can
+ * turn a valid reasoning_effort request into a provider-rejected `thinking`
+ * request (Issue #10).
+ */
 function isDeepSeekCompatCheckApplicable(model: PiModel): boolean {
-  return isDeepSeekLikeModel(model)
-    && isOpenAICompatibleApi(model.api)
-    && isKnownThirdPartyOpenAIEndpoint(model)
-    && !isPiBuiltInLlamaCppModel(model);
+  return isDeepSeekWireCompatApplicable(model);
+}
+
+function hasExplicitDeepSeekReasoningProtocol(model: PiModel): boolean {
+  return isDeepSeekWireCompatApplicable(model);
 }
 
 function describeMissingCacheCompatForModel(model: PiModel): string[] {
   if (isAdaptiveThinkingCompatApplicable(model)) {
     return describeMissingAdaptiveThinkingCompat(model);
   }
-  if (isDeepSeekCompatCheckApplicable(model)) {
-    return describeMissingDeepSeekCompat(model);
+
+  const missing = describeMissingOpenAICompatibleProxyCompat(model);
+  if (isDeepSeekWireCompatApplicable(model)) {
+    missing.push(...describeMissingDeepSeekCompat(model));
   }
-  return describeMissingOpenAICompatibleProxyCompat(model);
+  return missing;
 }
 
 function buildDeepSeekCompatSuggestion(missing: string[]): Record<string, unknown> {
-  const suggestion: Record<string, unknown> = {};
-
-  if (missing.includes("supportsLongCacheRetention")) {
-    suggestion.supportsLongCacheRetention = true;
-  }
-  if (missing.includes("sendSessionAffinityHeaders")) {
-    suggestion.sendSessionAffinityHeaders = true;
-  }
+  const suggestion: Record<string, unknown> = {
+    ...buildSafeOpenAIProxyCompatSuggestion(missing),
+  };
   if (missing.includes("requiresReasoningContentOnAssistantMessages")) {
     suggestion.requiresReasoningContentOnAssistantMessages = true;
   }
-  if (missing.includes("thinkingFormat")) {
-    suggestion.thinkingFormat = "deepseek";
-  }
-
   return suggestion;
 }
 
 function appendDeepSeekCompatAdviceLines(lines: string[], missing: string[], placement: CompatAdvicePlacement = {}): void {
   const suggestion = buildDeepSeekCompatSuggestion(missing);
   if (Object.keys(suggestion).length > 0) {
-    lines.push("Recommended DeepSeek compat snippet:");
+    lines.push("Recommended DeepSeek reasoning/replay compat snippet:");
     lines.push(JSON.stringify(suggestion, null, 2));
   }
 
   if (missing.includes("requiresReasoningContentOnAssistantMessages")) {
-    lines.push('- requiresReasoningContentOnAssistantMessages: true keeps replayed assistant turns compatible with DeepSeek reasoning_content requirements.');
-  }
-  if (missing.includes("thinkingFormat")) {
-    lines.push('- thinkingFormat: "deepseek" tells Pi to use DeepSeek reasoning/thinking parameter format.');
+    lines.push('- requiresReasoningContentOnAssistantMessages: true keeps replayed assistant turns compatible with an explicitly selected DeepSeek reasoning wire format.');
   }
   if (missing.includes("sendSessionAffinityHeaders")) {
-    lines.push("- sendSessionAffinityHeaders: recommended for OpenAI-compatible DeepSeek proxies when supported; it helps keep one Pi session on the same upstream/backend.");
-  }
-  if (missing.includes("supportsLongCacheRetention")) {
-    lines.push("- supportsLongCacheRetention: enable for DeepSeek-compatible endpoints that support long cache retention.");
+    lines.push("- sendSessionAffinityHeaders: recommended for third-party OpenAI-compatible proxies when supported; it helps keep one Pi session on the same upstream/backend.");
   }
 
   appendCredentialSafeProviderGuidance(lines, placement, suggestion);
@@ -3139,13 +4179,13 @@ const CACHE_PROVIDER_ADAPTERS: CacheProviderAdapter[] = [
       return normalizeWithFallback(message, getDeepSeekRawUsage, { allowInputOnlyPiUsage: true });
     },
     warningText(model) {
-      if (!isDeepSeekCompatCheckApplicable(model)) return undefined;
-
-      const missing = describeMissingDeepSeekCompat(model);
+      const missing = describeMissingCacheCompatForModel(model);
       if (missing.length === 0) return undefined;
 
       const key = modelKey(model);
-      return buildDeepSeekCompatWarningText(key, missing);
+      return isDeepSeekWireCompatApplicable(model)
+        ? buildDeepSeekCompatWarningText(key, missing)
+        : buildOpenAIProxyCompatWarningText(key, missing);
     },
   },
   {
@@ -4109,6 +5149,10 @@ function notifyCacheCompatIfNeeded(
 ): void {
   if (!model) return;
 
+  // A protocol rejection is retained separately from ordinary compat warnings;
+  // it is surfaced once by the response hook and can be used by a later fix.
+  // Do not turn it into an automatic write here.
+
   // Native anthropic-messages adaptive thinking compat check.
   // Adapter warningText only fires for OpenAI-compatible APIs, so native
   // Anthropic and Kimi Coding adaptive models need a separate check.
@@ -5484,7 +6528,7 @@ function getCompatCheckNotApplicableLines(model: PiModel): string[] {
   return ["ℹ️ Compat check not applicable for this model."];
 }
 
-function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400?: boolean; anthropicTtlOrderError?: boolean; sessionAffinity403?: boolean; openAISdkHeader403?: boolean } = {}): string {
+function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400?: boolean; promptCacheKey400?: boolean; anthropicTtlOrderError?: boolean; sessionAffinity403?: boolean; openAISdkHeader403?: boolean } = {}): string {
   const lines: string[] = [];
   lines.push(`Provider: ${model.provider}`);
   lines.push(`Model:    ${model.id}`);
@@ -5498,7 +6542,7 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
   const adaptiveThinkingApplicable = isAdaptiveThinkingCompatApplicable(model);
   const deepSeekCompatApplicable = isDeepSeekCompatCheckApplicable(model);
   const missing = describeMissingCacheCompatForModel(model);
-  const optionalOpenAIProxyCompat = (!adaptiveThinkingApplicable && !deepSeekCompatApplicable)
+  const optionalOpenAIProxyCompat = !adaptiveThinkingApplicable
     ? describeOptionalOpenAICompatibleProxyCompat(model)
     : [];
   const fixSug = buildFixSuggestion(model);
@@ -5522,6 +6566,7 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
       appendAdaptiveThinkingCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     } else if (deepSeekCompatApplicable) {
       appendDeepSeekCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
+      appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
     } else {
       appendOpenAIProxyCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
       appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
@@ -5533,6 +6578,13 @@ function buildDoctorDiagnosis(model: PiModel, options: { promptCacheRetention400
     lines.push(...getCompatCheckNotApplicableLines(model));
   }
 
+  if (options.promptCacheKey400 && isPromptCacheKeyUnsupportedApplicable(model)) {
+    lines.push("");
+    lines.push("⚠️  This model previously rejected prompt_cache_key with an explicit HTTP 400 signal.");
+    lines.push("   /cache-optimizer fix will offer a precise model-scoped opt-out.");
+    lines.push("   The opt-out removes both prompt_cache_key and promptCacheKey from the final request body.");
+  }
+
   if (isPromptCacheRetention400Applicable(model)) {
     lines.push("");
     if (options.promptCacheRetention400) {
@@ -5732,7 +6784,7 @@ function buildCompatDiagnosis(model: PiModel): string | undefined {
   const advisoryMissingC = missing.filter(m => !safeFixableMissingC.includes(m));
   const adaptiveThinkingApplicable = isAdaptiveThinkingCompatApplicable(model);
   const deepSeekCompatApplicable = isDeepSeekCompatCheckApplicable(model);
-  const optionalOpenAIProxyCompat = (!adaptiveThinkingApplicable && !deepSeekCompatApplicable)
+  const optionalOpenAIProxyCompat = !adaptiveThinkingApplicable
     ? describeOptionalOpenAICompatibleProxyCompat(model)
     : [];
   const routerNotes = describeRouterChannelDiagnostics(model);
@@ -5760,6 +6812,7 @@ function buildCompatDiagnosis(model: PiModel): string | undefined {
       appendAdaptiveThinkingCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
     } else if (deepSeekCompatApplicable) {
       appendDeepSeekCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
+      appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
     } else {
       appendOpenAIProxyCompatAdviceLines(lines, missing, { providerLabel, modelId: model.id });
       appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
@@ -5912,19 +6965,25 @@ function skipJsonValue(text: string, pos: number): number | undefined {
 /**
  * Find a top-level key in the object whose `{` is at `openBracePos`.
  * Only direct children are considered (nested values are skipped whole).
- * Returns the key's opening-quote offset and its value's start offset,
- * or undefined when the key is absent or the object is malformed.
+ * When duplicate keys exist, return the last one so scanning follows
+ * JSON.parse/Pi's effective last-definition-wins behavior. `count` lets
+ * callers refuse an ambiguous surgical edit rather than silently selecting a
+ * user-added duplicate. Return undefined when the key is absent or the object
+ * is malformed.
  */
 function findJsonObjectKey(
   text: string,
   openBracePos: number,
   targetKey: string,
-): { keyStart: number; valueStart: number } | undefined {
+): { keyStart: number; valueStart: number; count: number } | undefined {
   if (text[openBracePos] !== "{") return undefined;
   let i = openBracePos + 1;
+  let found: { keyStart: number; valueStart: number; count: number } | undefined;
+  let count = 0;
   while (i < text.length) {
     i = skipJsonWhitespace(text, i);
-    if (i >= text.length || text[i] === "}") return undefined;
+    if (i >= text.length) return undefined;
+    if (text[i] === "}") return found;
     if (text[i] === ",") {
       i++;
       continue;
@@ -5936,7 +6995,10 @@ function findJsonObjectKey(
     i = skipJsonWhitespace(text, key.end);
     if (text[i] !== ":") return undefined;
     i = skipJsonWhitespace(text, i + 1);
-    if (key.value === targetKey) return { keyStart, valueStart: i };
+    if (key.value === targetKey) {
+      count++;
+      found = { keyStart, valueStart: i, count };
+    }
     const after = skipJsonValue(text, i);
     if (after === undefined) return undefined;
     i = after;
@@ -6168,6 +7230,8 @@ function hasExplicitLongRetentionOptInFromConfig(
  * Returns the byte offsets for surgical insertion, or undefined if ambiguous.
  */
 interface ModelNodeLocation {
+  /** Number of exact provider keys found in the root providers object. */
+  providerKeyCount: number;
   /** Offset of the model object's opening `{` */
   modelObjectBrace: number;
   /** Offset of the model object's closing `}` */
@@ -6196,11 +7260,21 @@ interface ModelNodeLocation {
   modelOverrideCompatBrace: number;
   /** Offset of the target override compat object's closing `}`, or -1 if absent */
   modelOverrideCompatEnd: number;
+  /** Number of exact modelOverrides keys for this model id. */
+  modelOverrideKeyCount: number;
+  /** Number of exact compat keys in the selected model object. */
+  modelCompatKeyCount: number;
+  /** Number of exact provider compat keys. */
+  providerCompatKeyCount: number;
   /** All model ids found in this provider's models array (for placement safety analysis) */
   allModelIds: string[];
 }
 
 interface ModelOverrideNodeLocation {
+  providerKeyCount: number;
+  modelOverridesKeyCount: number;
+  modelOverrideKeyCount: number;
+  modelOverrideCompatKeyCount: number;
   providerObjectBrace: number;
   providerObjectEnd: number;
   modelOverridesObjectBrace: number;
@@ -6221,17 +7295,21 @@ function locateModelOverrideInJsonc(
   const rootBrace = skipJsonWhitespace(clean, 0);
   if (clean[rootBrace] !== "{") return undefined;
   const providersKey = findJsonObjectKey(clean, rootBrace, "providers");
-  if (!providersKey) return undefined;
+  if (!providersKey || providersKey.count !== 1) return undefined;
   const providersBrace = skipJsonWhitespace(clean, providersKey.valueStart);
   if (clean[providersBrace] !== "{") return undefined;
   const providersEnd = findMatchingBracket(clean, providersBrace);
   if (providersEnd === undefined) return undefined;
   const providerKey = findJsonObjectKey(clean, providersBrace, providerLabel);
-  if (!providerKey || providerKey.keyStart > providersEnd) return undefined;
+  if (!providerKey || providerKey.count !== 1 || providerKey.keyStart > providersEnd) return undefined;
   const providerObjectBrace = skipJsonWhitespace(clean, providerKey.valueStart);
   if (clean[providerObjectBrace] !== "{") return undefined;
   const providerObjectEnd = findMatchingBracket(clean, providerObjectBrace);
   if (providerObjectEnd === undefined || providerObjectEnd > providersEnd) return undefined;
+  const providerCompatKey = findJsonObjectKey(clean, providerObjectBrace, "compat");
+  if (providerCompatKey?.count && providerCompatKey.count > 1) return undefined;
+  const modelsKey = findJsonObjectKey(clean, providerObjectBrace, "models");
+  if (modelsKey?.count && modelsKey.count > 1) return undefined;
 
   let modelOverridesObjectBrace = -1;
   let modelOverridesObjectEnd = -1;
@@ -6239,7 +7317,10 @@ function locateModelOverrideInJsonc(
   let modelOverrideObjectEnd = -1;
   let modelOverrideCompatBrace = -1;
   let modelOverrideCompatEnd = -1;
+  let modelOverrideKeyCount = 0;
+  let modelOverrideCompatKeyCount = 0;
   const overridesKey = findJsonObjectKey(clean, providerObjectBrace, "modelOverrides");
+  if (overridesKey?.count && overridesKey.count > 1) return undefined;
   if (overridesKey && overridesKey.keyStart < providerObjectEnd) {
     const brace = skipJsonWhitespace(clean, overridesKey.valueStart);
     if (clean[brace] !== "{") return undefined;
@@ -6249,6 +7330,8 @@ function locateModelOverrideInJsonc(
     modelOverridesObjectEnd = end;
 
     const overrideKey = findJsonObjectKey(clean, brace, modelId);
+    modelOverrideKeyCount = overrideKey?.count ?? 0;
+    if (overrideKey?.count && overrideKey.count > 1) return undefined;
     if (overrideKey && overrideKey.keyStart < end) {
       const entryBrace = skipJsonWhitespace(clean, overrideKey.valueStart);
       if (clean[entryBrace] !== "{") return undefined;
@@ -6258,6 +7341,8 @@ function locateModelOverrideInJsonc(
       modelOverrideObjectEnd = entryEnd;
 
       const compatKey = findJsonObjectKey(clean, entryBrace, "compat");
+      modelOverrideCompatKeyCount = compatKey?.count ?? 0;
+      if (compatKey?.count && compatKey.count > 1) return undefined;
       if (compatKey && compatKey.keyStart < entryEnd) {
         const compatBrace = skipJsonWhitespace(clean, compatKey.valueStart);
         if (clean[compatBrace] !== "{") return undefined;
@@ -6270,6 +7355,10 @@ function locateModelOverrideInJsonc(
   }
 
   return {
+    providerKeyCount: providerKey.count,
+    modelOverridesKeyCount: overridesKey?.count ?? 0,
+    modelOverrideKeyCount,
+    modelOverrideCompatKeyCount,
     providerObjectBrace,
     providerObjectEnd,
     modelOverridesObjectBrace,
@@ -6304,14 +7393,14 @@ function locateModelInJsonc(
   if (clean[rootBrace] !== "{") return undefined;
 
   const providersKey = findJsonObjectKey(clean, rootBrace, "providers");
-  if (!providersKey) return undefined;
+  if (!providersKey || providersKey.count !== 1) return undefined;
   const providersBrace = skipJsonWhitespace(clean, providersKey.valueStart);
   if (clean[providersBrace] !== "{") return undefined;
   const providersEnd = findMatchingBracket(clean, providersBrace);
   if (providersEnd === undefined) return undefined;
 
   const providerKey = findJsonObjectKey(clean, providersBrace, providerLabel);
-  if (!providerKey || providerKey.keyStart > providersEnd) return undefined;
+  if (!providerKey || providerKey.count !== 1 || providerKey.keyStart > providersEnd) return undefined;
   const providerBrace = skipJsonWhitespace(clean, providerKey.valueStart);
   if (clean[providerBrace] !== "{") return undefined;
   const providerEndBrace = findMatchingBracket(clean, providerBrace);
@@ -6322,14 +7411,33 @@ function locateModelInJsonc(
   let providerCompatBrace = -1;
   let providerCompatEnd = -1;
   const providerCompatKey = findJsonObjectKey(clean, providerBrace, "compat");
+  const providerCompatKeyCount = providerCompatKey?.count ?? 0;
+  if (providerCompatKey?.count && providerCompatKey.count > 1) return undefined;
   if (providerCompatKey && providerCompatKey.keyStart < providerEndBrace) {
     const brace = skipJsonWhitespace(clean, providerCompatKey.valueStart);
-    if (clean[brace] === "{") {
-      const end = findMatchingBracket(clean, brace);
-      if (end !== undefined && end <= providerEndBrace) {
-        providerCompatBrace = brace;
-        providerCompatEnd = end;
-      }
+    if (clean[brace] !== "{") return undefined;
+    const end = findMatchingBracket(clean, brace);
+    if (end === undefined || end > providerEndBrace) return undefined;
+    providerCompatBrace = brace;
+    providerCompatEnd = end;
+  }
+
+  const modelOverridesKey = findJsonObjectKey(clean, providerBrace, "modelOverrides");
+  if (modelOverridesKey?.count && modelOverridesKey.count > 1) return undefined;
+  if (modelOverridesKey) {
+    const modelOverridesBrace = skipJsonWhitespace(clean, modelOverridesKey.valueStart);
+    if (clean[modelOverridesBrace] !== "{") return undefined;
+    const modelOverridesEnd = findMatchingBracket(clean, modelOverridesBrace);
+    if (modelOverridesEnd === undefined || modelOverridesEnd > providerEndBrace) return undefined;
+    const overrideKey = findJsonObjectKey(clean, modelOverridesBrace, modelId);
+    if (overrideKey?.count && overrideKey.count > 1) return undefined;
+    if (overrideKey) {
+      const overrideBrace = skipJsonWhitespace(clean, overrideKey.valueStart);
+      if (clean[overrideBrace] !== "{") return undefined;
+      const overrideEnd = findMatchingBracket(clean, overrideBrace);
+      if (overrideEnd === undefined || overrideEnd > modelOverridesEnd) return undefined;
+      const overrideCompatKey = findJsonObjectKey(clean, overrideBrace, "compat");
+      if (overrideCompatKey?.count && overrideCompatKey.count > 1) return undefined;
     }
   }
 
@@ -6340,7 +7448,7 @@ function locateModelInJsonc(
   const modelOverrideCompatEnd = overrideLocation?.modelOverrideCompatEnd ?? -1;
 
   const modelsKey = findJsonObjectKey(clean, providerBrace, "models");
-  if (!modelsKey || modelsKey.keyStart > providerEndBrace) return undefined;
+  if (!modelsKey || modelsKey.count !== 1 || modelsKey.keyStart > providerEndBrace) return undefined;
 
   let modelsScan = skipJsonWhitespace(clean, modelsKey.valueStart);
   if (clean[modelsScan] !== "[") return undefined;
@@ -6355,6 +7463,7 @@ function locateModelInJsonc(
   let compatKeyStartClean = -1;
   let compatBrace = -1;
   let compatEndBrace = -1;
+  let modelCompatKeyCount = 0;
 
   while (modelsScan < modelsEnd) {
     modelsScan = skipJsonWhitespace(clean, modelsScan);
@@ -6370,6 +7479,7 @@ function locateModelInJsonc(
     if (elementEnd === undefined || elementEnd > modelsEnd) return undefined;
 
     const idKey = findJsonObjectKey(clean, elementBrace, "id");
+    if (idKey?.count && idKey.count > 1) return undefined;
     let elementId: string | undefined;
     if (idKey && idKey.keyStart < elementEnd) {
       const idValueStart = skipJsonWhitespace(clean, idKey.valueStart);
@@ -6393,16 +7503,16 @@ function locateModelInJsonc(
       compatEndBrace = -1;
 
       const compatKey = findJsonObjectKey(clean, modelBrace, "compat");
+      modelCompatKeyCount = compatKey?.count ?? 0;
+      if (compatKey?.count && compatKey.count > 1) return undefined;
       if (compatKey && compatKey.keyStart < modelEndBrace) {
         compatKeyStartClean = compatKey.keyStart;
         const brace = skipJsonWhitespace(clean, compatKey.valueStart);
-        if (clean[brace] === "{") {
-          const end = findMatchingBracket(clean, brace);
-          if (end !== undefined && end <= modelEndBrace) {
-            compatBrace = brace;
-            compatEndBrace = end;
-          }
-        }
+        if (clean[brace] !== "{") return undefined;
+        const end = findMatchingBracket(clean, brace);
+        if (end === undefined || end > modelEndBrace) return undefined;
+        compatBrace = brace;
+        compatEndBrace = end;
       }
     }
 
@@ -6435,6 +7545,10 @@ function locateModelInJsonc(
     modelOverrideObjectEnd,
     modelOverrideCompatBrace,
     modelOverrideCompatEnd,
+    providerKeyCount: providerKey.count,
+    modelOverrideKeyCount: overrideLocation?.modelOverrideKeyCount ?? 0,
+    modelCompatKeyCount,
+    providerCompatKeyCount,
     allModelIds,
   };
 }
@@ -6464,8 +7578,9 @@ function analyzeModelsJsonForMissingEntry(
   if (clean[rootBrace] !== "{") return undefined;
 
   const providersKey = findJsonObjectKey(clean, rootBrace, "providers");
-  if (!providersKey) {
-    // Root has no "providers" key at all — we don't auto-create one.
+  if (!providersKey || providersKey.count !== 1) {
+    // Root has no unique "providers" key — we don't auto-create or guess
+    // among duplicate definitions.
     return undefined;
   }
   const providersBrace = skipJsonWhitespace(clean, providersKey.valueStart);
@@ -6474,9 +7589,10 @@ function analyzeModelsJsonForMissingEntry(
   if (providersEnd === undefined) return undefined;
 
   const providerKey = findJsonObjectKey(clean, providersBrace, providerLabel);
-  if (!providerKey || providerKey.keyStart > providersEnd) {
+  if (!providerKey) {
     return { scenario: "provider_missing", providersBrace, providersEnd };
   }
+  if (providerKey.count !== 1 || providerKey.keyStart > providersEnd) return undefined;
 
   // Provider exists. Check for a models array so we know where to append.
   const providerBrace = skipJsonWhitespace(clean, providerKey.valueStart);
@@ -6485,14 +7601,42 @@ function analyzeModelsJsonForMissingEntry(
   if (providerEndBrace === undefined || providerEndBrace > providersEnd) return undefined;
 
   const modelsKey = findJsonObjectKey(clean, providerBrace, "models");
+  if (modelsKey?.count && modelsKey.count > 1) return undefined;
   if (modelsKey && modelsKey.keyStart < providerEndBrace) {
-    let mScan = skipJsonWhitespace(clean, modelsKey.valueStart);
-    if (clean[mScan] === "[") {
-      const modelsEnd = findMatchingBracket(clean, mScan);
-      if (modelsEnd !== undefined && modelsEnd <= providerEndBrace) {
-        return { scenario: "model_missing", modelsEnd, providerBrace, providerEndBrace };
+    const mScan = skipJsonWhitespace(clean, modelsKey.valueStart);
+    if (clean[mScan] !== "[") return undefined;
+    const modelsEnd = findMatchingBracket(clean, mScan);
+    if (modelsEnd === undefined || modelsEnd > providerEndBrace) return undefined;
+
+    // Confirm that the target really is absent before offering an insertion.
+    // This second pass also refuses malformed/ambiguous existing entries, so
+    // a scanner failure can never turn into a duplicate model definition.
+    let modelScan = mScan + 1;
+    let targetFound = false;
+    while (modelScan < modelsEnd) {
+      modelScan = skipJsonWhitespace(clean, modelScan);
+      if (clean[modelScan] === ",") {
+        modelScan++;
+        continue;
       }
+      if (modelScan >= modelsEnd || clean[modelScan] === "]") break;
+      if (clean[modelScan] !== "{") return undefined;
+      const elementEnd = findMatchingBracket(clean, modelScan);
+      if (elementEnd === undefined || elementEnd > modelsEnd) return undefined;
+      const idKey = findJsonObjectKey(clean, modelScan, "id");
+      if (!idKey || idKey.count !== 1) return undefined;
+      const idStart = skipJsonWhitespace(clean, idKey.valueStart);
+      const idLiteral = readJsonStringLiteral(clean, idStart);
+      if (!idLiteral || idLiteral.end > elementEnd) return undefined;
+      if (idLiteral.value === modelId) {
+        targetFound = true;
+        const compatKey = findJsonObjectKey(clean, modelScan, "compat");
+        if (compatKey?.count && compatKey.count > 1) return undefined;
+      }
+      modelScan = elementEnd + 1;
     }
+    if (targetFound) return undefined;
+    return { scenario: "model_missing", modelsEnd, providerBrace, providerEndBrace };
   }
 
   // Provider exists, but there's no discoverable models array — treat as
@@ -6514,7 +7658,7 @@ function formatMissingEntryManualSnippet(
   const lines: string[] = [];
   const sorted = Object.entries(compatKeys).sort(([a], [b]) => a.localeCompare(b));
   const compatItems = sorted.map(([k, v]) => `          ${JSON.stringify(k)}: ${JSON.stringify(v)}`);
-  lines.push(`"${providerLabel}": {`);
+  lines.push(`${JSON.stringify(providerLabel)}: {`);
   lines.push(`    "modelOverrides": {`);
   lines.push(`      ${JSON.stringify(modelId)}: {`);
   lines.push(`        "compat": {`);
@@ -6541,6 +7685,7 @@ function composeModelOverrideInsertion(
 
   if (location?.modelOverrideObjectBrace !== undefined && location.modelOverrideObjectBrace >= 0) {
     const modelLocation: ModelNodeLocation = {
+      providerKeyCount: location.providerKeyCount,
       modelObjectBrace: -1,
       modelObjectEnd: -1,
       compatKeyStart: -1,
@@ -6555,6 +7700,9 @@ function composeModelOverrideInsertion(
       modelOverrideObjectEnd: location.modelOverrideObjectEnd,
       modelOverrideCompatBrace: location.modelOverrideCompatBrace,
       modelOverrideCompatEnd: location.modelOverrideCompatEnd,
+      modelOverrideKeyCount: location.modelOverrideKeyCount,
+      modelCompatKeyCount: 0,
+      providerCompatKeyCount: 0,
       allModelIds: [],
     };
     return {
@@ -6794,7 +7942,8 @@ function composeMissingEntryInsertion(
  * Lightweight self-check for a newly inserted model or modelOverrides entry.
  * Parses the modified text as JSONC and confirms:
  *   1. The target exists under models[] or modelOverrides.
- *   2. Every compat key has the expected effective three-layer value.
+ *   2. Every compat key has the expected effective provider/model/runtime/
+ *      modelOverride value.
  * Returns null on success, an error string on failure.
  */
 function selfCheckMissingEntryInsertion(
@@ -6803,6 +7952,7 @@ function selfCheckMissingEntryInsertion(
   providerLabel: string,
   modelId: string,
   compatKeys: Record<string, unknown>,
+  runtimeModel?: PiModel,
 ): string | null {
   try {
     const origParsed = parseJsonc(originalText);
@@ -6820,7 +7970,19 @@ function selfCheckMissingEntryInsertion(
       return `Modified file: model or modelOverrides entry "${modelId}" not found in provider after insertion`;
     }
 
+    const effectiveCompat = runtimeModel
+      ? resolveEffectiveCompatFromConfig(runtimeModel, modParsed)
+      : undefined;
     for (const [k, v] of Object.entries(compatKeys)) {
+      if (effectiveCompat) {
+        if (!Object.prototype.hasOwnProperty.call(effectiveCompat, k)) {
+          return `Modified file: effective compat.${k} not found`;
+        }
+        if ((effectiveCompat as Record<string, unknown>)[k] !== v) {
+          return `Modified file: effective compat.${k} wrong value: expected ${JSON.stringify(v)}, got ${JSON.stringify((effectiveCompat as Record<string, unknown>)[k])}`;
+        }
+        continue;
+      }
       const effective = resolveExplicitCompatValue(modParsed, providerLabel, modelId, k);
       if (!effective) return `Modified file: effective compat.${k} not found`;
       if (effective.value !== v) {
@@ -7002,8 +8164,10 @@ function decideFixPlacement(
       continue;
     }
     if (key === "thinkingFormat" || key === "requiresReasoningContentOnAssistantMessages") {
-      const allDeepSeek = siblings.every((id) => isDeepSeekLikeModel(syntheticModelForId(providerLabel, id)));
-      if (!allDeepSeek) unsafeKeys.push(key);
+      // Reasoning wire/replay behavior is model-specific. Sibling ids do not
+      // prove that they use the same protocol, so never broaden this repair to
+      // provider scope based on a shared DeepSeek name alone.
+      unsafeKeys.push(key);
       continue;
     }
     // Unknown model-behavior key — be conservative, keep it model-scoped.
@@ -7052,8 +8216,8 @@ function chooseFixPlacement(
 
   if (forceModelLevel) {
     return {
-      placement: "model",
-      reason: "runtime-observed provider/model failure — scoping the repair to the affected model",
+      placement: "modelOverride",
+      reason: "runtime-observed provider/model failure — using Pi's highest-precedence model override",
     };
   }
 
@@ -7203,6 +8367,7 @@ function selfCheckFix(
   modelId: string,
   compatKeys: Record<string, unknown>,
   placement: "provider" | "model" | "modelOverride" = "model",
+  runtimeModel?: PiModel,
 ): string | null {
   try {
     // Step 1: Parse both versions as JSONC (comments + trailing commas allowed).
@@ -7247,8 +8412,9 @@ function selfCheckFix(
     }
 
     // Step 5: Compute the EFFECTIVE merged compat using Pi's precedence:
-    // provider, custom model, then modelOverrides. The fix may have written any
-    // level, so validation must check what Pi will actually use.
+    // provider, custom model, runtime model, then modelOverrides. The fix may
+    // have written any persistent level, so validation must check what Pi will
+    // actually use.
     const provCompatRaw = (provider as Record<string, unknown>).compat;
     const provCompat = (provCompatRaw && typeof provCompatRaw === 'object' && !Array.isArray(provCompatRaw))
       ? provCompatRaw as Record<string, unknown>
@@ -7264,7 +8430,9 @@ function selfCheckFix(
       return `Modified file: modelOverrides["${modelId}"].compat is not an object`;
     }
     const overrideCompat = asRecord(overrideCompatRaw) ?? {};
-    const mergedCompat: Record<string, unknown> = { ...provCompat, ...mdlCompat, ...overrideCompat };
+    const mergedCompat: Record<string, unknown> = runtimeModel
+      ? resolveEffectiveCompatFromConfig(runtimeModel, modParsed) as Record<string, unknown>
+      : { ...provCompat, ...mdlCompat, ...overrideCompat };
 
     // Step 6: Validate all inserted keys are effective in the merged compat
     for (const [k, v] of Object.entries(compatKeys)) {
@@ -7276,62 +8444,97 @@ function selfCheckFix(
       }
     }
 
-    // Step 7: Validate original structure is preserved (no accidental deletions/changes)
-
-    function isSubset(origVal: unknown, modVal: unknown, path = ''): boolean {
-      if (origVal === modVal) return true;
-      if (typeof origVal !== typeof modVal) return false;
-      if (typeof origVal !== 'object' || origVal === null || modVal === null) return false;
-      if (Array.isArray(origVal) !== Array.isArray(modVal)) return false;
-      if (Array.isArray(origVal) && Array.isArray(modVal)) {
-        if (origVal.length !== modVal.length) return false;
-        return origVal.every((_, i) => isSubset(origVal[i], modVal[i], `${path}[${i}]`));
+    // Step 7: Validate that the parsed document is unchanged except for the
+    // explicitly requested scalar keys in the compat object we edited. A
+    // one-way subset check is not sufficient here: it would accept accidental
+    // additions such as credentials or unrelated provider fields.
+    const editedCompatContainer = (value: Record<string, unknown>): boolean =>
+      (placement === "provider" && value === origProvider) ||
+      (placement === "model" && value === origTargetModelRecord) ||
+      (placement === "modelOverride" && value === asRecord(asRecord(origProvider.modelOverrides)?.[modelId]));
+
+    function sameCompatObject(
+      originalCompatValue: unknown,
+      modifiedCompatValue: unknown,
+    ): boolean {
+      const originalCompat = originalCompatValue === undefined
+        ? {}
+        : asRecord(originalCompatValue);
+      const modifiedCompat = asRecord(modifiedCompatValue);
+      if (!originalCompat || !modifiedCompat) return false;
+
+      const allowedKeys = new Set([...Object.keys(originalCompat), ...Object.keys(compatKeys)]);
+      const modifiedKeys = Object.keys(modifiedCompat);
+      if (modifiedKeys.length !== allowedKeys.size || modifiedKeys.some((key) => !allowedKeys.has(key))) {
+        return false;
       }
-      // Both objects: check that every key in orig is in mod with same value
-      const origObj = origVal as Record<string, unknown>;
-      const modObj = modVal as Record<string, unknown>;
-      for (const key of Object.keys(origObj)) {
-        if (!(key in modObj)) return false;
-        if (key === 'compat') {
-          // For compat, allow extra keys in modified (the inserted ones).
-          // Use recursive isSubset so nested objects (e.g. { deep: true })
-          // are compared by content, not reference.
-          if (typeof origObj[key] !== 'object' || typeof modObj[key] !== 'object') {
-            if (origObj[key] !== modObj[key]) return false;
-          } else {
-            const origCompat = origObj[key] as Record<string, unknown>;
-            const modCompat = modObj[key] as Record<string, unknown>;
-            // Only the compat object at the level ACTUALLY edited may have
-            // its values repaired by this fix. The un-edited level must
-            // remain byte/structure-equivalent, so its same-name keys stay
-            // under full validation. Using a disjunction OR (provider ||
-            // target) here would silently skip validation at the un-edited
-            // level, masking corruption (e.g. a buggy editor accidentally
-            // breaking provider.compat.sendSessionAffinityHeaders while
-            // the fix was a model-level repair). Track placement — only
-            // the placement-resolved object's own compat may be exempt.
-            const mayRepairThisCompat =
-              (placement === "provider" && origObj === origProvider) ||
-              (placement === "model" && origObj === origTargetModelRecord) ||
-              (placement === "modelOverride" && origObj === asRecord(asRecord(origProvider.modelOverrides)?.[modelId]));
-            for (const ck of Object.keys(origCompat)) {
-              if (!(ck in modCompat)) return false;
-              // The fix may repair an existing wrong compat value (for example
-              // thinkingFormat: "legacy" -> "deepseek"), but only on the
-              // target provider/model compat objects. Sibling compat blocks must
-              // remain structure-equivalent.
-              if (mayRepairThisCompat && Object.prototype.hasOwnProperty.call(compatKeys, ck)) continue;
-              if (!isSubset(origCompat[ck], modCompat[ck], `${path}.${ck}`)) return false;
-            }
+
+      for (const key of allowedKeys) {
+        if (Object.prototype.hasOwnProperty.call(compatKeys, key)) {
+          if (!Object.prototype.hasOwnProperty.call(modifiedCompat, key) || modifiedCompat[key] !== compatKeys[key]) {
+            return false;
           }
-        } else if (!isSubset(origObj[key], modObj[key], `${path}.${key}`)) {
+          continue;
+        }
+        if (!Object.prototype.hasOwnProperty.call(originalCompat, key) ||
+            !sameDocumentValue(originalCompat[key], modifiedCompat[key])) {
           return false;
         }
       }
       return true;
     }
 
-    if (!isSubset(origParsed, modParsed)) {
+    function sameDocumentValue(originalValue: unknown, modifiedValue: unknown): boolean {
+      if (originalValue === modifiedValue) return true;
+      if (typeof originalValue !== typeof modifiedValue || originalValue === null || modifiedValue === null) return false;
+      if (Array.isArray(originalValue) || Array.isArray(modifiedValue)) {
+        if (!Array.isArray(originalValue) || !Array.isArray(modifiedValue) || originalValue.length !== modifiedValue.length) return false;
+        return originalValue.every((value, index) => sameDocumentValue(value, modifiedValue[index]));
+      }
+      if (typeof originalValue !== "object") return false;
+
+      const originalObject = originalValue as Record<string, unknown>;
+      const modifiedObject = modifiedValue as Record<string, unknown>;
+      const originalKeys = Object.keys(originalObject);
+      const modifiedKeys = Object.keys(modifiedObject);
+      if (originalKeys.length !== modifiedKeys.length || modifiedKeys.some((key) => !Object.prototype.hasOwnProperty.call(originalObject, key))) {
+        return false;
+      }
+      return originalKeys.every((key) => sameDocumentValue(originalObject[key], modifiedObject[key]));
+    }
+
+    function sameDocumentExceptEditedCompat(originalValue: unknown, modifiedValue: unknown): boolean {
+      if (originalValue === modifiedValue) return true;
+      if (typeof originalValue !== typeof modifiedValue || originalValue === null || modifiedValue === null) return false;
+      if (Array.isArray(originalValue) || Array.isArray(modifiedValue)) {
+        if (!Array.isArray(originalValue) || !Array.isArray(modifiedValue) || originalValue.length !== modifiedValue.length) return false;
+        return originalValue.every((value, index) => sameDocumentExceptEditedCompat(value, modifiedValue[index]));
+      }
+      if (typeof originalValue !== "object") return false;
+
+      const originalObject = originalValue as Record<string, unknown>;
+      const modifiedObject = modifiedValue as Record<string, unknown>;
+      if (editedCompatContainer(originalObject)) {
+        const originalKeys = Object.keys(originalObject).filter((key) => key !== "compat");
+        const modifiedKeys = Object.keys(modifiedObject).filter((key) => key !== "compat");
+        if (originalKeys.length !== modifiedKeys.length || modifiedKeys.some((key) => !Object.prototype.hasOwnProperty.call(originalObject, key))) {
+          return false;
+        }
+        for (const key of originalKeys) {
+          if (!sameDocumentExceptEditedCompat(originalObject[key], modifiedObject[key])) return false;
+        }
+        return sameCompatObject(originalObject.compat, modifiedObject.compat);
+      }
+
+      const originalKeys = Object.keys(originalObject);
+      const modifiedKeys = Object.keys(modifiedObject);
+      if (originalKeys.length !== modifiedKeys.length || modifiedKeys.some((key) => !Object.prototype.hasOwnProperty.call(originalObject, key))) {
+        return false;
+      }
+      return originalKeys.every((key) => sameDocumentExceptEditedCompat(originalObject[key], modifiedObject[key]));
+    }
+
+    if (!sameDocumentExceptEditedCompat(origParsed, modParsed)) {
       return "Modified file: original structure was altered (data loss detected)";
     }
 
@@ -7395,16 +8598,78 @@ function uniqueTempPath(targetPath: string, purpose: string): string {
   return `${targetPath}.${process.pid}.${Date.now()}.${backupSequence++}.${purpose}.tmp`;
 }
 
+type FileIdentity = { dev: number | bigint; ino: number | bigint };
+
+function sameFileIdentity(left: FileIdentity, right: FileIdentity): boolean {
+  // Some platforms do not expose a meaningful inode. On those platforms the
+  // hash checks around the transaction remain authoritative.
+  const leftDev = Number(left.dev);
+  const rightDev = Number(right.dev);
+  const leftIno = Number(left.ino);
+  const rightIno = Number(right.ino);
+  return leftIno === 0 || rightIno === 0 || (leftDev === rightDev && leftIno === rightIno);
+}
+
+type AtomicTargetGuard = {
+  identity?: FileIdentity;
+  hash?: string;
+  mode?: number;
+};
+
+async function validateAtomicTarget(
+  targetPath: string,
+  guard?: AtomicTargetGuard,
+): Promise<Awaited<ReturnType<typeof lstat>>> {
+  const info = await lstat(targetPath);
+  if (info.isSymbolicLink() || !info.isFile()) {
+    throw new Error("target is not a regular file; refusing atomic replacement");
+  }
+  if (guard?.identity && !sameFileIdentity(guard.identity, info)) {
+    throw new Error("target changed during atomic replacement");
+  }
+  if (guard?.mode !== undefined && (info.mode & 0o7777) !== guard.mode) {
+    throw new Error("target access mode changed during atomic replacement");
+  }
+  if (guard?.hash !== undefined) {
+    const text = await readFile(targetPath, "utf8");
+    if (hashText(text) !== guard.hash) {
+      throw new Error("target content changed during atomic replacement");
+    }
+  }
+  return info;
+}
+
 async function atomicReplaceTextFilePreservingMode(
   targetPath: string,
   content: string,
   mode: number,
   purpose: string,
+  guard?: AtomicTargetGuard,
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeRename?: () => Promise<void>,
 ): Promise<void> {
+  const initialTargetInfo = await validateAtomicTarget(targetPath, guard);
   const tempPath = uniqueTempPath(targetPath, purpose);
   try {
-    await writeFile(tempPath, content, { encoding: "utf8", mode });
+    // `wx` makes the unique temporary path non-overwriting even if a hostile
+    // or stale file appears between name generation and the write.
+    await writeFile(tempPath, content, { encoding: "utf8", mode, flag: "wx" });
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
+      throw new Error("temporary replacement is not a regular file");
+    }
     await chmod(tempPath, mode);
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: initialTargetInfo,
+      mode,
+    });
+    if (beforeRename) await beforeRename();
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: initialTargetInfo,
+      mode,
+    });
     await rename(tempPath, targetPath);
   } catch (error) {
     try {
@@ -7422,11 +8687,42 @@ async function atomicRestoreFileFromBackup(
   backupPath: string,
   targetPath: string,
   mode: number,
+  guard?: AtomicTargetGuard & { backupHash?: string },
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeRename?: () => Promise<void>,
 ): Promise<void> {
+  const backupInfo = await lstat(backupPath);
+  if (backupInfo.isSymbolicLink() || !backupInfo.isFile()) {
+    throw new Error("backup is not a regular file; refusing atomic restore");
+  }
+  if (guard?.backupHash !== undefined) {
+    const backupText = await readFile(backupPath, "utf8");
+    if (hashText(backupText) !== guard.backupHash) {
+      throw new Error("backup content changed during atomic restore");
+    }
+  }
+  const targetInfo = await validateAtomicTarget(targetPath, guard);
   const tempPath = uniqueTempPath(targetPath, "restore");
   try {
     await copyFile(backupPath, tempPath, fsConstants.COPYFILE_EXCL);
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
+      throw new Error("temporary restore is not a regular file");
+    }
     await chmod(tempPath, mode);
+    const tempText = await readFile(tempPath, "utf8");
+    if (guard?.backupHash !== undefined && hashText(tempText) !== guard.backupHash) {
+      throw new Error("backup content changed during atomic restore");
+    }
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: targetInfo,
+    });
+    if (beforeRename) await beforeRename();
+    await validateAtomicTarget(targetPath, {
+      ...guard,
+      identity: targetInfo,
+    });
     await rename(tempPath, targetPath);
   } catch (error) {
     try {
@@ -7444,43 +8740,285 @@ type ModelsJsonFixTransactionResult =
   | { ok: true }
   | { ok: false; postCheckError: string };
 
-async function applyModelsJsonFixTransaction(
+type ModelsJsonFixReceiptSnapshot = {
+  receipt: ModelsJsonFixReceiptV1;
+  receiptPath: string;
+  hash: string;
+  identity: FileIdentity;
+};
+
+type ModelsJsonFixTransactionOptions = {
+  onCommitted?: (writtenText: string) => Promise<void>;
+  expectedCurrentHash?: string;
+  /** Access mode captured by a preview, used to reject mode races. */
+  expectedCurrentMode?: number;
+  /** Hash of the transaction backup, used to revalidate a guarded restore. */
+  expectedBackupHash?: string;
+  /** Receipt identity captured before a rollback preview. */
+  receiptGuard?: ModelsJsonFixReceiptSnapshot;
+  purpose?: string;
+};
+
+function hashText(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+async function withModelsJsonTransactionLock<T>(operation: () => Promise<T>): Promise<T> {
+  await mkdir(STATE_DIR, { recursive: true });
+  const deadline = Date.now() + MODELS_TRANSACTION_LOCK_WAIT_MS;
+  const ownerToken = randomUUID();
+  const ownerText = JSON.stringify({ pid: process.pid, token: ownerToken });
+  let ownedLockIdentity: FileIdentity | undefined;
+  while (true) {
+    try {
+      // A single O_EXCL file is the lease: unlike mkdir-then-owner-file, there
+      // is no ownerless crash window between creating the lock and identifying
+      // its owner.
+      await writeFile(MODELS_TRANSACTION_LOCK_PATH, ownerText, {
+        encoding: "utf8",
+        mode: 0o600,
+        flag: "wx",
+      });
+      const lockInfo = await lstat(MODELS_TRANSACTION_LOCK_PATH);
+      if (lockInfo.isSymbolicLink() || !lockInfo.isFile()) {
+        throw new Error("models.json transaction lock path is unsafe");
+      }
+      ownedLockIdentity = lockInfo;
+      break;
+    } catch (error) {
+      if (getErrorCode(error) !== "EEXIST") throw error;
+      const lockInfo = await lstat(MODELS_TRANSACTION_LOCK_PATH).catch(() => undefined);
+      if (!lockInfo) continue;
+      if (lockInfo.isSymbolicLink() || !lockInfo.isFile()) {
+        throw new Error("models.json transaction lock path is unsafe");
+      }
+      let staleOwnerPid: number | undefined;
+      try {
+        const owner = asRecord(JSON.parse(await readFile(MODELS_TRANSACTION_LOCK_PATH, "utf8")));
+        if (typeof owner?.pid === "number") staleOwnerPid = owner.pid;
+      } catch {}
+      const stale = Date.now() - lockInfo.mtimeMs > MODELS_TRANSACTION_LOCK_STALE_MS;
+      if (stale && (staleOwnerPid === undefined || !isProcessAlive(staleOwnerPid))) {
+        // Recheck identity immediately before unlinking so a recovered owner
+        // cannot delete a replacement lease created at the same path.
+        const currentLock = await lstat(MODELS_TRANSACTION_LOCK_PATH).catch(() => undefined);
+        if (currentLock && sameFileIdentity(lockInfo, currentLock)) {
+          await unlink(MODELS_TRANSACTION_LOCK_PATH).catch((unlinkError) => {
+            if (getErrorCode(unlinkError) !== "ENOENT") throw unlinkError;
+          });
+        }
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        throw new Error("another cache-optimizer models.json transaction is still running");
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+
+  try {
+    return await operation();
+  } finally {
+    // Only the matching inode and owner token may remove the lease. A
+    // recovered/replaced lock belongs to another transaction.
+    try {
+      const currentLock = await lstat(MODELS_TRANSACTION_LOCK_PATH);
+      if (
+        ownedLockIdentity &&
+        !currentLock.isSymbolicLink() &&
+        currentLock.isFile() &&
+        sameFileIdentity(ownedLockIdentity, currentLock) &&
+        await readFile(MODELS_TRANSACTION_LOCK_PATH, "utf8") === ownerText
+      ) {
+        await unlink(MODELS_TRANSACTION_LOCK_PATH);
+      }
+    } catch (error) {
+      if (getErrorCode(error) !== "ENOENT") {
+        console.warn(`${LOG_PREFIX}: failed to remove models.json transaction lock`, error);
+      }
+    }
+  }
+}
+
+async function assertModelsJsonFixReceiptSnapshotUnchanged(
+  snapshot: ModelsJsonFixReceiptSnapshot,
+): Promise<void> {
+  const info = await lstat(snapshot.receiptPath);
+  if (
+    info.isSymbolicLink() ||
+    !info.isFile() ||
+    !sameFileIdentity(snapshot.identity, info)
+  ) {
+    throw new Error("fix receipt changed since the rollback preview");
+  }
+  const text = await readFile(snapshot.receiptPath, "utf8");
+  const afterRead = await lstat(snapshot.receiptPath);
+  if (
+    afterRead.isSymbolicLink() ||
+    !afterRead.isFile() ||
+    !sameFileIdentity(info, afterRead) ||
+    hashText(text) !== snapshot.hash
+  ) {
+    throw new Error("fix receipt changed since the rollback preview");
+  }
+}
+
+async function applyModelsJsonFixTransactionUnderLock(
   modifiedText: string,
   backupPath: string,
   validateWrittenText: (writtenText: string) => string | null,
+  options: ModelsJsonFixTransactionOptions = {},
 ): Promise<ModelsJsonFixTransactionResult> {
-  const originalMode = (await stat(MODELS_JSON_PATH)).mode & 0o7777;
+  if (options.receiptGuard) {
+    await assertModelsJsonFixReceiptSnapshotUnchanged(options.receiptGuard);
+  }
+  const targetInfo = await lstat(MODELS_JSON_PATH);
+  if (!targetInfo.isFile() || targetInfo.isSymbolicLink()) {
+    throw new Error("models.json is not a regular file; no changes were made");
+  }
+  const originalMode = targetInfo.mode & 0o7777;
+  const transactionName = options.purpose === "rollback" ? "rollback" : "fix";
+  if (options.expectedCurrentMode !== undefined && options.expectedCurrentMode !== originalMode) {
+    throw new Error(`models.json access mode changed since the ${transactionName} preview; no changes were made`);
+  }
+  const initialTargetText = await readFile(MODELS_JSON_PATH, "utf8");
+  const transactionInitialHash = hashText(initialTargetText);
+  const expectedCurrentHash = options.expectedCurrentHash ?? transactionInitialHash;
+  const expectedBackupHash = options.expectedBackupHash ?? expectedCurrentHash;
+  const assertCurrentTargetUnchanged = async (): Promise<void> => {
+    const currentInfo = await lstat(MODELS_JSON_PATH);
+    if (
+      currentInfo.isSymbolicLink() ||
+      !currentInfo.isFile() ||
+      !sameFileIdentity(targetInfo, currentInfo) ||
+      (currentInfo.mode & 0o7777) !== originalMode
+    ) {
+      throw new Error(`models.json changed during ${transactionName}; no changes were made`);
+    }
+    const currentText = await readFile(MODELS_JSON_PATH, "utf8");
+    if (hashText(currentText) !== expectedCurrentHash) {
+      throw new Error(`models.json changed since the ${transactionName} preview; no changes were made`);
+    }
+  };
+  const assertBackupUnchanged = async (): Promise<void> => {
+    const backupInfo = await lstat(backupPath);
+    if (backupInfo.isSymbolicLink() || !backupInfo.isFile()) {
+      throw new Error(`models.json ${transactionName} backup is not a regular file; no changes were made`);
+    }
+    if (expectedBackupHash !== undefined) {
+      const backupText = await readFile(backupPath, "utf8");
+      if (hashText(backupText) !== expectedBackupHash) {
+        throw new Error(`models.json ${transactionName} backup changed during preparation; no changes were made`);
+      }
+    }
+  };
+
+  await assertCurrentTargetUnchanged();
   await copyFile(MODELS_JSON_PATH, backupPath, fsConstants.COPYFILE_EXCL);
+  const createdBackupInfo = await lstat(backupPath);
+  if (createdBackupInfo.isSymbolicLink() || !createdBackupInfo.isFile()) {
+    throw new Error(`models.json ${transactionName} backup is not a regular file; no changes were made`);
+  }
   await chmod(backupPath, originalMode);
+  const chmodBackupInfo = await lstat(backupPath);
+  if (
+    chmodBackupInfo.isSymbolicLink() ||
+    !chmodBackupInfo.isFile() ||
+    !sameFileIdentity(createdBackupInfo, chmodBackupInfo)
+  ) {
+    throw new Error(`models.json ${transactionName} backup changed during preparation; no changes were made`);
+  }
+  await assertBackupUnchanged();
 
+  const expectedModifiedHash = hashText(modifiedText);
   let targetReplaced = false;
+  const restoreTargetIfUnchanged = async (): Promise<void> => {
+    const currentInfo = await lstat(MODELS_JSON_PATH);
+    if (
+      currentInfo.isSymbolicLink() ||
+      !currentInfo.isFile() ||
+      (currentInfo.mode & 0o7777) !== originalMode
+    ) {
+      throw new Error(`models.json changed after ${transactionName} replacement; refusing to overwrite user changes`);
+    }
+    const currentText = await readFile(MODELS_JSON_PATH, "utf8");
+    if (hashText(currentText) !== expectedModifiedHash) {
+      throw new Error(`models.json changed after ${transactionName} replacement; refusing to overwrite user changes`);
+    }
+    await assertBackupUnchanged();
+    await atomicRestoreFileFromBackup(backupPath, MODELS_JSON_PATH, originalMode, {
+      identity: currentInfo,
+      hash: expectedModifiedHash,
+      mode: originalMode,
+      backupHash: expectedBackupHash,
+    });
+    const restoredInfo = await lstat(MODELS_JSON_PATH);
+    if (restoredInfo.isSymbolicLink() || !restoredInfo.isFile()) {
+      throw new Error(`models.json restore produced a non-regular file`);
+    }
+    const restoredText = await readFile(MODELS_JSON_PATH, "utf8");
+    if (expectedBackupHash !== undefined && hashText(restoredText) !== expectedBackupHash) {
+      throw new Error(`models.json restore did not match the transaction backup`);
+    }
+  };
+
   try {
+    await assertCurrentTargetUnchanged();
     await atomicReplaceTextFilePreservingMode(
       MODELS_JSON_PATH,
       modifiedText,
       originalMode,
-      "fix",
+      options.purpose ?? "fix",
+      {
+        identity: targetInfo,
+        hash: expectedCurrentHash,
+        mode: originalMode,
+      },
     );
     targetReplaced = true;
 
+    const writtenInfo = await lstat(MODELS_JSON_PATH);
+    if (writtenInfo.isSymbolicLink() || !writtenInfo.isFile()) {
+      throw new Error(`models.json became a non-regular file during ${transactionName} replacement`);
+    }
     const writtenText = await readFile(MODELS_JSON_PATH, "utf8");
     const postCheckError = validateWrittenText(writtenText);
-    const writtenMode = (await stat(MODELS_JSON_PATH)).mode & 0o7777;
-    const effectiveError = postCheckError ?? (
-      writtenMode === originalMode
-        ? null
-        : `models.json access mode changed from ${originalMode.toString(8)} to ${writtenMode.toString(8)}`
-    );
+    const writtenMode = writtenInfo.mode & 0o7777;
+    const writeHashError = hashText(writtenText) === expectedModifiedHash
+      ? null
+      : `models.json changed during ${transactionName} replacement`;
+    const modeError = writtenMode === originalMode
+      ? null
+      : `models.json access mode changed from ${originalMode.toString(8)} to ${writtenMode.toString(8)}`;
+    const effectiveError = postCheckError ?? writeHashError ?? modeError;
     if (effectiveError !== null) {
-      await atomicRestoreFileFromBackup(backupPath, MODELS_JSON_PATH, originalMode);
+      await restoreTargetIfUnchanged();
+      targetReplaced = false;
       return { ok: false, postCheckError: effectiveError };
     }
 
+    // Re-check immediately before committing receipt metadata. If a caller
+    // changed the replacement after validation, do not mark the transaction
+    // successful and do not restore over that caller's change.
+    await validateAtomicTarget(MODELS_JSON_PATH, {
+      identity: writtenInfo,
+      hash: expectedModifiedHash,
+      mode: originalMode,
+    });
+
+    // A receipt is part of a successful fix transaction. If its atomic write
+    // fails, the catch path restores the models file from the transaction
+    // backup instead of leaving an un-recoverable configuration change.
+    if (options.receiptGuard) {
+      await assertModelsJsonFixReceiptSnapshotUnchanged(options.receiptGuard);
+    }
+    await options.onCommitted?.(writtenText);
     return { ok: true };
   } catch (error) {
     if (targetReplaced) {
       try {
-        await atomicRestoreFileFromBackup(backupPath, MODELS_JSON_PATH, originalMode);
+        await restoreTargetIfUnchanged();
+        targetReplaced = false;
       } catch (restoreError) {
         throw new AggregateError(
           [error, restoreError],
@@ -7492,7 +9030,631 @@ async function applyModelsJsonFixTransaction(
   }
 }
 
-// Internal helpers exported only so the task verification script
+async function applyModelsJsonFixTransaction(
+  modifiedText: string,
+  backupPath: string,
+  validateWrittenText: (writtenText: string) => string | null,
+  options: ModelsJsonFixTransactionOptions = {},
+): Promise<ModelsJsonFixTransactionResult> {
+  return withModelsJsonTransactionLock(() =>
+    applyModelsJsonFixTransactionUnderLock(modifiedText, backupPath, validateWrittenText, options)
+  );
+}
+
+function isReceiptScalar(value: unknown): value is ReceiptScalar {
+  return value === null || typeof value === "string" || typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value));
+}
+
+function isReceiptScalarState(value: unknown): value is ReceiptScalarState {
+  const record = asRecord(value);
+  if (!record || record.present === undefined) return false;
+  if (record.present === false) return Object.keys(record).every((key) => key === "present");
+  return record.present === true && isReceiptScalar(record.value) && Object.keys(record).every((key) => key === "present" || key === "value");
+}
+
+function sameReceiptScalarState(left: ReceiptScalarState, right: ReceiptScalarState): boolean {
+  if (left.present !== right.present) return false;
+  return !left.present || left.value === (right as { present: true; value: ReceiptScalar }).value;
+}
+
+function isFixReceiptPlacement(value: unknown): value is FixReceiptPlacement {
+  return value === "provider" || value === "model" || value === "modelOverride";
+}
+
+function isSha256(value: unknown): value is string {
+  return typeof value === "string" && /^[0-9a-f]{64}$/i.test(value);
+}
+
+function hasReceiptReasoningProtocolChange(receipt: ModelsJsonFixReceiptV1): boolean {
+  return [
+    "thinkingFormat",
+    "supportsReasoningEffort",
+    "requiresReasoningContentOnAssistantMessages",
+  ].some((key) => Object.prototype.hasOwnProperty.call(receipt.changedKeys, key));
+}
+
+function isActionableModelsJsonFixReceipt(receipt: ModelsJsonFixReceiptV1 | undefined): receipt is ModelsJsonFixReceiptV1 {
+  return receipt !== undefined && receipt.status === undefined;
+}
+
+function createRollbackBackupPath(modelsPath: string = MODELS_JSON_PATH): string {
+  return `${modelsPath}.backup-cache-optimizer-rollback-${backupTimestamp()}`;
+}
+
+function isSafeReceiptText(value: unknown): value is string {
+  return isNonEmptyString(value) && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+function isReceiptTimestamp(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV1 | undefined {
+  const record = asRecord(value);
+  if (!record || record.version !== 1 || record.kind !== "pi-cache-optimizer-fix-receipt") return undefined;
+  const allowedKeys = new Set([
+    "version", "kind", "transactionId", "provider", "modelId", "placement",
+    "targetExistedBefore", "changedKeys", "beforeHash", "afterHash", "backupFile",
+    "createdAt", "appliedAt", "status", "rolledBackAt",
+  ]);
+  if (Object.keys(record).some((key) => !allowedKeys.has(key))) return undefined;
+  if (!isSafeReceiptText(record.transactionId) || !isSafeReceiptText(record.provider) || !isSafeReceiptText(record.modelId)) return undefined;
+  if (!isFixReceiptPlacement(record.placement) || typeof record.targetExistedBefore !== "boolean") return undefined;
+  if (!isSha256(record.beforeHash) || !isSha256(record.afterHash) || record.beforeHash === record.afterHash) return undefined;
+  if (!isSafeReceiptText(record.backupFile) || basename(record.backupFile) !== record.backupFile || record.backupFile.includes("..")) return undefined;
+  if (!/^models\.json\.backup-cache-optimizer-/.test(record.backupFile)) return undefined;
+  const beforeHash = typeof record.beforeHash === "string" ? record.beforeHash.toLowerCase() : "";
+  const afterHash = typeof record.afterHash === "string" ? record.afterHash.toLowerCase() : "";
+  if (beforeHash === afterHash) return undefined;
+  if (!isReceiptTimestamp(record.createdAt) || !isReceiptTimestamp(record.appliedAt) || record.appliedAt < record.createdAt) return undefined;
+  const changedKeys = asRecord(record.changedKeys);
+  if (!changedKeys || Object.keys(changedKeys).length === 0) return undefined;
+
+  const parsedChanges: Record<string, FixReceiptCompatChange> = {};
+  for (const [key, rawChange] of Object.entries(changedKeys)) {
+    if (!RECEIPT_COMPAT_KEYS.has(key)) return undefined;
+    const change = asRecord(rawChange);
+    if (!change || !isReceiptScalarState(change.before) || !isReceiptScalarState(change.after)) return undefined;
+    if (sameReceiptScalarState(change.before, change.after)) return undefined;
+    parsedChanges[key] = {
+      before: change.before,
+      after: change.after,
+    };
+  }
+
+  if (record.status !== undefined && record.status !== "rolled_back") return undefined;
+  if (record.status === "rolled_back" && (!isReceiptTimestamp(record.rolledBackAt) || record.rolledBackAt < record.appliedAt)) return undefined;
+  if (record.status === undefined && record.rolledBackAt !== undefined) return undefined;
+
+  return {
+    version: 1,
+    kind: "pi-cache-optimizer-fix-receipt",
+    transactionId: record.transactionId.trim(),
+    provider: record.provider.trim(),
+    modelId: record.modelId.trim(),
+    placement: record.placement,
+    targetExistedBefore: record.targetExistedBefore,
+    changedKeys: parsedChanges,
+    beforeHash,
+    afterHash,
+    backupFile: record.backupFile,
+    createdAt: Number(record.createdAt),
+    appliedAt: Number(record.appliedAt),
+    ...(record.status === "rolled_back" ? { status: "rolled_back", rolledBackAt: Number(record.rolledBackAt) } : {}),
+  };
+}
+
+function receiptBackupPath(receipt: ModelsJsonFixReceiptV1, receiptPath: string = FIX_RECEIPT_PATH): string {
+  return join(dirname(receiptPath), receipt.backupFile);
+}
+
+async function writeModelsJsonFixReceipt(
+  receipt: ModelsJsonFixReceiptV1,
+  receiptPath: string = FIX_RECEIPT_PATH,
+  expectedSnapshot?: ModelsJsonFixReceiptSnapshot,
+  /** Test-only race injector; production callers leave this undefined. */
+  beforeRename?: () => Promise<void>,
+): Promise<void> {
+  if (!parseModelsJsonFixReceipt(receipt)) throw new Error("invalid fix receipt");
+  if (expectedSnapshot) {
+    if (expectedSnapshot.receiptPath !== receiptPath) throw new Error("fix receipt path changed since the rollback preview");
+    await assertModelsJsonFixReceiptSnapshotUnchanged(expectedSnapshot);
+  }
+  await mkdir(dirname(receiptPath), { recursive: true });
+  let existingReceiptInfo: { dev: number; ino: number } | undefined;
+  try {
+    const info = await lstat(receiptPath);
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error("invalid fix receipt path");
+    existingReceiptInfo = info;
+  } catch (error) {
+    if (getErrorCode(error) !== "ENOENT") throw error;
+  }
+  const mode = 0o600;
+
+  const tempPath = uniqueTempPath(receiptPath, "receipt");
+  try {
+    await writeFile(tempPath, JSON.stringify(receipt, null, 2) + "\n", { encoding: "utf8", mode, flag: "wx" });
+    const tempInfo = await lstat(tempPath);
+    if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) throw new Error("invalid temporary fix receipt");
+    await chmod(tempPath, mode);
+    if (expectedSnapshot) {
+      await assertModelsJsonFixReceiptSnapshotUnchanged(expectedSnapshot);
+    }
+    const assertReceiptDestinationUnchanged = async (): Promise<void> => {
+      try {
+        const currentReceiptInfo = await lstat(receiptPath);
+        if (!existingReceiptInfo || !sameFileIdentity(existingReceiptInfo, currentReceiptInfo)) {
+          throw new Error("fix receipt changed during atomic write");
+        }
+      } catch (error) {
+        if (getErrorCode(error) === "ENOENT" && !existingReceiptInfo) {
+          // The destination was absent both before and immediately before the
+          // rename. The atomic rename will create it safely.
+        } else {
+          throw error;
+        }
+      }
+      if (expectedSnapshot) await assertModelsJsonFixReceiptSnapshotUnchanged(expectedSnapshot);
+    };
+    await assertReceiptDestinationUnchanged();
+    if (beforeRename) await beforeRename();
+    await assertReceiptDestinationUnchanged();
+    await rename(tempPath, receiptPath);
+  } catch (error) {
+    try {
+      await unlink(tempPath);
+    } catch (cleanupError) {
+      if (getErrorCode(cleanupError) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove temporary fix receipt`, cleanupError);
+    }
+    throw error;
+  }
+}
+
+async function readModelsJsonFixReceiptSnapshot(
+  receiptPath: string = FIX_RECEIPT_PATH,
+): Promise<ModelsJsonFixReceiptSnapshot | undefined> {
+  try {
+    const info = await lstat(receiptPath);
+    if (info.isSymbolicLink() || !info.isFile()) return undefined;
+    const text = await readFile(receiptPath, "utf8");
+    const afterRead = await lstat(receiptPath);
+    if (
+      afterRead.isSymbolicLink() ||
+      !afterRead.isFile() ||
+      !sameFileIdentity(info, afterRead)
+    ) return undefined;
+    const receipt = parseModelsJsonFixReceipt(JSON.parse(text));
+    if (!receipt) return undefined;
+    return {
+      receipt,
+      receiptPath,
+      hash: hashText(text),
+      identity: afterRead,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+async function readModelsJsonFixReceipt(
+  receiptPath: string = FIX_RECEIPT_PATH,
+): Promise<ModelsJsonFixReceiptV1 | undefined> {
+  return (await readModelsJsonFixReceiptSnapshot(receiptPath))?.receipt;
+}
+
+async function markModelsJsonFixReceiptRolledBack(
+  snapshot: ModelsJsonFixReceiptSnapshot,
+): Promise<void> {
+  const receipt = snapshot.receipt;
+  await writeModelsJsonFixReceipt({
+    ...receipt,
+    status: "rolled_back",
+    rolledBackAt: Date.now(),
+  }, snapshot.receiptPath, snapshot);
+}
+
+type ReceiptCompatTarget = {
+  targetExists: boolean;
+  compatBrace: number;
+  compatEnd: number;
+};
+
+function locateReceiptCompatTarget(
+  text: string,
+  provider: string,
+  modelId: string,
+  placement: FixReceiptPlacement,
+): ReceiptCompatTarget | undefined {
+  if (placement === "modelOverride") {
+    const location = locateModelOverrideInJsonc(text, provider, modelId);
+    if (
+      !location ||
+      location.providerKeyCount !== 1 ||
+      location.modelOverridesKeyCount > 1 ||
+      location.modelOverrideKeyCount > 1 ||
+      location.modelOverrideCompatKeyCount > 1
+    ) return undefined;
+    return {
+      targetExists: location.modelOverrideObjectBrace >= 0,
+      compatBrace: location.modelOverrideCompatBrace,
+      compatEnd: location.modelOverrideCompatEnd,
+    };
+  }
+
+  const location = locateModelInJsonc(text, provider, modelId);
+  if (!location || location.providerKeyCount !== 1) return undefined;
+  // A changed-file surgical rollback cannot tell which duplicate model object
+  // was the receipt's target. Refuse that ambiguity instead of touching a
+  // later user-added definition. Provider-level changes do not need to inspect
+  // model compat, but duplicate target ids still make the receipt identity
+  // ambiguous and are rejected for both placements.
+  if (location.allModelIds.filter((id) => id === modelId).length !== 1) return undefined;
+  if (placement === "provider" && location.providerCompatKeyCount > 1) return undefined;
+  if (placement === "model" && location.modelCompatKeyCount > 1) return undefined;
+  return {
+    targetExists: location.modelObjectBrace >= 0,
+    compatBrace: placement === "provider" ? location.providerCompatBrace : location.compatObjectBrace,
+    compatEnd: placement === "provider" ? location.providerCompatEnd : location.compatObjectEnd,
+  };
+}
+
+function readReceiptCompatScalarState(
+  text: string,
+  target: ReceiptCompatTarget | undefined,
+  key: string,
+): ReceiptScalarState | undefined {
+  if (!target || target.compatBrace < 0 || target.compatEnd <= target.compatBrace) {
+    return { present: false };
+  }
+  const clean = stripJsoncComments(text);
+  const property = findJsonObjectKey(clean, target.compatBrace, key);
+  if (!property || property.keyStart >= target.compatEnd) return { present: false };
+  if (property.count !== 1) return undefined;
+  const valueStart = skipJsonWhitespace(clean, property.valueStart);
+  const valueEnd = skipJsonValue(clean, valueStart);
+  if (valueEnd === undefined || valueEnd > target.compatEnd) return undefined;
+  try {
+    const value = parseJsonc(text.slice(valueStart, valueEnd));
+    return isReceiptScalar(value) ? { present: true, value } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function createModelsJsonFixReceipt(
+  originalText: string,
+  modifiedText: string,
+  provider: string,
+  modelId: string,
+  placement: FixReceiptPlacement,
+  compatKeys: Record<string, unknown>,
+  targetExistedBefore: boolean,
+  backupPath: string,
+  now: number = Date.now(),
+): ModelsJsonFixReceiptV1 | undefined {
+  const backupFile = basename(backupPath);
+  if (!/^models\.json\.backup-cache-optimizer-/.test(backupFile)) return undefined;
+  const beforeTarget = locateReceiptCompatTarget(originalText, provider, modelId, placement);
+  const afterTarget = locateReceiptCompatTarget(modifiedText, provider, modelId, placement);
+  if (targetExistedBefore && !beforeTarget?.targetExists) return undefined;
+  if (!afterTarget?.targetExists) return undefined;
+
+  const changedKeys: Record<string, FixReceiptCompatChange> = {};
+  for (const [key, afterValue] of Object.entries(compatKeys)) {
+    if (!isReceiptScalar(afterValue)) return undefined;
+    const before = readReceiptCompatScalarState(originalText, beforeTarget, key);
+    const after = readReceiptCompatScalarState(modifiedText, afterTarget, key);
+    if (!before || !after || !sameReceiptScalarState(after, { present: true, value: afterValue })) return undefined;
+    if (!sameReceiptScalarState(before, after)) changedKeys[key] = { before, after };
+  }
+  if (Object.keys(changedKeys).length === 0) return undefined;
+
+  const receipt: ModelsJsonFixReceiptV1 = {
+    version: 1,
+    kind: "pi-cache-optimizer-fix-receipt",
+    transactionId: randomUUID(),
+    provider,
+    modelId,
+    placement,
+    targetExistedBefore,
+    changedKeys,
+    beforeHash: hashText(originalText),
+    afterHash: hashText(modifiedText),
+    backupFile,
+    createdAt: now,
+    appliedAt: now,
+  };
+  return parseModelsJsonFixReceipt(receipt);
+}
+
+function maskJsonSyntaxPreservingComments(text: string, start: number, end: number): string {
+  // Replace only JSON syntax/value bytes. Comments are copied verbatim so a
+  // user explanation attached to a receipt-owned key survives a surgical
+  // rollback. Newlines are also retained to keep line structure unchanged.
+  const output = text.slice(start, end).split("");
+  let i = start;
+  let inLineComment = false;
+  let inBlockComment = false;
+  let inString = false;
+  let escaped = false;
+  while (i < end) {
+    const ch = text[i];
+    const next = text[i + 1];
+    const offset = i - start;
+    if (inLineComment) {
+      if (ch === "\n" || ch === "\r") inLineComment = false;
+      i++;
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === "*" && next === "/") {
+        i += 2;
+        inBlockComment = false;
+      } else {
+        i++;
+      }
+      continue;
+    }
+    if (inString) {
+      if (ch === "\n" || ch === "\r") {
+        i++;
+        continue;
+      }
+      output[offset] = " ";
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      i++;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      output[offset] = " ";
+    } else if (ch === "/" && next === "/") {
+      inLineComment = true;
+      i += 2;
+      continue;
+    } else if (ch === "/" && next === "*") {
+      inBlockComment = true;
+      i += 2;
+      continue;
+    } else if (ch !== "\n" && ch !== "\r") {
+      output[offset] = " ";
+    }
+    i++;
+  }
+  return output.join("");
+}
+
+type JsonPropertyEdit = { start: number; end: number; text: string };
+
+function locateJsonPropertyValueSpan(
+  text: string,
+  objectBrace: number,
+  objectEnd: number,
+  key: string,
+): { keyStart: number; valueStart: number; valueEnd: number; removal: JsonPropertyEdit } | undefined {
+  const clean = stripJsoncComments(text);
+  const property = findJsonObjectKey(clean, objectBrace, key);
+  if (!property || property.keyStart >= objectEnd || property.count !== 1) return undefined;
+  const valueStart = skipJsonWhitespace(clean, property.valueStart);
+  const valueEnd = skipJsonValue(clean, valueStart);
+  if (valueEnd === undefined || valueEnd > objectEnd) return undefined;
+
+  const next = skipJsonWhitespace(clean, valueEnd);
+  if (clean[next] === ",") {
+    return {
+      keyStart: property.keyStart,
+      valueStart,
+      valueEnd,
+      removal: {
+        start: property.keyStart,
+        end: next + 1,
+        text: maskJsonSyntaxPreservingComments(text, property.keyStart, next + 1),
+      },
+    };
+  }
+
+  let previous = property.keyStart - 1;
+  while (previous >= objectBrace && isJsonWhitespace(clean[previous])) previous--;
+  const removalStart = clean[previous] === "," ? previous : property.keyStart;
+  return {
+    keyStart: property.keyStart,
+    valueStart,
+    valueEnd,
+    removal: {
+      start: removalStart,
+      end: valueEnd,
+      text: maskJsonSyntaxPreservingComments(text, removalStart, valueEnd),
+    },
+  };
+}
+
+function composeModelsJsonReceiptRollback(
+  currentText: string,
+  receipt: ModelsJsonFixReceiptV1,
+): { modifiedText: string; changed: boolean } | { error: string } {
+  if (!receipt.targetExistedBefore) {
+    return { error: "the fix created a new target entry and the file changed; refusing to remove user changes automatically" };
+  }
+
+  const target = locateReceiptCompatTarget(currentText, receipt.provider, receipt.modelId, receipt.placement);
+  if (!target?.targetExists) {
+    return { error: "the original target entry is missing or no longer safely locatable" };
+  }
+  if (target.compatBrace < 0 || target.compatEnd <= target.compatBrace) {
+    return { error: "the target compat object is missing or no longer safely locatable" };
+  }
+
+  const edits: JsonPropertyEdit[] = [];
+  for (const [key, change] of Object.entries(receipt.changedKeys)) {
+    const current = readReceiptCompatScalarState(currentText, target, key);
+    if (!current || !sameReceiptScalarState(current, change.after)) {
+      return { error: `receipt-owned compat.${key} was changed after the fix; refusing to overwrite it` };
+    }
+    const property = locateJsonPropertyValueSpan(currentText, target.compatBrace, target.compatEnd, key);
+    if (!property) return { error: `receipt-owned compat.${key} is no longer safely locatable` };
+    if (change.before.present) {
+      edits.push({
+        start: property.valueStart,
+        end: property.valueEnd,
+        text: JSON.stringify(change.before.value),
+      });
+    } else {
+      edits.push(property.removal);
+    }
+  }
+
+  const modifiedText = edits
+    .sort((left, right) => right.start - left.start)
+    .reduce((text, edit) => text.slice(0, edit.start) + edit.text + text.slice(edit.end), currentText);
+  return { modifiedText, changed: modifiedText !== currentText };
+}
+
+function validateModelsJsonRollback(
+  writtenText: string,
+  receipt: ModelsJsonFixReceiptV1,
+  expectedHash?: string,
+): string | null {
+  if (expectedHash !== undefined && hashText(writtenText) !== expectedHash) {
+    return "rollback result hash did not match the expected pre-fix file";
+  }
+  try {
+    parseJsonc(writtenText);
+  } catch {
+    return "rollback result is not valid JSONC";
+  }
+  // An exact hash check proves the complete pre-fix document, including a
+  // newly created target entry (which intentionally did not exist before).
+  if (expectedHash !== undefined) return null;
+
+  const target = locateReceiptCompatTarget(writtenText, receipt.provider, receipt.modelId, receipt.placement);
+  if (!target?.targetExists) return "rollback result lost the original target entry";
+  for (const [key, change] of Object.entries(receipt.changedKeys)) {
+    const state = readReceiptCompatScalarState(writtenText, target, key);
+    if (!state || !sameReceiptScalarState(state, change.before)) return `rollback result did not restore compat.${key}`;
+  }
+  return null;
+}
+
+type ModelsJsonRollbackPlan = {
+  receiptSnapshot: ModelsJsonFixReceiptSnapshot;
+  receipt: ModelsJsonFixReceiptV1;
+  currentHash: string;
+  modifiedText: string;
+  expectedResultHash?: string;
+  mode: "exact" | "surgical";
+  fileMode: number;
+  originalBackupPath: string;
+  rollbackBackupPath: string;
+};
+
+async function readRegularTextFile(path: string): Promise<{ text: string; mode: number }> {
+  const info = await lstat(path);
+  if (info.isSymbolicLink() || !info.isFile()) {
+    throw new Error("file is not a regular file");
+  }
+  const text = await readFile(path, "utf8");
+  const afterRead = await lstat(path);
+  if (
+    afterRead.isSymbolicLink() ||
+    !afterRead.isFile() ||
+    !sameFileIdentity(info, afterRead)
+  ) {
+    throw new Error("file changed while it was being read");
+  }
+  return {
+    text,
+    mode: afterRead.mode & 0o7777,
+  };
+}
+
+async function prepareModelsJsonRollback(
+  receiptSnapshot: ModelsJsonFixReceiptSnapshot | undefined,
+  modelsPath: string = MODELS_JSON_PATH,
+): Promise<ModelsJsonRollbackPlan | { error: string }> {
+  const receipt = receiptSnapshot?.receipt;
+  if (!receiptSnapshot || !isActionableModelsJsonFixReceipt(receipt)) {
+    return { error: "No unapplied /cache-optimizer fix receipt was found." };
+  }
+
+  let current: { text: string; mode: number };
+  try {
+    current = await readRegularTextFile(modelsPath);
+  } catch {
+    return { error: "models.json is missing or is not a regular file; no changes were made." };
+  }
+  const currentHash = hashText(current.text);
+  const originalBackupPath = join(dirname(modelsPath), receipt.backupFile);
+  const rollbackBackupPath = createRollbackBackupPath(modelsPath);
+
+  if (currentHash === receipt.afterHash) {
+    let backup: { text: string; mode: number };
+    try {
+      backup = await readRegularTextFile(originalBackupPath);
+    } catch {
+      return { error: "The receipt backup is missing or is not a regular file; refusing to overwrite models.json." };
+    }
+    if (hashText(backup.text) !== receipt.beforeHash) {
+      return { error: "The receipt backup hash does not match the recorded pre-fix file; refusing to overwrite models.json." };
+    }
+    try {
+      parseJsonc(backup.text);
+    } catch {
+      return { error: "The receipt backup is not valid JSONC; refusing to overwrite models.json." };
+    }
+    return {
+      receiptSnapshot,
+      receipt,
+      currentHash,
+      modifiedText: backup.text,
+      expectedResultHash: receipt.beforeHash,
+      mode: "exact",
+      fileMode: current.mode,
+      originalBackupPath,
+      rollbackBackupPath,
+    };
+  }
+
+  if (!receipt.targetExistedBefore) {
+    return {
+      error: "models.json changed after the fix, and the fix created the target entry. Refusing to remove or overwrite unrelated user changes; use the recorded backup for manual guidance.",
+    };
+  }
+
+  // A changed file is eligible only for a scalar, receipt-owned surgical
+  // rollback. Validate the current document before showing a confirmation;
+  // malformed JSONC must never be replaced by an edit derived from offsets.
+  try {
+    parseJsonc(current.text);
+  } catch {
+    return { error: "models.json changed after the fix and is not valid JSONC; refusing to overwrite user changes. Use the recorded backup for manual guidance." };
+  }
+
+  const surgical = composeModelsJsonReceiptRollback(current.text, receipt);
+  if ("error" in surgical) {
+    return {
+      error: `models.json changed after the fix. ${surgical.error}. Use the recorded backup for manual guidance.`,
+    };
+  }
+  if (!surgical.changed) {
+    return { error: "No receipt-owned change remains to roll back." };
+  }
+
+  return {
+    receiptSnapshot,
+    receipt,
+    currentHash,
+    modifiedText: surgical.modifiedText,
+    mode: "surgical",
+    fileMode: current.mode,
+    originalBackupPath,
+    rollbackBackupPath,
+  };
+}
+
+// Internal helpers exported only so the task verification script
 // (.trellis/tasks/.../verify.ts) can exercise them. They are not part of the
 // extension's public API; pi only invokes the default export below.
 export const __internals_for_tests = {
@@ -7511,6 +9673,8 @@ export const __internals_for_tests = {
   addOpenAIPromptCacheKey,
   clampPromptCacheKey,
   hasEffectivePromptCacheKey,
+  omitOpenAIPromptCacheKeys,
+  isPromptCacheKeyOmittedForModel,
   isNonEmptyString,
   shouldInjectOpenAIPromptCacheKey,
   shouldInjectOpenAIPromptCacheKeyForModel,
@@ -7531,7 +9695,9 @@ export const __internals_for_tests = {
   describeMissingOpenAICompatibleProxyCompat,
   describeOptionalOpenAICompatibleProxyCompat,
   describeMissingDeepSeekCompat,
+  isDeepSeekWireCompatApplicable,
   isDeepSeekCompatCheckApplicable,
+  hasExplicitDeepSeekReasoningProtocol,
   describeMissingCacheCompatForModel,
   buildDeepSeekCompatSuggestion,
   buildDeepSeekCompatWarningText,
@@ -7545,6 +9711,15 @@ export const __internals_for_tests = {
   isOpenAISdkHeader403Applicable,
   hasPromptCacheRetentionUnsupportedSignal,
   hasPromptCacheRetentionUnsupportedErrorMessage,
+  hasPromptCacheKeyUnsupportedSignal,
+  hasPromptCacheKeyUnsupportedErrorMessage,
+  isPromptCacheKeyUnsupportedApplicable,
+  hasReasoningProtocolRejectionText,
+  hasReasoningProtocolRejectionSignal,
+  hasReasoningProtocolRejectionErrorMessage,
+  isReasoningProtocolRejectionSignalApplicable,
+  isReasoningProtocolRejectionForModel,
+  buildReasoningProtocolFixSuggestion,
   // Non-GPT OpenAI-compatible model detection
   isKimiLikeModel,
   isKimiLikeAssistantMessage,
@@ -7666,6 +9841,12 @@ export const __internals_for_tests = {
   isValidModelsConfigForEffectiveCompat,
   addEffectiveSessionAffinityHeaders,
   getCompat,
+  isKnownToolOrderApi,
+  getToolNameForPayload,
+  compareToolOrderEntries,
+  isVerifiedToolForApi,
+  normalizeToolsInPayload,
+  sortToolsInPayload,
   modelKey,
   modelFromAssistantMessage,
   consolidateDirectProviderStatsModel,
@@ -7683,6 +9864,8 @@ export const __internals_for_tests = {
   formatOptimizerRuntimeMode,
   PI_CACHE_RETENTION_ENV,
   LONG_CACHE_RETENTION_VALUE,
+  TOOL_ORDER_ENV,
+  isToolOrderEnabled,
   // Integrity diagnostics
   getLastPromptIntegrityWarningAt,
   // Diagnostic command helpers
@@ -7725,15 +9908,27 @@ export const __internals_for_tests = {
   selectFooterStatsForModel,
   parseFooterStatsMode,
   parsePersistedCacheOptimizerConfig,
+  readPersistedCacheOptimizerConfig,
+  writePersistedCacheOptimizerConfig,
   readPersistedFooterMode,
   writePersistedFooterMode,
+  setPersistedCacheOptimizerConfig,
   resolveFooterStatsMode,
   footerStatsMode,
   CONFIG_FILE_PATH,
+  CONFIG_RECEIPT_PATH,
+  parsePromptCacheKeyConfigReceipt,
+  isActionablePromptCacheKeyConfigReceipt,
+  readPromptCacheKeyConfigReceipt,
+  writePromptCacheKeyConfigReceipt,
+  applyPromptCacheKeyConfigFix,
+  rollbackPromptCacheKeyConfig,
+  configReceiptBackupPath,
   FOOTER_MODE_ENV,
   // Routing-provider protocol helpers
   PI_ROUTING_REGISTRY_SYMBOL,
   PI_CACHE_HINTS_SYMBOL,
+  REASONING_PROTOCOL_FALLBACK_SYMBOL,
   ensureRoutingRegistry,
   getRoutingRegistry,
   parseRouteSnapshot,
@@ -7771,6 +9966,8 @@ export const __internals_for_tests = {
   STATE_FILE_PATH,
   LEGACY_STATE_FILE_PATH,
   SHARD_STATE_DIR,
+  FIX_RECEIPT_FILE_NAME,
+  FIX_RECEIPT_PATH,
   SHARD_FILES_DIR,
   SHARD_GLOBAL_EPOCH_PATH,
   STATE_DIR,
@@ -7798,6 +9995,20 @@ export const __internals_for_tests = {
   atomicReplaceTextFilePreservingMode,
   atomicRestoreFileFromBackup,
   applyModelsJsonFixTransaction,
+  hashText,
+  parseModelsJsonFixReceipt,
+  isActionableModelsJsonFixReceipt,
+  hasReceiptReasoningProtocolChange,
+  createRollbackBackupPath,
+  createModelsJsonFixReceipt,
+  writeModelsJsonFixReceipt,
+  readModelsJsonFixReceipt,
+  readModelsJsonFixReceiptSnapshot,
+  markModelsJsonFixReceiptRolledBack,
+  receiptBackupPath,
+  composeModelsJsonReceiptRollback,
+  validateModelsJsonRollback,
+  prepareModelsJsonRollback,
   // Fix suggestion builder
   buildFixSuggestion,
   // Adaptive thinking compat helpers
@@ -7822,6 +10033,11 @@ export default function (pi: ExtensionAPI) {
   const warnedSendSessionAffinityHeaders403Models = new Set<string>();
   const openAISdkHeader403Models = new Set<string>();
   const warnedOpenAISdkHeader403Models = new Set<string>();
+  const reasoningProtocolFallbackState = getReasoningProtocolFallbackState();
+  const reasoningProtocolRejectedModels = reasoningProtocolFallbackState.modelKeys;
+  const warnedReasoningProtocolRejectedModels = reasoningProtocolFallbackState.warnedModelKeys;
+  const promptCacheKeyRejectedModels = new Set<string>();
+  const warnedPromptCacheKeyRejectedModels = new Set<string>();
   let cacheStatsByModel: Record<string, CacheStats> = {};
   let cacheStatsProcessByModel: Record<string, CacheStats> = {};
   let cacheStatsTotalsByModel: Record<string, CacheStats> = {};
@@ -7845,6 +10061,13 @@ export default function (pi: ExtensionAPI) {
   let currentSessionHashSet = false;
   let lastActualRoutedModel: PersistedRoutedModelRef | undefined;
   let latestCacheHint: PiCacheHintSnapshot | undefined;
+  // Pi's response hooks do not expose a request id. Track one FIFO lifecycle
+  // record per request and mark records when their response hook arrives. A
+  // finalized assistant message consumes the oldest completed record, falling
+  // back to the oldest request only when a transport emitted no response hook.
+  // This preserves response A when request B/C starts before message_end(A).
+  type ProviderRequestState = { model: PiModel; responseReceived: boolean };
+  const providerRequestStates: ProviderRequestState[] = [];
   let shardCreatedAt = Date.now();
   const PERSIST_DEBOUNCE_MS = 2000;
   const SHARD_REFRESH_DEBOUNCE_MS = 250;
@@ -7873,7 +10096,14 @@ export default function (pi: ExtensionAPI) {
 
   function buildCommandFixSuggestion(model: PiModel): FixSuggestion | undefined {
     const regular = buildFixSuggestion(model);
-    const observed = buildObservedRuntimeFixSuggestion(model);
+    const observedReasoning = buildReasoningProtocolFixSuggestion(
+      model,
+      reasoningProtocolRejectedModels.has(modelKey(model)),
+    );
+    const observed = mergeFixSuggestions(
+      buildObservedRuntimeFixSuggestion(model),
+      observedReasoning,
+    );
     if (!regular) return observed;
     if (!observed) return regular;
     return {
@@ -7883,6 +10113,21 @@ export default function (pi: ExtensionAPI) {
       forceModelLevel: regular.forceModelLevel || observed.forceModelLevel,
     };
   }
+
+  function promptCacheKeyFixApplies(model: PiModel): boolean {
+    return isPromptCacheKeyUnsupportedApplicable(model) && promptCacheKeyRejectedModels.has(modelKey(model));
+  }
+
+  function buildPromptCacheKeyConfigPreview(model: PiModel): string[] {
+    const key = modelKey(model);
+    return [
+      `Target: ${key}`,
+      `Action: persist prompt_cache_key mode = omit in ${CONFIG_FILE_PATH}.`,
+      "The final request body will omit both prompt_cache_key and promptCacheKey.",
+      "This can reduce provider-side prompt-cache reuse for this model; it does not change prompts, credentials, headers, or other models.",
+      "The setting applies after Pi core has built the payload, including when Pi already supplied a key.",
+    ];
+  }
   /** In-memory recent usage samples per model key (not persisted, cleared on reload). */
   const recentSamplesByModelKey = new Map<string, CacheUsageSample[]>();
 
@@ -8380,6 +10625,7 @@ export default function (pi: ExtensionAPI) {
       shardWatcher?.close();
       shardWatcher = undefined;
       latestCacheHint = undefined;
+      providerRequestStates.length = 0;
       delete getProtocolGlobal().__piCacheOptimizerCacheKey__;
       uninstallCacheHintsService();
       restoreCacheRetentionEnv(STARTUP_CACHE_RETENTION_ENV);
@@ -8440,9 +10686,7 @@ export default function (pi: ExtensionAPI) {
     // prompt mutations below (session-overview churn strip, skill compression,
     // and stable-prefix reordering). Footer stats and the OpenAI
     // prompt_cache_key fallback remain active.
-    if (isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV])) {
-      return {};
-    }
+    if (isEnabledEnv(process.env[NO_PROMPT_REWRITE_ENV])) return {};
 
     // Step 1: strip per-turn churn from <session-overview>.
     // Removing RECENT COMMITS, Working directory status, and
@@ -8523,6 +10767,18 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("before_provider_request", (event, ctx) => {
     const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+    if (runtimeOptimizerEnabled) {
+      const snapshot = snapshotProviderRequestModel(requestModel);
+      if (snapshot) providerRequestStates.push({ model: snapshot, responseReceived: false });
+    }
+    let requestPayload: unknown = event.payload;
+    let toolOrderChanged = false;
+
+    if (isToolOrderEnabled() && isToolOrderingEligibleModel(requestModel)) {
+      const normalized = normalizeToolsInPayload(requestPayload, requestModel.api);
+      requestPayload = normalized.payload;
+      toolOrderChanged = normalized.changed;
+    }
 
     // Anthropic rejects mixed cache breakpoints when a 1h block appears after
     // a 5m/default block in wire order (tools → system → messages). Repair any
@@ -8530,9 +10786,9 @@ export default function (pi: ExtensionAPI) {
     // hidden short breakpoints after this hook; only models that have actually
     // returned the explicit TTL-order error receive the process-local 5m fallback.
     if (requestModel && isAnthropicMessagesApi(requestModel.api)) {
-      const visibleConflictFixed = normalizeAnthropicCacheControlTtlOrder(event.payload);
+      const visibleConflictFixed = normalizeAnthropicCacheControlTtlOrder(requestPayload);
       if (!visibleConflictFixed && anthropicTtlOrderErrorModels.has(modelKey(requestModel))) {
-        downgradeAnthropicLongCacheControls(event.payload);
+        downgradeAnthropicLongCacheControls(requestPayload);
       }
     }
 
@@ -8550,50 +10806,89 @@ export default function (pi: ExtensionAPI) {
     // Gate 2 before Gate 3 is critical: if a user explicitly opted in but
     // the API returned 400, we must strip — otherwise the 400 repeats forever.
     if (runtimeOptimizerEnabled) {
-      const payload = event.payload as UnknownRecord;
-      if (payload && typeof payload.prompt_cache_retention === 'string') {
+      const payloadRecord = asRecord(requestPayload);
+      if (payloadRecord && typeof payloadRecord.prompt_cache_retention === "string") {
         if (requestModel) {
           if (isOfficialOpenAIBaseUrl(requestModel)) {
             // Gate 1: Official OpenAI → keep
           } else if (promptCacheRetention400Models.has(modelKey(requestModel))) {
             // Gate 2: 400 history → strip (overrides user opt-in)
-            delete payload.prompt_cache_retention;
+            delete payloadRecord.prompt_cache_retention;
           } else if (hasExplicitLongRetentionOptIn(requestModel)) {
             // Gate 3: Explicit user opt-in → keep
           } else {
             // Gate 4: Safe default → strip
-            delete payload.prompt_cache_retention;
+            delete payloadRecord.prompt_cache_retention;
           }
         }
       }
     }
 
-    if (!shouldInjectOpenAIPromptCacheKey()) return undefined;
-    if (!shouldInjectOpenAIPromptCacheKeyForModel(requestModel)) return undefined;
+    if (isPromptCacheKeyOmittedForModel(requestModel)) {
+      const omitted = omitOpenAIPromptCacheKeys(requestPayload);
+      return omitted ?? (toolOrderChanged ? requestPayload : undefined);
+    }
+
+    if (!shouldInjectOpenAIPromptCacheKey() || !shouldInjectOpenAIPromptCacheKeyForModel(requestModel)) {
+      return toolOrderChanged ? requestPayload : undefined;
+    }
 
-    return addOpenAIPromptCacheKey(event.payload, getSessionPromptCacheKey(ctx));
+    const withCacheKey = addOpenAIPromptCacheKey(requestPayload, getSessionPromptCacheKey(ctx));
+    return withCacheKey ?? (toolOrderChanged ? requestPayload : undefined);
   });
 
-  pi.on("after_provider_response", (event, ctx) => {
-    const model = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+  pi.on("after_provider_response", async (event, ctx) => {
+    const responseState = providerRequestStates.find((state) => !state.responseReceived);
+    if (responseState) responseState.responseReceived = true;
+    const model = responseState?.model ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
     if (!runtimeOptimizerEnabled || !model) return;
 
-    // ── 400: prompt_cache_retention unsupported ──
-    if (event.status === 400) {
-      if (!isPromptCacheRetention400Applicable(model)) return;
-      if (!hasPromptCacheRetentionUnsupportedSignal(event.headers)) return;
+    // Keep only the category, never the provider's complete error text. This
+    // is evidence for a later, model-scoped `/fix`; it never edits config from
+    // a response hook.
+    if (
+      isReasoningProtocolRejectionSignalApplicable(model) &&
+      event.status === 400 &&
+      hasReasoningProtocolRejectionSignal(event.headers)
+    ) {
+      await notifyReasoningProtocolObservation(
+        model,
+        ctx,
+        reasoningProtocolRejectedModels,
+        warnedReasoningProtocolRejectedModels,
+      );
+    }
+
+    // ── 400: prompt_cache_key unsupported ──
+    if (event.status === 400 && isPromptCacheKeyUnsupportedApplicable(model) && hasPromptCacheKeyUnsupportedSignal(event.headers)) {
+      const key = modelKey(model);
+      promptCacheKeyRejectedModels.add(key);
+      if (!warnedPromptCacheKeyRejectedModels.has(key)) {
+        warnedPromptCacheKeyRejectedModels.add(key);
+        ctx.ui.notify(
+          `⚠️ ${LOG_PREFIX}: ${key} rejected prompt_cache_key. Run /cache-optimizer fix to review a precise model-scoped repair. No configuration was changed automatically.`,
+          "warning",
+        );
+      }
+    }
 
+    // ── 400: prompt_cache_retention unsupported ──
+    if (
+      event.status === 400 &&
+      isPromptCacheRetention400Applicable(model) &&
+      hasPromptCacheRetentionUnsupportedSignal(event.headers)
+    ) {
       const key = modelKey(model);
       promptCacheRetention400Models.add(key);
-      if (warnedPromptCacheRetention400Models.has(key)) return;
-      warnedPromptCacheRetention400Models.add(key);
-      ctx.ui.notify(
-        `⚠️ ${LOG_PREFIX}: ${key} returned HTTP 400 while supportsLongCacheRetention is enabled. ` +
-        getPromptCacheRetentionUnsupportedHint() +
-        ` Run /cache-optimizer doctor for the exact edit location.`,
-        "warning",
-      );
-      return;
+      if (!warnedPromptCacheRetention400Models.has(key)) {
+        warnedPromptCacheRetention400Models.add(key);
+        ctx.ui.notify(
+          `⚠️ ${LOG_PREFIX}: ${key} returned HTTP 400 while supportsLongCacheRetention is enabled. ` +
+          getPromptCacheRetentionUnsupportedHint() +
+          ` Run /cache-optimizer doctor for the exact edit location.`,
+          "warning",
+        );
+      }
     }
 
     // ── 403: proxy/CDN/WAF blocking ──
@@ -8638,13 +10933,55 @@ export default function (pi: ExtensionAPI) {
   pi.on("message_end", async (event, ctx) => {
     syncSessionHash(ctx);
     const msgRecord = asRecord(event.message);
+    const requestModelForMessage = msgRecord?.role === "assistant"
+      ? (() => {
+        const completedIndex = providerRequestStates.findIndex((state) => state.responseReceived);
+        const index = completedIndex >= 0 ? completedIndex : 0;
+        return providerRequestStates.splice(index, 1)[0]?.model;
+      })()
+      : undefined;
 
     // Some providers expose an HTTP 400 error body only through the finalized
     // assistant error message; after_provider_response may contain the status
-    // and no diagnostic response headers. Record the same model-scoped
-    // prompt_cache_retention fallback from that authoritative message identity.
+    // and no diagnostic response headers. Record only the model-scoped
+    // reasoning-protocol category from that authoritative message identity.
+    if (runtimeOptimizerEnabled && hasReasoningProtocolRejectionErrorMessage(event.message)) {
+      const fallbackModel = requestModelForMessage
+        ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
+      const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
+      const errorModel = messageModel
+        ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel
+        : undefined;
+      if (isReasoningProtocolRejectionForModel(event.message, errorModel)) {
+        await notifyReasoningProtocolObservation(
+          errorModel,
+          ctx,
+          reasoningProtocolRejectedModels,
+          warnedReasoningProtocolRejectedModels,
+        );
+      }
+    }
+    if (runtimeOptimizerEnabled && hasPromptCacheKeyUnsupportedErrorMessage(event.message)) {
+      const fallbackModel = requestModelForMessage ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
+      const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
+      const errorModel = messageModel
+        ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel
+        : undefined;
+      if (errorModel && isPromptCacheKeyUnsupportedApplicable(errorModel)) {
+        const key = modelKey(errorModel);
+        promptCacheKeyRejectedModels.add(key);
+        if (!warnedPromptCacheKeyRejectedModels.has(key)) {
+          warnedPromptCacheKeyRejectedModels.add(key);
+          ctx.ui.notify(
+            `⚠️ ${LOG_PREFIX}: ${key} rejected prompt_cache_key. Run /cache-optimizer fix to review a precise model-scoped repair. No configuration was changed automatically.`,
+            "warning",
+          );
+        }
+      }
+    }
     if (runtimeOptimizerEnabled && hasPromptCacheRetentionUnsupportedErrorMessage(event.message)) {
-      const fallbackModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+      const fallbackModel = requestModelForMessage
+        ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
       const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
       const errorModel = messageModel
         ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel
@@ -8668,7 +11005,8 @@ export default function (pi: ExtensionAPI) {
     // non-retryable 400 in Pi 0.82.1, so the fallback applies to the next
     // subsequent request (and to a retry only if another layer initiates one).
     if (hasAnthropicCacheTtlOrderError(event.message)) {
-      const fallbackModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+      const fallbackModel = requestModelForMessage
+        ?? (resolveRouteModel(ctx.model, ctx) ?? ctx.model);
       const errorModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
       if (errorModel && isAnthropicMessagesApi(errorModel.api)) {
         const key = modelKey(errorModel);
@@ -8789,7 +11127,8 @@ export default function (pi: ExtensionAPI) {
   //   stats   — show detailed current-session models; `stats all` shows all local shards
   //   compat  — show compat suggestion with file path
   //   config footer-mode total|session|process — persist footer mode override
-  //   fix     — auto-fix compat issues (writes models.json, requires UI)
+  //   fix     — auto-fix compat issues (writes models.json or extension config, requires UI)
+  //   rollback — undo the latest confirmed fix for the active model
   //   reset   — reset current provider/model footer stats bucket (local only)
   //   (no args) — interactive menu (with UI) or help summary
   // ────────────────────────────────────────────────────────────────
@@ -8811,6 +11150,7 @@ export default function (pi: ExtensionAPI) {
         cmdCtx.ui.notify(`✅ Pi Cache Optimizer enabled for this Pi process. Local footer stats were reset for before/after comparison.\n${formatOptimizerRuntimeMode()}`, "info");
       } else if (subcommand === "disable") {
         setRuntimeOptimizerEnabled(false);
+        providerRequestStates.length = 0;
         await resetCurrentSessionStats();
         await flushPersistCacheStats(cmdCtx);
         await publishStatus(cmdCtx, model);
@@ -8821,7 +11161,7 @@ export default function (pi: ExtensionAPI) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
           return;
         }
-        const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), anthropicTtlOrderError: anthropicTtlOrderErrorModels.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
+        const diagnosis = buildDoctorDiagnosis(model, { promptCacheRetention400: promptCacheRetention400Models.has(modelKey(model)), promptCacheKey400: promptCacheKeyRejectedModels.has(modelKey(model)), anthropicTtlOrderError: anthropicTtlOrderErrorModels.has(modelKey(model)), sessionAffinity403: sendSessionAffinityHeaders403Models.has(modelKey(model)), openAISdkHeader403: openAISdkHeader403Models.has(modelKey(model)) });
         const adapter = selectAdapterForModel(model);
         const sk = model ? sessionModelKey(model) : undefined;
         const statsState = model ? cacheStatsTotalsByModel[modelKey(model)] : undefined;
@@ -8860,7 +11200,7 @@ export default function (pi: ExtensionAPI) {
         const nextMode = requestedMode as FooterStatsMode;
         try {
           await writePersistedFooterMode(nextMode);
-          persistedFooterStatsMode = nextMode;
+          setPersistedCacheOptimizerConfig(readPersistedCacheOptimizerConfig());
           lastStatusText = undefined;
           await publishStatus(cmdCtx, model);
           const resolved = resolveFooterStatsMode(persistedFooterStatsMode);
@@ -8890,6 +11230,133 @@ export default function (pi: ExtensionAPI) {
             "info",
           );
         }
+      } else if (subcommand === "rollback") {
+        if (!model) {
+          cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
+          return;
+        }
+        const configReceipt = await readPromptCacheKeyConfigReceipt();
+        const modelsReceipt = await readModelsJsonFixReceipt();
+        const useConfigReceipt = isActionablePromptCacheKeyConfigReceipt(configReceipt) &&
+          configReceipt.provider === model.provider &&
+          configReceipt.modelId === model.id &&
+          (!isActionableModelsJsonFixReceipt(modelsReceipt) || modelsReceipt.provider !== model.provider || modelsReceipt.modelId !== model.id || configReceipt.appliedAt >= modelsReceipt.appliedAt);
+        if (useConfigReceipt) {
+          if (!cmdCtx.hasUI) {
+            cmdCtx.ui.notify("❌ Rollback requires interactive confirmation. No changes were made.\nRun /cache-optimizer rollback in Pi's interactive UI to restore the prompt-cache-key setting.", "warning");
+            return;
+          }
+          const confirmed = await cmdCtx.ui.confirm(
+            "Cache Optimizer — Rollback prompt_cache_key opt-out",
+            `Model: ${modelKey(model)}\nAction: restore the extension config before the confirmed opt-out.\nFooter mode and unrelated configuration will be preserved.\nAfterward, run /reload or restart Pi.\n\nProceed with rollback?`,
+          );
+          if (!confirmed) {
+            cmdCtx.ui.notify("No changes were made. Rollback canceled by user.", "info");
+            return;
+          }
+          try {
+            await rollbackPromptCacheKeyConfig(configReceipt);
+            setPersistedCacheOptimizerConfig(readPersistedCacheOptimizerConfig());
+            cmdCtx.ui.notify(`✅ Restored prompt_cache_key behavior for ${modelKey(model)}. Run /reload or restart Pi for the change to take effect.`, "info");
+          } catch (error) {
+            cmdCtx.ui.notify(`❌ Prompt cache key rollback refused: ${error instanceof Error ? error.message : String(error)}. No changes were made.`, "error");
+          }
+          return;
+        }
+        if (!cmdCtx.hasUI) {
+          const receipt = await readModelsJsonFixReceipt();
+          const backupHint = receipt && isActionableModelsJsonFixReceipt(receipt)
+            ? ` The recorded backup is ${receipt.backupFile} next to ${getModelsJsonDisplayPath()}.`
+            : " Check the recorded models.json backup manually if a fix receipt exists.";
+          cmdCtx.ui.notify(
+            "❌ Rollback requires interactive confirmation. No changes were made.\n" +
+            `Run /cache-optimizer rollback in Pi's interactive UI.${backupHint} Then run /reload.`,
+            "warning",
+          );
+          return;
+        }
+
+        const receiptSnapshot = await readModelsJsonFixReceiptSnapshot();
+        const receipt = receiptSnapshot?.receipt;
+        if (!receiptSnapshot || !isActionableModelsJsonFixReceipt(receipt)) {
+          cmdCtx.ui.notify("ℹ️ No unapplied /cache-optimizer fix receipt was found.", "info");
+          return;
+        }
+        if (receipt.provider !== model.provider || receipt.modelId !== model.id) {
+          cmdCtx.ui.notify(
+            `ℹ️ The latest fix receipt is for ${receipt.provider}/${receipt.modelId}, not the active model ${model.provider}/${model.id}. ` +
+            "Switch to the matching model before running rollback. No changes were made.",
+            "warning",
+          );
+          return;
+        }
+
+        const rollback = await prepareModelsJsonRollback(receiptSnapshot);
+        if ("error" in rollback) {
+          cmdCtx.ui.notify(`ℹ️ ${rollback.error}`, "info");
+          return;
+        }
+
+        const rollbackScope = rollback.mode === "exact"
+          ? "restore the exact pre-fix models.json because the file is unchanged since the fix"
+          : "restore only the receipt-owned compat scalar keys and preserve subsequent user changes";
+        const rollbackPreview = [
+          `Rollback transaction ${rollback.receipt.transactionId}:`,
+          `Model: ${rollback.receipt.provider}/${rollback.receipt.modelId}`,
+          `Action: ${rollbackScope}.`,
+          `A new rollback backup will be written to: ${rollback.rollbackBackupPath}`,
+          "Comments, credentials, unrelated fields, and the existing access mode will be preserved.",
+          "Afterward, run /reload or restart Pi for the configuration change to take effect.",
+          "",
+          "Proceed with rollback?",
+        ].join("\n");
+        const confirmed = await cmdCtx.ui.confirm("Cache Optimizer — Rollback", rollbackPreview);
+        if (!confirmed) {
+          cmdCtx.ui.notify("No changes were made. Rollback canceled by user.", "info");
+          return;
+        }
+
+        try {
+          const result = await applyModelsJsonFixTransaction(
+            rollback.modifiedText,
+            rollback.rollbackBackupPath,
+            (writtenText) => validateModelsJsonRollback(
+              writtenText,
+              rollback.receipt,
+              rollback.expectedResultHash,
+            ),
+            {
+              expectedCurrentHash: rollback.currentHash,
+              expectedCurrentMode: rollback.fileMode,
+              receiptGuard: rollback.receiptSnapshot,
+              purpose: "rollback",
+              onCommitted: async () => {
+                await markModelsJsonFixReceiptRolledBack(rollback.receiptSnapshot);
+              },
+            },
+          );
+          if ("postCheckError" in result) {
+            cmdCtx.ui.notify(
+              `❌ Rollback self-check failed: ${result.postCheckError}\n` +
+              `The rollback backup at ${rollback.rollbackBackupPath} was restored. No changes applied.`,
+              "error",
+            );
+            return;
+          }
+          invalidateModelsConfigCache();
+          cmdCtx.ui.notify(
+            `✅ Rollback completed for ${rollback.receipt.provider}/${rollback.receipt.modelId}.\n` +
+            `Rollback backup saved to: ${rollback.rollbackBackupPath}\n` +
+            "The receipt was marked as rolled back. Run /reload or restart Pi for the change to take effect.",
+            "info",
+          );
+        } catch (rollbackError) {
+          cmdCtx.ui.notify(
+            `❌ Rollback failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}\n` +
+            "No automatic overwrite was performed; use the recorded backup for manual guidance.",
+            "error",
+          );
+        }
       } else if (subcommand === "reset") {
         if (!model) {
           cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
@@ -8926,7 +11393,58 @@ export default function (pi: ExtensionAPI) {
           return;
         }
 
-        const suggestion = buildCommandFixSuggestion(model);
+        const promptCacheKeyRequested = commandParts[1] === "prompt-cache-key";
+        const promptCacheKeyFixRequested = promptCacheKeyRequested || promptCacheKeyFixApplies(model);
+        if (promptCacheKeyRequested && !isPromptCacheKeyUnsupportedApplicable(model)) {
+          cmdCtx.ui.notify("ℹ️ Prompt cache key opt-out applies only to a known OpenAI-compatible provider/model endpoint. No changes were made.", "info");
+          return;
+        }
+        const suggestion = promptCacheKeyFixRequested ? undefined : buildCommandFixSuggestion(model);
+
+        if (promptCacheKeyFixRequested) {
+          if (isPromptCacheKeyOmittedForModel(model)) {
+            cmdCtx.ui.notify(`✅ prompt_cache_key is already omitted for "${modelKey(model)}".`, "info");
+            return;
+          }
+          if (!cmdCtx.hasUI) {
+            cmdCtx.ui.notify(
+              "❌ Non-interactive terminal detected. Prompt cache key opt-out requires UI confirmation. No changes were made.\n" +
+              `Run /cache-optimizer fix prompt-cache-key in Pi's interactive UI for ${modelKey(model)}.`,
+              "warning",
+            );
+            return;
+          }
+          const preview = [
+            "📝 Preview of extension configuration change:",
+            ...buildPromptCacheKeyConfigPreview(model),
+            "",
+            "⚠️ Risk notice:",
+            "  1. This affects all sessions using this exact provider/model.",
+            "  2. Provider prompt-cache reuse may decrease because both key spellings are removed.",
+            "  3. This does not modify Pi's models.json, credentials, prompts, headers, or other models.",
+            "  4. The extension config will be backed up and Pi must be reloaded/restarted.",
+            "",
+            "Apply this persistent opt-out?",
+          ].join("\n");
+          const confirmed = await cmdCtx.ui.confirm("Cache Optimizer — Omit prompt_cache_key", preview);
+          if (!confirmed) {
+            cmdCtx.ui.notify("No changes were made. Canceled by user.", "info");
+            return;
+          }
+          try {
+            const result = await applyPromptCacheKeyConfigFix(model);
+            setPersistedCacheOptimizerConfig(readPersistedCacheOptimizerConfig());
+            cmdCtx.ui.notify(
+              `✅ Prompt cache key opt-out saved for ${modelKey(model)}.\n` +
+              `Config backup saved to: ${result.backupPath}\n` +
+              "Run /reload or restart Pi for the change to take effect. Use /cache-optimizer rollback to restore it.",
+              "info",
+            );
+          } catch (error) {
+            cmdCtx.ui.notify(`❌ Could not save prompt cache key opt-out: ${error instanceof Error ? error.message : String(error)}. No changes were made.`, "error");
+          }
+          return;
+        }
 
         if (!suggestion) {
           const key = modelKey(model);
@@ -9021,6 +11539,7 @@ export default function (pi: ExtensionAPI) {
             const checkError = selfCheckMissingEntryInsertion(
               originalText, plan.modifiedText,
               suggestion.providerLabel, suggestion.modelId, suggestion.compatKeys,
+              model,
             );
             if (checkError !== null) {
               // Fall through to manual guidance.
@@ -9065,6 +11584,20 @@ export default function (pi: ExtensionAPI) {
               );
               if (confirmed) {
                 try {
+                  const receipt = createModelsJsonFixReceipt(
+                    originalText,
+                    plan.modifiedText,
+                    suggestion.providerLabel,
+                    suggestion.modelId,
+                    "modelOverride",
+                    suggestion.compatKeys,
+                    repairsExistingOverride,
+                    backupPath,
+                  );
+                  if (!receipt) {
+                    cmdCtx.ui.notify("❌ Could not create a privacy-safe fix receipt. No changes were made.", "error");
+                    return;
+                  }
                   const result = await applyModelsJsonFixTransaction(
                     plan.modifiedText,
                     backupPath,
@@ -9074,7 +11607,13 @@ export default function (pi: ExtensionAPI) {
                       suggestion.providerLabel,
                       suggestion.modelId,
                       suggestion.compatKeys,
+                      model,
                     ),
+                    {
+                      expectedCurrentHash: hashText(originalText),
+                      purpose: "fix",
+                      onCommitted: async () => writeModelsJsonFixReceipt(receipt),
+                    },
                   );
                   if ("postCheckError" in result) {
                     cmdCtx.ui.notify(
@@ -9084,6 +11623,7 @@ export default function (pi: ExtensionAPI) {
                     );
                     return;
                   }
+                  invalidateModelsConfigCache();
                   cmdCtx.ui.notify(
                     `✅ Fix applied to ${getModelsJsonDisplayPath()}.\n` +
                     `Backup saved to: ${backupPath}\n` +
@@ -9161,10 +11701,45 @@ export default function (pi: ExtensionAPI) {
           suggestion.providerLabel,
           suggestion.forceModelLevel,
         );
-        const modifiedText = composeFixInsertion(originalText, location, suggestion.compatKeys, decision.placement);
+        const createsModelOverride = decision.placement === "modelOverride" && location.modelOverrideObjectBrace < 0;
+        const modelOverridePlan = createsModelOverride
+          ? composeModelOverrideInsertion(
+              originalText,
+              suggestion.providerLabel,
+              suggestion.modelId,
+              suggestion.compatKeys,
+            )
+          : undefined;
+        if (createsModelOverride && !modelOverridePlan) {
+          cmdCtx.ui.notify(
+            "❌ Could not safely create the highest-precedence model override. No changes were made.",
+            "error",
+          );
+          return;
+        }
+        const modifiedText = modelOverridePlan?.modifiedText
+          ?? composeFixInsertion(originalText, location, suggestion.compatKeys, decision.placement);
 
-        // Self-check
-        const checkError = selfCheckFix(originalText, modifiedText, suggestion.providerLabel, suggestion.modelId, suggestion.compatKeys, decision.placement);
+        // Self-check against the same provider → model → runtime →
+        // modelOverride precedence used by request hooks.
+        const checkError = createsModelOverride
+          ? selfCheckMissingEntryInsertion(
+              originalText,
+              modifiedText,
+              suggestion.providerLabel,
+              suggestion.modelId,
+              suggestion.compatKeys,
+              model,
+            )
+          : selfCheckFix(
+              originalText,
+              modifiedText,
+              suggestion.providerLabel,
+              suggestion.modelId,
+              suggestion.compatKeys,
+              decision.placement,
+              model,
+            );
         if (checkError !== null) {
           cmdCtx.ui.notify(
             `❌ Self-check failed before write: ${checkError}\n` +
@@ -9229,17 +11804,46 @@ export default function (pi: ExtensionAPI) {
 
         // Write: backup → temp + rename → self-check again
         try {
+          const receipt = createModelsJsonFixReceipt(
+            originalText,
+            modifiedText,
+            suggestion.providerLabel,
+            suggestion.modelId,
+            decision.placement,
+            suggestion.compatKeys,
+            !createsModelOverride,
+            backupPath,
+          );
+          if (!receipt) {
+            cmdCtx.ui.notify("❌ Could not create a privacy-safe fix receipt. No changes were made.", "error");
+            return;
+          }
           const result = await applyModelsJsonFixTransaction(
             modifiedText,
             backupPath,
-            (writtenText) => selfCheckFix(
-              originalText,
-              writtenText,
-              suggestion.providerLabel,
-              suggestion.modelId,
-              suggestion.compatKeys,
-              decision.placement,
-            ),
+            (writtenText) => createsModelOverride
+              ? selfCheckMissingEntryInsertion(
+                  originalText,
+                  writtenText,
+                  suggestion.providerLabel,
+                  suggestion.modelId,
+                  suggestion.compatKeys,
+                  model,
+                )
+              : selfCheckFix(
+                  originalText,
+                  writtenText,
+                  suggestion.providerLabel,
+                  suggestion.modelId,
+                  suggestion.compatKeys,
+                  decision.placement,
+                  model,
+                ),
+            {
+              expectedCurrentHash: hashText(originalText),
+              purpose: "fix",
+              onCommitted: async () => writeModelsJsonFixReceipt(receipt),
+            },
           );
           if ("postCheckError" in result) {
             cmdCtx.ui.notify(
@@ -9273,7 +11877,9 @@ export default function (pi: ExtensionAPI) {
             "Doctor — Show cache configuration",
             "Stats — Show current-session model statistics",
             "Compat — Show compat suggestion",
-            "Fix — Auto-fix compat issues (writes models.json)",
+            "Fix — Auto-fix compat issues (writes models.json or extension config)",
+            "Disable prompt_cache_key — Omit it for the active model",
+            "Rollback — Undo the latest confirmed fix",
             "Footer mode — Choose total, session, or process stats",
             "Reset — Reset local provider/model stats",
             "Cancel",
@@ -9292,6 +11898,10 @@ export default function (pi: ExtensionAPI) {
           } else if (choice === menuOptions[5]) {
             await handleCacheOptimizerCommand("fix", cmdCtx);
           } else if (choice === menuOptions[6]) {
+            await handleCacheOptimizerCommand("fix prompt-cache-key", cmdCtx);
+          } else if (choice === menuOptions[7]) {
+            await handleCacheOptimizerCommand("rollback", cmdCtx);
+          } else if (choice === menuOptions[8]) {
             const modeOptions = ["session — Current Pi conversation session (default)", "total — All local sessions today", "process — Current extension instance only", "Cancel"];
             const modeChoice = await cmdCtx.ui.select("Footer cache stats mode", modeOptions);
             const nextMode = modeChoice === modeOptions[0]
@@ -9302,7 +11912,7 @@ export default function (pi: ExtensionAPI) {
                   ? "process"
                   : undefined;
             if (nextMode) await handleCacheOptimizerCommand(`config footer-mode ${nextMode}`, cmdCtx);
-          } else if (choice === menuOptions[7]) {
+          } else if (choice === menuOptions[9]) {
             await handleCacheOptimizerCommand("reset", cmdCtx);
           }
           // choice === "cancel" or undefined → no action
@@ -9320,7 +11930,9 @@ export default function (pi: ExtensionAPI) {
         diagnosis.push("  stats contributors — Show per-session contributors for the active model");
         diagnosis.push("  compat  — Show compat suggestion with edit location");
         diagnosis.push("  config footer-mode total|session|process — Persist the footer stats mode");
-        diagnosis.push("  fix     — Auto-fix compat issues (writes models.json, requires UI)");
+        diagnosis.push("  fix     — Auto-fix compat issues (writes models.json or extension config, requires UI)");
+        diagnosis.push("  fix prompt-cache-key — Explicitly omit prompt_cache_key for the active model");
+        diagnosis.push("  rollback — Undo the latest confirmed fix (requires UI confirmation)");
         diagnosis.push("  reset   — Reset local provider/model stats for current model (does not affect upstream)");
         diagnosis.push("");
         diagnosis.push(formatOptimizerRuntimeMode());