pi-cache-optimizer 2.8.20 → 2.8.22

package/README.md

@@ -35,9 +35,9 @@ Pi extension for improving provider-side KV / prompt cache hit rates. It keeps s
 
 - Compresses Pi's skill list into a grouped Markdown list that keeps every skill name and description (only the XML envelope and repeated paths are removed), and strips session-overview churn. Both are in-place edits that never move content between Pi's prompt sections, and they also apply to OpenAI Responses/Codex models. (Earlier versions also lifted "stable" content to the front of the prompt; Pi >= 0.86 already orders its sections from stable to variable, and measured prefix stability was identical, so that step was removed.)
 - Requests long cache retention when Pi/provider compat supports it.
-- Adds a conservative session-id `prompt_cache_key` fallback for `openai-completions` proxy payloads when no effective key exists. Pi 1.0+ owns this field for Responses/Codex transports.
+- Adds a conservative per-session `prompt_cache_key` fallback for `openai-completions` proxy payloads when no effective key exists. The values this extension adds itself (that key fallback, the session-affinity header bridge, and cache hints) are a one-way hash of the Pi session id (`pi-<32 hex>`); keys and headers that Pi core sets on its own are left untouched, and an existing key is never overwritten. Pi 1.0+ owns this field for Responses/Codex transports.
 - Warns once for third-party OpenAI-compatible proxies missing cache/session-affinity compat flags.
-- Detects adaptive-thinking compat for Claude (opus-4.6+ including Opus 5, sonnet-4.6+ including Sonnet 5, fable-5+) and Kimi Coding K3 / `kimi-for-coding` custom channels.
+- Detects adaptive-thinking compat for Claude (opus-4.6+ including Opus 5, sonnet-4.6+ including Sonnet 5, fable-5+, haiku-5+ including Haiku 5.5) and Kimi Coding K3 / `kimi-for-coding` custom channels.
 - Stores cache statistics in per-extension-instance atomic shards, so parent sessions, child Pi agents, and parallel Pi processes cannot overwrite one another.
 - Shows current conversation-session provider/model footer stats by default; `total` aggregates all valid local shards for the exact provider/model.
 - Supports optional router-extension integration through versioned global protocols (`Symbol.for("pi.routing.registry.v1")` and `Symbol.for("pi.cache.hints.v1")`) without importing router packages.
@@ -62,7 +62,7 @@ Run `/reload` in Pi after install/update/remove so extension hooks refresh.
 
 On Pi 0.79.7 and newer, `pi update` updates Pi itself only. To update installed Pi packages such as this extension, run `pi update --extensions` (packages only) or `pi update --all` (Pi + packages).
 
-This extension requires Pi 0.82+ and is validated against Pi 1.0.3. It uses the official Pi package types directly for type-checking, along with extension hooks, `getAgentDir()`, and prompt options shared by those versions; it does not depend on Pi 0.83+ APIs such as `ctx.scopedModels` or the bundled TypeBox 1.3 aliases. Native virtual model support and codemode nested-call coalescing activate only on Pi 0.99+ hosts that produce them; older hosts keep the previous behavior. The local development baseline uses Node.js 22.19.0 or newer, matching Pi 1.0.3's engine requirement.
+This extension requires Pi 0.82+ and is validated against Pi 1.1.0. It uses the official Pi package types directly for type-checking, along with extension hooks, `getAgentDir()`, and prompt options shared by those versions; it does not depend on Pi 0.83+ APIs such as `ctx.scopedModels` or the bundled TypeBox 1.3 aliases. Native virtual model support and codemode nested-call coalescing activate only on Pi 0.99+ hosts that produce them; older hosts keep the previous behavior. The local development baseline uses Node.js 22.19.0 or newer, matching Pi 1.0.3's engine requirement.
 
 ## Commands
 
