@agimon-ai/doompi-cache 0.0.1-alpha.44 → 0.0.1-alpha.46

package/dist/{pi-cache-optimizer-BfO9Qmqm.mjs → pi-cache-optimizer-DjqO0Quf.mjs}

@@ -1,10 +1,10 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, copyFile, lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, link, lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { constants, readFileSync, statSync, watch } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-//#region ../../../node_modules/.pnpm/pi-cache-optimizer@2.8.7_@earendil-works+pi-coding-agent@0.86.0_supports-color@7.2.0_zod@4.6.2_/node_modules/pi-cache-optimizer/index.ts
+//#region ../../../node_modules/.pnpm/pi-cache-optimizer@2.8.10_@earendil-works+pi-coding-agent@0.86.0_supports-color@7.2.0_zod@4.6.5_/node_modules/pi-cache-optimizer/index.ts
 const PI_CACHE_RETENTION_ENV = "PI_CACHE_RETENTION";
 const LONG_CACHE_RETENTION_VALUE = "long";
 const PI_CACHE_RETENTION_BASELINE_SYMBOL = Symbol.for("pi.cache.optimizer.retention-baseline.v1");
@@ -70,6 +70,7 @@ 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_PATH = join(STATE_DIR, "pi-cache-optimizer-config-receipt.json");
 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");
