pi-cache-optimizer 2.8.19 → 2.8.21

package/README.md

@@ -35,7 +35,7 @@ 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.
 - Stores cache statistics in per-extension-instance atomic shards, so parent sessions, child Pi agents, and parallel Pi processes cannot overwrite one another.
@@ -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.2. 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.2's engine requirement.
+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.
 
 ## Commands
 
@@ -156,9 +156,9 @@ The explicit setting is stored in `pi-cache-optimizer-config.json` under Pi's ag
 
 ## Per-model `prompt_cache_key` opt-out
 
-Some OpenAI-compatible Completions endpoints reject `prompt_cache_key` with HTTP 400 even though the same field is valid for other providers. Pi 1.0.2 owns the key for Responses/Codex transports; this extension's key opt-out and fallback apply only to `openai-completions`. Pi 1.0.2 has no native `supportsPromptCacheKey` compat field; do **not** add that unknown field to `models.json`. `supportsLongCacheRetention` is not an equivalent switch and should not be used for this purpose.
+Some OpenAI-compatible Completions endpoints reject `prompt_cache_key` with HTTP 400 even though the same field is valid for other providers. Pi 1.0.3 owns the key for Responses/Codex transports; this extension's key opt-out and fallback apply only to `openai-completions`. Pi 1.0.3 has no native `supportsPromptCacheKey` compat field; do **not** add that unknown field to `models.json`. `supportsLongCacheRetention` is not an equivalent switch and should not be used for this purpose.
 
