pi-cache-optimizer 2.8.23 → 2.8.24

package/README.md

@@ -80,6 +80,7 @@ This extension requires Pi 0.82+ and is validated against Pi 1.1.0. It uses the
 | `/cache-optimizer reset` | Resets local footer stats for the active provider/model; upstream provider cache is not modified. |
 | `/cache-optimizer config footer-mode total\|session\|process` | Persist the footer stats mode. Persistent command configuration overrides the environment variable. |
 | `/cache-optimizer fix` | Auto-repairs safe compat issues for the active model. Shows preview + risk warning, requires confirmation. It writes `models.json` only for native compat fixes, or the extension config for an evidenced `prompt_cache_key` issue. |
+| `/cache-optimizer fix prompt-cache` | Adds `promptCache` lifetimes for the active model so Pi's native cache warming can run. Preview, backup, receipt, and rollback. Requires confirmation. |
 | `/cache-optimizer fix prompt-cache-key` | Explicitly configures the active OpenAI-compatible provider/model to omit `prompt_cache_key` and `promptCacheKey` from the final request body. Requires confirmation. |
 | `/cache-optimizer rollback` | Reviews the latest matching confirmed fix and, after UI confirmation, restores either the extension config or `models.json` fix safely. |
 
@@ -208,7 +209,7 @@ Notes:
 
 Pi itself can keep a prompt cache alive by re-sending the last request with a one-token output cap shortly before the entry expires (the global `cacheWarming` setting: `off`, `streaming` (default), or `idle`; change it with `/settings` → Cache warming or `"cacheWarming"` in `~/.pi/agent/settings.json`). This extension does not run a keepalive timer of its own: a second warmer would pay for duplicate refreshes and cannot replay Pi's exact request.
 
-Pi only warms a model that declares a cache lifetime for the retention tier in use, has input/cache prices, and is replayable (Anthropic budget-based thinking is not). Custom proxy models in `models.json` often lack the first two, so warming never starts. `/cache-optimizer doctor` now reports the mode, the tier, and what is missing, with a snippet such as `"promptCache": {"short":300,"long":3600}` for `anthropic-messages` models. Put it on the model entry (custom models) or under the provider's `modelOverrides` (built-in models). It is advice only; the extension does not write it for you.
+Pi only warms a model that declares a cache lifetime for the retention tier in use, has input/cache prices, and is replayable (Anthropic budget-based thinking is not). Custom proxy models in `models.json` often lack the first two, so warming never starts. For models whose prices are all zero, Pi stops with "cache economics unavailable"; this extension answers Pi's `cache_warming_decision` with `warm` in that case only, since a refresh is just a cache read plus one output token. Models with real prices keep Pi's own decision, and Pi's mode, lifetime, replayability and time limits still apply. Each refresh is a real request, so a channel that does bill despite the zero prices pays for it. Pi's `/session` still shows "cache economics unavailable" between refreshes, and if another extension also handles `cache_warming_decision`, the one Pi runs last wins. Turn it off with `/cache-optimizer config zero-price-warming off` or `PI_CACHE_OPTIMIZER_NO_ZERO_PRICE_WARMING=1`. `/cache-optimizer doctor` now reports the mode, the tier, and what is missing, with a snippet such as `"promptCache": {"short":300,"long":3600}` for `anthropic-messages` models. Put it on the model entry (custom models) or under the provider's `modelOverrides` (built-in models), or run `/cache-optimizer fix prompt-cache` to have it written for you: it previews the edit, asks for confirmation, keeps a timestamped backup and comments, and records a receipt so `/cache-optimizer rollback` removes exactly that `promptCache` object (or restores the whole file if nothing else changed). It writes `{"short":300,"long":3600}` for `anthropic-messages` models (Anthropic's documented 5m/1h, the values Pi ships for its own Claude models) and `{"short":300}` elsewhere; when the long tier is in use and no long lifetime is documented for the API, it refuses rather than guessing. It never merges into or overwrites an existing `promptCache`, and it does not create a provider entry that models.json lacks.
 
 Streaming warming stops 60 minutes after the real request and idle warming after 30 minutes. With this extension's 1-hour retention, the refresh would fire at 54 minutes, so `idle` adds nothing; the 1-hour lifetime already covers breaks under an hour. Keep the default `streaming` unless you use 5-minute caches and often return within half an hour.
 

package/README.zh-CN.md

@@ -80,6 +80,7 @@ Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安
 | `/cache-optimizer reset` | 重置当前 provider/model 的本地 footer 统计；不会修改上游 provider 缓存。 |
 | `/cache-optimizer config footer-mode total\|session\|process` | 持久设置 footer 统计模式；持久命令配置优先于环境变量。 |
 | `/cache-optimizer fix` | 为当前模型自动修复安全的 compat 问题。展示预览 + 风险提示，需要用户确认；原生 compat 修复写 `models.json`，已观测到的 `prompt_cache_key` 问题写扩展配置。 |
+| `/cache-optimizer fix prompt-cache` | 为当前模型写入 `promptCache` 缓存时长，让 Pi 原生保温生效。带预览、备份、receipt 和回滚。需要确认。 |
 | `/cache-optimizer fix prompt-cache-key` | 明确把当前 OpenAI-compatible provider/model 配置为从最终请求体移除 `prompt_cache_key` 与 `promptCacheKey`。需要确认。 |
 | `/cache-optimizer rollback` | 查看最近一次匹配的已确认修复；经 UI 确认后安全恢复扩展配置或 `models.json` 修复。 |
 