@@ -1036,7 +1037,7 @@ function isValidAnthropicMessagesCompat(compat) {
 function isValidCompatRecord(value) {
 	if (value === void 0) return true;
 	const compat = asRecord(value);
-	return !!compat && (isValidOpenAICompletionsCompat(compat) || isValidOpenAIResponsesCompat(compat) || isValidAnthropicMessagesCompat(compat));
+	return !!compat && !Object.prototype.hasOwnProperty.call(compat, "supportsPromptCacheKey") && (isValidOpenAICompletionsCompat(compat) || isValidOpenAIResponsesCompat(compat) || isValidAnthropicMessagesCompat(compat));
 }
 function isValidModelsConfigForEffectiveCompat(value) {
 	const root = asRecord(value);
@@ -1177,6 +1178,7 @@ const CACHE_OPTIMIZER_FOOTER_MODES = [
 	"process"
 ];
 const CACHE_OPTIMIZER_STATS_ARGUMENTS = ["all", "contributors"];
+const CACHE_OPTIMIZER_FIX_ARGUMENTS = ["prompt-cache-key"];
 function filterCommandCompletionItems(values, prefix, argumentPath = "") {
 	const normalizedPrefix = prefix.trim().toLowerCase();
 	const matches = values.filter((value) => value.startsWith(normalizedPrefix)).map((value) => ({
@@ -1201,6 +1203,7 @@ function getCacheOptimizerArgumentCompletions(argumentPrefix) {
 		return filterCommandCompletionItems(CACHE_OPTIMIZER_COMMANDS, parts[0]);
 	}
 	if (parts[0].toLowerCase() === "stats") return parts.length === 2 ? filterCommandCompletionItems(CACHE_OPTIMIZER_STATS_ARGUMENTS, parts[1], "stats") : 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) {
 		if (parts[1].toLowerCase() === "footer-mode") return filterCommandCompletionItems(CACHE_OPTIMIZER_FOOTER_MODES, "", "config footer-mode");
@@ -1211,33 +1214,471 @@ function getCacheOptimizerArgumentCompletions(argumentPrefix) {
 }
 function parsePersistedCacheOptimizerConfig(value) {
 	const record = asRecord(value);
-	if (!record || record.version !== 1) return void 0;
+	if (!record || record.version !== 1 && record.version !== 2) return void 0;
+	const allowedTopLevel = new Set(record.version === 1 ? ["version", "footerMode"] : [
+		"version",
+		"footerMode",
+		"promptCacheKey"
+	]);
+	if (Object.keys(record).some((key) => !allowedTopLevel.has(key))) return void 0;
 	const footerMode = parseFooterStatsMode(record.footerMode);
 	if (record.footerMode !== void 0 && !footerMode) return void 0;
-	return {
+	if (record.version === 1) return {
 		version: 1,
 		...footerMode ? { footerMode } : {}
 	};
+	const rawPromptCacheKey = record.promptCacheKey;
+	if (rawPromptCacheKey !== void 0 && !asRecord(rawPromptCacheKey)) return void 0;
+	const promptCacheKey = asRecord(rawPromptCacheKey);
+	if (promptCacheKey && Object.keys(promptCacheKey).some((key) => key !== "omit")) return void 0;
+	const omit = promptCacheKey?.omit;
+	if (omit !== void 0 && (!Array.isArray(omit) || omit.some((value) => !isNonEmptyString(value)))) return void 0;
+	const stringOmit = omit;
+	const uniqueOmit = stringOmit ? [...new Set(stringOmit.map((value) => value.trim()))].sort() : void 0;
+	return {
+		version: 2,
+		...footerMode ? { footerMode } : {},
+		...uniqueOmit && uniqueOmit.length > 0 ? { promptCacheKey: { omit: uniqueOmit } } : {}
+	};
+}
+function normalizePersistedCacheOptimizerConfig(value) {
+	if (!value) return { version: 2 };
+	return value.version === 2 ? value : {
+		version: 2,
+		...value.footerMode ? { footerMode: value.footerMode } : {}
+	};
+}
+function readPersistedCacheOptimizerConfig(configPath = CONFIG_FILE_PATH) {
+	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 = CONFIG_FILE_PATH) {
+	return readPersistedCacheOptimizerConfig(configPath).footerMode;
+}
+async function writePersistedCacheOptimizerConfigUnlocked(config, configPath) {
+	await mkdir(dirname(configPath), { recursive: true });
+	const payloadText = JSON.stringify(normalizePersistedCacheOptimizerConfig(config), null, 2) + "\n";
+	let targetInfo;
+	let targetMode = 384;
+	let targetHash;
+	try {
+		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 & 4095;
+		targetHash = hashText(targetText);
+	} catch (error) {
+		if (getErrorCode(error) !== "ENOENT") throw error;
+	}
+	if (targetInfo) {
+		await atomicReplaceTextFilePreservingMode(configPath, payloadText, targetMode, "config", {
+			identity: targetInfo,
+			hash: targetHash,
+			mode: targetMode
+		});
+		return;
+	}
+	await atomicCreateTextFileNoReplace(configPath, payloadText, targetMode, "config");
+}
+async function writePersistedCacheOptimizerConfig(config, configPath = CONFIG_FILE_PATH) {
+	await withModelsJsonTransactionLock(() => writePersistedCacheOptimizerConfigUnlocked(config, configPath));
+}
+async function writePersistedFooterModeUnlocked(mode, configPath) {
+	let version = 1;
+	let raw;
+	let targetExists = false;
 	try {
-		const parsed = parsePersistedCacheOptimizerConfig(JSON.parse(readFileSync(configPath, "utf8")));
-		if (!parsed) throw new Error("invalid footer config schema");
-		return parsed.footerMode;
+		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") console.warn(`${LOG_PREFIX}: failed to read footer config; using environment/default mode`, 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) : void 0;
+		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") : void 0;
+		const targetMode = targetInfo ? targetInfo.mode & 4095 : 384;
+		const footerText = JSON.stringify({
+			version: 1,
+			footerMode: mode
+		}, null, 2) + "\n";
+		if (targetInfo && targetText !== void 0) await atomicReplaceTextFilePreservingMode(configPath, footerText, targetMode, "config-footer", {
+			identity: targetInfo,
+			hash: hashText(targetText),
+			mode: targetMode
+		});
+		else await atomicCreateTextFileNoReplace(configPath, footerText, targetMode, "config-footer");
 		return;
 	}
+	await writePersistedCacheOptimizerConfigUnlocked({
+		...current,
+		version: 2,
+		footerMode: mode
+	}, configPath);
 }
 async function writePersistedFooterMode(mode, configPath = CONFIG_FILE_PATH) {
+	await withModelsJsonTransactionLock(() => writePersistedFooterModeUnlocked(mode, configPath));
+}
+function configReceiptBackupPath(receipt, receiptPath = CONFIG_RECEIPT_PATH) {
+	return join(dirname(receiptPath), receipt.backupFile);
+}
+function parsePromptCacheKeyConfigReceipt(value) {
+	const record = asRecord(value);
+	if (!record || record.version !== 1 && record.version !== 2 || record.kind !== "pi-cache-optimizer-config-receipt") return void 0;
+	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 void 0;
+	if (![
+		record.transactionId,
+		record.provider,
+		record.modelId
+	].every(isSafeReceiptText)) return void 0;
+	if (!isSha256(record.beforeHash) || !isSha256(record.afterHash) || record.beforeHash === record.afterHash) return void 0;
+	if (!isSafeReceiptText(record.backupFile) || basename(record.backupFile) !== record.backupFile || !record.backupFile.startsWith("pi-cache-optimizer-config.backup-")) return void 0;
+	if (typeof record.targetExistedBefore !== "boolean" || !isReceiptTimestamp(record.createdAt) || !isReceiptTimestamp(record.appliedAt) || record.appliedAt < record.createdAt) return void 0;
+	const addedModelKey = `${record.provider}/${record.modelId}`;
+	const targetHadModelKey = record.version === 1 ? false : record.targetHadModelKey;
+	if (typeof targetHadModelKey !== "boolean") return void 0;
+	if (record.version === 2 && (!isSafeReceiptText(record.addedModelKey) || record.addedModelKey !== addedModelKey)) return void 0;
+	if (record.status !== void 0 && record.status !== "rolled_back") return void 0;
+	if (record.status === "rolled_back" && (!isReceiptTimestamp(record.rolledBackAt) || record.rolledBackAt < record.appliedAt)) return void 0;
+	if (record.status === void 0 && record.rolledBackAt !== void 0) return void 0;
+	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) {
+	return receipt !== void 0 && receipt.status === void 0;
+}
+async function assertPromptCacheKeyConfigReceiptSnapshotUnchanged(snapshot) {
+	const info = await lstat(snapshot.receiptPath);
+	if (info.isSymbolicLink() || !info.isFile() || !sameFileIdentity(snapshot.identity, info)) throw new Error("prompt-cache-key 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("prompt-cache-key receipt changed since the rollback preview");
+}
+async function readPromptCacheKeyConfigReceiptSnapshot(receiptPath = CONFIG_RECEIPT_PATH) {
+	try {
+		const info = await lstat(receiptPath);
+		if (info.isSymbolicLink() || !info.isFile()) return void 0;
+		const text = await readFile(receiptPath, "utf8");
+		const afterRead = await lstat(receiptPath);
+		if (afterRead.isSymbolicLink() || !afterRead.isFile() || !sameFileIdentity(info, afterRead)) return void 0;
+		const receipt = parsePromptCacheKeyConfigReceipt(JSON.parse(text));
+		if (!receipt) return void 0;
+		return {
+			receipt,
+			receiptPath,
+			hash: hashText(text),
+			identity: afterRead
+		};
+	} catch {
+		return;
+	}
+}
+async function readPromptCacheKeyConfigReceipt(receiptPath = CONFIG_RECEIPT_PATH) {
+	return (await readPromptCacheKeyConfigReceiptSnapshot(receiptPath))?.receipt;
+}
+async function writePromptCacheKeyConfigReceipt(receipt, receiptPath = CONFIG_RECEIPT_PATH, expectedSnapshot, beforeRename) {
+	if (!parsePromptCacheKeyConfigReceipt(receipt)) throw new Error("invalid prompt cache key config receipt");
+	if (expectedSnapshot?.receiptPath !== void 0 && expectedSnapshot.receiptPath !== receiptPath) throw new Error("prompt-cache-key receipt path changed since the rollback preview");
+	if (expectedSnapshot) await assertPromptCacheKeyConfigReceiptSnapshotUnchanged(expectedSnapshot);
+	await mkdir(dirname(receiptPath), { recursive: true });
+	let existingReceiptInfo;
+	try {
+		const info = await lstat(receiptPath);
+		if (info.isSymbolicLink() || !info.isFile()) throw new Error("invalid prompt-cache-key receipt path");
+		existingReceiptInfo = info;
+	} catch (error) {
+		if (getErrorCode(error) !== "ENOENT") throw error;
+	}
+	const tempPath = uniqueTempPath(receiptPath, "config-receipt");
+	try {
+		await writeFile(tempPath, JSON.stringify(receipt, null, 2) + "\n", {
+			encoding: "utf8",
+			mode: 384,
+			flag: "wx"
+		});
+		const tempInfo = await lstat(tempPath);
+		if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) throw new Error("invalid temporary prompt-cache-key receipt");
+		await chmod(tempPath, 384);
+		const assertDestinationUnchanged = async () => {
+			try {
+				const currentInfo = await lstat(receiptPath);
+				if (!existingReceiptInfo || !sameFileIdentity(existingReceiptInfo, currentInfo)) throw new Error("prompt-cache-key receipt changed during atomic write");
+			} catch (error) {
+				if (getErrorCode(error) !== "ENOENT" || existingReceiptInfo) throw error;
+			}
+			if (expectedSnapshot) await assertPromptCacheKeyConfigReceiptSnapshotUnchanged(expectedSnapshot);
+		};
+		await assertDestinationUnchanged();
+		if (beforeRename) await beforeRename();
+		await assertDestinationUnchanged();
+		if (existingReceiptInfo) await rename(tempPath, receiptPath);
+		else {
+			await link(tempPath, receiptPath);
+			await unlink(tempPath).catch((cleanupError) => {
+				console.warn(`${LOG_PREFIX}: committed prompt-cache-key receipt but failed to remove its temporary hard link`, cleanupError);
+			});
+		}
+	} 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, configPath = CONFIG_FILE_PATH, receiptPath = CONFIG_RECEIPT_PATH) {
 	await mkdir(dirname(configPath), { recursive: true });
-	const payload = {
-		version: 1,
-		footerMode: mode
+	let originalText = "";
+	let targetExistedBefore = false;
+	let mode = 384;
+	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 & 4095;
+	} catch (error) {
+		if (getErrorCode(error) !== "ENOENT") throw error;
+	}
+	const parsedCurrent = targetExistedBefore ? parsePersistedCacheOptimizerConfig(JSON.parse(originalText)) : void 0;
+	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);
+	if (targetHadModelKey) throw new Error("prompt-cache-key is already configured; no changes were made");
+	const omit = [.../* @__PURE__ */ new Set([...existingOmit, key])].sort();
+	const next = {
+		...current,
+		version: 2,
+		promptCacheKey: { omit }
 	};
-	const tempPath = `${configPath}.${process.pid}.${Date.now()}.tmp`;
-	await writeFile(tempPath, JSON.stringify(payload, null, 2) + "\n", "utf8");
-	await rename(tempPath, configPath);
+	const modifiedText = JSON.stringify(next, null, 2) + "\n";
+	const beforeHash = hashText(originalText);
+	const afterHash = hashText(modifiedText);
+	const originalInfo = targetExistedBefore ? await lstat(configPath) : void 0;
+	const backupFile = `pi-cache-optimizer-config.backup-${backupTimestamp()}`;
+	const backupPath = join(dirname(configPath), backupFile);
+	if (targetExistedBefore) {
+		await copyFile(configPath, backupPath, constants.COPYFILE_EXCL);
+		await chmod(backupPath, mode);
+	}
+	const tempPath = uniqueTempPath(configPath, "config-fix");
+	let committedInfo;
+	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;
+		}
+		if (originalInfo) {
+			await rename(tempPath, configPath);
+			committedInfo = await lstat(configPath);
+		} else {
+			await link(tempPath, configPath);
+			committedInfo = await lstat(configPath);
+			await unlink(tempPath).catch((cleanupError) => {
+				console.warn(`${LOG_PREFIX}: committed optimizer config but failed to remove its temporary hard link`, cleanupError);
+			});
+		}
+		const receipt = {
+			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(() => {});
+		try {
+			if (targetExistedBefore && committedInfo) await atomicRestoreFileFromBackup(backupPath, configPath, mode, {
+				identity: committedInfo,
+				hash: afterHash,
+				mode
+			});
+			else if (!targetExistedBefore && committedInfo) {
+				await validateAtomicTarget(configPath, {
+					identity: committedInfo,
+					hash: afterHash,
+					mode
+				});
+				await unlink(configPath);
+			}
+		} catch (compensationError) {
+			const writeMessage = error instanceof Error ? error.message : String(error);
+			const compensationMessage = compensationError instanceof Error ? compensationError.message : String(compensationError);
+			throw new Error(`prompt-cache-key fix receipt update failed (${writeMessage}) and config compensation failed (${compensationMessage})`);
+		}
+		throw error;
+	}
+}
+async function applyPromptCacheKeyConfigFix(model, configPath = CONFIG_FILE_PATH, receiptPath = CONFIG_RECEIPT_PATH) {
+	return withModelsJsonTransactionLock(() => applyPromptCacheKeyConfigFixUnderLock(model, configPath, receiptPath));
+}
+async function rollbackPromptCacheKeyConfigUnderLock(snapshot, configPath = CONFIG_FILE_PATH, receiptPath = CONFIG_RECEIPT_PATH, options = {}) {
+	if (snapshot.receiptPath !== receiptPath) throw new Error("prompt-cache-key receipt path changed since the rollback preview");
+	await assertPromptCacheKeyConfigReceiptSnapshotUnchanged(snapshot);
+	const receipt = snapshot.receipt;
+	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");
+	const currentHash = hashText(currentText);
+	const currentMode = currentInfo.mode & 4095;
+	if (currentHash !== 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");
+	let rollbackResultText;
+	let rollbackResultMode;
+	let rollbackResultInfo;
+	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");
+		rollbackResultText = backupText;
+		rollbackResultMode = backupInfo.mode & 4095;
+		await atomicRestoreFileFromBackup(backupPath, configPath, rollbackResultMode, {
+			backupHash: receipt.beforeHash,
+			identity: currentInfo,
+			hash: currentHash,
+			mode: currentMode
+		});
+		rollbackResultInfo = await lstat(configPath);
+	} else if (current.footerMode || omit.length > 1) {
+		const restored = {
+			version: 2,
+			...current.footerMode ? { footerMode: current.footerMode } : {},
+			...omit.length > 1 ? { promptCacheKey: { omit: omit.filter((item) => item !== receipt.addedModelKey) } } : {}
+		};
+		rollbackResultText = JSON.stringify(restored, null, 2) + "\n";
+		rollbackResultMode = currentMode;
+		await atomicReplaceTextFilePreservingMode(configPath, rollbackResultText, rollbackResultMode, "config-rollback", {
+			identity: currentInfo,
+			hash: currentHash,
+			mode: currentMode
+		});
+		rollbackResultInfo = await lstat(configPath);
+	} else {
+		await validateAtomicTarget(configPath, {
+			identity: currentInfo,
+			hash: currentHash,
+			mode: currentMode
+		});
+		await unlink(configPath);
+	}
+	try {
+		await writePromptCacheKeyConfigReceipt({
+			...receipt,
+			status: "rolled_back",
+			rolledBackAt: Date.now()
+		}, receiptPath, snapshot, options.beforeReceiptRename);
+	} catch (receiptError) {
+		try {
+			if (rollbackResultText === void 0) await atomicCreateTextFileNoReplace(configPath, currentText, currentMode, "config-rollback-compensation");
+			else {
+				if (!rollbackResultInfo || rollbackResultMode === void 0) throw new Error("missing rollback result guard");
+				await atomicReplaceTextFilePreservingMode(configPath, currentText, currentMode, "config-rollback-compensation", {
+					identity: rollbackResultInfo,
+					hash: hashText(rollbackResultText),
+					mode: rollbackResultMode
+				});
+			}
+		} catch (compensationError) {
+			const receiptMessage = receiptError instanceof Error ? receiptError.message : String(receiptError);
+			const compensationMessage = compensationError instanceof Error ? compensationError.message : String(compensationError);
+			throw new Error(`prompt-cache-key rollback receipt update failed (${receiptMessage}) and config compensation failed (${compensationMessage})`);
+		}
+		throw receiptError;
+	}
+}
+async function rollbackPromptCacheKeyConfig(snapshot, configPath = CONFIG_FILE_PATH, receiptPath = CONFIG_RECEIPT_PATH, options = {}) {
+	return withModelsJsonTransactionLock(() => rollbackPromptCacheKeyConfigUnderLock(snapshot, configPath, receiptPath, options));
 }
 function resolveFooterStatsMode(configuredMode, env = process.env) {
 	if (configuredMode) return {
@@ -1256,7 +1697,8 @@ function resolveFooterStatsMode(configuredMode, env = process.env) {
 function footerStatsMode(env = process.env, configuredMode = persistedFooterStatsMode) {
 	return resolveFooterStatsMode(configuredMode, env).mode;
 }
-let persistedFooterStatsMode = readPersistedFooterMode();
+let persistedCacheOptimizerConfig = readPersistedCacheOptimizerConfig();
+let persistedFooterStatsMode = persistedCacheOptimizerConfig.footerMode;
 function isDisabledEnv(value) {
 	if (!value) return false;
 	const normalized = value.trim().toLowerCase();
@@ -1339,6 +1781,22 @@ function isPiBuiltInLlamaCppModel(model) {
 function shouldInjectOpenAIPromptCacheKeyForModel(model) {
 	return isOpenAICompatibleApi(model?.api);
 }
+function isPromptCacheKeyOmittedForModel(model, config = persistedCacheOptimizerConfig) {
+	if (!model || !isOpenAICompatibleApi(model.api)) return false;
+	return config.promptCacheKey?.omit?.includes(modelKey(model)) === true;
+}
+function setPersistedCacheOptimizerConfig(config) {
+	persistedCacheOptimizerConfig = normalizePersistedCacheOptimizerConfig(config);
+	persistedFooterStatsMode = persistedCacheOptimizerConfig.footerMode;
+}
+function omitOpenAIPromptCacheKeys(payload) {
+	const record = asRecord(payload);
+	if (!record || !Object.prototype.hasOwnProperty.call(record, "prompt_cache_key") && !Object.prototype.hasOwnProperty.call(record, "promptCacheKey")) return void 0;
+	const copy = { ...record };
+	delete copy.prompt_cache_key;
+	delete copy.promptCacheKey;
+	return copy;
+}
 function collectAnthropicCacheControlsInWireOrder(payload) {
 	const record = asRecord(payload);
 	if (!record) return [];
@@ -2268,6 +2726,26 @@ function hasPromptCacheRetentionUnsupportedErrorMessage(message) {
 	const record = getAssistantRecord(message);
 	return record?.stopReason === "error" && hasPromptCacheRetentionUnsupportedText(record.errorMessage);
 }
+function hasPromptCacheKeyUnsupportedText(value) {
+	const normalized = lower(value).replace(/["'`]/g, "").replace(/[\s_-]+/g, " ").replace(/\s+/g, " ").trim();
+	const key = String.raw`(?:prompt ?cache ?key|promptcachekey)`;
+	const field = String.raw`(?:parameter|field|input|argument)`;
+	const unsupported = String.raw`(?:unsupported|unknown|unrecognized|unexpected|not supported|not allowed|not permitted|must be omitted|should be omitted)`;
+	if (!new RegExp(key).test(normalized)) return false;
+	const terminal = String.raw`(?=$|[}\]>,.;])`;
+	return new RegExp(String.raw`(?:unsupported|unknown|unrecognized|unexpected)\s+${field}\s*[:=]?\s*${key}${terminal}`).test(normalized) || new RegExp(String.raw`(?:extra\s+inputs?|${field}\s+not\s+(?:allowed|permitted|supported))\s*[:=]\s*${key}${terminal}`).test(normalized) || new RegExp(String.raw`${key}(?:\s+${field})?\s*[:=]?\s*(?:is\s+)?${unsupported}${terminal}`).test(normalized);
+}
+function hasPromptCacheKeyUnsupportedSignal(headers) {
+	if (!headers) return false;
+	return Object.entries(headers).some(([key, value]) => hasPromptCacheKeyUnsupportedText(`${key}: ${value}`));
+}
+function hasPromptCacheKeyUnsupportedErrorMessage(message) {
+	const record = getAssistantRecord(message);
+	return record?.stopReason === "error" && getOptionalAssistantHttpStatus(record) === 400 && hasPromptCacheKeyUnsupportedText(record.errorMessage);
+}
+function isPromptCacheKeyUnsupportedApplicable(model) {
+	return isOpenAICompatibleApi(model.api);
+}
 function hasReasoningProtocolRejectionText(value) {
 	const normalized = lower(value).replace(/\s+/g, " ").trim();
 	if (!normalized) return false;
@@ -4532,6 +5010,12 @@ function buildDoctorDiagnosis(model, options = {}) {
 		lines.push("✅ Compat fully configured.");
 		appendOptionalOpenAIProxyCompatAdviceLines(lines, optionalOpenAIProxyCompat);
 	} else 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) {
@@ -5900,6 +6384,31 @@ async function atomicReplaceTextFilePreservingMode(targetPath, content, mode, pu
 		throw error;
 	}
 }
+async function atomicCreateTextFileNoReplace(targetPath, content, mode, purpose, beforeLink) {
+	const tempPath = uniqueTempPath(targetPath, purpose);
+	try {
+		await writeFile(tempPath, content, {
+			encoding: "utf8",
+			mode,
+			flag: "wx"
+		});
+		const tempInfo = await lstat(tempPath);
+		if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) throw new Error("temporary creation is not a regular file");
+		await chmod(tempPath, mode);
+		if (beforeLink) await beforeLink();
+		await link(tempPath, targetPath);
+		await unlink(tempPath).catch((cleanupError) => {
+			console.warn(`${LOG_PREFIX}: committed config file but failed to remove its temporary hard link`, cleanupError);
+		});
+	} catch (error) {
+		try {
+			await unlink(tempPath);
+		} catch (cleanupError) {
+			if (getErrorCode(cleanupError) !== "ENOENT") console.warn(`${LOG_PREFIX}: failed to remove temporary config file`, cleanupError);
+		}
+		throw error;
+	}
+}
 async function atomicRestoreFileFromBackup(backupPath, targetPath, mode, guard, beforeRename) {
 	const backupInfo = await lstat(backupPath);
 	if (backupInfo.isSymbolicLink() || !backupInfo.isFile()) throw new Error("backup is not a regular file; refusing atomic restore");
@@ -6233,7 +6742,13 @@ async function writeModelsJsonFixReceipt(receipt, receiptPath = FIX_RECEIPT_PATH
 		await assertReceiptDestinationUnchanged();
 		if (beforeRename) await beforeRename();
 		await assertReceiptDestinationUnchanged();
-		await rename(tempPath, receiptPath);
+		if (existingReceiptInfo) await rename(tempPath, receiptPath);
+		else {
+			await link(tempPath, receiptPath);
+			await unlink(tempPath).catch((cleanupError) => {
+				console.warn(`${LOG_PREFIX}: committed fix receipt but failed to remove its temporary hard link`, cleanupError);
+			});
+		}
 	} catch (error) {
 		try {
 			await unlink(tempPath);
@@ -6557,6 +7072,8 @@ const __internals_for_tests = {
 	addOpenAIPromptCacheKey,
 	clampPromptCacheKey,
 	hasEffectivePromptCacheKey,
+	omitOpenAIPromptCacheKeys,
+	isPromptCacheKeyOmittedForModel,
 	isNonEmptyString,
 	shouldInjectOpenAIPromptCacheKey,
 	shouldInjectOpenAIPromptCacheKeyForModel,
@@ -6593,6 +7110,9 @@ const __internals_for_tests = {
 	isOpenAISdkHeader403Applicable,
 	hasPromptCacheRetentionUnsupportedSignal,
 	hasPromptCacheRetentionUnsupportedErrorMessage,
+	hasPromptCacheKeyUnsupportedSignal,
+	hasPromptCacheKeyUnsupportedErrorMessage,
+	isPromptCacheKeyUnsupportedApplicable,
 	hasReasoningProtocolRejectionText,
 	hasReasoningProtocolRejectionSignal,
 	hasReasoningProtocolRejectionErrorMessage,
@@ -6776,11 +7296,23 @@ const __internals_for_tests = {
 	selectFooterStatsForModel,
 	parseFooterStatsMode,
 	parsePersistedCacheOptimizerConfig,
+	readPersistedCacheOptimizerConfig,
+	writePersistedCacheOptimizerConfig,
 	readPersistedFooterMode,
 	writePersistedFooterMode,
+	setPersistedCacheOptimizerConfig,
 	resolveFooterStatsMode,
 	footerStatsMode,
 	CONFIG_FILE_PATH,
+	CONFIG_RECEIPT_PATH,
+	parsePromptCacheKeyConfigReceipt,
+	isActionablePromptCacheKeyConfigReceipt,
+	readPromptCacheKeyConfigReceipt,
+	readPromptCacheKeyConfigReceiptSnapshot,
+	writePromptCacheKeyConfigReceipt,
+	applyPromptCacheKeyConfigFix,
+	rollbackPromptCacheKeyConfig,
+	configReceiptBackupPath,
 	FOOTER_MODE_ENV,
 	PI_ROUTING_REGISTRY_SYMBOL,
 	PI_CACHE_HINTS_SYMBOL,
@@ -6847,6 +7379,7 @@ const __internals_for_tests = {
 	formatCompatKeysForInsertion,
 	backupTimestamp,
 	atomicReplaceTextFilePreservingMode,
+	atomicCreateTextFileNoReplace,
 	atomicRestoreFileFromBackup,
 	applyModelsJsonFixTransaction,
 	hashText,
@@ -6887,6 +7420,8 @@ function pi_cache_optimizer_default(pi) {
 	const reasoningProtocolFallbackState = getReasoningProtocolFallbackState();
 	const reasoningProtocolRejectedModels = reasoningProtocolFallbackState.modelKeys;
 	const warnedReasoningProtocolRejectedModels = reasoningProtocolFallbackState.warnedModelKeys;
+	const promptCacheKeyRejectedModels = /* @__PURE__ */ new Set();
+	const warnedPromptCacheKeyRejectedModels = /* @__PURE__ */ new Set();
 	let cacheStatsByModel = {};
 	let cacheStatsProcessByModel = {};
 	let cacheStatsTotalsByModel = {};
@@ -6910,7 +7445,7 @@ function pi_cache_optimizer_default(pi) {
 	let currentSessionHashSet = false;
 	let lastActualRoutedModel;
 	let latestCacheHint;
-	let pendingProviderResponseModel;
+	const providerRequestStates = [];
 	let shardCreatedAt = Date.now();
 	const PERSIST_DEBOUNCE_MS = 2e3;
 	const SHARD_REFRESH_DEBOUNCE_MS = 250;
@@ -6946,6 +7481,18 @@ function pi_cache_optimizer_default(pi) {
 			forceModelLevel: regular.forceModelLevel || observed.forceModelLevel
 		};
 	}
+	function promptCacheKeyFixApplies(model) {
+		return isPromptCacheKeyUnsupportedApplicable(model) && promptCacheKeyRejectedModels.has(modelKey(model));
+	}
+	function buildPromptCacheKeyConfigPreview(model) {
+		return [
+			`Target: ${modelKey(model)}`,
+			`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 = /* @__PURE__ */ new Map();
 	function syncSessionHash(ctx) {
@@ -7305,7 +7852,7 @@ function pi_cache_optimizer_default(pi) {
 			shardWatcher?.close();
 			shardWatcher = void 0;
 			latestCacheHint = void 0;
-			pendingProviderResponseModel = void 0;
+			providerRequestStates.length = 0;
 			delete getProtocolGlobal().__piCacheOptimizerCacheKey__;
 			uninstallCacheHintsService();
 			restoreCacheRetentionEnv(STARTUP_CACHE_RETENTION_ENV);
@@ -7367,7 +7914,12 @@ function pi_cache_optimizer_default(pi) {
 	});
 	pi.on("before_provider_request", (event, ctx) => {
 		const requestModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
-		pendingProviderResponseModel = runtimeOptimizerEnabled ? snapshotProviderRequestModel(requestModel) : void 0;
+		const snapshot = snapshotProviderRequestModel(requestModel);
+		if (snapshot) providerRequestStates.push({
+			model: snapshot,
+			responseReceived: false,
+			correlationAmbiguous: false
+		});
 		let requestPayload = event.payload;
 		let toolOrderChanged = false;
 		if (isToolOrderEnabled() && isToolOrderingEligibleModel(requestModel)) {
@@ -7387,25 +7939,37 @@ function pi_cache_optimizer_default(pi) {
 				}
 			}
 		}
+		if (isPromptCacheKeyOmittedForModel(requestModel)) return omitOpenAIPromptCacheKeys(requestPayload) ?? (toolOrderChanged ? requestPayload : void 0);
 		if (!shouldInjectOpenAIPromptCacheKey() || !shouldInjectOpenAIPromptCacheKeyForModel(requestModel)) return toolOrderChanged ? requestPayload : void 0;
 		return addOpenAIPromptCacheKey(requestPayload, getSessionPromptCacheKey(ctx)) ?? (toolOrderChanged ? requestPayload : void 0);
 	});
 	pi.on("after_provider_response", async (event, ctx) => {
-		const model = pendingProviderResponseModel ?? resolveRouteModel(ctx.model, ctx) ?? ctx.model;
-		if (!runtimeOptimizerEnabled || !model) {
-			pendingProviderResponseModel = void 0;
-			return;
-		}
+		const pendingStates = providerRequestStates.filter((state) => !state.responseReceived);
+		let responseState;
+		if (pendingStates.length === 1) responseState = pendingStates[0];
+		else if (pendingStates.length > 1) {
+			if (new Set(pendingStates.map((state) => modelKey(state.model))).size === 1) responseState = pendingStates[0];
+			else for (const state of pendingStates) state.correlationAmbiguous = true;
+		}
+		if (responseState) responseState.responseReceived = true;
+		const model = responseState?.model ?? (pendingStates.length === 0 ? resolveRouteModel(ctx.model, ctx) ?? ctx.model : void 0);
+		if (!runtimeOptimizerEnabled || !model) return;
 		if (isReasoningProtocolRejectionSignalApplicable(model) && event.status === 400 && hasReasoningProtocolRejectionSignal(event.headers)) await notifyReasoningProtocolObservation(model, ctx, reasoningProtocolRejectedModels, warnedReasoningProtocolRejectedModels);
-		if (event.status === 400) {
-			if (!isPromptCacheRetention400Applicable(model)) return;
-			if (!hasPromptCacheRetentionUnsupportedSignal(event.headers)) return;
+		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");
+			}
+		}
+		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");
+			}
 		}
 		if (event.status === 403) {
 			const key403 = modelKey(model);
@@ -7428,16 +7992,49 @@ function pi_cache_optimizer_default(pi) {
 	pi.on("message_end", async (event, ctx) => {
 		syncSessionHash(ctx);
 		const msgRecord = asRecord(event.message);
-		const requestModelForMessage = msgRecord?.role === "assistant" ? pendingProviderResponseModel : void 0;
-		if (msgRecord?.role === "assistant") pendingProviderResponseModel = void 0;
+		const requestCorrelationForMessage = msgRecord?.role === "assistant" ? (() => {
+			const explicitModel = modelFromAssistantMessage(event.message, void 0);
+			const explicitIndex = explicitModel ? providerRequestStates.findIndex((state) => modelKey(state.model) === modelKey(explicitModel)) : -1;
+			const completedIndex = providerRequestStates.findIndex((state) => state.responseReceived);
+			const contextModel = resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+			const contextIndex = contextModel && !providerRequestStates.some((state) => state.correlationAmbiguous) ? providerRequestStates.findIndex((state) => modelKey(state.model) === modelKey(contextModel)) : -1;
+			const index = explicitIndex >= 0 ? explicitIndex : completedIndex >= 0 ? completedIndex : contextIndex >= 0 ? contextIndex : 0;
+			const state = providerRequestStates.splice(index, 1)[0];
+			if (!state) return {
+				model: void 0,
+				ambiguous: false
+			};
+			return {
+				model: state.correlationAmbiguous && explicitIndex < 0 ? void 0 : state.model,
+				ambiguous: state.correlationAmbiguous && explicitIndex < 0
+			};
+		})() : {
+			model: void 0,
+			ambiguous: false
+		};
+		const requestModelForMessage = requestCorrelationForMessage.model;
+		const contextualFallbackForMessage = requestCorrelationForMessage.ambiguous ? void 0 : resolveRouteModel(ctx.model, ctx) ?? ctx.model;
 		if (runtimeOptimizerEnabled && hasReasoningProtocolRejectionErrorMessage(event.message)) {
-			const fallbackModel = requestModelForMessage ?? resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+			const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
 			const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
 			const errorModel = messageModel ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel : void 0;
 			if (isReasoningProtocolRejectionForModel(event.message, errorModel)) await notifyReasoningProtocolObservation(errorModel, ctx, reasoningProtocolRejectedModels, warnedReasoningProtocolRejectedModels);
 		}
+		if (runtimeOptimizerEnabled && hasPromptCacheKeyUnsupportedErrorMessage(event.message)) {
+			const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
+			const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
+			const errorModel = messageModel ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel : void 0;
+			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 = requestModelForMessage ?? resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+			const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
 			const messageModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
 			const errorModel = messageModel ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel : void 0;
 			if (errorModel && isExplicitPromptCacheRetentionUnsupportedApplicable(errorModel)) {
@@ -7450,7 +8047,7 @@ function pi_cache_optimizer_default(pi) {
 			}
 		}
 		if (hasAnthropicCacheTtlOrderError(event.message)) {
-			const fallbackModel = requestModelForMessage ?? resolveRouteModel(ctx.model, ctx) ?? ctx.model;
+			const fallbackModel = requestModelForMessage ?? contextualFallbackForMessage;
 			const errorModel = modelFromAssistantMessage(event.message, fallbackModel) ?? fallbackModel;
 			if (errorModel && isAnthropicMessagesApi(errorModel.api)) {
 				const key = modelKey(errorModel);
@@ -7530,7 +8127,7 @@ function pi_cache_optimizer_default(pi) {
 			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);
-			pendingProviderResponseModel = void 0;
+			providerRequestStates.length = 0;
 			await resetCurrentSessionStats();
 			await flushPersistCacheStats(cmdCtx);
 			await publishStatus(cmdCtx, model);
@@ -7543,6 +8140,7 @@ function pi_cache_optimizer_default(pi) {
 			}
 			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))
@@ -7577,7 +8175,7 @@ function pi_cache_optimizer_default(pi) {
 			const nextMode = requestedMode;
 			try {
 				await writePersistedFooterMode(nextMode);
-				persistedFooterStatsMode = nextMode;
+				setPersistedCacheOptimizerConfig(readPersistedCacheOptimizerConfig());
 				lastStatusText = void 0;
 				await publishStatus(cmdCtx, model);
 				const resolved = resolveFooterStatsMode(persistedFooterStatsMode);
@@ -7598,6 +8196,28 @@ function pi_cache_optimizer_default(pi) {
 				cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
 				return;
 			}
+			const configReceiptSnapshot = await readPromptCacheKeyConfigReceiptSnapshot();
+			const configReceipt = configReceiptSnapshot?.receipt;
+			const modelsReceipt = await readModelsJsonFixReceipt();
+			if (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 (!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;
+				}
+				if (!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?`)) {
+					cmdCtx.ui.notify("No changes were made. Rollback canceled by user.", "info");
+					return;
+				}
+				try {
+					if (!configReceiptSnapshot) throw new Error("prompt-cache-key receipt changed since the rollback preview");
+					await rollbackPromptCacheKeyConfig(configReceiptSnapshot);
+					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.";
@@ -7673,7 +8293,48 @@ Run /cache-optimizer rollback in Pi's interactive UI.${backupHint} Then run /rel
 				cmdCtx.ui.notify("No active model selected. Select a model first with /model or pi --model.", "warning");
 				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 ? void 0 : 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.
+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");
+				if (!await cmdCtx.ui.confirm("Cache Optimizer — Omit prompt_cache_key", preview)) {
+					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)}.\nConfig backup saved to: ${result.backupPath}\nRun /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);
 				cmdCtx.ui.notify(`✅ Nothing to fix for "${key}". Compat already configured.`, "info");
@@ -7841,7 +8502,8 @@ Run /cache-optimizer rollback in Pi's interactive UI.${backupHint} Then run /rel
 					"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",
@@ -7854,8 +8516,9 @@ Run /cache-optimizer rollback in Pi's interactive UI.${backupHint} Then run /rel
 				else if (choice === menuOptions[3]) await handleCacheOptimizerCommand("stats", cmdCtx);
 				else if (choice === menuOptions[4]) await handleCacheOptimizerCommand("compat", cmdCtx);
 				else if (choice === menuOptions[5]) await handleCacheOptimizerCommand("fix", cmdCtx);
-				else if (choice === menuOptions[6]) await handleCacheOptimizerCommand("rollback", cmdCtx);
-				else if (choice === menuOptions[7]) {
+				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",
@@ -7865,7 +8528,7 @@ Run /cache-optimizer rollback in Pi's interactive UI.${backupHint} Then run /rel
 					const modeChoice = await cmdCtx.ui.select("Footer cache stats mode", modeOptions);
 					const nextMode = modeChoice === modeOptions[0] ? "session" : modeChoice === modeOptions[1] ? "total" : modeChoice === modeOptions[2] ? "process" : void 0;
 					if (nextMode) await handleCacheOptimizerCommand(`config footer-mode ${nextMode}`, cmdCtx);
-				} else if (choice === menuOptions[8]) await handleCacheOptimizerCommand("reset", cmdCtx);
+				} else if (choice === menuOptions[9]) await handleCacheOptimizerCommand("reset", cmdCtx);
 				return;
 			}
 			const diagnosis = [];
@@ -7878,7 +8541,8 @@ Run /cache-optimizer rollback in Pi's interactive UI.${backupHint} Then run /rel
 			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("");
@@ -7911,4 +8575,4 @@ Run /cache-optimizer rollback in Pi's interactive UI.${backupHint} Then run /rel
 //#endregion
 export { __internals_for_tests, pi_cache_optimizer_default as default };
 
-//# sourceMappingURL=pi-cache-optimizer-BfO9Qmqm.mjs.map
+//# sourceMappingURL=pi-cache-optimizer-DjqO0Quf.mjs.map