-When the extension observes an explicit field-level `prompt_cache_key` unsupported error for the exact provider/model, ordinary `/cache-optimizer fix` offers a confirmed model-scoped repair. Value-validation failures and conditional restrictions such as “not allowed when temperature is set” do not qualify. If concurrent responses from different models cannot be correlated because Pi provides no request ID, header-only evidence is ignored unless the finalized assistant message supplies exact provider/model identity. If you already know that the endpoint rejects the field, use the explicit command:
+When the extension observes an explicit field-level `prompt_cache_key` unsupported error for the exact provider/model (including recognized Chinese-localized forms such as `未知请求字段：prompt_cache_key`), ordinary `/cache-optimizer fix` offers a confirmed model-scoped repair. Value-validation failures and conditional restrictions such as “not allowed when temperature is set” do not qualify. If concurrent responses from different models cannot be correlated because Pi provides no request ID, header-only evidence is ignored unless the finalized assistant message supplies exact provider/model identity. If you already know that the endpoint rejects the field, use the explicit command:
 
 ```text
 /cache-optimizer fix prompt-cache-key
@@ -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:
 
@@ -196,7 +196,7 @@ Notes:
 
 - `sendSessionAffinityHeaders: true` is the safe default when your proxy supports sticky routing.
 - `supportsLongCacheRetention: true` is optional. Add it only when the endpoint explicitly supports OpenAI long prompt cache retention.
-- Do not add `supportsPromptCacheKey` to `models.json`: Pi 1.0.2 does not define that compat field. Use `/cache-optimizer fix prompt-cache-key` to store an exact provider/model omit rule in the extension-owned config; it removes both key spellings, including a key supplied by Pi.
+- Do not add `supportsPromptCacheKey` to `models.json`: Pi 1.0.3 does not define that compat field. Use `/cache-optimizer fix prompt-cache-key` to store an exact provider/model omit rule in the extension-owned config; it removes both key spellings, including a key supplied by Pi.
 - If you see `400 Unsupported parameter: prompt_cache_retention`, remove/avoid `supportsLongCacheRetention` for that channel. Keep `sendSessionAffinityHeaders` if supported. The extension detects the explicit error from response headers or the finalized assistant error message and strips the parameter from subsequent requests in the current process.
 - Use `/cache-optimizer compat` or `/cache-optimizer doctor` to see model-specific advice.
 - DeepSeek model names select the `DS cache` adapter only; they do not prove a reasoning wire protocol. Generic cache/routing advice remains active for absent or non-DeepSeek formats. DeepSeek replay advice is shown only when effective `compat.thinkingFormat: "deepseek"` is explicitly configured; it never treats `thinkingFormat` as a missing fix key.
@@ -354,7 +354,7 @@ Pi's model-family name and its reasoning wire protocol are separate. A DeepSeek-
 The novice-safe workflow is staged:
 
 1. Run `/cache-optimizer fix` for protocol-neutral cache/routing repairs such as session affinity. It shows the exact placement and requires confirmation.
-2. Make a normal request. If an OpenAI-compatible DeepSeek-like model explicitly rejects the `thinking` parameter in favor of `reasoning_effort`, the extension keeps only a model-scoped, process-local category. It does not persist or display the complete provider error, send a hidden probe, or edit configuration from a response hook.
+2. Make a normal request. If an OpenAI-compatible DeepSeek-like model explicitly rejects the `thinking` parameter in favor of `reasoning_effort` (including recognized Chinese-localized rejection and recommendation text), the extension keeps only a model-scoped, process-local category. It does not persist or display the complete provider error, send a hidden probe, or edit configuration from a response hook.
 3. Run `/cache-optimizer fix` again to review an evidence-based model-level protocol repair. It is written through the highest-precedence `modelOverrides[modelId].compat` layer and validated against runtime compat, so an extension-provided model cannot silently shadow it. A provider-level change is never broadened from a model name alone. Explicit `openai`, `qwen`, `openrouter`, and `together` formats remain respected.
 4. If the latest confirmed fix caused the problem, run `/cache-optimizer rollback`. Rollback always requires UI confirmation.
 

package/README.zh-CN.md

@@ -35,7 +35,7 @@
 
 - 将 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。
 - 使用每个 extension instance 独占的原子 shard 保存缓存统计，避免父会话、子 Pi agent 和并行 Pi 进程互相覆盖。
@@ -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.2 验证。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.2 的 engine 要求一致。
+本扩展要求 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 要求一致。
 
 ## 命令
 
@@ -156,9 +156,9 @@ Footer 默认使用 `session`，避免另一个并行 Pi 终端使用相同 prov
 
 ## 按模型关闭 `prompt_cache_key`
 
-某些 OpenAI-compatible Completions endpoint 会因 `prompt_cache_key` 返回 HTTP 400，但同一个字段对其他 provider 可能有效。Pi 1.0+ 已负责 Responses/Codex transport 的 key；本扩展的 fallback 和 opt-out 只作用于 `openai-completions`。Pi 1.0.2 没有原生的 `supportsPromptCacheKey` compat 字段，**不要**把这个未知字段加入 `models.json`。`supportsLongCacheRetention` 也不是等价开关，不应借用来实现此目的。
+某些 OpenAI-compatible Completions endpoint 会因 `prompt_cache_key` 返回 HTTP 400，但同一个字段对其他 provider 可能有效。Pi 1.0+ 已负责 Responses/Codex transport 的 key；本扩展的 fallback 和 opt-out 只作用于 `openai-completions`。Pi 1.0.3 没有原生的 `supportsPromptCacheKey` compat 字段，**不要**把这个未知字段加入 `models.json`。`supportsLongCacheRetention` 也不是等价开关，不应借用来实现此目的。
 
-当扩展观察到精确 provider/model 对 `prompt_cache_key` 的明确字段级拒绝后，普通 `/cache-optimizer fix` 会提供经过确认的模型级修复。参数值校验失败，以及“设置 temperature 时不允许”这类条件限制都不构成证据。若不同模型的响应并发交错，而 Pi 又没有提供 request ID，扩展会忽略无法安全关联的 response-header 证据；只有最终 assistant message 提供精确 provider/model 身份时才恢复归因。如果你已经确定 endpoint 不支持该字段，可以主动执行：
+当扩展观察到精确 provider/model 对 `prompt_cache_key` 的明确字段级拒绝后（包括 `未知请求字段：prompt_cache_key` 这类已识别的中文错误），普通 `/cache-optimizer fix` 会提供经过确认的模型级修复。参数值校验失败，以及“设置 temperature 时不允许”这类条件限制都不构成证据。若不同模型的响应并发交错，而 Pi 又没有提供 request ID，扩展会忽略无法安全关联的 response-header 证据；只有最终 assistant message 提供精确 provider/model 身份时才恢复归因。如果你已经确定 endpoint 不支持该字段，可以主动执行：
 
 ```text
 /cache-optimizer fix prompt-cache-key