@@ -208,7 +209,7 @@ Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention`
 
 Pi 自带缓存保温：在缓存条目过期前，用一个 token 的输出上限原样重放上一次请求（全局设置 `cacheWarming`：`off`、`streaming`（默认）或 `idle`；在 `/settings` → Cache warming 中修改，或在 `~/.pi/agent/settings.json` 中设置 `"cacheWarming"`）。本扩展不自行运行保活定时器：第二个保温器会重复计费，而且无法精确重放 Pi 的请求。
 
-Pi 只会为满足以下条件的模型保温：为当前保留档位声明了缓存时长、有输入/缓存价格、请求可重放（Anthropic 基于 budget 的 thinking 不可重放）。`models.json` 里的自定义代理模型常常缺前两项，保温根本不会启动。`/cache-optimizer doctor` 现在会显示保温模式、档位和缺失项，并给出片段，例如 `anthropic-messages` 模型的 `"promptCache": {"short":300,"long":3600}`。自定义模型写在该模型条目中，内置模型写在 provider 的 `modelOverrides` 下。这只是建议，扩展不会替你写入。
+Pi 只会为满足以下条件的模型保温：为当前保留档位声明了缓存时长、有输入/缓存价格、请求可重放（Anthropic 基于 budget 的 thinking 不可重放）。`models.json` 里的自定义代理模型常常缺前两项，保温根本不会启动。对价格全为 0 的模型，Pi 会以 “cache economics unavailable” 停止保温；本扩展仅在这种情况下通过 `cache_warming_decision` 返回 `warm`，因为一次刷新只是一次缓存读取加一个输出 token。有真实价格的模型仍按 Pi 自己的判断，Pi 的模式、缓存时长、可重放性和时间上限也照常生效。每次刷新都是一次真实请求，若渠道价格写 0 但实际计费，会产生费用。刷新间隔里 Pi 的 `/session` 仍会显示 “cache economics unavailable”；若其他扩展也处理 `cache_warming_decision`，以 Pi 最后执行的那个为准。可用 `/cache-optimizer config zero-price-warming off` 或 `PI_CACHE_OPTIMIZER_NO_ZERO_PRICE_WARMING=1` 关闭。`/cache-optimizer doctor` 现在会显示保温模式、档位和缺失项，并给出片段，例如 `anthropic-messages` 模型的 `"promptCache": {"short":300,"long":3600}`。自定义模型写在该模型条目中，内置模型写在 provider 的 `modelOverrides` 下；也可以运行 `/cache-optimizer fix prompt-cache` 一键写入：先预览、需确认、保留带时间戳的备份和注释，并记录 receipt，`/cache-optimizer rollback` 只会删除这次加入的 `promptCache` 对象（若文件之后没有改动则整文件恢复）。`anthropic-messages` 模型写入 `{"short":300,"long":3600}`（Anthropic 文档的 5 分钟/1 小时，与 Pi 内置 Claude 模型一致），其他 API 写入 `{"short":300}`；若当前使用长档位而该 API 没有文档化的长时长，则拒绝写入而不是猜测。已有 `promptCache` 时不会合并或覆盖，models.json 中不存在的 provider 条目也不会被创建。
 
 streaming 保温在真实请求后 60 分钟停止，idle 保温在 30 分钟后停止。本扩展使用 1 小时保留时，刷新会在第 54 分钟才触发，所以 `idle` 没有额外作用；1 小时的缓存本身已覆盖一小时内的中断。除非你使用 5 分钟缓存且经常在半小时内回来，否则保持默认的 `streaming` 即可。
 

package/index.ts

@@ -16,9 +16,9 @@ import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, choose
 import { type CacheProviderId, type CacheStats, LEGACY_STATE_FILE_PATH, type PersistedRoutedModelRef, type PersistedStatsShardV7, SHARD_FILES_DIR, SHARD_GLOBAL_EPOCH_PATH, SHARD_STATE_DIR, STATE_FILE_PATH, type ShardAggregate, type UsageSnapshot, addUsageToCacheStats, advanceGlobalStatsEpoch, advanceModelStatsEpoch, aggregateStatsShardsV7, cleanupStatsShardsV7, cloneCacheStats, currentLocalDay, emptyAllCacheStats, emptyCacheStats, initialEpoch, loadStatsShardAggregateV7, maybeCleanupStatsShardsV7, modelEpochPath, parseCacheStats, parsePersistedRoutedModelRef, parsePersistedStatsShardV7, readGlobalStatsEpoch, readModelStatsEpoch, readValidStatsShardsV7, removeLegacyStatsFiles, writeStatsShardV7 } from "./src/stats-store.ts";
 import { PI_VIRTUAL_MODEL_API, getCompat, isAnthropicMessagesApi, isKimiCodingEmptySignatureModel, isKnownThirdPartyOpenAIEndpoint, isMistralConversationsApi, isNativeVirtualModel, isOfficialOpenAIBaseUrl, isOpenAICompatibleApi, isOpenAICompatibleProxyApi, isOpenAIFamilyAssistantMessage, isOpenAIFamilyModel, isOpenAIFamilyToken, isPiBuiltInLlamaCppModel, isResponsesPromptRewriteBypassApi, isRoutedFallbackModel, isValidModelsConfigForEffectiveCompat, modelKey, readEffectiveCompatConfig } from "./src/model-identity.ts";
 import { CONFIG_FILE_PATH, VIRTUAL_REWRITE_ENV, FOOTER_MODE_ENV, TOOL_ORDER_ENV, featureEnabled, footerStatsMode, isEnabledEnv, isToolOrderEnabled, parseFooterStatsMode, parsePersistedCacheOptimizerConfig, readPersistedCacheOptimizerConfig, resolveFooterStatsMode, runtimeOptimizerEnabled, setPersistedCacheOptimizerConfig, shouldInjectOpenAIPromptCacheKey, writePersistedCacheOptimizerConfig, writePersistedFeature, writePersistedFooterMode } from "./src/config.ts";
-import { readCacheWarmingMode } from "./src/cache-warming.ts";
+import { decideZeroPriceWarming, readCacheWarmingMode } from "./src/cache-warming.ts";
 import { LONG_CACHE_RETENTION_VALUE, PI_CACHE_RETENTION_BASELINE_SYMBOL, PI_CACHE_RETENTION_ENV, STARTUP_CACHE_RETENTION_ENV, captureCacheRetentionEnv, getOrCaptureCacheRetentionBaseline, decidePromptCacheRetention, recordPromptCacheRetentionDecision, requestLongCacheRetention, restoreCacheRetentionEnv, userRequestedLongCacheRetention } from "./src/retention.ts";
-import { isRuntimeOptimizerEnabled, setRuntimeOptimizerEnabled } from "./src/config.ts";
+import { isRuntimeOptimizerEnabled, isZeroPriceWarmingEnabled, setRuntimeOptimizerEnabled } from "./src/config.ts";
 import { compareToolOrderEntries, getToolNameForPayload, isKnownToolOrderApi, isToolOrderingEligibleModel, isVerifiedToolForApi, normalizeToolsInPayload, sortToolsInPayload } from "./src/tool-ordering.ts";
 import { SKILL_COMPRESSION_MIN_COUNT, compressSkillsInSystemPrompt, compressSkillsViaSection, formatSkillsForPrompt, formatSkillsForPromptCompressed, stripSessionOverviewChurn, explainSkillCompressionSkip, recordSkillCompressionOutcome, getLastSkillCompressionOutcome, describeSkillCompressionOutcome } from "./src/prompt-rewrite.ts";
 import { addEffectiveSessionAffinityHeaders, addOpenAIPromptCacheKey, clampPromptCacheKey, collectAnthropicCacheControlsInWireOrder, downgradeAnthropicLongCacheControls, getEffectiveCompatValueSource, hasAnthropicCacheTtlOrderError, hasEffectivePromptCacheKey, isPromptCacheKeyOmittedForModel, normalizeAnthropicCacheControlTtlOrder, omitOpenAIPromptCacheKeys, shouldInjectOpenAIPromptCacheKeyForModel, withAnthropicCacheTtlRepair, withoutPromptCacheRetention, derivePromptCacheKey } from "./src/request-payload.ts";
@@ -988,6 +988,15 @@ export default function (pi: ExtensionAPI) {
     await publishStatus(ctx);
   });
 
+  // Pi 0.86+ native prompt-cache warming: keep it running for models whose
+  // prices are unknown (all-zero cost), where Pi would otherwise stop with
+  // "cache economics unavailable". Older hosts never emit this event.
+  pi.on("cache_warming_decision", (event, ctx) => {
+    if (!isZeroPriceWarmingEnabled()) return undefined;
+    const action = decideZeroPriceWarming(event, ctx.model);
+    return action ? { action } : undefined;
+  });
+
   pi.on("agent_settled", async (_event, ctx) => {
     // No provider request can still be in flight once the agent has settled.
     // Drop leftover lifecycle records (a request whose message never ended, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.8.23",
+  "version": "2.8.24",
   "description": "Improve Pi prompt/KV cache hit rates with stable prompts, OpenAI-compatible cache keys, proxy compat warnings, and footer cache stats.",
   "keywords": [
     "pi-package",

package/src/cache-warming.ts

@@ -54,6 +54,7 @@ export function suggestedPromptCacheLifetimes(model: PiModel): { short: number;
   // other APIs only the conservative short lifetime is suggested; extended
   // retention differs per provider and deployment.
   if (model.api === "anthropic-messages") return { short: 300, long: 3600 };
+  // Elsewhere only the short tier has a value the extension can stand behind.
   return { short: 300 };
 }
 
@@ -69,6 +70,13 @@ function hasPricing(model: PiModel): boolean {
   return ["input", "cacheRead", "cacheWrite"].some((key) => typeof cost[key] === "number" && (cost[key] as number) > 0);
 }
 
+/** Every price Pi uses for warming economics is zero or missing. */
+function isZeroPriced(model: PiModel): boolean {
+  const cost = asRecord((model as unknown as Record<string, unknown>).cost);
+  if (!cost) return true;
+  return ["input", "output", "cacheRead", "cacheWrite"].every((key) => !(typeof cost[key] === "number" && (cost[key] as number) > 0));
+}
+
 function isReplayableForWarming(model: PiModel): boolean {
   if (!model.reasoning || model.api !== "anthropic-messages") return true;
   return asRecord(asRecord(model as unknown)?.compat)?.forceAdaptiveThinking === true;
@@ -78,6 +86,8 @@ export type CacheWarmingDiagnosisInput = {
   mode: CacheWarmingMode | "unsupported";
   /** Retention tier Pi uses for this request ("long" when PI_CACHE_RETENTION=long). */
   tier: "short" | "long";
+  /** Whether the extension keeps warming running for zero-price models. */
+  zeroPriceWarming?: boolean;
 };
 
 export type CacheWarmingDiagnosis = {
@@ -118,6 +128,9 @@ export function buildCacheWarmingDiagnosis(model: PiModel, input: CacheWarmingDi
     lines.push(`- ⚠️ The model declares no promptCache.${input.tier} lifetime, so Pi never warms its cache.`);
     lines.push(`  Add to this model's entry in models.json (custom models) or under the provider's modelOverrides.${JSON.stringify(model.id)} (built-in models):`);
     lines.push(`  "promptCache": ${JSON.stringify(snippet)}`);
+    if (input.tier === "short" || suggested.long !== undefined) {
+      lines.push("  Or run /cache-optimizer fix prompt-cache to add it with a preview, backup and rollback.");
+    }
     if (input.tier === "long" && suggested.long === undefined) {
       lines.push("  Only add a long lifetime your provider documents; use the conservative end of any range.");
     }
@@ -126,8 +139,12 @@ export function buildCacheWarmingDiagnosis(model: PiModel, input: CacheWarmingDi
   }
 
   if (!hasPricing(model)) {
-    issues.push("pricing_missing");
-    lines.push("- ⚠️ The model has no input/cache prices, so Pi cannot estimate savings and skips warming. Add a cost block to the model entry.");
+    if (input.zeroPriceWarming && isZeroPriced(model)) {
+      lines.push("- The model has no input/cache prices. Pi would skip warming; this extension overrides that (config zero-price-warming on).");
+    } else {
+      issues.push("pricing_missing");
+      lines.push("- ⚠️ The model has no input/cache prices, so Pi cannot estimate savings and skips warming. Add a cost block, or turn on /cache-optimizer config zero-price-warming.");
+    }
   }
 
   if (!isReplayableForWarming(model)) {
@@ -148,3 +165,25 @@ export function buildCacheWarmingDiagnosis(model: PiModel, input: CacheWarmingDi
   }
   return { eligible, issues, lines };
 }
+
+export type CacheWarmingDecisionLike = {
+  action?: unknown;
+  warmCost?: unknown;
+  missCost?: unknown;
+};
+
+/**
+ * `cache_warming_decision` policy: Pi stops warming when it cannot price the
+ * refresh ("cache economics unavailable"), which is every model whose cost
+ * block is all zero, the common case for custom proxy channels. A refresh is a
+ * cache read of the prompt plus one output token, far cheaper than rewriting
+ * the cache, so keep warming for those models. Pi's own decision stands
+ * whenever the model has real prices, and Pi's mode, lifetime, replayability
+ * and 60m/30m safety limits still apply.
+ */
+export function decideZeroPriceWarming(event: CacheWarmingDecisionLike, model: PiModel | undefined): "warm" | undefined {
+  if (!model || event.action !== "stop") return undefined;
+  if (event.warmCost !== 0 || event.missCost !== 0) return undefined;
+  if (!isZeroPriced(model)) return undefined;
+  return "warm";
+}

package/src/command-completion.ts

@@ -18,9 +18,9 @@ export const CACHE_OPTIMIZER_COMMANDS = [
   "rollback",
 ] as const;
 
-export const CACHE_OPTIMIZER_CONFIG_ARGUMENTS = ["footer-mode", "prompt-rewrite", "virtual-rewrite", "skill-compression", "openai-cache-key", "tool-order", "reset"] as const;
+export const CACHE_OPTIMIZER_CONFIG_ARGUMENTS = ["footer-mode", "prompt-rewrite", "virtual-rewrite", "skill-compression", "openai-cache-key", "tool-order", "zero-price-warming", "reset"] as const;
 
-export const CACHE_OPTIMIZER_FEATURE_COMMANDS = ["prompt-rewrite", "virtual-rewrite", "skill-compression", "openai-cache-key", "tool-order"] as const;
+export const CACHE_OPTIMIZER_FEATURE_COMMANDS = ["prompt-rewrite", "virtual-rewrite", "skill-compression", "openai-cache-key", "tool-order", "zero-price-warming"] as const;
 
 export const CACHE_OPTIMIZER_FEATURE_VALUES = ["on", "off"] as const;
 
@@ -32,11 +32,12 @@ export const FEATURE_COMMAND_MAP: Record<string, PersistedCacheOptimizerFeature>
   "skill-compression": "skillCompression",
   "openai-cache-key": "openAICacheKey",
   "tool-order": "toolOrder",
+  "zero-price-warming": "zeroPriceWarming",
 };
 
 export const CACHE_OPTIMIZER_STATS_ARGUMENTS = ["all", "contributors"] as const;
 
-export const CACHE_OPTIMIZER_FIX_ARGUMENTS = ["prompt-cache-key"] as const;
+export const CACHE_OPTIMIZER_FIX_ARGUMENTS = ["prompt-cache", "prompt-cache-key"] as const;
 
 export function filterCommandCompletionItems(
   values: readonly string[],

package/src/command.ts

@@ -1,16 +1,17 @@
 import { type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { readFile } from "node:fs/promises";
 import { selectAdapterForModel } from "./adapters.ts";
-import { backupTimestamp, hashText } from "./atomic-fs.ts";
+import { backupTimestamp, hashText, readRegularTextFile } from "./atomic-fs.ts";
+import { choosePromptCacheLifetimes, planPromptCacheFix, validateWrittenPromptCacheFix } from "./prompt-cache-fix.ts";
 import { FEATURE_COMMAND_MAP } from "./command-completion.ts";
 import { type PiModel, asRecord } from "./common.ts";
 import { describeMissingCacheCompatForModel, getModelsJsonDisplayPath, isAdaptiveThinkingCompatApplicable } from "./compat-advice.ts";
 import { resolveEffectiveCompatFromConfig } from "./compat-config.ts";
-import { FOOTER_MODE_ENV, type FooterStatsMode, formatOptimizerRuntimeMode, formatPersistentFeatureConfig, persistedFooterStatsMode, readPersistedCacheOptimizerConfig, resetPersistedFeatures, resolveFooterStatsMode, setPersistedCacheOptimizerConfig, setRuntimeOptimizerEnabled, writePersistedFeature, writePersistedFooterMode } from "./config.ts";
+import { isZeroPriceWarmingEnabled, FOOTER_MODE_ENV, type FooterStatsMode, formatOptimizerRuntimeMode, formatPersistentFeatureConfig, persistedFooterStatsMode, readPersistedCacheOptimizerConfig, resetPersistedFeatures, resolveFooterStatsMode, setPersistedCacheOptimizerConfig, setRuntimeOptimizerEnabled, writePersistedFeature, writePersistedFooterMode } from "./config.ts";
 import { buildCompatDiagnosis, buildDoctorDiagnosis, buildLowHitDiagnosis, getCompatCheckNotApplicableLines, isCompatCheckApplicable, isDeepSeekCompatCheckApplicable, isPromptCacheKeyUnsupportedApplicable } from "./diagnostics.ts";
 import { locateModelOverrideInJsonc, parseJsonc } from "./jsonc.ts";
 import { invalidateModelsConfigCache, isValidModelsConfigForEffectiveCompat, modelKey } from "./model-identity.ts";
-import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, chooseFixPlacement, composeFixInsertion, composeModelOverrideInsertion, composeProviderAffinityInsertion, createModelsJsonFixReceipt, formatCompatKeysForInsertion, formatMissingEntryManualSnippet, isActionableModelsJsonFixReceipt, locateModelInJsonc, markModelsJsonFixReceiptRolledBack, prepareModelsJsonRollback, readModelsJsonFixReceipt, readModelsJsonFixReceiptSnapshot, resolveExplicitCompatValue, selfCheckFix, selfCheckMissingEntryInsertion, validateModelsJsonRollback, writeModelsJsonFixReceipt } from "./models-json-fix.ts";
+import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, chooseFixPlacement, composeFixInsertion, composeModelOverrideInsertion, composeProviderAffinityInsertion, createModelsJsonFixReceipt, createPromptCacheFixReceipt, formatCompatKeysForInsertion, formatMissingEntryManualSnippet, isActionableModelsJsonFixReceipt, locateModelInJsonc, markModelsJsonFixReceiptRolledBack, prepareModelsJsonRollback, readModelsJsonFixReceipt, readModelsJsonFixReceiptSnapshot, resolveExplicitCompatValue, selfCheckFix, selfCheckMissingEntryInsertion, validateModelsJsonRollback, writeModelsJsonFixReceipt } from "./models-json-fix.ts";
 import { MODELS_JSON_PATH } from "./paths.ts";
 import { applyPromptCacheKeyConfigFix, isActionablePromptCacheKeyConfigReceipt, readPromptCacheKeyConfigReceiptSnapshot, rollbackPromptCacheKeyConfig } from "./prompt-cache-key-config.ts";
 import { getEffectiveCompatValueSource, isPromptCacheKeyOmittedForModel } from "./request-payload.ts";
@@ -117,6 +118,7 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
           ? buildCacheWarmingDiagnosis(model, {
             mode: runtime.getCacheWarmingMode(),
             tier: process.env[PI_CACHE_RETENTION_ENV] === LONG_CACHE_RETENTION_VALUE ? "long" : "short",
+            zeroPriceWarming: isZeroPriceWarmingEnabled(),
           }).lines
           : [];
         const fullDiagnosis = [routeNote, diagnosis, describeSkillCompressionOutcome(), describePromptCacheRetentionDecision(getLastPromptCacheRetentionDecision()), ...warmingLines, ...lowHitLines].filter((line) => line !== undefined).join("\n");
@@ -169,7 +171,7 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
           const resolved = resolveFooterStatsMode(persistedFooterStatsMode);
           cmdCtx.ui.notify(
             `Usage: /cache-optimizer config footer-mode total|session|process\n` +
-            `       /cache-optimizer config prompt-rewrite|virtual-rewrite|skill-compression|openai-cache-key|tool-order on|off\n` +
+            `       /cache-optimizer config prompt-rewrite|virtual-rewrite|skill-compression|openai-cache-key|tool-order|zero-price-warming on|off\n` +
             `       /cache-optimizer config reset\n` +
             `Current footer mode: ${resolved.mode} (${resolved.source})`,
             "info",
@@ -284,7 +286,9 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
 
         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";
+          : rollback.receipt.promptCacheAdded
+            ? "remove only the promptCache object the fix added (and restore any receipt-owned compat keys), preserving subsequent user changes"
+            : "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}`,
@@ -378,6 +382,11 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
           return;
         }
 