@@ -170,7 +170,7 @@ The preview explains that the setting is stored in the extension-owned `pi-cache
 
 Third-party `openai-completions` proxies (LiteLLM / OneAPI / NewAPI / OpenRouter-like channels) often route one session across multiple upstream backends. That splits provider-side prompt caches.
 
-Pi 0.84.1 also fixes built-in Fireworks compatibility for models that reject `prompt_cache_retention`; the extension avoids provider-name special cases and resolves exact provider/model compat from `models.json` plus the runtime model. Pi 0.81+ also has a built-in `llama.cpp` provider using an OpenAI-shaped transport. The extension keeps its session-id key fallback for third-party `openai-completions` channels, while Pi 1.0+ owns the key for Responses/Codex transports. The built-in provider's explicit compat fingerprint is excluded from generic proxy routing/session-affinity advice, but a custom or overridden provider that merely reuses the id `llama.cpp` is treated like any other OpenAI-compatible channel. `prompt_cache_retention` remains subject to the normal safety rule: keep it only for official OpenAI or an explicit effective `supportsLongCacheRetention: true` opt-in in `models.json`; otherwise strip it before sending. The extension-owned `pi-cache-optimizer-config.json` stores per-model key opt-outs only for `openai-completions`.
+Pi 0.84.1 also fixes built-in Fireworks compatibility for models that reject `prompt_cache_retention`; the extension avoids provider-name special cases and resolves exact provider/model compat from `models.json` plus the runtime model. Pi 0.81+ also has a built-in `llama.cpp` provider using an OpenAI-shaped transport. The extension keeps its session-id key fallback for third-party `openai-completions` channels, while Pi 1.0+ owns the key for Responses/Codex transports. The built-in provider's explicit compat fingerprint is excluded from generic proxy routing/session-affinity advice, but a custom or overridden provider that merely reuses the id `llama.cpp` is treated like any other OpenAI-compatible channel. `prompt_cache_retention` follows one safety rule: the extension only undoes the side effect of its own `PI_CACHE_RETENTION=long`. In order: a model that already rejected the parameter in this process never gets it again; official OpenAI keeps it; an explicit `supportsLongCacheRetention: true` (from `models.json`, or on the runtime model from a provider extension; an explicit `false` in `models.json` still wins) keeps it; a `PI_CACHE_RETENTION=long` you set yourself before Pi started keeps it; otherwise it is removed before sending. Azure OpenAI is not allow-listed because extended retention there depends on the deployed model. `/cache-optimizer doctor` shows the latest decision and its reason. The extension-owned `pi-cache-optimizer-config.json` stores per-model key opt-outs only for `openai-completions`.
 
 For real proxies, start with session affinity:
 
@@ -213,7 +213,7 @@ Some proxies rewrite or insert hidden 5-minute breakpoints after Pi's request ho
 
 ## Adaptive thinking models
 
-Claude models from opus-4.6 / sonnet-4.6 (including Opus 5 and Sonnet 5) / fable-5 onwards require `forceAdaptiveThinking: true` in compat. Kimi Coding K3 (`k3`) and `kimi-for-coding` also use adaptive thinking and need `allowEmptySignature: true` so replayed empty-signature thinking blocks remain valid. Without the required compat, Pi may send a legacy thinking payload or replay thinking incorrectly. Pi 0.83+ native Opus 5 catalogs are covered by the same adaptive-thinking detection; custom `anthropic-messages` channels still need the compat flag when Pi does not provide it.
+Claude models from opus-4.6 / sonnet-4.6 (including Opus 5 and Sonnet 5) / fable-5 / haiku-5 (Haiku 5.5, Pi 1.1.0+) onwards require `forceAdaptiveThinking: true` in compat. Kimi Coding K3 (`k3`) and `kimi-for-coding` also use adaptive thinking and need `allowEmptySignature: true` so replayed empty-signature thinking blocks remain valid. Without the required compat, Pi may send a legacy thinking payload or replay thinking incorrectly. Pi 0.83+ native Opus 5 catalogs are covered by the same adaptive-thinking detection; custom `anthropic-messages` channels still need the compat flag when Pi does not provide it.
 
 Pi's built-in catalog already sets this flag for official models. Custom channels in `models.json` that override these models must include the flag:
 

package/README.zh-CN.md

@@ -35,9 +35,9 @@
 
 - 将 Pi 的 skill 列表压缩为按目录分组的 Markdown 列表，保留每个 skill 的名称和完整描述（只去掉 XML 外壳和重复路径），并移除 session-overview 中的易变字段。这两项都是原位修改，不会在 Pi 的提示段之间搬移内容，对 OpenAI Responses/Codex 模型同样生效。（早期版本还会把“稳定”内容提到提示最前面；Pi 0.86 起已按从稳定到易变的顺序拼段，实测前缀稳定性没有差别，因此移除了这一步。）
 - 在 Pi / provider compat 支持时请求长缓存保留。
-- 仅对 `openai-completions` 代理请求，在没有有效 key 时使用 Pi session id 保守补 `prompt_cache_key`；Pi 1.0+ 已负责 Responses/Codex transport 的 key。
+- 仅对 `openai-completions` 代理请求，在没有有效 key 时按会话保守补 `prompt_cache_key`；本扩展自己补的值（该 key、session-affinity 头补齐、cache hints）使用 Pi session id 的单向哈希（`pi-<32 位 hex>`）；Pi 核心自己设置的 key 和头保持不变，已有 key 也绝不覆盖；Pi 1.0+ 已负责 Responses/Codex transport 的 key。
 - 对缺少缓存 / session-affinity compat 的第三方 OpenAI-compatible 代理给出一次性提醒。
-- 检测 Claude（opus-4.6+ 含 Opus 5、sonnet-4.6+ 含 Sonnet 5、fable-5+）以及 Kimi Coding K3 / `kimi-for-coding` 自定义渠道的 adaptive-thinking compat。
+- 检测 Claude（opus-4.6+ 含 Opus 5、sonnet-4.6+ 含 Sonnet 5、fable-5+、haiku-5+ 含 Haiku 5.5）以及 Kimi Coding K3 / `kimi-for-coding` 自定义渠道的 adaptive-thinking compat。
 - 使用每个 extension instance 独占的原子 shard 保存缓存统计，避免父会话、子 Pi agent 和并行 Pi 进程互相覆盖。
 - Footer 默认显示当前 conversation session 的 provider/model 统计；`total` 可聚合同一精确 provider/model 的所有有效本地 shard。
 - 通过版本化全局协议（`Symbol.for("pi.routing.registry.v1")` 与 `Symbol.for("pi.cache.hints.v1")`）支持可选的 router extension 集成，而不导入任何 router 包。
@@ -62,7 +62,7 @@ pi remove npm:pi-deepseek-cache-optimizer && pi install npm:pi-cache-optimizer
 
 Pi 0.79.7 及之后，`pi update` 默认只更新 Pi 本体。若要更新已安装的 Pi package（包括本扩展），请运行 `pi update --extensions`（只更新 packages）或 `pi update --all`（Pi 与 packages 一起更新）。
 
-本扩展要求 Pi 0.82+，并已使用 Pi 1.0.3 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。原生虚拟模型支持与 codemode 嵌套工具调用合并只在会产生它们的 Pi 0.99+ 上生效，较早版本保持原有行为。本地开发基线需要 Node.js 22.19.0 或更高版本，与 Pi 1.0.3 的 engine 要求一致。
+本扩展要求 Pi 0.82+，并已使用 Pi 1.1.0 验证。TypeScript 校验直接使用官方 Pi package 类型，同时只使用这些版本共有的 extension hooks、`getAgentDir()` 和 prompt options；不依赖 Pi 0.83+ 专有 API（例如 `ctx.scopedModels` 或 bundled TypeBox 1.3 aliases）。原生虚拟模型支持与 codemode 嵌套工具调用合并只在会产生它们的 Pi 0.99+ 上生效，较早版本保持原有行为。本地开发基线需要 Node.js 22.19.0 或更高版本，与 Pi 1.0.3 的 engine 要求一致。
 
 ## 命令
 
@@ -170,7 +170,7 @@ Footer 默认使用 `session`，避免另一个并行 Pi 终端使用相同 prov
 
 LiteLLM / OneAPI / NewAPI / 类 OpenRouter 渠道等第三方 `openai-completions` 代理，常会把同一个 session 分散到多个上游后端，导致 provider 侧 prompt cache 被拆散。
 
-Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention` 的模型兼容性；本扩展不按 provider 名称增加特殊分支，而是结合 `models.json` 与 runtime model，按精确 provider/model 解析有效 compat。Pi 0.81+ 也内置了使用 OpenAI-shaped transport 的 `llama.cpp` provider。本扩展只对第三方 `openai-completions` 保留 session-id key fallback；Pi 1.0+ 已负责 Responses/Codex transport 的 key。只有符合 Pi 内置 provider 明确 compat 指纹的模型会跳过通用 proxy 路由 / session-affinity 建议；仅复用 `llama.cpp` id 的自定义或覆盖 provider 仍按普通 OpenAI-compatible 渠道处理。`prompt_cache_retention` 继续遵循统一安全规则：仅官方 OpenAI 或 `models.json` 中有效配置为 `supportsLongCacheRetention: true` 时保留，否则发送前移除。Pi 1.0.3 没有原生的 `supportsPromptCacheKey` compat 字段，因此仅对 `openai-completions` 按模型关闭 key 的策略保存在本扩展的 `pi-cache-optimizer-config.json` 中，而不是 `models.json`。扩展配置独立于 Pi 的 compat 优先级，只影响其中列出的精确 provider/model。
+Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention` 的模型兼容性；本扩展不按 provider 名称增加特殊分支，而是结合 `models.json` 与 runtime model，按精确 provider/model 解析有效 compat。Pi 0.81+ 也内置了使用 OpenAI-shaped transport 的 `llama.cpp` provider。本扩展只对第三方 `openai-completions` 保留 session-id key fallback；Pi 1.0+ 已负责 Responses/Codex transport 的 key。只有符合 Pi 内置 provider 明确 compat 指纹的模型会跳过通用 proxy 路由 / session-affinity 建议；仅复用 `llama.cpp` id 的自定义或覆盖 provider 仍按普通 OpenAI-compatible 渠道处理。`prompt_cache_retention` 遵循统一安全规则：扩展只撤销自己设置 `PI_CACHE_RETENTION=long` 带来的副作用。依次判断：本进程内该模型已明确拒绝过该参数 → 移除；官方 OpenAI → 保留；显式 `supportsLongCacheRetention: true`（来自 `models.json`，或 provider 扩展注册的 runtime model；`models.json` 中显式 `false` 仍优先）→ 保留；用户在 Pi 启动前自行设置了 `PI_CACHE_RETENTION=long` → 保留；其余情况发送前移除。Azure OpenAI 不在白名单中，因为其长缓存支持取决于具体部署的模型。`/cache-optimizer doctor` 会显示最近一次判断及原因。Pi 1.0.3 没有原生的 `supportsPromptCacheKey` compat 字段，因此仅对 `openai-completions` 按模型关闭 key 的策略保存在本扩展的 `pi-cache-optimizer-config.json` 中，而不是 `models.json`。扩展配置独立于 Pi 的 compat 优先级，只影响其中列出的精确 provider/model。
 
 对真正的代理，建议先启用 session affinity：
 
@@ -213,7 +213,7 @@ Anthropic 按 `tools → system → messages` 顺序处理 cache breakpoint，
 
 ## Adaptive thinking 模型
 
-Claude 从 opus-4.6 / sonnet-4.6（含 Opus 5、Sonnet 5）/ fable-5 开始需要在 compat 中设置 `forceAdaptiveThinking: true`。Kimi Coding K3（`k3`）和 `kimi-for-coding` 也使用 adaptive thinking，并需要 `allowEmptySignature: true`，以正确重放空 signature 的 thinking block。缺少这些 compat 时，Pi 可能发送旧版 thinking payload 或错误重放 thinking。Pi 0.83+ 的原生 Opus 5 catalog 已覆盖在同一 adaptive-thinking 检测中；如果自定义 `anthropic-messages` 渠道没有继承该 compat，仍需手动设置。
+Claude 从 opus-4.6 / sonnet-4.6（含 Opus 5、Sonnet 5）/ fable-5 / haiku-5（Haiku 5.5，Pi 1.1.0+）开始需要在 compat 中设置 `forceAdaptiveThinking: true`。Kimi Coding K3（`k3`）和 `kimi-for-coding` 也使用 adaptive thinking，并需要 `allowEmptySignature: true`，以正确重放空 signature 的 thinking block。缺少这些 compat 时，Pi 可能发送旧版 thinking payload 或错误重放 thinking。Pi 0.83+ 的原生 Opus 5 catalog 已覆盖在同一 adaptive-thinking 检测中；如果自定义 `anthropic-messages` 渠道没有继承该 compat，仍需手动设置。
 
 Pi 内置 catalog 已为官方模型设置此 flag。`models.json` 中覆盖这些模型的自定义渠道必须包含该 flag：
 

package/index.ts

@@ -1,48 +1,40 @@
-import { createHash, randomUUID } from "node:crypto";
-import { chmod, copyFile, link, lstat, mkdir, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
-import { constants as fsConstants, readFileSync, statSync, watch } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { watch } from "node:fs";
+import { join } from "node:path";
 import {
-  getAgentDir,
-  type BuildSystemPromptOptions,
-  type ExtensionAPI,
-  type ExtensionCommandContext,
-  type ExtensionContext,
+  type ExtensionAPI, type ExtensionContext
 } from "@earendil-works/pi-coding-agent";
-import { LOG_PREFIX, type ModelIdentity, type PiModel, type UnknownRecord, asRecord, getErrorCode, isNonEmptyString, isProcessAlive, lower, type MutableEnv } from "./src/common.ts";
-import { FIX_RECEIPT_FILE_NAME, FIX_RECEIPT_PATH, MODELS_JSON_PATH, MODELS_TRANSACTION_LOCK_PATH, MODELS_TRANSACTION_LOCK_STALE_MS, MODELS_TRANSACTION_LOCK_WAIT_MS, STATE_DIR } from "./src/paths.ts";
-import { type FixReceiptCompatChange, type FixReceiptPlacement, type FixSuggestion, type ModelsJsonFixReceiptV1, RECEIPT_COMPAT_KEYS, type ReceiptScalar, type ReceiptScalarState, isReceiptTimestamp, isSafeReceiptText, isSha256 } from "./src/fix-types.ts";
-import { type JsonPropertyEdit, type ModelNodeLocation, deepEqualIgnoringKeys, deriveInnerIndent, findExistingCompatKeysInJsonc, findJsonObjectKey, findMatchingBracket, isJsonWhitespace, lineIndentOf, locateJsonPropertyValueSpan, locateModelOverrideInJsonc, locateProviderCompatInJsonc, parseJsonc, readJsonStringLiteral, skipJsonValue, skipJsonWhitespace, stripJsoncComments, stripJsoncTrailingCommas } from "./src/jsonc.ts";
-import { type FileIdentity, atomicCreateTextFileNoReplace, atomicReplaceTextFilePreservingMode, atomicRestoreFileFromBackup, backupTimestamp, hashText, readRegularTextFile, sameFileIdentity, uniqueTempPath, validateAtomicTarget, withModelsJsonTransactionLock } from "./src/atomic-fs.ts";
-import { getAssistantMessageModelTokenValues, getModelIdNameTokenValues, hasAnyTokenContaining, isAdaptiveGenerationModel, isKimiCodingAdaptiveModel, modelOrAssistantMessageHas } from "./src/model-detect.ts";
-import { type CacheCompat, NESTED_COMPAT_KEYS, findLastExactModelDefinition, getEffectiveCompatSources, mergeCacheCompat, resolveEffectiveCompatFromConfig } from "./src/compat-config.ts";
-import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, chooseFixPlacement, composeFixInsertion, composeMissingEntryInsertion, composeModelOverrideInsertion, composeModelsJsonReceiptRollback, composeProviderAffinityInsertion, createModelsJsonFixReceipt, createRollbackBackupPath, decideFixPlacement, formatCompatKeysForInsertion, formatMissingEntryManualSnippet, hasExplicitLongRetentionOptInFromConfig, hasReceiptReasoningProtocolChange, isActionableModelsJsonFixReceipt, locateModelInJsonc, markModelsJsonFixReceiptRolledBack, parseModelsJsonFixReceipt, prepareModelsJsonRollback, readModelsJsonFixReceipt, readModelsJsonFixReceiptSnapshot, receiptBackupPath, resolveExplicitCompatValue, selfCheckFix, selfCheckMissingEntryInsertion, validateModelsJsonRollback, writeModelsJsonFixReceipt } from "./src/models-json-fix.ts";
-import { getNonNegativeNumber, getNumber } from "./src/common.ts";
-import { CACHE_PROVIDER_IDS, 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, mergeCacheStatsForTotal, modelEpochPath, parseCacheStats, parsePersistedRoutedModelRef, parsePersistedStatsShardV7, readGlobalStatsEpoch, readModelStatsEpoch, readValidStatsShardsV7, removeLegacyStatsFiles, writeStatsShardV7 } from "./src/stats-store.ts";
-import { ALEPH_MODEL_PATTERN, ARCTIC_MODEL_PATTERN, AYA_MODEL_PATTERN, DOUBAO_SEED_PATTERN, MIMO_MODEL_PATTERN, MPT_MODEL_PATTERN, NOVA_MODEL_PATTERN, ORION_MODEL_PATTERN, PHI_MODEL_PATTERN, PI_VIRTUAL_MODEL_API, PPLX_MODEL_PATTERN, ROUTED_FALLBACK_MODEL_SYMBOL, XAI_MODEL_PATTERN, YI_MODEL_PATTERN, getAssistantRecord, getCompat, isAnthropicMessagesApi, isAssistantMessage, isClaudeLikeAssistantMessage, isClaudeLikeModel, isDeepSeekLikeAssistantMessage, isDeepSeekLikeModel, isGeminiLikeAssistantMessage, isGeminiLikeModel, isKimiCodingEmptySignatureModel, isKnownThirdPartyOpenAIEndpoint, isMistralConversationsApi, isNativeVirtualModel, isOfficialOpenAIBaseUrl, isOpenAICompatibleApi, isOpenAICompatibleProxyApi, isOpenAIFamilyAssistantMessage, isOpenAIFamilyModel, isOpenAIFamilyToken, isPiBuiltInLlamaCppModel, isResponsesPromptRewriteBypassApi, isRoutedFallbackModel, isValidModelsConfigForEffectiveCompat, modelKey, readEffectiveCompatConfig } from "./src/model-identity.ts";
-import { invalidateModelsConfigCache } from "./src/model-identity.ts";
-import { getAnthropicRawUsage, getDeepSeekRawUsage, getGeminiRawUsage, getOpenAIRawUsage, normalizeWithFallback, usageRecordFromAssistant } from "./src/usage.ts";
-import { CONFIG_FILE_PATH, NO_SKILL_COMPRESSION_ENV, VIRTUAL_REWRITE_ENV, FOOTER_MODE_ENV, type FooterStatsMode, NO_OPENAI_CACHE_KEY_ENV, type PersistedCacheOptimizerConfig, type PersistedCacheOptimizerConfigV2, type PersistedCacheOptimizerConfigV3, type PersistedCacheOptimizerFeature, TOOL_ORDER_ENV, featureEnabled, footerStatsMode, isEnabledEnv, isToolOrderEnabled, normalizePersistedCacheOptimizerConfig, parseFooterStatsMode, parsePersistedCacheOptimizerConfig, persistedCacheOptimizerConfig, persistedFooterStatsMode, readPersistedCacheOptimizerConfig, resolveFooterStatsMode, runtimeOptimizerEnabled, setPersistedCacheOptimizerConfig, shouldInjectOpenAIPromptCacheKey, writePersistedCacheOptimizerConfig, writePersistedFeature, writePersistedFooterMode } from "./src/config.ts";
-import { LONG_CACHE_RETENTION_VALUE, PI_CACHE_RETENTION_BASELINE_SYMBOL, PI_CACHE_RETENTION_ENV, STARTUP_CACHE_RETENTION_ENV, captureCacheRetentionEnv, getOrCaptureCacheRetentionBaseline, requestLongCacheRetention, restoreCacheRetentionEnv } from "./src/retention.ts";
+import { LOG_PREFIX, type PiModel, asRecord, isNonEmptyString } from "./src/common.ts";
+import { FIX_RECEIPT_FILE_NAME, FIX_RECEIPT_PATH, MODELS_JSON_PATH, STATE_DIR } from "./src/paths.ts";
+import { type FixSuggestion } from "./src/fix-types.ts";
+import { deepEqualIgnoringKeys, findExistingCompatKeysInJsonc, locateModelOverrideInJsonc, locateProviderCompatInJsonc, parseJsonc, stripJsoncComments, stripJsoncTrailingCommas } from "./src/jsonc.ts";
+import { atomicCreateTextFileNoReplace, atomicReplaceTextFilePreservingMode, atomicRestoreFileFromBackup, backupTimestamp, hashText } from "./src/atomic-fs.ts";
+import { getAssistantMessageModelTokenValues, getModelIdNameTokenValues, isAdaptiveGenerationModel, isKimiCodingAdaptiveModel } from "./src/model-detect.ts";
+import { findLastExactModelDefinition, mergeCacheCompat, resolveEffectiveCompatFromConfig } from "./src/compat-config.ts";
+import { analyzeModelsJsonForMissingEntry, applyModelsJsonFixTransaction, chooseFixPlacement, composeFixInsertion, composeMissingEntryInsertion, composeModelOverrideInsertion, composeModelsJsonReceiptRollback, composeProviderAffinityInsertion, createModelsJsonFixReceipt, createRollbackBackupPath, decideFixPlacement, formatCompatKeysForInsertion, hasExplicitLongRetentionOptInFromConfig, hasReceiptReasoningProtocolChange, isActionableModelsJsonFixReceipt, locateModelInJsonc, markModelsJsonFixReceiptRolledBack, parseModelsJsonFixReceipt, prepareModelsJsonRollback, readModelsJsonFixReceipt, readModelsJsonFixReceiptSnapshot, receiptBackupPath, resolveExplicitCompatValue, selfCheckFix, selfCheckMissingEntryInsertion, validateModelsJsonRollback, writeModelsJsonFixReceipt } from "./src/models-json-fix.ts";
+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 { 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 { 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 } from "./src/request-payload.ts";
-import { PI_CACHE_HINTS_SYMBOL, PI_ROUTING_REGISTRY_SYMBOL, type PiCacheHintsInput, type PiCacheHintsOutput, type PiCacheHintsV1, applyConfiguredTransportToModel, canRewriteNativeVirtualPrompt, describeNativeVirtualRouteNote, ensureRoutingRegistry, findModelInRegistry, findNativeVirtualDispatches, firstNonEmptyString, getProtocolGlobal, getProviderPayloadModelId, getRoutingRegistry, hashSessionId, installCacheHintsService, isRouterModel, nativeVirtualDispatchFromMessage, nativeVirtualDispatchToModel, parseRouteSnapshot, resolveActiveRouteSnapshot, resolveNativeVirtualRequestModel, resolveNativeVirtualRouteModel, resolveRouteModel, routeSnapshotToPiModel, sessionHashFromContext } from "./src/routing.ts";
-import { CONFIG_RECEIPT_PATH, type PromptCacheKeyConfigReceipt, type PromptCacheKeyConfigReceiptSnapshot, applyPromptCacheKeyConfigFix, configReceiptBackupPath, parsePromptCacheKeyConfigReceipt, rollbackPromptCacheKeyConfig, writePromptCacheKeyConfigReceipt } from "./src/prompt-cache-key-config.ts";
-import { type CompatAdvicePlacement, appendCredentialSafeProviderGuidance, appendDeepSeekCompatAdviceLines, appendOpenAIProxyCompatAdviceLines, buildDeepSeekCompatSuggestion, buildDeepSeekCompatWarningText, buildModelCompatOverride, buildOpenAIProxyCompatWarningText, buildProviderCompatOverride, buildSafeOpenAIProxyCompatSuggestion, describeMissingAdaptiveThinkingCompat, describeMissingCacheCompatForModel, describeMissingDeepSeekCompat, describeMissingOpenAICompatibleProxyCompat, getAgentDirDisplayPath, getModelsJsonDisplayPath, isAdaptiveThinkingCompatApplicable, isDeepSeekWireCompatApplicable } from "./src/compat-advice.ts";
+import { addEffectiveSessionAffinityHeaders, addOpenAIPromptCacheKey, clampPromptCacheKey, collectAnthropicCacheControlsInWireOrder, downgradeAnthropicLongCacheControls, getEffectiveCompatValueSource, hasAnthropicCacheTtlOrderError, hasEffectivePromptCacheKey, isPromptCacheKeyOmittedForModel, normalizeAnthropicCacheControlTtlOrder, omitOpenAIPromptCacheKeys, shouldInjectOpenAIPromptCacheKeyForModel, withAnthropicCacheTtlRepair, withoutPromptCacheRetention, derivePromptCacheKey } from "./src/request-payload.ts";
+import { PI_CACHE_HINTS_SYMBOL, PI_ROUTING_REGISTRY_SYMBOL, type PiCacheHintsInput, type PiCacheHintsOutput, applyConfiguredTransportToModel, canRewriteNativeVirtualPrompt, describeNativeVirtualRouteNote, ensureRoutingRegistry, findModelInRegistry, findNativeVirtualDispatches, getProtocolGlobal, getProviderPayloadModelId, getRoutingRegistry, hashSessionId, installCacheHintsService, nativeVirtualDispatchFromMessage, nativeVirtualDispatchToModel, parseRouteSnapshot, resolveActiveRouteSnapshot, resolveNativeVirtualRequestModel, resolveNativeVirtualRouteModel, resolveRouteModel, routeSnapshotToPiModel, sessionHashFromContext } from "./src/routing.ts";
+import { CONFIG_RECEIPT_PATH, applyPromptCacheKeyConfigFix, configReceiptBackupPath, parsePromptCacheKeyConfigReceipt, rollbackPromptCacheKeyConfig, writePromptCacheKeyConfigReceipt } from "./src/prompt-cache-key-config.ts";
+import { buildDeepSeekCompatSuggestion, buildDeepSeekCompatWarningText, buildModelCompatOverride, buildOpenAIProxyCompatWarningText, buildProviderCompatOverride, buildSafeOpenAIProxyCompatSuggestion, describeMissingAdaptiveThinkingCompat, describeMissingCacheCompatForModel, describeMissingDeepSeekCompat, describeMissingOpenAICompatibleProxyCompat, getAgentDirDisplayPath, getModelsJsonDisplayPath, isAdaptiveThinkingCompatApplicable, isDeepSeekWireCompatApplicable } from "./src/compat-advice.ts";
 import { type CacheProviderAdapter, isVirtualRoutingModel, modelFromAssistantMessage, selectAdapterForAssistantMessage, selectAdapterForModel } from "./src/adapters.ts";
 import { describeMissingOpenAIFamilyProxyCompat } from "./src/compat-advice.ts";
 import { type CacheUsageSample, buildAllStatsOutput, buildContributorsStatsOutput, buildSessionStatsOutput, buildStatsOutput, deriveTotalsByModelFromSessionStats, filterRestorableStatsForSession, formatCacheStats, formatCompactStats, formatHitRatio, formatRecentTrendSummary, formatTokenM, hasMissingUsageFields, makeSessionModelKey, mergeCacheSessions, mergeCacheTotals, mergeLastRoutedModels, modelKeyFromSessionKey, parsePersistedCacheStats, parsePersistedTotalsByModel, prefixFooterStatus, readPersistedCacheStats, routedModelRefToPiModel, selectFooterStatsForModel, writePersistedCacheStats } from "./src/stats-report.ts";
-import { appendAdaptiveThinkingCompatAdviceLines, buildAdaptiveThinkingCompatSuggestion, buildCompatDiagnosis, buildDoctorDiagnosis, buildFixSuggestion, buildLowHitDiagnosis, describeOptionalOpenAICompatibleProxyCompat, describeRouterChannelDiagnostics, getCompatCheckNotApplicableLines, getOptionalAssistantHttpStatus, getPromptCacheRetentionUnsupportedHint, isCompatCheckApplicable, isDeepSeekCompatCheckApplicable, isOpenAISdkHeader403Applicable, isPromptCacheKeyUnsupportedApplicable, isPromptCacheRetention400Applicable, isSessionAffinity403Applicable } from "./src/diagnostics.ts";
-import { REASONING_PROTOCOL_FALLBACK_SYMBOL, buildReasoningProtocolFixSuggestion, getAnthropicTtlFallbackState, getReasoningProtocolFallbackState, hasExplicitDeepSeekReasoningProtocol, hasPromptCacheKeyUnsupportedErrorMessage, hasPromptCacheKeyUnsupportedText, hasPromptCacheRetentionUnsupportedErrorMessage, hasPromptCacheRetentionUnsupportedText, hasReasoningProtocolRejectionErrorMessage, hasReasoningProtocolRejectionText, isExplicitPromptCacheRetentionUnsupportedApplicable, isReasoningProtocolRejectionForModel, isReasoningProtocolRejectionSignalApplicable, mergeFixSuggestions, notifyReasoningProtocolObservation } from "./src/provider-errors.ts";
+import { appendAdaptiveThinkingCompatAdviceLines, buildAdaptiveThinkingCompatSuggestion, buildCompatDiagnosis, buildDoctorDiagnosis, buildFixSuggestion, buildLowHitDiagnosis, describeOptionalOpenAICompatibleProxyCompat, describeRouterChannelDiagnostics, getCompatCheckNotApplicableLines, getPromptCacheRetentionUnsupportedHint, isCompatCheckApplicable, isDeepSeekCompatCheckApplicable, isOpenAISdkHeader403Applicable, isPromptCacheKeyUnsupportedApplicable, isPromptCacheRetention400Applicable, isSessionAffinity403Applicable } from "./src/diagnostics.ts";
+import { REASONING_PROTOCOL_FALLBACK_SYMBOL, buildReasoningProtocolFixSuggestion, getAnthropicTtlFallbackState, getReasoningProtocolFallbackState, hasExplicitDeepSeekReasoningProtocol, hasPromptCacheKeyUnsupportedErrorMessage, hasPromptCacheKeyUnsupportedText, hasPromptCacheRetentionUnsupportedErrorMessage, hasReasoningProtocolRejectionErrorMessage, hasReasoningProtocolRejectionText, isExplicitPromptCacheRetentionUnsupportedApplicable, isReasoningProtocolRejectionForModel, isReasoningProtocolRejectionSignalApplicable, mergeFixSuggestions, notifyReasoningProtocolObservation } from "./src/provider-errors.ts";
 import { hasPromptCacheKeyUnsupportedSignal, hasPromptCacheRetentionUnsupportedSignal, hasReasoningProtocolRejectionSignal } from "./src/provider-errors.ts";
 import { MAX_RECENT_SAMPLES, buildExactRouterStatusEntry, consolidateDirectProviderStatsModel, createSerializedAsyncRunner, findBestRouterModelStats, keyForModelExt } from "./src/stats-report.ts";
 import { type PiCacheHintSnapshot, getCacheHintsService, getSessionPromptCacheKey, isOptimizerOwnedCacheHintsService, markOptimizerOwnedCacheHintsService } from "./src/routing.ts";
 import { isActionablePromptCacheKeyConfigReceipt, readPromptCacheKeyConfigReceipt, readPromptCacheKeyConfigReceiptSnapshot } from "./src/prompt-cache-key-config.ts";
-import { formatOptimizerRuntimeMode, formatPersistentFeatureConfig, getOptimizerRuntimeModeLines, readPersistedFooterMode } from "./src/config.ts";
-import { FEATURE_COMMAND_MAP, getCacheOptimizerArgumentCompletions } from "./src/command-completion.ts";
+import { formatOptimizerRuntimeMode, getOptimizerRuntimeModeLines, readPersistedFooterMode } from "./src/config.ts";
+import { getCacheOptimizerArgumentCompletions } from "./src/command-completion.ts";
 import { MAX_PROVIDER_REQUEST_STATES, pruneProviderRequestStates, snapshotProviderRequestModel } from "./src/request-state.ts";
 import { NO_PROMPT_REWRITE_ENV } from "./src/config.ts";
 import { createCacheOptimizerCommandHandler } from "./src/command.ts";
@@ -50,37 +42,6 @@ import { type ProviderRequestState } from "./src/request-state.ts";
 
 const STATUS_KEY = "pi-cache-stats";
 
-type PersistedCacheStatsV2 = {
-  version: 2;
-  statsByProvider: Partial<Record<CacheProviderId, CacheStats>>;
-};
-
-type PersistedCacheStatsV3 = {
-  version: 3;
-  statsByModel: Record<string, CacheStats>;
-  legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
-};
-
-/**
- * V4 format: session-scoped stats buckets.
- * Each Pi process/session gets its own stats isolated by a hashed session id.
- *
- * sessions: sessionHash → modelKey (provider/id) → CacheStats
- * legacyFamily: unchanged from v3 (migration/fallback when ctx.model is unknown)
- */
-type PersistedCacheStatsV4 = {
-  version: 4;
-  sessions: Record<string, Record<string, CacheStats>>;
-  legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
-};
-
-type PersistedCacheStatsV5 = {
-  version: 5;
-  sessions: Record<string, Record<string, CacheStats>>;
-  legacyFamily: Partial<Record<CacheProviderId, CacheStats>>;
-  lastRoutedModelBySession?: Record<string, PersistedRoutedModelRef>;
-};
-
 function buildAdaptiveThinkingCompatWarningText(key: string, missing: string[]): string {
   const slashIdx = key.indexOf("/");
   const providerLabel = slashIdx > 0 ? key.slice(0, slashIdx) : key;
@@ -143,6 +104,11 @@ function notifyCacheCompatIfNeeded(
 // extension's public API; pi only invokes the default export below.
 export const __internals_for_tests = {
   getLastSkillCompressionOutcome,
+  decidePromptCacheRetention,
+  userRequestedLongCacheRetention,
+  derivePromptCacheKey,
+  withAnthropicCacheTtlRepair,
+  withoutPromptCacheRetention,
   describeSkillCompressionOutcome,
   stripSessionOverviewChurn,
   formatSkillsForPrompt,
@@ -966,11 +932,19 @@ export default function (pi: ExtensionAPI) {
    * The caller strips prompt_cache_retention when this returns false.
    */
   function hasExplicitLongRetentionOptIn(model: PiModel): boolean {
-    return hasExplicitLongRetentionOptInFromConfig(
+    // Pi's built-in catalog only ever sets supportsLongCacheRetention: false, so
+    // an explicit true on the runtime model (provider extension or merged
+    // models.json) is as deliberate as one read from models.json directly.
+    // A value resolved from models.json (modelOverrides > model > provider)
+    // still wins, so an explicit false there is never overridden.
+    const configured = resolveExplicitCompatValue(
       readEffectiveCompatConfig(),
       model.provider,
       model.id,
+      "supportsLongCacheRetention",
     );
+    if (configured !== undefined) return configured.value === true;
+    return asRecord(model.compat)?.supportsLongCacheRetention === true;
   }
 
   /**
@@ -1014,6 +988,11 @@ export default function (pi: ExtensionAPI) {
   });
 
   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
+    // a record consumed out of order) so they cannot be correlated with the
+    // next run's messages.
+    providerRequestStates.length = 0;
     await refreshShardAggregate();
     await publishStatus(ctx);
   });
@@ -1198,61 +1177,57 @@ export default function (pi: ExtensionAPI) {
       toolOrderChanged = normalized.changed;
     }
 
+    // Every mutation below works on a copy and is returned explicitly: Pi's
+    // event.payload is never modified in place, so the hook does not depend on
+    // the host honouring in-place edits.
+    let payloadChanged = toolOrderChanged;
+
     // Anthropic rejects mixed cache breakpoints when a 1h block appears after
     // a 5m/default block in wire order (tools → system → messages). Repair any
     // conflict visible in Pi's final payload immediately. Some proxies inject
     // hidden short breakpoints after this hook; only models that have actually
     // returned the explicit TTL-order error receive the process-local 5m fallback.
     if (requestModel && isAnthropicMessagesApi(requestModel.api)) {
-      const visibleConflictFixed = normalizeAnthropicCacheControlTtlOrder(requestPayload);
-      if (!visibleConflictFixed && anthropicTtlOrderErrorModels.has(modelKey(requestModel))) {
-        downgradeAnthropicLongCacheControls(requestPayload);
+      const repaired = withAnthropicCacheTtlRepair(requestPayload, anthropicTtlOrderErrorModels.has(modelKey(requestModel)));
+      if (repaired !== undefined) {
+        requestPayload = repaired;
+        payloadChanged = true;
       }
     }
 
-    // ── Safety: strip prompt_cache_retention from payload for models that
-    // are not authorised to send it. Pi defaults supportsLongCacheRetention
-    // to true for all openai-completions models, but most third-party APIs
-    // reject the parameter with 400 “Extra inputs are not permitted”.
-    //
-    // Gate order (first match wins):
-    //   1. Official OpenAI          → keep (trusted to support it)
-    //   2. 400 history              → strip (empirical evidence overrides user config)
-    //   3. Explicit opt-in in models.json → keep (user explicitly wants it)
-    //   4. Everything else          → strip (safe default for third-party APIs)
-    //
-    // Gate 2 before Gate 3 is critical: if a user explicitly opted in but
-    // the API returned 400, we must strip — otherwise the 400 repeats forever.
-    if (runtimeOptimizerEnabled) {
-      const payloadRecord = asRecord(requestPayload);
-      if (payloadRecord && typeof payloadRecord.prompt_cache_retention === "string") {
-        if (requestModel) {
-          if (isOfficialOpenAIBaseUrl(requestModel)) {
-            // Gate 1: Official OpenAI → keep
-          } else if (promptCacheRetention400Models.has(modelKey(requestModel))) {
-            // Gate 2: 400 history → strip (overrides user opt-in)
-            delete payloadRecord.prompt_cache_retention;
-          } else if (hasExplicitLongRetentionOptIn(requestModel)) {
-            // Gate 3: Explicit user opt-in → keep
-          } else {
-            // Gate 4: Safe default → strip
-            delete payloadRecord.prompt_cache_retention;
-          }
+    // prompt_cache_retention gate. This extension sets PI_CACHE_RETENTION=long,
+    // which makes Pi emit prompt_cache_retention: "24h" for every endpoint whose
+    // detected compat does not explicitly disable it, including third-party
+    // proxies that reject unknown fields with HTTP 400. The gate undoes only that
+    // side effect; see decidePromptCacheRetention for the order and reasons.
+    if (runtimeOptimizerEnabled && typeof asRecord(requestPayload)?.prompt_cache_retention === "string") {
+      const decision = decidePromptCacheRetention({
+        providerRejected: !!requestModel && promptCacheRetention400Models.has(modelKey(requestModel)),
+        officialOpenAI: !!requestModel && isOfficialOpenAIBaseUrl(requestModel),
+        explicitOptIn: !!requestModel && hasExplicitLongRetentionOptIn(requestModel),
+        userRequestedLong: userRequestedLongCacheRetention(),
+      });
+      recordPromptCacheRetentionDecision(requestModel ? modelKey(requestModel) : undefined, decision);
+      if (!decision.keep) {
+        const stripped = withoutPromptCacheRetention(requestPayload);
+        if (stripped !== undefined) {
+          requestPayload = stripped;
+          payloadChanged = true;
         }
       }
     }
 
     if (isPromptCacheKeyOmittedForModel(requestModel)) {
       const omitted = omitOpenAIPromptCacheKeys(requestPayload);
-      return omitted ?? (toolOrderChanged ? requestPayload : undefined);
+      return omitted ?? (payloadChanged ? requestPayload : undefined);
     }
 
     if (!shouldInjectOpenAIPromptCacheKey() || !shouldInjectOpenAIPromptCacheKeyForModel(requestModel)) {
-      return toolOrderChanged ? requestPayload : undefined;
+      return payloadChanged ? requestPayload : undefined;
     }
 
     const withCacheKey = addOpenAIPromptCacheKey(requestPayload, getSessionPromptCacheKey(ctx));
-    return withCacheKey ?? (toolOrderChanged ? requestPayload : undefined);
+    return withCacheKey ?? (payloadChanged ? requestPayload : undefined);
   });
 
   pi.on("after_provider_response", async (event, ctx) => {
@@ -1412,7 +1387,7 @@ export default function (pi: ExtensionAPI) {
       const errorModel = messageModel
         ? findModelInRegistry(ctx.modelRegistry, messageModel.provider, messageModel.id) ?? messageModel
         : undefined;
-      if (isReasoningProtocolRejectionForModel(event.message, errorModel)) {
+      if (errorModel && isReasoningProtocolRejectionForModel(event.message, errorModel)) {
         await notifyReasoningProtocolObservation(
           errorModel,
           ctx,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.8.20",
+  "version": "2.8.22",
   "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",
@@ -37,8 +37,8 @@
     "check:modules": "node scripts/check-module-graph.mjs"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.0.3",
-    "@earendil-works/pi-server": "1.0.3",
+    "@earendil-works/pi-coding-agent": "^1.1.0",
+    "@earendil-works/pi-server": "^1.1.0",
     "@types/node": "^22.0.0",
     "jiti": "^2.7.0",
     "typescript": "^5.8.3"

package/src/atomic-fs.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, copyFile, link, lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, link, lstat, mkdir, open, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { LOG_PREFIX, asRecord, getErrorCode, isProcessAlive } from "./common.ts";
 import { MODELS_TRANSACTION_LOCK_PATH, MODELS_TRANSACTION_LOCK_STALE_MS, MODELS_TRANSACTION_LOCK_WAIT_MS, STATE_DIR } from "./paths.ts";
 
@@ -25,6 +25,31 @@ export function uniqueTempPath(targetPath: string, purpose: string): string {
   return `${targetPath}.${process.pid}.${Date.now()}.${backupSequence++}.${purpose}.tmp`;
 }
 
+/**
+ * Create `path` exclusively (`wx`) and flush it to stable storage before the
+ * caller renames or links it into place, so a crash right after the commit
+ * cannot leave an empty or truncated models.json / config file.
+ */
+export async function writeFileExclusiveDurable(path: string, content: string, mode: number): Promise<void> {
+  const handle = await open(path, "wx", mode);
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Flush an already-written file (for example a copyFile result) to stable storage. */
+export async function syncFile(path: string): Promise<void> {
+  const handle = await open(path, "r+");
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
 export type FileIdentity = { dev: number | bigint; ino: number | bigint };
 
 export function sameFileIdentity(left: FileIdentity, right: FileIdentity): boolean {
@@ -80,7 +105,7 @@ export async function atomicReplaceTextFilePreservingMode(
   try {
     // `wx` makes the unique temporary path non-overwriting even if a hostile
     // or stale file appears between name generation and the write.
-    await writeFile(tempPath, content, { encoding: "utf8", mode, flag: "wx" });
+    await writeFileExclusiveDurable(tempPath, content, mode);
     const tempInfo = await lstat(tempPath);
     if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
       throw new Error("temporary replacement is not a regular file");
@@ -120,7 +145,7 @@ export async function atomicCreateTextFileNoReplace(
 ): Promise<void> {
   const tempPath = uniqueTempPath(targetPath, purpose);
   try {
-    await writeFile(tempPath, content, { encoding: "utf8", mode, flag: "wx" });
+    await writeFileExclusiveDurable(tempPath, content, mode);
     const tempInfo = await lstat(tempPath);
     if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
       throw new Error("temporary creation is not a regular file");
@@ -167,6 +192,7 @@ export async function atomicRestoreFileFromBackup(
   const tempPath = uniqueTempPath(targetPath, "restore");
   try {
     await copyFile(backupPath, tempPath, fsConstants.COPYFILE_EXCL);
+    await syncFile(tempPath);
     const tempInfo = await lstat(tempPath);
     if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) {
       throw new Error("temporary restore is not a regular file");

package/src/command.ts

@@ -1,6 +1,5 @@
 import { type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { readFile, rename } from "node:fs/promises";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
 import { selectAdapterForModel } from "./adapters.ts";
 import { backupTimestamp, hashText } from "./atomic-fs.ts";
 import { FEATURE_COMMAND_MAP } from "./command-completion.ts";
@@ -22,6 +21,7 @@ import { type ProviderRequestState } from "./request-state.ts";
 import { type CacheStats, type ShardAggregate } from "./stats-store.ts";
 import { type CacheUsageSample } from "./stats-report.ts";
 import { describeSkillCompressionOutcome } from "./prompt-rewrite.ts";
+import { describePromptCacheRetentionDecision, getLastPromptCacheRetentionDecision } from "./retention.ts";
 
 /**
  * Everything the command needs from the extension instance. The extension keeps this state in closures
@@ -72,7 +72,7 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
     sessionModelKey,
     syncSessionHash,
   } = runtime;
-  const { getCacheStatsTotalsByModel, getCurrentSessionHashSet, getCurrentSessionHash, getLastStatusText, clearLastStatusText } = runtime;
+  const { getCacheStatsTotalsByModel, getCurrentSessionHashSet, getCurrentSessionHash, clearLastStatusText } = runtime;
 
   return async function handleCacheOptimizerCommand(
     args: string,
@@ -110,7 +110,7 @@ export function createCacheOptimizerCommandHandler(runtime: CommandRuntime) {
         const samples = sk ? getRecentSamples(sk) : [];
         const lowHitLines = buildLowHitDiagnosis(model, adapter, statsState, samples);
         const routeNote = describeNativeVirtualRouteNote(selectedModel, model);
-        const fullDiagnosis = [routeNote, diagnosis, describeSkillCompressionOutcome(), ...lowHitLines].filter((line) => line !== undefined).join("\n");
+        const fullDiagnosis = [routeNote, diagnosis, describeSkillCompressionOutcome(), describePromptCacheRetentionDecision(getLastPromptCacheRetentionDecision()), ...lowHitLines].filter((line) => line !== undefined).join("\n");
         cmdCtx.ui.notify(fullDiagnosis, "info");
       } else if (subcommand === "stats") {
         const aggregate = await refreshShardAggregate();

package/src/compat-advice.ts

@@ -1,10 +1,8 @@
 import { type PiModel, isNonEmptyString, lower } from "./common.ts";
 import { isAdaptiveGenerationModel, isKimiCodingAdaptiveModel } from "./model-detect.ts";
 import { getCompat, isDeepSeekLikeModel, isKimiCodingEmptySignatureModel, isKnownThirdPartyOpenAIEndpoint, isOpenAICompatibleProxyApi, isOpenAIFamilyModel, isPiBuiltInLlamaCppModel, isRoutedFallbackModel } from "./model-identity.ts";
-import { MODELS_JSON_PATH, STATE_DIR } from "./paths.ts";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { homedir } from "node:os";
-import { join } from "node:path";
 
 /** Join display-only path fragments without resolving them for I/O. */
 export function joinDisplayPath(base: string, child: string, platform: string = process.platform): string {

package/src/compat-config.ts

@@ -1,4 +1,4 @@
-import { type PiModel, type UnknownRecord, asRecord, lower } from "./common.ts";
+import { type PiModel, type UnknownRecord, asRecord } from "./common.ts";
 
 export type CacheCompat = {
   supportsStore?: boolean;

package/src/diagnostics.ts

@@ -1,4 +1,3 @@
-import { join } from "node:path";
 import { type CacheProviderAdapter } from "./adapters.ts";
 import { type PiModel, type UnknownRecord, asRecord, isNonEmptyString, lower } from "./common.ts";
 import { type CompatAdvicePlacement, appendCredentialSafeProviderGuidance, appendDeepSeekCompatAdviceLines, appendOpenAIProxyCompatAdviceLines, buildDeepSeekCompatSuggestion, buildSafeOpenAIProxyCompatSuggestion, describeMissingCacheCompatForModel, getModelsJsonDisplayPath, isAdaptiveThinkingCompatApplicable, isDeepSeekWireCompatApplicable } from "./compat-advice.ts";
@@ -555,8 +554,6 @@ export function buildLowHitDiagnosis(
   const recent10 = samples.slice(-10);
   const recent10Hits = recent10.filter((s) => s.hit).length;
   const recent10Total = recent10.length;
-  const recent10Cached = recent10.reduce((sum, s) => sum + s.cachedInputTokens, 0);
-  const recent10Input = recent10.reduce((sum, s) => sum + s.totalInputTokens, 0);
 
   // 5. Today's overall trend from persisted stats
   const todayStats = stats ?? emptyCacheStats();
@@ -611,7 +608,6 @@ export function buildLowHitDiagnosis(
 
   // Priority 4: recent trend low
   if (recent10Total > 0) {
-    const hitRatio = recent10Input > 0 ? Math.round((recent10Cached / recent10Input) * 100) : 0;
     if (recent10Hits === 0 && todayStats.totalRequests > 3 && todayHitRatio < 30) {
       lines.push(`📉 Cache hit rate is low: ${todayHitRatio}% today (${recent10Total} recent samples).`);
       lines.push("   Likely causes: proxy routing to different backends per request,");

package/src/jsonc.ts

@@ -1,4 +1,3 @@
-import { join } from "node:path";
 
 // ── String-aware JSONC scanning primitives ─────────────────────────
 //

package/src/model-detect.ts

@@ -32,8 +32,10 @@ export function modelOrAssistantMessageHas(message: unknown, model: PiModel | un
  *   claude-opus-4-6, claude-opus-4-7, claude-opus-4-8 (also dotted 4.6/4.7/4.8)
  *   claude-sonnet-4-6, claude-sonnet-5
  *   claude-fable-5
+ *   claude-haiku-5-5 (Pi 1.1.0+)
  *
- * We match broadly: opus >= 4-6, sonnet >= 4-6, fable >= 5.
+ * We match broadly: opus >= 4-6, sonnet >= 4-6, fable >= 5, haiku >= 5
+ * (Pi's own Bedrock/Anthropic detection treats every haiku-5* as adaptive).
  * Ids may carry date-stamp or size suffixes like "[1M]".
  */
 export const ADAPTIVE_OPUS_PATTERN = /(^|[\/\s:_-])(opus-4[.-][6-9]|opus-4-[1-9][0-9]|opus-([5-9]|[1-9][0-9]))($|[-_.:\/\s\[])/i;
@@ -42,10 +44,12 @@ export const ADAPTIVE_SONNET_PATTERN = /(^|[\/\s:_-])(sonnet-4[.-][6-9]|sonnet-4
 
 export const ADAPTIVE_FABLE_PATTERN = /(^|[\/\s:_-])fable-([5-9]|[1-9][0-9])($|[-_.:\/\s\[])/i;
 
+export const ADAPTIVE_HAIKU_PATTERN = /(^|[\/\s:_-])haiku-([5-9]|[1-9][0-9])($|[-_.:\/\s\[])/i;
+
 export function isAdaptiveGenerationModel(model: PiModel | undefined): boolean {
   if (!model) return false;
   const tokens = getModelIdNameTokenValues(model);
-  return tokens.some((t) => ADAPTIVE_OPUS_PATTERN.test(t) || ADAPTIVE_SONNET_PATTERN.test(t) || ADAPTIVE_FABLE_PATTERN.test(t));
+  return tokens.some((t) => ADAPTIVE_OPUS_PATTERN.test(t) || ADAPTIVE_SONNET_PATTERN.test(t) || ADAPTIVE_FABLE_PATTERN.test(t) || ADAPTIVE_HAIKU_PATTERN.test(t));
 }
 
 export function isKimiCodingAdaptiveModel(model: PiModel | undefined): boolean {

package/src/models-json-fix.ts

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, copyFile, link, lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, link, lstat, mkdir, readFile, rename, unlink } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { type FileIdentity, atomicReplaceTextFilePreservingMode, atomicRestoreFileFromBackup, backupTimestamp, hashText, readRegularTextFile, sameFileIdentity, uniqueTempPath, validateAtomicTarget, withModelsJsonTransactionLock } from "./atomic-fs.ts";
+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";
@@ -1610,7 +1610,7 @@ export async function writeModelsJsonFixReceipt(
 
   const tempPath = uniqueTempPath(receiptPath, "receipt");
   try {
-    await writeFile(tempPath, JSON.stringify(receipt, null, 2) + "\n", { encoding: "utf8", mode, flag: "wx" });
+    await writeFileExclusiveDurable(tempPath, JSON.stringify(receipt, null, 2) + "\n", mode);
     const tempInfo = await lstat(tempPath);
     if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) throw new Error("invalid temporary fix receipt");
     await chmod(tempPath, mode);

package/src/prompt-cache-key-config.ts

@@ -1,12 +1,12 @@
-import { type FileIdentity, atomicCreateTextFileNoReplace, atomicReplaceTextFilePreservingMode, atomicRestoreFileFromBackup, backupTimestamp, hashText, sameFileIdentity, uniqueTempPath, validateAtomicTarget, withModelsJsonTransactionLock } from "./atomic-fs.ts";
+import { type FileIdentity, atomicCreateTextFileNoReplace, atomicReplaceTextFilePreservingMode, atomicRestoreFileFromBackup, backupTimestamp, hashText, sameFileIdentity, uniqueTempPath, validateAtomicTarget, withModelsJsonTransactionLock, writeFileExclusiveDurable } from "./atomic-fs.ts";
 import { LOG_PREFIX, type PiModel, asRecord, getErrorCode } from "./common.ts";
-import { CONFIG_FILE_PATH, type PersistedCacheOptimizerConfigV2, type PersistedCacheOptimizerConfigV3, normalizePersistedCacheOptimizerConfig, parsePersistedCacheOptimizerConfig } from "./config.ts";
+import { CONFIG_FILE_PATH, type PersistedCacheOptimizerConfigV3, normalizePersistedCacheOptimizerConfig, parsePersistedCacheOptimizerConfig } from "./config.ts";
 import { isReceiptTimestamp, isSafeReceiptText, isSha256 } from "./fix-types.ts";
 import { modelKey } from "./model-identity.ts";
 import { STATE_DIR } from "./paths.ts";
 import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { chmod, copyFile, link, lstat, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, link, lstat, mkdir, readFile, rename, unlink } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
 export const CONFIG_RECEIPT_FILE_NAME = "pi-cache-optimizer-config-receipt.json";
@@ -125,7 +125,7 @@ export async function writePromptCacheKeyConfigReceipt(
   }
   const tempPath = uniqueTempPath(receiptPath, "config-receipt");
   try {
-    await writeFile(tempPath, JSON.stringify(receipt, null, 2) + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await writeFileExclusiveDurable(tempPath, JSON.stringify(receipt, null, 2) + "\n", 0o600);
     const tempInfo = await lstat(tempPath);
     if (tempInfo.isSymbolicLink() || !tempInfo.isFile()) throw new Error("invalid temporary prompt-cache-key receipt");
     await chmod(tempPath, 0o600);
@@ -199,7 +199,7 @@ export async function applyPromptCacheKeyConfigFixUnderLock(
   const tempPath = uniqueTempPath(configPath, "config-fix");
   let committedInfo: Awaited<ReturnType<typeof lstat>> | undefined;
   try {
-    await writeFile(tempPath, modifiedText, { encoding: "utf8", mode, flag: "wx" });
+    await writeFileExclusiveDurable(tempPath, modifiedText, mode);
     await chmod(tempPath, mode);
     if (originalInfo) {
       await validateAtomicTarget(configPath, { identity: originalInfo, hash: beforeHash, mode });

package/src/prompt-rewrite.ts

@@ -1,5 +1,5 @@
 import { type BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname } from "node:path";
 import { NO_SKILL_COMPRESSION_ENV, featureEnabled } from "./config.ts";
 
 

package/src/provider-errors.ts

@@ -6,7 +6,6 @@ import { getAssistantRecord, getCompat, isDeepSeekLikeModel, isOfficialOpenAIBas
 import { isActionableModelsJsonFixReceipt, readModelsJsonFixReceipt } from "./models-json-fix.ts";
 import { firstNonEmptyString } from "./routing.ts";
 import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { join } from "node:path";
 
 export const ANTHROPIC_TTL_FALLBACK_SYMBOL = Symbol.for("pi.cache.optimizer.anthropic-ttl-fallback.v1");
 

package/src/request-payload.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { createHash } from "node:crypto";
 import { type PiModel, type UnknownRecord, asRecord, isNonEmptyString, lower } from "./common.ts";
 import { type CacheCompat, getEffectiveCompatSources, resolveEffectiveCompatFromConfig } from "./compat-config.ts";
 import { type PersistedCacheOptimizerConfig, type PersistedCacheOptimizerConfigV3, persistedCacheOptimizerConfig, runtimeOptimizerEnabled } from "./config.ts";
@@ -15,6 +15,19 @@ export function clampPromptCacheKey(key: string | undefined): string | undefined
   return chars.slice(0, OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH).join("");
 }
 
+/**
+ * Opaque, stable per-session identifier sent to providers and proxies for
+ * cache routing (`prompt_cache_key` and the session-affinity header bridge).
+ * The raw Pi session id never leaves the process: a one-way hash is just as
+ * stable for sticky routing and does not expose the local session identity to
+ * third-party endpoints.
+ */
+export function derivePromptCacheKey(sessionId: string | undefined): string | undefined {
+  const normalized = sessionId?.trim();
+  if (!normalized) return undefined;
+  return `pi-${createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 32)}`;
+}
+
 export function getEffectiveCompatValueSource(
   model: PiModel,
   config: unknown,
@@ -71,7 +84,8 @@ export function addEffectiveSessionAffinityHeaders(
       ? "openrouter"
       : "openai"
   );
-  const value = sessionId.trim();
+  const value = derivePromptCacheKey(sessionId);
+  if (!value) return false;
   let changed = false;
   if (format === "openrouter") {
     return setProviderHeaderIfMissing(headers, "x-session-id", value);
@@ -161,25 +175,68 @@ export function hasAnthropicCacheTtlOrderError(message: unknown): boolean {
     error.includes("must not come after");
 }
 
-export function normalizeAnthropicCacheControlTtlOrder(payload: unknown): boolean {
-  const controls = collectAnthropicCacheControlsInWireOrder(payload);
+/** Pure check: does the payload put a 1h breakpoint after a 5m/default one? */
+export function hasAnthropicCacheTtlOrderConflict(payload: unknown): boolean {
   let seenShort = false;
-  let hasInvalidLongAfterShort = false;
-
-  for (const control of controls) {
+  for (const control of collectAnthropicCacheControlsInWireOrder(payload)) {
     const ttl = control.ttl;
     if (ttl === undefined || ttl === "5m") {
       seenShort = true;
     } else if (ttl === "1h" && seenShort) {
-      hasInvalidLongAfterShort = true;
-      break;
+      return true;
     }
   }
-  if (!hasInvalidLongAfterShort) return false;
+  return false;
+}
+
+/** Pure check: does the payload carry any 1h breakpoint? */
+export function hasAnthropicLongCacheControl(payload: unknown): boolean {
+  return collectAnthropicCacheControlsInWireOrder(payload).some((control) => control.ttl === "1h");
+}
 
+/**
+ * In-place repair, kept for callers that own the object. The request hook uses
+ * {@link withAnthropicCacheTtlRepair}, which never mutates Pi's payload.
+ */
+export function normalizeAnthropicCacheControlTtlOrder(payload: unknown): boolean {
+  if (!hasAnthropicCacheTtlOrderConflict(payload)) return false;
   return downgradeAnthropicLongCacheControls(payload);
 }
 
+function clonePayload(payload: unknown): unknown {
+  try {
+    return structuredClone(payload);
+  } catch {
+    // Non-cloneable payloads are not produced by Pi's built-in transports; keep
+    // the request valid by falling back to a JSON round-trip.
+    return JSON.parse(JSON.stringify(payload));
+  }
+}
+
+/**
+ * Returns a repaired copy when the Anthropic payload needs its 1h breakpoints
+ * downgraded, or undefined when it is already valid. `forceDowngrade` applies
+ * the process-local fallback for models that already returned the TTL-order
+ * error (proxies may inject hidden short breakpoints after this hook).
+ */
+export function withAnthropicCacheTtlRepair(payload: unknown, forceDowngrade: boolean): unknown | undefined {
+  const needsRepair = hasAnthropicCacheTtlOrderConflict(payload) ||
+    (forceDowngrade && hasAnthropicLongCacheControl(payload));
+  if (!needsRepair) return undefined;
+  const copy = clonePayload(payload);
+  downgradeAnthropicLongCacheControls(copy);
+  return copy;
+}
+
+/** Returns a copy without `prompt_cache_retention`, or undefined when absent. */
+export function withoutPromptCacheRetention(payload: unknown): unknown | undefined {
+  const record = asRecord(payload);
+  if (!record || !Object.prototype.hasOwnProperty.call(record, "prompt_cache_retention")) return undefined;
+  const copy = { ...record };
+  delete copy.prompt_cache_retention;
+  return copy;
+}
+
 export function addOpenAIPromptCacheKey(payload: unknown, cacheKey: string | undefined): unknown | undefined {
   const record = asRecord(payload);
   const normalizedCacheKey = clampPromptCacheKey(cacheKey);

package/src/retention.ts

@@ -37,6 +37,87 @@ export function restoreCacheRetentionEnv(snapshot: CacheRetentionEnvSnapshot, en
   }
 }
 
+/**
+ * Why `prompt_cache_retention` was kept on, or removed from, a provider payload.
+ *
+ * - `provider-rejected`: this model already answered with an explicit
+ *   unsupported-parameter error in this process; never resend it.
+ * - `official-openai`: api.openai.com documents the parameter.
+ * - `explicit-opt-in`: models.json or the runtime model compat explicitly sets
+ *   `supportsLongCacheRetention: true` (Pi's built-in catalog only ever sets
+ *   `false`, so `true` is always a deliberate choice).
+ * - `user-requested-long`: the user started Pi with `PI_CACHE_RETENTION=long`
+ *   themselves, so the field is vanilla Pi behaviour, not an optimizer side effect.
+ * - `unverified-endpoint`: the field exists only because this extension forced
+ *   `PI_CACHE_RETENTION=long`; third-party endpoints (including Azure, whose
+ *   support is per deployed model) are not known to accept it.
+ */
+export type PromptCacheRetentionGateReason =
+  | "provider-rejected"
+  | "official-openai"
+  | "explicit-opt-in"
+  | "user-requested-long"
+  | "unverified-endpoint";
+
+export type PromptCacheRetentionGateInput = {
+  providerRejected: boolean;
+  officialOpenAI: boolean;
+  explicitOptIn: boolean;
+  userRequestedLong: boolean;
+};
+
+export type PromptCacheRetentionGateDecision = {
+  keep: boolean;
+  reason: PromptCacheRetentionGateReason;
+};
+
+/**
+ * Pure decision for the `prompt_cache_retention` gate. The optimizer only undoes
+ * its own side effect: it never strips a field the user or the provider config
+ * asked for, except after the provider has explicitly rejected it.
+ */
+export function decidePromptCacheRetention(input: PromptCacheRetentionGateInput): PromptCacheRetentionGateDecision {
+  if (input.providerRejected) return { keep: false, reason: "provider-rejected" };
+  if (input.officialOpenAI) return { keep: true, reason: "official-openai" };
+  if (input.explicitOptIn) return { keep: true, reason: "explicit-opt-in" };
+  if (input.userRequestedLong) return { keep: true, reason: "user-requested-long" };
+  return { keep: false, reason: "unverified-endpoint" };
+}
+
+/** True when PI_CACHE_RETENTION=long was already set before this extension loaded. */
+export function userRequestedLongCacheRetention(snapshot: CacheRetentionEnvSnapshot = STARTUP_CACHE_RETENTION_ENV): boolean {
+  return snapshot.wasSet && snapshot.value === LONG_CACHE_RETENTION_VALUE;
+}
+
+export type PromptCacheRetentionDecisionRecord = PromptCacheRetentionGateDecision & {
+  modelKey?: string;
+  at: number;
+};
+
+let lastPromptCacheRetentionDecision: PromptCacheRetentionDecisionRecord | undefined;
+
+/** Remember the latest gate decision so `/cache-optimizer doctor` can explain it. */
+export function recordPromptCacheRetentionDecision(modelKey: string | undefined, decision: PromptCacheRetentionGateDecision): void {
+  lastPromptCacheRetentionDecision = { ...decision, modelKey, at: Date.now() };
+}
+
+export function getLastPromptCacheRetentionDecision(): PromptCacheRetentionDecisionRecord | undefined {
+  return lastPromptCacheRetentionDecision ? { ...lastPromptCacheRetentionDecision } : undefined;
+}
+
+const PROMPT_CACHE_RETENTION_REASON_TEXT: Record<PromptCacheRetentionGateReason, string> = {
+  "provider-rejected": "removed: this model rejected the parameter earlier in this process",
+  "official-openai": "kept: official OpenAI endpoint",
+  "explicit-opt-in": "kept: supportsLongCacheRetention: true is set explicitly",
+  "user-requested-long": "kept: PI_CACHE_RETENTION=long was set before Pi started",
+  "unverified-endpoint": "removed: added only by the optimizer and the endpoint is not known to accept it (set supportsLongCacheRetention: true to opt in)",
+};
+
+export function describePromptCacheRetentionDecision(record: PromptCacheRetentionDecisionRecord | undefined): string | undefined {
+  if (!record) return undefined;
+  return `prompt_cache_retention ${PROMPT_CACHE_RETENTION_REASON_TEXT[record.reason]}${record.modelKey ? ` (${record.modelKey})` : ""}`;
+}
+
 export function isCacheRetentionBaselineV1(value: unknown): value is CacheRetentionBaselineV1 {
   if (typeof value !== "object" || value === null) return false;
   const record = value as { version?: unknown; snapshot?: unknown };

package/src/routing.ts

@@ -2,7 +2,7 @@ import { LOG_PREFIX, type PiModel, asRecord, getNumber, isNonEmptyString, lower
 import { findLastExactModelDefinition } from "./compat-config.ts";
 import { VIRTUAL_REWRITE_ENV, featureEnabled } from "./config.ts";
 import { ROUTED_FALLBACK_MODEL_SYMBOL, getAssistantRecord, isNativeVirtualModel, isResponsesPromptRewriteBypassApi, modelKey, readEffectiveCompatConfig } from "./model-identity.ts";
-import { clampPromptCacheKey } from "./request-payload.ts";
+import { derivePromptCacheKey } from "./request-payload.ts";
 import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { createHash } from "node:crypto";
 
@@ -229,8 +229,8 @@ export function resolveNativeVirtualCandidateModels(
   model: PiModel | undefined,
   ctx?: ContextWithOptionalModelRegistry,
 ): PiModel[] | undefined {
-  if (!isNativeVirtualModel(model)) return undefined;
-  const adapter = model ? getRoutingRegistry()?.getRouter(model.provider) : undefined;
+  if (!model || !isNativeVirtualModel(model)) return undefined;
+  const adapter = getRoutingRegistry()?.getRouter(model.provider);
   if (!adapter?.resolveCandidateRoutes) return undefined;
 
   try {
@@ -527,7 +527,7 @@ export type PiCacheHintSnapshot = PiCacheHintsInput & PiCacheHintsOutput & {
 };
 
 export function getSessionPromptCacheKey(ctx: ExtensionContext): string | undefined {
-  return clampPromptCacheKey(ctx.sessionManager.getSessionId());
+  return derivePromptCacheKey(ctx.sessionManager.getSessionId());
 }
 
 export function isCacheHintsServiceV1(value: unknown): value is PiCacheHintsV1 {

package/src/stats-report.ts

@@ -7,7 +7,6 @@ import { CACHE_PROVIDER_IDS, type CacheProviderId, type CacheStats, LEGACY_STATE
 import { usageRecordFromAssistant } from "./usage.ts";
 import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 
 export type CacheStatsState = {
   statsByModel: Record<string, CacheStats>;
@@ -138,7 +137,6 @@ export function formatRecentTrendSummary(samples: CacheUsageSample[], maxCount:
   const totalInput = recent.reduce((sum, s) => sum + s.totalInputTokens, 0);
   const missingCount = recent.filter((s) => s.missingUsageFields).length;
 
-  const hitRatio = formatHitRatio(hits, recent.length);
   const tokenRatio = totalInput > 0 ? formatHitRatio(totalCached, totalInput) : "N/A";
 
   let result = `Recent ${recent.length}/${maxCount}: ${hits}/${recent.length} hits · ${tokenRatio} tok cached`;

package/src/stats-store.ts

@@ -331,8 +331,36 @@ export function parsePersistedStatsShardV7(value: unknown): PersistedStatsShardV
 export async function writeStatsShardV7(path: string, shard: PersistedStatsShardV7): Promise<void> {
   await mkdir(dirname(path), { recursive: true });
   const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
-  await writeFile(tempPath, JSON.stringify(shard, null, 2) + "\n", "utf8");
-  await rename(tempPath, path);
+  try {
+    await writeFile(tempPath, JSON.stringify(shard, null, 2) + "\n", "utf8");
+    await rename(tempPath, path);
+  } catch (error) {
+    // Do not leave an orphaned temp file behind until the next cleanup pass.
+    await unlink(tempPath).catch(() => undefined);
+    throw error;
+  }
+}
+
+type CachedShardRead = {
+  ino: number | bigint;
+  size: number;
+  mtimeMs: number;
+  shard: PersistedStatsShardV7 | undefined;
+};
+
+/**
+ * Parsed-shard cache keyed by path and validated by inode, size, and mtime.
+ * Writers always publish through temp-file + rename, so an updated shard gets
+ * a new inode; unchanged shards are not re-read or re-parsed on every refresh.
+ */
+const shardReadCache = new Map<string, CachedShardRead>();
+
+export function clearStatsShardReadCache(): void {
+  shardReadCache.clear();
+}
+
+function cloneShard(shard: PersistedStatsShardV7): PersistedStatsShardV7 {
+  return structuredClone(shard);
 }
 
 export async function readValidStatsShardsV7(directory: string = SHARD_FILES_DIR): Promise<PersistedStatsShardV7[]> {
@@ -344,20 +372,39 @@ export async function readValidStatsShardsV7(directory: string = SHARD_FILES_DIR
     throw error;
   }
   const shards: PersistedStatsShardV7[] = [];
+  const seenPaths = new Set<string>();
   for (const name of names) {
     if (!/^[0-9a-f-]+\.json$/i.test(name)) continue;
     const path = join(directory, name);
+    seenPaths.add(path);
     try {
       const info = await lstat(path);
-      if (!info.isFile() || info.isSymbolicLink()) continue;
-      const parsed = parsePersistedStatsShardV7(JSON.parse(await readFile(path, "utf8")));
-      const filenameInstanceId = name.slice(0, -".json".length);
-      if (parsed && parsed.instanceId === filenameInstanceId) shards.push(parsed);
+      if (!info.isFile() || info.isSymbolicLink()) {
+        shardReadCache.delete(path);
+        continue;
+      }
+      const cached = shardReadCache.get(path);
+      let parsed: PersistedStatsShardV7 | undefined;
+      if (cached && cached.ino === info.ino && cached.size === info.size && cached.mtimeMs === info.mtimeMs) {
+        parsed = cached.shard;
+      } else {
+        const filenameInstanceId = name.slice(0, -".json".length);
+        const candidate = parsePersistedStatsShardV7(JSON.parse(await readFile(path, "utf8")));
+        parsed = candidate && candidate.instanceId === filenameInstanceId ? candidate : undefined;
+        shardReadCache.set(path, { ino: info.ino, size: info.size, mtimeMs: info.mtimeMs, shard: parsed });
+      }
+      // Callers may mutate the aggregate they build; hand out copies so the
+      // cache stays authoritative.
+      if (parsed) shards.push(cloneShard(parsed));
     } catch {
       // Ignore malformed or transiently unavailable shards. Atomic writers will
       // publish a complete replacement on the next successful update.
+      shardReadCache.delete(path);
     }
   }
+  for (const path of Array.from(shardReadCache.keys())) {
+    if (!seenPaths.has(path) && path.startsWith(directory)) shardReadCache.delete(path);
+  }
   return shards;
 }
 

package/src/tool-ordering.ts

@@ -15,7 +15,7 @@ export function isKnownToolOrderApi(api: unknown): api is ToolOrderApi {
     api === "google-vertex" || api === "bedrock-converse-stream";
 }
 
-export function isToolOrderingEligibleModel(model: PiModel | undefined): boolean {
+export function isToolOrderingEligibleModel(model: PiModel | undefined): model is PiModel {
   // Responses/Codex prompt bypasses remain untouched. The pure helper still
   // supports the verified Responses shape for fixture use, but the request
   // hook must preserve Pi's server-managed/safety-sensitive bypass.