@@ -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.2 没有原生的 `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：
 
@@ -196,7 +196,7 @@ Pi 0.84.1 还修复了内置 Fireworks 渠道对拒绝 `prompt_cache_retention`
 
 - `sendSessionAffinityHeaders: true` 是安全默认项，前提是你的代理支持 sticky routing。
 - `supportsLongCacheRetention: true` 是可选项。只有 endpoint 明确支持 OpenAI long prompt cache retention 时才添加。
-- 不要把 `supportsPromptCacheKey` 加入 `models.json`：Pi 1.0.2 没有定义这个 compat 字段。请使用 `/cache-optimizer fix prompt-cache-key` 在扩展自有配置中保存精确 provider/model 的 omit 规则；它会移除两种 key 写法，包括 Pi 提供的 key。
+- 不要把 `supportsPromptCacheKey` 加入 `models.json`：Pi 1.0.3 没有定义这个 compat 字段。请使用 `/cache-optimizer fix prompt-cache-key` 在扩展自有配置中保存精确 provider/model 的 omit 规则；它会移除两种 key 写法，包括 Pi 提供的 key。
 - 如果出现 `400 Unsupported parameter: prompt_cache_retention`，请为该渠道移除 / 避免 `supportsLongCacheRetention`；如支持，可保留 `sendSessionAffinityHeaders`。扩展会从响应头或最终 assistant error message 中识别这条明确错误，并在当前进程的后续请求中移除该参数。
 - 使用 `/cache-optimizer compat` 或 `/cache-optimizer doctor` 查看当前模型的具体建议。
 - DeepSeek 模型名只用于选择 `DS cache` adapter，不能证明 reasoning wire protocol。缺少或使用非 DeepSeek format 时仍保留通用缓存 / 路由建议；只有 effective `compat.thinkingFormat: "deepseek"` 被明确配置时，才显示 DeepSeek replay 建议，且不会把 `thinkingFormat` 列为缺失修复项。
@@ -353,7 +353,7 @@ Pi Cache Optimizer 按 Pi 的优先级解析有效 compat（`provider.compat`
 面向新手的安全流程是分阶段的：
 
 1. 先运行 `/cache-optimizer fix`，只处理协议无关的缓存 / 路由修复，例如 session affinity；命令会展示具体位置并要求确认。
-2. 发起一次普通请求。如果 OpenAI-compatible 的 DeepSeek-like 模型明确拒绝 `thinking` 并要求使用 `reasoning_effort`，扩展只在当前进程保留 model-scoped 分类，不会持久化或显示完整错误，不会发送隐藏探测请求，也不会在 response hook 中自动修改配置。
+2. 发起一次普通请求。如果 OpenAI-compatible 的 DeepSeek-like 模型明确拒绝 `thinking` 并要求使用 `reasoning_effort`（包括已识别的中文拒绝和建议文本），扩展只在当前进程保留 model-scoped 分类，不会持久化或显示完整错误，不会发送隐藏探测请求，也不会在 response hook 中自动修改配置。
 3. 再次运行 `/cache-optimizer fix`，查看基于证据的 model-level 协议修复；该修复写入最高优先级的 `modelOverrides[modelId].compat`，并结合 runtime compat 自检，避免 extension-provided model 静默遮挡。不会仅凭共享 provider 或模型名字扩大修改范围，显式 `openai`、`qwen`、`openrouter`、`together` format 会被尊重。
 4. 如果最近一次已确认修复导致问题，运行 `/cache-optimizer rollback`；回滚始终需要 UI 确认。
 

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,
@@ -197,6 +163,7 @@ export const __internals_for_tests = {
   isOpenAISdkHeader403Applicable,
   hasPromptCacheRetentionUnsupportedSignal,
   hasPromptCacheRetentionUnsupportedErrorMessage,
+  hasPromptCacheKeyUnsupportedText,
   hasPromptCacheKeyUnsupportedSignal,
   hasPromptCacheKeyUnsupportedErrorMessage,
   isPromptCacheKeyUnsupportedApplicable,
@@ -965,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;
   }
 
   /**
@@ -1013,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);
   });
@@ -1197,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) => {
@@ -1411,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.19",
+  "version": "2.8.21",
   "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.2",
-    "@earendil-works/pi-server": "1.0.2",
+    "@earendil-works/pi-coding-agent": "^1.0.3",
+    "@earendil-works/pi-server": "1.0.3",
     "@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/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");
 
@@ -84,6 +83,15 @@ export function hasPromptCacheRetentionUnsupportedErrorMessage(message: unknown)
     hasPromptCacheRetentionUnsupportedText(record.errorMessage);
 }
 
+// A Chinese rejection must start a diagnostic clause, not occur inside a
+// negation or condition. Keep comma-separated conditions in the same sentence.
+function hasChineseRejectionContext(value: string, index: number): boolean {
+  const prefix = value.slice(0, index).split(/[;!\n。；！]/).at(-1) ?? "";
+  const suffix = value.slice(index).split(/[;!\n。；！]/)[0];
+  return !/(?:如果|若|当|仅在|只有|模式下|情况下|设置.{0,40}时)/.test(prefix + suffix) &&
+    !/(?:并非|并不|并未|不是)/.test(prefix);
+}
+
 export function hasPromptCacheKeyUnsupportedText(value: unknown): boolean {
   const normalized = lower(value)
     .replace(/["'`]/g, "")