+        if (commandParts[1] === "prompt-cache") {
+          await runPromptCacheFix(cmdCtx, model);
+          return;
+        }
+
         const promptCacheKeyRequested = commandParts[1] === "prompt-cache-key";
         const promptCacheKeyFixRequested = promptCacheKeyRequested || promptCacheKeyFixApplies(model);
         if (promptCacheKeyRequested && !isPromptCacheKeyUnsupportedApplicable(model)) {
@@ -987,10 +996,11 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
         diagnosis.push("  stats all — Show detailed totals for every model across all local sessions");
         diagnosis.push("  stats contributors — Show per-session contributors for the active model");
         diagnosis.push("  compat  — Show compat suggestion with edit location");
-        diagnosis.push("  config prompt-rewrite|virtual-rewrite|skill-compression|openai-cache-key|tool-order on|off — Persist feature settings");
+        diagnosis.push("  config prompt-rewrite|virtual-rewrite|skill-compression|openai-cache-key|tool-order|zero-price-warming on|off — Persist feature settings");
         diagnosis.push("  config footer-mode total|session|process — Persist the footer stats mode");
         diagnosis.push("  config reset — Remove persistent feature overrides");
         diagnosis.push("  fix     — Auto-fix compat issues (writes models.json or extension config, requires UI)");
+        diagnosis.push("  fix prompt-cache — Add promptCache lifetimes so Pi's cache warming can run");
         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)");