@@ -98,11 +106,13 @@ export function hasPromptCacheKeyUnsupportedText(value: unknown): boolean {
   // Keep this deliberately grammar-bound. A rejected value or a conditional
   // restriction (for example, "not allowed when temperature is set") is not
   // proof that the endpoint lacks support for the field itself.
-  const terminal = String.raw`(?=$|[}\]>,.;])`;
+  const terminal = String.raw`(?=$|[}\]>,.;，。；])`;
   return (
     new RegExp(String.raw`(?:unsupported|unknown|unrecognized|unexpected)\s+${field}\s*[:=]?\s*${key}${terminal}`).test(normalized) ||
     new RegExp(String.raw`(?:extra\s+inputs?|${field}\s+not\s+(?:allowed|permitted|supported))\s*[:=]\s*${key}${terminal}`).test(normalized) ||
-    new RegExp(String.raw`${key}(?:\s+${field})?\s*[:=]?\s*(?:is\s+)?${unsupported}${terminal}`).test(normalized)
+    new RegExp(String.raw`${key}(?:\s+${field})?\s*[:=]?\s*(?:is\s+)?${unsupported}${terminal}`).test(normalized) ||
+    Array.from(normalized.matchAll(new RegExp(String.raw`(?:^|[^a-z0-9_\u4e00-\u9fff])(?:未知|未识别|不支持|不允许)(?:请求)?(?:字段|参数)\s*[：:]\s*${key}${terminal}`, "g")))
+      .some((match) => hasChineseRejectionContext(normalized, match.index))
   );
 }
 
@@ -126,6 +136,15 @@ export function hasReasoningProtocolRejectionText(value: unknown): boolean {
     /(?:^|[^a-z0-9_])(?:unsupported|unknown|unrecognized|invalid|disallowed|rejected|not\s+(?:a\s+)?valid|not\s+accepted|not\s+allowed|not\s+permitted)(?:[_ ](?:parameter|field|argument))?\s*[:=]?\s*["'`]?thinking["'`]?(?![a-z0-9_])/,
     /(?:^|[^a-z0-9_])(?:extra\s+inputs?|additional\s+(?:inputs?|parameters?))\s+(?:are\s+)?(?:not permitted|not allowed|unsupported)\s*[:=]?\s*["'`]?thinking["'`]?(?![a-z0-9_])/,
   ];
+  const chineseStart = String.raw`(?:^|[^a-z0-9_\u4e00-\u9fff])`;
+  const chineseEnd = String.raw`(?=\s*(?:$|["'\x60}\]>,.;!?，。；！？]))`;
+  const chineseRejection = String.raw`(?:未知|未识别|无法识别|不支持|不被支持|不允许|不被允许|不接受|不被接受|无效|不合法|拒绝|被拒绝)`;
+  const chineseThinking = String.raw`["'\x60]?thinking["'\x60]?`;
+  const chinesePatterns = [
+    new RegExp(String.raw`${chineseStart}${chineseRejection}(?:请求)?(?:参数|字段)\s*[：:]?\s*${chineseThinking}${chineseEnd}`, "g"),
+    new RegExp(String.raw`${chineseStart}${chineseRejection}\s*${chineseThinking}(?:\s*(?:请求)?(?:参数|字段))?${chineseEnd}`, "g"),
+    new RegExp(String.raw`${chineseStart}${chineseThinking}\s*(?:(?:请求)?(?:参数|字段)\s*)?${chineseRejection}${chineseEnd}`, "g"),
+  ];
   let rejectionEnd = -1;
   for (const pattern of thinkingParameterRejectionPatterns) {
     const match = pattern.exec(normalized);
@@ -133,6 +152,13 @@ export function hasReasoningProtocolRejectionText(value: unknown): boolean {
       rejectionEnd = match.index + match[0].length;
     }
   }
+  for (const pattern of chinesePatterns) {
+    for (const match of normalized.matchAll(pattern)) {
+      if (hasChineseRejectionContext(normalized, match.index)) {
+        rejectionEnd = Math.max(rejectionEnd, match.index + match[0].length);
+      }
+    }
+  }
   if (rejectionEnd < 0) return false;
 
   // The provider must direct the caller to reasoning_effort after the
@@ -142,7 +168,7 @@ export function hasReasoningProtocolRejectionText(value: unknown): boolean {
   const recommendation = normalized.slice(rejectionEnd, rejectionEnd + 260);
   if (!/\breasoning[_\.]effort\b/.test(recommendation)) return false;
 
-  const recommendationClauses = recommendation.split(/[.;!?\n]/);
+  const recommendationClauses = recommendation.split(/[.;!?\n，。；！？]/);
   return recommendationClauses.some((clause) => {
     if (!/\breasoning[_\.]effort\b/.test(clause)) return false;
     // A target mentioned inside a negated/disabled clause is not positive
@@ -150,7 +176,9 @@ export function hasReasoningProtocolRejectionText(value: unknown): boolean {
     if (
       /\b(?:do\s+not|don't|never|avoid)\s+(?:use|set|send|pass|provide)?\s*["'`]?reasoning[_\.]effort\b/.test(clause) ||
       /\breasoning[_\.]effort\b[^.;]{0,80}\b(?:must|should|may|do)\s+(?:not|never)\b/.test(clause) ||
-      /\breasoning[_\.]effort\b[^.;]{0,80}\b(?:unsupported|disabled|unavailable|not\s+(?:supported|accepted|allowed|available|enabled|required|recommended|expected))\b/.test(clause)
+      /\breasoning[_\.]effort\b[^.;]{0,80}\b(?:unsupported|disabled|unavailable|not\s+(?:supported|accepted|allowed|available|enabled|required|recommended|expected))\b/.test(clause) ||
+      /(?:请)?(?:不要|勿|不应|不该|不得|不可|不能|不建议|不推荐|禁止|无需|不必|不需要)\s*(?:再)?(?:使用|设置|发送|传入|提供|改用|采用|把)?\s*(?:参数\s*)?["'`]?reasoning[_\.]effort\b/.test(clause) ||
+      /\breasoning[_\.]effort\b[^.;，。；！？]{0,80}(?:不支持|不允许|不可用|不接受|不能|不建议|不推荐|不需要|无需|不必|不得|不应|不该|禁止)/.test(clause)
     ) return false;
 
     return [
@@ -159,6 +187,9 @@ export function hasReasoningProtocolRejectionText(value: unknown): boolean {
       /(?:parameter|field|option)\s+(?:is|should be)\s+["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
       /instead[^.;]{0,120}(?:use|try|set|send|pass|provide)\s+(?:the\s+)?["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
       /(?:replace|change|switch)\s+(?:the\s+)?["'`]?thinking["'`]?\s+(?:with|to)\s+["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
+      /(?:请)?(?:使用|改用|采用|设置|发送|传入|提供|切换到|改为|用)\s*(?:参数\s*)?["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
+      /(?:将|把)\s*["'`]?thinking["'`]?(?:\s*(?:请求)?参数)?\s*(?:替换为|改为|换成|切换为|替代为)\s*["'`]?reasoning[_\.]effort["'`]?(?![a-z0-9_])/,
+      /reasoning[_\.]effort\b[^.;，。；！？]{0,80}(?:必须|必需|应当|应该|推荐|受支持|可用)/,
     ].some((pattern) => pattern.test(clause));
   });
 }

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.