@@ -1019,3 +1029,114 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
       }
   }
 }
+
+function declaredPromptCacheTier(model: PiModel, tier: "short" | "long"): number | undefined {
+  const value = asRecord(asRecord(model as unknown)?.promptCache)?.[tier];
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+/**
+ * `/cache-optimizer fix prompt-cache`: add Pi's model-level promptCache
+ * lifetimes so native cache warming can run. Same safety model as the compat
+ * fix: preview + confirmation, timestamped backup, guarded atomic write,
+ * post-write check, and a receipt that /cache-optimizer rollback understands.
+ */
+async function runPromptCacheFix(cmdCtx: ExtensionCommandContext, model: PiModel): Promise<void> {
+  const tier: "short" | "long" = process.env[PI_CACHE_RETENTION_ENV] === LONG_CACHE_RETENTION_VALUE ? "long" : "short";
+  const declared = declaredPromptCacheTier(model, tier);
+  if (declared !== undefined) {
+    cmdCtx.ui.notify(`✅ ${modelKey(model)} already declares promptCache.${tier} (${declared}s). Nothing to fix.`, "info");
+    return;
+  }
+  const choice = choosePromptCacheLifetimes(model, tier);
+  if ("error" in choice) {
+    cmdCtx.ui.notify(`ℹ️ ${choice.error} No changes were made.`, "warning");
+    return;
+  }
+  const snippet = `"promptCache": ${JSON.stringify(choice.promptCache)}`;
+  const manual = (reason: string): string => [
+    `❌ ${reason}. No changes were made.`,
+    "",
+    `Add this to the model entry in ${getModelsJsonDisplayPath()} (custom models) or under`,
+    `providers["${model.provider}"].modelOverrides["${model.id}"] (built-in models), then run /reload:`,
+    `  ${snippet}`,
+  ].join("\n");
+
+  if (!cmdCtx.hasUI) {
+    cmdCtx.ui.notify(manual("Non-interactive terminal detected. The fix requires UI confirmation"), "warning");
+    return;
+  }
+
+  let current: { text: string; mode: number };
+  try {
+    current = await readRegularTextFile(MODELS_JSON_PATH);
+  } catch {
+    cmdCtx.ui.notify(manual(`Could not read ${getModelsJsonDisplayPath()} as a regular file`), "error");
+    return;
+  }
+  const plan = planPromptCacheFix(current.text, model.provider, model.id, choice.promptCache);
+  if ("error" in plan) {
+    cmdCtx.ui.notify(manual(`Cannot edit models.json safely: ${plan.error}`), "error");
+    return;
+  }
+
+  const backupPath = `${MODELS_JSON_PATH}.backup-cache-optimizer-${backupTimestamp()}`;
+  const pendingReceipt = await readModelsJsonFixReceipt();
+  const confirmed = await cmdCtx.ui.confirm("Cache Optimizer — Add promptCache lifetimes", [
+    `📝 Preview of changes to ${getModelsJsonDisplayPath()}:`,
+    `Location: ${plan.locationLabel}`,
+    `JSON to write: ${snippet}`,
+    plan.targetExistedBefore ? "" : "A new modelOverrides entry will be created for this model.",
+    "",
+    "Why: Pi only warms a prompt cache when the model declares its lifetime for the retention tier in use",
+    `(${tier} here). ${model.api === "anthropic-messages" ? "300s/3600s are Anthropic's documented 5m and 1h lifetimes, the values Pi ships for its own Claude models." : "300s is the conservative short lifetime."}`,
+    "",
+    `A timestamped backup will be written to: ${backupPath}`,
+    "Comments and unrelated fields are preserved. Undo with /cache-optimizer rollback.",
+    isActionableModelsJsonFixReceipt(pendingReceipt)
+      ? `⚠️ This replaces the rollback receipt of the earlier fix for ${pendingReceipt.provider}/${pendingReceipt.modelId}; its backup ${pendingReceipt.backupFile} stays on disk.`
+      : "",
+    "Run /reload or restart Pi for the change to take effect.",
+    "",
+    "Apply this change?",
+  ].filter((line, index, lines) => line !== "" || lines[index - 1] !== "").join("\n"));
+  if (!confirmed) {
+    cmdCtx.ui.notify("No changes were made. Canceled by user.", "info");
+    return;
+  }
+
+  const receipt = createPromptCacheFixReceipt(
+    current.text, plan.modifiedText, model.provider, model.id,
+    plan.placement, plan.promptCache, plan.targetExistedBefore, backupPath,
+  );
+  if (!receipt) {
+    cmdCtx.ui.notify("❌ Could not create a fix receipt for rollback. No changes were made.", "error");
+    return;
+  }
+  try {
+    const result = await applyModelsJsonFixTransaction(
+      plan.modifiedText,
+      backupPath,
+      (writtenText) => validateWrittenPromptCacheFix(writtenText, plan),
+      {
+        expectedCurrentHash: hashText(current.text),
+        expectedCurrentMode: current.mode,
+        purpose: "fix",
+        onCommitted: async () => writeModelsJsonFixReceipt(receipt),
+      },
+    );
+    if ("postCheckError" in result) {
+      cmdCtx.ui.notify(`❌ Post-write self-check failed: ${result.postCheckError}. Backup restored.`, "error");
+      return;
+    }
+    invalidateModelsConfigCache();
+    cmdCtx.ui.notify(
+      `✅ promptCache ${JSON.stringify(plan.promptCache)} added for ${modelKey(model)}.\n` +
+      `Backup saved to: ${backupPath}\n` +
+      "Run /reload or restart Pi, then /cache-optimizer doctor to confirm warming is eligible.",
+      "info",
+    );
+  } catch (error) {
+    cmdCtx.ui.notify(`❌ Write failed: ${error instanceof Error ? error.message : String(error)}. No changes were kept.`, "error");
+  }
+}

package/src/config.ts

@@ -15,6 +15,8 @@ export const NO_OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_NO_OPENAI_CACHE_KEY";
 
 export const TOOL_ORDER_ENV = "PI_CACHE_OPTIMIZER_TOOL_ORDER";
 
+export const NO_ZERO_PRICE_WARMING_ENV = "PI_CACHE_OPTIMIZER_NO_ZERO_PRICE_WARMING";
+
 export const FOOTER_MODE_ENV = "PI_CACHE_OPTIMIZER_FOOTER_MODE";
 
 export type FooterStatsMode = "session" | "total" | "process";
@@ -26,7 +28,7 @@ export type PersistedCacheOptimizerConfigV1 = {
   footerMode?: FooterStatsMode;
 };
 
-export type PersistedCacheOptimizerFeature = "promptRewrite" | "virtualRewrite" | "skillCompression" | "openAICacheKey" | "toolOrder";
+export type PersistedCacheOptimizerFeature = "promptRewrite" | "virtualRewrite" | "skillCompression" | "openAICacheKey" | "toolOrder" | "zeroPriceWarming";
 
 export type PersistedCacheOptimizerConfigV2 = {
   version: 2;
@@ -66,12 +68,17 @@ export function featureEnabled(
   if (feature === "openAICacheKey") {
     return !isEnabledEnv(env[envName]) && !isDisabledEnv(env[OPENAI_CACHE_KEY_ENV]);
   }
-  if (feature === "promptRewrite" || feature === "skillCompression") {
+  if (feature === "promptRewrite" || feature === "skillCompression" || feature === "zeroPriceWarming") {
     return !isEnabledEnv(env[envName]);
   }
   return isEnabledEnv(env[envName]) || defaultValue;
 }
 
+/** Keep Pi's cache warming running for models whose prices are unknown (all zero). */
+export function isZeroPriceWarmingEnabled(): boolean {
+  return runtimeOptimizerEnabled && featureEnabled("zeroPriceWarming", NO_ZERO_PRICE_WARMING_ENV, true);
+}
+
 export function isToolOrderEnabled(env: MutableEnv = process.env): boolean {
   return runtimeOptimizerEnabled && featureEnabled("toolOrder", TOOL_ORDER_ENV, false);
 }
@@ -94,7 +101,7 @@ export function parsePersistedCacheOptimizerConfig(value: unknown): PersistedCac
   const rawFeatures = record.version === 3 ? record.features : undefined;
   if (rawFeatures !== undefined && !asRecord(rawFeatures)) return undefined;
   const featuresRecord = asRecord(rawFeatures);
-  const featureNames = new Set<PersistedCacheOptimizerFeature>(["promptRewrite", "virtualRewrite", "skillCompression", "openAICacheKey", "toolOrder"]);
+  const featureNames = new Set<PersistedCacheOptimizerFeature>(["promptRewrite", "virtualRewrite", "skillCompression", "openAICacheKey", "toolOrder", "zeroPriceWarming"]);
   if (featuresRecord && Object.keys(featuresRecord).some((key) => !featureNames.has(key as PersistedCacheOptimizerFeature) || typeof featuresRecord[key] !== "boolean")) return undefined;
 
   const rawPromptCacheKey = record.promptCacheKey;
@@ -354,6 +361,7 @@ export function formatPersistentFeatureConfig(): string {
     ["Skill compression", "skillCompression", NO_SKILL_COMPRESSION_ENV, true],
     ["OpenAI cache key", "openAICacheKey", NO_OPENAI_CACHE_KEY_ENV, true],
     ["Tool ordering", "toolOrder", TOOL_ORDER_ENV, false],
+    ["Zero-price cache warming", "zeroPriceWarming", NO_ZERO_PRICE_WARMING_ENV, true],
   ];
   for (const [label, feature, envName, defaultValue] of entries) {
     const hasEnv = process.env[envName] !== undefined || (feature === "openAICacheKey" && process.env[OPENAI_CACHE_KEY_ENV] !== undefined);

package/src/fix-types.ts

@@ -13,8 +13,33 @@ export type FixReceiptCompatChange = {
   after: ReceiptScalarState;
 };
 
+/** Pi model-level prompt-cache lifetimes in seconds (`promptCache`). */
+export type PromptCacheLifetimes = { short?: number; long?: number };
+
+export function isValidPromptCacheLifetimes(value: unknown): value is PromptCacheLifetimes {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record);
+  if (keys.length === 0 || keys.some((key) => key !== "short" && key !== "long")) return false;
+  return keys.every((key) => {
+    const seconds = record[key];
+    return typeof seconds === "number" && Number.isSafeInteger(seconds) && seconds > 0;
+  });
+}
+
+export function samePromptCacheLifetimes(left: unknown, right: unknown): boolean {
+  if (!isValidPromptCacheLifetimes(left) || !isValidPromptCacheLifetimes(right)) return false;
+  return left.short === right.short && left.long === right.long;
+}
+
+/**
+ * Version 1 receipts record scalar compat changes only. Version 2 receipts
+ * also record a `promptCache` object the fix added (it never overwrites one),
+ * so rollback can remove exactly that property. Older extension versions
+ * reject version 2 receipts instead of misreading them.
+ */
 export type ModelsJsonFixReceiptV1 = {
-  version: 1;
+  version: 1 | 2;
   kind: "pi-cache-optimizer-fix-receipt";
   transactionId: string;
   provider: string;
@@ -22,6 +47,8 @@ export type ModelsJsonFixReceiptV1 = {
   placement: FixReceiptPlacement;
   targetExistedBefore: boolean;
   changedKeys: Record<string, FixReceiptCompatChange>;
+  /** Version 2 only: the promptCache object added at the target (absent before). */
+  promptCacheAdded?: PromptCacheLifetimes;
   beforeHash: string;
   afterHash: string;
   backupFile: string;

package/src/models-json-fix.ts

@@ -5,7 +5,7 @@ import { basename, dirname, join } from "node:path";
 import { type FileIdentity, atomicReplaceTextFilePreservingMode, atomicRestoreFileFromBackup, backupTimestamp, hashText, readRegularTextFile, sameFileIdentity, uniqueTempPath, validateAtomicTarget, withModelsJsonTransactionLock, writeFileExclusiveDurable } from "./atomic-fs.ts";
 import { LOG_PREFIX, type PiModel, asRecord, getErrorCode } from "./common.ts";
 import { findLastExactModelDefinition, resolveEffectiveCompatFromConfig } from "./compat-config.ts";
-import { type FixReceiptCompatChange, type FixReceiptPlacement, type ModelsJsonFixReceiptV1, RECEIPT_COMPAT_KEYS, type ReceiptScalar, type ReceiptScalarState, isReceiptTimestamp, isSafeReceiptText, isSha256 } from "./fix-types.ts";
+import { type FixReceiptCompatChange, type FixReceiptPlacement, type ModelsJsonFixReceiptV1, type PromptCacheLifetimes, RECEIPT_COMPAT_KEYS, type ReceiptScalar, type ReceiptScalarState, isReceiptTimestamp, isValidPromptCacheLifetimes, samePromptCacheLifetimes, isSafeReceiptText, isSha256 } from "./fix-types.ts";
 import { type JsonPropertyEdit, type ModelNodeLocation, deepEqualIgnoringKeys, deriveInnerIndent, findExistingCompatKeysInJsonc, findJsonObjectKey, findMatchingBracket, isJsonWhitespace, lineIndentOf, locateJsonPropertyValueSpan, locateModelOverrideInJsonc, locateProviderCompatInJsonc, parseJsonc, readJsonStringLiteral, skipJsonValue, skipJsonWhitespace, stripJsoncComments } from "./jsonc.ts";
 import { isAdaptiveGenerationModel, isKimiCodingAdaptiveModel } from "./model-detect.ts";
 import { FIX_RECEIPT_PATH, MODELS_JSON_PATH } from "./paths.ts";
@@ -1528,10 +1528,10 @@ export function createRollbackBackupPath(modelsPath: string = MODELS_JSON_PATH):
 
 export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV1 | undefined {
   const record = asRecord(value);
-  if (!record || record.version !== 1 || record.kind !== "pi-cache-optimizer-fix-receipt") return undefined;
+  if (!record || (record.version !== 1 && record.version !== 2) || record.kind !== "pi-cache-optimizer-fix-receipt") return undefined;
   const allowedKeys = new Set([
     "version", "kind", "transactionId", "provider", "modelId", "placement",
-    "targetExistedBefore", "changedKeys", "beforeHash", "afterHash", "backupFile",
+    "targetExistedBefore", "changedKeys", "promptCacheAdded", "beforeHash", "afterHash", "backupFile",
     "createdAt", "appliedAt", "status", "rolledBackAt",
   ]);
   if (Object.keys(record).some((key) => !allowedKeys.has(key))) return undefined;
@@ -1544,8 +1544,13 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
   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;
+  // promptCacheAdded is the version 2 marker: present exactly on v2 receipts,
+  // only for model-scoped targets, and always a valid lifetime object.
+  const isV2 = record.version === 2;
+  if (isV2 !== (record.promptCacheAdded !== undefined)) return undefined;
+  if (isV2 && (!isValidPromptCacheLifetimes(record.promptCacheAdded) || record.placement === "provider")) return undefined;
   const changedKeys = asRecord(record.changedKeys);
-  if (!changedKeys || Object.keys(changedKeys).length === 0) return undefined;
+  if (!changedKeys || (Object.keys(changedKeys).length === 0 && !isV2)) return undefined;
 
   const parsedChanges: Record<string, FixReceiptCompatChange> = {};
   for (const [key, rawChange] of Object.entries(changedKeys)) {
@@ -1563,8 +1568,9 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
   if (record.status === "rolled_back" && (!isReceiptTimestamp(record.rolledBackAt) || record.rolledBackAt < record.appliedAt)) return undefined;
   if (record.status === undefined && record.rolledBackAt !== undefined) return undefined;
 
+  const promptCacheAdded = isV2 ? record.promptCacheAdded as PromptCacheLifetimes : undefined;
   return {
-    version: 1,
+    version: isV2 ? 2 : 1,
     kind: "pi-cache-optimizer-fix-receipt",
     transactionId: record.transactionId.trim(),
     provider: record.provider.trim(),
@@ -1572,6 +1578,7 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
     placement: record.placement,
     targetExistedBefore: record.targetExistedBefore,
     changedKeys: parsedChanges,
+    ...(promptCacheAdded ? { promptCacheAdded: { ...(promptCacheAdded.short !== undefined ? { short: promptCacheAdded.short } : {}), ...(promptCacheAdded.long !== undefined ? { long: promptCacheAdded.long } : {}) } } : {}),
     beforeHash,
     afterHash,
     backupFile: record.backupFile,
@@ -1701,6 +1708,9 @@ export type ReceiptCompatTarget = {
   targetExists: boolean;
   compatBrace: number;
   compatEnd: number;
+  /** The model object or modelOverrides entry (-1 when absent or provider-level). */
+  objectBrace: number;
+  objectEnd: number;
 };
 
 export function locateReceiptCompatTarget(
@@ -1722,6 +1732,8 @@ export function locateReceiptCompatTarget(
       targetExists: location.modelOverrideObjectBrace >= 0,
       compatBrace: location.modelOverrideCompatBrace,
       compatEnd: location.modelOverrideCompatEnd,
+      objectBrace: location.modelOverrideObjectBrace,
+      objectEnd: location.modelOverrideObjectEnd,
     };
   }
 
@@ -1732,6 +1744,8 @@ export function locateReceiptCompatTarget(
       targetExists: true,
       compatBrace: location.providerCompatBrace,
       compatEnd: location.providerCompatEnd,
+      objectBrace: -1,
+      objectEnd: -1,
     };
   }
   const location = locateModelInJsonc(text, provider, modelId);
@@ -1746,6 +1760,8 @@ export function locateReceiptCompatTarget(
     targetExists: location.modelObjectBrace >= 0,
     compatBrace: location.compatObjectBrace,
     compatEnd: location.compatObjectEnd,
+    objectBrace: location.modelObjectBrace,
+    objectEnd: location.modelObjectEnd,
   };
 }
 
@@ -1772,6 +1788,72 @@ export function readReceiptCompatScalarState(
   }
 }
 
+/**
+ * Read the direct `promptCache` value of a receipt target object: the parsed
+ * value, `undefined` when absent, or "invalid" when duplicated or unreadable.
+ */
+export function readReceiptPromptCacheState(
+  text: string,
+  target: ReceiptCompatTarget | undefined,
+): unknown {
+  if (!target || target.objectBrace < 0 || target.objectEnd <= target.objectBrace) return undefined;
+  const clean = stripJsoncComments(text);
+  const property = findJsonObjectKey(clean, target.objectBrace, "promptCache");
+  if (!property || property.keyStart >= target.objectEnd) return undefined;
+  if (property.count !== 1) return "invalid";
+  const valueStart = skipJsonWhitespace(clean, property.valueStart);
+  const valueEnd = skipJsonValue(clean, valueStart);
+  if (valueEnd === undefined || valueEnd > target.objectEnd) return "invalid";
+  try {
+    return parseJsonc(text.slice(valueStart, valueEnd));
+  } catch {
+    return "invalid";
+  }
+}
+
+/**
+ * Receipt for `/cache-optimizer fix prompt-cache`: a version 2 receipt with no
+ * compat changes and the promptCache object the fix added.
+ */
+export function createPromptCacheFixReceipt(
+  originalText: string,
+  modifiedText: string,
+  provider: string,
+  modelId: string,
+  placement: "model" | "modelOverride",
+  promptCache: PromptCacheLifetimes,
+  targetExistedBefore: boolean,
+  backupPath: string,
+  now: number = Date.now(),
+): ModelsJsonFixReceiptV1 | undefined {
+  const backupFile = basename(backupPath);
+  if (!/^models\.json\.backup-cache-optimizer-/.test(backupFile)) return undefined;
+  if (!isValidPromptCacheLifetimes(promptCache)) return undefined;
+  const beforeTarget = locateReceiptCompatTarget(originalText, provider, modelId, placement);
+  const afterTarget = locateReceiptCompatTarget(modifiedText, provider, modelId, placement);
+  if (targetExistedBefore && !beforeTarget?.targetExists) return undefined;
+  if (!targetExistedBefore && beforeTarget?.targetExists) return undefined;
+  if (!afterTarget?.targetExists) return undefined;
+  if (targetExistedBefore && readReceiptPromptCacheState(originalText, beforeTarget) !== undefined) return undefined;
+  if (!samePromptCacheLifetimes(readReceiptPromptCacheState(modifiedText, afterTarget), promptCache)) return undefined;
+  return parseModelsJsonFixReceipt({
+    version: 2,
+    kind: "pi-cache-optimizer-fix-receipt",
+    transactionId: randomUUID(),
+    provider,
+    modelId,
+    placement,
+    targetExistedBefore,
+    changedKeys: {},
+    promptCacheAdded: promptCache,
+    beforeHash: hashText(originalText),
+    afterHash: hashText(modifiedText),
+    backupFile,
+    createdAt: now,
+    appliedAt: now,
+  });
+}
+
 export function createModelsJsonFixReceipt(
   originalText: string,
   modifiedText: string,
@@ -1830,11 +1912,22 @@ export function composeModelsJsonReceiptRollback(
   if (!target?.targetExists) {
     return { error: "the original target entry is missing or no longer safely locatable" };
   }
-  if (target.compatBrace < 0 || target.compatEnd <= target.compatBrace) {
+  const hasCompatChanges = Object.keys(receipt.changedKeys).length > 0;
+  if (hasCompatChanges && (target.compatBrace < 0 || target.compatEnd <= target.compatBrace)) {
     return { error: "the target compat object is missing or no longer safely locatable" };
   }
 
   const edits: JsonPropertyEdit[] = [];
+  if (receipt.promptCacheAdded) {
+    const current = readReceiptPromptCacheState(currentText, target);
+    if (current === "invalid") return { error: "receipt-owned promptCache is no longer safely locatable" };
+    if (current === undefined || !samePromptCacheLifetimes(current, receipt.promptCacheAdded)) {
+      return { error: "receipt-owned promptCache was changed after the fix; refusing to overwrite it" };
+    }
+    const property = locateJsonPropertyValueSpan(currentText, target.objectBrace, target.objectEnd, "promptCache");
+    if (!property) return { error: "receipt-owned promptCache is no longer safely locatable" };
+    edits.push(property.removal);
+  }
   for (const [key, change] of Object.entries(receipt.changedKeys)) {
     const current = readReceiptCompatScalarState(currentText, target, key);
     if (!current || !sameReceiptScalarState(current, change.after)) {
@@ -1882,6 +1975,9 @@ export function validateModelsJsonRollback(
     const state = readReceiptCompatScalarState(writtenText, target, key);
     if (!state || !sameReceiptScalarState(state, change.before)) return `rollback result did not restore compat.${key}`;
   }
+  if (receipt.promptCacheAdded && readReceiptPromptCacheState(writtenText, target) !== undefined) {
+    return "rollback result did not remove promptCache";
+  }
   return null;
 }
 

package/src/prompt-cache-fix.ts

@@ -0,0 +1,285 @@
+import { type PiModel, asRecord } from "./common.ts";
+import { deriveInnerIndent, findJsonObjectKey, findMatchingBracket, isJsonWhitespace, lineIndentOf, locateModelOverrideInJsonc, parseJsonc, skipJsonWhitespace, stripJsoncComments } from "./jsonc.ts";
+import { isValidModelsConfigForEffectiveCompat } from "./model-identity.ts";
+import { locateModelInJsonc } from "./models-json-fix.ts";
+import { suggestedPromptCacheLifetimes } from "./cache-warming.ts";
+import { type PromptCacheLifetimes, isValidPromptCacheLifetimes, samePromptCacheLifetimes } from "./fix-types.ts";
+
+/**
+ * `/cache-optimizer fix prompt-cache`: write Pi's model-level `promptCache`
+ * lifetimes into models.json so native cache warming can run.
+ *
+ * Only lifetimes this extension can stand behind are written (the same values
+ * Pi ships for its built-in Anthropic models): `{ short: 300, long: 3600 }` on
+ * the Anthropic Messages API, and `{ short: 300 }` elsewhere. When the
+ * retention tier in use has no documented lifetime, the fix refuses instead of
+ * guessing. The edit is a single new `promptCache` property; an existing
+ * `promptCache` object is never merged or overwritten.
+ */
+
+export type { PromptCacheLifetimes };
+export { isValidPromptCacheLifetimes, samePromptCacheLifetimes };
+
+export type PromptCachePlacement = "model" | "modelOverride";
+
+export type PromptCacheFixPlan = {
+  modifiedText: string;
+  placement: PromptCachePlacement;
+  /** Whether the model object or modelOverrides entry existed before the fix. */
+  targetExistedBefore: boolean;
+  promptCache: PromptCacheLifetimes;
+  locationLabel: string;
+};
+
+/**
+ * Lifetimes to write for the active retention tier, or the reason none can be
+ * written. `tier` is "long" when the extension requests 1h retention.
+ */
+export function choosePromptCacheLifetimes(
+  model: PiModel,
+  tier: "short" | "long",
+): { promptCache: PromptCacheLifetimes } | { error: string } {
+  const suggested = suggestedPromptCacheLifetimes(model);
+  if (tier === "long" && suggested.long === undefined) {
+    return {
+      error: `No documented long-retention lifetime is known for the ${model.api ?? "unknown"} API, so the fix will not guess one. ` +
+        "Add promptCache.long manually from your provider's documentation (use the conservative end of any range).",
+    };
+  }
+  // Pi merges override lifetimes over the model's own, so write only the tiers
+  // the model does not declare yet; a built-in short lifetime stays as is.
+  const declared = asRecord(asRecord(model as unknown)?.promptCache);
+  const isDeclared = (key: "short" | "long"): boolean => typeof declared?.[key] === "number" && (declared[key] as number) > 0;
+  const promptCache: PromptCacheLifetimes = {};
+  if (!isDeclared("short")) promptCache.short = suggested.short;
+  if (suggested.long !== undefined && !isDeclared("long")) promptCache.long = suggested.long;
+  if (Object.keys(promptCache).length === 0) return { error: "The model already declares every lifetime the fix would write." };
+  return { promptCache };
+}
+
+/** Pretty-print `value` so its continuation lines sit at `indent`. */
+function formatJsonValue(value: unknown, indent: string, unit: string, eol: string): string {
+  const raw = JSON.stringify(value, null, unit);
+  return raw.split("\n").map((line, index) => (index === 0 ? line : indent + line)).join(eol);
+}
+
+/**
+ * Insert `"key": value` as the last direct member of the object spanning
+ * `brace`..`end` (offsets valid in both `text` and its comment-stripped form).
+ * Comments and formatting elsewhere are untouched.
+ */
+export function insertJsonProperty(text: string, brace: number, end: number, key: string, value: unknown): string {
+  const clean = stripJsoncComments(text);
+  if (clean[brace] !== "{" || clean[end] !== "}") throw new Error("invalid object span");
+  const outerIndent = lineIndentOf(text, brace);
+  const innerIndent = deriveInnerIndent(text, brace, end);
+  const unit = innerIndent.startsWith(outerIndent) && innerIndent.length > outerIndent.length
+    ? innerIndent.slice(outerIndent.length)
+    : "  ";
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const property = `${JSON.stringify(key)}: ${formatJsonValue(value, innerIndent, unit, eol)}`;
+
+  let last = end - 1;
+  while (last > brace && isJsonWhitespace(clean[last])) last--;
+  if (last === brace) {
+    // Empty object. Keep any comment inside it, and put the closing brace on
+    // its own line when the object held only whitespace.
+    if (text.slice(brace + 1, end).trim() === "") {
+      return `${text.slice(0, brace + 1)}${eol}${innerIndent}${property}${eol}${outerIndent}${text.slice(end)}`;
+    }
+    return `${text.slice(0, brace + 1)}${eol}${innerIndent}${property}${text.slice(brace + 1)}`;
+  }
+
+  const needsComma = clean[last] !== ",";
+  // A trailing line comment on the last member stays on that member's line.
+  let insertAt = last + 1;
+  // Only a line comment qualifies: a block comment can span the newline, and
+  // inserting there would put the property inside the comment.
+  let newline = text.indexOf("\n", last + 1);
+  if (newline > 0 && text[newline - 1] === "\r") newline--;
+  if (newline >= 0 && newline < end && clean.slice(last + 1, newline).trim() === "" && !text.slice(last + 1, newline).includes("/*")) {
+    insertAt = newline;
+  }
+  const insertion = `${eol}${innerIndent}${property}`;
+  if (!needsComma) return text.slice(0, insertAt) + insertion + text.slice(insertAt);
+  return text.slice(0, last + 1) + "," + text.slice(last + 1, insertAt) + insertion + text.slice(insertAt);
+}
+
+function objectSpanForKey(clean: string, parentBrace: number, parentEnd: number, key: string): { brace: number; end: number } | "absent" | "ambiguous" {
+  const property = findJsonObjectKey(clean, parentBrace, key);
+  if (!property || property.keyStart >= parentEnd) return "absent";
+  if (property.count !== 1) return "ambiguous";
+  const brace = skipJsonWhitespace(clean, property.valueStart);
+  if (clean[brace] !== "{") return "ambiguous";
+  const end = findMatchingBracket(clean, brace);
+  if (end === undefined || end > parentEnd) return "ambiguous";
+  return { brace, end };
+}
+
+function hasDirectKey(clean: string, brace: number, end: number, key: string): boolean {
+  const property = findJsonObjectKey(clean, brace, key);
+  return property !== undefined && property.keyStart < end;
+}
+
+/** Read the promptCache value at a receipt target, `undefined` when absent. */
+export function readTargetPromptCache(parsed: unknown, provider: string, modelId: string, placement: PromptCachePlacement): unknown {
+  const providerRecord = asRecord(asRecord(asRecord(parsed)?.providers)?.[provider]);
+  if (!providerRecord) return undefined;
+  if (placement === "modelOverride") {
+    return asRecord(asRecord(providerRecord.modelOverrides)?.[modelId])?.promptCache;
+  }
+  const models = Array.isArray(providerRecord.models) ? providerRecord.models : [];
+  const matches = models.filter((entry) => asRecord(entry)?.id === modelId);
+  return asRecord(matches[matches.length - 1])?.promptCache;
+}
+
+/**
+ * Remove exactly what the plan added from a parsed copy of the modified file:
+ * the promptCache property, plus any modelOverrides entry or object the plan
+ * created. The result must equal the parsed original.
+ */
+function revertPlanInParsed(parsed: unknown, provider: string, modelId: string, plan: Pick<PromptCacheFixPlan, "placement" | "targetExistedBefore">, createdOverrides: boolean): unknown {
+  const clone = JSON.parse(JSON.stringify(parsed)) as Record<string, unknown>;
+  const providerRecord = asRecord(asRecord(clone.providers)?.[provider]);
+  if (!providerRecord) return clone;
+  if (plan.placement === "model") {
+    const models = Array.isArray(providerRecord.models) ? providerRecord.models : [];
+    const matches = models.filter((entry) => asRecord(entry)?.id === modelId);
+    const target = asRecord(matches[matches.length - 1]);
+    if (target) delete target.promptCache;
+    return clone;
+  }
+  const overrides = asRecord(providerRecord.modelOverrides);
+  if (!overrides) return clone;
+  if (!plan.targetExistedBefore) {
+    delete overrides[modelId];
+    if (createdOverrides) delete providerRecord.modelOverrides;
+  } else {
+    const entry = asRecord(overrides[modelId]);
+    if (entry) delete entry.promptCache;
+  }
+  return clone;
+}
+
+/**
+ * Plan the models.json edit. Custom models defined under `models[]` get the
+ * property on their own object; other models (built-in or proxied) get it on
+ * `providers[provider].modelOverrides[modelId]`. A provider with no
+ * models.json entry is refused, because creating one could change how Pi
+ * loads that provider.
+ */
+export function planPromptCacheFix(
+  originalText: string,
+  provider: string,
+  modelId: string,
+  promptCache: PromptCacheLifetimes,
+): PromptCacheFixPlan | { error: string } {
+  let parsedOriginal: unknown;
+  try {
+    parsedOriginal = parseJsonc(originalText);
+  } catch {
+    return { error: "models.json is not valid JSONC" };
+  }
+  if (!isValidModelsConfigForEffectiveCompat(parsedOriginal)) {
+    return { error: "models.json does not match Pi's model configuration schema" };
+  }
+  const clean = stripJsoncComments(originalText);
+
+  let plan: PromptCacheFixPlan | undefined;
+  let createdOverrides = false;
+  const modelLocation = locateModelInJsonc(originalText, provider, modelId);
+  if (modelLocation && modelLocation.modelObjectBrace >= 0) {
+    if (modelLocation.providerKeyCount !== 1 || modelLocation.allModelIds.filter((id) => id === modelId).length !== 1) {
+      return { error: `models.json defines ${provider}/${modelId} more than once` };
+    }
+    if (hasDirectKey(clean, modelLocation.modelObjectBrace, modelLocation.modelObjectEnd, "promptCache")) {
+      return { error: "the model entry already has a promptCache object; edit it manually" };
+    }
+    plan = {
+      modifiedText: insertJsonProperty(originalText, modelLocation.modelObjectBrace, modelLocation.modelObjectEnd, "promptCache", promptCache),
+      placement: "model",
+      targetExistedBefore: true,
+      promptCache,
+      locationLabel: `providers[${JSON.stringify(provider)}].models[id=${JSON.stringify(modelId)}].promptCache`,
+    };
+  } else {
+    const overrideLocation = locateModelOverrideInJsonc(originalText, provider, modelId);
+    if (!overrideLocation) {
+      return { error: `models.json has no single "${provider}" provider entry to hold a modelOverrides entry` };
+    }
+    if (overrideLocation.providerKeyCount !== 1 || overrideLocation.modelOverridesKeyCount > 1 || overrideLocation.modelOverrideKeyCount > 1) {
+      return { error: "the provider's modelOverrides entry is ambiguous (duplicate keys)" };
+    }
+    const locationLabel = `providers[${JSON.stringify(provider)}].modelOverrides[${JSON.stringify(modelId)}].promptCache`;
+    if (overrideLocation.modelOverrideObjectBrace >= 0) {
+      if (hasDirectKey(clean, overrideLocation.modelOverrideObjectBrace, overrideLocation.modelOverrideObjectEnd, "promptCache")) {
+        return { error: "the modelOverrides entry already has a promptCache object; edit it manually" };
+      }
+      plan = {
+        modifiedText: insertJsonProperty(originalText, overrideLocation.modelOverrideObjectBrace, overrideLocation.modelOverrideObjectEnd, "promptCache", promptCache),
+        placement: "modelOverride",
+        targetExistedBefore: true,
+        promptCache,
+        locationLabel,
+      };
+    } else if (overrideLocation.modelOverridesObjectBrace >= 0) {
+      plan = {
+        modifiedText: insertJsonProperty(originalText, overrideLocation.modelOverridesObjectBrace, overrideLocation.modelOverridesObjectEnd, modelId, { promptCache }),
+        placement: "modelOverride",
+        targetExistedBefore: false,
+        promptCache,
+        locationLabel,
+      };
+    } else {
+      const overrides = objectSpanForKey(clean, overrideLocation.providerObjectBrace, overrideLocation.providerObjectEnd, "modelOverrides");
+      if (overrides !== "absent") return { error: "the provider's modelOverrides value is not a single object" };
+      createdOverrides = true;
+      plan = {
+        modifiedText: insertJsonProperty(originalText, overrideLocation.providerObjectBrace, overrideLocation.providerObjectEnd, "modelOverrides", { [modelId]: { promptCache } }),
+        placement: "modelOverride",
+        targetExistedBefore: false,
+        promptCache,
+        locationLabel,
+      };
+    }
+  }
+
+  const checkError = selfCheckPromptCacheFix(originalText, plan, provider, modelId, createdOverrides);
+  if (checkError) return { error: `self-check failed: ${checkError}` };
+  return plan;
+}
+
+export function selfCheckPromptCacheFix(
+  originalText: string,
+  plan: PromptCacheFixPlan,
+  provider: string,
+  modelId: string,
+  createdOverrides: boolean,
+): string | null {
+  let original: unknown;
+  let modified: unknown;
+  try {
+    original = parseJsonc(originalText);
+    modified = parseJsonc(plan.modifiedText);
+  } catch {
+    return "the edited file is not valid JSONC";
+  }
+  if (!isValidModelsConfigForEffectiveCompat(modified)) return "the edited file does not match Pi's model configuration schema";
+  if (!samePromptCacheLifetimes(readTargetPromptCache(modified, provider, modelId, plan.placement), plan.promptCache)) {
+    return "promptCache was not written at the target";
+  }
+  const reverted = revertPlanInParsed(modified, provider, modelId, plan, createdOverrides);
+  if (JSON.stringify(reverted) !== JSON.stringify(original)) return "unrelated configuration was altered";
+  return null;
+}
+
+/** Validate a file written by the fix transaction (same checks, re-read from disk). */
+export function validateWrittenPromptCacheFix(writtenText: string, plan: PromptCacheFixPlan): string | null {
+  if (writtenText !== plan.modifiedText) return "models.json content differs from the previewed edit";
+  try {
+    parseJsonc(writtenText);
+  } catch {
+    return "the written file is not valid JSONC";
+  }
+  return null;
+}